libniimai 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anam Ahmed
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,144 @@
-# Temporary Holding Version
+# libniimai
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Print from the browser on four families of thermal printers: **NIIMBOT**, **TSPL label printers**, **ESC/POS mini printers** and **cat printers**. One API connects, detects the printer and prints any canvas, over Web Bluetooth or Web Serial. No server, no drivers, no app.
+
+libniimai powers [niimai](https://niimai.app), the label designer.
+
+## Supported printers
+
+| Family | Paper | Print width | Connection | Models |
+|---|---|---|---|---|
+| **NIIMBOT** | Labels with gaps, black mark, continuous, transparent | 12 mm and up, by model | Bluetooth, USB | D11, D110, D101, B1, B18, B21, B3S and more |
+| **TSPL label printers** | Labels with gaps, black mark, continuous | Up to 80 mm | Bluetooth | QR380A (sold as CC390) |
+| **ESC/POS mini printers** | 58 mm continuous | 48 mm | Bluetooth | MP583, MPT-II, PT-210, RPP02, ZJ-58 and more |
+| **Cat printers** | 58 mm continuous | 48 mm | Bluetooth | GB01, GB02, GB03, MX05, MX06, MX10 and more |
+
+The family is found from the device the user picks: by its Bluetooth name, then checked against the services it offers. Every family gets the same treatment:
+
+- **Detection**: the right client and settings, picked for you.
+- **Page handling**: each page is cropped to the head, rotated where the printer needs it, and encoded in the printer's own format.
+- **Paper types**: gaps, black marks and continuous paper, on printers that tell them apart.
+- **Density**: each printer's own darkness range, mapped from one `density` option.
+- **Progress**: pages done, and how much of each page has been sent.
+
+### NIIMBOT
+
+Label printers in many widths, from 12 mm pocket models up. Protocol by [niimbluelib](https://github.com/MultiMote/niimbluelib), which libniimai loads only when a NIIMBOT connects. libniimai reads the loaded roll from its RFID tag (size, paper type, labels left) and the battery level, and adds fixes verified on hardware, such as the B21 C2B on early firmware. Models niimbluelib does not know yet print with a manual profile from `MANUAL_PROFILES`.
+
+### TSPL label printers
+
+Desktop label printers up to 80 mm wide that take TSC's TSPL label language. The printer finds each label's edge itself, and confirms each job. When a job goes unconfirmed, libniimai asks the printer why, and an open cover, jam or empty roll comes back as an error. Common 2- to 3-inch label sizes are listed in `profile.sizes`, 3 × 4 inch included. These printers cannot sense the roll, so `status.label.barcode` gives a stable key to remember its size per printer.
+
+### ESC/POS mini printers
+
+Pocket receipt printers on 58 mm paper with a 384-dot head. Pages print as one raster image at any length, for receipts, lists and long labels.
+
+### Cat printers
+
+The small "cat" printers sold under many names, on 58 mm paper with a 384-dot head. Five darkness levels, flow control so long prints never overrun the printer, and the newer GB03 and MX-series variants handled per model.
+
+Each model is marked by how well it is tested in `TSPL_MODELS`, `ESCPOS_MODELS` and `CAT_MODELS`; see also [thermal-printers.md](https://github.com/theanam/niimai/blob/main/docs/thermal-printers.md).
+
+## Install
+
+```bash
+npm i libniimai
+```
+
+Ships as an ES module with TypeScript types.
+
+## Quick start
+
+```ts
+import { createPrinter } from 'libniimai';
+
+const printer = createPrinter();
+printer.subscribe((status) => console.log(status.state, status.deviceName, status.progress));
+
+// Connecting must start from a user gesture, such as a click.
+button.onclick = async () => {
+  await printer.connect('bluetooth');
+  const { dpi } = printer.getStatus().profile!;
+
+  // A 50 × 30 mm label at the printer's resolution.
+  const dots = (mm: number) => Math.round((mm / 25.4) * dpi);
+  const canvas = document.createElement('canvas');
+  canvas.width = dots(50);
+  canvas.height = dots(30);
+  const ctx = canvas.getContext('2d')!;
+  ctx.fillStyle = '#fff';
+  ctx.fillRect(0, 0, canvas.width, canvas.height);
+  ctx.fillStyle = '#000';
+  ctx.font = `bold ${dots(8)}px sans-serif`;
+  ctx.fillText('Hello', dots(4), dots(18));
+
+  await printer.print(canvas, { density: 3, copies: 1 });
+};
+```
+
+Draw black on white. Thermal printers print each dot black or white, so dither photos and greys first. The same code prints on all four families; `density` is clamped to the printer's range.
+
+## API
+
+### `createPrinter()`
+
+Returns a `PrinterService`, which owns one printer connection.
+
+| Member | What it does |
+| --- | --- |
+| `connect(kind)` | Opens the browser's device picker and connects. `kind` is `'bluetooth'` (every family), `'serial'` (NIIMBOT over USB) or `'demo'` (a printer in memory, for trying things out). |
+| `disconnect()` | Closes the connection. |
+| `print(source, options)` | Prints a canvas, or a `{ count, page(i) }` source for a batch of different labels. |
+| `getStatus()` | The current `PrinterStatus`. |
+| `subscribe(fn)` | Calls `fn` on every status change. Returns a function that unsubscribes. |
+| `setManualProfile(id)` | Picks a printer type from `MANUAL_PROFILES` for NIIMBOT models niimbluelib does not know yet. |
+
+**Print options**
+
+| Option | What it does |
+| --- | --- |
+| `density` | Darkness, clamped to `profile.densityMin`–`densityMax`. |
+| `copies` | Copies of each page. |
+| `labelType` | Paper type, from `PAPER_TYPES`: 1 labels with gaps, 2 black mark, 3 continuous. |
+| `offset` | Nudges the print, in mm: `{ x, y }`. |
+
+**`PrinterStatus`**
+
+| Field | What it holds |
+| --- | --- |
+| `state` | `disconnected`, `connecting`, `ready` or `printing`. |
+| `deviceName` | The printer's Bluetooth name. |
+| `profile` | `dpi`, `printheadPixels`, `printDirection`, density range, `kind: 'thermal'` for continuous-paper printers, and `sizes` for printers with a size list. |
+| `label` | The loaded roll, where the printer reports one. |
+| `battery` | Battery level, where the printer reports one. |
+| `progress` | `{ page, total, sending }`; `sending` is 0–100 for the page going over the link. |
+
+### Lower level
+
+Every piece is exported, for building your own flow:
+
+- `createClient(kind)` returns a raw client for one connection.
+- `TsplPrinterClient`, `EscPosPrinterClient` and `CatPrinterClient` take any `ThermalTransport`, so they also work over other links.
+- `tsplJob`, `escposJob` and `catJob` build the bytes for one page.
+- `tsplModelFor`, `escposModelFor` and `catModelFor` match a Bluetooth name to a known model.
+- `unsupportedReason(kind)` says in a few words why a connection type cannot be used in the current browser.
+
+## Browsers
+
+Needs Web Bluetooth or Web Serial: Chrome or Edge on desktop, or Chrome on Android. On iPhone and iPad, the Bluefy browser adds Web Bluetooth.
+
+## Feedback
+
+Found a bug, or a printer that should work? [Open an issue](https://github.com/theanam/niimai/issues). For anything else, write to [anam.ahmed.a@gmail.com](mailto:anam.ahmed.a@gmail.com).
+
+## Credits
+
+- [niimbluelib](https://github.com/MultiMote/niimbluelib) by MultiMote, for the NIIMBOT protocol
+- [rbaron/catprinter](https://github.com/rbaron/catprinter) and [NaitLee/Cat-Printer](https://github.com/NaitLee/Cat-Printer), for the cat printer protocol
+- TSC's TSPL programming manual, for the label printer language
+
+libniimai is an independent project and is not affiliated with NIIMBOT or any printer maker.
+
+## License
+
+[MIT](https://github.com/theanam/niimai/blob/main/LICENSE)

package/dist/ble.d.ts

@@ -0,0 +1,40 @@
+import type { NiimbotAbstractClient } from '@mmote/niimbluelib';
+type Lib = typeof import('@mmote/niimbluelib');
+/** The standard NIIMBOT service, followed by serial-over-BLE services common on budget printers. */
+export declare const CANDIDATE_SERVICES: string[];
+/** Name prefixes of NIIMBOT printers; the chooser lists only these and known cat printers. */
+export declare const NAME_PREFIXES: string[];
+/** Opens the browser's printer chooser. */
+export declare function requestPrinter(extraPrefixes?: string[]): Promise<BluetoothDevice>;
+interface CharLike {
+    uuid: string;
+    properties: {
+        notify: boolean;
+        indicate?: boolean;
+        write: boolean;
+        writeWithoutResponse: boolean;
+    };
+}
+export interface ServiceLike<C extends CharLike = CharLike> {
+    uuid: string;
+    getCharacteristics(): Promise<C[]>;
+}
+export interface Channel<C extends CharLike = CharLike> {
+    write: C;
+    notify: C;
+}
+/**
+ * Picks the characteristics to talk through. A single characteristic that both
+ * notifies and accepts writes wins (the NIIMBOT layout); otherwise a write and
+ * a notify characteristic from the same service are paired.
+ */
+export declare function pickChannel<C extends CharLike>(services: ServiceLike<C>[]): Promise<Channel<C> | null>;
+/** Turns Chrome's terse GATT errors into something a person can act on. */
+export declare function describeBleError(err: unknown, found?: string[]): Error;
+/**
+ * A Web Bluetooth client that accepts more service layouts than niimbluelib's
+ * own, which only knows the standard NIIMBOT service. The protocol handling
+ * (packets, negotiation, heartbeat) is inherited unchanged.
+ */
+export declare function createBleClient(lib: Lib, chosen?: BluetoothDevice): NiimbotAbstractClient;
+export {};

package/dist/bluetooth.d.ts

@@ -0,0 +1,57 @@
+import type { ClientLike } from './client.js';
+type Lib = typeof import('@mmote/niimbluelib');
+/**
+ * The Bluetooth printer behind the Connect button. One chooser lists NIIMBOT
+ * printers and the known extra thermal printers. A known cat printer offering
+ * AE30 gets the cat client, a known ESC/POS printer offering 18F0 the ESC/POS
+ * client, a known TSPL label printer offering 18F0 the TSPL client, and
+ * everything else the NIIMBOT client exactly as before. Known names never
+ * overlap, so each printer matches one client at most.
+ */
+export declare class BluetoothPrinter implements ClientLike {
+    private lib;
+    private inner;
+    constructor(lib: () => Promise<Lib>);
+    private get client();
+    connect(): Promise<{
+        deviceName?: string;
+    }>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    on(event: string, fn: (e: any) => void): unknown;
+    off(event: string, fn: (e: any) => void): unknown;
+    getPrinterInfo(): {
+        batteryPercents?: number;
+        modelId?: number;
+        printheadWidth?: number;
+        protocolVersion?: number;
+    };
+    getModelMetadata(): import("@mmote/niimbluelib").PrinterModelMeta | undefined;
+    getPrintTaskType(): "B1" | "B21_L2B" | "B21_V1" | "D110" | "D110M_V4" | "D11_V1" | "H1S" | undefined;
+    getRfidInfo(): {
+        labelRfidInfo?: {
+            tagPresent?: boolean;
+            barCode?: string;
+            allPaper?: number;
+            usedPaper?: number;
+            consumablesType?: number;
+        };
+        paperInfo?: {
+            valid?: boolean;
+            paperWidth?: number;
+            paperHeight?: number;
+            paperType?: number;
+        };
+    };
+    fetchRfidInfo(): Promise<unknown>;
+    startHeartbeat(): void;
+    stopHeartbeat(): void;
+    isHeartbeatStarted(): boolean;
+    get protocol(): {
+        newPrintTask(name: import("@mmote/niimbluelib").PrintTaskName, options: Record<string, unknown>): import("./client.js").PrintTaskLike;
+        printEnd(): Promise<boolean>;
+    };
+    get encodePage(): ((canvas: HTMLCanvasElement) => unknown) | undefined;
+    get rollKey(): (() => string) | undefined;
+}
+export {};

package/dist/cat.d.ts

@@ -0,0 +1,53 @@
+/**
+ * "Cat printers": the small Bluetooth thermal printers sold as GB01, MX06 and
+ * the like. See thermal.ts for what they share with other extras.
+ *
+ * Protocol, from rbaron/catprinter and NaitLee/Cat-Printer: packets are
+ * 51 78 <cmd> 00 <len> 00 <payload> <crc8(payload)> FF over service AE30,
+ * written to AE01. The printer sends flow control on AE02.
+ */
+import { ThermalPrinterClient, type Confidence, type Pace, type ThermalModel, type ThermalTransport } from './thermal.js';
+export declare const CAT_SERVICE = "0000ae30-0000-1000-8000-00805f9b34fb";
+export declare const CAT_TX = "0000ae01-0000-1000-8000-00805f9b34fb";
+export declare const CAT_RX = "0000ae02-0000-1000-8000-00805f9b34fb";
+export type { Confidence };
+export interface CatModel extends ThermalModel {
+    /** Takes the newer "start printing" command. */
+    newKind?: boolean;
+    /** Mishandles the feed command, so the paper is fed with blank rows. */
+    feedWithRows?: boolean;
+}
+/**
+ * Models known to speak this protocol. "high": supported by both reference
+ * projects and widely used. "medium": listed by Cat-Printer, fewer reports.
+ * "tested": printed with niimai on real hardware.
+ */
+export declare const CAT_MODELS: CatModel[];
+/** Look-alikes that use other protocols. Listed in Help and docs/thermal-printers.md. */
+export declare const CAT_UNSUPPORTED: {
+    name: string;
+    note: string;
+}[];
+export declare const catModelFor: (name: string | undefined) => CatModel | null;
+export declare const crc8: (data: ArrayLike<number>) => number;
+export declare function packet(cmd: number, payload: ArrayLike<number>): number[];
+/** Flow control the printer sends on AE02 when its buffer fills and drains. */
+export declare const FLOW_PAUSE: number[];
+export declare const FLOW_RESUME: number[];
+/** Rows for a cat printer: leftmost dot in the lowest bit. */
+export declare const encodeRows: (data: ArrayLike<number>, width: number, height: number) => Uint8Array[];
+/** Everything sent for one job: setup, the rows for each copy, then feed and finish. */
+export declare function printJob(rows: Uint8Array[], { density, copies, model }: {
+    density: number;
+    copies: number;
+    model: CatModel | null;
+}): Uint8Array;
+/** A cat printer: the shared thermal client with cat packets and flow control. */
+export declare class CatPrinterClient extends ThermalPrinterClient {
+    readonly model: CatModel | null;
+    protected readonly densityLevels: number;
+    protected readonly modelName: string;
+    constructor(transport: ThermalTransport, model: CatModel | null, pace?: Pace);
+    protected encodeRows(data: ArrayLike<number>, width: number, height: number): Uint8Array<ArrayBufferLike>[];
+    protected job(rows: Uint8Array[], density: number, copies: number): Uint8Array<ArrayBufferLike>;
+}

package/dist/client.d.ts

@@ -0,0 +1,70 @@
+import type { PrinterModelMeta, PrintTaskName } from '@mmote/niimbluelib';
+/**
+ * The slice of niimbluelib's client the app uses. Keeping it narrow lets the
+ * mock printer and the tests stand in for real hardware.
+ */
+export interface PrintTaskLike {
+    printInit(): Promise<void>;
+    printPage(image: unknown, quantity?: number): Promise<void>;
+    waitForFinished(): Promise<void>;
+    printEnd(): Promise<boolean>;
+}
+export interface ClientLike {
+    connect(): Promise<{
+        deviceName?: string;
+    }>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    on(event: string, fn: (e: any) => void): unknown;
+    off(event: string, fn: (e: any) => void): unknown;
+    getPrinterInfo(): {
+        batteryPercents?: number;
+        modelId?: number;
+        printheadWidth?: number;
+        protocolVersion?: number;
+    };
+    getModelMetadata(): PrinterModelMeta | undefined;
+    getPrintTaskType(): PrintTaskName | undefined;
+    getRfidInfo(): {
+        labelRfidInfo?: {
+            tagPresent?: boolean;
+            barCode?: string;
+            allPaper?: number;
+            usedPaper?: number;
+            consumablesType?: number;
+        };
+        paperInfo?: {
+            valid?: boolean;
+            paperWidth?: number;
+            paperHeight?: number;
+            paperType?: number;
+        };
+    };
+    fetchRfidInfo(): Promise<unknown>;
+    startHeartbeat(): void;
+    stopHeartbeat(): void;
+    isHeartbeatStarted?(): boolean;
+    protocol: {
+        newPrintTask(name: PrintTaskName, options: Record<string, unknown>): PrintTaskLike;
+        /** True once the printer has finished every page. */
+        printEnd(): Promise<boolean>;
+    };
+    /** Clients that encode pages themselves (cat printers); NIIMBOT pages go through niimbluelib's encoder. */
+    encodePage?(canvas: HTMLCanvasElement): unknown;
+    /**
+     * Label printers that cannot sense the roll: a key to remember the roll
+     * size the user sets, per printer. NIIMBOT printers read their rolls instead.
+     */
+    rollKey?(): string;
+}
+export type ConnectionKind = 'bluetooth' | 'serial' | 'demo';
+export declare const supportsBluetooth: () => boolean;
+export declare const supportsSerial: () => boolean;
+export type Platform = 'ios' | 'android' | 'desktop';
+export declare function detectPlatform(ua?: string, touchPoints?: number): Platform;
+/**
+ * Why a connection type cannot be used in this browser, in a few words, or
+ * null when it can. iOS browsers all run on WebKit, which has neither Web
+ * Bluetooth nor Web Serial; Bluefy adds Web Bluetooth there.
+ */
+export declare function unsupportedReason(kind: ConnectionKind, platform?: Platform): string | null;

package/dist/escpos.d.ts

@@ -0,0 +1,32 @@
+/**
+ * ESC/POS mini printers: 58 mm Bluetooth receipt printers such as the MP583
+ * (YAEN MPT-II). They take standard raster images (GS v 0) over the 18F0
+ * printer service. See thermal.ts for what they share with other extras.
+ */
+import { ThermalPrinterClient, type Pace, type ThermalModel, type ThermalTransport } from './thermal.js';
+export declare const ESCPOS_SERVICE = "000018f0-0000-1000-8000-00805f9b34fb";
+export declare const ESCPOS_WRITE = "00002af1-0000-1000-8000-00805f9b34fb";
+/**
+ * Models known to take ESC/POS raster images over 18F0. "tested": printed
+ * with niimai on real hardware. "medium": the same chipset and service are
+ * widely reported, untested here.
+ */
+export declare const ESCPOS_MODELS: ThermalModel[];
+export declare const escposModelFor: (name: string | undefined) => ThermalModel | null;
+/** Rows for an ESC/POS printer: leftmost dot in the highest bit. */
+export declare const encodeRows: (data: ArrayLike<number>, width: number, height: number) => Uint8Array[];
+/** ESC @, then each copy as GS v 0 bands with a gap between, then a feed. */
+export declare function escposJob(rows: Uint8Array[], copies: number): Uint8Array;
+/**
+ * An ESC/POS printer: the shared thermal client with raster commands. These
+ * printers send no flow control, so writes are paced. Heat settings vary by
+ * vendor, so darkness is left to the printer.
+ */
+export declare class EscPosPrinterClient extends ThermalPrinterClient {
+    readonly model: ThermalModel | null;
+    protected readonly densityLevels = 1;
+    protected readonly modelName: string;
+    constructor(transport: ThermalTransport, model: ThermalModel | null, pace?: Pace);
+    protected encodeRows(data: ArrayLike<number>, width: number, height: number): Uint8Array<ArrayBufferLike>[];
+    protected job(rows: Uint8Array[], _density: number, copies: number): Uint8Array<ArrayBufferLike>;
+}

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+/// <reference types="web-bluetooth" preserve="true" />
+/// <reference types="w3c-web-serial" preserve="true" />
+import type { ClientLike, ConnectionKind } from './client.js';
+import { PrinterService } from './service.js';
+/**
+ * A client for one kind of connection. Bluetooth finds the printer family
+ * from the device the user picks; serial is NIIMBOT only; demo is a printer
+ * in memory.
+ */
+export declare function createClient(kind: ConnectionKind): Promise<ClientLike>;
+/** A ready printer service: connect, watch its status, print canvases. */
+export declare function createPrinter(): PrinterService;
+export { PrinterService, DEMO_NAME, friendlyError, fitToPrinthead, shiftCanvas } from './service.js';
+export type { ClientFactory, PageSource, PrinterState, PrinterStatus, PrintOffset, PrintOptions } from './service.js';
+export { detectPlatform, supportsBluetooth, supportsSerial, unsupportedReason } from './client.js';
+export type { ClientLike, ConnectionKind, Platform, PrintTaskLike } from './client.js';
+export { correctTask, findManualProfile, inkOutsideHead, MANUAL_PROFILES, printheadCrop, printheadMm, resolveProfile } from './profiles.js';
+export type { LabelSize, PrintDirection, PrinterProfile } from './profiles.js';
+export { effectivePaper, labelTypeOf, PAPER_TYPES, paperFromLabelType, paperName } from './paper.js';
+export type { PaperType } from './paper.js';
+export { BluetoothPrinter } from './bluetooth.js';
+export { describeBleError } from './ble.js';
+export { DEMO_META, MockClient } from './mock.js';
+export { modelFor, THERMAL_DEFAULT_SIZE, THERMAL_HEAD_DOTS, THERMAL_HEAD_MM, THERMAL_SIZES, ThermalPrinterClient, webTransport } from './thermal.js';
+export type { Confidence, Pace, ThermalModel, ThermalTransport } from './thermal.js';
+export { CAT_MODELS, CAT_UNSUPPORTED, CatPrinterClient, catModelFor, printJob as catJob } from './cat.js';
+export type { CatModel } from './cat.js';
+export { ESCPOS_MODELS, EscPosPrinterClient, escposJob, escposModelFor } from './escpos.js';
+export { TSPL_MODELS, TSPL_SIZES, TsplPrinterClient, tsplJob, tsplModelFor } from './tspl.js';