libniimai 0.5.0 → 0.7.0

package/README.md

@@ -1,6 +1,6 @@
 # libniimai
 
-Print from the browser on four families of thermal printers: **NIIMBOT**, **TSPL label printers**, **ESC/POS receipt 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.
+Print from the browser on four families of thermal printers: **NIIMBOT**, **TSPL label printers**, **ESC/POS receipt printers** and **cat printers**. One API connects, detects the printer and prints any canvas, over Web Bluetooth, Web Serial or WebUSB. No server, no drivers, no app.
 
 libniimai powers [niimai](https://niimai.app), the label designer.
 
@@ -9,11 +9,11 @@ libniimai powers [niimai](https://niimai.app), the label designer.
 | 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), Gprinter GP-M322 |
-| **ESC/POS receipt printers** | 58 or 80 mm, continuous or stickers with gaps | 48 or 72 mm | Bluetooth | MP583, MPT-II, Xprinter XP-58IIL, PT-210, RPP02, MPT-3, RPP300 and more |
+| **TSPL label printers** | Labels with gaps, black mark, continuous | Up to 80 mm | Bluetooth, USB | QR380A (sold as CC390), Gprinter GP-M322 |
+| **ESC/POS receipt printers** | 58 or 80 mm, continuous or stickers with gaps | 48 or 72 mm | Bluetooth, USB | MP583, MPT-II, Xprinter XP-58IIL, PT-210, RPP02, MPT-3, RPP300 and more |
 | **Cat printers** | 58 mm continuous, stickers with gaps | 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 in `PRINTER_CATALOG`, then checked against the services it offers. A name that matches no family is treated as a NIIMBOT, unless a type from `PRINTER_TYPES` is set for unrecognised printers. Every family gets the same treatment:
+The family is found from the device the user picks: by its Bluetooth name in `PRINTER_CATALOG`, then checked against the services it offers. A name that matches no family goes to NIIMBOT first, exactly as before. If it does not look like a NIIMBOT and misses the handshake twice, its services decide (`byServices`): the cat service makes it a cat printer, any other serial service outside NIIMBOT's a receipt printer, and a printer offering only NIIMBOT services keeps the NIIMBOT error. A type from `PRINTER_TYPES` set for unrecognised printers overrides all of this. 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.
@@ -90,12 +90,14 @@ 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). |
+| `connect(kind)` | Opens the browser's device picker and connects. `kind` is `'bluetooth'` (every family), `'serial'` (NIIMBOT over USB, as a serial port), `'usb'` (label and receipt printers that show up as standard USB printers) 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. |
 | `feed(mm)` | Moves the paper by `mm` to line it up, back into the printer when negative. For printers that cannot sense the paper, where `status.canFeed` is true. |
+| `rememberMatches(map)` | Printers matched by their services before, by Bluetooth name (`{ 'MTP-4B_6DEF': 'escpos' }`, built from `status.deviceName` and `status.matchedAs`). They connect straight to that client, without the NIIMBOT handshake a receipt printer would print as text. |
+| `setPrintWidth(mm)` | Sets the print width on a printer whose head width is not known (`status.headUnknown`): a stock module name, or a printer matched by its services. Other printers keep their own. |
 | `setManualProfile(id)` | Picks a printer type for a printer that is not recognised: a NIIMBOT model from `MANUAL_PROFILES`, or a receipt, label or cat printer from `PRINTER_TYPES`. With one of those, the Bluetooth chooser lists every device. |
 
 **Print options**
@@ -120,6 +122,8 @@ Returns a `PrinterService`, which owns one printer connection.
 | `battery` | Battery level, where the printer reports one. |
 | `progress` | `{ page, total, sending }`; `sending` is 0–100 for the page going over the link. |
 | `canFeed` | True when `feed(mm)` can move the paper: ESC/POS and cat printers. |
+| `matchedAs` | `'escpos'` or `'cat'` when the printer was matched by its services; keep it for `rememberMatches`. |
+| `headUnknown` | True when the head's width is a guess (384 dots until set) and `setPrintWidth(mm)` can set it. |
 
 ### Your own clients
 
