@zpl-toolchain/print 0.1.2

package/dist/types.d.ts

@@ -0,0 +1,175 @@
+/** Configuration for connecting to a ZPL printer over TCP/IP. */
+export interface PrinterConfig {
+    /** Printer IP address or hostname. */
+    host: string;
+    /** TCP port (default: 9100 — the standard ZPL raw printing port). */
+    port?: number;
+    /** Connection timeout in milliseconds (default: 5000). */
+    timeout?: number;
+    /** Maximum number of retry attempts on transient errors (default: 2). */
+    maxRetries?: number;
+    /** Base delay between retries in milliseconds; grows with exponential backoff (default: 500). */
+    retryDelay?: number;
+}
+/** Outcome of a print operation. */
+export interface PrintResult {
+    /** Whether the ZPL was successfully sent to the printer. */
+    success: boolean;
+    /** Number of bytes written to the printer socket. */
+    bytesWritten: number;
+    /** Wall-clock duration of the operation in milliseconds. */
+    duration: number;
+}
+/** Parsed representation of the Zebra ~HS (Host Status) response.
+ *
+ * Contains all 24 fields from the three response lines,
+ * matching the Rust `HostStatus` struct for full parity.
+ */
+export interface PrinterStatus {
+    /** Printer is ready to accept data (not paused, head closed, media loaded). */
+    ready: boolean;
+    /** Communication settings (field 0). */
+    communicationFlag: number;
+    /** Media (label stock) is depleted or not detected (field 1). */
+    paperOut: boolean;
+    /** Printer is in a paused state (field 2). */
+    paused: boolean;
+    /** Label length in dots (field 3). */
+    labelLengthDots: number;
+    /** Number of formats waiting in the receive buffer (field 4). */
+    formatsInBuffer: number;
+    /** Receive-buffer full (field 5). */
+    bufferFull: boolean;
+    /** Communications diagnostic mode active (field 6). */
+    commDiagMode: boolean;
+    /** Partial format in progress (field 7). */
+    partialFormat: boolean;
+    /** Reserved/unused field (field 8). */
+    reserved1: number;
+    /** Corrupt RAM detected (field 9). */
+    corruptRam: boolean;
+    /** Under-temperature condition (field 10). */
+    underTemperature: boolean;
+    /** Over-temperature condition (field 11). */
+    overTemperature: boolean;
+    /** Function settings bitmask (field 0). */
+    functionSettings: number;
+    /** Print head is open / not latched (field 1). */
+    headOpen: boolean;
+    /** Ribbon cartridge is depleted or missing (field 2). */
+    ribbonOut: boolean;
+    /** Thermal transfer mode active (field 3). */
+    thermalTransferMode: boolean;
+    /** Print mode code (field 4): 0=tear-off, 1=peel-off, 2=rewind, etc. */
+    printMode: number;
+    /** Print width mode (field 5). */
+    printWidthMode: number;
+    /** Label waiting to be taken (field 6). */
+    labelWaiting: boolean;
+    /** Number of labels remaining in the current batch (field 7). */
+    labelsRemaining: number;
+    /** Format-while-printing flag/mask (field 8). */
+    formatWhilePrinting: number;
+    /** Number of graphics stored in memory (field 9). */
+    graphicsStoredInMemory: number;
+    /** Password value (field 0). */
+    password: number;
+    /** Static RAM installed flag (field 1). */
+    staticRamInstalled: boolean;
+    /** The raw ~HS response string for advanced inspection. */
+    raw: string;
+}
+/** A printer device as reported by the Zebra Browser Print agent. */
+export interface PrinterDevice {
+    /** Human-readable device name (e.g. "ZD421"). */
+    name: string;
+    /** Unique device identifier. */
+    uid: string;
+    /** Connection type reported by the agent (e.g. "network", "usb", "driver"). */
+    connection: string;
+    /** Device type string. */
+    deviceType: string;
+    /** Provider identifier. */
+    provider: string;
+    /** Manufacturer string. */
+    manufacturer: string;
+}
+/** Configuration for the HTTP print proxy server. */
+export interface ProxyConfig {
+    /** Port the proxy listens on (default: 3001). */
+    port?: number;
+    /** Hostname to bind to (default: "127.0.0.1"). */
+    hostname?: string;
+    /**
+     * List of allowed printer IPs / hostnames.
+     * Required — the proxy rejects all requests when this is empty or undefined (SSRF protection).
+     * Supports simple glob patterns with `*` (e.g., `"192.168.1.*"`).
+     */
+    allowedPrinters?: string[];
+    /**
+     * List of allowed destination ports.
+     * Defaults to `[9100]`. Restricts which ports the proxy can connect to,
+     * preventing port-scanning attacks on allowed hosts.
+     */
+    allowedPorts?: number[];
+    /**
+     * Maximum number of concurrent WebSocket connections.
+     * Defaults to 50. New connections are rejected when the limit is reached.
+     */
+    maxConnections?: number;
+    /** Maximum request body size in bytes (default: 1 MiB). */
+    maxPayloadSize?: number;
+    /**
+     * CORS allowed origins.
+     * `"*"` allows any origin; an array restricts to specific origins.
+     * Default: `"*"`.
+     */
+    cors?: string | string[];
+}
+/** Options for pre-print validation via `printValidated()`. */
+export interface ValidateOptions {
+    /**
+     * Printer profile JSON string for profile-aware validation.
+     * Enables DPI-specific, media-specific, and hardware-gated checks.
+     *
+     * Pass the raw JSON string of a printer profile (e.g., `fs.readFileSync("ZD421.json", "utf-8")`).
+     */
+    profileJson?: string;
+    /**
+     * Whether to treat warnings as errors (abort printing if any warnings are found).
+     * Default: `false`.
+     */
+    strict?: boolean;
+}
+/** Options for batch printing with status polling. */
+export interface BatchOptions {
+    /**
+     * Poll printer status (`~HS`) every N labels.
+     * When undefined or 0, no status polling is performed.
+     */
+    statusInterval?: number;
+}
+/** Progress update emitted after each label in a batch. */
+export interface BatchProgress {
+    /** Number of labels sent so far. */
+    sent: number;
+    /** Total number of labels in the batch. */
+    total: number;
+    /** Latest printer status (only present when `statusInterval` is set). */
+    status?: PrinterStatus;
+}
+/** Final result of a batch print operation. */
+export interface BatchResult {
+    /** Number of labels successfully sent. */
+    sent: number;
+    /** Total number of labels in the batch. */
+    total: number;
+}
+/** Well-known error codes surfaced by the print client. */
+export type PrintErrorCode = "CONNECTION_REFUSED" | "TIMEOUT" | "HOST_NOT_FOUND" | "BROKEN_PIPE" | "CONNECTION_RESET" | "VALIDATION_FAILED" | "UNKNOWN";
+/** An error thrown by the print client with a classified code. */
+export declare class PrintError extends Error {
+    readonly code: PrintErrorCode;
+    constructor(message: string, code: PrintErrorCode, cause?: unknown);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,14 @@
+// ─── Printer connection configuration ────────────────────────────────────────
+/** An error thrown by the print client with a classified code. */
+export class PrintError extends Error {
+    code;
+    constructor(message, code, cause) {
+        super(message);
+        this.name = "PrintError";
+        this.code = code;
+        if (cause) {
+            this.cause = cause;
+        }
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAuOhF,kEAAkE;AAClE,MAAM,OAAO,UAAW,SAAQ,KAAK;IACnB,IAAI,CAAiB;IAErC,YAAY,OAAe,EAAE,IAAoB,EAAE,KAAe;QAChE,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;QACzB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,KAAK,EAAE,CAAC;YACV,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACrB,CAAC;IACH,CAAC;CACF"}

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@zpl-toolchain/print",
+  "version": "0.1.2",
+  "description": "Print client for sending ZPL to Zebra and ZPL-compatible printers",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "node": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./proxy": {
+      "types": "./dist/proxy.d.ts",
+      "node": "./dist/proxy.js"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "default": "./dist/browser.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "node --test dist/test/*.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "zpl",
+    "zebra",
+    "label",
+    "printer",
+    "print",
+    "tcp",
+    "raw"
+  ],
+  "license": "MIT OR Apache-2.0",
+  "author": "zpl-toolchain contributors",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/trevordcampbell/zpl-toolchain.git",
+    "directory": "packages/ts/print"
+  },
+  "homepage": "https://github.com/trevordcampbell/zpl-toolchain",
+  "bugs": {
+    "url": "https://github.com/trevordcampbell/zpl-toolchain/issues"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "dist/**/*.d.ts.map",
+    "dist/**/*.js.map",
+    "!dist/test",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.2",
+    "@types/ws": "^8.18.1",
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "@zpl-toolchain/core": ">=0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@zpl-toolchain/core": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "ws": "^8.19.0"
+  }
+}