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

package/README.md

@@ -6,6 +6,10 @@ Intended as a drop-in replacement for qz-tray.js with a simpler token-based auth
 
 ---
 
+> **Upgrading from 1.x?** See [MIGRATING.md](../MIGRATING.md). `print()`'s
+> return type changed, printed output changes on both platforms, and the
+> `virtual` field you may be filtering on never worked.
+
 ## Prerequisites
 
 1. **Edge Printing agent** must be installed and running on the user's machine. The agent listens on `wss://127.0.0.1:8181` by default.
@@ -136,9 +140,11 @@ the substitution this release exists to remove. Three things soften it:
 - **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.
+`paperSize` and `tray` are only *validated* on paths that can act on them, so
+`raw` and `html` content and network targets do not start failing. Validated is
+not the same as unused: on macOS both settings are still passed to CUPS as
+`media=` and `InputSlot=` for raw and HTML jobs, as they were in 1.x. On
+Windows those paths genuinely do discard them.
 
 **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
@@ -192,10 +198,13 @@ const { jobId, warnings } = await ep.print(config, data)
 | `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.
+Each `JobWarning` is `{ code, message }`. Two codes are raised today:
+`capability_unverified`, where the agent could not determine a capability so it
+skipped the check and passed the request through, and `content_scaled_to_fit`,
+where content that did not fit was scaled down rather than clipped. What it had
+to fit is the sheet when you sent no `margins` and the margin box when you did,
+so content well inside the sheet can still warn. 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(…)`),
@@ -249,9 +258,13 @@ 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"`). 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 |
+| `paperSize` | `string?` | Paper size from `PrinterInfo.papers` (e.g. `"Letter"`). Rejects with `unsupported_value` if the printer lists paper sizes and this is not one |
+| `tray` | `string?` | Tray name from `TrayInfo.name` (e.g. `"Tray 1"`). Rejects with `unsupported_value` if the printer lists trays and this is not one |
+| `mediaType` | `string?` | Stock type from `PrinterInfo.mediaTypes` (e.g. `"Bond"`). Rejects with `unsupported_value` if the printer lists stock types and this is not one; rejected for `raw`/`html` content and network targets |
+| `scaling` | `'actual' \| 'fit' \| 'shrink-to-fit'?` | How content is sized against the media. **Default `'actual'`** — see below |
+| `scalePercent` | `number?` | Explicit scale, 10–400. Overrides `scaling` when both are sent |
+| `margins` | `Margins?` | Inset from the physical sheet edge. `{ top?, right?, bottom?, left?, units }`, `units` required |
+| `anchor` | `'center' \| 'top-left'?` | Where content sits in the margin box. Default `'center'` |
 
 **`data`** — `PrintData[]`
 
@@ -265,6 +278,102 @@ Each item in the array is one unit of content (page, label, etc.).
 | `data` | `string` | The content, encoded per `flavor` |
 | `options` | `Record<string, unknown>?` | Format-specific options forwarded to the agent renderer |
 
