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

package/src/edge-print.ts

@@ -0,0 +1,484 @@
+/**
+ * @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
+}
+
+type Pending = { resolve: (v: unknown) => void; reject: (e: Error) => void }
+
+/**
+ * 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 class EdgePrintClient {
+  private ws: WebSocket | null = null
+  private pending = new Map<string, Pending>()
+  private authenticated = false
+  private closeListeners: Array<() => void> = []
+
+  /**
+   * 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,
+   * })
+   * ```
+   */
+  async connect(options: ConnectOptions): Promise<void> {
+    const {
+      host = '127.0.0.1',
+      port = 8181,
+      token,
+      retries = 3,
+      retryDelay = 1000,
+    } = options
+
+    for (let attempt = 0; attempt <= retries; attempt++) {
+      try {
+        await this.openSocket(`wss://${host}:${port}`)
+        await this.request('auth', { token })
+        this.authenticated = true
+        return
+      } catch (err) {
+        if (attempt === retries) throw err
+        await sleep(retryDelay)
+      }
+    }
+  }
+
+  /**
+   * 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)
+   * ```
+   */
+  async printers(): Promise<PrinterInfo[]> {
+    const resp = await this.request('get_printers', {}) as { printers: PrinterInfo[] }
+    return resp.printers
+  }
+
+  /**
+   * 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.
+   */
+  async defaultPrinter(): Promise<string> {
+    const resp = await this.request('get_default_printer', {}) as { name: string }
+    return resp.name
+  }
+
+  /**
+   * 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 }],
+   * )
+   * ```
+   */
+  async print(config: PrintConfig, data: PrintData[]): Promise<string> {
+    const resp = await this.request('print', { config, data }) as { job_id: string }
+    return resp.job_id
+  }
+
+  /**
+   * Close the WebSocket connection and reset client state.
+   *
+   * Any in-flight requests are rejected. Safe to call when already
+   * disconnected.
+   */
+  disconnect(): void {
+    this.ws?.close()
+    this.ws = null
+    this.authenticated = false
+  }
+
+  /**
+   * `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 {
+    return this.ws?.readyState === WebSocket.OPEN && this.authenticated
+  }
+
+  /**
+   * 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 {
+    this.closeListeners.push(fn)
+  }
+
+  // ── internals ────────────────────────────────────────────────────────────
+
+  private openSocket(url: string): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const ws = new WebSocket(url)
+      ws.onopen = () => { this.ws = ws; resolve() }
+      ws.onerror = () => reject(new Error(`Cannot reach Edge Printing agent at ${url}`))
+      ws.onmessage = (ev) => this.handleMessage(String(ev.data))
+      ws.onclose = () => {
+        this.ws = null
+        this.authenticated = false
+        this.rejectPending(new Error('Connection closed'))
+        this.closeListeners.forEach(fn => fn())
+      }
+    })
+  }
+
+  private handleMessage(raw: string): void {
+    let msg: Record<string, unknown>
+    try { msg = JSON.parse(raw) } catch { return }
+
+    const id = msg['id'] as string | undefined
+    if (!id || !this.pending.has(id)) return
+
+    const { resolve, reject } = this.pending.get(id)!
+    this.pending.delete(id)
+
+    if (msg['type'] === 'error') {
+      reject(new Error((msg['message'] as string) ?? 'Unknown error'))
+    } else {
+      resolve(msg)
+    }
+  }
+
+  private request(type: string, payload: Record<string, unknown>): Promise<unknown> {
+    return new Promise((resolve, reject) => {
+      if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+        reject(new Error('Not connected to Edge Printing agent'))
+        return
+      }
+      const id = crypto.randomUUID()
+      this.pending.set(id, { resolve, reject })
+
+      const timeout = setTimeout(() => {
+        if (this.pending.has(id)) {
+          this.pending.delete(id)
+          reject(new Error(`Request "${type}" timed out`))
+        }
+      }, 30_000)
+
+      this.ws.send(JSON.stringify({ type, id, ...payload }))
+
+      // Wrap resolve/reject to also clear the timeout.
+      const original = this.pending.get(id)!
+      this.pending.set(id, {
+        resolve: (v) => { clearTimeout(timeout); original.resolve(v) },
+        reject: (e) => { clearTimeout(timeout); original.reject(e) },
+      })
+    })
+  }
+
+  private rejectPending(err: Error): void {
+    for (const { reject } of this.pending.values()) reject(err)
+    this.pending.clear()
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+/**
+ * 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 const ep = new EdgePrintClient()
+export default ep

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "declaration": true,
+    "declarationDir": "./dist",
+    "outDir": "./dist",
+    "strict": true,
+    "lib": ["ES2020", "DOM"]
+  },
+  "include": ["src/**/*.ts"]
+}