@zpl-toolchain/print 0.1.2 → 0.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +123 -0
  2. package/package.json +2 -2
package/README.md ADDED
@@ -0,0 +1,123 @@
1
+ # @zpl-toolchain/print
2
+
3
+ Send ZPL to Zebra and ZPL-compatible label printers from Node.js. Supports persistent TCP connections, batch printing, status queries, browser printing, and a built-in HTTP/WebSocket proxy for web apps.
4
+
5
+ Part of the [zpl-toolchain](https://github.com/trevordcampbell/zpl-toolchain) project.
6
+
7
+ ## Installation
8
+
9
+ ```bash
10
+ npm install @zpl-toolchain/print
11
+ ```
12
+
13
+ ## Quick Start
14
+
15
+ ```ts
16
+ import { print, TcpPrinter, isReachable } from "@zpl-toolchain/print";
17
+
18
+ // One-shot: send ZPL and disconnect
19
+ const result = await print({ host: "192.168.1.55" }, "^XA^FDHello^FS^XZ");
20
+ console.log(result); // { success: true, bytesWritten: 21 }
21
+
22
+ // Check if a printer is reachable
23
+ if (await isReachable({ host: "192.168.1.55" })) {
24
+ console.log("Printer is online");
25
+ }
26
+
27
+ // Persistent connection: reuse for multiple labels
28
+ const printer = new TcpPrinter({ host: "192.168.1.55" });
29
+ await printer.print("^XA^FDLabel 1^FS^XZ");
30
+ await printer.print("^XA^FDLabel 2^FS^XZ");
31
+
32
+ // Query printer status
33
+ const status = await printer.getStatus();
34
+ console.log(`Paper out: ${status.paperOut}, Paused: ${status.paused}`);
35
+
36
+ await printer.close();
37
+ ```
38
+
39
+ ## Features
40
+
41
+ - **One-shot printing** — `print()` sends ZPL and disconnects in a single call
42
+ - **Persistent connections** — `TcpPrinter` keeps the socket open for high-throughput printing
43
+ - **Batch printing** — `TcpPrinter.printBatch()` sends multiple labels with optional progress callbacks and status polling
44
+ - **Status queries** — `TcpPrinter.getStatus()` parses the full `~HS` host status response (24 fields)
45
+ - **Retry with backoff** — configurable automatic retries on transient errors
46
+ - **Validated printing** — `printValidated()` validates ZPL before sending (requires optional `@zpl-toolchain/core` peer dependency)
47
+ - **HTTP/WebSocket proxy** — `createPrintProxy()` bridges browser apps to network printers with CORS, SSRF protection, allowlists, and connection limits
48
+ - **Browser printing** — `ZebraBrowserPrint` wraps the Zebra Browser Print agent for printing from the browser via `fetch()`
49
+ - **Full TypeScript types** — all APIs are fully typed with exported interfaces
50
+
51
+ ## API
52
+
53
+ ### One-shot functions
54
+
55
+ | Function | Description |
56
+ |----------|-------------|
57
+ | `print(config, zpl)` | Send ZPL and disconnect |
58
+ | `printValidated(config, zpl, opts?)` | Validate then print (requires `@zpl-toolchain/core`) |
59
+ | `isReachable(config)` | Check if a printer accepts TCP connections |
60
+
61
+ ### `TcpPrinter` — persistent connection
62
+
63
+ | Method | Description |
64
+ |--------|-------------|
65
+ | `new TcpPrinter(config)` | Create a printer (connects lazily on first call) |
66
+ | `print(zpl)` | Send ZPL over the persistent connection |
67
+ | `getStatus()` | Query `~HS` host status (paper out, paused, labels remaining, etc.) |
68
+ | `printBatch(labels, opts?, onProgress?)` | Send multiple labels with optional status polling and progress callbacks |
69
+ | `waitForCompletion(timeoutMs?)` | Poll until all labels are printed or timeout |
70
+ | `close()` | Gracefully close the connection |
71
+
72
+ ### Proxy — `@zpl-toolchain/print/proxy`
73
+
74
+ ```ts
75
+ import { createPrintProxy } from "@zpl-toolchain/print/proxy";
76
+
77
+ const server = createPrintProxy({
78
+ port: 3001,
79
+ allowed: ["192.168.1.*", "printer.local"],
80
+ allowedPorts: [9100],
81
+ cors: "*",
82
+ });
83
+ // POST /print { host, port?, zpl }
84
+ // POST /status { host, port? }
85
+ // WebSocket: send { action: "print"|"status", host, port?, zpl? }
86
+ ```
87
+
88
+ ### Browser — `@zpl-toolchain/print/browser`
89
+
90
+ ```ts
91
+ import { ZebraBrowserPrint } from "@zpl-toolchain/print/browser";
92
+
93
+ const zbp = new ZebraBrowserPrint();
94
+ if (await zbp.isAvailable()) {
95
+ const printers = await zbp.discover();
96
+ await zbp.print(printers[0], "^XA^FDHello^FS^XZ");
97
+ }
98
+ ```
99
+
100
+ ## Types
101
+
102
+ All types are exported from the main entry point:
103
+
104
+ - **`PrinterConfig`** — host, port, timeout, retries
105
+ - **`PrintResult`** — success, bytesWritten, error details
106
+ - **`PrinterStatus`** — 24-field parsed `~HS` response
107
+ - **`PrintError`** — typed error with `code` (CONNECTION_REFUSED, TIMEOUT, etc.)
108
+ - **`BatchOptions`** / **`BatchProgress`** / **`BatchResult`** — batch printing control
109
+ - **`ProxyConfig`** — proxy server configuration
110
+ - **`ValidateOptions`** — options for validated printing
111
+
112
+ ## Requirements
113
+
114
+ - **Node.js 18+** (uses `node:net` for TCP)
115
+ - **Optional**: `@zpl-toolchain/core` peer dependency for `printValidated()`
116
+
117
+ ## Documentation
118
+
119
+ See the [Print Client Guide](https://github.com/trevordcampbell/zpl-toolchain/blob/main/docs/PRINT_CLIENT.md) for comprehensive usage, CLI integration, proxy setup, and troubleshooting.
120
+
121
+ ## License
122
+
123
+ Dual-licensed under MIT or Apache-2.0.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zpl-toolchain/print",
3
- "version": "0.1.2",
3
+ "version": "0.1.4",
4
4
  "description": "Print client for sending ZPL to Zebra and ZPL-compatible printers",
5
5
  "type": "module",
6
6
  "engines": {
@@ -66,7 +66,7 @@
66
66
  "typescript": "^5.0.0"
67
67
  },
68
68
  "peerDependencies": {
69
- "@zpl-toolchain/core": ">=0.1.0"
69
+ "@zpl-toolchain/core": "^0.1.0"
70
70
  },
71
71
  "peerDependenciesMeta": {
72
72
  "@zpl-toolchain/core": {