+#### Scaling, margins and anchoring
+
+These four settings control where content lands on the sheet. They apply to
+`pdf` and `image` content sent to a named printer.
+
+**The default is actual size.** Content prints at its intrinsic size, centred,
+with no scaling applied:
+
+```ts
+// A 4x6 label prints 4x6, wherever the sheet is bigger.
+await ep.print({ printer: 'Office Laser' }, [label])
+```
+
+**This changed in 2.0, and it changes output.** Windows previously stretched
+every page to fill the printable area and had no actual-size path at all. If a
+job depended on that stretch, the nearest equivalent is:
+
+```ts
+await ep.print({ printer: 'Office Laser', scaling: 'fit' }, [doc])
+```
+
+`'fit'` scales to fill the margin box **preserving aspect ratio**, which the
+old Windows path did not — it stretched to fill the printable area regardless
+of shape. Any unprintable band changes that area's proportions, an even band as
+much as an uneven one, so even a document matching its media is slightly
+letterboxed under `'fit'` where it used to be stretched to fill exactly.
+`'shrink-to-fit'` is actual size that scales down only when content overflows —
+it never scales up.
+
+**Margins are measured from the physical sheet edge**, not from the printable
+area, so the same numbers mean the same place on paper across printers whose
+unprintable bands differ. Import `inches` or `mm` rather than converting by
+hand:
+
+```ts
+import { inches, mm } from '@gohcltech/edge-print-client'
+
+await ep.print(
+  { printer: 'Office Laser', margins: inches({ top: 0.5, right: 0.5, bottom: 0.5, left: 0.5 }) },
+  [doc],
+)
+```
+
+`units` is required — there is no safe default. A value meant as inches and
+read as points is a near-invisible 1/72" margin.
+
+**Set all four edges.** An omitted edge is a deliberate zero, not "leave this
+one alone" — and zero is below the unprintable band on most real printers, so a
+partial object is usually *rejected*:
+
+```ts
+// Rejected on any printer with a hardware margin:
+//   invalid_geometry — margins.right 0.00pt is below the hardware minimum
+//   18.00pt (0.25in) for 'Office Laser'
+await ep.print({ printer: 'Office Laser', margins: inches({ top: 0.5 }) }, [doc])
+```
+
+Sending no `margins` key at all is different again, and always fine — it means
+no margin control rather than four zero margins.
+
+An explicit `scalePercent` (10–400) **silently overrides** `scaling` when both
+are sent. It also changes how overflow is treated: content that does not fit
+rejects with `content_overflow` under an explicit `scalePercent`, where without
+one it is scaled down and reports a `content_scaled_to_fit` warning instead.
+
+What "does not fit" is measured against depends on whether you sent `margins`.
+With them, it is the margin box. Without, it is the whole physical sheet —
+because with no margins the box is the hardware printable area, which an
+ordinary Letter page on a Letter queue already exceeds on any printer with an
+unprintable edge.
+
+**Where these are refused rather than ignored.** A setting that provably cannot
+work on the requested path is rejected, because silently dropping it is the
+failure this release exists to remove:
+
+| Situation | Code |
+|---|---|
+| `raw` or `html` content, or a network target | `unsupported_for_path` |
+| The PDF is encrypted (its pages cannot be re-composed) | `encrypted_pdf` |
+| `scalePercent` outside 10–400 | `invalid_geometry`, `field: 'scalePercent'` |
+| A negative margin edge | `invalid_geometry`, `field: 'margins.top'` etc. |
+| A margin inside the printer's unprintable band | `invalid_geometry`, naming the hardware minimum |
+
+**All of this needs a measurable sheet.** Margins are placed from the sheet
+edge, the hardware minimum is checked against the unprintable band, and
+overflow is judged against the sheet — so the agent has to ask the queue for
+its geometry. Windows reads it locally; macOS asks over IPP, and a queue that
+will not answer yields nothing. The placement rules are then skipped and the
+document goes to the printer as supplied, logged by the agent but carrying no
+warning on the job.
+
+Developer Printers skip the *path* checks above, since their job is to show
+what was asked for. They are not exempt from the rules that need no printer: an
+encrypted PDF, an out-of-range `scalePercent` and a negative margin edge all
+still reject.
+
 #### Image sizing
 
 An image prints at its **intrinsic physical size**, taken from the resolution
@@ -276,10 +385,14 @@ resolution metadata prints at 12.5 x 6.25 inches rather than being sized to the
 paper. Send a file that declares its resolution if you need a specific size.
 
 An image too large for the sheet is scaled down to fit and the job reports a
-`content_scaled_to_fit` warning; nothing is silently cropped.
-
-This describes Windows. On macOS the image is handed to the system print
-system, which fits it to the page instead — the two converge in a later release.
+`content_scaled_to_fit` warning, so nothing is silently cropped — **as long as
+the agent could measure the sheet.** That means asking the queue for its
+geometry, which Windows reads locally and macOS asks for over IPP. A macOS
+queue that will not answer skips the overflow rule along with the margin rules,
+and an oversized image is clipped instead, with no warning on the job because
+nothing was decided. Worth knowing on macOS specifically: CUPS used to fit an
+image to the page by itself, and does not do that for a PDF, which is what an
+image becomes on the way to the spooler in 2.0.
 
 #### Print examples
 
@@ -301,6 +414,18 @@ await ep.print(
   { printer: 'Office Laser', paperSize: 'Letter' },
   [{ type: 'pixel', format: 'image', flavor: 'file', data: 'C:\\Reports\\invoice.png' }],
 )
