@appzgatenz/label-print-topbridge-js

Headless browser SDK for TopBridge label printing. WebSocket API V2 client, health check, login status, benefits, printers, template schema, and print execution — zero dependencies.

Install

npm install @appzgatenz/label-print-topbridge-js

Quick Start

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

const client = new TopBridgeClient({ debug: true })

// 1. Preflight
const { printers } = await client.preflight.run()

// 2. Print
const result = await client.print.execute({
  template: 'PRICE_LABEL',
  printer: printers.data.defaultPrinter,
  products: [
    { name: 'Apple', examplePrice: { value: 3.99, currency: '$', unit: '/kg' }, copies: 2 },
  ],
})

console.log(`Printed ${result.data.printedCopies} copies`)

Documentation

• API Reference
• Developer Guide
• WebSocket API V2

Architecture

TopBridgeClient
├── health        Health check
├── whoami        Login status
├── benefits      Print quota verification
├── printers      Printer list
├── templates     Template list + schema
├── print         Print execution with data transformation
├── preflight     Orchestrated health → benefits → printers
├── launch        Tray App launch + retry orchestration
├── printerSetup  Printer config + BPAC setup
└── events        Push events + connection lifecycle

Features

• Zero dependencies — pure TypeScript, browser-native APIs only
• ~8.6 KB gzipped — minimal bundle size
• TypeScript strict mode — full type safety with exported types
• Headless — no UI framework dependency, works with React/Vue/Svelte/vanilla
• Layered error model — instanceof type narrowing for all error scenarios
• ESM + CJS — compatible with Vite, Next.js, webpack
• WebSocket API V2 — unified /v2 endpoint with action-based requests
• Realtime events — persistent connection with printer/template/user push events + connection lifecycle

Security

• Fixed SDK endpoints (ws://localhost:8765 by default, optional wss://topbridge.topsale.co.nz:8764 via wssEnabled: true) — no arbitrary URL configuration
• SDK caller source whitelist (Core-SDK / React-SDK / Nextjs-SDK; Excel / Odoo are Tray App integration sources outside this core package)
• Production build minification
• URL safety validation
• Input sanitization (formula injection prevention)

License

MIT