@zpl-toolchain/print 0.1.2

package/dist/browser.d.ts

@@ -0,0 +1,66 @@
+import type { PrinterDevice, PrinterStatus } from "./types.js";
+export type { PrinterDevice, PrinterStatus } from "./types.js";
+/** Options for configuring the Zebra Browser Print client. */
+export interface ZebraBrowserPrintOptions {
+    /**
+     * Base URL of the Zebra Browser Print agent.
+     * Defaults to `http://127.0.0.1:9100` when served over HTTP, or
+     * `https://localhost:9101` when served over HTTPS.
+     */
+    agentUrl?: string;
+    /** Request timeout in milliseconds (default: 5000). */
+    timeout?: number;
+}
+/**
+ * Wrapper around the Zebra Browser Print local agent.
+ *
+ * Uses only `fetch()` — no external dependencies.
+ *
+ * @example
+ * ```ts
+ * import { ZebraBrowserPrint } from "@zpl-toolchain/print/browser";
+ *
+ * const zbp = new ZebraBrowserPrint();
+ *
+ * if (await zbp.isAvailable()) {
+ *   const devices = await zbp.discover();
+ *   if (devices.length > 0) {
+ *     await zbp.print(devices[0], "^XA^FDHello^FS^XZ");
+ *   }
+ * }
+ * ```
+ */
+export declare class ZebraBrowserPrint {
+    private readonly agentUrl;
+    private readonly timeout;
+    constructor(options?: ZebraBrowserPrintOptions);
+    /**
+     * Check whether the Zebra Browser Print agent is running and reachable.
+     *
+     * @returns `true` if the agent responds, `false` otherwise.
+     */
+    isAvailable(): Promise<boolean>;
+    /**
+     * Discover Zebra printers available through the local agent.
+     *
+     * @returns An array of {@link PrinterDevice} objects.
+     */
+    discover(): Promise<PrinterDevice[]>;
+    /**
+     * Send ZPL to a specific printer through the agent.
+     *
+     * @param device - The target printer device (from {@link discover}).
+     * @param zpl    - The ZPL II command string to send.
+     */
+    print(device: PrinterDevice, zpl: string): Promise<void>;
+    /**
+     * Query the host status of a printer through the agent.
+     *
+     * Sends `~HS` to the device and parses the response into a
+     * {@link PrinterStatus} object.
+     *
+     * @param device - The target printer device.
+     */
+    getStatus(device: PrinterDevice): Promise<PrinterStatus>;
+}
+//# sourceMappingURL=browser.d.ts.map

package/dist/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAG/D,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAkB/D,8DAA8D;AAC9D,MAAM,WAAW,wBAAwB;IACvC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAoBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,OAAO,CAAC,EAAE,wBAAwB;IAO9C;;;;OAIG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAcrC;;;;OAIG;IACG,QAAQ,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;IAqC1C;;;;;OAKG;IACG,KAAK,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkB9D;;;;;;;OAOG;IACG,SAAS,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;CAqC/D"}

package/dist/browser.js

