libniimai 0.0.0-stage → 0.1.0

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,88 @@
-# 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 to NIIMBOT label printers and other Bluetooth thermal printers from the browser. libniimai is the printer layer of [niimai](https://niimai.app), the label designer, published on its own.
+
+- **One connect call** for NIIMBOT, TSPL label printers, ESC/POS mini printers and cat printers. The printer family is found from the device the user picks.
+- **Print any canvas.** Pages are cropped to the printhead, rotated and encoded for the printer they go to.
+- **Live status**: battery, the loaded roll on NIIMBOT printers, and print progress.
+- **No server.** Everything runs in the page over Web Bluetooth or Web Serial.
+
+## Install
+
+```bash
+npm i libniimai
+```
+
+## Print a label
+
+```ts
+import { createPrinter } from 'libniimai';
+
+const printer = createPrinter();
+printer.subscribe((status) => console.log(status.state, status.deviceName, status.progress));
+
+// Must run from a user gesture, such as a click.
+button.onclick = async () => {
+  await printer.connect('bluetooth');
+
+  // A 40 × 12 mm label at 203 dpi: 8 dots per mm.
+  const canvas = document.createElement('canvas');
+  canvas.width = 320;
+  canvas.height = 96;
+  const ctx = canvas.getContext('2d')!;
+  ctx.fillStyle = '#fff';
+  ctx.fillRect(0, 0, canvas.width, canvas.height);
+  ctx.fillStyle = '#000';
+  ctx.font = 'bold 48px sans-serif';
+  ctx.fillText('Hello', 20, 66);
+
+  await printer.print(canvas, { density: 3, copies: 1 });
+};
+```
+
+Draw black on white at the printer's resolution, `status.profile.dpi`. Thermal printers print each dot black or white, so dither photos and greys first.
+
+## 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'`, `'serial'` (NIIMBOT over USB) or `'demo'` (a printer in memory). |
+| `disconnect()` | Closes the connection. |
+| `print(source, options)` | Prints a canvas, or a `{ count, page(i) }` source for a batch of different labels. Options: `density`, `copies`, `labelType` (paper type, see `PAPER_TYPES`) and `offset` in mm. |
+| `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 recognise yet. |
+
+`PrinterStatus` holds `state` (`disconnected`, `connecting`, `ready` or `printing`), `deviceName`, `battery`, `profile` (dpi, printhead width, density range), `label` (the loaded roll) and `progress`.
+
+### Lower level
+
+The protocol pieces are exported too, for building your own flow:
+
+- `createClient(kind)` returns a raw client for one connection.
+- `TsplPrinterClient`, `EscPosPrinterClient`, `CatPrinterClient` and `ThermalPrinterClient` take any `ThermalTransport`.
+- `tsplJob`, `escposJob` and `catJob` build the bytes for one page.
+- `TSPL_MODELS`, `ESCPOS_MODELS` and `CAT_MODELS` list the known models, with `tsplModelFor`, `escposModelFor` and `catModelFor` to match a Bluetooth name.
+- `unsupportedReason(kind)` says in a few words why a connection type cannot be used in the current browser.
+
+## Printers
+
+NIIMBOT printers go through [niimbluelib](https://github.com/MultiMote/niimbluelib), which loads only when one connects. The other families and their models are listed under [Supported printers](https://github.com/theanam/niimai#supported-printers), with how well each model is tested in [thermal-printers.md](https://github.com/theanam/niimai/blob/main/docs/thermal-printers.md).
+
+## Browsers
+
+Needs Web Bluetooth or Web Serial: Chrome or Edge on desktop, or Chrome on Android. Connecting has to start from a user gesture.
+
+## 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).
+
+libniimai is an independent project and is not affiliated with NIIMBOT.
+
+## License
+
+[MIT](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';