API Quick Reference

Module Methods

Module	Method	Return Type	Description
health	check()	Promise<HealthResponse>	Health check
benefits	check()	Promise<BenefitsResponse>	Entitlement validation
printers	list()	Promise<PrintersResponse>	Printer list
templates	list()	Promise<TemplatesListResponse>	Template list
templates	schema(template)	Promise<TemplateSchemaResponse>	Template field definitions
print	execute(request)	Promise<PrintResponse>	Execute print
preflight	run(options?)	Promise<PreflightResult>	Preflight orchestration
launch	trigger()	void	Trigger TopBridge App launch
launch	ensureRunning(fn, options?)	Promise<T>	Launch + retry orchestration

TopBridgeClientConfig

Field	Type	Default	Description
source	string	'(internal)'	SDK source identifier (set internally, do not configure manually)
debug	boolean	false	Enable console logging (prefix: [TopBridge])
logger	Logger	Silent (no-op)	Custom logger implementation
timeouts.health	number (ms)	3000	Health check timeout
timeouts.preflight	number (ms)	10000	Preflight / template query timeout
wssEnabled	boolean	false	Enable WSS secure connection mode
timeouts.print	number (ms)	60000	Print execution timeout

import type { TopBridgeClientConfig } from '@appzgatenz/label-print-topbridge-js'

const client = new TopBridgeClient({
  debug: true,
  timeouts: { health: 5000, print: 120000 },
})

PrintExecuteRequest

interface PrintExecuteRequest {
  template: string             // Template ID or Code
  printer: string              // Printer name
  products: PrintProductInput[] // Product data array
}

PrintProductInput

interface PrintProductInput {
  [key: string]: string | number | Record<string, string | number | undefined> | undefined
  copies?: number  // Print copies, range [1, 9999], default 1
}

SyncedPrinter

interface SyncedPrinter {
  name: string               // Printer name (used as printer parameter)
  isDefault: boolean         // Whether this is the default printer
  protocol?: 'TSPL' | 'ZPL' // Label protocol
}

Response Types

Type	Key Fields
HealthResponse	type: 'pong', isRunning: true, data.isLoggedIn, data.version(optional), data.networkStatus(optional)
BenefitsResponse	data.isValid, data.remainingPrints, data.expiresAt, data.reason, data.hasPrintBenefit, data.hasSessionBenefit
PrintersResponse	data.count, data.defaultPrinter, data.printers[]
TemplatesListResponse	data.count, data.templates[]
TemplateSchemaResponse	data.fields[], data.code, data.name
PrintResponse	message(top-level), data.printedCopies, data.jobId, data.templateName, data.userId(optional), details(optional), warnings(optional)
PreflightResult	health, benefits, printers

SdkResponse<T>

All SDK methods return a unified response envelope:

interface SdkResponse<T> {
  status: 'ok' | 'warning'  // Request result status
  requestId?: string         // Request trace ID
  data: T                    // Business data
  message: string            // Human-readable status description
  details?: unknown          // Extended details (optional)
  warnings?: SdkWarning[]    // Non-fatal format hints (optional)
}

Status	Behavior
'ok'	Request succeeded. Use data directly.
'warning'	Request succeeded with hints. data is usable, check message and warnings for details.
(error)	SDK throws a TopBridgeError subclass. No return value.

Export List

// Classes
import { TopBridgeClient } from '@appzgatenz/label-print-topbridge-js'
import { LaunchModule } from '@appzgatenz/label-print-topbridge-js'

// Error Classes (11 total)
import {
  TopBridgeError,
  TopBridgeConnectionError,
  TopBridgeAuthError,
  TopBridgeVersionError,
  TopBridgeQuotaError,
  TopBridgePrintError,
  TopBridgeConfigError,
  TopBridgeValidationError,
  TopBridgePrinterError,
  TopBridgeTemplateError,
  TopBridgeNetworkError,
  TopBridgeSourceError,
} from '@appzgatenz/label-print-topbridge-js'

// Types (import on demand)
import type {
  TopBridgeClientConfig,
  TopBridgeSource,
  Logger,
  SdkWarning,
  V2WarningCode,
  HealthResponse,
  HealthData,
  BenefitsResponse,
  BenefitsData,
  PrintersResponse,
  PrintersData,
  SyncedPrinter,
  TemplatesListResponse,
  TemplatesListData,
  TemplateItem,
  TemplateSchemaResponse,
  TemplateSchema,
  TemplateFieldSchema,
  PrintResponse,
  PrintData,
  PrintExecuteRequest,
  PrintProductInput,
  PreflightResult,
  PreflightOptions,
  PreflightStep,
  EnsureRunningOptions,
} from '@appzgatenz/label-print-topbridge-js'