@gohcltech/edge-print-client 2.0.40-develop → 2.0.42-develop

package/src/edge-print.ts

@@ -1,685 +0,0 @@
-/**
- * @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. */
-  isDefault: 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. */
-  shareName?: 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. */
-  copiesMax?: 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.
-   */
-  virtualPrinter?: 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
-  /**
-   * Name shown for this application in the agent's Clients tab and in the
-   * approval prompt the user sees when connecting with an unapproved token.
-   *
-   * Strongly recommended: without it the user is asked to trust an
-   * "Unknown client", which is not much of a decision.
-   */
-  clientName?: 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>()
-  /** Rejects the connect currently waiting on `onopen`, if there is one. */
-  private pendingOpen: ((e: Error) => void) | null = null
-  /** Bumped per connect, so a superseded one can tell it is no longer current. */
-  private connectGeneration = 0
-  /**
-   * Whether a connection currently exists from the application's point of view:
-   * a socket that opened *and* authenticated, and has not since gone away.
-   *
-   * Distinct from `authenticated`, which tracks one socket. This tracks whether
-   * there is anything for `onClose` to report the loss of, and is the single
-   * rule every teardown path consults — the alternative was each path deciding
-   * for itself, which is how the same event came to be announced in one place
-   * and swallowed in another.
-   */
-  private established = false
-  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.
-   *
-   * Calling this on an already-connected client **replaces** the connection:
-   * the existing socket is torn down before the new one is attempted, and its
-   * in-flight requests reject. If the new attempt then fails there is no
-   * connection left, and close listeners are notified. Guard a
-   * 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
-   *   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,
-      clientName,
-      retries = 3,
-      retryDelay = 1000,
-    } = options
-
-    // A negative count would skip the loop altogether and resolve without ever
-    // opening a socket, leaving the caller believing it is connected while
-    // every later call rejects with "Not connected".
-    const attempts = Math.max(0, retries)
-
-    const generation = ++this.connectGeneration
-
-    for (let attempt = 0; attempt <= attempts; attempt++) {
-      // Checked before every attempt, not only after a failed one. A connect
-      // sleeping between retries would otherwise wake and open a socket —
-      // discarding whatever connection was established while it slept, and
-      // reconnecting after an explicit disconnect.
-      if (this.connectGeneration !== generation) {
-        throw new Error('Connection superseded')
-      }
-
-      try {
-        await this.openSocket(`wss://${host}:${port}`)
-        // Omitted entirely when unset, rather than sent as undefined/null —
-        // the agent treats a missing key as "no name given".
-        await this.request('auth', clientName ? { token, clientName } : { token })
-        this.authenticated = true
-        this.established = true
-        return
-      } catch (err) {
-        // A newer connect has taken over since this attempt began. Its socket
-        // is not this attempt's to tear down.
-        if (this.connectGeneration !== generation) throw err
-
-        this.discardSocket(new Error('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
-        // someone clicks Approve is the documented flow. Repeat attempts only
-        // bump a counter on the pending entry; the notification fires once.
-        if (attempt === attempts) {
-          this.markClosed()
-          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, if the agent rejects the job, or if the
-   *   job fails on the way to the spooler.
-   *
-   * 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
-   * after the spooler accepts the job still resolves.
-   *
-   * A rejection is also not proof that nothing printed: a request that exceeds
-   * 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:
-   *
-   * ```ts
-   * try {
-   *   await ep.print(config, data)
-   * } catch (err) {
-   *   const jobId = (err as Error & { jobId?: string }).jobId
-   * }
-   * ```
-   *
-   * @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 { jobId: string }
-    return resp.jobId
-  }
-
-  /**
-   * Close the WebSocket connection and reset client state.
-   *
-   * Any in-flight requests are rejected. Safe to call when already
-   * disconnected.
-   */
-  disconnect(): void {
-    // Routed through the same teardown as a replacement: nulling the reference
-    // alone leaves the socket's handlers attached, and its close then arrives
-    // later and tears down whatever connection has taken its place.
-    // Invalidates any connect still running, so a retry cannot wake up after
-    // this and quietly reconnect.
-    this.connectGeneration++
-
-    this.discardSocket(new Error('Disconnected'))
-    // Detaching the handlers means the socket's own close never arrives, so
-    // without this the loss would go unannounced.
-    this.markClosed()
-  }
-
-  /**
-   * `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.
-   *
-   * @returns A function that removes this listener. Registering inside a
-   *   reconnect path without unsubscribing stacks a duplicate listener on every
-   *   attempt, so hold onto this if the caller can register more than once.
-   *
-   * @example
-   * ```ts
-   * const stop = ep.onClose(() => {
-   *   console.warn('Lost connection to Edge Printing agent — reconnecting…')
-   *   reconnect()
-   * })
-   *
-   * // later, e.g. when the component unmounts
-   * stop()
-   * ```
-   */
-  onClose(fn: () => void): () => void {
-    this.closeListeners.push(fn)
-    return () => {
-      const i = this.closeListeners.indexOf(fn)
-      if (i !== -1) this.closeListeners.splice(i, 1)
-    }
-  }
-
-  // ── internals ────────────────────────────────────────────────────────────
-
-  /**
-   * Announces the loss of an established connection, exactly once.
-   *
-   * A socket that never authenticated was never a connection, so its going
-   * away is not something `onClose` reports — announcing it would have an
-   * onClose-driven reconnect racing the retry loop already running.
-   */
-  private markClosed(): void {
-    if (!this.established) return
-    this.established = false
-    // Copied: a listener may remove itself via the function onClose returns,
-    // and splicing the live array mid-iteration skips the next one.
-    ;[...this.closeListeners].forEach(fn => fn())
-  }
-
-  /**
-   * Tears down the current socket so it cannot reach this client again.
-   *
-   * Handlers are detached before closing, because the close event arrives in a
-   * later task — by which time the socket may have been replaced, and its
-   * `onclose` would otherwise report the *replacement* as disconnected.
-   *
-   * Detaching means the teardown that handler would have done has to happen
-   * here instead: clearing `authenticated`, settling in-flight requests, and
-   * settling a connect still waiting on `onopen`. That last one is easy to
-   * miss — a connect whose handlers are removed before either fires has
-   * nothing left to settle it, and `request()`'s timeout does not cover it, so
-   * it would wait forever.
-   *
-   * Close listeners are not fired from here. Whether a caller hears about a
-   * lost connection is `markClosed`'s decision, because only it knows whether
-   * there was an established connection to lose.
-   */
-  private discardSocket(reason: Error): void {
-    const ws = this.ws
-    const settleOpen = this.pendingOpen
-    this.ws = null
-    this.pendingOpen = null
-    this.authenticated = false
-
-    if (ws) {
-      ws.onopen = null
-      ws.onmessage = null
-      ws.onclose = null
-      ws.onerror = null
-      try { ws.close() } catch { /* already closing or closed */ }
-    }
-
-    settleOpen?.(reason)
-    this.rejectPending(reason)
-  }
-
-  private openSocket(url: string): Promise<void> {
-    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'))
-
-      const ws = new WebSocket(url)
-      this.ws = ws
-      this.pendingOpen = reject
-
-      const settled = () => { this.pendingOpen = null }
-      ws.onopen = () => { settled(); resolve() }
-      ws.onerror = () => {
-        settled()
-        reject(new Error(`Cannot reach Edge Printing agent at ${url}`))
-      }
-      ws.onmessage = (ev) => this.handleMessage(String(ev.data))
-      ws.onclose = () => {
-        // A socket can close during the handshake, before either onopen or
-        // onerror fires. Clearing the pending open without settling it would
-        // leave this connect waiting forever — request()'s timeout does not
-        // cover the open.
-        const openWaiting = this.pendingOpen
-        settled()
-        openWaiting?.(new Error(`Cannot reach Edge Printing agent at ${url}`))
-
-        this.ws = null
-        this.authenticated = false
-        this.rejectPending(new Error('Connection closed'))
-        this.markClosed()
-      }
-    })
-  }
-
-  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)
-
-    // `error` means the request never became a job. `print_error` means a job
-    // was created and then failed — it carries a real jobId, which is why
-    // matching only on `error` let failed prints resolve as successes.
-    // Matched by suffix so error types added later reject by default rather
-    // than silently resolving.
-    const type = String(msg['type'] ?? '')
-    if (type === 'error' || type.endsWith('_error')) {
-      const failure = new Error((msg['message'] as string) ?? '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)
-    } 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()
-
-      const timeout = setTimeout(() => {
-        if (this.pending.delete(id)) {
-          reject(new Error(`Request "${type}" timed out`))
-        }
-      }, 30_000)
-
-      // Registered once, already wrapped. The previous version inserted the
-      // raw handlers, sent, then replaced the entry with wrapped ones that
-      // closed over what it read back out of the map. A close in that window
-      // made rejectPending clear the map first, so the replacement re-inserted
-      // an entry whose captured handlers were undefined — poisoning the map for
-      // the next rejectPending, which then threw mid-loop and left every later
-      // request unsettled.
-      this.pending.set(id, {
-        resolve: (v) => { clearTimeout(timeout); resolve(v) },
-        reject: (e) => { clearTimeout(timeout); reject(e) },
-      })
-
-      try {
-        this.ws.send(JSON.stringify({ type, id, ...payload }))
-      } catch (err) {
-        clearTimeout(timeout)
-        this.pending.delete(id)
-        reject(err instanceof Error ? err : new Error(String(err)))
-      }
-    })
-  }
-
-  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

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