retail-print-kit 0.1.0 → 0.2.0

package/README.md

@@ -1,39 +1,109 @@
 # retail-print-kit
 
-Receipt printer and cash drawer driver for Node and Electron. ESC/POS and Star command sets,
-printer profiles, USB / network / serial transports, no native dependency in the core.
+[![npm](https://img.shields.io/npm/v/retail-print-kit.svg)](https://www.npmjs.com/package/retail-print-kit)
+[![ci](https://github.com/arka162/thermal-print/actions/workflows/ci.yml/badge.svg)](https://github.com/arka162/thermal-print/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/retail-print-kit.svg)](LICENSE)
 
-Status: early development. Not published yet.
+**Receipt printers, cash drawers and label printers for Node.js and Electron, in one package.**
 
-* Receipt command sets: ESC/POS (Epson and compatibles), Star Line Mode (TSP650 / mC-Print), Star raster (TSP100 / TSP143).
-* Label languages: ZPL (Zebra), TSPL (TSC, Xprinter, Rongta), EZPL (Godex).
-* Browser bundle (`retail-print-kit/browser`) with templates, previews and label encoders; a designer app in `apps/designer`.
-* Transports: `retail-print-kit/net` (raw TCP :9100, no deps), `retail-print-kit/usb` (needs `usb`), `retail-print-kit/serial` (needs `serialport`).
-* QR: native where the printer has it, bitmap fallback otherwise. Images: 1-bit `Bitmap` from RGBA.
-* Status: `printer.status()` reads ESC/POS DLE EOT (online, cover, paper, cutter, drawer pin).
-* Bitmap-only printers render through a canvas (`@napi-rs/canvas`, or pass your own factory in Electron).
+A modern replacement for `escpos` / `node-thermal-printer`: ESC/POS **and** Star printers, USB /
+network / serial, printer profiles instead of model `if`s, receipt and label **templates**, live
+**previews**, a visual **designer**, and a CLI for testing hardware in the field.
+
+**[Open the designer](https://arka162.github.io/thermal-print/)** · [Printer matrix](docs/printer-matrix.md) · [Hardware checklist](docs/hardware-checklist.md)
+
+![Receipt designer](https://raw.githubusercontent.com/arka162/thermal-print/main/docs/images/designer-receipt.png)
+
+## Why
+
+| | retail-print-kit | escpos | node-thermal-printer |
+|---|---|---|---|
+| Epson ESC/POS and compatibles | yes | yes | yes |
+| Star Line Mode (TSP650, mC-Print) | yes | no | yes |
+| Star raster-only (TSP100 / TSP143) | yes | no | no |
+| Label printers (ZPL, TSPL, EZPL) | yes | no | no |
+| Printer profiles (cut, drawer pulse, code page, columns) | yes | no | no |
+| Templates with data binding | yes | no | no |
+| HTML / PNG / SVG preview without a printer | yes | no | no |
+| Status (paper, cover, drawer) and model detection | yes | no | partly |
+| Native dependencies in the core | none | none | none |
+| TypeScript types | built in | community | built in |
+
+## Install
+
+```
+npm install retail-print-kit
+```
+
+The core is pure JavaScript. Add a transport only if you need it:
+
+```
+npm install usb            # USB printers
+npm install serialport     # RS-232 / USB-serial printers
+npm install @napi-rs/canvas  # PNG preview, image files, Star TSP100
+```
+
+Node 18 or newer, including Electron's main process. CI runs on Linux, Windows and macOS.
+
+## Quick start
 
 ```js
 const { Printer, profiles } = require('retail-print-kit');
 const { NetTransport } = require('retail-print-kit/net');
 
-const printer = new Printer(new NetTransport('192.168.1.50'), profiles.epsonTmT88);
+const printer = new Printer(new NetTransport('192.168.1.50'), profiles['epson-tm-t88']);
 await printer.open();
 printer
   .align('ct').style('b').size(2, 2).text('MY STORE')
   .size(1, 1).style('normal').align('lt')
-  .tableCustom([{ text: 'Coffee', align: 'LEFT', width: 0.7 }, { text: '$2.50', align: 'RIGHT', width: 0.3 }])
+  .tableCustom([
+    { text: 'Coffee', align: 'LEFT', width: 0.7 },
+    { text: '$2.50', align: 'RIGHT', width: 0.3 },
+  ])
   .drawLine()
+  .qr('https://example.com/receipt/1042')
   .feed(2).cut().cashdraw();
 await printer.close();
 ```
 
+The method names match the `escpos` package (`text`, `align`, `style`, `size`, `feed`, `cut`,
+`cashdraw`, `tableCustom`, `drawLine`, `barcode`, `qrimage`), so existing receipt code moves over
+with a device swap. Other transports:
+
+```js
+const { UsbTransport } = require('retail-print-kit/usb');       // new UsbTransport() or { vendorId, productId }
+const { SerialTransport } = require('retail-print-kit/serial'); // new SerialTransport('COM3', { baudRate: 9600 })
+```
+
+## Supported printers
+
+| Family | Profile ids | Command set |
+|---|---|---|
+| Epson TM-T88 V/VI/VII, TM-T20III, TM-m30 | `epson-tm-t88`, `epson-tm-t20`, `epson-tm-m30` | ESC/POS |
+| Bixolon, Citizen, SNBC, Xprinter, Rongta, HPRT, POS-X | `generic-escpos`, `generic-escpos-58` | ESC/POS |
+| Star TSP650II, TSP700II, mC-Print3 | `star-tsp650`, `star-mc-print3` | Star Line Mode |
+| Star TSP100 / TSP143 | `star-tsp100` | Star raster |
+| Zebra, TSC and clones, Godex (labels) | `encodeZpl`, `encodeTspl`, `encodeEzpl` | ZPL, TSPL, EZPL |
+
+A profile carries paper width, columns, code page, cut command, drawer pulse and features, so the
+same receipt code prints correctly on each. `identify()` and `profileForUsb()` pick one for you.
+See the [printer matrix](docs/printer-matrix.md) for what has been run on real hardware.
+
+## Cash drawer and status
+
+```js
+printer.cashdraw();        // pin 2; cashdraw(5) for the second drawer
+await printer.flush();
+
+const s = await printer.status();
+// { online, coverOpen, paperOut, paperNearEnd, cutterError, drawerPinHigh, ... }
+```
+
 ## Templates
 
-A receipt can be a JSON layout rendered with data, which is what a visual designer will produce:
+A receipt can be a JSON layout rendered with data. This is what the designer produces.
 
 ```js
-const { render } = require('retail-print-kit');
 const template = {
   name: 'receipt', version: 1,
   blocks: [
@@ -49,14 +119,24 @@ const template = {
     { type: 'cut' }, { type: 'drawer' },
   ],
 };
-printer.render(template, data);          // appends to a Printer
-const ops = render(template, data, profiles.epsonTmT88); // or just the ops
+printer.render(template, data);
+```
+
+Blocks: `text`, `line`, `row`, `table`, `image`, `feed`, `newline`, `cut`, `drawer`, `qr`,
+`barcode`, `each`, `if`. Values use `{{path | filter}}` with `upper`, `lower`, `trim`,
+`money[:prefix]`, `fixed[:n]`, `pad:n`, `padEnd:n`, `default:x`, `date[:time|datetime]`, `count`.
+Inside `each` and table rows, `this`, `@index` and `@number` refer to the current item.
+
+## Images and logos
+
+```js
+const { loadImage } = require('retail-print-kit');
+const logo = await loadImage('logo.png', { width: 384, dither: true }); // needs @napi-rs/canvas
+printer.align('ct').image(logo);
 ```
 
-Blocks: `text`, `line`, `row`, `table`, `feed`, `newline`, `cut`, `drawer`, `qr`, `barcode`, `each`, `if`.
-Values use `{{path | filter}}`; filters: `upper`, `lower`, `trim`, `money[:prefix]`, `fixed[:n]`,
-`pad:n`, `padEnd:n`, `default:x`, `date[:time|datetime]`, `count`. Inside `each`/`table` rows, `this`,
-`@index` and `@number` refer to the current item.
+`fromRgba` and `ditherRgba` convert raw pixels; `serializeBitmap` stores a bitmap as JSON for the
+template `image` block.
 
 ## Labels
 
@@ -68,40 +148,63 @@ const { LabelBuilder, encodeZpl, encodeTspl, encodeEzpl, labelToSvg, renderLabel
 const b = new LabelBuilder({ widthMm: 50.8, heightMm: 25.4, dpi: 203 });
 b.text(18, 14, 'Coffee Beans 1lb', 26).text(92, 65, '$12.99', 85, { bold: true })
  .barcode(35, 140, '036000291452', 'UPC_A', 35).qr(330, 20, 'https://x.io/i/1', { module: 3 });
-const zpl = encodeZpl(b.label);          // string
-const svg = labelToSvg(b.label);         // preview
+const zpl = encodeZpl(b.label);                 // send to the printer on port 9100
+const svg = labelToSvg(b.label);                // preview
 const label = renderLabel(labelTemplate, data); // from a designer JSON
 ```
 
+![Label designer](https://raw.githubusercontent.com/arka162/thermal-print/main/docs/images/designer-label.png)
+
 ## Designer
 
-`apps/designer/index.html` is a browser app (no build, no server) that edits receipt and label
-templates with a live preview, drag-to-position for labels, sample data, and exports the JSON that
-`render()` / `renderLabel()` and the CLI's `print --template` consume. Open it after `npm run build`.
+**https://arka162.github.io/thermal-print/** edits receipt and label templates in the browser:
+block palette, nested `each` / `if`, property editor, sample data, live preview, drag-to-position
+on labels, logo upload with dithering, JSON import and export. It runs entirely in the page from
+the browser bundle (`retail-print-kit/browser`); nothing is uploaded.
+
+## Preview without a printer
+
+```js
+printer.toHtml();                                 // paper-like HTML of the recorded ops
+opsToHtml(ops, profile); opsToPng(ops, profile);  // same without a Printer
+```
+
+<img src="https://raw.githubusercontent.com/arka162/thermal-print/main/docs/images/test-page.png" width="300" alt="PNG preview of the test page">
 
-## Preview and identify
+## Find and identify printers
 
 ```js
-printer.toHtml();                               // paper-like HTML of the recorded ops
-opsToHtml(ops, profile); opsToPng(ops, profile); // same without a Printer (PNG needs a canvas)
-const id = await identify(transport);           // { maker, model, firmware, set, profile }
-profileForUsb(0x04b8);                          // profile from a USB vendor/product id
+const { discoverNetworkPrinters, identify, profileForUsb } = require('retail-print-kit');
+await discoverNetworkPrinters({ identify: true }); // [{ host, port, identity: { maker, model, profile } }]
+await identify(transport);                         // GS I for ESC/POS, status probe for Star
+profileForUsb(0x04b8);                             // profile from a USB vendor id
 ```
 
 ## CLI
 
 ```
+npx retail-print-kit discover --identify                              # printers on this network
 npx retail-print-kit test --net 192.168.1.50 --profile epson-tm-t20   # test page + status
+npx retail-print-kit verify --net 192.168.1.50 --drawer               # numbered hardware checks
 npx retail-print-kit drawer --usb                                     # kick the drawer
 npx retail-print-kit status --serial /dev/ttyUSB0
-npx retail-print-kit identify --net 192.168.1.50                      # maker/model/firmware + suggested profile
-npx retail-print-kit preview --profile star-tsp100 --out page.png     # or .html, no printer needed
+npx retail-print-kit identify --net 192.168.1.50
+npx retail-print-kit image --file logo.png --width 384 --dither --net 192.168.1.50
 npx retail-print-kit print --template receipt.json --data sale.json --net 192.168.1.50
 npx retail-print-kit print --template shelf.json --data item.json --language zpl --net 192.168.1.60
+npx retail-print-kit verify-label --language tspl --net 192.168.1.60
+npx retail-print-kit preview --profile star-tsp100 --out page.png     # no printer needed
 npx retail-print-kit profiles
-npx retail-print-kit test --dry --profile star-tsp100 | head -c 200   # bytes only, no printer
 ```
 
-Docs: [ADR 0001](docs/adr/0001-replace-escpos.md), [printer matrix](docs/printer-matrix.md).
+Add `--dry` to any printing command to dump the bytes as hex instead of sending them.
+
+## Status of hardware verification
+
+Encoders are covered by byte-exact tests. Items still to be confirmed on real units are listed in
+the [hardware checklist](docs/hardware-checklist.md): Star raster cut modes, Star status bits,
+Godex font sizes, and QR syntax on EZPL and TSPL. Reports from the field are welcome as issues.
+
+## License
 
-License: MIT, Arkaprova Majumder.
+MIT, Arkaprova Majumder.

package/bin/retail-print-kit.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 'use strict';
 const fs = require('fs');
-const { Printer, profiles, profileById, NetTransport, identify, opsToHtml, opsToPng, OpBuilder, render, renderLabel, encodeLabel, labelToSvg } = require('../dist');
+const { Printer, profiles, profileById, NetTransport, identify, opsToHtml, opsToPng, OpBuilder, render, renderLabel, encodeLabel, labelToSvg, discoverNetworkPrinters, emptyBitmap, setPixel, qrBitmap, LabelBuilder, loadImage } = require('../dist');
 
 process.stdout.on('error', (err) => {
   if (err.code === 'EPIPE') process.exit(0);
@@ -14,6 +14,11 @@ Commands
   test       print a test page (text styles, table, barcode, QR) and show status
   drawer     kick the cash drawer
   status     print the printer status as JSON
+  verify     print the numbered hardware verification page (see docs/hardware-checklist.md)
+             add --drawer to kick pin 2 then pin 5
+  verify-label  print a verification label: --language zpl|tspl|ezpl [--width-mm 50.8 --height-mm 25.4]
+  discover   find printers on the local network (port 9100); --identify asks each one its model
+  image      print an image file: --file logo.png [--width 384] [--dither]
   identify   ask the printer its maker, model and firmware; suggest a profile
   preview    write the test page as HTML (--out page.html) or PNG (--out page.png)
   print      print a template: --template t.json --data d.json (receipt or label)
@@ -124,6 +129,72 @@ async function testPage(printer, profile) {
   await showStatus(printer);
 }
 
+function section(p, id, title) {
+  p.align('lt').style('b').text(`[${id}] ${title}`).style('normal');
+}
+
+async function verifyPage(printer, profile, args) {
+  const cols = profile.columns.a;
+  const ruler = (n) => '1234567890'.repeat(Math.ceil(n / 10)).slice(0, n);
+  printer.align('ct').style('b').size(2, 2).text('VERIFY').size(1, 1).style('normal')
+    .text(`${profile.id} / ${profile.set}`).text(new Date().toLocaleString()).align('lt').drawLine();
+  section(printer, 'V1', `Font A ruler: last digit must be ${ruler(cols).slice(-1)} at the right edge (${cols} cols)`);
+  printer.text(ruler(cols));
+  section(printer, 'V2', `Font B ruler (${profile.columns.b} cols)`);
+  printer.setFont('b').text(ruler(profile.columns.b)).setFont('a');
+  section(printer, 'V3', 'Styles: bold, underline, double width, double height, inverse');
+  printer.style('b').text('bold').style('u').text('underline').style('normal').size(2, 1).text('wide').size(1, 2).text('tall').size(1, 1)
+    .style({ invert: true }).text(' inverse ').style('normal');
+  section(printer, 'V4', 'Alignment: left, centre, right');
+  printer.align('lt').text('left').align('ct').text('centre').align('rt').text('right').align('lt');
+  section(printer, 'V5', 'Code page: bytes 80..FF (expect CP437 box drawing in B0..DF)');
+  for (let row = 0x80; row < 0x100; row += 16) {
+    printer.print(row.toString(16).toUpperCase() + ' ').raw(Array.from({ length: 16 }, (_, i) => row + i)).newLine();
+  }
+  section(printer, 'V6', 'Barcodes: UPC-A, EAN-13, CODE128, CODE39');
+  printer.align('ct')
+    .barcode('036000291452', 'UPC_A', { height: 50 }).newLine()
+    .barcode('5901234123457', 'EAN13', { height: 50 }).newLine()
+    .barcode('RPK-12345', 'CODE128', { height: 50 }).newLine()
+    .barcode('RPK 123', 'CODE39', { height: 50 }).newLine().align('lt');
+  section(printer, 'V7', 'QR A = printer native, QR B = bitmap; both must scan to the same URL');
+  printer.align('ct').text('A');
+  if (profile.features.nativeQr || profile.set === 'star-graphic') printer.qr('https://github.com/arka162/thermal-print', { size: 5 });
+  else printer.text('(no native QR on this profile)');
+  printer.newLine().text('B').image(qrBitmap('https://github.com/arka162/thermal-print', { size: 5 })).newLine().align('lt');
+  section(printer, 'V8', 'Raster: checkerboard, then a diagonal line, edges sharp');
+  const bm = emptyBitmap(256, 64);
+  for (let y = 0; y < 64; y++) for (let x = 0; x < 256; x++) if (x < 128 ? ((x >> 3) + (y >> 3)) % 2 === 0 : Math.abs(x - 128 - y * 2) < 2) setPixel(bm, x, y, true);
+  printer.align('ct').image(bm).newLine().align('lt');
+  section(printer, 'V9', 'Partial cut follows this line');
+  printer.cut(true);
+  section(printer, 'V10', 'Full cut follows this line');
+  printer.text('End of verification page. Fill in docs/hardware-checklist.md.').cut(false);
+  await printer.flush();
+  if (args.drawer) {
+    printer.cashdraw(2);
+    await printer.flush();
+    await new Promise((r) => setTimeout(r, 1500));
+    printer.cashdraw(5);
+    await printer.flush();
+    console.log('V11 drawer: kicked pin 2, then pin 5 after 1.5 s');
+  }
+  await showStatus(printer);
+}
+
+function verifyLabel(args) {
+  const b = new LabelBuilder({ widthMm: Number(args['width-mm'] || 50.8), heightMm: Number(args['height-mm'] || 25.4), dpi: Number(args.dpi || 203) });
+  const w = b.label.width;
+  const h = b.label.height;
+  b.box(2, 2, w - 4, h - 4, 2)
+    .text(10, 8, 'L1 text 20', 20).text(10, 32, 'L2 text 32', 32)
+    .barcode(10, 72, '036000291452', 'UPC_A', 40)
+    .qr(w - 110, 8, 'https://github.com/arka162/thermal-print', { module: 3 })
+    .rect(10, h - 14, w - 20, 4)
+    .text(w - 150, h - 60, String(args.language || 'zpl').toUpperCase(), 40, { bold: true });
+  return b.label;
+}
+
 async function showStatus(printer) {
   if (!printer.transport.read) return;
   try {
@@ -144,6 +215,35 @@ async function main() {
       return withPrinter(args, async (p) => { p.cashdraw(args.pin === '5' ? 5 : 2); });
     case 'status':
       return withPrinter(args, showStatus);
+    case 'verify':
+      return withPrinter(args, (p, profile) => verifyPage(p, profile, args));
+    case 'verify-label': {
+      const label = verifyLabel(args);
+      const language = String(args.language || 'zpl');
+      if (args.out) {
+        const out = String(args.out);
+        fs.writeFileSync(out, out.endsWith('.svg') ? labelToSvg(label) : Buffer.from(encodeLabel(label, language)));
+        console.log(`wrote ${out}`);
+        return;
+      }
+      const t = transportFor(args);
+      await t.open();
+      try { await t.write(Buffer.from(encodeLabel(label, language))); } finally { await t.close(); }
+      return;
+    }
+    case 'discover': {
+      const found = await discoverNetworkPrinters({ port: args.port ? Number(args.port) : undefined, identify: !!args.identify });
+      if (!found.length) console.log('no hosts answered on the printing port');
+      for (const p of found) {
+        const id = p.identity;
+        console.log(`${p.host}:${p.port}` + (id ? `  ${id.maker || '?'} ${id.model || ''}  -> ${id.profile ? id.profile.id : 'unknown'}` : ''));
+      }
+      return;
+    }
+    case 'image': {
+      const bm = await loadImage(String(args.file), { width: args.width ? Number(args.width) : undefined, dither: !!args.dither });
+      return withPrinter(args, async (p) => { p.align('ct').image(bm).newLine().cut(); });
+    }
     case 'identify': {
       const t = transportFor(args);
       await t.open();