@@ -0,0 +1,194 @@
+import { parseHostStatus } from "./status.js";
+// ─── Zebra Browser Print Agent ───────────────────────────────────────────────
+//
+// The Zebra Browser Print SDK provides a localhost HTTP agent that bridges
+// the browser to USB / network-attached Zebra printers. By default it listens
+// on http://127.0.0.1:9100 (for HTTP) and https://localhost:9101 (for HTTPS).
+//
+// This module wraps that agent using plain `fetch()` — zero dependencies.
+// It is designed to run *only* in browser environments.
+// ─────────────────────────────────────────────────────────────────────────────
+/** Default HTTP endpoint for the Zebra Browser Print agent. */
+const DEFAULT_AGENT_HTTP = "http://127.0.0.1:9100";
+/** Default HTTPS endpoint for the Zebra Browser Print agent. */
+const DEFAULT_AGENT_HTTPS = "https://localhost:9101";
+function resolveAgentUrl(options) {
+    if (options?.agentUrl)
+        return options.agentUrl;
+    // Auto-detect protocol if running in a browser context.
+    if (typeof globalThis.location !== "undefined") {
+        return globalThis.location.protocol === "https:"
+            ? DEFAULT_AGENT_HTTPS
+            : DEFAULT_AGENT_HTTP;
+    }
+    return DEFAULT_AGENT_HTTP;
+}
+function buildAbortSignal(timeout) {
+    return AbortSignal.timeout(timeout);
+}
+// ─── ZebraBrowserPrint API ───────────────────────────────────────────────────
+/**
+ * Wrapper around the Zebra Browser Print local agent.
+ *
+ * Uses only `fetch()` — no external dependencies.
+ *
+ * @example
+ * ```ts
+ * import { ZebraBrowserPrint } from "@zpl-toolchain/print/browser";
+ *
+ * const zbp = new ZebraBrowserPrint();
+ *
+ * if (await zbp.isAvailable()) {
+ *   const devices = await zbp.discover();
+ *   if (devices.length > 0) {
+ *     await zbp.print(devices[0], "^XA^FDHello^FS^XZ");
+ *   }
+ * }
+ * ```
+ */
+export class ZebraBrowserPrint {
+    agentUrl;
+    timeout;
+    constructor(options) {
+        this.agentUrl = resolveAgentUrl(options);
+        this.timeout = options?.timeout ?? 5_000;
+    }
+    // ── Availability ─────────────────────────────────────────────────────
+    /**
+     * Check whether the Zebra Browser Print agent is running and reachable.
+     *
+     * @returns `true` if the agent responds, `false` otherwise.
+     */
+    async isAvailable() {
+        try {
+            const res = await fetch(`${this.agentUrl}/available`, {
+                method: "GET",
+                signal: buildAbortSignal(this.timeout),
+            });
+            return res.ok;
+        }
+        catch {
+            return false;
+        }
+    }
+    // ── Discovery ────────────────────────────────────────────────────────
+    /**
+     * Discover Zebra printers available through the local agent.
+     *
+     * @returns An array of {@link PrinterDevice} objects.
+     */
+    async discover() {
+        const res = await fetch(`${this.agentUrl}/available`, {
+            method: "GET",
+            signal: buildAbortSignal(this.timeout),
+        });
+        if (!res.ok) {
+            throw new Error(`Zebra Browser Print agent returned ${res.status}: ${res.statusText}`);
+        }
+        const text = await res.text();
+        // The agent returns a newline-separated list of device records.
+        // Each record is a set of key/value pairs separated by \t within the line.
+        // Different firmware versions may return JSON or the legacy format.
+        try {
+            // Try parsing as JSON first (newer agent versions).
+            const json = JSON.parse(text);
+            if (Array.isArray(json)) {
+                return json.map(mapDevice);
+            }
+            // Single device object.
+            if (json && typeof json === "object") {
+                return [mapDevice(json)];
+            }
+        }
+        catch {
+            // Fall through to legacy parsing.
+        }
+        // Legacy tab-separated format.
+        return parseLegacyDeviceList(text);
+    }
+    // ── Printing ─────────────────────────────────────────────────────────
+    /**
+     * Send ZPL to a specific printer through the agent.
+     *
+     * @param device - The target printer device (from {@link discover}).
+     * @param zpl    - The ZPL II command string to send.
+     */
+    async print(device, zpl) {
+        const res = await fetch(`${this.agentUrl}/write`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ device: device.uid, data: zpl }),
+            signal: buildAbortSignal(this.timeout),
+        });
+        if (!res.ok) {
+            const body = await res.text().catch(() => "");
+            throw new Error(`Print failed (${res.status}): ${body || res.statusText}`);
+        }
+    }
+    // ── Status ───────────────────────────────────────────────────────────
+    /**
+     * Query the host status of a printer through the agent.
+     *
+     * Sends `~HS` to the device and parses the response into a
+     * {@link PrinterStatus} object.
+     *
+     * @param device - The target printer device.
+     */
+    async getStatus(device) {
+        // Send the ~HS command through the agent's read-after-write flow.
+        const writeRes = await fetch(`${this.agentUrl}/write`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ device: device.uid, data: "~HS" }),
+            signal: buildAbortSignal(this.timeout),
+        });
+        if (!writeRes.ok) {
+            const body = await writeRes.text().catch(() => "");
+            throw new Error(`Status query write failed (${writeRes.status}): ${body || writeRes.statusText}`);
+        }
+        // Allow the printer time to prepare its response before reading.
+        await new Promise((r) => setTimeout(r, 200));
+        // Read the response back from the printer.
+        const readRes = await fetch(`${this.agentUrl}/read`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ device: device.uid }),
+            signal: buildAbortSignal(this.timeout),
+        });
+        if (!readRes.ok) {
+            const body = await readRes.text().catch(() => "");
+            throw new Error(`Status query read failed (${readRes.status}): ${body || readRes.statusText}`);
+        }
+        const raw = await readRes.text();
+        return parseHostStatus(raw);
+    }
+}
+// ─── Device mapping helpers ──────────────────────────────────────────────────
+function mapDevice(obj) {
+    return {
+        name: String(obj.name ?? obj.Name ?? "Unknown"),
+        uid: String(obj.uid ?? obj.UID ?? obj.uniqueId ?? ""),
+        connection: String(obj.connection ?? obj.Connection ?? "unknown"),
+        deviceType: String(obj.deviceType ?? obj.DeviceType ?? "unknown"),
+        provider: String(obj.provider ?? obj.Provider ?? "unknown"),
+        manufacturer: String(obj.manufacturer ?? obj.Manufacturer ?? "unknown"),
+    };
+}
+function parseLegacyDeviceList(text) {
+    const lines = text
+        .split("\n")
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0);
+    return lines.map((line) => {
+        const fields = line.split("\t");
+        return {
+            name: fields[0] ?? "Unknown",
+            uid: fields[1] ?? "",
+            connection: fields[2] ?? "unknown",
+            deviceType: fields[3] ?? "unknown",
+            provider: fields[4] ?? "unknown",
+            manufacturer: fields[5] ?? "unknown",
+        };
+    });
+}
+//# sourceMappingURL=browser.js.map

