@gohcltech/edge-print-client 0.2.0-dev.6

package/README.md

@@ -0,0 +1,301 @@
+# @gohcltech/edge-print-client
+
+Browser-side WebSocket client for the [Edge Printing](https://github.com/gohcltech/edge-printing) agent. Connects your web app to a locally-installed print agent so users can print PDFs, images, labels, and raw commands to any printer on their machine — without browser print dialogs or plugins.
+
+Intended as a drop-in replacement for qz-tray.js with a simpler token-based auth model.
+
+---
+
+## 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.
+2. **API token** — the user opens the Edge Printing settings window and copies their token. Your app must receive this token (e.g. via your own backend, or by prompting the user to paste it).
+
+---
+
+## Installation
+
+```bash
+npm install @gohcltech/edge-print-client
+# or
+pnpm add @gohcltech/edge-print-client
+```
+
+---
+
+## Quick start
+
+```ts
+import ep from '@gohcltech/edge-print-client'
+
+// 1. Connect and authenticate
+await ep.connect({ token: 'user-api-token-here' })
+
+// 2. List available printers
+const printers = await ep.printers()
+console.log(printers.map(p => p.name))
+
+// 3. Print a PDF (base64-encoded)
+const jobId = await ep.print(
+  { printer: 'Office Laser', copies: 1 },
+  [{ type: 'pixel', format: 'pdf', flavor: 'base64', data: pdfBase64 }],
+)
+console.log('Queued as', jobId)
+
+// 4. Disconnect when done
+ep.disconnect()
+```
+
+---
+
+## API reference
+
+### `connect(options)`
+
+Opens a WebSocket connection to the agent and authenticates. Retries automatically on failure.
+
+```ts
+await ep.connect({
+  host: '127.0.0.1', // default
+  port: 8181,        // default
+  token: 'abc123',   // required — from the agent settings window
+  retries: 3,        // default — additional attempts after the first failure
+  retryDelay: 1000,  // default — ms between retries
+})
+```
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `host` | `string` | `'127.0.0.1'` | Hostname or IP of the agent machine |
+| `port` | `number` | `8181` | Port the agent listens on |
+| `token` | `string` | _(required)_ | API token from the Edge Printing settings window |
+| `retries` | `number` | `3` | Max additional connection attempts after the first failure |
+| `retryDelay` | `number` | `1000` | Ms to wait between retry attempts |
+
+Throws if the agent is unreachable or the token is rejected after all retries.
+
+---
+
+### `printers()`
+
+Returns all printers available on the agent machine.
+
+```ts
+const printers = await ep.printers()
+// [{ name: 'Office Laser', is_default: true, status: 'idle', color: true, ... }]
+```
+
+Each `PrinterInfo` object includes:
+
+| Field | Type | Description |
+|---|---|---|
+| `name` | `string` | OS printer name — use this in `PrintConfig.printer` |
+| `is_default` | `boolean` | `true` if this is the system default |
+| `status` | `string` | `"idle"` \| `"printing"` \| `"offline"` \| `"error"` \| `"paused"` \| `"paper_jam"` \| `"paper_out"` \| `"disabled"` \| `"unknown"` |
+| `driver` | `string?` | Driver name |
+| `port` | `string?` | Port or URI (e.g. `"USB001"`, `"ipp://…"`) |
+| `location` | `string?` | Physical location string from printer properties |
+| `comment` | `string?` | Freeform comment from printer properties |
+| `share_name` | `string?` | Windows share name if the printer is network-shared |
+| `color` | `boolean?` | `true` if the printer supports color output |
+| `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"]`) |
+| `copies_max` | `number?` | Maximum copies the driver accepts in one job |
+| `orientations` | `string[]?` | Supported orientations (e.g. `["portrait", "landscape"]`) |
+
+`TrayInfo`:
+
+| Field | Type | Description |
+|---|---|---|
+| `name` | `string` | Tray name — use this in `PrintConfig.tray` |
+| `papers` | `string[]?` | Paper sizes this tray supports; may be empty if the driver doesn't report per-tray capability — fall back to `PrinterInfo.papers` |
+
+---
+
+### `defaultPrinter()`
+
+Returns the name of the OS default printer. Cheaper than `printers()` when you only need the default.
+
+```ts
+const name = await ep.defaultPrinter() // "Office Laser"
+```
+
+---
+
+### `print(config, data)`
+
+Submits a print job. Returns the job ID assigned by the agent.
+
+```ts
+const jobId = await ep.print(config, data)
+```
+
+**`config`** — `PrintConfig`
+
+| Field | Type | Description |
+|---|---|---|
+| `printer` | `string \| { host, port }` | Printer name from `PrinterInfo.name`, or a remote network address |
+| `copies` | `number?` | Number of copies (default: 1) |
+| `duplex` | `'none' \| 'long-edge' \| 'short-edge'?` | Duplex mode |
+| `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"`) |
+
+**`data`** — `PrintData[]`
+
+Each item in the array is one unit of content (page, label, etc.).
+
+| Field | Type | Description |
+|---|---|---|
+| `type` | `'raw' \| 'pixel'` | `'raw'` — bytes forwarded verbatim (ESC/POS, ZPL, …); `'pixel'` — agent rasterises before printing (PDF, HTML, image) |
+| `format` | `'command' \| 'pdf' \| 'html' \| 'image'` | Content format |
+| `flavor` | `'plain' \| 'base64' \| 'hex' \| 'file'` | How `data` is encoded; `'file'` = absolute path on the agent machine |
+| `data` | `string` | The content, encoded per `flavor` |
+| `options` | `Record<string, unknown>?` | Format-specific options forwarded to the agent renderer |
+
+#### Print examples
+
+```ts
+// PDF from base64
+await ep.print(
+  { printer: 'Office Laser', copies: 2, duplex: 'long-edge' },
+  [{ type: 'pixel', format: 'pdf', flavor: 'base64', data: pdfBase64 }],
+)
+
+// ZPL label (raw command)
+await ep.print(
+  { printer: 'Zebra ZT410' },
+  [{ type: 'raw', format: 'command', flavor: 'plain', data: '^XA^FO50,50^ADN,36,20^FDHello^FS^XZ' }],
+)
+
+// Image file already on the agent machine
+await ep.print(
+  { printer: 'Office Laser', paperSize: 'Letter' },
+  [{ type: 'pixel', format: 'image', flavor: 'file', data: 'C:\\Reports\\invoice.png' }],
+)
+```
+
+---
+
+### `disconnect()`
+
+Closes the connection. Any in-flight requests are rejected. Safe to call when already disconnected.
+
+```ts
+ep.disconnect()
+```
+
+---
+
+### `isConnected()`
+
+Returns `true` when the WebSocket is open and authenticated.
+
+```ts
+if (!ep.isConnected()) {
+  await ep.connect({ token })
+}
+```
+
+---
+
+### `onClose(fn)`
+
+Registers a callback that fires whenever the connection closes — network drop, agent restart, or an explicit `disconnect()` call. Multiple listeners are supported.
+
+```ts
+ep.onClose(() => {
+  console.warn('Connection lost — reconnecting…')
+  reconnect()
+})
+```
+
+---
+
+## 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:
+
+```ts
+import { EdgePrintClient } from '@gohcltech/edge-print-client'
+
+const officeAgent = new EdgePrintClient()
+const warehouseAgent = new EdgePrintClient()
+
+await officeAgent.connect({ token: officeToken })
+await warehouseAgent.connect({ host: '192.168.1.50', token: warehouseToken })
+```
+
+---
+
+## Reconnect pattern
+
+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'
+
+async function connectWithBackoff(opts: ConnectOptions, maxMs = 30_000) {
+  let delay = 1_000
+  while (true) {
+    try {
+      await ep.connect(opts)
+      return
+    } catch {
+      await new Promise(r => setTimeout(r, delay))
+      delay = Math.min(delay * 2, maxMs)
+    }
+  }
+}
+
+ep.onClose(() => connectWithBackoff({ token: storedToken }))
+await connectWithBackoff({ token: storedToken })
+```
+
+---
+
+## Troubleshooting
+
+### Browser blocks the WebSocket connection (`net::ERR_CERT_AUTHORITY_INVALID`)
+
+The agent uses `wss://` (TLS) so it works from HTTPS pages. Its certificate is
+self-signed and must be trusted by the OS before the browser will allow the
+connection.
+
+**This is handled automatically by the Edge Printing installer.** If a user
+sees this error it almost always means one of the following:
+
+| Cause | Fix |
+|---|---|
+| Agent was not installed with administrator rights | Re-run the installer as an administrator |
+| OS certificate store was updated and the trust was removed | Re-run the installer to re-register the certificate |
+| Corporate policy blocks user-trusted certificates | Ask IT to trust the certificate via Group Policy, or whitelist `127.0.0.1:8181` |
+| macOS Keychain prompt was dismissed without clicking "Always Allow" | Open Keychain Access, find the **Edge Printing** certificate, and set trust to **Always Trust** |
+
+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"
+
+- 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
+
+The token was rejected. Generate a new one from the Edge Printing settings window.
+
+### Requests time out after 30 seconds
+
+The agent accepted the connection but stopped responding. Restart the agent. If
+the problem persists, file an issue with the agent log attached.
+
+---
+
+## License
+
+MIT © GOH Clinical Technology

