react-native-telpo 1.0.0

package/src/printer/index.ts

@@ -0,0 +1,432 @@
+/**
+ * TelpoPrinter
+ *
+ * Wraps @haroldtran/react-native-thermal-printer to provide a clean, typed API
+ * for Telpo M1 and TPS320 internal (USB) thermal printers.
+ *
+ * Connection priority: USB (internal) → Bluetooth → Network
+ */
+
+import { Platform } from 'react-native';
+import {
+  TelpoError,
+  TelpoErrorCode,
+  TelpoResult,
+  PrinterDevice,
+  PrinterOptions,
+  PrintLine,
+  PrintTicket,
+  PrintReceiptOptions,
+  PrintAlignment,
+  PrintFontSize,
+} from '../types';
+
+// Lazy-loaded to avoid crashing if peer dep is missing
+let USBPrinter: any;
+let BLEPrinter: any;
+let NetPrinter: any;
+let COMMANDS: any;
+
+function loadPrinterLib(): void {
+  try {
+    const lib = require('@haroldtran/react-native-thermal-printer');
+    USBPrinter = lib.USBPrinter;
+    BLEPrinter = lib.BLEPrinter;
+    NetPrinter = lib.NetPrinter;
+    COMMANDS = lib.COMMANDS;
+  } catch {
+    throw buildError(
+      TelpoErrorCode.PRINTER_INIT_FAILED,
+      'Peer dependency @haroldtran/react-native-thermal-printer is not installed. Run: npm install @haroldtran/react-native-thermal-printer'
+    );
+  }
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function buildError(code: TelpoErrorCode, message: string, raw?: unknown): TelpoError {
+  return { code, message, raw };
+}
+
+function wrapSuccess<T>(data: T): TelpoResult<T> {
+  return { success: true, data };
+}
+
+function wrapError<T>(error: TelpoError): TelpoResult<T> {
+  return { success: false, error };
+}
+
+function alignCmd(alignment: PrintAlignment): string {
+  if (!COMMANDS) return '';
+  switch (alignment) {
+    case 'LEFT':   return COMMANDS.TEXT_FORMAT.TXT_ALIGN_LT;
+    case 'CENTER': return COMMANDS.TEXT_FORMAT.TXT_ALIGN_CT;
+    case 'RIGHT':  return COMMANDS.TEXT_FORMAT.TXT_ALIGN_RT;
+  }
+}
+
+function fontSizeCmd(size: PrintFontSize): string {
+  if (!COMMANDS) return '';
+  switch (size) {
+    case 'SMALL':  return COMMANDS.TEXT_FORMAT.TXT_CUSTOM_SIZE(1, 1);
+    case 'NORMAL': return COMMANDS.TEXT_FORMAT.TXT_CUSTOM_SIZE(1, 1);
+    case 'LARGE':  return COMMANDS.TEXT_FORMAT.TXT_CUSTOM_SIZE(2, 2);
+    case 'DOUBLE': return COMMANDS.TEXT_FORMAT.TXT_CUSTOM_SIZE(2, 2);
+  }
+}
+
+function repeatChar(char: string, times: number): string {
+  return char.repeat(times);
+}
+
+const DIVIDER = repeatChar('-', 32);
+const THICK_DIVIDER = repeatChar('=', 32);
+
+/** Build a formatted two-column line: "Label         Value" */
+function twoCol(label: string, value: string, width = 32): string {
+  const gap = width - label.length - value.length;
+  return label + repeatChar(' ', Math.max(1, gap)) + value;
+}
+
+function nowString(): string {
+  const d = new Date();
+  const pad = (n: number) => String(n).padStart(2, '0');
+  return (
+    `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ` +
+    `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`
+  );
+}
+
+// ── State ─────────────────────────────────────────────────────────────────────
+
+type ActivePrinterType = 'USB' | 'BLUETOOTH' | 'NETWORK' | null;
+
+let _initialized = false;
+let _activePrinterType: ActivePrinterType = null;
+
+// ── Module ────────────────────────────────────────────────────────────────────
+
+/**
+ * TelpoPrinter
+ *
+ * @example
+ * // Connect to internal USB printer (M1 / TPS320)
+ * await TelpoPrinter.init();
+ * const devices = await TelpoPrinter.getDeviceList();
+ * await TelpoPrinter.connect({ connectionType: 'USB' });
+ *
+ * // Print a bus ticket
+ * await TelpoPrinter.printTicket({
+ *   ticketId: 'TKT-001234',
+ *   route: 'Route 42 — City Centre → Airport',
+ *   passenger: 'John Doe',
+ *   fare: 'SLE 5.00',
+ * });
+ */
+export const TelpoPrinter = {
+  get _initialized(): boolean {
+    return _initialized;
+  },
+  set _initialized(value: boolean) {
+    _initialized = value;
+  },
+
+  get _activePrinterType(): ActivePrinterType {
+    return _activePrinterType;
+  },
+  set _activePrinterType(value: ActivePrinterType) {
+    _activePrinterType = value;
+  },
+
+  /**
+   * Initialise the printer module.
+   * Must be called once before any other method.
+   * On Android only — iOS has no USB printer support.
+   */
+  async init(): Promise<TelpoResult<void>> {
+    if (Platform.OS !== 'android') {
+      return wrapError(
+        buildError(TelpoErrorCode.PRINTER_INIT_FAILED, 'Thermal printing is only supported on Android.')
+      );
+    }
+
+    try {
+      loadPrinterLib();
+      await USBPrinter.init();
+      _initialized = true;
+      return wrapSuccess(undefined);
+    } catch (e: unknown) {
+      const err = e as TelpoError;
+      if (err.code) return wrapError(err);
+      return wrapError(buildError(TelpoErrorCode.PRINTER_INIT_FAILED, 'Failed to initialise printer', e));
+    }
+  },
+
+  /**
+   * List all available USB printer devices.
+   * Returns empty array on non-Android platforms.
+   */
+  async getDeviceList(): Promise<TelpoResult<PrinterDevice[]>> {
+    if (!_initialized) {
+      return wrapError(buildError(TelpoErrorCode.PRINTER_INIT_FAILED, 'Call TelpoPrinter.init() first.'));
+    }
+    try {
+      const devices: PrinterDevice[] = await USBPrinter.getDeviceList();
+      return wrapSuccess(devices);
+    } catch (e) {
+      return wrapError(buildError(TelpoErrorCode.PRINTER_INIT_FAILED, 'Failed to list printer devices', e));
+    }
+  },
+
+  /**
+   * Connect to the printer.
+   *
+   * - `USB` (default): connects to the first available USB device automatically.
+   *   For Telpo M1 / TPS320 this is the internal printer — no vendorId/productId needed.
+   * - `BLUETOOTH`: requires `bluetoothAddress`.
+   * - `NETWORK`: requires `networkHost` (and optionally `networkPort`, default 9100).
+   */
+  async connect(options: PrinterOptions = {}): Promise<TelpoResult<void>> {
+    if (!_initialized && options.connectionType !== 'BLUETOOTH' && options.connectionType !== 'NETWORK') {
+      const initResult = await TelpoPrinter.init();
+      if (!initResult.success) return initResult;
+    }
+
+    const type = options.connectionType ?? 'USB';
+
+    try {
+      if (type === 'USB') {
+        const devResult = await TelpoPrinter.getDeviceList();
+        if (!devResult.success) return devResult;
+
+        const devices = devResult.data;
+        if (devices.length === 0) {
+          return wrapError(
+            buildError(TelpoErrorCode.PRINTER_NOT_CONNECTED, 'No USB printer devices found. Make sure the device has an internal printer.')
+          );
+        }
+
+        const device = devices[0]!;
+        await USBPrinter.connectPrinter(device.vendorId, device.productId);
+        _activePrinterType = 'USB';
+      } else if (type === 'BLUETOOTH') {
+        if (!options.bluetoothAddress) {
+          return wrapError(
+            buildError(TelpoErrorCode.PRINTER_NOT_CONNECTED, 'bluetoothAddress is required for Bluetooth connection.')
+          );
+        }
+        await BLEPrinter.init();
+        await BLEPrinter.connectPrinter(options.bluetoothAddress);
+        _activePrinterType = 'BLUETOOTH';
+      } else if (type === 'NETWORK') {
+        if (!options.networkHost) {
+          return wrapError(
+            buildError(TelpoErrorCode.PRINTER_NOT_CONNECTED, 'networkHost is required for Network connection.')
+          );
+        }
+        await NetPrinter.init();
+        await NetPrinter.connectPrinter(options.networkHost, options.networkPort ?? 9100);
+        _activePrinterType = 'NETWORK';
+      }
+
+      return wrapSuccess(undefined);
+    } catch (e) {
+      _activePrinterType = null;
+      return wrapError(buildError(TelpoErrorCode.PRINTER_NOT_CONNECTED, 'Failed to connect to printer', e));
+    }
+  },
+
+  /** Disconnect from the printer and release resources. */
+  async disconnect(): Promise<TelpoResult<void>> {
+    try {
+      if (_activePrinterType === 'USB') await USBPrinter.closeConn();
+      else if (_activePrinterType === 'BLUETOOTH') await BLEPrinter.closeConn();
+      else if (_activePrinterType === 'NETWORK') await NetPrinter.closeConn();
+      _activePrinterType = null;
+      return wrapSuccess(undefined);
+    } catch (e) {
+      return wrapError(buildError(TelpoErrorCode.PRINTER_PRINT_FAILED, 'Failed to disconnect printer', e));
+    }
+  },
+
+  /**
+   * Print an array of custom lines. Full control over alignment, bold, and font size.
+   *
+   * @example
+   * await TelpoPrinter.printLines([
+   *   { text: 'CITY BUS', alignment: 'CENTER', bold: true, fontSize: 'LARGE' },
+   *   { text: 'Ticket ID: TKT-0012', alignment: 'LEFT' },
+   * ]);
+   */
+  async printLines(
+    lines: PrintLine[],
+    options: PrintReceiptOptions = {}
+  ): Promise<TelpoResult<void>> {
+    if (!_activePrinterType) {
+      return wrapError(buildError(TelpoErrorCode.PRINTER_NOT_CONNECTED, 'Not connected. Call TelpoPrinter.connect() first.'));
+    }
+
+    try {
+      const printer = _getPrinter();
+      let output = '';
+
+      for (const line of lines) {
+        const align  = alignCmd(line.alignment ?? 'LEFT');
+        const size   = fontSizeCmd(line.fontSize ?? 'NORMAL');
+        const bold   = line.bold ? COMMANDS.TEXT_FORMAT.TXT_BOLD_ON : COMMANDS.TEXT_FORMAT.TXT_BOLD_OFF;
+        const uline  = line.underline ? COMMANDS.TEXT_FORMAT.TXT_UNDERL_ON : COMMANDS.TEXT_FORMAT.TXT_UNDERL_OFF;
+        const reset  = COMMANDS.TEXT_FORMAT.TXT_NORMAL;
+
+        output += `${align}${size}${bold}${uline}${line.text}${reset}\n`;
+      }
+
+      const feedLines = options.feedLines ?? 4;
+      output += '\n'.repeat(feedLines);
+
+      if (options.cutPaper !== false) {
+        output += COMMANDS.PAPER.PAPER_FULL_CUT;
+      }
+
+      await printer.printText(output);
+      return wrapSuccess(undefined);
+    } catch (e) {
+      return wrapError(buildError(TelpoErrorCode.PRINTER_PRINT_FAILED, 'Failed to print lines', e));
+    }
+  },
+
+  /**
+   * Print a formatted bus ticket receipt.
+   * Automatically formats header, route, passenger info,
+   * ticket ID, fare, and optional QR code.
+   *
+   * @example
+   * await TelpoPrinter.printTicket({
+   *   operatorName: 'City Bus Services',
+   *   route: 'Route 42 — City Centre → Airport',
+   *   passenger: 'John Doe',
+   *   ticketId: 'TKT-001234',
+   *   fare: 'SLE 5.00',
+   *   footer: 'Thank you for travelling with us!',
+   * });
+   */
+  async printTicket(
+    ticket: PrintTicket,
+    options: PrintReceiptOptions = {}
+  ): Promise<TelpoResult<void>> {
+    if (!_activePrinterType) {
+      return wrapError(buildError(TelpoErrorCode.PRINTER_NOT_CONNECTED, 'Not connected. Call TelpoPrinter.connect() first.'));
+    }
+
+    try {
+      const printer = _getPrinter();
+      const dateTime = ticket.dateTime ?? nowString();
+      const qrValue = ticket.qrValue ?? ticket.ticketId;
+
+      // Build ESC/POS string
+      let out = '';
+      const C = COMMANDS.TEXT_FORMAT;
+      const P = COMMANDS.PAPER;
+
+      const centerBoldLarge = `${C.TXT_ALIGN_CT}${C.TXT_CUSTOM_SIZE(2, 2)}${C.TXT_BOLD_ON}`;
+      const centerNormal    = `${C.TXT_ALIGN_CT}${C.TXT_NORMAL}`;
+      const leftNormal      = `${C.TXT_ALIGN_LT}${C.TXT_NORMAL}`;
+      const reset           = C.TXT_NORMAL;
+
+      // ── Header ──
+      if (ticket.operatorName) {
+        out += `${centerBoldLarge}${ticket.operatorName}${reset}\n`;
+      }
+
+      out += `${centerNormal}BUS TICKET\n`;
+      out += `${leftNormal}${THICK_DIVIDER}\n`;
+
+      // ── Route ──
+      if (ticket.route) {
+        out += `${leftNormal}${ticket.route}\n`;
+        out += `${leftNormal}${DIVIDER}\n`;
+      }
+
+      // ── Details ──
+      if (ticket.passenger) {
+        out += `${leftNormal}${twoCol('Passenger:', ticket.passenger)}\n`;
+      }
+
+      out += `${leftNormal}${twoCol('Date/Time:', dateTime)}\n`;
+      out += `${leftNormal}${twoCol('Ticket ID:', ticket.ticketId)}\n`;
+
+      if (ticket.fare) {
+        out += `${leftNormal}${twoCol('Fare:', ticket.fare)}\n`;
+      }
+
+      // ── Extras ──
+      if (ticket.extras) {
+        for (const [key, value] of Object.entries(ticket.extras)) {
+          out += `${leftNormal}${twoCol(`${key}:`, value)}\n`;
+        }
+      }
+
+      out += `${leftNormal}${THICK_DIVIDER}\n`;
+
+      // ── QR Code ──
+      out += `${centerNormal}`;
+      out += COMMANDS.BARCODE?.QR_CODE_256?.(qrValue) ?? '';
+      out += '\n';
+
+      // ── Footer ──
+      if (ticket.footer) {
+        out += `${centerNormal}${ticket.footer}\n`;
+      }
+
+      // ── Feed + Cut ──
+      const feedLines = options.feedLines ?? 4;
+      out += '\n'.repeat(feedLines);
+      if (options.cutPaper !== false) {
+        out += P.PAPER_FULL_CUT;
+      }
+
+      await printer.printText(out);
+      return wrapSuccess(undefined);
+    } catch (e) {
+      return wrapError(buildError(TelpoErrorCode.PRINTER_PRINT_FAILED, 'Failed to print ticket', e));
+    }
+  },
+
+  /**
+   * Print raw ESC/POS text. Use when you need full manual control.
+   */
+  async printRaw(rawText: string): Promise<TelpoResult<void>> {
+    if (!_activePrinterType) {
+      return wrapError(buildError(TelpoErrorCode.PRINTER_NOT_CONNECTED, 'Not connected. Call TelpoPrinter.connect() first.'));
+    }
+    try {
+      await _getPrinter().printText(rawText);
+      return wrapSuccess(undefined);
+    } catch (e) {
+      return wrapError(buildError(TelpoErrorCode.PRINTER_PRINT_FAILED, 'Failed to print raw text', e));
+    }
+  },
+
+  /** Feed paper by N lines without printing. */
+  async feedPaper(lines = 3): Promise<TelpoResult<void>> {
+    return TelpoPrinter.printRaw('\n'.repeat(lines));
+  },
+
+  /** Whether the printer is currently connected. */
+  isConnected(): boolean {
+    return _activePrinterType !== null;
+  },
+
+  /** Returns the current connection type, or null if not connected. */
+  getConnectionType(): ActivePrinterType {
+    return _activePrinterType;
+  },
+};
+
+function _getPrinter() {
+  if (_activePrinterType === 'USB') return USBPrinter;
+  if (_activePrinterType === 'BLUETOOTH') return BLEPrinter;
+  if (_activePrinterType === 'NETWORK') return NetPrinter;
+  throw buildError(TelpoErrorCode.PRINTER_NOT_CONNECTED, 'No active printer connection.');
+}
+
+export type { PrinterDevice, PrinterOptions, PrintLine, PrintTicket, PrintReceiptOptions };