zykk-print-receipt

Universal JavaScript/TypeScript client library for the BridgeWeb receipt print gateway (BridgeWeb.exe).

Works in any web project regardless of framework — include it via <script> tag or install it as an npm package.

How it works

Your App → ZykkPrintGatewayClient → BridgeWeb.exe (localhost or remote) → Receipt Printer

The library wraps all three gateway API endpoints so you never deal with raw HTTP or gateway-specific response shapes.

Installation

npm / pnpm / yarn

npm install zykk-print-receipt

Browser <script> tag (IIFE)

Download dist/index.global.js from a build and include it directly:

<script src="path/to/zykk-print-receipt.global.js"></script>
<!-- window.PrintReceipt is now available -->

Quick start

ESM / TypeScript

import { ZykkPrintGatewayClient, PrintGatewayError } from 'zykk-print-receipt';
import type { CompanyData } from 'zykk-print-receipt';

const company: CompanyData = {
  companyName: 'Acme Ltd',
  taxNumber: '123456789',
};

const client = new ZykkPrintGatewayClient({
  host: '192.168.1.50', // BridgeWeb gateway host
  companyData: company, // merged into every print receipt
});

// Check gateway readiness
const status = await client.checkPrinters();
if (!status.receiptPrintReady) {
  console.warn('Printer not configured on gateway');
}

// Ping the physical device
await client.testPrinter();

// Print a receipt
try {
  const result = await client.print({
    requestId: 'order-2026-0042', // optional — auto-generated if omitted
    receipt: {
      items: [
        { name: 'Coffee', qty: 2, price: 3.50 },
        { name: 'Cake',   qty: 1, price: 4.00 },
      ],
      total: 11.00,
      paymentMethod: 'card',
    },
  });
  console.log('Printed:', result.ResponseBody);
} catch (err) {
  if (err instanceof PrintGatewayError) {
    console.error(`[${err.code}] ${err.message}`);
  }
}

CommonJS

const { ZykkPrintGatewayClient, PrintGatewayError } = require('zykk-print-receipt');

const client = new ZykkPrintGatewayClient({ host: 'localhost' });
client.setCompanyData({ companyName: 'My Shop', taxNumber: '000' });

Browser <script> tag

<script src="zykk-print-receipt.global.js"></script>
<script>
  const { ZykkPrintGatewayClient, PrintGatewayError } = window.PrintReceipt;

  const client = new ZykkPrintGatewayClient({
    host: '192.168.1.50',
    companyData: { companyName: 'Acme Ltd', taxNumber: '123456' },
  });

  document.getElementById('print-btn').addEventListener('click', async () => {
    try {
      await client.print({
        receipt: { items: [], total: 99.00 },
      });
      alert('Printed!');
    } catch (err) {
      alert(err.message);
    }
  });
</script>

API Reference

new ZykkPrintGatewayClient(options)

| Option | Type | Default | Description | |--------|------|---------|-------------| | host | string | required | IP address or hostname of the BridgeWeb gateway | | port | number | 8090 | Gateway port | | protocol | 'http' \| 'https' | 'http' | Protocol | | timeoutMs | number | 120000 | HTTP timeout in ms (gateway may wait up to 120 s for device) | | companyData | CompanyData | undefined | Company data merged into print payloads |

CompanyData

A named, exported interface — import it independently whenever you need to represent the sender on a receipt:

import type { CompanyData } from 'zykk-print-receipt';

const company: CompanyData = {
  companyName: 'Acme Ltd', // legal name printed on the receipt
  taxNumber: '123456789',  // VAT / NIP / INN / EIN etc.
};

Company data on the client

// Supply at construction time
const client = new ZykkPrintGatewayClient({ host: 'localhost', companyData: company });

// Or set / update at any time before printing
client.setCompanyData({ companyName: 'New Name', taxNumber: '000' });

// Read the current value
const data = client.getCompanyData(); // CompanyData | undefined

companyData is required before calling print(). All other methods work without it.

client.checkPrinters() → Promise<PrintersStatus>

GET /api/printers — checks whether a receipt printer is configured on the gateway.

interface PrintersStatus {
  receiptPrintReady: boolean;
}

Does not require companyData.

client.testPrinter() → Promise<ReceiptPrinterTestResult>

POST /api/test-printer — pings the physical print device.

interface ReceiptPrinterTestResult {
  Success: boolean;
  DeviceReachable: boolean;
  HttpStatus: number;
  ErrorMessage: string | null;
  ResponseBody: string | null;
}

Does not require companyData. Throws PrintGatewayError when Success: false.

client.print(request) → Promise<ReceiptPrintResult>

POST /api/print-receipt — sends a receipt to the printer.

interface PrintRequest<TReceipt> {
  requestId?: string; // auto-generated if omitted
  receipt: TReceipt;
}

interface ReceiptPrintResult {
  Success: boolean;
  HttpStatus: number;
  ErrorMessage: string | null;
  ResponseBody: string | null;
}

Requires companyData — throws PrintGatewayError({ code: 'NO_COMPANY_DATA' }) if not set.

The receipt sent to the gateway is built as:

{ ...companyData, ...request.receipt }

Fields in request.receipt override any matching keys in companyData.

PrintGatewayError

All failures throw a PrintGatewayError extending Error:

| Property | Type | Description | |----------|------|-------------| | code | PrintGatewayErrorCode | Machine-readable category (see below) | | message | string | Human-readable description | | httpStatus | number \| undefined | HTTP status if the request reached the gateway | | response | unknown | Raw parsed gateway response body (if available) |

Error codes

| Code | When | |------|------| | NO_COMPANY_DATA | print() called before setCompanyData() | | NETWORK_ERROR | Fetch failed at network level (timeout, ECONNREFUSED, …) | | HTTP_ERROR | Gateway returned non-2xx status or non-JSON body | | GATEWAY_ERROR | HTTP 200 but Success: false in response body |

TypeScript — typing the receipt payload

CompanyData is a concrete named interface with a fixed shape. The receipt payload passed to print() is still generic — annotate it with your own type so TypeScript validates the receipt structure at the call site:

import { ZykkPrintGatewayClient } from 'zykk-print-receipt';
import type { CompanyData } from 'zykk-print-receipt';

interface MyReceipt {
  items: Array<{ name: string; price: number }>;
  total: number;
  paymentMethod: 'cash' | 'card';
}

const company: CompanyData = {
  companyName: 'Acme Ltd',
  taxNumber: '123456789',
};

const client = new ZykkPrintGatewayClient({ host: 'localhost', companyData: company });

// TReceipt is inferred from the argument — no explicit annotation needed
await client.print<MyReceipt>({
  receipt: { items: [{ name: 'Tea', price: 2.5 }], total: 2.5, paymentMethod: 'card' },
});

Recommended flow

1. new ZykkPrintGatewayClient({ host, companyData })  — app start / login
2. checkPrinters()                                 — shift start or after network event
3. testPrinter()                                   — shift start or after failure
4. print({ receipt })                              — per sale

Development

npm run build      # compile to dist/ (ESM + CJS + IIFE browser bundle)
npm test           # run vitest
npm run test:watch # vitest in watch mode
npm run lint       # eslint src/
npm run typecheck  # tsc --noEmit

Verification against a live gateway

node -e "
const { ZykkPrintGatewayClient } = require('./dist/index.js');
const c = new ZykkPrintGatewayClient({ host: 'localhost' });
c.checkPrinters().then(console.log).catch(console.error);
"

Gateway documentation

See HOST_GUIDE.md for the full BridgeWeb gateway API specification.

License

MIT