libniimai 0.4.0 → 0.6.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,8 +9,8 @@ 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:
@@ -90,7 +90,7 @@ 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`. |
@@ -159,12 +159,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.
-- `unsupportedReason(kind)` says in a few words why a connection type cannot be used in the current browser.
+- `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 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.
+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,4 +1,4 @@
-import type { ClientLike } from './client.js';
+import { RoutedClient } from './routed.js';
 type Lib = typeof import('@mmote/niimbluelib');
 /**
  * The Bluetooth printer behind the Connect button. One chooser lists NIIMBOT
@@ -9,55 +9,14 @@ 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;
     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;
 }
 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

@@ -67,14 +67,57 @@ export interface ClientLike {
      */
     unrecognisedAs?(typeId: string | null): void;
 }
-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';
+export type BrowserName = 'chrome' | 'edge' | 'opera' | 'brave' | 'samsung' | 'bluefy' | 'firefox' | 'safari' | 'other';
+export interface BrowserInfo {
+    os: OperatingSystem;
+    browser: BrowserName;
+    /** 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;
+}
+/** What the browser tells about itself. Defaults to the running browser. */
+export interface BrowserEnv {
+    ua: string;
+    touchPoints: number;
+    /** Brave hides itself in the user agent; it has `navigator.brave` instead. */
+    brave: boolean;
+    secure: boolean;
+}
+export declare function detectBrowser(env?: Partial<BrowserEnv>): BrowserInfo;
 /**
- * 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.
+ * A Help topic that shows how to get a connection type working:
+ * - `linux`: Chrome and other Chromium browsers on Linux need a flag for Bluetooth.
+ * - `brave`: Brave keeps Bluetooth and USB behind flags.
+ * - `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' | 'usb';
+export interface SupportIssue {
+    /** In a few words, what is missing or what to do. */
+    reason: string;
+    topic: SetupTopic;
+}
+/**
+ * Why a connection type cannot be used in this browser, and where to read how
+ * to fix it, or null when it can be used.
+ */
+export declare function supportIssue(kind: ConnectionKind, env?: Partial<BrowserEnv>): SupportIssue | null;
+/** supportIssue's reason alone. */
 export declare function unsupportedReason(kind: ConnectionKind, platform?: Platform): string | 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/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 { detectPlatform, supportsBluetooth, supportsSerial, unsupportedReason } from './client.js';
-export type { ClientLike, ConnectionKind, Platform, PrintTaskLike } 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 { 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';