@thermal-label/brother-ql-core 0.0.1 → 0.2.1

package/src/status.ts

@@ -1,67 +1,83 @@
-import { type PrinterStatus, type MediaType } from './types.js';
+/* eslint-disable import-x/consistent-type-specifier-style */
+import type { PrinterError } from '@thermal-label/contracts';
+import { type BrotherQLStatus } from './types.js';
+import { findMediaByDimensions } from './media.js';
 
-const ERROR_INFO_1: Record<number, string> = {
-  0: 'No media',
-  1: 'End of media',
-  2: 'Cutter jam',
-  3: 'Weak battery',
-  4: 'Printer in use',
-  6: 'High voltage adapter',
-  7: 'Fan motor error',
-};
+export const STATUS_REQUEST = new Uint8Array([0x1b, 0x69, 0x53]);
+
+/** Error-info 1 bit → structured PrinterError code + human message. */
+const ERROR_INFO_1: { bit: number; code: string; message: string }[] = [
+  { bit: 0, code: 'no_media', message: 'No media' },
+  { bit: 1, code: 'media_end', message: 'End of media' },
+  { bit: 2, code: 'cutter_jam', message: 'Cutter jam' },
+  { bit: 3, code: 'system_error', message: 'Weak battery' },
+  { bit: 4, code: 'not_ready', message: 'Printer in use' },
+  { bit: 6, code: 'system_error', message: 'High voltage adapter' },
+  { bit: 7, code: 'system_error', message: 'Fan motor error' },
+];
 
-const ERROR_INFO_2: Record<number, string> = {
-  0: 'Replace media',
-  1: 'Expansion buffer full',
-  2: 'Transmission error',
-  3: 'Communication buffer full',
-  4: 'Cover open',
-  5: 'Cancel key',
-  6: 'Media cannot be fed',
-  7: 'System error',
-};
+/** Error-info 2 bit → structured PrinterError code + human message. */
+const ERROR_INFO_2: { bit: number; code: string; message: string }[] = [
+  { bit: 0, code: 'wrong_media', message: 'Replace media' },
+  { bit: 1, code: 'system_error', message: 'Expansion buffer full' },
+  { bit: 2, code: 'system_error', message: 'Transmission error' },
+  { bit: 3, code: 'system_error', message: 'Communication buffer full' },
+  { bit: 4, code: 'cover_open', message: 'Cover open' },
+  { bit: 5, code: 'not_ready', message: 'Cancel key pressed' },
+  { bit: 6, code: 'media_end', message: 'Media cannot be fed' },
+  { bit: 7, code: 'system_error', message: 'System error' },
+];
 