@@ -159,14 +163,15 @@ 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; `escposFeed` and `catFeed` the bytes that move the paper.
-- `identifyPrinter(name)` matches a Bluetooth name to a known model across every family, from `PRINTER_CATALOG`; `tsplModelFor`, `escposModelFor` and `catModelFor` look in one family.
-- `supportIssue(kind)` says why a connection type cannot be used in the current browser, as `{ reason, topic }`, or null when it can. `topic` names what fixes it: `linux` (a Chrome flag), `brave` (Brave flags), `ios`, `https` or `browsers`. `unsupportedReason(kind)` returns the reason alone.
+- `identifyPrinter(name)` matches a Bluetooth name to a known model across every family, from `PRINTER_CATALOG`; `tsplModelFor`, `escposModelFor` and `catModelFor` look in one family. `identifyUsbPrinter(device)` does the same for a USB device, by vendor and product ID, then product name.
+- `UsbPrinter` connects over WebUSB to a printer-class device (`USB_PRINTER_CLASS`, 7). The family comes from the catalog, then from a type set with `unrecognisedAs` when the printer speaks it, then from the printer's IEEE 1284 device ID (`familiesFromDeviceId`). A printer the site already uses connects without the chooser when it is the only one plugged in; `rememberedUsbPrinters()` lists them. `usbTransport(device)` gives the raw `ThermalTransport`.
+- `supportIssue(kind)` says why a connection type cannot be used in the current browser, as `{ reason, topic }`, or null when it can. `topic` names what fixes it: `linux` (a Chrome flag), `brave` (Brave flags), `ios`, `https`, `usb` (Windows and Linux drivers holding a USB printer) or `browsers`. `unsupportedReason(kind)` returns the reason alone.
 - `detectBrowser()` returns the system, the browser and whether it is built on Chromium.
-- `connectErrorTopic(err)` maps a connect error from a browser that has Bluetooth but cannot use it (adapter off, API turned off) to the same topics.
+- `connectErrorTopic(err)` maps a connect error from a browser that has Bluetooth or USB but cannot use it (adapter off, API turned off, a system driver holding the printer) to the same topics.
 
 ## 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. On Linux, Chrome needs `chrome://flags/#enable-web-bluetooth` turned on; Brave keeps both APIs behind `brave://flags`.
+Needs Web Bluetooth, Web Serial or WebUSB: Chrome or Edge on desktop, or Chrome on Android. On iPhone and iPad, the Bluefy browser adds Web Bluetooth. On Linux, Chrome needs `chrome://flags/#enable-web-bluetooth` turned on; Brave keeps Bluetooth and serial behind `brave://flags`. For USB printers, Windows needs the WinUSB driver (Zadig installs it), and Linux needs the `usblp` module unloaded and a udev rule granting access.
 
 ## Feedback
 

package/dist/bluetooth.d.ts

@@ -1,5 +1,19 @@
-import type { ClientLike } from './client.js';
+import { type CatalogEntry } from './catalog.js';
+import { RoutedClient } from './routed.js';
 type Lib = typeof import('@mmote/niimbluelib');
+/**
+ * What an unknown printer that did not answer as a NIIMBOT is, by its
+ * services: the cat service makes it a cat printer, and any other serial
+ * service outside NIIMBOT's a receipt printer. Null when it offers only
+ * NIIMBOT services, or nothing to print through: those stay NIIMBOT's.
+ */
+export declare function byServices(services: string[]): CatalogEntry | null;
+/** A family a printer was matched as by its services. */
+export type MatchedFamily = 'escpos' | 'cat';
+/** Printers matched by their services, by Bluetooth name. */
+export type MatchedPrinters = Record<string, MatchedFamily>;
+/** The pause before another try, growing with each one. */
+export declare const RETRY_MS = 250;
 /**
  * The Bluetooth printer behind the Connect button. One chooser lists NIIMBOT
  * printers and the known extra thermal printers. A known cat printer offering
@@ -9,55 +23,26 @@ type Lib = typeof import('@mmote/niimbluelib');
  * 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 {
+export declare class BluetoothPrinter extends RoutedClient {
     private lib;
-    private inner;
     constructor(lib: () => Promise<Lib>);
-    private get client();
     /** The kind of printer to treat an unrecognised one as; null leaves it to NIIMBOT. */
     private fallback;
     unrecognisedAs(typeId: string | null): void;
+    /** Printers matched by their services before, by Bluetooth name: they skip the NIIMBOT handshake. */
+    private remembered;
+    /** What the printer connected now was matched as by its services, if it was. */
+    matchedAs: MatchedFamily | undefined;
+    rememberMatches(matches: MatchedPrinters): void;
     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;
-    get feedPaper(): ((dots: number) => Promise<void>) | undefined;
-    get feedsBack(): boolean | undefined;
+    /**
+     * An unknown name that failed its first NIIMBOT try. NIIMBOT goes first
+     * again, so an unknown NIIMBOT that missed one handshake still gets its
+     * own client; only after a second miss do its services decide, and a
+     * printer offering only NIIMBOT services is never handed to another client.
+     */
+    private unknown;
 }
 export {};

