@qumra/receipt-encoder

A chainable ESC/POS receipt encoder — build receipt content and turn it into print-ready bytes.

Part of the @qumra suite. Fully standalone (zero dependencies) and transport-agnostic — send its output over any channel (@qumra/webusb, @qumra/node-usb, network, or Bluetooth).

Features

• ⛓️ Fluent, chainable API ending in encode(): Uint8Array.
• 🅰️ Arabic-ready — render with @qumra/arabic-canvas and pass the canvas to image().
• 🧾 Text formatting, raster images, native QR codes, paper cut, and cash-drawer pulse.
• 📦 Zero dependencies, dual ESM + CJS, fully typed.

Installation

npm install @qumra/receipt-encoder

Quick start

import { QumraReceiptEncoder } from '@qumra/receipt-encoder';

const data = new QumraReceiptEncoder()
  .initialize()
  .align('center')
  .bold().size(2).line('QUMRA').size(1).bold(false)
  .rule()
  .qrcode('https://qumra.io')
  .newline(2)
  .cut()
  .encode();          // Uint8Array

await printer.print(data);

API

Every method returns this for chaining; the chain ends with encode().

| Method | Description | |---|---| | initialize() | Reset printer state (ESC @). | | align(value) | Alignment: 'left' \| 'center' \| 'right'. | | bold(on?) · underline(on?) · invert(on?) | Toggle formatting (default true). | | size(w?, h?) | Scale (multiplier 1–8 per axis). | | text(str) | ASCII text without a newline (Arabic via image). | | line(str?) | Text followed by a newline. | | newline(n?) | One or more newlines. | | rule(cols?, ch?) | A divider line. | | image(img, opts?) | Raster image (RgbaImage or HTMLCanvasElement). Width is padded to a multiple of 8. | | qrcode(data, opts?) | Native QR code. opts: { size?, errorCorrection? }. | | cut(partial?) | Cut the paper. | | pulse(pin?, onMs?, offMs?) | Open the cash drawer. | | raw(bytes) | Append raw bytes (number[] \| Uint8Array). | | encode() | Finalize and return Uint8Array. |

Arabic example

import { renderReceipt } from '@qumra/arabic-canvas';

const canvas = renderReceipt({ storeName: 'متجر قمرة', total: '30.50' });
const data = new QumraReceiptEncoder().initialize().image(canvas).cut().encode();

Notes

• text() / line() encode ASCII only; other characters become ?. For Arabic, render with @qumra/arabic-canvas and use image().
• Output follows standard ESC/POS commands, compatible with most thermal printers (Xprinter, Epson, …).

Related packages

• @qumra/arabic-canvas — render Arabic to a canvas for image().
• @qumra/pos — the all-in-one facade that wires this up for you.

License

MIT © Qumra