@gohcltech/edge-print-client 2.0.61-develop → 2.0.71-develop

package/README.md

@@ -119,10 +119,38 @@ 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 `paperSize`, `tray` and `mediaType`.** A value the printer does not
+recognise now rejects the job rather than printing on the driver's default —
+the substitution this release exists to remove. Three things soften it:
+
+- **Only when the printer actually said.** If `papers`, `trays` or `mediaTypes`
+  is absent, the agent could not determine that capability and accepts whatever
+  you ask, with a `capability_unverified` warning on the response. Many printers
+  report nothing at all, so this is the common case.
+- **Matching ignores case.** `"letter"` is accepted for `"Letter"`.
+- **The rejection tells you what would work.** `unsupported_value` carries
+  `field` and a `supported` array of the printer's real values.
+
+`paperSize` and `tray` are only checked on paths that can apply them; `raw`,
+`html` and network targets never did, so they are left alone rather than
+starting to fail.
+
+**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.**
@@ -221,8 +249,9 @@ Two limits worth knowing before you build on this:
 | `orientation` | `'portrait' \| 'landscape'?` | Page orientation |
 | `jobName` | `string?` | Name shown in the OS print queue |
 | `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"`) |
+| `paperSize` | `string?` | Paper size from `PrinterInfo.papers` (e.g. `"Letter"`). Rejects if the printer lists paper sizes and this is not one — see below |
+| `tray` | `string?` | Tray name from `TrayInfo.name` (e.g. `"Tray 1"`). Rejects if the printer lists trays and this is not one — see below |
+| `mediaType` | `string?` | Stock type from `PrinterInfo.mediaTypes` (e.g. `"Bond"`). Rejected for `raw`/`html` content and network targets |
 
 **`data`** — `PrintData[]`
 
@@ -407,11 +436,14 @@ 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.
+`unsupported_value` is raised when `paperSize`, `tray` or `mediaType` names a
+value the printer does not list, and it is the one code that populates
+`supported` — read that array rather than parsing the message, and offer the
+values it names.
+
+Two more are still **reserved**: `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.
 
 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

package/dist/edge-print.d.ts

@@ -58,14 +58,34 @@ export interface PrintConfig {
     /**
      * Paper size, exactly as returned by {@link PrinterInfo.papers}
      * (e.g. `"Letter"`, `"A4"`). Omit to use the printer's current default.
+     *
+     * Rejects with `unsupported_value` when the printer lists paper sizes and
+     * this is not one of them — the error's `supported` array names the real
+     * ones. A printer that lists none accepts anything, with a
+     * `capability_unverified` warning. Matching ignores case.
      */
     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.
+     *
+     * Rejects with `unsupported_value` when the printer lists trays and this is
+     * not one of them — the error's `supported` array names the real ones. A
+     * printer that lists none accepts anything, with a `capability_unverified`
+     * warning. Matching ignores case.
      */
     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 +198,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"]`). */

package/package.json

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