@gohcltech/edge-print-client 2.0.50-develop → 2.0.54-develop

package/README.md

@@ -80,6 +80,11 @@ asked to trust an "Unknown client".
 
 Throws if the agent is unreachable or the token is rejected after all retries.
 
+The client sends its wire protocol version automatically as part of the auth
+handshake; it is not a `connect()` option. If the agent speaks a different
+version, `connect()` throws a message naming both versions and which side to
+update — see [`protocolVersion`](#protocolversion).
+
 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
@@ -117,6 +122,15 @@ Each `PrinterInfo` object includes:
 | `orientations` | `string[]?` | Supported orientations (e.g. `["portrait", "landscape"]`) |
 | `virtualPrinter` | `boolean?` | `true` for Developer (virtual) printers injected by the agent |
 
+1.x agents sent `is_default`, `share_name`, `copies_max` and `virtual_printer`.
+Those spellings are still accepted on read and mapped onto the camelCase fields
+above, so nothing downstream sees the old names. **Removed in 3.0.**
+
+This is not a promise that a 1.x agent works: `connect()` refuses a protocol-1
+agent before `printers()` is ever reached. It is there so that a 2.x agent which
+regresses a field name degrades to a missing value rather than a silent
+`undefined`.
+
 `TrayInfo`:
 
 | Field | Type | Description |
@@ -238,6 +252,41 @@ if (!ep.isConnected()) {
 
 ---
 
+### `agentVersion`
+
+Read-only. Version of the agent this client is connected to, as the agent
+reported it during `connect()`.
+
+```ts
+console.log(`Edge Printing agent ${ep.agentVersion}`)  // "2.0.7"
+```
+
+`undefined` until a connection is authenticated, and again once it closes —
+including the gap during a reconnect, where the old socket is torn down before
+the new one authenticates. It is also `undefined` on a live connection if the
+agent did not report a version, so treat it as optional even when
+`isConnected()` is `true`. Use it for diagnostics and support output, not to
+branch behaviour on.
+
+---
+
+### `protocolVersion`
+
+Read-only. Wire protocol version the connected agent speaks.
+
+```ts
+console.log(ep.protocolVersion)  // 2
+```
+
+`undefined` until a connection is authenticated, and again once it closes. When
+it is set it always equals this client's own protocol version — `connect()`
+refuses any other — so it is a diagnostic rather than a capability check.
+
+The protocol version is independent of the package version: 2.0 and 2.4 of this
+library both speak protocol `2`.
+
+---
+
 ### `onClose(fn)`
 
 Registers a callback that fires whenever the connection closes — network drop, agent restart, or an explicit `disconnect()` call. Multiple listeners are supported.
@@ -334,6 +383,22 @@ If you see a security warning, the certificate is not yet trusted.
 
 The token was rejected. Generate a new one from the Edge Printing settings window.
 
+### `connect()` throws "Protocol version mismatch"
+
+The agent and this library speak different wire protocol versions. The message
+names both and says which side to update:
+
+- **"Update the Edge Printing agent"** — the agent is older than this library.
+  Install a newer agent build on the user's machine.
+- **"Update the Edge Printing client library"** — the agent is newer. Upgrade
+  `@gohcltech/edge-print-client` in the web app.
+
+An agent older than 2.0 has no handshake at all and reports as protocol `1`.
+
+A mismatch is deterministic, so `connect()`'s retries cannot clear it — it still
+exhausts them (about 3 seconds by default) before throwing. Pass `retries: 0`
+when probing for a usable agent. One side has to be upgraded.
+
 ### Requests time out after 30 seconds
 
 The agent accepted the connection but stopped responding. Restart the agent. If

package/dist/edge-print.d.ts

@@ -268,6 +268,8 @@ export declare class EdgePrintClient {
     private established;
     private authenticated;
     private closeListeners;
+    private agentVersionValue;
+    private protocolVersionValue;
     /**
      * Open a WebSocket connection to the Edge Printing agent and authenticate.
      *
@@ -379,6 +381,31 @@ export declare class EdgePrintClient {
      * connection is established.
      */
     isConnected(): boolean;
+    /**
+     * Version of the Edge Printing agent this client is connected to, as the
+     * agent reported it during {@link connect}.
+     *
+     * `undefined` until a connection is authenticated, and again once it closes —
+     * including for the gap during a reconnect, where the old socket is torn down
+     * before the new one authenticates. Also `undefined` on a live connection if
+     * the agent reported no version, so it stays optional even when
+     * {@link isConnected} is `true`. Read it for diagnostics and support output,
+     * not to branch behaviour on: the agent's *protocol* version, which
+     * {@link protocolVersion} reports, is what determines what the wire supports.
+     */
+    get agentVersion(): string | undefined;
+    /**
+     * Wire protocol version the connected agent speaks.
+     *
+     * `undefined` until a connection is authenticated, and again once it closes.
+     * When it is set it always equals this client's own protocol version —
+     * {@link connect} refuses any other — so it is a diagnostic, not a
+     * capability check.
+     *
+     * This client sends its protocol version automatically; it is not a
+     * {@link ConnectOptions} field.
+     */
+    get protocolVersion(): number | undefined;
     /**
      * Register a callback invoked whenever the connection closes — whether from
      * a network drop, an agent restart, or an explicit {@link disconnect} call.
@@ -431,6 +458,16 @@ export declare class EdgePrintClient {
     private openSocket;
     private handleMessage;
     private request;
+    /**
+     * Clears the state that belongs to one socket rather than to the client.
+     *
+     * Invariant: when {@link isConnected} is `false`, both version getters read
+     * `undefined`. Two paths tear a socket down — {@link discardSocket} and
+     * `openSocket`'s `onclose`, which does *not* route through it — and both must
+     * call this. Clearing in only one leaves a client whose agent restarted still
+     * reporting a version for a connection that is gone.
+     */
+    private clearSessionState;
     private rejectPending;
 }
 /**

package/dist/edge-print.js

@@ -16,6 +16,55 @@
  * )
  * ```
  */
+/**
+ * The wire protocol this client speaks.
+ *
+ * Deliberately independent of the package version and hand-maintained: 2.0 and
+ * 2.4 of this library both speak protocol 2, and a patch release must not read
+ * as a protocol change. Bump it only when the wire format itself changes, in
+ * lockstep with the agent's `PROTOCOL_VERSION`.
+ */
+const PROTOCOL_VERSION = 2;
+/**
+ * An `auth_ok` from an agent that predates the handshake carries no version.
+ * Such an agent is, by definition, speaking protocol 1.
+ */
+const LEGACY_PROTOCOL_VERSION = 1;
+/**
+ * Maps a printer object off the wire onto {@link PrinterInfo}.
+ *
+ * Belt-and-braces, not a promise of 1.x agent support: the version handshake in
+ * {@link EdgePrintClient.connect} refuses a protocol-1 agent outright, so a real
+ * 1.x agent never reaches this function. It exists so that a *2.x* agent which
+ * regresses a field name — or a future decision to tolerate older agents —
+ * degrades to a missing value rather than a silent `undefined` in a UI. Do not
+ * read support for old agents into it and relax the handshake.
+ *
+ * Deprecated on arrival: the snake_case half is removed in 3.0.
+ */
+function normalisePrinter(p) {
+    // Destructured out rather than spread over, so the result carries no
+    // snake_case keys. `{ ...p, isDefault }` would leave `is_default` sitting on
+    // an object whose declared type says it cannot be there.
+    const { is_default, share_name, copies_max, virtual_printer, ...rest } = p;
+    const shareName = p.shareName ?? share_name;
+    const copiesMax = p.copiesMax ?? copies_max;
+    const virtualPrinter = p.virtualPrinter ?? virtual_printer;
+    return {
+        ...rest,
+        // Required and a boolean, so it gets a default — `undefined` reaching a
+        // template renders "default: undefined".
+        isDefault: p.isDefault ?? is_default ?? false,
+        // Spread conditionally, not assigned. `shareName: undefined` still creates
+        // an own key, so a plain assignment would make `'virtualPrinter' in p` true
+        // for every printer — and a caller uses that to tell "the agent did not
+        // report this" from "reported false". The agent omits absent optionals, so
+        // this keeps the shim's output the same shape as an unshimmed payload.
+        ...(shareName !== undefined && { shareName }),
+        ...(copiesMax !== undefined && { copiesMax }),
+        ...(virtualPrinter !== undefined && { virtualPrinter }),
+    };
+}
 /**
  * WebSocket client for the Edge Printing agent.
  *
@@ -103,9 +152,44 @@ export class EdgePrintClient {
             }
             try {
                 await this.openSocket(`wss://${host}:${port}`);
-                // 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 });
+                // `clientName` is omitted entirely when unset, rather than sent as
+                // undefined/null — the agent treats a missing key as "no name given".
+                // Built as one object rather than a ternary over two literals, so
+                // `protocolVersion` cannot end up on only one of the branches.
+                const auth = {
+                    token,
+                    protocolVersion: PROTOCOL_VERSION,
+                    ...(clientName ? { clientName } : {}),
+                };
+                const ack = await this.request('auth', auth);
+                // An agent that predates the handshake answers with a bare `auth_ok`.
+                // A non-integer version folds to the same place: `"2"` is a client bug
+                // we want reported, not coerced into a match.
+                const agentProtocol = Number.isInteger(ack['protocolVersion'])
+                    ? ack['protocolVersion']
+                    : LEGACY_PROTOCOL_VERSION;
+                if (agentProtocol !== PROTOCOL_VERSION) {
+                    throw new Error(`Protocol version mismatch: this client speaks protocol version ` +
+                        `${PROTOCOL_VERSION}, but the agent speaks ${agentProtocol}. ` +
+                        (agentProtocol < PROTOCOL_VERSION
+                            ? 'Update the Edge Printing agent.'
+                            : 'Update the Edge Printing client library.'));
+                }
+                // Re-checked after the await: `request` suspends, and a newer connect
+                // (or a `disconnect`) can land while this one is waiting on the agent.
+                // Without this the superseded attempt goes on to publish its agent's
+                // versions and mark itself established over whatever replaced it — the
+                // same check the loop makes before each attempt and in the catch, which
+                // between them cover every path except this one.
+                if (this.connectGeneration !== generation) {
+                    throw new Error('Connection superseded');
+                }
+                // Assigned together so the getters and `isConnected()` agree: either
+                // this attempt owns the connection and publishes all of it, or none.
+                this.agentVersionValue = typeof ack['agentVersion'] === 'string'
+                    ? ack['agentVersion']
+                    : undefined;
+                this.protocolVersionValue = agentProtocol;
                 this.authenticated = true;
                 this.established = true;
                 return;
@@ -142,7 +226,7 @@ export class EdgePrintClient {
      */
     async printers() {
         const resp = await this.request('get_printers', {});
-        return resp.printers;
+        return (resp.printers ?? []).map(normalisePrinter);
     }
     /**
      * Return the name of the OS default printer.
@@ -233,6 +317,35 @@ export class EdgePrintClient {
     isConnected() {
         return this.ws?.readyState === WebSocket.OPEN && this.authenticated;
     }
+    /**
+     * Version of the Edge Printing agent this client is connected to, as the
+     * agent reported it during {@link connect}.
+     *
+     * `undefined` until a connection is authenticated, and again once it closes —
+     * including for the gap during a reconnect, where the old socket is torn down
+     * before the new one authenticates. Also `undefined` on a live connection if
+     * the agent reported no version, so it stays optional even when
+     * {@link isConnected} is `true`. Read it for diagnostics and support output,
+     * not to branch behaviour on: the agent's *protocol* version, which
+     * {@link protocolVersion} reports, is what determines what the wire supports.
+     */
+    get agentVersion() {
+        return this.agentVersionValue;
+    }
+    /**
+     * Wire protocol version the connected agent speaks.
+     *
+     * `undefined` until a connection is authenticated, and again once it closes.
+     * When it is set it always equals this client's own protocol version —
+     * {@link connect} refuses any other — so it is a diagnostic, not a
+     * capability check.
+     *
+     * This client sends its protocol version automatically; it is not a
+     * {@link ConnectOptions} field.
+     */
+    get protocolVersion() {
+        return this.protocolVersionValue;
+    }
     /**
      * Register a callback invoked whenever the connection closes — whether from
      * a network drop, an agent restart, or an explicit {@link disconnect} call.
@@ -299,7 +412,7 @@ export class EdgePrintClient {
         const settleOpen = this.pendingOpen;
         this.ws = null;
         this.pendingOpen = null;
-        this.authenticated = false;
+        this.clearSessionState();
         if (ws) {
             ws.onopen = null;
             ws.onmessage = null;
@@ -337,7 +450,7 @@ export class EdgePrintClient {
                 settled();
                 openWaiting?.(new Error(`Cannot reach Edge Printing agent at ${url}`));
                 this.ws = null;
-                this.authenticated = false;
+                this.clearSessionState();
                 this.rejectPending(new Error('Connection closed'));
                 this.markClosed();
             };
@@ -412,6 +525,20 @@ export class EdgePrintClient {
             }
         });
     }
+    /**
+     * Clears the state that belongs to one socket rather than to the client.
+     *
+     * Invariant: when {@link isConnected} is `false`, both version getters read
+     * `undefined`. Two paths tear a socket down — {@link discardSocket} and
+     * `openSocket`'s `onclose`, which does *not* route through it — and both must
+     * call this. Clearing in only one leaves a client whose agent restarted still
+     * reporting a version for a connection that is gone.
+     */
+    clearSessionState() {
+        this.authenticated = false;
+        this.agentVersionValue = undefined;
+        this.protocolVersionValue = undefined;
+    }
     rejectPending(err) {
         for (const { reject } of this.pending.values())
             reject(err);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gohcltech/edge-print-client",
-  "version": "2.0.50-develop",
+  "version": "2.0.54-develop",
   "description": "Browser client for the Edge Printing WebSocket agent",
   "license": "MIT",
   "repository": {