package/dist/catalog.d.ts

@@ -1,4 +1,12 @@
-import { type ThermalModel } from './thermal.js';
+/**
+ * Every printer outside NIIMBOT that libniimai knows, by Bluetooth name, in
+ * one lookup across families. A name matches one family at most, and a name
+ * that matches none is known to be unknown before anything is sent to it.
+ * The models themselves live with their family: ESCPOS_MODELS, TSPL_MODELS
+ * and CAT_MODELS.
+ */
+import type { ClientLike } from './client.js';
+import { type Pace, type ThermalModel, type ThermalTransport } from './thermal.js';
 export type PrinterFamily = 'escpos' | 'tspl' | 'cat';
 export interface CatalogEntry {
     family: PrinterFamily;
@@ -7,6 +15,18 @@ export interface CatalogEntry {
 export declare const PRINTER_CATALOG: CatalogEntry[];
 /** The known printer a Bluetooth name belongs to, longest prefix first across every family. */
 export declare function identifyPrinter(name: string | undefined): CatalogEntry | null;
+/** The known printer behind a USB device: by its vendor and product IDs, then by its product name. */
+export declare function identifyUsbPrinter({ vendorId, productId, productName }: {
+    vendorId: number;
+    productId: number;
+    productName?: string;
+}): CatalogEntry | null;
+/**
+ * The client for a thermal printer over a cable link. Cat printers are
+ * Bluetooth only, so they get null. `ackTimeoutMs`: how long a label printer
+ * waits for its "OK" before asking for its status.
+ */
+export declare function cableClient({ family, model }: CatalogEntry, transport: ThermalTransport, pace: Pace, ackTimeoutMs: number): ClientLike | null;
 /** A kind of printer to pick for one niimai does not recognise. */
 export interface PrinterType extends CatalogEntry {
     id: string;

package/dist/client.d.ts

@@ -60,16 +60,26 @@ export interface ClientLike {
     feedPaper?(dots: number): Promise<void>;
     /** feedPaper can also move the paper back. */
     feedsBack?: boolean;
+    /** The head's width is not known (a stock module name, or a printer matched by its services): `setHeadDots` sets it. */
+    headUnknown?: boolean;
+    /** Sets how many dots the head prints across, on printers whose head width is not known. */
+    setHeadDots?(dots: number): void;
     /**
      * Bluetooth: the kind of printer to treat one with an unknown name as, set
      * before connecting: an id from PRINTER_TYPES, or a NIIMBOT profile id the
      * client ignores.
      */
     unrecognisedAs?(typeId: string | null): void;
+    /** Bluetooth: printers matched by their services on earlier connections, by name; they skip the NIIMBOT handshake. */
+    rememberMatches?(matches: Record<string, 'escpos' | 'cat'>): void;
+    /** Bluetooth: what the printer just connected was matched as by its services, if it was. */
+    matchedAs?: 'escpos' | 'cat';
 }
-export type ConnectionKind = 'bluetooth' | 'serial' | 'demo';
+/** `serial`: a printer on a USB cable that shows up as a serial port, as NIIMBOT printers do. `usb`: one that shows up as a standard USB printer. */
+export type ConnectionKind = 'bluetooth' | 'serial' | 'usb' | 'demo';
 export declare const supportsBluetooth: () => boolean;
 export declare const supportsSerial: () => boolean;
+export declare const supportsUsb: () => boolean;
 export type Platform = 'ios' | 'android' | 'desktop';
 export declare function detectPlatform(ua?: string, touchPoints?: number): Platform;
 export type OperatingSystem = 'ios' | 'android' | 'chromeos' | 'linux' | 'mac' | 'windows' | 'other';
@@ -77,7 +87,7 @@ export type BrowserName = 'chrome' | 'edge' | 'opera' | 'brave' | 'samsung' | 'b
 export interface BrowserInfo {
     os: OperatingSystem;
     browser: BrowserName;
-    /** Built on Chromium, so Web Bluetooth and Web Serial can be there. */
+    /** Built on Chromium, so Web Bluetooth, Web Serial and WebUSB can be there. */
     chromium: boolean;
     /** Served over https or from localhost; browsers hide both APIs elsewhere. */
     secure: boolean;
@@ -98,8 +108,9 @@ export declare function detectBrowser(env?: Partial<BrowserEnv>): BrowserInfo;
  * - `ios`: iPhone and iPad browsers, and Bluefy.
  * - `https`: the page has to be served over https.
  * - `browsers`: which browsers work.
+ * - `usb`: Windows and Linux hold on to USB printers until told to let the browser have them.
  */
-export type SetupTopic = 'linux' | 'brave' | 'ios' | 'https' | 'browsers';
+export type SetupTopic = 'linux' | 'brave' | 'ios' | 'https' | 'browsers' | 'usb';
 export interface SupportIssue {
     /** In a few words, what is missing or what to do. */
     reason: string;
@@ -113,8 +124,8 @@ export declare function supportIssue(kind: ConnectionKind, env?: Partial<Browser
 /** supportIssue's reason alone. */
 export declare function unsupportedReason(kind: ConnectionKind, platform?: Platform): string | null;
 /**
- * Errors browsers raise when Bluetooth is there but cannot be used: the
- * adapter is off or missing, or the browser turned the API off. The Help topic
- * to point to, or null.
+ * Errors browsers raise when Bluetooth or USB is there but cannot be used:
+ * the adapter is off or missing, the browser turned the API off, or the
+ * system keeps a USB printer for itself. The Help topic to point to, or null.
  */
 export declare function connectErrorTopic(err: unknown): SetupTopic | null;

package/dist/escpos.d.ts

@@ -44,8 +44,12 @@ export declare class EscPosPrinterClient extends ThermalPrinterClient {
     readonly model: ThermalModel | null;
     protected readonly densityLevels = 1;
     protected readonly modelName: string;
-    protected readonly headDots: number;
+    protected headDots: number;
+    /** A stock module name or a printer matched by its services: the head's width is a guess until set. */
+    readonly headUnknown: boolean;
     constructor(transport: ThermalTransport, model: ThermalModel | null, pace?: Pace);
+    /** Sets the head's width, in whole bytes of dots, on a printer whose width is not known; a known head keeps its own. */
+    setHeadDots(dots: number): void;
     protected encodeRows(data: ArrayLike<number>, width: number, height: number): Uint8Array<ArrayBufferLike>[];
     protected job(rows: Uint8Array[], _density: number, copies: number, _labelType: number, gapDots?: number): Uint8Array<ArrayBufferLike>;
     /** These printers cannot sense the paper, so the user lines it up by hand. */

package/dist/index.d.ts

@@ -1,11 +1,13 @@
 /// <reference types="web-bluetooth" preserve="true" />
 /// <reference types="w3c-web-serial" preserve="true" />
+/// <reference types="w3c-web-usb" preserve="true" />
 import type { ClientLike, ConnectionKind } from './client.js';
 import { PrinterService, type ClientFactory } 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.
+ * from the device the user picks; serial is NIIMBOT only; usb is for label
+ * and receipt printers that show up as standard USB printers; demo is a
+ * printer in memory.
  */
 export declare function createClient(kind: ConnectionKind): Promise<ClientLike>;
 export interface CreatePrinterOptions {
@@ -19,15 +21,16 @@ export interface CreatePrinterOptions {
 export declare function createPrinter(options?: CreatePrinterOptions): PrinterService;
 export { PrinterService, DEMO_NAME, friendlyError, fitToPrinthead, rotateCanvas, shiftCanvas } from './service.js';
 export type { ClientFactory, PageSource, PrinterState, PrinterStatus, PrintOffset, PrintOptions, Rotation } from './service.js';
-export { connectErrorTopic, detectBrowser, detectPlatform, supportIssue, supportsBluetooth, supportsSerial, unsupportedReason } from './client.js';
+export { connectErrorTopic, detectBrowser, detectPlatform, supportIssue, supportsBluetooth, supportsSerial, supportsUsb, unsupportedReason } from './client.js';
 export type { BrowserEnv, BrowserInfo, BrowserName, ClientLike, ConnectionKind, OperatingSystem, Platform, PrintTaskLike, SetupTopic, SupportIssue } 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 { findPrinterType, identifyPrinter, PRINTER_CATALOG, PRINTER_TYPES } from './catalog.js';
+export { findPrinterType, identifyPrinter, identifyUsbPrinter, PRINTER_CATALOG, PRINTER_TYPES } from './catalog.js';
 export type { CatalogEntry, PrinterFamily, PrinterType } from './catalog.js';
-export { BluetoothPrinter } from './bluetooth.js';
+export { BluetoothPrinter, byServices, type MatchedFamily, type MatchedPrinters } from './bluetooth.js';
+export { familiesFromDeviceId, parseDeviceId, rememberedUsbPrinters, UsbPrinter, usbTransport, USB_PRINTER_CLASS } from './usb.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';