taro-bluetooth-print 2.2.0 → 2.3.0

package/dist/types/adapters/AdapterFactory.d.ts

@@ -1,6 +1,5 @@
 import { IPrinterAdapter } from '../types';
 import { PlatformType } from '../utils/platform';
-
 /**
  * Adapter factory class
  */

package/dist/types/adapters/AlipayAdapter.d.ts

@@ -1,9 +1,10 @@
-import { IAdapterOptions } from '../types';
-import { BaseAdapter } from './BaseAdapter';
-
+import { MiniProgramAdapter, MiniProgramBLEApi } from './BaseAdapter';
 /**
  * Alipay Bluetooth Low Energy adapter
  *
+ * Uses the Alipay mini-program's BLE APIs (my.xxx).
+ * All connection, write, and service discovery logic is inherited from MiniProgramAdapter.
+ *
  * @example
  * ```typescript
  * const adapter = new AlipayAdapter();
@@ -12,35 +13,6 @@ import { BaseAdapter } from './BaseAdapter';
  * await adapter.disconnect('device-id-123');
  * ```
  */
-export declare class AlipayAdapter extends BaseAdapter {
-    /**
-     * Connects to a Bluetooth device and discovers services
-     *
-     * @param deviceId - Bluetooth device ID
-     * @throws {BluetoothPrintError} When connection fails
-     */
-    connect(deviceId: string): Promise<void>;
-    /**
-     * Disconnects from a Bluetooth device
-     *
-     * @param deviceId - Bluetooth device ID
-     */
-    disconnect(deviceId: string): Promise<void>;
-    /**
-     * Writes data to the Bluetooth device in chunks with retry logic
-     *
-     * @param deviceId - Bluetooth device ID
-     * @param buffer - Data to write as ArrayBuffer
-     * @param options - Write options (chunk size, delay, retries)
-     * @throws {BluetoothPrintError} When write fails after retries
-     */
-    write(deviceId: string, buffer: ArrayBuffer, options?: IAdapterOptions): Promise<void>;
-    /**
-     * Discovers services and characteristics for a device
-     * Caches the writeable characteristic for future writes
-     *
-     * @param deviceId - Bluetooth device ID
-     * @throws {BluetoothPrintError} When no writeable characteristic is found
-     */
-    private discoverServices;
+export declare class AlipayAdapter extends MiniProgramAdapter {
+    protected getApi(): MiniProgramBLEApi;
 }

package/dist/types/adapters/BaiduAdapter.d.ts

@@ -1,9 +1,10 @@
-import { IAdapterOptions } from '../types';
-import { BaseAdapter } from './BaseAdapter';
-
+import { MiniProgramAdapter, MiniProgramBLEApi } from './BaseAdapter';
 /**
  * Baidu Bluetooth Low Energy adapter
  *
+ * Uses the Baidu smart program's BLE APIs (swan.xxx).
+ * All connection, write, and service discovery logic is inherited from MiniProgramAdapter.
+ *
  * @example
  * ```typescript
  * const adapter = new BaiduAdapter();
@@ -12,35 +13,6 @@ import { BaseAdapter } from './BaseAdapter';
  * await adapter.disconnect('device-id-123');
  * ```
  */
-export declare class BaiduAdapter extends BaseAdapter {
-    /**
-     * Connects to a Bluetooth device and discovers services
-     *
-     * @param deviceId - Bluetooth device ID
-     * @throws {BluetoothPrintError} When connection fails
-     */
-    connect(deviceId: string): Promise<void>;
-    /**
-     * Disconnects from a Bluetooth device
-     *
-     * @param deviceId - Bluetooth device ID
-     */
-    disconnect(deviceId: string): Promise<void>;
-    /**
-     * Writes data to the Bluetooth device in chunks with retry logic
-     *
-     * @param deviceId - Bluetooth device ID
-     * @param buffer - Data to write as ArrayBuffer
-     * @param options - Write options (chunk size, delay, retries)
-     * @throws {BluetoothPrintError} When write fails after retries
-     */
-    write(deviceId: string, buffer: ArrayBuffer, options?: IAdapterOptions): Promise<void>;
-    /**
-     * Discovers services and characteristics for a device
-     * Caches the writeable characteristic for future writes
-     *
-     * @param deviceId - Bluetooth device ID
-     * @throws {BluetoothPrintError} When no writeable characteristic is found
-     */
-    private discoverServices;
+export declare class BaiduAdapter extends MiniProgramAdapter {
+    protected getApi(): MiniProgramBLEApi;
 }

package/dist/types/adapters/BaseAdapter.d.ts

@@ -1,5 +1,4 @@
 import { IPrinterAdapter, IAdapterOptions, PrinterState } from '../types';
-
 /**
  * Service information cache entry
  */
@@ -7,6 +6,64 @@ export interface ServiceInfo {
     serviceId: string;
     characteristicId: string;
 }
+/**
+ * BLE characteristic properties (common across all mini-program platforms)
+ */
+export interface BLECharacteristicProperties {
+    write?: boolean;
+    writeWithoutResponse?: boolean;
+    read?: boolean;
+    notify?: boolean;
+    indicate?: boolean;
+}
+/**
+ * BLE characteristic (common across all mini-program platforms)
+ */
+export interface BLECharacteristic {
+    uuid: string;
+    properties: BLECharacteristicProperties;
+}
+/**
+ * Unified mini-program BLE API interface.
+ * All mini-program platforms (Taro/WeChat, Alipay, Baidu, ByteDance)
+ * share the same API shape, only the global object differs.
+ */
+export interface MiniProgramBLEApi {
+    createBLEConnection(options: {
+        deviceId: string;
+    }): Promise<void>;
+    closeBLEConnection(options: {
+        deviceId: string;
+    }): Promise<void>;
+    getBLEConnectionState(options: {
+        deviceId: string;
+    }): Promise<{
+        connected: boolean;
+    }>;
+    writeBLECharacteristicValue(options: {
+        deviceId: string;
+        serviceId: string;
+        characteristicId: string;
+        value: ArrayBuffer;
+    }): Promise<void>;
+    getBLEDeviceServices(options: {
+        deviceId: string;
+    }): Promise<{
+        services: Array<{
+            uuid: string;
+        }>;
+    }>;
+    getBLEDeviceCharacteristics(options: {
+        deviceId: string;
+        serviceId: string;
+    }): Promise<{
+        characteristics: BLECharacteristic[];
+    }>;
+    onBLEConnectionStateChange(callback: (res: {
+        deviceId: string;
+        connected: boolean;
+    }) => void): void;
+}
 /**
  * Base adapter class that provides common functionality for all platform-specific adapters
  */
@@ -91,3 +148,57 @@ export declare abstract class BaseAdapter implements IPrinterAdapter {
      */
     protected cleanupDevice(deviceId: string): void;
 }
+/**
+ * Base adapter for mini-program platforms (Taro/WeChat, Alipay, Baidu, ByteDance).
+ *
+ * Implements connect/disconnect/write/discoverServices once with adaptive transmission.
+ * Subclasses only need to implement `getApi()` to return the platform-specific BLE API object.
+ */
+export declare abstract class MiniProgramAdapter extends BaseAdapter {
+    /**
+     * Returns the platform-specific BLE API object.
+     * Subclasses must implement this to return the appropriate global (Taro, my, swan, tt).
+     */
+    protected abstract getApi(): MiniProgramBLEApi;
+    /**
+     * Connects to a Bluetooth device and discovers services
+     *
+     * @param deviceId - Bluetooth device ID
+     * @throws {BluetoothPrintError} When connection fails
+     */
+    connect(deviceId: string): Promise<void>;
+    /**
+     * Disconnects from a Bluetooth device
+     *
+     * @param deviceId - Bluetooth device ID
+     */
+    disconnect(deviceId: string): Promise<void>;
+    /**
+     * Writes data to the Bluetooth device in chunks with adaptive transmission.
+     *
+     * Features:
+     * - Automatic chunk size adjustment based on success/failure rate
+     * - Dynamic delay adjustment for congestion control
+     * - Periodic connection state checks
+     * - Exponential backoff for retries
+     * - Write timeout per chunk
+     *
+     * @param deviceId - Bluetooth device ID
+     * @param buffer - Data to write as ArrayBuffer
+     * @param options - Write options (chunk size, delay, retries)
+     * @throws {BluetoothPrintError} When write fails after retries
+     */
+    write(deviceId: string, buffer: ArrayBuffer, options?: IAdapterOptions): Promise<void>;
+    /**
+     * Check connection state, throw if disconnected
+     */
+    private checkConnectionState;
+    /**
+     * Discovers services and characteristics for a device.
+     * Caches the writeable characteristic for future writes.
+     *
+     * @param deviceId - Bluetooth device ID
+     * @throws {BluetoothPrintError} When no writeable characteristic is found
+     */
+    private discoverServices;
+}

package/dist/types/adapters/ByteDanceAdapter.d.ts

@@ -1,9 +1,10 @@
-import { IAdapterOptions } from '../types';
-import { BaseAdapter } from './BaseAdapter';
-
+import { MiniProgramAdapter, MiniProgramBLEApi } from './BaseAdapter';
 /**
  * ByteDance Bluetooth Low Energy adapter
  *
+ * Uses the ByteDance mini-program's BLE APIs (tt.xxx, for Douyin/TikTok etc).
+ * All connection, write, and service discovery logic is inherited from MiniProgramAdapter.
+ *
  * @example
  * ```typescript
  * const adapter = new ByteDanceAdapter();
@@ -12,35 +13,6 @@ import { BaseAdapter } from './BaseAdapter';
  * await adapter.disconnect('device-id-123');
  * ```
  */
-export declare class ByteDanceAdapter extends BaseAdapter {
-    /**
-     * Connects to a Bluetooth device and discovers services
-     *
-     * @param deviceId - Bluetooth device ID
-     * @throws {BluetoothPrintError} When connection fails
-     */
-    connect(deviceId: string): Promise<void>;
-    /**
-     * Disconnects from a Bluetooth device
-     *
-     * @param deviceId - Bluetooth device ID
-     */
-    disconnect(deviceId: string): Promise<void>;
-    /**
-     * Writes data to the Bluetooth device in chunks with retry logic
-     *
-     * @param deviceId - Bluetooth device ID
-     * @param buffer - Data to write as ArrayBuffer
-     * @param options - Write options (chunk size, delay, retries)
-     * @throws {BluetoothPrintError} When write fails after retries
-     */
-    write(deviceId: string, buffer: ArrayBuffer, options?: IAdapterOptions): Promise<void>;
-    /**
-     * Discovers services and characteristics for a device
-     * Caches the writeable characteristic for future writes
-     *
-     * @param deviceId - Bluetooth device ID
-     * @throws {BluetoothPrintError} When no writeable characteristic is found
-     */
-    private discoverServices;
+export declare class ByteDanceAdapter extends MiniProgramAdapter {
+    protected getApi(): MiniProgramBLEApi;
 }

package/dist/types/adapters/TaroAdapter.d.ts

@@ -1,9 +1,10 @@
-import { IAdapterOptions } from '../types';
-import { BaseAdapter } from './BaseAdapter';
-
+import { MiniProgramAdapter, MiniProgramBLEApi } from './BaseAdapter';
 /**
  * Taro Bluetooth Low Energy adapter
  *
+ * Uses the Taro framework's BLE APIs (compatible with WeChat mini-program).
+ * All connection, write, and service discovery logic is inherited from MiniProgramAdapter.
+ *
  * @example
  * ```typescript
  * const adapter = new TaroAdapter();
@@ -12,35 +13,6 @@ import { BaseAdapter } from './BaseAdapter';
  * await adapter.disconnect('device-id-123');
  * ```
  */
-export declare class TaroAdapter extends BaseAdapter {
-    /**
-     * Connects to a Bluetooth device and discovers services
-     *
-     * @param deviceId - Bluetooth device ID
-     * @throws {BluetoothPrintError} When connection fails
-     */
-    connect(deviceId: string): Promise<void>;
-    /**
-     * Disconnects from a Bluetooth device
-     *
-     * @param deviceId - Bluetooth device ID
-     */
-    disconnect(deviceId: string): Promise<void>;
-    /**
-     * Writes data to the Bluetooth device in chunks with retry logic
-     *
-     * @param deviceId - Bluetooth device ID
-     * @param buffer - Data to write as ArrayBuffer
-     * @param options - Write options (chunk size, delay, retries)
-     * @throws {BluetoothPrintError} When write fails after retries
-     */
-    write(deviceId: string, buffer: ArrayBuffer, options?: IAdapterOptions): Promise<void>;
-    /**
-     * Discovers services and characteristics for a device
-     * Caches the writeable characteristic for future writes
-     *
-     * @param deviceId - Bluetooth device ID
-     * @throws {BluetoothPrintError} When no writeable characteristic is found
-     */
-    private discoverServices;
+export declare class TaroAdapter extends MiniProgramAdapter {
+    protected getApi(): MiniProgramBLEApi;
 }

package/dist/types/adapters/WebBluetoothAdapter.d.ts

@@ -1,6 +1,5 @@
 import { IAdapterOptions } from '../types';
 import { BaseAdapter } from './BaseAdapter';
-
 /**
  * Request device options for Web Bluetooth
  */

package/dist/types/config/PrinterConfig.d.ts

@@ -1,5 +1,4 @@
 import { LogLevel } from '../utils/logger';
-
 /**
  * Adapter configuration options
  */

package/dist/types/core/BluetoothPrinter.d.ts

@@ -2,7 +2,6 @@ import { IAdapterOptions, IQrOptions, PrinterState, IPrinterAdapter } from '../t
 import { EventEmitter } from './EventEmitter';
 import { BluetoothPrintError } from '../errors/BluetoothError';
 import { IConnectionManager, IPrintJobManager, ICommandBuilder } from '../services/interfaces';
-
 /**
  * Event types emitted by BluetoothPrinter
  */

package/dist/types/drivers/EscPos.d.ts

@@ -1,5 +1,4 @@
 import { IPrinterDriver, IQrOptions } from '../types';
-
 /**
  * ESC/POS driver options
  */

package/dist/types/drivers/TsplDriver.d.ts

@@ -0,0 +1,251 @@
+/**
+ * TSPL Driver
+ * TSC Printer Language driver for label/barcode printers
+ *
+ * TSPL is commonly used in thermal transfer label printers (TSC, Zebra, etc.)
+ */
+/**
+ * Label size configuration
+ */
+export interface LabelSize {
+    /** Label width in mm */
+    width: number;
+    /** Label height in mm */
+    height: number;
+    /** Gap between labels in mm (default: 3) */
+    gap?: number;
+}
+/**
+ * Text position and style
+ */
+export interface TextOptions {
+    /** X position in dots */
+    x: number;
+    /** Y position in dots */
+    y: number;
+    /** Font size (1-8, default: 2) */
+    font?: number;
+    /** Rotation (0, 90, 180, 270, default: 0) */
+    rotation?: 0 | 90 | 180 | 270;
+    /** Horizontal multiplier (1-10, default: 1) */
+    xMultiplier?: number;
+    /** Vertical multiplier (1-10, default: 1) */
+    yMultiplier?: number;
+}
+/**
+ * Barcode options
+ */
+export interface BarcodeOptions {
+    /** X position in dots */
+    x: number;
+    /** Y position in dots */
+    y: number;
+    /** Barcode type */
+    type: '128' | '39' | 'EAN13' | 'EAN8' | 'UPCA' | 'QRCODE';
+    /** Height in dots (default: 100) */
+    height?: number;
+    /** Narrow bar width (default: 2) */
+    narrow?: number;
+    /** Wide bar width (default: 4) */
+    wide?: number;
+    /** Show human-readable text (default: true) */
+    showText?: boolean;
+    /** Rotation (0, 90, 180, 270, default: 0) */
+    rotation?: 0 | 90 | 180 | 270;
+}
+/**
+ * QR Code options
+ */
+export interface QRCodeOptions {
+    /** X position in dots */
+    x: number;
+    /** Y position in dots */
+    y: number;
+    /** Error correction level (L, M, Q, H, default: M) */
+    eccLevel?: 'L' | 'M' | 'Q' | 'H';
+    /** Cell width (1-10, default: 6) */
+    cellWidth?: number;
+    /** Mode (A=Auto, M=Manual, default: A) */
+    mode?: 'A' | 'M';
+    /** Rotation (0, 90, 180, 270, default: 0) */
+    rotation?: 0 | 90 | 180 | 270;
+}
+/**
+ * Box/Rectangle options
+ */
+export interface BoxOptions {
+    /** X position in dots */
+    x: number;
+    /** Y position in dots */
+    y: number;
+    /** Width in dots */
+    width: number;
+    /** Height in dots */
+    height: number;
+    /** Line thickness (default: 2) */
+    thickness?: number;
+}
+/**
+ * Line options
+ */
+export interface LineOptions {
+    /** Start X position in dots */
+    x1: number;
+    /** Start Y position in dots */
+    y1: number;
+    /** End X position in dots */
+    x2: number;
+    /** End Y position in dots */
+    y2: number;
+    /** Line thickness (default: 2) */
+    thickness?: number;
+}
+/**
+ * TSPL Driver for label printers
+ *
+ * @example
+ * ```typescript
+ * const tspl = new TsplDriver();
+ *
+ * const commands = tspl
+ *   .size(60, 40)
+ *   .gap(3)
+ *   .clear()
+ *   .text('Product Name', { x: 50, y: 50, font: 3 })
+ *   .barcode('1234567890', { x: 50, y: 100, type: '128' })
+ *   .print(1)
+ *   .getBuffer();
+ * ```
+ */
+export declare class TsplDriver {
+    private commands;
+    private readonly logger;
+    private dpi;
+    /**
+     * Set printer DPI (dots per inch)
+     * @param dpi - DPI value (203 or 300)
+     */
+    setDPI(dpi: 203 | 300): this;
+    /**
+     * Convert mm to dots
+     */
+    mmToDots(mm: number): number;
+    /**
+     * Convert dots to mm
+     */
+    dotsToMm(dots: number): number;
+    /**
+     * Set label size
+     * @param width - Label width in mm
+     * @param height - Label height in mm
+     */
+    size(width: number, height: number): this;
+    /**
+     * Set gap between labels
+     * @param gap - Gap size in mm
+     * @param offset - Offset in mm (default: 0)
+     */
+    gap(gap: number, offset?: number): this;
+    /**
+     * Set print speed
+     * @param speed - Speed level (1-10)
+     */
+    speed(speed: number): this;
+    /**
+     * Set print density
+     * @param density - Density level (0-15)
+     */
+    density(density: number): this;
+    /**
+     * Set print direction
+     * @param direction - 0=normal, 1=reversed
+     */
+    direction(direction: 0 | 1): this;
+    /**
+     * Clear image buffer
+     */
+    clear(): this;
+    /**
+     * Add text to label
+     * @param content - Text content
+     * @param options - Text options
+     */
+    text(content: string, options: TextOptions): this;
+    /**
+     * Add barcode to label
+     * @param content - Barcode content
+     * @param options - Barcode options
+     */
+    barcode(content: string, options: BarcodeOptions): this;
+    /**
+     * Add QR code to label
+     * @param content - QR code content
+     * @param options - QR code options
+     */
+    qrcode(content: string, options: QRCodeOptions): this;
+    /**
+     * Draw a box/rectangle
+     * @param options - Box options
+     */
+    box(options: BoxOptions): this;
+    /**
+     * Draw a line
+     * @param options - Line options
+     */
+    line(options: LineOptions): this;
+    /**
+     * Fill a rectangular area
+     * @param x - X position
+     * @param y - Y position
+     * @param width - Width
+     * @param height - Height
+     */
+    bar(x: number, y: number, width: number, height: number): this;
+    /**
+     * Reverse a rectangular area (white becomes black and vice versa)
+     * @param x - X position
+     * @param y - Y position
+     * @param width - Width
+     * @param height - Height
+     */
+    reverse(x: number, y: number, width: number, height: number): this;
+    /**
+     * Print the label
+     * @param copies - Number of copies (default: 1)
+     * @param sets - Number of sets (default: 1)
+     */
+    print(copies?: number, sets?: number): this;
+    /**
+     * Feed labels
+     * @param count - Number of labels to feed
+     */
+    feed(count?: number): this;
+    /**
+     * Cut paper (if cutter available)
+     */
+    cut(): this;
+    /**
+     * Beep the buzzer
+     */
+    beep(): this;
+    /**
+     * Home the print head
+     */
+    home(): this;
+    /**
+     * Escape special characters in string
+     */
+    private escapeString;
+    /**
+     * Get all commands as string
+     */
+    getCommands(): string;
+    /**
+     * Get commands as buffer for sending to printer
+     */
+    getBuffer(): Uint8Array;
+    /**
+     * Clear all commands
+     */
+    reset(): this;
+}

package/dist/types/encoding/gbk-data.d.ts

@@ -0,0 +1,12 @@
+/**
+ * GBK/Big5 Encoding Data
+ *
+ * 紧凑的编码映射数据。
+ * 扁平数组格式: [unicode1, gbk1, unicode2, gbk2, ...]
+ * GBK: 23940 个字符映射
+ * Big5: 13911 个字符映射
+ *
+ * 由脚本自动生成，请勿手动编辑。
+ */
+export declare const GBK_DATA: number[];
+export declare const BIG5_DATA: number[];

package/dist/types/encoding/gbk-table.d.ts

@@ -8,6 +8,10 @@
  * GBK encoding uses double-byte encoding for Chinese characters:
  * - First byte: 0x81-0xFE
  * - Second byte: 0x40-0xFE (excluding 0x7F)
+ *
+ * 映射数据存储在 gbk-data.ts 中，运行时解码为 Map。
+ * GBK: 23940 个字符映射
+ * Big5: 13911 个字符映射
  */
 /**
  * Unicode to GBK mapping table
@@ -30,7 +34,7 @@ export declare const big5ToUnicode: Map<number, number>;
 /**
  * Get GBK bytes for a Unicode character
  * @param unicode - Unicode code point
- * @returns GBK byte pair or null if not found
+ * @returns GBK byte pair [high, low] or null if not found
  */
 export declare function getGbkBytes(unicode: number): [number, number] | null;
 /**

package/dist/types/index.d.ts

@@ -8,6 +8,8 @@ export { BluetoothPrinter } from './core/BluetoothPrinter';
 export type { PrinterEvents } from './core/BluetoothPrinter';
 export { EventEmitter } from './core/EventEmitter';
 export { EscPos } from './drivers/EscPos';
+export { TsplDriver } from './drivers/TsplDriver';
+export type { LabelSize, TextOptions as TsplTextOptions, BarcodeOptions as TsplBarcodeOptions, QRCodeOptions as TsplQRCodeOptions, BoxOptions, LineOptions, } from './drivers/TsplDriver';
 export { TaroAdapter } from './adapters/TaroAdapter';
 export { AdapterFactory } from './adapters/AdapterFactory';
 export { BaseAdapter } from './adapters/BaseAdapter';
@@ -38,4 +40,7 @@ export { PlatformType, detectPlatform, isPlatformSupported } from './utils/platf
 export { BluetoothPrintError, ErrorCode } from './errors/BluetoothError';
 export { DEFAULT_CONFIG, mergeConfig } from './config/PrinterConfig';
 export type { PrinterConfig, AdapterConfig, DriverConfig, LoggingConfig, } from './config/PrinterConfig';
+export { PluginManager } from './plugins/PluginManager';
+export { createLoggingPlugin, createRetryPlugin } from './plugins';
+export type { Plugin, PluginHooks, PluginOptions, PluginFactory } from './plugins/types';
 export * from './types';