-export function parseStatus(bytes: Uint8Array): PrinterStatus {
-  if (bytes.length < 32)
+/**
+ * Parse a Brother QL 32-byte status response.
+ *
+ * Fields:
+ *   byte 8  — error info 1 (bit mask, see ERROR_INFO_1)
+ *   byte 9  — error info 2 (bit mask, see ERROR_INFO_2)
+ *   byte 10 — media width (mm)
+ *   byte 11 — media type (0x0A continuous, 0x0B die-cut)
+ *   byte 17 — media length (mm), 0 for continuous
+ *   byte 18 — status type (0x02 = error response)
+ *
+ * `detectedMedia` is resolved against the media registry via
+ * `findMediaByDimensions`. `editorLiteMode` is a driver-specific
+ * extension on `BrotherQLStatus` — the status-type byte doesn't
+ * actually report it, but keeping the field here means callers can
+ * set it from other signals (e.g. mass-storage PID detected during
+ * discovery) without changing the return type.
+ */
+export function parseStatus(bytes: Uint8Array): BrotherQLStatus {
+  if (bytes.length < 32) {
     throw new Error(`Status response too short: ${bytes.length.toString()} bytes`);
+  }
 
-  // noUncheckedIndexedAccess forces `?? 0` fallbacks that are unreachable after
-  // the length check above. DataView avoids the issue: getUint8 returns number.
   const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
-
-  const errors: string[] = [];
   const errInfo1 = view.getUint8(8);
   const errInfo2 = view.getUint8(9);
-
-  for (const [bitStr, msg] of Object.entries(ERROR_INFO_1)) {
-    if (errInfo1 & (1 << Number(bitStr))) errors.push(msg);
-  }
-  for (const [bitStr, msg] of Object.entries(ERROR_INFO_2)) {
-    if (errInfo2 & (1 << Number(bitStr))) errors.push(msg);
-  }
-
   const mediaWidthMm = view.getUint8(10);
   const mediaTypeByte = view.getUint8(11);
   const mediaLengthMm = view.getUint8(17);
+  const statusType = view.getUint8(18);
 
-  let mediaType: MediaType | null = null;
-  if (mediaTypeByte === 0x0a) mediaType = 'continuous';
-  else if (mediaTypeByte === 0x0b) mediaType = 'die-cut';
+  const errors: PrinterError[] = [];
+  for (const { bit, code, message } of ERROR_INFO_1) {
+    if (errInfo1 & (1 << bit)) errors.push({ code, message });
+  }
+  for (const { bit, code, message } of ERROR_INFO_2) {
+    if (errInfo2 & (1 << bit)) errors.push({ code, message });
+  }
 
-  // Status type is at byte 18, not 14. Byte 14 is an undocumented media-type
-  // code that carries non-zero values and is not the status type field.
-  const statusType = view.getUint8(18);
-  const ready = errors.length === 0 && statusType !== 0x02;
+  const mediaLoaded = mediaWidthMm > 0 && mediaTypeByte !== 0;
+  const detected = mediaLoaded
+    ? findMediaByDimensions(mediaWidthMm, mediaLengthMm, false)
+    : undefined;
 
   return {
-    ready,
-    mediaWidthMm,
-    mediaLengthMm,
-    mediaType,
+    ready: errors.length === 0 && statusType !== 0x02,
+    mediaLoaded,
+    ...(detected === undefined ? {} : { detectedMedia: detected }),
     errors,
     editorLiteMode: false,
     rawBytes: bytes,
   };
 }
-
-export const STATUS_REQUEST = new Uint8Array([0x1b, 0x69, 0x53]);

package/src/types.ts

@@ -1,43 +1,71 @@
+/* eslint-disable import-x/consistent-type-specifier-style */
 import { type LabelBitmap } from '@mbtech-nl/bitmap';
+import type { DeviceDescriptor, MediaDescriptor, PrinterStatus } from '@thermal-label/contracts';
 
 export type MediaType = 'continuous' | 'die-cut';
 export type HeadWidth = 720 | 1296;
 export type ColorMode = 'single' | 'two-color';
 export type NetworkSupport = 'none' | 'wifi' | 'wired' | 'wifi+wired';
 
-export interface DeviceDescriptor {
-  name: string;
+/**
+ * Brother QL device descriptor.
+ *
+ * Extends the contracts base with QL-specific fields: head geometry,
+ * protocol feature flags, and the optional mass-storage PID for Editor
+ * Lite mode.
+ *
+ * **Bluetooth on the QL-820NWB / 820NWBc**: not exposed over GATT.
+ * Classic Bluetooth (SPP) is paired at the OS level; the kernel/driver
+ * exposes an RFCOMM serial port, reachable via the `'serial'` transport
+ * in Node.js and the `'web-serial'` transport in Chrome/Edge. macOS has
+ * dropped classic Bluetooth SPP — no serial route there.
+ */
+export interface BrotherQLDevice extends DeviceDescriptor {
+  family: 'brother-ql';
   vid: number;
   pid: number;
   headPins: HeadWidth;
   bytesPerRow: number;
   twoColor: boolean;
   network: NetworkSupport;
-  bluetooth: boolean;
   autocut: boolean;
   compression: boolean;
   editorLite: boolean;
+  /** Alternate PID seen when the printer is in Editor Lite mass-storage mode. */
   massStoragePid?: number;
 }
 
-export interface MediaDescriptor {
+/**
+ * Brother QL media descriptor.
+ *
+ * Extends `MediaDescriptor` with the dots-based geometry the raster
+ * encoder needs. `colorCapable: true` flips the driver into
+ * two-colour mode — only DK-22251 has this set in the registry.
+ */
+export interface BrotherQLMedia extends MediaDescriptor {
   id: number;
-  name: string;
   type: MediaType;
-  widthMm: number;
-  lengthMm: number;
+  colorCapable: boolean;
   printAreaDots: number;
   leftMarginPins: number;
   rightMarginPins: number;
+  /** Die-cut masked area in dots (registration windows). */
   dieCutMaskedAreaDots?: number;
-  /** True for DK-22251 and similar two-color tapes — printer rejects single-color jobs */
-  twoColorTape?: boolean;
+}
+
+/**
+ * Brother QL status — contracts `PrinterStatus` plus the
+ * `editorLiteMode` flag (pre-paired QL-820NWB silently drops raster
+ * jobs when in Editor Lite mode; callers need to know).
+ */
+export interface BrotherQLStatus extends PrinterStatus {
+  editorLiteMode: boolean;
 }
 
 export interface PageData {
   bitmap: LabelBitmap;
   redBitmap?: LabelBitmap;
-  media: MediaDescriptor;
+  media: BrotherQLMedia;
   options?: PageOptions;
 }
 
@@ -52,26 +80,3 @@ export interface PageOptions {
 export interface JobOptions {
   copies?: number;
 }
-
-export interface TextPrintOptions extends PageOptions {
-  invert?: boolean;
-  scaleX?: number;
-  scaleY?: number;
-}
-
-export interface ImagePrintOptions extends PageOptions {
-  threshold?: number;
-  dither?: boolean;
-  invert?: boolean;
-  rotate?: 0 | 90 | 180 | 270;
-}
-
-export interface PrinterStatus {
-  ready: boolean;
-  mediaWidthMm: number;
-  mediaLengthMm: number;
-  mediaType: MediaType | null;
-  errors: string[];
-  editorLiteMode: boolean;
-  rawBytes: Uint8Array;
-}