jc-printer-sdk-ts 0.1.1 → 0.1.2

package/src/webBluetoothTransport.ts

@@ -7,8 +7,11 @@ import type {
   PrintDocument,
   PrinterDevice,
   PrinterInfo,
+  PrinterReadiness,
+  PrinterReadinessWarningCode,
   PrinterSdkCallback,
   PrinterState,
+  PrinterStatusSnapshot,
   ScanCallback,
 } from "./types.js";
 import { JCPrintApi } from "./client.js";
@@ -33,6 +36,8 @@ export interface WebBluetoothPrinterTransportOptions {
   scanMode?: "all" | "name";
   optionalServices?: string[];
   chunkSize?: number;
+  preflightStatus?: boolean;
+  statusQueryTimeoutMs?: number;
 }
 
 interface ResolvedWebBluetoothPrinterTransportOptions {
@@ -42,6 +47,8 @@ interface ResolvedWebBluetoothPrinterTransportOptions {
   scanMode: "all" | "name";
   optionalServices: string[];
   chunkSize: number;
+  preflightStatus: boolean;
+  statusQueryTimeoutMs: number;
 }
 
 export const NIIMBOT_WEB_BLUETOOTH_SERVICE_UUID = "e7810a71-73ae-499d-8c15-faa9aef0c3f2";
@@ -54,6 +61,8 @@ export const DEFAULT_WEB_BLUETOOTH_PRINTER_TRANSPORT_OPTIONS: ResolvedWebBluetoo
   scanMode: "all",
   optionalServices: [],
   chunkSize: 180,
+  preflightStatus: true,
+  statusQueryTimeoutMs: 700,
 };
 
 interface PrintJobContext {
@@ -90,6 +99,13 @@ interface PendingResponse {
   optional: boolean;
 }
 
+const DEFAULT_GATT_BUSY_RETRY_COUNT = 8;
+const DEFAULT_GATT_BUSY_RETRY_DELAY_MS = 25;
+const HEARTBEAT_ADVANCED_1 = 0x01;
+const HEARTBEAT_ADVANCED_2 = 0x04;
+const HEARTBEAT_RESPONSE_COMMANDS = [0xd9, 0xdd, 0xde, 0xdf];
+const INVERTED_LID_MODEL_IDS = new Set([512, 514, 513, 2304, 1792, 3584, 5120, 2560, 3840, 4352, 272, 273, 274]);
+
 function clone<T>(value: T): T {
   if (typeof globalThis.structuredClone === "function") {
     return globalThis.structuredClone(value);
@@ -105,6 +121,13 @@ function uniqueStrings(values: Array<string | undefined>): string[] {
   return Array.from(new Set(values.map((value) => value?.trim()).filter((value): value is string => !!value)));
 }
 
+function isGattOperationBusyError(error: unknown): boolean {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+  return /GATT operation already in progress/i.test(error.message);
+}
+
 function resolveOptions(
   options: Partial<WebBluetoothPrinterTransportOptions> = {},
 ): ResolvedWebBluetoothPrinterTransportOptions {
@@ -119,9 +142,24 @@ function resolveOptions(
     scanMode: options.scanMode ?? DEFAULT_WEB_BLUETOOTH_PRINTER_TRANSPORT_OPTIONS.scanMode,
     optionalServices: [...(options.optionalServices ?? DEFAULT_WEB_BLUETOOTH_PRINTER_TRANSPORT_OPTIONS.optionalServices)],
     chunkSize: Math.max(20, chunkSize),
+    preflightStatus: options.preflightStatus ?? DEFAULT_WEB_BLUETOOTH_PRINTER_TRANSPORT_OPTIONS.preflightStatus,
+    statusQueryTimeoutMs: Math.max(
+      100,
+      Math.trunc(Number(options.statusQueryTimeoutMs ?? DEFAULT_WEB_BLUETOOTH_PRINTER_TRANSPORT_OPTIONS.statusQueryTimeoutMs)),
+    ),
   };
 }
 
+function signedByte(value: number): number {
+  const byte = value & 0xff;
+  return byte > 0x7f ? byte - 0x100 : byte;
+}
+
+function signedWord(high: number, low: number): number {
+  const value = ((high & 0xff) << 8) | (low & 0xff);
+  return value > 0x7fff ? value - 0x10000 : value;
+}
+
 function defaultPrinterInfo(): PrinterInfo {
   return {
     deviceType: 2,
@@ -175,6 +213,7 @@ export class WebBluetoothPrinterTransport implements PrinterTransport {
   private b1HandshakeDone = false;
   private responseQueue: ParsedResponse[] = [];
   private pendingResponse: PendingResponse | undefined;
+  private gattOperationQueue: Promise<void> = Promise.resolve();
 
   constructor(options: Partial<WebBluetoothPrinterTransportOptions> = {}) {
     this.options = resolveOptions(options);
@@ -230,13 +269,13 @@ export class WebBluetoothPrinterTransport implements PrinterTransport {
         };
 
     const device = await navigator.bluetooth.requestDevice(requestOptions);
-    const server = await device.gatt?.connect();
+    const server = await this.runGattOperation(() => device.gatt!.connect());
     if (!server) {
       throw new Error("Failed to open the selected Bluetooth device.");
     }
 
-    const service = await server.getPrimaryService(serviceUuid);
-    const characteristic = await service.getCharacteristic(characteristicUuid);
+    const service = await this.runGattOperation(() => server.getPrimaryService(serviceUuid));
+    const characteristic = await this.runGattOperation(() => service.getCharacteristic(characteristicUuid));
 
     this.device = device;
     this.server = server;
@@ -255,7 +294,7 @@ export class WebBluetoothPrinterTransport implements PrinterTransport {
 
     device.addEventListener("gattserverdisconnected", this.handleDisconnect);
     characteristic.addEventListener("characteristicvaluechanged", this.handleCharacteristicChanged);
-    await characteristic.startNotifications();
+    await this.runGattOperation(() => characteristic.startNotifications());
     await this.handshakeAndIdentify();
     this.sdkCallback?.onConnectSuccess(this.lastAddress, 20);
     return 0;
@@ -303,14 +342,33 @@ export class WebBluetoothPrinterTransport implements PrinterTransport {
     printMode: number,
     callback: PrintCallback,
   ): Promise<void> {
+    if (this.currentJob && (this.printerState === "Printing" || this.printerState === "Working")) {
+      throw new Error("A print job is already in progress on this Web Bluetooth printer.");
+    }
+
     this.currentJob = { density, paperType, printMode, callback };
-    this.printerState = "Printing";
-    callback.onProgress(0, 0, {
-      phase: "start",
-      density,
-      paperType,
-      printMode,
-    });
+    this.printerState = "Working";
+
+    try {
+      if (this.options.preflightStatus) {
+        const readiness = await this.evaluatePrintReadiness(this.options.statusQueryTimeoutMs, true);
+        if (!readiness.canPrint) {
+          throw new Error(`Printer is not ready to print: ${readiness.reason}`);
+        }
+      }
+
+      this.printerState = "Printing";
+      callback.onProgress(0, 0, {
+        phase: "start",
+        density,
+        paperType,
+        printMode,
+      });
+    } catch (error) {
+      this.currentJob = undefined;
+      this.printerState = this.server?.connected ? "Connected" : "Disconnected";
+      throw error;
+    }
   }
 
   async commitData(jsonPages: string[], infoPages: string[]): Promise<void> {
@@ -379,13 +437,15 @@ export class WebBluetoothPrinterTransport implements PrinterTransport {
 
     this.reconnecting = true;
     try {
-      const server = await this.device.gatt.connect();
+      const server = await this.runGattOperation(() => this.device!.gatt!.connect());
       this.server = server;
-      const service = await server.getPrimaryService(normalizeUuid(this.options.serviceUuid));
-      const characteristic = await service.getCharacteristic(normalizeUuid(this.options.characteristicUuid));
+      const service = await this.runGattOperation(() => server.getPrimaryService(normalizeUuid(this.options.serviceUuid)));
+      const characteristic = await this.runGattOperation(() =>
+        service.getCharacteristic(normalizeUuid(this.options.characteristicUuid)),
+      );
       this.characteristic = characteristic;
       characteristic.addEventListener("characteristicvaluechanged", this.handleCharacteristicChanged);
-      await characteristic.startNotifications();
+      await this.runGattOperation(() => characteristic.startNotifications());
       await this.handshakeAndIdentify();
       this.printerState = "Connected";
       this.sdkCallback?.onConnectSuccess(this.lastAddress, 20);
@@ -409,7 +469,7 @@ export class WebBluetoothPrinterTransport implements PrinterTransport {
     if (this.characteristic) {
       this.characteristic.removeEventListener("characteristicvaluechanged", this.handleCharacteristicChanged);
       try {
-        await this.characteristic.stopNotifications();
+        await this.runGattOperation(() => this.characteristic!.stopNotifications());
       } catch {
         // Some browsers reject when the device is already gone.
       }
@@ -466,6 +526,22 @@ export class WebBluetoothPrinterTransport implements PrinterTransport {
     return clone(this.printerInfo);
   }
 
+  async queryPrinterStatus(timeoutMs = this.options.statusQueryTimeoutMs): Promise<PrinterStatusSnapshot> {
+    if (!this.isDeviceConnected()) {
+      return this.createLocalStatusSnapshot(false);
+    }
+
+    if (this.currentJob && (this.printerState === "Printing" || this.printerState === "Working")) {
+      return this.createLocalStatusSnapshot(true);
+    }
+
+    return this.queryPhysicalPrinterStatus(timeoutMs);
+  }
+
+  async canStartPrintJob(timeoutMs = this.options.statusQueryTimeoutMs): Promise<PrinterReadiness> {
+    return this.evaluatePrintReadiness(timeoutMs, false);
+  }
+
   async getPrinterState(): Promise<PrinterState> {
     return this.printerState;
   }
@@ -549,6 +625,196 @@ export class WebBluetoothPrinterTransport implements PrinterTransport {
     this.currentJob?.callback?.onCancelJob(success);
   }
 
+  private isDeviceConnected(): boolean {
+    return !!this.server?.connected && !!this.characteristic;
+  }
+
+  private createLocalStatusSnapshot(connected = this.isDeviceConnected()): PrinterStatusSnapshot {
+    return {
+      connected,
+      state: this.printerState,
+      statusAvailable: false,
+    };
+  }
+
+  private async evaluatePrintReadiness(
+    timeoutMs: number,
+    ignoreCurrentJob: boolean,
+  ): Promise<PrinterReadiness> {
+    if (!this.isDeviceConnected()) {
+      return this.createReadiness("not_connected", "Printer is not connected.", false, this.createLocalStatusSnapshot(false));
+    }
+
+    if (!ignoreCurrentJob && this.currentJob && this.printerState === "Printing") {
+      return this.createReadiness(
+        "sdk_printing",
+        "A print job is already in progress on this Web Bluetooth printer.",
+        false,
+        this.createLocalStatusSnapshot(true),
+      );
+    }
+
+    if (!ignoreCurrentJob && this.currentJob && this.printerState === "Working") {
+      return this.createReadiness(
+        "printer_working",
+        "Printer is preparing another job.",
+        false,
+        this.createLocalStatusSnapshot(true),
+      );
+    }
+
+    const status = await this.queryPhysicalPrinterStatus(timeoutMs);
+    const warnings = this.collectReadinessWarnings(status);
+
+    if (!status.statusAvailable) {
+      return this.createReadiness(
+        "status_unavailable",
+        "Printer is connected, but live hardware status did not respond before the timeout.",
+        true,
+        status,
+        warnings,
+      );
+    }
+
+    if (status.lidClosed === false) {
+      return this.createReadiness("cover_open", "Printer cover is open.", false, status, warnings);
+    }
+
+    if (status.paperInserted === false) {
+      return this.createReadiness("paper_missing", "Printer has no paper inserted.", false, status, warnings);
+    }
+
+    if (status.voltageState !== undefined && status.voltageState !== 0) {
+      return this.createReadiness("voltage_error", "Printer voltage state is abnormal.", false, status, warnings);
+    }
+
+    return this.createReadiness("ready", "Printer is ready to receive a print job.", true, status, warnings);
+  }
+
+  private createReadiness(
+    code: PrinterReadiness["code"],
+    reason: string,
+    canPrint: boolean,
+    status: PrinterStatusSnapshot,
+    warnings: PrinterReadinessWarningCode[] = [],
+  ): PrinterReadiness {
+    return {
+      canPrint,
+      code,
+      reason,
+      warnings,
+      state: status.state,
+      connected: status.connected,
+      status,
+    };
+  }
+
+  private collectReadinessWarnings(status: PrinterStatusSnapshot): PrinterReadinessWarningCode[] {
+    const warnings: PrinterReadinessWarningCode[] = [];
+    if (status.paperRfidSuccess === false) {
+      warnings.push("paper_rfid_failed");
+    }
+    if (status.ribbonInserted === false) {
+      warnings.push("ribbon_missing");
+    }
+    if (status.ribbonRfidSuccess === false) {
+      warnings.push("ribbon_rfid_failed");
+    }
+    if (status.lightingErrorCode !== undefined && status.lightingErrorCode !== 0) {
+      warnings.push("lighting_error");
+    }
+    return warnings;
+  }
+
+  private async queryPhysicalPrinterStatus(timeoutMs: number): Promise<PrinterStatusSnapshot> {
+    if (!this.isDeviceConnected()) {
+      return this.createLocalStatusSnapshot(false);
+    }
+
+    const heartbeatType = this.connectedProfile?.protocolVersion !== undefined && this.connectedProfile.protocolVersion < 3
+      ? HEARTBEAT_ADVANCED_1
+      : HEARTBEAT_ADVANCED_2;
+    let response = await this.sendCommand(0xdc, [heartbeatType], HEARTBEAT_RESPONSE_COMMANDS, timeoutMs, true);
+    if (!response && heartbeatType !== HEARTBEAT_ADVANCED_1) {
+      response = await this.sendCommand(0xdc, [HEARTBEAT_ADVANCED_1], HEARTBEAT_RESPONSE_COMMANDS, timeoutMs, true);
+    }
+
+    if (!response) {
+      return this.createLocalStatusSnapshot(true);
+    }
+
+    return this.parseHeartbeatStatus(response);
+  }
+
+  private parseHeartbeatStatus(response: ParsedResponse): PrinterStatusSnapshot {
+    const status: PrinterStatusSnapshot = {
+      connected: this.isDeviceConnected(),
+      state: this.printerState,
+      statusAvailable: false,
+      responseCommand: response.cmd,
+      rawData: [...response.data],
+    };
+
+    if (response.cmd === 0xd9) {
+      this.applyAdvanced2Heartbeat(status, response.data);
+    } else if (response.cmd === 0xdd) {
+      this.applyAdvanced1Heartbeat(status, response.data);
+    }
+
+    return status;
+  }
+
+  private applyAdvanced2Heartbeat(status: PrinterStatusSnapshot, data: number[]): void {
+    if (data.length < 9) {
+      return;
+    }
+
+    status.chargeLevel = signedByte(data[2]);
+    status.temperature = signedByte(data[3]);
+    status.lidClosed = signedByte(data[4]) === 0;
+    status.paperInserted = signedByte(data[5]) === 0;
+    status.paperRfidSuccess = signedByte(data[6]) !== 0;
+    status.ribbonRfidSuccess = signedByte(data[7]) !== 0;
+    status.ribbonInserted = signedByte(data[8]) === 0;
+    if (data.length >= 11) {
+      status.wifiRssi = signedWord(data[9], data[10]);
+    }
+    if (data.length >= 13) {
+      status.lightingErrorCode = signedByte(data[12]);
+    }
+    if (data.length >= 14) {
+      status.voltageState = signedByte(data[13]);
+    }
+    status.statusAvailable = true;
+  }
+
+  private applyAdvanced1Heartbeat(status: PrinterStatusSnapshot, data: number[]): void {
+    if (data.length === 10) {
+      status.lidClosed = signedByte(data[8]) === 0;
+      status.chargeLevel = signedByte(data[9]);
+    } else if (data.length === 13) {
+      status.lidClosed = signedByte(data[9]) === 0;
+      status.chargeLevel = signedByte(data[10]);
+      status.paperInserted = signedByte(data[11]) === 0;
+      status.paperRfidSuccess = signedByte(data[12]) !== 0;
+    } else if (data.length === 19) {
+      status.lidClosed = signedByte(data[15]) === 0;
+      status.chargeLevel = signedByte(data[16]);
+      status.paperInserted = signedByte(data[17]) === 0;
+      status.paperRfidSuccess = signedByte(data[18]) !== 0;
+    } else if (data.length === 20) {
+      status.paperInserted = signedByte(data[18]) === 0;
+      status.paperRfidSuccess = signedByte(data[19]) !== 0;
+    } else {
+      return;
+    }
+
+    if (status.lidClosed !== undefined && INVERTED_LID_MODEL_IDS.has(this.printerInfo.deviceType)) {
+      status.lidClosed = !status.lidClosed;
+    }
+    status.statusAvailable = true;
+  }
+
   private handleDisconnect = (): void => {
     this.printerState = "Disconnected";
     this.server = undefined;
@@ -787,9 +1053,8 @@ export class WebBluetoothPrinterTransport implements PrinterTransport {
     timeoutMs = 2000,
     optional = false,
   ): Promise<ParsedResponse | null> {
-    const wait = expected?.length ? this.waitForCommand(expected, timeoutMs, optional) : Promise.resolve(null);
     await this.writeBytes(createFrame(cmd, data));
-    return wait;
+    return expected?.length ? this.waitForCommand(expected, timeoutMs, optional) : null;
   }
 
   private async waitForCommand(
@@ -835,17 +1100,47 @@ export class WebBluetoothPrinterTransport implements PrinterTransport {
     const payload = new ArrayBuffer(bytes.byteLength);
     new Uint8Array(payload).set(bytes);
 
-    if (canWriteWithoutResponse) {
-      await characteristic.writeValueWithoutResponse(payload);
-    } else {
-      await characteristic.writeValue(payload);
-    }
+    await this.runGattOperation(async () => {
+      if (canWriteWithoutResponse) {
+        await characteristic.writeValueWithoutResponse(payload);
+      } else {
+        await characteristic.writeValue(payload);
+      }
+    });
 
     if (paceMs > 0) {
       await delay(paceMs);
     }
   }
 
+  private async runGattOperation<T>(operation: () => Promise<T>): Promise<T> {
+    const run = async (): Promise<T> => {
+      let lastError: unknown;
+
+      for (let attempt = 0; attempt <= DEFAULT_GATT_BUSY_RETRY_COUNT; attempt += 1) {
+        try {
+          return await operation();
+        } catch (error) {
+          lastError = error;
+          if (!isGattOperationBusyError(error) || attempt >= DEFAULT_GATT_BUSY_RETRY_COUNT) {
+            throw error;
+          }
+
+          await delay(DEFAULT_GATT_BUSY_RETRY_DELAY_MS * (attempt + 1));
+        }
+      }
+
+      throw lastError;
+    };
+
+    const queued = this.gattOperationQueue.then(run, run);
+    this.gattOperationQueue = queued.then(
+      () => undefined,
+      () => undefined,
+    );
+    return queued;
+  }
+
   private normalizeDensity(value: number, task: "v4" | "b1"): number {
     if (task === "b1") {
       return Math.max(1, Math.min(5, Math.round(value)));