+
+// Actual size, half-inch margins, anchored top-left, on card stock
+await ep.print(
+  {
+    printer: 'Office Laser',
+    scaling: 'actual',
+    margins: inches({ top: 0.5, right: 0.5, bottom: 0.5, left: 0.5 }),
+    anchor: 'top-left',
+    mediaType: 'Bond',
+  },
+  [{ type: 'pixel', format: 'pdf', flavor: 'base64', data: pdfBase64 }],
+)
 ```
 
 ---
@@ -427,11 +552,14 @@ Sent by the agent:
 | `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_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 |
 | `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 |
+| `unsupported_for_path` | Geometry or `mediaType` on a path that cannot honour it — `field` is `mediaType`, absent for geometry |
+| `content_overflow` | Content exceeds the margin box under an explicit `scalePercent` |
+| `encrypted_pdf` | Scaling, margins or anchoring were asked for on an encrypted PDF |
+| `printer_not_found` | `defaultPrinter()` found no default configured on the machine. **Not** raised for a `print()` to a missing printer — see below |
+| `print_failed` | The backend failed after the job was accepted and recorded — including a `printer` naming a queue that no longer exists |
 | `internal_error` | The agent itself failed — not the caller's doing |
 
 Raised locally by this library, never sent by the agent:
@@ -448,19 +576,25 @@ Raised locally by this library, never sent by the agent:
 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.
+Four of those five — `not_connected`, `unreachable`, `connection_closed` and
+`timeout` — 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. `protocol_mismatch` is the exception: it
+belongs to the agent's own set and would be accepted off the wire, but nothing
+in the agent raises it, so in practice it only ever comes from here.
+
+**A print to a printer that no longer exists arrives as `print_failed`, not
+`printer_not_found`.** Neither platform backend can separate a missing queue
+from any other spooling failure, so an app that caches printer names cannot
+detect a stale one by code alone — `printer_not_found` covers only the
+`defaultPrinter()` lookup. Re-read `printers()` when a `print_failed` looks
+like it might be a vanished queue.
 
 `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
 unfamiliar code as a plain failure rather than a bug.
@@ -499,7 +633,7 @@ The client does not reconnect automatically after a connection drop. A simple
 exponential-backoff reconnect loop:
 
 ```ts
-import ep, { ConnectOptions } from '@gohcltech/edge-print-client'
+import ep, { type ConnectOptions } from '@gohcltech/edge-print-client'
 
 async function connectWithBackoff(opts: ConnectOptions, maxMs = 30_000) {
   let delay = 1_000

package/dist/edge-print.d.ts

@@ -26,6 +26,61 @@ export type PrinterTarget = string | {
     host: string;
     port: number;
 };
+/**
+ * How content is sized relative to the media.
+ *
+ * - `'actual'` — the document's intrinsic size, 1:1. The default.
+ * - `'fit'` — scaled to fill the margin box, preserving aspect ratio.
+ * - `'shrink-to-fit'` — actual size, scaled down only when content overflows.
+ */
+export type ScalingMode = 'actual' | 'fit' | 'shrink-to-fit';
+/**
+ * Where content sits inside the margin box when it does not fill it.
+ * Defaults to `'center'`.
+ */
+export type ContentAnchor = 'center' | 'top-left';
+/** The unit a {@link Margins} value is expressed in. */
+export type MarginUnits = 'pt' | 'in' | 'mm';
+/**
+ * Margins measured inward from the **physical sheet edge** — not from the
+ * printable area, so the same numbers describe the same place on paper
+ * whatever unprintable band a given printer has.
+ *
+ * Every edge is optional, but **set all four in practice.** An omitted edge is
+ * a deliberate zero rather than "leave this one alone", and zero falls inside
+ * the unprintable band on most real printers — so a partial object is usually
+ * rejected with `invalid_geometry` naming an edge you never set. Omitting the
+ * whole `margins` key is different, and always fine: it means no margin
+ * control at all.
+ *
+ * Each edge must be zero or greater, or the job rejects with
+ * `invalid_geometry` naming it — `margins.top`, `margins.right`,
+ * `margins.bottom`, `margins.left`. A margin inside the printer's unprintable
+ * band is refused with the same code, naming both the requested value and the
+ * hardware minimum.
+ *
+ * `units` is required here. There is no safe default: a value meant as inches
+ * and read as points is a near-invisible ~1/72" margin. Use {@link inches} or
+ * {@link mm} to say it once. (The agent itself defaults to points when a
+ * hand-rolled client omits the field; this type declines to rely on that.)
+ *
+ * @example
+ * ```ts
+ * const margins = inches({ top: 0.5, right: 0.5, bottom: 0.5, left: 0.5 })
+ * await ep.print({ printer: 'Office Laser', margins }, data)
+ * ```
+ */
+export interface Margins {
+    top?: number;
+    right?: number;
+    bottom?: number;
+    left?: number;
+    units: MarginUnits;
+}
+/** Builds {@link Margins} in millimetres. */
+export declare const mm: (m: Omit<Margins, "units">) => Margins;
+/** Builds {@link Margins} in inches. */
+export declare const inches: (m: Omit<Margins, "units">) => Margins;
 /**
  * Configuration options for a print job.
  *
@@ -81,11 +136,59 @@ export interface PrintConfig {
      * (e.g. `"Plain"`, `"Bond"`, `"Thermal"`). Changes how the printer feeds and
      * fuses the page. Omit to use the printer's current default.
      *
+     * Rejects with `unsupported_value` when the printer lists stock types 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.
+     *
      * 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`.
