@gohcltech/edge-print-client 2.0.89-develop → 2.0.108-develop

package/README.md

@@ -76,6 +76,7 @@ await ep.connect({
 | `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 |
+| `requestApproval` | `boolean?` | _(none)_ | Whether an unapproved token asks the user for approval — see below |
 | `retries` | `number` | `3` | Max additional connection attempts after the first failure |
 | `retryDelay` | `number` | `1000` | Ms to wait between retry attempts |
 
@@ -85,6 +86,35 @@ asked to trust an "Unknown client".
 
 Throws if the agent is unreachable or the token is rejected after all retries.
 
+#### Asking for approval
+
+An application can connect with a token it generated itself and have the user
+approve it in Edge Printing, instead of having them paste a token in. Set
+`requestApproval` to say when that should prompt the user:
+
+- **`true`** when the user has asked to connect, for example from a "Connect to
+  Edge Printing" button. The request appears on the agent's Clients tab, and
+  `connect()` rejects with `pending_approval` until the user approves it.
+- **`false`** on every automatic connect, such as page load or a reconnect.
+  Nobody is prompted. `connect()` rejects with `pending_approval` if a
+  request is already waiting, or `not_approved` if there is none: never asked,
+  dismissed or revoked.
+- **Omitted:** every unapproved connect prompts and is refused with
+  `invalid_token`, as before this option existed.
+
+`not_approved` is thrown without retrying, since waiting cannot change it.
+`pending_approval` is retried, and `connect()` succeeds if the user approves
+in time. Within one `connect()`, `true` is only sent until the agent confirms
+the request. Retries send `false`, so a request the user dismisses is not
+put back.
+
+An agent older than this option ignores it and answers `invalid_token`.
+
+Revoking an application on the Clients tab closes its open connections. The
+client sees the close, and its next connect is treated like any unapproved
+token: refused with `not_approved` under `requestApproval: false`, or put back
+on the Clients tab as a new request under `true` or with the option omitted.
+
 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
@@ -550,7 +580,9 @@ Sent by the agent:
 | Code | Raised when |
 |---|---|
 | `not_authenticated` | A request was sent before `connect()` finished authenticating |
-| `invalid_token` | The token is unknown, or still awaiting approval in the agent UI |
+| `invalid_token` | The token is unknown, or still awaiting approval in the agent UI. Only when `requestApproval` was not set |
+| `pending_approval` | The token is waiting for the user to approve it on the agent's Clients tab |
+| `not_approved` | The token is not approved and nobody has been asked: never requested, dismissed or revoked. Connect with `requestApproval: true` to ask |
 | `invalid_request` | The agent could not parse the request |
 | `unsupported_value` | `paperSize`, `tray` or `mediaType` names a value the printer does not list. Carries `supported` |
 | `unsupported_capability` | A capability the printer explicitly reports it lacks |
@@ -685,7 +717,17 @@ If you see a security warning, the certificate is not yet trusted.
 
 The token was rejected, or it is new and still awaiting approval in the agent's
 Clients tab. Approve it there, or generate a fresh one from the Edge Printing
-settings window.
+settings window. Setting `requestApproval` tells the two cases apart.
+
+### `connect()` rejects with `code: 'pending_approval'`
+
+The request is on the agent's Clients tab, waiting for the user. Tell them to
+approve it there, then connect again with `requestApproval: false`.
+
+### `connect()` rejects with `code: 'not_approved'`
+
+The user has not been asked, or dismissed or revoked the request. Offer to ask
+again, and connect with `requestApproval: true` when they accept.
 
 ### `connect()` rejects with `code: 'protocol_mismatch'`
 

package/dist/edge-print.d.ts

@@ -362,6 +362,22 @@ export interface ConnectOptions {
      * "Unknown client", which is not much of a decision.
      */
     clientName?: string;
+    /**
+     * Whether an unapproved token should ask the user for approval.
+     *
+     * - `true` — put this application on the agent's Clients tab for the user
+     *   to approve. Rejects with `pending_approval`. Use only when the user has
+     *   asked to connect.
+     * - `false` — ask nobody. Rejects with `pending_approval` if a request is
+     *   already waiting, or `not_approved` if there is none (never asked,
+     *   dismissed or revoked). Use on every automatic connect, so a dismissed
+     *   request does not come back by itself.
+     * - omitted — the agent's original behaviour: every unapproved connect
+     *   asks, and is refused with `invalid_token`.
+     *
+     * An agent older than this option ignores it and answers `invalid_token`.
+     */
+    requestApproval?: boolean;
     /**
      * Maximum number of additional connection attempts after the first failure.
      * @default 3
@@ -373,7 +389,7 @@ export interface ConnectOptions {
      */
     retryDelay?: number;
 }
-declare const ERROR_CODES: readonly ["not_authenticated", "invalid_token", "protocol_mismatch", "invalid_request", "unsupported_value", "unsupported_capability", "invalid_geometry", "content_overflow", "unsupported_for_path", "encrypted_pdf", "printer_not_found", "print_failed", "internal_error", "not_connected", "unreachable", "connection_closed", "timeout", "unknown"];
+declare const ERROR_CODES: readonly ["not_authenticated", "invalid_token", "pending_approval", "not_approved", "protocol_mismatch", "invalid_request", "unsupported_value", "unsupported_capability", "invalid_geometry", "content_overflow", "unsupported_for_path", "encrypted_pdf", "printer_not_found", "print_failed", "internal_error", "not_connected", "unreachable", "connection_closed", "timeout", "unknown"];
 export type EdgePrintErrorCode = typeof ERROR_CODES[number];
 /** A warning the agent recorded about a job it nonetheless printed. */
 export interface JobWarning {
@@ -479,7 +495,8 @@ export declare class EdgePrintClient {
      *
      * 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.
+     * attempts fail the last error is re-thrown. A `not_approved` refusal is
+     * thrown at once: nobody has been asked, so waiting cannot change it.
      *
      * Calling this on an already-connected client **replaces** the connection:
      * the existing socket is torn down before the new one is attempted, and its

package/dist/edge-print.js

@@ -33,7 +33,8 @@ export const inches = (m) => ({ ...m, units: 'in' });
  * does not recognise, which is what lets a new client work against an old agent.
  */
 const AGENT_CODES = [
-    'not_authenticated', 'invalid_token', 'protocol_mismatch', 'invalid_request',
+    'not_authenticated', 'invalid_token', 'pending_approval', 'not_approved',
+    'protocol_mismatch', 'invalid_request',
     'unsupported_value', 'unsupported_capability', 'invalid_geometry',
     'content_overflow', 'unsupported_for_path', 'encrypted_pdf',
     'printer_not_found', 'print_failed', 'internal_error',
@@ -212,7 +213,8 @@ export class EdgePrintClient {
      *
      * 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.
+     * attempts fail the last error is re-thrown. A `not_approved` refusal is
+     * thrown at once: nobody has been asked, so waiting cannot change it.
      *
      * Calling this on an already-connected client **replaces** the connection:
      * the existing socket is torn down before the new one is attempted, and its
@@ -236,7 +238,11 @@ export class EdgePrintClient {
      * ```
      */
     async connect(options) {
-        const { host = '127.0.0.1', port = 8181, token, clientName, retries = 3, retryDelay = 1000, } = options;
+        const { host = '127.0.0.1', port = 8181, token, clientName, requestApproval, retries = 3, retryDelay = 1000, } = options;
+        // Asks on the first attempt that reaches the agent, and not again: if the
+        // user dismissed the request while this was retrying, asking on the next
+        // attempt would put it straight back in front of them.
+        let ask = requestApproval;
         // 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".
@@ -260,6 +266,8 @@ export class EdgePrintClient {
                     token,
                     protocolVersion: PROTOCOL_VERSION,
                     ...(clientName ? { clientName } : {}),
+                    // Omitted when unset, which an agent reads as the original behaviour.
+                    ...(typeof ask === 'boolean' ? { requestApproval: ask } : {}),
                 };
                 const ack = await this.request('auth', auth);
                 // An agent that predates the handshake answers with a bare `auth_ok`.
@@ -300,11 +308,22 @@ export class EdgePrintClient {
                 if (this.connectGeneration !== generation)
                     throw err;
                 this.discardSocket(new EdgePrintError('connection_closed', '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.
+                // Nobody has been asked, so waiting cannot change the answer.
+                if (err instanceof EdgePrintError && err.code === 'not_approved') {
+                    this.markClosed();
+                    throw err;
+                }
+                if (err instanceof EdgePrintError && err.code === 'pending_approval') {
+                    ask = false;
+                }
+                // Every other failure retries, including a refused token. A token
+                // awaiting approval may be approved before the next attempt — and an
+                // older agent answers that with the same `invalid_token` it gives a bad
+                // one, so the client cannot tell them apart. Once the agent confirms a
+                // request with `pending_approval`, retries send `requestApproval:
+                // false`, so they only check on it and a dismissal sticks. Without the
+                // option, repeat attempts bump a counter on the pending entry; either
+                // way the notification fires once.
                 if (attempt === attempts) {
                     this.markClosed();
                     throw err;

package/package.json

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