@gohcltech/edge-print-client 2.0.57-develop → 2.0.70-develop

package/README.md

@@ -36,11 +36,12 @@ const printers = await ep.printers()
 console.log(printers.map(p => p.name))
 
 // 3. Print a PDF (base64-encoded)
-const jobId = await ep.print(
+const { jobId, warnings } = await ep.print(
   { printer: 'Office Laser', copies: 1 },
   [{ type: 'pixel', format: 'pdf', flavor: 'base64', data: pdfBase64 }],
 )
 console.log('Queued as', jobId)
+for (const w of warnings) console.warn(w.message)
 
 // 4. Disconnect when done
 ep.disconnect()
@@ -118,10 +119,22 @@ Each `PrinterInfo` object includes:
 | `duplex` | `boolean?` | `true` if the printer supports double-sided printing |
 | `trays` | `TrayInfo[]?` | Input trays/bins (see below) |
 | `papers` | `string[]?` | All supported paper sizes (e.g. `["Letter", "A4"]`) |
+| `mediaTypes` | `string[]?` | Stock types the driver reports (e.g. `["Plain", "Bond"]`). Absent for most printers — see below |
 | `copiesMax` | `number?` | Maximum copies the driver accepts in one job |
 | `orientations` | `string[]?` | Supported orientations (e.g. `["portrait", "landscape"]`) |
 | `virtualPrinter` | `boolean?` | `true` for Developer (virtual) printers injected by the agent |
 
+**On `mediaTypes`.** The field is usually absent. Of eleven drivers surveyed,
+eight listed no stock types at all, and a ninth listed them only under a
+vendor-private key whose values are the driver's internal codes rather than
+names you could choose from — the agent reports nothing in that case too. When
+the field is absent the agent accepts whatever stock you ask for rather than
+guessing. When it *is*
+present the strings are the driver's own and are not always self-describing, so
+read them off the target machine (the agent's Printers tab lists them) rather
+than assuming a vocabulary. Passing a value the printer does not list rejects
+with `unsupported_value`, and the error's `supported` array names the real ones.
+
 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.**
@@ -152,24 +165,53 @@ const name = await ep.defaultPrinter() // "Office Laser"
 
 ### `print(config, data)`
 
-Submits a print job. Returns the job ID assigned by the agent.
+Submits a print job. Resolves to a `PrintResult`.
 
 ```ts
-const jobId = await ep.print(config, data)
+const { jobId, warnings } = await ep.print(config, data)
 ```
 
+| Field | Type | Description |
+|---|---|---|
+| `jobId` | `string` | The agent's id for the job, matching its entry in the job history |
+| `warnings` | `JobWarning[]` | Caveats the agent recorded about a job it printed anyway. Empty in the common case |
+
+Each `JobWarning` is `{ code, message }`. Today the only code is
+`capability_unverified` — the agent could not determine a capability, so it
+skipped the check and passed the request through. Treat the set as open-ended:
+log or surface `message` rather than branching on every code.
+
+> **Breaking change.** `print()` used to resolve to the job id string. It now
+> resolves to an object. Destructure it (`const { jobId } = await ep.print(…)`),
+> or the value you pass on will be `[object Object]`. TypeScript callers get a
+> compile error; JavaScript callers do not.
+
 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:
+rejection, and branch on `err.code` rather than the message text:
 
 ```ts
+import { EdgePrintError } from '@gohcltech/edge-print-client'
+
 try {
-  const jobId = await ep.print(config, data)
+  const { jobId } = await ep.print(config, data)
 } catch (err) {
-  // printer not found, decode failure, spooler error …
+  if (err instanceof EdgePrintError && err.code === 'unsupported_capability') {
+    // err.field names the setting the printer cannot do — 'colorType', 'duplex'
+  }
 }
 ```
 
+A job rejected by validation still gets a record in the agent's History, so an
+`EdgePrintError` from `print()` usually carries a `jobId` you can quote to
+support. A request refused before a job existed — one the agent could not parse
+— has no `jobId`.
+
+A rejection never carries warnings, even where the agent had already recorded
+some before the rule that failed. They are dropped deliberately: a note saying
+"we could not verify duplex" alongside a rejection for an unrelated reason is
+noise, not help.
+
 Two limits worth knowing before you build on this:
 
 - **Resolved means spooled, not printed.** The agent resolves once the OS print
@@ -193,6 +235,7 @@ Two limits worth knowing before you build on this:
 | `colorType` | `'color' \| 'grayscale' \| 'black-white'?` | Color mode |
 | `paperSize` | `string?` | Paper size from `PrinterInfo.papers` (e.g. `"Letter"`) |
 | `tray` | `string?` | Tray name from `TrayInfo.name` (e.g. `"Tray 1"`) |
+| `mediaType` | `string?` | Stock type from `PrinterInfo.mediaTypes` (e.g. `"Bond"`). Rejected for `raw`/`html` content and network targets |
 
 **`data`** — `PrintData[]`
 
@@ -309,6 +352,96 @@ attempt, and they all fire on the next close.
 
 ---
 
+## Errors
+
+Every rejection from this library is an `EdgePrintError` — including the ones
+raised locally, before a request ever reaches the agent. It extends `Error`, so
+`err.message` and `String(err)` read exactly as they did before codes existed.
+
+```ts
+import ep, { EdgePrintError } from '@gohcltech/edge-print-client'
+
+try {
+  await ep.print(config, data)
+} catch (err) {
+  if (!(err instanceof EdgePrintError)) throw err
+
+  if (err.retryable) {
+    // transport trouble — the same request may well work on a second attempt
+  } else if (err.field) {
+    console.error(`${err.field}: ${err.message}`)
+  } else {
+    console.error(err.message)
+  }
+}
+```
+
+| Property | Type | Description |
+|---|---|---|
+| `code` | `EdgePrintErrorCode` | The failure, from a closed set. `'unknown'` when the agent sent no code, or one this client predates |
+| `message` | `string` | Human-readable. Do not match on it — that is what `code` is for |
+| `field` | `string?` | The offending setting, when one setting is to blame |
+| `supported` | `string[]?` | What the printer accepts, for the codes that can say |
+| `requestId` | `string?` | The request this answers. Absent for failures raised before one existed |
+| `jobId` | `string?` | Present when the agent created a job and then failed it |
+| `retryable` | `boolean` | True only for transport failures — see below |
+
+### Codes
+
+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_request` | The agent could not parse the request |
+| `unsupported_capability` | A capability the printer explicitly reports it lacks |
+| `invalid_geometry` | A scale or margin outside what the protocol accepts |
+| `unsupported_for_path` | A setting that cannot be honoured on the requested path |
+| `printer_not_found` | `defaultPrinter()` found no default configured on the machine |
+| `print_failed` | The backend failed after the job was accepted and recorded |
+| `internal_error` | The agent itself failed — not the caller's doing |
+
+Raised locally by this library, never sent by the agent:
+
+| Code | Raised when |
+|---|---|
+| `not_connected` | A call was made while disconnected |
+| `unreachable` | The WebSocket could not be opened — agent not running, or wrong host/port |
+| `protocol_mismatch` | The agent and this library speak different wire protocol versions |
+| `connection_closed` | The connection dropped with a request in flight |
+| `timeout` | The agent accepted the request and did not answer within 30 seconds |
+
+`invalid_request` is raised by **both** sides: by the agent for a request it
+cannot parse, and here for a `config` or `data` value that cannot be serialised
+to JSON at all — a circular reference, say. Neither is retryable.
+
+The four codes in the table above are never accepted *from* the agent. A frame
+claiming `code: "timeout"` is read as `unknown`, so a failure the agent
+considers final cannot arrive labelled retryable.
+
+Three more are **reserved**: `unsupported_value`, `content_overflow` and
+`encrypted_pdf` are part of the closed set and typed here, so code written
+today handles them, but no agent sends them yet. `supported` is populated only
+by `unsupported_value`, so it is always `undefined` against an agent of this
+generation.
+
+And `unknown`, the fallback for a code this client does not recognise — which
+is what lets a client built today keep working against a future agent. Treat an
+unfamiliar code as a plain failure rather than a bug.
+
+### `retryable`
+
+`err.retryable` is true for `unreachable`, `connection_closed`, and `timeout`,
+and false for everything else. A validation rejection is deterministic: retrying
+it sends the same bad request again.
+
+Note that `retryable` says the *request* may succeed — not that nothing
+happened. See the `timeout` entry under Troubleshooting before you retry a
+print.
+
+---
+
 ## Using a custom instance
 
 The default export `ep` is a module-level singleton. If you need to connect to multiple agents simultaneously, create separate instances:
@@ -374,16 +507,18 @@ To confirm the certificate is trusted, open `https://127.0.0.1:8181` in the
 browser. If the page loads (even with an empty body) the certificate is fine.
 If you see a security warning, the certificate is not yet trusted.
 
-### `connect()` throws "Cannot reach Edge Printing agent"
+### `connect()` rejects with `code: 'unreachable'`
 
 - Confirm the Edge Printing agent is running (check the system tray / menu bar).
 - Confirm `host` and `port` match the agent's configured values (default `127.0.0.1:8181`).
 
-### `connect()` throws after authentication
+### `connect()` rejects with `code: 'invalid_token'`
 
-The token was rejected. Generate a new one from the Edge Printing settings window.
+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.
 
-### `connect()` throws "Protocol version mismatch"
+### `connect()` rejects with `code: 'protocol_mismatch'`
 
 The agent and this library speak different wire protocol versions. The message
 names both and says which side to update:
@@ -399,10 +534,15 @@ A mismatch is deterministic, so `connect()`'s retries cannot clear it — it sti
 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
+### A request rejects with `code: 'timeout'`
+
+The agent accepted the connection and did not answer within 30 seconds. Restart
+the agent. If the problem persists, file an issue with the agent log attached.
 
-The agent accepted the connection but stopped responding. Restart the agent. If
-the problem persists, file an issue with the agent log attached.
+For a `print()`, a timeout does **not** prove nothing printed — a large PDF can
+take longer than 30 seconds to spool, and the rejection arrives while the agent
+is still working. Never resubmit a print automatically; surface it and let a
+person decide.
 
 ---
 

package/dist/edge-print.d.ts

@@ -10,7 +10,7 @@
  *
  * await ep.connect({ token: 'your-api-token' })
  * const printers = await ep.printers()
- * const jobId = await ep.print(
+ * const { jobId, warnings } = await ep.print(
  *   { printer: 'Office Laser' },
  *   [{ type: 'pixel', format: 'pdf', flavor: 'base64', data: pdfBase64 }],
  * )
@@ -66,6 +66,16 @@ export interface PrintConfig {
      * Omit to use the printer's current default.
      */
     tray?: string;
+    /**
+     * Media / stock type, exactly as returned by {@link PrinterInfo.mediaTypes}
+     * (e.g. `"Plain"`, `"Bond"`, `"Thermal"`). Changes how the printer feeds and
+     * fuses the page. Omit to use the printer's current default.
+     *
+     * Not supported for `raw` or `html` content, or a network target — those
+     * paths never reach the printer's driver. Requesting it there rejects with
+     * `unsupported_for_path`.
+     */
+    mediaType?: string;
 }
 /**
  * A single unit of content to be printed.
@@ -178,6 +188,18 @@ export interface PrinterInfo {
      * Pass one of these values to {@link PrintConfig.paperSize}.
      */
     papers?: string[];
+    /**
+     * Stock types the driver reports — card stock, labels, envelopes and so on.
+     * Pass one of these values to {@link PrintConfig.mediaType}.
+     *
+     * Absent for most printers — many drivers report no stock types, and some
+     * report them only under a vendor-private key whose values are internal
+     * codes rather than choosable names. The agent reports nothing in either
+     * case and then accepts whatever is asked rather than guessing. When the
+     * field *is* present, the strings are the driver's own and may not be
+     * self-describing.
+     */
+    mediaTypes?: string[];
     /** Maximum number of copies the driver accepts in a single job. */
     copiesMax?: number;
     /** Page orientations the driver supports (e.g. `["portrait", "landscape"]`). */
@@ -228,6 +250,65 @@ 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"];
+export type EdgePrintErrorCode = typeof ERROR_CODES[number];
+/** A warning the agent recorded about a job it nonetheless printed. */
+export interface JobWarning {
+    /** e.g. `"capability_unverified"`. Open-ended: an agent may add codes. */
+    code: string;
+    message: string;
+}
+/** What {@link EdgePrintClient.print} resolves to. */
+export interface PrintResult {
+    /** The agent's id for the job, matching its entry in the job history. */
+    jobId: string;
+    /** Empty when the agent had nothing to report, which is the common case. */
+    warnings: JobWarning[];
+}
+/**
+ * A failure from the Edge Printing agent or from this client.
+ *
+ * Extends `Error`, so `e.message` and `String(e)` keep working for code
+ * written before codes existed.
+ *
+ * **Do not set `name` on this class.** A class name does not set `.name` — it
+ * is inherited as `"Error"` — so `String(e)` stays `"Error: …"`. Setting it
+ * would change that string for every existing consumer, which is exactly what
+ * extending `Error` is here to avoid.
+ */
+export declare class EdgePrintError extends Error {
+    /** `'unknown'` when the agent sent no code, or one this client predates. */
+    readonly code: EdgePrintErrorCode;
+    /** The offending setting, when one setting is to blame. */
+    readonly field?: string;
+    /** What the printer accepts, for the codes that can say. */
+    readonly supported?: string[];
+    /** The request this answers. Absent for failures raised before one existed. */
+    readonly requestId?: string;
+    /** Present when the agent created a job and then failed it. */
+    readonly jobId?: string;
+    constructor(code: EdgePrintErrorCode, message: string, detail?: {
+        field?: string;
+        supported?: string[];
+        requestId?: string;
+        jobId?: string;
+    });
+    /**
+     * Builds an error from an agent failure frame.
+     *
+     * Everything is read defensively: an older agent sends no `code` at all, and
+     * a newer one may send a code this client has never heard of. Both become
+     * `'unknown'` rather than reaching a caller as an invalid value.
+     */
+    static fromWire(msg: Record<string, unknown>): EdgePrintError;
+    /**
+     * Whether the same request might succeed on a retry.
+     *
+     * True only for transport failures. A validation rejection is deterministic:
+     * retrying it sends the same bad request again.
+     */
+    get retryable(): boolean;
+}
 /**
  * WebSocket client for the Edge Printing agent.
  *
@@ -284,7 +365,7 @@ export declare class EdgePrintClient {
      * 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
+     * @throws {EdgePrintError} If the agent is unreachable or the token is rejected after
      *   all retries are exhausted.
      *
      * @example
@@ -302,7 +383,7 @@ export declare class EdgePrintClient {
     /**
      * Return all printers available on the agent machine.
      *
-     * @throws {Error} If not connected.
+     * @throws {EdgePrintError} If not connected.
      *
      * @example
      * ```ts
@@ -317,7 +398,7 @@ export declare class EdgePrintClient {
      * Cheaper than calling {@link printers} when you only need the default name
      * and no other printer metadata.
      *
-     * @throws {Error} If not connected.
+     * @throws {EdgePrintError} If not connected.
      */
     defaultPrinter(): Promise<string>;
     /**
@@ -325,10 +406,13 @@ export declare class EdgePrintClient {
      *
      * @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.
+     * @returns A {@link PrintResult} — the agent's `jobId`, and any `warnings`
+     *   it recorded about a job it printed anyway. `warnings` is empty in the
+     *   common case.
      *
-     * @throws {Error} If not connected, if the agent rejects the job, or if the
-     *   job fails on the way to the spooler.
+     * @throws {EdgePrintError} If not connected, if the agent rejects the job, or
+     *   if the job fails on the way to the spooler. Branch on `err.code`, never
+     *   on the message text.
      *
      * 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
@@ -338,24 +422,31 @@ export declare class EdgePrintClient {
      * 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:
+     * A job rejected by validation is still recorded, so the thrown error
+     * usually carries a `jobId` matching the entry in the agent's job history —
+     * useful when surfacing a failure someone has to chase. A request refused
+     * before a job existed at all, such as one the agent could not parse, has no
+     * `jobId` to carry.
+     *
+     * A rejection never carries warnings, even where the agent had accumulated
+     * some before the rule that failed: they are dropped deliberately rather
+     * than reported alongside an unrelated failure.
      *
      * ```ts
      * try {
      *   await ep.print(config, data)
      * } catch (err) {
-     *   const jobId = (err as Error & { jobId?: string }).jobId
+     *   if (err instanceof EdgePrintError) console.error(err.code, err.jobId)
      * }
      * ```
      *
      * @example Print a PDF
      * ```ts
-     * const jobId = await ep.print(
+     * const { jobId, warnings } = await ep.print(
      *   { printer: 'Office Laser', copies: 2, duplex: 'long-edge' },
      *   [{ type: 'pixel', format: 'pdf', flavor: 'base64', data: pdfBase64 }],
      * )
+     * for (const w of warnings) console.warn(w.message)
      * ```
      *
      * @example Print a ZPL label
@@ -366,7 +457,7 @@ export declare class EdgePrintClient {
      * )
      * ```
      */
-    print(config: PrintConfig, data: PrintData[]): Promise<string>;
+    print(config: PrintConfig, data: PrintData[]): Promise<PrintResult>;
     /**
      * Close the WebSocket connection and reset client state.
      *

package/dist/edge-print.js

@@ -10,12 +10,108 @@
  *
  * await ep.connect({ token: 'your-api-token' })
  * const printers = await ep.printers()
- * const jobId = await ep.print(
+ * const { jobId, warnings } = await ep.print(
  *   { printer: 'Office Laser' },
  *   [{ type: 'pixel', format: 'pdf', flavor: 'base64', data: pdfBase64 }],
  * )
  * ```
  */
+/**
+ * Every failure code this client understands.
+ *
+ * Declared as a runtime array first, with the union derived from it — a
+ * hand-written union would be erased at compile time, leaving nothing to
+ * validate a wire value against, and the two would drift the first time the
+ * agent gained a code.
+ *
+ * The first group is the agent's closed set. The second is raised locally and
+ * never sent by the agent. `unknown` is the fallback for a code this client
+ * 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',
+    'unsupported_value', 'unsupported_capability', 'invalid_geometry',
+    'content_overflow', 'unsupported_for_path', 'encrypted_pdf',
+    'printer_not_found', 'print_failed', 'internal_error',
+];
+/**
+ * Raised here, never accepted off the wire.
+ *
+ * Kept separate so `fromWire` can reject them. An agent — or anything between
+ * the client and it — sending `code: "timeout"` would otherwise be taken at
+ * face value, and `retryable` would report `true` for a failure the agent
+ * considers final. `invalid_request` is deliberately *not* in this list: both
+ * sides can raise it, and a request this client refuses to serialise is the
+ * same kind of failure as one the agent refuses to parse.
+ */
+const CLIENT_ONLY_CODES = ['not_connected', 'unreachable', 'connection_closed', 'timeout'];
+const ERROR_CODES = [...AGENT_CODES, ...CLIENT_ONLY_CODES, 'unknown'];
+/** Codes where the same request may succeed if simply tried again. */
+const RETRYABLE = ['unreachable', 'connection_closed', 'timeout'];
+/**
+ * A failure from the Edge Printing agent or from this client.
+ *
+ * Extends `Error`, so `e.message` and `String(e)` keep working for code
+ * written before codes existed.
+ *
+ * **Do not set `name` on this class.** A class name does not set `.name` — it
+ * is inherited as `"Error"` — so `String(e)` stays `"Error: …"`. Setting it
+ * would change that string for every existing consumer, which is exactly what
+ * extending `Error` is here to avoid.
+ */
+export class EdgePrintError extends Error {
+    constructor(code, message, detail = {}) {
+        super(message);
+        this.code = code;
+        this.field = detail.field;
+        this.supported = detail.supported;
+        this.requestId = detail.requestId;
+        this.jobId = detail.jobId;
+    }
+    /**
+     * Builds an error from an agent failure frame.
+     *
+     * Everything is read defensively: an older agent sends no `code` at all, and
+     * a newer one may send a code this client has never heard of. Both become
+     * `'unknown'` rather than reaching a caller as an invalid value.
+     */
+    static fromWire(msg) {
+        const raw = msg['code'];
+        // Checked against the agent's set, not the union: see CLIENT_ONLY_CODES.
+        const code = AGENT_CODES.includes(raw)
+            ? raw
+            : 'unknown';
+        const str = (v) => (typeof v === 'string' && v.length > 0 ? v : undefined);
+        const supported = Array.isArray(msg['supported'])
+            ? msg['supported'].filter((v) => typeof v === 'string')
+            : undefined;
+        return new EdgePrintError(code, str(msg['message']) ?? 'Unknown error', {
+            field: str(msg['field']),
+            supported,
+            requestId: str(msg['id']),
+            jobId: str(msg['jobId']),
+        });
+    }
+    /**
+     * Whether the same request might succeed on a retry.
+     *
+     * True only for transport failures. A validation rejection is deterministic:
+     * retrying it sends the same bad request again.
+     */
+    get retryable() {
+        return RETRYABLE.includes(this.code);
+    }
+}
+/**
+ * The message an `Error` carries, or the value itself stringified.
+ *
+ * `String(err)` on an `Error` yields `"TypeError: foo"`, not `"foo"`. Using it
+ * to build a replacement error would silently prefix every such message with a
+ * constructor name.
+ */
+function messageOf(err) {
+    return err instanceof Error ? err.message : String(err);
+}
 /**
  * The wire protocol this client speaks.
  *
@@ -121,7 +217,7 @@ export class EdgePrintClient {
      * 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
+     * @throws {EdgePrintError} If the agent is unreachable or the token is rejected after
      *   all retries are exhausted.
      *
      * @example
@@ -148,7 +244,7 @@ export class EdgePrintClient {
             // discarding whatever connection was established while it slept, and
             // reconnecting after an explicit disconnect.
             if (this.connectGeneration !== generation) {
-                throw new Error('Connection superseded');
+                throw new EdgePrintError('connection_closed', 'Connection superseded');
             }
             try {
                 await this.openSocket(`wss://${host}:${port}`);
@@ -169,7 +265,7 @@ export class EdgePrintClient {
                     ? ack['protocolVersion']
                     : LEGACY_PROTOCOL_VERSION;
                 if (agentProtocol !== PROTOCOL_VERSION) {
-                    throw new Error(`Protocol version mismatch: this client speaks protocol version ` +
+                    throw new EdgePrintError('protocol_mismatch', `Protocol version mismatch: this client speaks protocol version ` +
                         `${PROTOCOL_VERSION}, but the agent speaks ${agentProtocol}. ` +
                         (agentProtocol < PROTOCOL_VERSION
                             ? 'Update the Edge Printing agent.'
@@ -182,7 +278,7 @@ export class EdgePrintClient {
                 // 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');
+                    throw new EdgePrintError('connection_closed', 'Connection superseded');
                 }
                 // Assigned together so the getters and `isConnected()` agree: either
                 // this attempt owns the connection and publishes all of it, or none.
@@ -199,7 +295,7 @@ export class EdgePrintClient {
                 // is not this attempt's to tear down.
                 if (this.connectGeneration !== generation)
                     throw err;
-                this.discardSocket(new Error('Connection closed'));
+                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
@@ -216,7 +312,7 @@ export class EdgePrintClient {
     /**
      * Return all printers available on the agent machine.
      *
-     * @throws {Error} If not connected.
+     * @throws {EdgePrintError} If not connected.
      *
      * @example
      * ```ts
@@ -234,7 +330,7 @@ export class EdgePrintClient {
      * Cheaper than calling {@link printers} when you only need the default name
      * and no other printer metadata.
      *
-     * @throws {Error} If not connected.
+     * @throws {EdgePrintError} If not connected.
      */
     async defaultPrinter() {
         const resp = await this.request('get_default_printer', {});
@@ -245,10 +341,13 @@ export class EdgePrintClient {
      *
      * @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.
+     * @returns A {@link PrintResult} — the agent's `jobId`, and any `warnings`
+     *   it recorded about a job it printed anyway. `warnings` is empty in the
+     *   common case.
      *
-     * @throws {Error} If not connected, if the agent rejects the job, or if the
-     *   job fails on the way to the spooler.
+     * @throws {EdgePrintError} If not connected, if the agent rejects the job, or
+     *   if the job fails on the way to the spooler. Branch on `err.code`, never
+     *   on the message text.
      *
      * 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
@@ -258,24 +357,31 @@ export class EdgePrintClient {
      * 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:
+     * A job rejected by validation is still recorded, so the thrown error
+     * usually carries a `jobId` matching the entry in the agent's job history —
+     * useful when surfacing a failure someone has to chase. A request refused
+     * before a job existed at all, such as one the agent could not parse, has no
+     * `jobId` to carry.
+     *
+     * A rejection never carries warnings, even where the agent had accumulated
+     * some before the rule that failed: they are dropped deliberately rather
+     * than reported alongside an unrelated failure.
      *
      * ```ts
      * try {
      *   await ep.print(config, data)
      * } catch (err) {
-     *   const jobId = (err as Error & { jobId?: string }).jobId
+     *   if (err instanceof EdgePrintError) console.error(err.code, err.jobId)
      * }
      * ```
      *
      * @example Print a PDF
      * ```ts
-     * const jobId = await ep.print(
+     * const { jobId, warnings } = await ep.print(
      *   { printer: 'Office Laser', copies: 2, duplex: 'long-edge' },
      *   [{ type: 'pixel', format: 'pdf', flavor: 'base64', data: pdfBase64 }],
      * )
+     * for (const w of warnings) console.warn(w.message)
      * ```
      *
      * @example Print a ZPL label
@@ -288,7 +394,9 @@ export class EdgePrintClient {
      */
     async print(config, data) {
         const resp = await this.request('print', { config, data });
-        return resp.jobId;
+        // Defaulted here rather than left optional: a caller destructuring
+        // `warnings` should get an array to iterate, not `undefined` to guard.
+        return { jobId: resp.jobId, warnings: resp.warnings ?? [] };
     }
     /**
      * Close the WebSocket connection and reset client state.
@@ -303,7 +411,7 @@ export class EdgePrintClient {
         // Invalidates any connect still running, so a retry cannot wake up after
         // this and quietly reconnect.
         this.connectGeneration++;
-        this.discardSocket(new Error('Disconnected'));
+        this.discardSocket(new EdgePrintError('connection_closed', 'Disconnected'));
         // Detaching the handlers means the socket's own close never arrives, so
         // without this the loss would go unannounced.
         this.markClosed();
@@ -430,7 +538,7 @@ export class EdgePrintClient {
         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'));
+            this.discardSocket(new EdgePrintError('connection_closed', 'Connection superseded'));
             const ws = new WebSocket(url);
             this.ws = ws;
             this.pendingOpen = reject;
@@ -438,7 +546,7 @@ export class EdgePrintClient {
             ws.onopen = () => { settled(); resolve(); };
             ws.onerror = () => {
                 settled();
-                reject(new Error(`Cannot reach Edge Printing agent at ${url}`));
+                reject(new EdgePrintError('unreachable', `Cannot reach Edge Printing agent at ${url}`));
             };
             ws.onmessage = (ev) => this.handleMessage(String(ev.data));
             ws.onclose = () => {
@@ -448,10 +556,10 @@ export class EdgePrintClient {
                 // cover the open.
                 const openWaiting = this.pendingOpen;
                 settled();
-                openWaiting?.(new Error(`Cannot reach Edge Printing agent at ${url}`));
+                openWaiting?.(new EdgePrintError('unreachable', `Cannot reach Edge Printing agent at ${url}`));
                 this.ws = null;
                 this.clearSessionState();
-                this.rejectPending(new Error('Connection closed'));
+                this.rejectPending(new EdgePrintError('connection_closed', 'Connection closed'));
                 this.markClosed();
             };
         });
@@ -476,17 +584,11 @@ export class EdgePrintClient {
         // 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);
+            // job history. `fromWire` reads that alongside the code, field and
+            // supported values, so the whole failure arrives as one typed object.
+            reject(EdgePrintError.fromWire(msg));
         }
         else {
             resolve(msg);
@@ -495,13 +597,13 @@ export class EdgePrintClient {
     request(type, payload) {
         return new Promise((resolve, reject) => {
             if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
-                reject(new Error('Not connected to Edge Printing agent'));
+                reject(new EdgePrintError('not_connected', 'Not connected to Edge Printing agent'));
                 return;
             }
             const id = crypto.randomUUID();
             const timeout = setTimeout(() => {
                 if (this.pending.delete(id)) {
-                    reject(new Error(`Request "${type}" timed out`));
+                    reject(new EdgePrintError('timeout', `Request "${type}" timed out`, { requestId: id }));
                 }
             }, 30000);
             // Registered once, already wrapped. The previous version inserted the
@@ -515,13 +617,32 @@ export class EdgePrintClient {
                 resolve: (v) => { clearTimeout(timeout); resolve(v); },
                 reject: (e) => { clearTimeout(timeout); reject(e); },
             });
+            // Serialised outside the try below: a payload that cannot be stringified
+            // — a circular reference, a BigInt — is a bad request, not a dead socket,
+            // and labelling it `connection_closed` would make `retryable` true for a
+            // failure that reproduces identically on every retry.
+            let frame;
+            try {
+                frame = JSON.stringify({ type, id, ...payload });
+            }
+            catch (err) {
+                clearTimeout(timeout);
+                this.pending.delete(id);
+                reject(new EdgePrintError('invalid_request', messageOf(err), { requestId: id }));
+                return;
+            }
             try {
-                this.ws.send(JSON.stringify({ type, id, ...payload }));
+                this.ws.send(frame);
             }
             catch (err) {
                 clearTimeout(timeout);
                 this.pending.delete(id);
-                reject(err instanceof Error ? err : new Error(String(err)));
+                // Coded like everything else this client raises, so a caller never has
+                // to ask whether `e.code` exists before reading it. `messageOf` rather
+                // than `String(err)`: the latter prepends the constructor name, so a
+                // caller's `e.message` would gain a "TypeError: " it never had before
+                // codes existed — the one thing extending `Error` is here to preserve.
+                reject(new EdgePrintError('connection_closed', messageOf(err), { requestId: id }));
             }
         });
     }

package/package.json

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