@gohcltech/edge-print-client 2.0.31-develop → 2.0.42-develop

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Health Care Logistics, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -56,11 +56,12 @@ Opens a WebSocket connection to the agent and authenticates. Retries automatical
 
 ```ts
 await ep.connect({
-  host: '127.0.0.1', // default
-  port: 8181,        // default
-  token: 'abc123',   // required — from the agent settings window
-  retries: 3,        // default — additional attempts after the first failure
-  retryDelay: 1000,  // default — ms between retries
+  host: '127.0.0.1',        // default
+  port: 8181,               // default
+  token: 'abc123',          // required — from the agent settings window
+  clientName: 'Warehouse',  // recommended — shown in the agent's approval prompt
+  retries: 3,               // default — additional attempts after the first failure
+  retryDelay: 1000,         // default — ms between retries
 })
 ```
 
@@ -69,11 +70,22 @@ await ep.connect({
 | `host` | `string` | `'127.0.0.1'` | Hostname or IP of the agent machine |
 | `port` | `number` | `8181` | Port the agent listens on |
 | `token` | `string` | _(required)_ | API token from the Edge Printing settings window |
+| `clientName` | `string?` | _(none)_ | Name shown in the agent's Clients tab and approval prompt |
 | `retries` | `number` | `3` | Max additional connection attempts after the first failure |
 | `retryDelay` | `number` | `1000` | Ms to wait between retry attempts |
 
+Pass `clientName` unless you have a reason not to. Connecting with an unapproved
+token prompts the user to approve the application by name; without it they are
+asked to trust an "Unknown client".
+
 Throws if the agent is unreachable or the token is rejected after all retries.
 
+Calling `connect()` on an already-connected client **replaces** the connection —
+the existing socket is torn down before the new one is attempted, and its
+in-flight requests reject. If the new attempt then fails there is no connection
+left. Guard a connect-on-demand helper with `isConnected()` rather than
+reconnecting unconditionally.
+
 ---
 
 ### `printers()`
@@ -132,6 +144,29 @@ Submits a print job. Returns the job ID assigned by the agent.
 const jobId = await ep.print(config, data)
 ```
 
+Rejects if the job is refused, and also if it fails on the way to the spooler —
+where it previously resolved with a job id regardless. Always handle the
+rejection:
+
+```ts
+try {
+  const jobId = await ep.print(config, data)
+} catch (err) {
+  // printer not found, decode failure, spooler error …
+}
+```
+
+Two limits worth knowing before you build on this:
+
+- **Resolved means spooled, not printed.** The agent resolves once the OS print
+  spooler accepts the job. A printer that is offline, jammed, or out of paper
+  after that point still resolves, so keep whatever confirmation step your
+  workflow needs.
+- **Rejected does not prove nothing printed.** Requests time out after 30
+  seconds, and a large PDF can take longer than that to spool — the rejection
+  arrives while the agent is still working. Never resubmit a print
+  automatically on rejection; surface it and let a person decide.
+
 **`config`** — `PrintConfig`
 
 | Field | Type | Description |
@@ -207,13 +242,22 @@ if (!ep.isConnected()) {
 
 Registers a callback that fires whenever the connection closes — network drop, agent restart, or an explicit `disconnect()` call. Multiple listeners are supported.
 
+Returns a function that removes the listener:
+
 ```ts
-ep.onClose(() => {
+const stop = ep.onClose(() => {
   console.warn('Connection lost — reconnecting…')
   reconnect()
 })
+
+// later, e.g. when the component unmounts
+stop()
 ```
 
+Register once for the life of the client where you can. Registering inside a
+reconnect path without unsubscribing stacks a duplicate listener on every
+attempt, and they all fire on the next close.
+
 ---
 
 ## Using a custom instance

package/dist/edge-print.d.ts

@@ -209,6 +209,14 @@ export interface ConnectOptions {
      * any other requests are accepted.
      */
     token: string;
+    /**
+     * Name shown for this application in the agent's Clients tab and in the
+     * approval prompt the user sees when connecting with an unapproved token.
+     *
+     * Strongly recommended: without it the user is asked to trust an
+     * "Unknown client", which is not much of a decision.
+     */
+    clientName?: string;
     /**
      * Maximum number of additional connection attempts after the first failure.
      * @default 3
@@ -243,6 +251,21 @@ export interface ConnectOptions {
 export declare class EdgePrintClient {
     private ws;
     private pending;
+    /** Rejects the connect currently waiting on `onopen`, if there is one. */
+    private pendingOpen;
+    /** Bumped per connect, so a superseded one can tell it is no longer current. */
+    private connectGeneration;
+    /**
+     * Whether a connection currently exists from the application's point of view:
+     * a socket that opened *and* authenticated, and has not since gone away.
+     *
+     * Distinct from `authenticated`, which tracks one socket. This tracks whether
+     * there is anything for `onClose` to report the loss of, and is the single
+     * rule every teardown path consults — the alternative was each path deciding
+     * for itself, which is how the same event came to be announced in one place
+     * and swallowed in another.
+     */
+    private established;
     private authenticated;
     private closeListeners;
     /**
@@ -252,6 +275,13 @@ export declare class EdgePrintClient {
      * waiting `options.retryDelay` ms (default 1 000) between attempts. If all
      * attempts fail the last error is re-thrown.
      *
+     * Calling this on an already-connected client **replaces** the connection:
+     * the existing socket is torn down before the new one is attempted, and its
+     * in-flight requests reject. If the new attempt then fails there is no
+     * connection left, and close listeners are notified. Guard a
+     * connect-on-demand helper with {@link EdgePrintClient.isConnected} rather
+     * than reconnecting unconditionally.
+     *
      * @throws {Error} If the agent is unreachable or the token is rejected after
      *   all retries are exhausted.
      *
@@ -295,7 +325,28 @@ export declare class EdgePrintClient {
      * @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.
+     * @throws {Error} If not connected, if the agent rejects the job, or if the
+     *   job fails on the way to the spooler.
+     *
+     * A resolved promise means the job was handed to the OS print spooler — not
+     * that paper came out. A printer that is offline, jammed or out of paper
+     * after the spooler accepts the job still resolves.
+     *
+     * A rejection is also not proof that nothing printed: a request that exceeds
+     * the client's 30 s timeout rejects while the agent may still be spooling it.
+     * Do not resubmit a print automatically on rejection.
+     *
+     * When the agent had already created a job before it failed, the thrown error
+     * carries a `jobId` property matching the entry in the agent's job history —
+     * useful when surfacing a failure someone has to chase:
+     *
+     * ```ts
+     * try {
+     *   await ep.print(config, data)
+     * } catch (err) {
+     *   const jobId = (err as Error & { jobId?: string }).jobId
+     * }
+     * ```
      *
      * @example Print a PDF
      * ```ts
@@ -334,15 +385,49 @@ export declare class EdgePrintClient {
      *
      * Multiple listeners can be registered; all are called in registration order.
      *
+     * @returns A function that removes this listener. Registering inside a
+     *   reconnect path without unsubscribing stacks a duplicate listener on every
+     *   attempt, so hold onto this if the caller can register more than once.
+     *
      * @example
      * ```ts
-     * ep.onClose(() => {
+     * const stop = ep.onClose(() => {
      *   console.warn('Lost connection to Edge Printing agent — reconnecting…')
      *   reconnect()
      * })
+     *
+     * // later, e.g. when the component unmounts
+     * stop()
      * ```
      */
-    onClose(fn: () => void): void;
+    onClose(fn: () => void): () => void;
+    /**
+     * Announces the loss of an established connection, exactly once.
+     *
+     * A socket that never authenticated was never a connection, so its going
+     * away is not something `onClose` reports — announcing it would have an
+     * onClose-driven reconnect racing the retry loop already running.
+     */
+    private markClosed;
+    /**
+     * Tears down the current socket so it cannot reach this client again.
+     *
+     * Handlers are detached before closing, because the close event arrives in a
+     * later task — by which time the socket may have been replaced, and its
+     * `onclose` would otherwise report the *replacement* as disconnected.
+     *
+     * Detaching means the teardown that handler would have done has to happen
+     * here instead: clearing `authenticated`, settling in-flight requests, and
+     * settling a connect still waiting on `onopen`. That last one is easy to
+     * miss — a connect whose handlers are removed before either fires has
+     * nothing left to settle it, and `request()`'s timeout does not cover it, so
+     * it would wait forever.
+     *
+     * Close listeners are not fired from here. Whether a caller hears about a
+     * lost connection is `markClosed`'s decision, because only it knows whether
+     * there was an established connection to lose.
+     */
+    private discardSocket;
     private openSocket;
     private handleMessage;
     private request;

package/dist/edge-print.js

@@ -40,6 +40,21 @@ export class EdgePrintClient {
     constructor() {
         this.ws = null;
         this.pending = new Map();
+        /** Rejects the connect currently waiting on `onopen`, if there is one. */
+        this.pendingOpen = null;
+        /** Bumped per connect, so a superseded one can tell it is no longer current. */
+        this.connectGeneration = 0;
+        /**
+         * Whether a connection currently exists from the application's point of view:
+         * a socket that opened *and* authenticated, and has not since gone away.
+         *
+         * Distinct from `authenticated`, which tracks one socket. This tracks whether
+         * there is anything for `onClose` to report the loss of, and is the single
+         * rule every teardown path consults — the alternative was each path deciding
+         * for itself, which is how the same event came to be announced in one place
+         * and swallowed in another.
+         */
+        this.established = false;
         this.authenticated = false;
         this.closeListeners = [];
     }
@@ -50,6 +65,13 @@ export class EdgePrintClient {
      * waiting `options.retryDelay` ms (default 1 000) between attempts. If all
      * attempts fail the last error is re-thrown.
      *
+     * Calling this on an already-connected client **replaces** the connection:
+     * the existing socket is torn down before the new one is attempted, and its
+     * in-flight requests reject. If the new attempt then fails there is no
+     * connection left, and close listeners are notified. Guard a
+     * connect-on-demand helper with {@link EdgePrintClient.isConnected} rather
+     * than reconnecting unconditionally.
+     *
      * @throws {Error} If the agent is unreachable or the token is rejected after
      *   all retries are exhausted.
      *
@@ -65,17 +87,44 @@ export class EdgePrintClient {
      * ```
      */
     async connect(options) {
-        const { host = '127.0.0.1', port = 8181, token, retries = 3, retryDelay = 1000, } = options;
-        for (let attempt = 0; attempt <= retries; attempt++) {
+        const { host = '127.0.0.1', port = 8181, token, clientName, retries = 3, retryDelay = 1000, } = options;
+        // A negative count would skip the loop altogether and resolve without ever
+        // opening a socket, leaving the caller believing it is connected while
+        // every later call rejects with "Not connected".
+        const attempts = Math.max(0, retries);
+        const generation = ++this.connectGeneration;
+        for (let attempt = 0; attempt <= attempts; attempt++) {
+            // Checked before every attempt, not only after a failed one. A connect
+            // sleeping between retries would otherwise wake and open a socket —
+            // discarding whatever connection was established while it slept, and
+            // reconnecting after an explicit disconnect.
+            if (this.connectGeneration !== generation) {
+                throw new Error('Connection superseded');
+            }
             try {
                 await this.openSocket(`wss://${host}:${port}`);
-                await this.request('auth', { token });
+                // Omitted entirely when unset, rather than sent as undefined/null —
+                // the agent treats a missing key as "no name given".
+                await this.request('auth', clientName ? { token, clientName } : { token });
                 this.authenticated = true;
+                this.established = true;
                 return;
             }
             catch (err) {
-                if (attempt === retries)
+                // A newer connect has taken over since this attempt began. Its socket
+                // is not this attempt's to tear down.
+                if (this.connectGeneration !== generation)
+                    throw err;
+                this.discardSocket(new Error('Connection closed'));
+                // Every failure retries, including a refused token. The agent answers a
+                // token still awaiting approval with the same "Invalid token" it gives
+                // a bad one, so the client cannot tell them apart — and retrying while
+                // someone clicks Approve is the documented flow. Repeat attempts only
+                // bump a counter on the pending entry; the notification fires once.
+                if (attempt === attempts) {
+                    this.markClosed();
                     throw err;
+                }
                 await sleep(retryDelay);
             }
         }
@@ -114,7 +163,28 @@ export class EdgePrintClient {
      * @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.
+     * @throws {Error} If not connected, if the agent rejects the job, or if the
+     *   job fails on the way to the spooler.
+     *
+     * A resolved promise means the job was handed to the OS print spooler — not
+     * that paper came out. A printer that is offline, jammed or out of paper
+     * after the spooler accepts the job still resolves.
+     *
+     * A rejection is also not proof that nothing printed: a request that exceeds
+     * the client's 30 s timeout rejects while the agent may still be spooling it.
+     * Do not resubmit a print automatically on rejection.
+     *
+     * When the agent had already created a job before it failed, the thrown error
+     * carries a `jobId` property matching the entry in the agent's job history —
+     * useful when surfacing a failure someone has to chase:
+     *
+     * ```ts
+     * try {
+     *   await ep.print(config, data)
+     * } catch (err) {
+     *   const jobId = (err as Error & { jobId?: string }).jobId
+     * }
+     * ```
      *
      * @example Print a PDF
      * ```ts
@@ -143,9 +213,16 @@ export class EdgePrintClient {
      * disconnected.
      */
     disconnect() {
-        this.ws?.close();
-        this.ws = null;
-        this.authenticated = false;
+        // Routed through the same teardown as a replacement: nulling the reference
+        // alone leaves the socket's handlers attached, and its close then arrives
+        // later and tears down whatever connection has taken its place.
+        // Invalidates any connect still running, so a retry cannot wake up after
+        // this and quietly reconnect.
+        this.connectGeneration++;
+        this.discardSocket(new Error('Disconnected'));
+        // Detaching the handlers means the socket's own close never arrives, so
+        // without this the loss would go unannounced.
+        this.markClosed();
     }
     /**
      * `true` when the WebSocket is open and the session is authenticated.
@@ -162,29 +239,107 @@ export class EdgePrintClient {
      *
      * Multiple listeners can be registered; all are called in registration order.
      *
+     * @returns A function that removes this listener. Registering inside a
+     *   reconnect path without unsubscribing stacks a duplicate listener on every
+     *   attempt, so hold onto this if the caller can register more than once.
+     *
      * @example
      * ```ts
-     * ep.onClose(() => {
+     * const stop = ep.onClose(() => {
      *   console.warn('Lost connection to Edge Printing agent — reconnecting…')
      *   reconnect()
      * })
+     *
+     * // later, e.g. when the component unmounts
+     * stop()
      * ```
      */
     onClose(fn) {
         this.closeListeners.push(fn);
+        return () => {
+            const i = this.closeListeners.indexOf(fn);
+            if (i !== -1)
+                this.closeListeners.splice(i, 1);
+        };
     }
     // ── internals ────────────────────────────────────────────────────────────
+    /**
+     * Announces the loss of an established connection, exactly once.
+     *
+     * A socket that never authenticated was never a connection, so its going
+     * away is not something `onClose` reports — announcing it would have an
+     * onClose-driven reconnect racing the retry loop already running.
+     */
+    markClosed() {
+        if (!this.established)
+            return;
+        this.established = false;
+        [...this.closeListeners].forEach(fn => fn());
+    }
+    /**
+     * Tears down the current socket so it cannot reach this client again.
+     *
+     * Handlers are detached before closing, because the close event arrives in a
+     * later task — by which time the socket may have been replaced, and its
+     * `onclose` would otherwise report the *replacement* as disconnected.
+     *
+     * Detaching means the teardown that handler would have done has to happen
+     * here instead: clearing `authenticated`, settling in-flight requests, and
+     * settling a connect still waiting on `onopen`. That last one is easy to
+     * miss — a connect whose handlers are removed before either fires has
+     * nothing left to settle it, and `request()`'s timeout does not cover it, so
+     * it would wait forever.
+     *
+     * Close listeners are not fired from here. Whether a caller hears about a
+     * lost connection is `markClosed`'s decision, because only it knows whether
+     * there was an established connection to lose.
+     */
+    discardSocket(reason) {
+        const ws = this.ws;
+        const settleOpen = this.pendingOpen;
+        this.ws = null;
+        this.pendingOpen = null;
+        this.authenticated = false;
+        if (ws) {
+            ws.onopen = null;
+            ws.onmessage = null;
+            ws.onclose = null;
+            ws.onerror = null;
+            try {
+                ws.close();
+            }
+            catch { /* already closing or closed */ }
+        }
+        settleOpen?.(reason);
+        this.rejectPending(reason);
+    }
     openSocket(url) {
         return new Promise((resolve, reject) => {
+            // Never hold two sockets. This covers a retry, a reconnect on a live
+            // client, and a second connect racing the first.
+            this.discardSocket(new Error('Connection superseded'));
             const ws = new WebSocket(url);
-            ws.onopen = () => { this.ws = ws; resolve(); };
-            ws.onerror = () => reject(new Error(`Cannot reach Edge Printing agent at ${url}`));
+            this.ws = ws;
+            this.pendingOpen = reject;
+            const settled = () => { this.pendingOpen = null; };
+            ws.onopen = () => { settled(); resolve(); };
+            ws.onerror = () => {
+                settled();
+                reject(new Error(`Cannot reach Edge Printing agent at ${url}`));
+            };
             ws.onmessage = (ev) => this.handleMessage(String(ev.data));
             ws.onclose = () => {
+                // A socket can close during the handshake, before either onopen or
+                // onerror fires. Clearing the pending open without settling it would
+                // leave this connect waiting forever — request()'s timeout does not
+                // cover the open.
+                const openWaiting = this.pendingOpen;
+                settled();
+                openWaiting?.(new Error(`Cannot reach Edge Printing agent at ${url}`));
                 this.ws = null;
                 this.authenticated = false;
                 this.rejectPending(new Error('Connection closed'));
-                this.closeListeners.forEach(fn => fn());
+                this.markClosed();
             };
         });
     }
@@ -201,8 +356,24 @@ export class EdgePrintClient {
             return;
         const { resolve, reject } = this.pending.get(id);
         this.pending.delete(id);
-        if (msg['type'] === 'error') {
-            reject(new Error(msg['message'] ?? 'Unknown error'));
+        // `error` means the request never became a job. `print_error` means a job
+        // was created and then failed — it carries a real jobId, which is why
+        // matching only on `error` let failed prints resolve as successes.
+        // Matched by suffix so error types added later reject by default rather
+        // than silently resolving.
+        const type = String(msg['type'] ?? '');
+        if (type === 'error' || type.endsWith('_error')) {
+            const failure = new Error(msg['message'] ?? 'Unknown error');
+            // `print_error` carries the id of the job the agent created and then
+            // failed, which is the handle a caller needs to find it in the agent's
+            // job history. Attached rather than given an exported error type: the
+            // typed client error that formalises this arrives later, and a second
+            // error shape now would only have to be reconciled with it.
+            const jobId = msg['jobId'];
+            if (typeof jobId === 'string' && jobId.length > 0) {
+                Object.assign(failure, { jobId });
+            }
+            reject(failure);
         }
         else {
             resolve(msg);
@@ -215,20 +386,30 @@ export class EdgePrintClient {
                 return;
             }
             const id = crypto.randomUUID();
-            this.pending.set(id, { resolve, reject });
             const timeout = setTimeout(() => {
-                if (this.pending.has(id)) {
-                    this.pending.delete(id);
+                if (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);
+            // Registered once, already wrapped. The previous version inserted the
+            // raw handlers, sent, then replaced the entry with wrapped ones that
+            // closed over what it read back out of the map. A close in that window
+            // made rejectPending clear the map first, so the replacement re-inserted
+            // an entry whose captured handlers were undefined — poisoning the map for
+            // the next rejectPending, which then threw mid-loop and left every later
+            // request unsettled.
             this.pending.set(id, {
-                resolve: (v) => { clearTimeout(timeout); original.resolve(v); },
-                reject: (e) => { clearTimeout(timeout); original.reject(e); },
+                resolve: (v) => { clearTimeout(timeout); resolve(v); },
+                reject: (e) => { clearTimeout(timeout); reject(e); },
             });
+            try {
+                this.ws.send(JSON.stringify({ type, id, ...payload }));
+            }
+            catch (err) {
+                clearTimeout(timeout);
+                this.pending.delete(id);
+                reject(err instanceof Error ? err : new Error(String(err)));
+            }
         });
     }
     rejectPending(err) {

package/package.json

@@ -1,22 +1,32 @@
 {
   "name": "@gohcltech/edge-print-client",
-  "version": "2.0.31-develop",
+  "version": "2.0.42-develop",
   "description": "Browser client for the Edge Printing WebSocket agent",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://bitbucket.org/gohcl/edge-printing.git",
+    "directory": "client"
+  },
   "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"
+      "types": "./dist/edge-print.d.ts",
+      "import": "./dist/edge-print.js"
     }
   },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
   "scripts": {
-    "build": "tsc"
+    "build": "tsc",
+    "test": "tsc -p tsconfig.test.json && vitest run"
   },
   "devDependencies": {
-    "typescript": "^5.5.0"
+    "typescript": "^5.5.0",
+    "vitest": "^3.0.0"
   }
 }

package/src/edge-print.ts

@@ -1,484 +0,0 @@
-/**
- * @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 }],
- * )
- * ```
- */
-
-/**
- * Identifies the target printer.
- *
- * - Pass a `string` to use a printer by its OS name (e.g. `"Office Laser"`).
- * - Pass `{ host, port }` to route to a network printer by address.
- */
-export type PrinterTarget = string | { host: string; port: number }
-
-/**
- * Configuration options for a print job.
- *
- * All fields except `printer` are optional; omitted fields use the printer's
- * own defaults.
- */
-export interface PrintConfig {
-  /** Target printer — OS name string or remote `{ host, port }` object. */
-  printer: PrinterTarget
-  /** Number of copies to print (default: 1). */
-  copies?: number
-  /**
-   * Duplex (double-sided) mode.
-   * - `'none'` — single-sided
-   * - `'long-edge'` — flip on the long edge (standard book binding)
-   * - `'short-edge'` — flip on the short edge (calendar binding)
-   */
-  duplex?: 'none' | 'long-edge' | 'short-edge'
-  /** Page orientation (default: determined by document content). */
-  orientation?: 'portrait' | 'landscape'
-  /** Human-readable name shown in the OS print queue. */
-  jobName?: string
-  /**
-   * Color output mode.
-   * - `'color'` — full color
-   * - `'grayscale'` — color converted to gray
-   * - `'black-white'` — pure monochrome (fastest on mono printers)
-   */
-  colorType?: 'color' | 'grayscale' | 'black-white'
-  /**
-   * Paper size, exactly as returned by {@link PrinterInfo.papers}
-   * (e.g. `"Letter"`, `"A4"`). Omit to use the printer's current default.
-   */
-  paperSize?: string
-  /**
-   * Input tray, exactly as returned by {@link TrayInfo.name} inside
-   * {@link PrinterInfo.trays} (e.g. `"Tray 1"`, `"Auto"`).
-   * Omit to use the printer's current default.
-   */
-  tray?: string
-}
-
-/**
- * A single unit of content to be printed.
- *
- * Pass an array of `PrintData` to {@link EdgePrintClient.print} — each item
- * maps to one page or label in the job.
- *
- * @example PDF from a base64 string
- * ```ts
- * const page: PrintData = {
- *   type: 'pixel',
- *   format: 'pdf',
- *   flavor: 'base64',
- *   data: '<base64-encoded PDF>',
- * }
- * ```
- *
- * @example ZPL label (raw command)
- * ```ts
- * const label: PrintData = {
- *   type: 'raw',
- *   format: 'command',
- *   flavor: 'plain',
- *   data: '^XA^FO50,50^ADN,36,20^FDHello^FS^XZ',
- * }
- * ```
- */
-export interface PrintData {
-  /**
-   * Rendering pipeline.
-   * - `'raw'` — bytes are forwarded to the printer verbatim (ESC/POS, ZPL, EPL, …)
-   * - `'pixel'` — the agent rasterises the content before printing (PDF, HTML, image)
-   */
-  type: 'raw' | 'pixel'
-  /**
-   * Content format.
-   * - `'command'` — raw printer command language
-   * - `'pdf'` — Portable Document Format
-   * - `'html'` — HTML markup (agent renders to pixels)
-   * - `'image'` — raster image (PNG, JPEG, …)
-   */
-  format: 'command' | 'pdf' | 'html' | 'image'
-  /**
-   * How `data` is encoded.
-   * - `'plain'` — UTF-8 text
-   * - `'base64'` — Base64-encoded binary
-   * - `'hex'` — hex-encoded binary
-   * - `'file'` — absolute file path on the agent machine (agent reads the file)
-   */
-  flavor: 'plain' | 'base64' | 'hex' | 'file'
-  /** The content, encoded according to `flavor`. */
-  data: string
-  /** Format-specific extra options forwarded to the agent renderer. */
-  options?: Record<string, unknown>
-}
-
-/**
- * An input tray/bin reported by the printer driver.
- *
- * Returned inside {@link PrinterInfo.trays}.
- */
-export interface TrayInfo {
-  /** Tray name exactly as the driver reports it (e.g. `"Tray 1"`, `"Auto"`). */
-  name: string
-  /**
-   * Paper sizes this tray can hold, when the driver reports per-tray
-   * capability. Empty when the driver does not distinguish by tray —
-   * fall back to {@link PrinterInfo.papers} in that case.
-   */
-  papers?: string[]
-}
-
-/**
- * Metadata about a printer available on the agent machine.
- *
- * Returned by {@link EdgePrintClient.printers}.
- * Use {@link name} as the value for {@link PrintConfig.printer}.
- */
-export interface PrinterInfo {
-  /** OS-assigned printer name. Pass this to {@link PrintConfig.printer}. */
-  name: string
-  /** `true` if this is the system default printer. */
-  isDefault: boolean
-  /**
-   * Current printer status reported by the OS.
-   *
-   * Possible values: `"idle"` | `"printing"` | `"offline"` | `"error"` |
-   * `"paused"` | `"paper_jam"` | `"paper_out"` | `"disabled"` | `"unknown"`
-   */
-  status: string
-  /** Driver name as reported by the OS (present when available). */
-  driver?: string
-  /** Port or URI the printer is connected on (e.g. `"USB001"`, `"ipp://…"`). */
-  port?: string
-  /** Physical location string set in the printer properties. */
-  location?: string
-  /** Freeform comment from the printer properties. */
-  comment?: string
-  /** Windows share name, if the printer is shared on the network. */
-  shareName?: string
-  /** `true` if the printer supports color output. */
-  color?: boolean
-  /** `true` if the printer supports duplex (double-sided) printing. */
-  duplex?: boolean
-  /**
-   * Input trays available on this printer.
-   * Pass a {@link TrayInfo.name} value to {@link PrintConfig.tray}.
-   */
-  trays?: TrayInfo[]
-  /**
-   * All paper sizes the printer supports, regardless of tray.
-   * Pass one of these values to {@link PrintConfig.paperSize}.
-   */
-  papers?: string[]
-  /** Maximum number of copies the driver accepts in a single job. */
-  copiesMax?: number
-  /** Page orientations the driver supports (e.g. `["portrait", "landscape"]`). */
-  orientations?: string[]
-  /**
-   * `true` for Developer (virtual) printers — injected by the agent when
-   * Developer Printers mode is enabled in Settings. These printers capture
-   * jobs to disk or render a ZPL preview rather than sending to physical hardware.
-   */
-  virtualPrinter?: boolean
-}
-
-/**
- * Options passed to {@link EdgePrintClient.connect}.
- */
-export interface ConnectOptions {
-  /**
-   * Hostname or IP of the machine running the Edge Printing agent.
-   * @default '127.0.0.1'
-   */
-  host?: string
-  /**
-   * Port the agent is listening on.
-   * @default 8181
-   */
-  port?: number
-  /**
-   * API token shown in the Edge Printing settings window.
-   * Every WebSocket session must authenticate with this token before
-   * any other requests are accepted.
-   */
-  token: string
-  /**
-   * Maximum number of additional connection attempts after the first failure.
-   * @default 3
-   */
-  retries?: number
-  /**
-   * Milliseconds to wait between retry attempts.
-   * @default 1000
-   */
-  retryDelay?: number
-}
-
-type Pending = { resolve: (v: unknown) => void; reject: (e: Error) => void }
-
-/**
- * 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 {
-  private ws: WebSocket | null = null
-  private pending = new Map<string, Pending>()
-  private authenticated = false
-  private closeListeners: Array<() => void> = []
-
-  /**
-   * 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: ConnectOptions): Promise<void> {
-    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(): Promise<PrinterInfo[]> {
-    const resp = await this.request('get_printers', {}) as { printers: PrinterInfo[] }
-    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(): Promise<string> {
-    const resp = await this.request('get_default_printer', {}) as { name: string }
-    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: PrintConfig, data: PrintData[]): Promise<string> {
-    const resp = await this.request('print', { config, data }) as { jobId: string }
-    return resp.jobId
-  }
-
-  /**
-   * Close the WebSocket connection and reset client state.
-   *
-   * Any in-flight requests are rejected. Safe to call when already
-   * disconnected.
-   */
-  disconnect(): void {
-    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(): boolean {
-    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: () => void): void {
-    this.closeListeners.push(fn)
-  }
-
-  // ── internals ────────────────────────────────────────────────────────────
-
-  private openSocket(url: string): Promise<void> {
-    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())
-      }
-    })
-  }
-
-  private handleMessage(raw: string): void {
-    let msg: Record<string, unknown>
-    try { msg = JSON.parse(raw) } catch { return }
-
-    const id = msg['id'] as string | undefined
-    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'] as string) ?? 'Unknown error'))
-    } else {
-      resolve(msg)
-    }
-  }
-
-  private request(type: string, payload: Record<string, unknown>): Promise<unknown> {
-    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`))
-        }
-      }, 30_000)
-
-      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) },
-      })
-    })
-  }
-
-  private rejectPending(err: Error): void {
-    for (const { reject } of this.pending.values()) reject(err)
-    this.pending.clear()
-  }
-}
-
-function sleep(ms: number): Promise<void> {
-  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/tsconfig.json

@@ -1,13 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2020",
-    "module": "ESNext",
-    "moduleResolution": "bundler",
-    "declaration": true,
-    "declarationDir": "./dist",
-    "outDir": "./dist",
-    "strict": true,
-    "lib": ["ES2020", "DOM"]
-  },
-  "include": ["src/**/*.ts"]
-}