package/dist/browser.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,189 @@
+import type { PrinterConfig, PrintResult, PrinterStatus, ValidateOptions, BatchOptions, BatchProgress, BatchResult } from "./types.js";
+export { parseHostStatus } from "./status.js";
+export { PrintError, type PrinterConfig, type PrintResult, type PrinterStatus, type PrintErrorCode, type ValidateOptions, type BatchOptions, type BatchProgress, type BatchResult, } from "./types.js";
+/**
+ * Open a TCP socket, write `command`, read the response until the socket is
+ * idle for a short period, then close and return the response.
+ *
+ * Exported so that `proxy.ts` can re-use it instead of duplicating the logic.
+ */
+export declare function tcpQuery(host: string, port: number, command: string, timeout: number): Promise<string>;
+/**
+ * Send ZPL to a printer and return the result.
+ *
+ * Automatically retries on transient network errors with exponential backoff.
+ *
+ * @example
+ * ```ts
+ * import { print } from "@zpl-toolchain/print";
+ *
+ * const result = await print("^XA^FO50,50^A0N,50,50^FDHello^FS^XZ", {
+ *   host: "192.168.1.100",
+ * });
+ * console.log(result); // { success: true, bytesWritten: 44, duration: 12 }
+ * ```
+ */
+export declare function print(zpl: string, config: PrinterConfig): Promise<PrintResult>;
+/**
+ * A persistent TCP connection to a ZPL printer.
+ *
+ * @example
+ * ```ts
+ * import { createPrinter } from "@zpl-toolchain/print";
+ *
+ * const printer = createPrinter({ host: "192.168.1.100" });
+ * await printer.print("^XA^FO50,50^A0N,50,50^FDHello^FS^XZ");
+ * const status = await printer.getStatus();
+ * console.log(status.ready);
+ * await printer.close();
+ * ```
+ */
+export declare class TcpPrinter {
+    private readonly config;
+    private socket;
+    private connecting;
+    private closed;
+    private writeQueue;
+    constructor(config: PrinterConfig);
+    /** Ensure a live connection exists, creating one if needed. */
+    private ensureConnected;
+    /**
+     * Send ZPL to the printer over the persistent connection.
+     *
+     * Falls back to a fresh connection if the existing one is broken.
+     */
+    print(zpl: string): Promise<PrintResult>;
+    /**
+     * Query the printer's host status (~HS).
+     *
+     * Sends the `~HS` command and parses the response into a
+     * {@link PrinterStatus} object.
+     *
+     * **Note:** This opens a separate short-lived TCP connection for the query
+     * rather than using the persistent connection, because the ~HS response
+     * needs an idle-timeout-based read strategy that would interfere with the
+     * persistent socket's event handlers.
+     */
+    getStatus(): Promise<PrinterStatus>;
+    /**
+     * Send an arbitrary command and return the raw response string.
+     *
+     * Useful for querying ~HI (Host Identification), ~HM (Host Memory), etc.
+     *
+     * **Note:** This opens a separate short-lived TCP connection for each query
+     * rather than using the persistent connection, because reading a response
+     * requires an idle-timeout strategy that would interfere with the
+     * persistent socket's event handlers.
+     */
+    query(command: string): Promise<string>;
+    /**
+     * Check whether the printer is reachable by attempting a TCP connection.
+     * Returns `true` if the connection succeeds, `false` otherwise.
+     */
+    isReachable(): Promise<boolean>;
+    /**
+     * Send multiple labels sequentially over the persistent connection.
+     *
+     * @param labels - Array of ZPL strings, one per label.
+     * @param opts - Optional batch options (e.g., status polling interval).
+     * @param onProgress - Optional callback after each label.
+     *   Return `false` (strictly) to abort the batch early.
+     *   Any other return value (including `undefined`/`true`) continues normally.
+     * @returns The number of labels sent and the total.
+     *
+     * @example
+     * ```ts
+     * // Simple batch
+     * await printer.printBatch(labels);
+     *
+     * // With progress tracking
+     * await printer.printBatch(labels, {}, (p) => {
+     *   console.log(`${p.sent}/${p.total}`);
+     * });
+     *
+     * // With status polling every 5 labels
+     * await printer.printBatch(labels, { statusInterval: 5 }, (p) => {
+     *   if (p.status) console.log(`Labels remaining: ${p.status.labelsRemaining}`);
+     * });
+     * ```
+     */
+    printBatch(labels: string[], opts?: BatchOptions, onProgress?: (progress: BatchProgress) => boolean | void): Promise<BatchResult>;
+    /**
+     * Poll the printer until all queued labels have been printed.
+     *
+     * Queries `~HS` at the specified interval and resolves when
+     * `formatsInBuffer === 0` and `labelsRemaining === 0`.
+     *
+     * @param pollInterval - Milliseconds between status polls (default: 500).
+     * @param timeout - Maximum wait time in milliseconds (default: 30000).
+     * @throws {PrintError} with code `TIMEOUT` if the timeout is exceeded.
+     */
+    waitForCompletion(pollInterval?: number, timeout?: number): Promise<void>;
+    /** Close the persistent connection. Safe to call multiple times. */
+    close(): Promise<void>;
+}
+/**
+ * Create a {@link TcpPrinter} with a persistent TCP connection.
+ *
+ * @see {@link TcpPrinter}
+ */
+export declare function createPrinter(config: PrinterConfig): TcpPrinter;
+/**
+ * Print ZPL after first validating it with `@zpl-toolchain/core` (if
+ * installed). Falls back to a plain print if the core package is not
+ * available.
+ *
+ * Supports optional printer-profile-aware validation and strict mode
+ * (treat warnings as errors).
+ *
+ * @param zpl - The ZPL source string to validate and send.
+ * @param config - Printer connection configuration.
+ * @param validateOpts - Optional validation settings (profile, strict mode).
+ *
+ * @throws {PrintError} with code `VALIDATION_FAILED` if validation finds errors
+ *   (or warnings in strict mode).
+ * @throws {PrintError} with a network-related code if the print operation fails.
+ *
+ * @example
+ * ```ts
+ * import { printValidated } from "@zpl-toolchain/print";
+ * import { readFileSync } from "node:fs";
+ *
+ * // Basic: validate then print
+ * await printValidated("^XA^FDHello^FS^XZ", { host: "192.168.1.100" });
+ *
+ * // With printer profile for hardware-aware validation
+ * const profile = readFileSync("profiles/ZD421.json", "utf-8");
+ * await printValidated("^XA^FDHello^FS^XZ", { host: "192.168.1.100" }, {
+ *   profileJson: profile,
+ *   strict: true,  // treat warnings as errors
+ * });
+ * ```
+ */
+export declare function printValidated(zpl: string, config: PrinterConfig, validateOpts?: ValidateOptions): Promise<PrintResult>;
+/**
+ * Send multiple ZPL labels to a printer in a single session.
+ *
+ * Opens a persistent connection, sends all labels sequentially, and closes.
+ *
+ * @param labels - Array of ZPL strings, one per label.
+ * @param config - Printer connection configuration.
+ * @param opts - Optional batch options (e.g., status polling interval).
+ * @param onProgress - Optional callback after each label.
+ *   Return `false` (strictly) to abort the batch early.
+ * @returns The number of labels sent and the total.
+ *
+ * @example
+ * ```ts
+ * import { printBatch } from "@zpl-toolchain/print";
+ *
+ * const labels = [
+ *   "^XA^FO50,50^A0N,50,50^FDLabel 1^FS^XZ",
+ *   "^XA^FO50,50^A0N,50,50^FDLabel 2^FS^XZ",
+ * ];
+ * const result = await printBatch(labels, { host: "192.168.1.100" });
+ * console.log(`Sent ${result.sent}/${result.total} labels`);
+ * ```
+ */
+export declare function printBatch(labels: string[], config: PrinterConfig, opts?: BatchOptions, onProgress?: (progress: BatchProgress) => boolean | void): Promise<BatchResult>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,aAAa,EACb,WAAW,EACX,aAAa,EAEb,eAAe,EACf,YAAY,EACZ,aAAa,EACb,WAAW,EACZ,MAAM,YAAY,CAAC;AAIpB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EACL,UAAU,EACV,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,WAAW,GACjB,MAAM,YAAY,CAAC;AAgIpB;;;;;GAKG;AACH,wBAAgB,QAAQ,CACtB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,CAAC,CAyDjB;AAID;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,KAAK,CACzB,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,WAAW,CAAC,CAyBtB;AAID;;;;;;;;;;;;;GAaG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmC;IAC1D,OAAO,CAAC,MAAM,CAA2B;IACzC,OAAO,CAAC,UAAU,CAA8B;IAChD,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,UAAU,CAAoC;gBAE1C,MAAM,EAAE,aAAa;IAMjC,+DAA+D;YACjD,eAAe;IAwD7B;;;;OAIG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IA8BxC;;;;;;;;;;OAUG;IACG,SAAS,IAAI,OAAO,CAAC,aAAa,CAAC;IAUzC;;;;;;;;;OASG;IACG,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAS7C;;;OAGG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IA6BrC;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACG,UAAU,CACd,MAAM,EAAE,MAAM,EAAE,EAChB,IAAI,CAAC,EAAE,YAAY,EACnB,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,aAAa,KAAK,OAAO,GAAG,IAAI,GACvD,OAAO,CAAC,WAAW,CAAC;IA2BvB;;;;;;;;;OASG;IACG,iBAAiB,CACrB,YAAY,SAAM,EAClB,OAAO,SAAS,GACf,OAAO,CAAC,IAAI,CAAC;IAkChB,oEAAoE;IAC9D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAkC7B;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,UAAU,CAE/D;AAiFD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,aAAa,EACrB,YAAY,CAAC,EAAE,eAAe,GAC7B,OAAO,CAAC,WAAW,CAAC,CAsBtB;AAID;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,UAAU,CAC9B,MAAM,EAAE,MAAM,EAAE,EAChB,MAAM,EAAE,aAAa,EACrB,IAAI,CAAC,EAAE,YAAY,EACnB,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,aAAa,KAAK,OAAO,GAAG,IAAI,GACvD,OAAO,CAAC,WAAW,CAAC,CAOtB"}