@gohcltech/edge-print-client 0.2.0-dev.6

package/dist/edge-print.js

@@ -0,0 +1,259 @@
+/**
+ * @module edge-print
+ *
+ * Browser-side WebSocket client for the Edge Printing agent.
+ * Drop-in replacement for qz-tray.js with a simpler token-based auth model.
+ *
+ * @example
+ * ```ts
+ * import ep from '@gohcltech/edge-print-client'
+ *
+ * await ep.connect({ token: 'your-api-token' })
+ * const printers = await ep.printers()
+ * const jobId = await ep.print(
+ *   { printer: 'Office Laser' },
+ *   [{ type: 'pixel', format: 'pdf', flavor: 'base64', data: pdfBase64 }],
+ * )
+ * ```
+ */
+/**
+ * WebSocket client for the Edge Printing agent.
+ *
+ * Each instance manages a single persistent connection. For most applications
+ * the exported {@link ep} singleton is sufficient; create additional instances
+ * only when you need concurrent connections to different agents.
+ *
+ * ### Lifecycle
+ * ```
+ * connect() → printers() / print() / … → disconnect()
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { EdgePrintClient } from '@gohcltech/edge-print-client'
+ *
+ * const client = new EdgePrintClient()
+ * await client.connect({ token: 'abc123' })
+ * ```
+ */
+export class EdgePrintClient {
+    constructor() {
+        this.ws = null;
+        this.pending = new Map();
+        this.authenticated = false;
+        this.closeListeners = [];
+    }
+    /**
+     * Open a WebSocket connection to the Edge Printing agent and authenticate.
+     *
+     * On failure the client retries up to `options.retries` times (default 3),
+     * waiting `options.retryDelay` ms (default 1 000) between attempts. If all
+     * attempts fail the last error is re-thrown.
+     *
+     * @throws {Error} If the agent is unreachable or the token is rejected after
+     *   all retries are exhausted.
+     *
+     * @example
+     * ```ts
+     * await ep.connect({
+     *   host: '127.0.0.1',
+     *   port: 8181,
+     *   token: 'abc123',
+     *   retries: 5,
+     *   retryDelay: 2000,
+     * })
+     * ```
+     */
+    async connect(options) {
+        const { host = '127.0.0.1', port = 8181, token, retries = 3, retryDelay = 1000, } = options;
+        for (let attempt = 0; attempt <= retries; attempt++) {
+            try {
+                await this.openSocket(`wss://${host}:${port}`);
+                await this.request('auth', { token });
+                this.authenticated = true;
+                return;
+            }
+            catch (err) {
+                if (attempt === retries)
+                    throw err;
+                await sleep(retryDelay);
+            }
+        }
+    }
+    /**
+     * Return all printers available on the agent machine.
+     *
+     * @throws {Error} If not connected.
+     *
+     * @example
+     * ```ts
+     * const printers = await ep.printers()
+     * const colorPrinters = printers.filter(p => p.color)
+     * ```
+     */
+    async printers() {
+        const resp = await this.request('get_printers', {});
+        return resp.printers;
+    }
+    /**
+     * Return the name of the OS default printer.
+     *
+     * Cheaper than calling {@link printers} when you only need the default name
+     * and no other printer metadata.
+     *
+     * @throws {Error} If not connected.
+     */
+    async defaultPrinter() {
+        const resp = await this.request('get_default_printer', {});
+        return resp.name;
+    }
+    /**
+     * Submit a print job to the agent.
+     *
+     * @param config - Printer selection and job settings.
+     * @param data - One or more content items to print (pages, labels, …).
+     * @returns The job ID assigned by the agent.
+     *
+     * @throws {Error} If not connected, or if the agent rejects the job.
+     *
+     * @example Print a PDF
+     * ```ts
+     * const jobId = await ep.print(
+     *   { printer: 'Office Laser', copies: 2, duplex: 'long-edge' },
+     *   [{ type: 'pixel', format: 'pdf', flavor: 'base64', data: pdfBase64 }],
+     * )
+     * ```
+     *
+     * @example Print a ZPL label
+     * ```ts
+     * await ep.print(
+     *   { printer: 'Zebra ZT410' },
+     *   [{ type: 'raw', format: 'command', flavor: 'plain', data: zplString }],
+     * )
+     * ```
+     */
+    async print(config, data) {
+        const resp = await this.request('print', { config, data });
+        return resp.job_id;
+    }
+    /**
+     * Close the WebSocket connection and reset client state.
+     *
+     * Any in-flight requests are rejected. Safe to call when already
+     * disconnected.
+     */
+    disconnect() {
+        this.ws?.close();
+        this.ws = null;
+        this.authenticated = false;
+    }
+    /**
+     * `true` when the WebSocket is open and the session is authenticated.
+     *
+     * Use this to guard print calls in components that may render before the
+     * connection is established.
+     */
+    isConnected() {
+        return this.ws?.readyState === WebSocket.OPEN && this.authenticated;
+    }
+    /**
+     * Register a callback invoked whenever the connection closes — whether from
+     * a network drop, an agent restart, or an explicit {@link disconnect} call.
+     *
+     * Multiple listeners can be registered; all are called in registration order.
+     *
+     * @example
+     * ```ts
+     * ep.onClose(() => {
+     *   console.warn('Lost connection to Edge Printing agent — reconnecting…')
+     *   reconnect()
+     * })
+     * ```
+     */
+    onClose(fn) {
+        this.closeListeners.push(fn);
+    }
+    // ── internals ────────────────────────────────────────────────────────────
+    openSocket(url) {
+        return new Promise((resolve, reject) => {
+            const ws = new WebSocket(url);
+            ws.onopen = () => { this.ws = ws; resolve(); };
+            ws.onerror = () => reject(new Error(`Cannot reach Edge Printing agent at ${url}`));
+            ws.onmessage = (ev) => this.handleMessage(String(ev.data));
+            ws.onclose = () => {
+                this.ws = null;
+                this.authenticated = false;
+                this.rejectPending(new Error('Connection closed'));
+                this.closeListeners.forEach(fn => fn());
+            };
+        });
+    }
+    handleMessage(raw) {
+        let msg;
+        try {
+            msg = JSON.parse(raw);
+        }
+        catch {
+            return;
+        }
+        const id = msg['id'];
+        if (!id || !this.pending.has(id))
+            return;
+        const { resolve, reject } = this.pending.get(id);
+        this.pending.delete(id);
+        if (msg['type'] === 'error') {
+            reject(new Error(msg['message'] ?? 'Unknown error'));
+        }
+        else {
+            resolve(msg);
+        }
+    }
+    request(type, payload) {
+        return new Promise((resolve, reject) => {
+            if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+                reject(new Error('Not connected to Edge Printing agent'));
+                return;
+            }
+            const id = crypto.randomUUID();
+            this.pending.set(id, { resolve, reject });
+            const timeout = setTimeout(() => {
+                if (this.pending.has(id)) {
+                    this.pending.delete(id);
+                    reject(new Error(`Request "${type}" timed out`));
+                }
+            }, 30000);
+            this.ws.send(JSON.stringify({ type, id, ...payload }));
+            // Wrap resolve/reject to also clear the timeout.
+            const original = this.pending.get(id);
+            this.pending.set(id, {
+                resolve: (v) => { clearTimeout(timeout); original.resolve(v); },
+                reject: (e) => { clearTimeout(timeout); original.reject(e); },
+            });
+        });
+    }
+    rejectPending(err) {
+        for (const { reject } of this.pending.values())
+            reject(err);
+        this.pending.clear();
+    }
+}
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+/**
+ * Shared singleton `EdgePrintClient` instance.
+ *
+ * Suitable for most single-page applications. Call {@link EdgePrintClient.connect}
+ * once at app startup, then use `ep` from any module without passing the
+ * client around.
+ *
+ * @example
+ * ```ts
+ * import ep from '@gohcltech/edge-print-client'
+ *
+ * await ep.connect({ token: 'abc123' })
+ * await ep.print({ printer: 'Office Laser' }, [pdfData])
+ * ```
+ */
+export const ep = new EdgePrintClient();
+export default ep;

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@gohcltech/edge-print-client",
+  "version": "0.2.0-dev.6",
+  "description": "Browser client for the Edge Printing WebSocket agent",
+  "type": "module",
+  "main": "./dist/edge-print.cjs",
+  "module": "./dist/edge-print.js",
+  "types": "./dist/edge-print.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/edge-print.js",
+      "require": "./dist/edge-print.cjs",
+      "types": "./dist/edge-print.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0"
+  }
+}