jc-printer-sdk-ts 0.1.1 → 0.1.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "jc-printer-sdk-ts",
   "type": "module",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "TypeScript surface for the JCPrintApi printer SDK",
   "license": "UNLICENSED",
   "keywords": [

package/src/client.ts

@@ -29,7 +29,9 @@ import type {
   PrinterSdkCallback,
   PrinterAddress,
   PrinterInfo,
+  PrinterReadiness,
   PrinterState,
+  PrinterStatusSnapshot,
   Point,
   ScanCallback,
 } from "./types.js";
@@ -54,6 +56,64 @@ function resolveBoolean(result: MaybePromise<boolean | void> | undefined): Maybe
   return typeof result === "boolean" ? result : true;
 }
 
+function createLocalReadiness(
+  state: PrinterState,
+  connection: number,
+): PrinterReadiness {
+  const connected = connection === 0 && state !== "Disconnected";
+  const status: PrinterStatusSnapshot = {
+    connected,
+    state,
+    statusAvailable: false,
+  };
+
+  if (!connected) {
+    return {
+      canPrint: false,
+      code: "not_connected",
+      reason: "Printer is not connected.",
+      warnings: [],
+      state,
+      connected,
+      status,
+    };
+  }
+
+  if (state === "Printing") {
+    return {
+      canPrint: false,
+      code: "sdk_printing",
+      reason: "A print job is already in progress.",
+      warnings: [],
+      state,
+      connected,
+      status,
+    };
+  }
+
+  if (state === "Working") {
+    return {
+      canPrint: false,
+      code: "printer_working",
+      reason: "Printer is currently working.",
+      warnings: [],
+      state,
+      connected,
+      status,
+    };
+  }
+
+  return {
+    canPrint: true,
+    code: "status_unavailable",
+    reason: "Printer is connected; live hardware status is not available in this transport.",
+    warnings: [],
+    state,
+    connected,
+    status,
+  };
+}
+
 function toPrinterAddress(device: BluetoothDeviceLike): PrinterAddress {
   return {
     macAddress: device.address,
@@ -417,6 +477,46 @@ export class PrinterClient {
     return this.transport.getPrinterInfo?.() ?? null;
   }
 
+  queryPrinterStatus(timeoutMs?: number): MaybePromise<PrinterStatusSnapshot> {
+    const status = this.transport.queryPrinterStatus?.(timeoutMs);
+    if (status) {
+      return status;
+    }
+
+    const state = this.getPrinterState();
+    const connection = this.isConnection();
+    if (isPromise(state) || isPromise(connection)) {
+      return Promise.all([state, connection]).then(([resolvedState, resolvedConnection]) => ({
+        connected: resolvedConnection === 0 && resolvedState !== "Disconnected",
+        state: resolvedState,
+        statusAvailable: false,
+      }));
+    }
+
+    return {
+      connected: connection === 0 && state !== "Disconnected",
+      state,
+      statusAvailable: false,
+    };
+  }
+
+  canStartPrintJob(timeoutMs?: number): MaybePromise<PrinterReadiness> {
+    const readiness = this.transport.canStartPrintJob?.(timeoutMs);
+    if (readiness) {
+      return readiness;
+    }
+
+    const state = this.getPrinterState();
+    const connection = this.isConnection();
+    if (isPromise(state) || isPromise(connection)) {
+      return Promise.all([state, connection]).then(([resolvedState, resolvedConnection]) =>
+        createLocalReadiness(resolvedState, resolvedConnection),
+      );
+    }
+
+    return createLocalReadiness(state, connection);
+  }
+
   getPrinterState(): MaybePromise<PrinterState> {
     return this.transport.getPrinterState?.() ?? "Disconnected";
   }

package/src/imagePrint.ts

@@ -98,6 +98,8 @@ export const DEFAULT_IMAGE_PRINT_SETTINGS: ResolvedImagePrintSettings = {
   meta: {},
 };
 
+const imagePrintQueues = new WeakMap<PrintableImageClient, Promise<void>>();
+
 function finiteNumber(value: number | undefined, fallback: number): number {
   return Number.isFinite(value) ? Number(value) : fallback;
 }
@@ -157,6 +159,22 @@ function toPrintCallback(callback?: Partial<PrintCallback>): PrintCallback {
   };
 }
 
+function queueImagePrintJob<T>(
+  printer: PrintableImageClient,
+  run: () => Promise<T>,
+): Promise<T> {
+  const previous = imagePrintQueues.get(printer) ?? Promise.resolve();
+  const queued = previous.catch(() => undefined).then(run);
+  imagePrintQueues.set(
+    printer,
+    queued.then(
+      () => undefined,
+      () => undefined,
+    ),
+  );
+  return queued;
+}
+
 export function fitRect(
   boxWidth: number,
   boxHeight: number,
@@ -253,28 +271,30 @@ export async function printImageData(
   sources: ImagePrintSource,
   settings: ImagePrintSettings,
 ): Promise<PrintImageResult> {
-  const resolved = normalizeSettings(settings);
-  const images = await loadImageSources(sources);
-  const document = buildPrintDocument(images, resolved);
-  const callback = toPrintCallback(resolved.callback);
-  let started = false;
+  return queueImagePrintJob(printer, async () => {
+    const resolved = normalizeSettings(settings);
+    const images = await loadImageSources(sources);
+    const document = buildPrintDocument(images, resolved);
+    const callback = toPrintCallback(resolved.callback);
+    let started = false;
 
-  try {
-    await printer.startPrintJob(resolved.density, resolved.paperType, resolved.printMode, callback);
-    started = true;
-    await printer.commitDocument(document);
-    await printer.endPrintJob();
-    return { document, images };
-  } catch (error) {
-    if (started && printer.cancelJob) {
-      try {
-        await printer.cancelJob();
-      } catch {
-        // Keep the original print error.
+    try {
+      await printer.startPrintJob(resolved.density, resolved.paperType, resolved.printMode, callback);
+      started = true;
+      await printer.commitDocument(document);
+      await printer.endPrintJob();
+      return { document, images };
+    } catch (error) {
+      if (started && printer.cancelJob) {
+        try {
+          await printer.cancelJob();
+        } catch {
+          // Keep the original print error.
+        }
       }
+      throw error;
     }
-    throw error;
-  }
+  });
 }
 
 export async function printCanvases(

package/src/transport.ts

@@ -8,8 +8,10 @@ import type {
   PrintDocument,
   PrinterDevice,
   PrinterInfo,
+  PrinterReadiness,
   PrinterSdkCallback,
   PrinterState,
+  PrinterStatusSnapshot,
   ScanCallback,
 } from "./types.js";
 
@@ -70,6 +72,8 @@ export interface PrinterTransport {
   getPrintScaleMultiplier?(): MaybePromise<number>;
   getPrinterName?(): MaybePromise<string>;
   getPrinterInfo?(): MaybePromise<PrinterInfo | null>;
+  queryPrinterStatus?(timeoutMs?: number): MaybePromise<PrinterStatusSnapshot>;
+  canStartPrintJob?(timeoutMs?: number): MaybePromise<PrinterReadiness>;
   getPrinterState?(): MaybePromise<PrinterState>;
   waitPrinterState?(
     state: PrinterState,
@@ -149,6 +153,60 @@ function defaultPaperInfo(): PaperInfo {
   };
 }
 
+function createMemoryPrinterStatus(state: PrinterState): PrinterStatusSnapshot {
+  return {
+    connected: state !== "Disconnected",
+    state,
+    statusAvailable: false,
+  };
+}
+
+function createMemoryReadiness(state: PrinterState): PrinterReadiness {
+  const status = createMemoryPrinterStatus(state);
+  if (!status.connected) {
+    return {
+      canPrint: false,
+      code: "not_connected",
+      reason: "Printer is not connected.",
+      warnings: [],
+      state,
+      connected: false,
+      status,
+    };
+  }
+  if (state === "Printing") {
+    return {
+      canPrint: false,
+      code: "sdk_printing",
+      reason: "A print job is already in progress.",
+      warnings: [],
+      state,
+      connected: true,
+      status,
+    };
+  }
+  if (state === "Working") {
+    return {
+      canPrint: false,
+      code: "printer_working",
+      reason: "Printer is currently working.",
+      warnings: [],
+      state,
+      connected: true,
+      status,
+    };
+  }
+  return {
+    canPrint: true,
+    code: "status_unavailable",
+    reason: "Printer is connected; live hardware status is not available in this transport.",
+    warnings: [],
+    state,
+    connected: true,
+    status,
+  };
+}
+
 function dimensionsFromInfo(info: string): Pick<BitmapLike, "width" | "height"> {
   try {
     const parsed = JSON.parse(info) as {
@@ -425,6 +483,14 @@ export class MemoryPrinterTransport implements PrinterTransport {
     return clone(this.printerInfo);
   }
 
+  queryPrinterStatus(): PrinterStatusSnapshot {
+    return createMemoryPrinterStatus(this.printerState);
+  }
+
+  canStartPrintJob(): PrinterReadiness {
+    return createMemoryReadiness(this.printerState);
+  }
+
   getPrinterState(): PrinterState {
     return this.printerState;
   }

package/src/types.ts

@@ -137,6 +137,50 @@ export interface PaperInfo {
   tailLength: number;
 }
 
+export interface PrinterStatusSnapshot {
+  connected: boolean;
+  state: PrinterState;
+  statusAvailable: boolean;
+  responseCommand?: number;
+  rawData?: number[];
+  chargeLevel?: number;
+  temperature?: number;
+  lidClosed?: boolean;
+  paperInserted?: boolean;
+  paperRfidSuccess?: boolean;
+  ribbonInserted?: boolean;
+  ribbonRfidSuccess?: boolean;
+  wifiRssi?: number;
+  lightingErrorCode?: number;
+  voltageState?: number;
+}
+
+export type PrinterReadinessCode =
+  | "ready"
+  | "status_unavailable"
+  | "not_connected"
+  | "sdk_printing"
+  | "printer_working"
+  | "cover_open"
+  | "paper_missing"
+  | "voltage_error";
+
+export type PrinterReadinessWarningCode =
+  | "paper_rfid_failed"
+  | "ribbon_missing"
+  | "ribbon_rfid_failed"
+  | "lighting_error";
+
+export interface PrinterReadiness {
+  canPrint: boolean;
+  code: PrinterReadinessCode;
+  reason: string;
+  warnings: PrinterReadinessWarningCode[];
+  state: PrinterState;
+  connected: boolean;
+  status?: PrinterStatusSnapshot;
+}
+
 export interface ColorSupport {
   normalMode: number;
   rbMode: number;