@gohcltech/edge-print-client 1.0.29-develop → 2.0.40-develop

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,6 +1,6 @@
 {
   "name": "@gohcltech/edge-print-client",
-  "version": "1.0.29-develop",
+  "version": "2.0.40-develop",
   "description": "Browser client for the Edge Printing WebSocket agent",
   "type": "module",
   "main": "./dist/edge-print.cjs",
@@ -14,9 +14,11 @@
     }
   },
   "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"
   }
 }