package/dist/edge-print.d.ts

@@ -0,0 +1,367 @@
+/**
+ * @module edge-print
+ *
+ * Browser-side WebSocket client for the Edge Printing agent.
+ * Drop-in replacement for qz-tray.js with a simpler token-based auth model.
+ *
+ * @example
+ * ```ts
+ * import ep from '@gohcltech/edge-print-client'
+ *
+ * await ep.connect({ token: 'your-api-token' })
+ * const printers = await ep.printers()
+ * const jobId = await ep.print(
+ *   { printer: 'Office Laser' },
+ *   [{ type: 'pixel', format: 'pdf', flavor: 'base64', data: pdfBase64 }],
+ * )
+ * ```
+ */
+/**
+ * Identifies the target printer.
+ *
+ * - Pass a `string` to use a printer by its OS name (e.g. `"Office Laser"`).
+ * - Pass `{ host, port }` to route to a network printer by address.
+ */
+export type PrinterTarget = string | {
+    host: string;
+    port: number;
+};
+/**
+ * Configuration options for a print job.
+ *
+ * All fields except `printer` are optional; omitted fields use the printer's
+ * own defaults.
+ */
+export interface PrintConfig {
+    /** Target printer — OS name string or remote `{ host, port }` object. */
+    printer: PrinterTarget;
+    /** Number of copies to print (default: 1). */
+    copies?: number;
+    /**
+     * Duplex (double-sided) mode.
+     * - `'none'` — single-sided
+     * - `'long-edge'` — flip on the long edge (standard book binding)
+     * - `'short-edge'` — flip on the short edge (calendar binding)
+     */
+    duplex?: 'none' | 'long-edge' | 'short-edge';
+    /** Page orientation (default: determined by document content). */
+    orientation?: 'portrait' | 'landscape';
+    /** Human-readable name shown in the OS print queue. */
+    jobName?: string;
+    /**
+     * Color output mode.
+     * - `'color'` — full color
+     * - `'grayscale'` — color converted to gray
+     * - `'black-white'` — pure monochrome (fastest on mono printers)
+     */
+    colorType?: 'color' | 'grayscale' | 'black-white';
+    /**
+     * Paper size, exactly as returned by {@link PrinterInfo.papers}
+     * (e.g. `"Letter"`, `"A4"`). Omit to use the printer's current default.
+     */
+    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.
+     */
+    tray?: string;
+}
+/**
+ * A single unit of content to be printed.
+ *
+ * Pass an array of `PrintData` to {@link EdgePrintClient.print} — each item
+ * maps to one page or label in the job.
+ *
+ * @example PDF from a base64 string
+ * ```ts
+ * const page: PrintData = {
+ *   type: 'pixel',
+ *   format: 'pdf',
+ *   flavor: 'base64',
+ *   data: '<base64-encoded PDF>',
+ * }
+ * ```
+ *
+ * @example ZPL label (raw command)
+ * ```ts
+ * const label: PrintData = {
+ *   type: 'raw',
+ *   format: 'command',
+ *   flavor: 'plain',
+ *   data: '^XA^FO50,50^ADN,36,20^FDHello^FS^XZ',
+ * }
+ * ```
+ */
+export interface PrintData {
+    /**
+     * Rendering pipeline.
+     * - `'raw'` — bytes are forwarded to the printer verbatim (ESC/POS, ZPL, EPL, …)
+     * - `'pixel'` — the agent rasterises the content before printing (PDF, HTML, image)
+     */
+    type: 'raw' | 'pixel';
+    /**
+     * Content format.
+     * - `'command'` — raw printer command language
+     * - `'pdf'` — Portable Document Format
+     * - `'html'` — HTML markup (agent renders to pixels)
+     * - `'image'` — raster image (PNG, JPEG, …)
+     */
+    format: 'command' | 'pdf' | 'html' | 'image';
+    /**
+     * How `data` is encoded.
+     * - `'plain'` — UTF-8 text
+     * - `'base64'` — Base64-encoded binary
+     * - `'hex'` — hex-encoded binary
+     * - `'file'` — absolute file path on the agent machine (agent reads the file)
+     */
+    flavor: 'plain' | 'base64' | 'hex' | 'file';
+    /** The content, encoded according to `flavor`. */
+    data: string;
+    /** Format-specific extra options forwarded to the agent renderer. */
+    options?: Record<string, unknown>;
+}
+/**
+ * An input tray/bin reported by the printer driver.
+ *
+ * Returned inside {@link PrinterInfo.trays}.
+ */
+export interface TrayInfo {
+    /** Tray name exactly as the driver reports it (e.g. `"Tray 1"`, `"Auto"`). */
+    name: string;
+    /**
+     * Paper sizes this tray can hold, when the driver reports per-tray
+     * capability. Empty when the driver does not distinguish by tray —
+     * fall back to {@link PrinterInfo.papers} in that case.
+     */
+    papers?: string[];
+}
+/**
+ * Metadata about a printer available on the agent machine.
+ *
+ * Returned by {@link EdgePrintClient.printers}.
+ * Use {@link name} as the value for {@link PrintConfig.printer}.
+ */
+export interface PrinterInfo {
+    /** OS-assigned printer name. Pass this to {@link PrintConfig.printer}. */
+    name: string;
+    /** `true` if this is the system default printer. */
+    is_default: boolean;
+    /**
+     * Current printer status reported by the OS.
+     *
+     * Possible values: `"idle"` | `"printing"` | `"offline"` | `"error"` |
+     * `"paused"` | `"paper_jam"` | `"paper_out"` | `"disabled"` | `"unknown"`
+     */
+    status: string;
+    /** Driver name as reported by the OS (present when available). */
+    driver?: string;
+    /** Port or URI the printer is connected on (e.g. `"USB001"`, `"ipp://…"`). */
+    port?: string;
+    /** Physical location string set in the printer properties. */
+    location?: string;
+    /** Freeform comment from the printer properties. */
+    comment?: string;
+    /** Windows share name, if the printer is shared on the network. */
+    share_name?: string;
+    /** `true` if the printer supports color output. */
+    color?: boolean;
+    /** `true` if the printer supports duplex (double-sided) printing. */
+    duplex?: boolean;
+    /**
+     * Input trays available on this printer.
+     * Pass a {@link TrayInfo.name} value to {@link PrintConfig.tray}.
+     */
+    trays?: TrayInfo[];
+    /**
+     * All paper sizes the printer supports, regardless of tray.
+     * Pass one of these values to {@link PrintConfig.paperSize}.
+     */
+    papers?: string[];
+    /** Maximum number of copies the driver accepts in a single job. */
+    copies_max?: number;
+    /** Page orientations the driver supports (e.g. `["portrait", "landscape"]`). */
+    orientations?: string[];
+    /**
+     * `true` for Developer (virtual) printers — injected by the agent when
+     * Developer Printers mode is enabled in Settings. These printers capture
+     * jobs to disk or render a ZPL preview rather than sending to physical hardware.
+     */
+    virtual?: boolean;
+}
+/**
+ * Options passed to {@link EdgePrintClient.connect}.
+ */
+export interface ConnectOptions {
+    /**
+     * Hostname or IP of the machine running the Edge Printing agent.
+     * @default '127.0.0.1'
+     */
+    host?: string;
+    /**
+     * Port the agent is listening on.
+     * @default 8181
+     */
+    port?: number;
+    /**
+     * API token shown in the Edge Printing settings window.
+     * Every WebSocket session must authenticate with this token before
+     * any other requests are accepted.
+     */
+    token: string;
+    /**
+     * Maximum number of additional connection attempts after the first failure.
+     * @default 3
+     */
+    retries?: number;
+    /**
+     * Milliseconds to wait between retry attempts.
+     * @default 1000
+     */
+    retryDelay?: number;
+}
+/**
+ * WebSocket client for the Edge Printing agent.
+ *
+ * Each instance manages a single persistent connection. For most applications
+ * the exported {@link ep} singleton is sufficient; create additional instances
+ * only when you need concurrent connections to different agents.
+ *
+ * ### Lifecycle
+ * ```
+ * connect() → printers() / print() / … → disconnect()
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { EdgePrintClient } from '@gohcltech/edge-print-client'
+ *
+ * const client = new EdgePrintClient()
+ * await client.connect({ token: 'abc123' })
+ * ```
+ */
+export declare class EdgePrintClient {
+    private ws;
+    private pending;
+    private authenticated;
+    private closeListeners;
+    /**
+     * Open a WebSocket connection to the Edge Printing agent and authenticate.
+     *
+     * 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.
+     *
+     * @throws {Error} If the agent is unreachable or the token is rejected after
+     *   all retries are exhausted.
+     *
+     * @example
+     * ```ts
+     * await ep.connect({
+     *   host: '127.0.0.1',
+     *   port: 8181,
+     *   token: 'abc123',
+     *   retries: 5,
+     *   retryDelay: 2000,
+     * })
+     * ```
+     */
+    connect(options: ConnectOptions): Promise<void>;
+    /**
+     * Return all printers available on the agent machine.
+     *
+     * @throws {Error} If not connected.
+     *
+     * @example
+     * ```ts
+     * const printers = await ep.printers()
+     * const colorPrinters = printers.filter(p => p.color)
+     * ```
+     */
+    printers(): Promise<PrinterInfo[]>;
+    /**
+     * Return the name of the OS default printer.
+     *
+     * Cheaper than calling {@link printers} when you only need the default name
+     * and no other printer metadata.
+     *
+     * @throws {Error} If not connected.
+     */
+    defaultPrinter(): Promise<string>;
+    /**
+     * Submit a print job to the agent.
+     *
+     * @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.
+     *
+     * @throws {Error} If not connected, or if the agent rejects the job.
+     *
+     * @example Print a PDF
+     * ```ts
+     * const jobId = await ep.print(
+     *   { printer: 'Office Laser', copies: 2, duplex: 'long-edge' },
+     *   [{ type: 'pixel', format: 'pdf', flavor: 'base64', data: pdfBase64 }],
+     * )
+     * ```
+     *
+     * @example Print a ZPL label
+     * ```ts
+     * await ep.print(
+     *   { printer: 'Zebra ZT410' },
+     *   [{ type: 'raw', format: 'command', flavor: 'plain', data: zplString }],
+     * )
+     * ```
+     */
+    print(config: PrintConfig, data: PrintData[]): Promise<string>;
+    /**
+     * Close the WebSocket connection and reset client state.
+     *
+     * Any in-flight requests are rejected. Safe to call when already
+     * disconnected.
+     */
+    disconnect(): void;
+    /**
+     * `true` when the WebSocket is open and the session is authenticated.
+     *
+     * Use this to guard print calls in components that may render before the
+     * connection is established.
+     */
+    isConnected(): boolean;
+    /**
+     * Register a callback invoked whenever the connection closes — whether from
+     * a network drop, an agent restart, or an explicit {@link disconnect} call.
+     *
+     * Multiple listeners can be registered; all are called in registration order.
+     *
+     * @example
+     * ```ts
+     * ep.onClose(() => {
+     *   console.warn('Lost connection to Edge Printing agent — reconnecting…')
+     *   reconnect()
+     * })
+     * ```
+     */
+    onClose(fn: () => void): void;
+    private openSocket;
+    private handleMessage;
+    private request;
+    private rejectPending;
+}
+/**
+ * Shared singleton `EdgePrintClient` instance.
+ *
+ * Suitable for most single-page applications. Call {@link EdgePrintClient.connect}
+ * once at app startup, then use `ep` from any module without passing the
+ * client around.
+ *
+ * @example
+ * ```ts
+ * import ep from '@gohcltech/edge-print-client'
+ *
+ * await ep.connect({ token: 'abc123' })
+ * await ep.print({ printer: 'Office Laser' }, [pdfData])
+ * ```
+ */
+export declare const ep: EdgePrintClient;
+export default ep;