@thermal-label/contracts

Shared types and interfaces for the thermal-label printer driver ecosystem. Pure TypeScript — zero runtime dependencies beyond a type re-export from @mbtech-nl/bitmap. Safe to import from Node, the browser, or any bundler.

Install

pnpm add @thermal-label/contracts

What's in the box

This package is types and interfaces only. For transport implementations (USB, TCP, WebUSB, Web Bluetooth), see @thermal-label/transport.

Interfaces

Export	Purpose
Transport	Bidirectional byte channel to a printer. Implemented per transport type.
PrinterAdapter	High-level printer interface. print(), createPreview(), getStatus(), close().
PrinterDiscovery	Enumerate and open printers for a driver family.
DeviceDescriptor	Static description of a supported printer model (VID/PID, transports, BLE config).
MediaDescriptor	Base media shape (width, height, type, colorCapable). Drivers extend it.
PrinterStatus	Runtime status including detectedMedia and structured PrinterError[].
PrintOptions	Per-call print options (copies, density).
PreviewOptions	Media override for createPreview().
PreviewResult	Preview with separated colour planes and an assumed flag.
PreviewPlane	One colour plane — bitmap + display colour.
DiscoveredPrinter	One entry returned by PrinterDiscovery.listPrinters().
OpenOptions	Filter for PrinterDiscovery.openPrinter().
BluetoothConfig	GATT UUIDs and MTU for a BLE-capable device.
TransportType	'usb' | 'tcp' | 'webusb' | 'web-bluetooth'.

Errors

Export	Thrown when
TransportError	Base class for all transport-layer failures.
TransportTimeoutError	A read timed out waiting for bytes.
TransportClosedError	The transport was closed mid-operation.
DeviceNotFoundError	No device matches the requested VID/PID filter.
UnsupportedOperationError	Operation not supported by this driver/printer/media.
MediaNotSpecifiedError	print() / createPreview() called without a known media.

Bitmap re-exports

LabelBitmap and RawImageData are re-exported from @mbtech-nl/bitmap so drivers and consumers need only one import for everything they pass through PrinterAdapter.

Example: implementing PrinterAdapter

A sketch — see each driver's *-core / *-node / *-web packages for real implementations.

import type {
  DeviceDescriptor,
  MediaDescriptor,
  PreviewOptions,
  PreviewResult,
  PrinterAdapter,
  PrinterStatus,
  PrintOptions,
  RawImageData,
} from '@thermal-label/contracts';
import { MediaNotSpecifiedError } from '@thermal-label/contracts';

export class MyPrinter implements PrinterAdapter {
  readonly family = 'my-driver';
  readonly model: string;
  readonly device: DeviceDescriptor;

  private lastStatus?: PrinterStatus;

  constructor(device: DeviceDescriptor) {
    this.device = device;
    this.model = device.name;
  }

  get connected(): boolean {
    /* ... */
    return true;
  }

  async print(
    image: RawImageData,
    media?: MediaDescriptor,
    options?: PrintOptions,
  ): Promise<void> {
    const m = media ?? this.lastStatus?.detectedMedia;
    if (!m) throw new MediaNotSpecifiedError();
    // render RGBA → native format, stream to the printer...
  }

  async createPreview(
    image: RawImageData,
    options?: PreviewOptions,
  ): Promise<PreviewResult> {
    // return { planes: [...], media, assumed: ... }
  }

  async getStatus(): Promise<PrinterStatus> {
    // query the printer, cache `lastStatus`, return it
  }

  async close(): Promise<void> {
    /* ... */
  }
}

Example: rendering PreviewResult in a UI

import type { PreviewResult } from '@thermal-label/contracts';

function renderPreview(canvas: HTMLCanvasElement, preview: PreviewResult): void {
  const ctx = canvas.getContext('2d');
  if (!ctx) return;

  if (preview.assumed) {
    showWarning(
      'Preview may differ from print — select media or connect printer for an accurate result.',
    );
  }

  // Each plane renders in its own colour; composite them on the canvas.
  for (const plane of preview.planes) {
    drawBitmap(ctx, plane.bitmap, plane.displayColor);
  }
}

Drivers that implement these contracts

Family	Package	Status
Brother QL	@thermal-label/brother-ql-*	Retrofitting
LabelWriter	@thermal-label/labelwriter-*	Retrofitting
LabelManager	@thermal-label/labelmanager-*	Retrofitting

Applying these contracts to existing drivers is covered in separate driver retrofit amendments. This package defines the interface; each driver implements it in its own repository.

A contributor guide for writing new drivers will live in the @thermal-label/transport package once it ships.

Key design decisions

• MediaDescriptor.heightMm is optional — undefined = continuous media, a number = fixed length. No magic zero.
• PrinterStatus has only detectedMedia? — no redundant scalar mediaWidthMm / mediaType. One source of truth.
• PrinterStatus.errors is PrinterError[] with { code, message } — programmatic branching, not string matching.
• PrintOptions.density is string — drivers validate internally. 'normal' is universally supported; drivers throw UnsupportedOperationError for values they don't recognise.
• DeviceDescriptor.vid / pid are optional — required only when transports includes USB or WebUSB. Network-only printers omit them.
• Two-colour splitting is driver knowledge — the contract says colorCapable: boolean. What "red" means is up to the driver.
• print() is one label per call — batch = loop. Drivers manage job framing internally.

Attribution

Not affiliated with Dymo, Brother, Seiko Epson, or any other printer manufacturer. Trademarks belong to their respective owners.

Funding

If you rely on this package commercially, please consider sponsoring:

• GitHub Sponsors
• Ko-fi

License

MIT © Mannes Brak