+     * `unsupported_for_path` and a `field` of `mediaType`.
      */
     mediaType?: string;
+    /**
+     * How content is sized relative to the media. Defaults to `'actual'`.
+     *
+     * **This default changed in 2.0.** Windows previously stretched every page
+     * to fill the printable area and had no actual-size path at all; a job that
+     * relied on that stretch needs `scaling: 'fit'` to keep it.
+     *
+     * `scaling`, {@link PrintConfig.scalePercent}, {@link PrintConfig.margins}
+     * and {@link PrintConfig.anchor} are refused rather than silently dropped on
+     * paths that cannot honour them: `raw` or `html` content, and network
+     * targets, all reject with `unsupported_for_path`. Asking for any of them on
+     * an encrypted PDF rejects with `encrypted_pdf`, since honouring them means
+     * re-composing pages the agent cannot open. Developer Printers skip the path
+     * check only — the encrypted-PDF and range rules still apply to them.
+     */
+    scaling?: ScalingMode;
+    /**
+     * Explicit scale percentage, 10–400 inclusive. Outside that range rejects
+     * with `invalid_geometry` and a `field` of `scalePercent`.
+     *
+     * **Overrides {@link PrintConfig.scaling} when both are present**, silently
+     * rather than erroring.
+     *
+     * It also changes what happens to oversized content. Content that does not
+     * fit rejects with `content_overflow` under an explicit `scalePercent`;
+     * without one, it is scaled down and the job reports a
+     * `content_scaled_to_fit` warning instead of failing.
+     *
+     * What it must fit depends on {@link PrintConfig.margins}: the margin box
+     * when margins were sent, the whole physical sheet when they were not.
+     */
+    scalePercent?: number;
+    /**
+     * Margins measured inward from the physical sheet edge. Omit entirely for no
+     * margin control; present with an edge omitted makes that edge a deliberate
+     * zero.
+     */
+    margins?: Margins;
+    /**
+     * Where content sits inside the margin box when it does not fill it.
+     * Defaults to `'center'`.
+     */
+    anchor?: ContentAnchor;
 }
 /**
  * A single unit of content to be printed.
@@ -136,10 +239,6 @@ export interface PrintData {
      *
      * An image too large for the sheet is scaled down to fit, and the job
      * reports a `content_scaled_to_fit` warning.
-     *
-     * This applies on Windows. On macOS the image is handed to the system print
-     * system, which fits it to the page instead; the two converge in a later
-     * release.
      */
     format: 'command' | 'pdf' | 'html' | 'image';
     /**

package/dist/edge-print.js

@@ -16,6 +16,10 @@
  * )
  * ```
  */
+/** Builds {@link Margins} in millimetres. */
+export const mm = (m) => ({ ...m, units: 'mm' });
+/** Builds {@link Margins} in inches. */
+export const inches = (m) => ({ ...m, units: 'in' });
 /**
  * Every failure code this client understands.
  *

package/package.json

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