taro-bluetooth-print 2.8.4 → 2.9.0

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

@@ -62,11 +62,28 @@ export declare class BluetoothPrinter extends EventEmitter<PrinterEvents> {
     /**
      * Creates a new BluetoothPrinter instance
      *
-     * @param connectionManagerOrAdapter - Connection manager instance or printer adapter instance (for backward compatibility)
-     * @param printJobManagerOrDriver - Print job manager instance or printer driver instance (for backward compatibility)
-     * @param commandBuilder - Command builder instance (optional)
+     * Supports two calling conventions:
+     * - Modern DI: new BluetoothPrinter(connectionManager, printJobManager, commandBuilder)
+     * - Legacy API: new BluetoothPrinter(adapter) - adapter is wrapped in ConnectionManager
+     *
+     * @param connectionManagerOrAdapter - Connection manager (recommended) or IPrinterAdapter (legacy)
+     * @param printJobManager - Print job manager instance
+     * @param commandBuilder - Command builder instance
+     *
+     * @example
+     * ```typescript
+     * // Recommended: use the factory
+     * import { createBluetoothPrinter } from 'taro-bluetooth-print';
+     * const printer = createBluetoothPrinter({ adapter: myAdapter });
+     *
+     * // Direct instantiation with DI
+     * const printer = new BluetoothPrinter(connectionManager, printJobManager, commandBuilder);
+     *
+     * // Legacy API (backward compatible)
+     * const printer = new BluetoothPrinter(adapter);
+     * ```
      */
-    constructor(connectionManagerOrAdapter?: IConnectionManager | IPrinterAdapter, printJobManagerOrDriver?: IPrintJobManager, commandBuilder?: ICommandBuilder);
+    constructor(connectionManagerOrAdapter?: IConnectionManager | IPrinterAdapter, printJobManager?: IPrintJobManager, commandBuilder?: ICommandBuilder);
     /**
      * Updates the current state based on the connection manager and print job manager states
      */

package/dist/types/errors/CommandBuildError.d.ts

@@ -0,0 +1,40 @@
+import { BluetoothPrintError } from './BluetoothError';
+/**
+ * Command building error codes
+ */
+export declare enum CommandBuildErrorCode {
+    /** Invalid configuration */
+    INVALID_CONFIG = "INVALID_CONFIGURATION",
+    /** Encoding not supported */
+    ENCODING_NOT_SUPPORTED = "ENCODING_NOT_SUPPORTED",
+    /** Invalid image data */
+    INVALID_IMAGE = "INVALID_IMAGE_DATA",
+    /** Invalid QR code data */
+    INVALID_QR = "INVALID_QR_DATA",
+    /** Driver error */
+    DRIVER_ERROR = "DRIVER_ERROR"
+}
+/**
+ * CommandBuildError - Specialized error for command building failures
+ *
+ * @example
+ * ```typescript
+ * throw new CommandBuildError(
+ *   CommandBuildErrorCode.ENCODING_NOT_SUPPORTED,
+ *   'Encoding "EUC-JP" is not supported',
+ *   originalError
+ * );
+ * ```
+ */
+export declare class CommandBuildError extends BluetoothPrintError {
+    readonly buildErrorCode: CommandBuildErrorCode;
+    constructor(buildErrorCode: CommandBuildErrorCode, message: string, originalError?: Error);
+    /**
+     * Converts CommandBuildErrorCode to base ErrorCode
+     */
+    private static _toBaseCode;
+    /**
+     * Checks if an error is a command build error
+     */
+    static isCommandBuildError(error: unknown): error is CommandBuildError;
+}

package/dist/types/errors/ConnectionError.d.ts

@@ -0,0 +1,45 @@
+import { BluetoothPrintError } from './BluetoothError';
+/**
+ * Connection-related error codes
+ */
+export declare enum ConnectionErrorCode {
+    /** Failed to establish connection */
+    FAILED = "CONNECTION_FAILED",
+    /** Connection attempt timed out */
+    TIMEOUT = "CONNECTION_TIMEOUT",
+    /** Device not found during discovery */
+    NOT_FOUND = "DEVICE_NOT_FOUND",
+    /** Device disconnected unexpectedly */
+    DISCONNECTED = "DEVICE_DISCONNECTED",
+    /** Bluetooth service not found on device */
+    SERVICE_NOT_FOUND = "SERVICE_NOT_FOUND",
+    /** Bluetooth characteristic not found */
+    CHARACTERISTIC_NOT_FOUND = "CHARACTERISTIC_NOT_FOUND",
+    /** Service discovery failed */
+    DISCOVERY_FAILED = "SERVICE_DISCOVERY_FAILED",
+    /** Platform doesn't support Bluetooth */
+    PLATFORM_UNSUPPORTED = "PLATFORM_NOT_SUPPORTED"
+}
+/**
+ * ConnectionError - Specialized error for connection-related failures
+ *
+ * @example
+ * ```typescript
+ * throw new ConnectionError(
+ *   ConnectionErrorCode.TIMEOUT,
+ *   'Connection timed out after 30s',
+ *   originalError
+ * );
+ * ```
+ */
+export declare class ConnectionError extends BluetoothPrintError {
+    constructor(code: ConnectionErrorCode, message: string, originalError?: Error);
+    /**
+     * Converts ConnectionErrorCode to base ErrorCode
+     */
+    private static _toBaseCode;
+    /**
+     * Checks if an error is a connection-related error
+     */
+    static isConnectionError(error: unknown): error is ConnectionError;
+}

package/dist/types/errors/PrintJobError.d.ts

@@ -0,0 +1,42 @@
+import { BluetoothPrintError } from './BluetoothError';
+/**
+ * Print job-related error codes
+ */
+export declare enum PrintJobErrorCode {
+    /** Print job failed */
+    FAILED = "PRINT_JOB_FAILED",
+    /** Print job is already in progress */
+    IN_PROGRESS = "PRINT_JOB_IN_PROGRESS",
+    /** Print job was cancelled */
+    CANCELLED = "PRINT_JOB_CANCELLED",
+    /** Print data is invalid */
+    INVALID_DATA = "INVALID_IMAGE_DATA",
+    /** Write operation failed */
+    WRITE_FAILED = "WRITE_FAILED",
+    /** Write operation timed out */
+    WRITE_TIMEOUT = "WRITE_TIMEOUT"
+}
+/**
+ * PrintJobError - Specialized error for print job failures
+ *
+ * @example
+ * ```typescript
+ * throw new PrintJobError(
+ *   PrintJobErrorCode.WRITE_FAILED,
+ *   'Failed to send data to printer',
+ *   originalError
+ * );
+ * ```
+ */
+export declare class PrintJobError extends BluetoothPrintError {
+    readonly jobErrorCode: PrintJobErrorCode;
+    constructor(jobErrorCode: PrintJobErrorCode, message: string, originalError?: Error);
+    /**
+     * Converts PrintJobErrorCode to base ErrorCode
+     */
+    private static _toBaseCode;
+    /**
+     * Checks if an error is a print job error
+     */
+    static isPrintJobError(error: unknown): error is PrintJobError;
+}

package/dist/types/errors/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Errors Module
+ *
+ * @packageDocumentation
+ */
+export { BluetoothPrintError, ErrorCode } from './BluetoothError';
+export { ConnectionError, ConnectionErrorCode } from './ConnectionError';
+export { PrintJobError, PrintJobErrorCode } from './PrintJobError';
+export { CommandBuildError, CommandBuildErrorCode } from './CommandBuildError';

package/dist/types/factory/PrinterFactory.d.ts

@@ -0,0 +1,108 @@
+import { BluetoothPrinter } from '../core/BluetoothPrinter';
+import { IPrinterAdapter } from '../types';
+import { IConnectionManager, IPrintJobManager, ICommandBuilder } from '../services/interfaces';
+/**
+ * Options for creating a BluetoothPrinter via the factory
+ */
+export interface PrinterFactoryOptions {
+    /**
+     * Printer adapter to use for Bluetooth communication.
+     * Required if not providing custom connectionManager.
+     *
+     * Common adapters:
+     * - WebBluetoothAdapter (browser Web Bluetooth API)
+     * - TaroAdapter (Taro framework)
+     * - AlipayAdapter (Alipay mini-program)
+     * - ReactNativeAdapter (React Native)
+     *
+     * @example
+     * ```typescript
+     * import { WebBluetoothAdapter } from 'taro-bluetooth-print';
+     *
+     * const printer = createBluetoothPrinter({
+     *   adapter: new WebBluetoothAdapter()
+     * });
+     * ```
+     */
+    adapter?: IPrinterAdapter;
+    /**
+     * Custom connection manager instance.
+     * If provided, overrides the default ConnectionManager.
+     * Useful for testing or custom connection handling.
+     */
+    connectionManager?: IConnectionManager;
+    /**
+     * Custom print job manager instance.
+     * If provided, overrides the default PrintJobManager.
+     * Useful for custom job scheduling or queue management.
+     */
+    printJobManager?: IPrintJobManager;
+    /**
+     * Custom command builder instance.
+     * If provided, overrides the default CommandBuilder.
+     * Useful for custom command formatting or driver selection.
+     */
+    commandBuilder?: ICommandBuilder;
+}
+/**
+ * Creates a new BluetoothPrinter instance with properly configured services.
+ *
+ * This is the recommended factory function for creating printer instances.
+ * It handles dependency injection and ensures all services are properly wired.
+ *
+ * @param options - Factory options for configuring the printer
+ * @returns A fully configured BluetoothPrinter instance
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with WebBluetooth
+ * import { createBluetoothPrinter, WebBluetoothAdapter } from 'taro-bluetooth-print';
+ *
+ * const printer = createBluetoothPrinter({
+ *   adapter: new WebBluetoothAdapter()
+ * });
+ *
+ * await printer.connect('device-id');
+ * await printer.text('Hello').feed(2).cut().print();
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Advanced usage with custom services
+ * import { createBluetoothPrinter, TaroAdapter } from 'taro-bluetooth-print';
+ *
+ * const printer = createBluetoothPrinter({
+ *   adapter: new TaroAdapter(),
+ *   printJobManager: customPrintJobManager,
+ * });
+ * ```
+ */
+export declare function createBluetoothPrinter(options?: PrinterFactoryOptions): BluetoothPrinter;
+/**
+ * Creates a BluetoothPrinter instance for the Web Bluetooth API.
+ *
+ * This is a convenience function specifically for browser environments
+ * using the Web Bluetooth API.
+ *
+ * @param adapterOptions - Options to pass to the WebBluetoothAdapter
+ * @returns A BluetoothPrinter instance configured for Web Bluetooth
+ *
+ * @example
+ * ```typescript
+ * import { createWebBluetoothPrinter } from 'taro-bluetooth-print';
+ *
+ * const printer = createWebBluetoothPrinter();
+ * await printer.connect('device-id');
+ * ```
+ */
+export declare function createWebBluetoothPrinter(): Promise<BluetoothPrinter>;
+/**
+ * Default printer factory instance
+ *
+ * @deprecated Use the factory functions directly. This export exists
+ * for backward compatibility only.
+ */
+export declare const PrinterFactory: {
+    create: typeof createBluetoothPrinter;
+    createWebBluetooth: typeof createWebBluetoothPrinter;
+};

package/dist/types/factory/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Factory Module
+ *
+ * @packageDocumentation
+ */
+export { createBluetoothPrinter, createWebBluetoothPrinter, PrinterFactory, type PrinterFactoryOptions, } from './PrinterFactory';

package/dist/types/index.d.ts

@@ -40,6 +40,10 @@ export { Encoding } from './utils/encoding';
 export { ImageProcessing } from './utils/image';
 export { PlatformType, detectPlatform, isPlatformSupported } from './utils/platform';
 export { BluetoothPrintError, ErrorCode } from './errors/BluetoothError';
+export { ConnectionError, ConnectionErrorCode } from './errors/ConnectionError';
+export { PrintJobError, PrintJobErrorCode } from './errors/PrintJobError';
+export { CommandBuildError, CommandBuildErrorCode } from './errors/CommandBuildError';
+export { createBluetoothPrinter, createWebBluetoothPrinter, PrinterFactory, type PrinterFactoryOptions, } from './factory';
 export { DEFAULT_CONFIG, mergeConfig } from './config/PrinterConfig';
 export type { PrinterConfig, AdapterConfig, DriverConfig, LoggingConfig, } from './config/PrinterConfig';
 export { PrinterConfigManager, printerConfigManager } from './config/PrinterConfigManager';

package/dist/types/services/interfaces/ICommandBuilder.d.ts

@@ -0,0 +1,123 @@
+import { IQrOptions } from '../../types';
+import { TextAlign, TextStyle } from '../../formatter';
+import { BarcodeOptions } from '../../barcode';
+/**
+ * Command Builder Interface
+ *
+ * Builds print commands using the printer driver
+ */
+export interface ICommandBuilder {
+    /**
+     * Adds text to the print queue
+     *
+     * @param content - Text content
+     * @param encoding - Text encoding
+     * @returns this - For method chaining
+     */
+    text(content: string, encoding?: string): this;
+    /**
+     * Adds line feeds to the print queue
+     *
+     * @param lines - Number of lines to feed
+     * @returns this - For method chaining
+     */
+    feed(lines?: number): this;
+    /**
+     * Adds a paper cut command to the print queue
+     *
+     * @returns this - For method chaining
+     */
+    cut(): this;
+    /**
+     * Adds an image to the print queue
+     *
+     * @param data - Image data as Uint8Array
+     * @param width - Image width
+     * @param height - Image height
+     * @returns this - For method chaining
+     */
+    image(data: Uint8Array, width: number, height: number): this;
+    /**
+     * Adds a QR code to the print queue
+     *
+     * @param content - QR code content
+     * @param options - QR code options
+     * @returns this - For method chaining
+     */
+    qr(content: string, options?: IQrOptions): this;
+    /**
+     * Clears the print queue
+     *
+     * @returns this - For method chaining
+     */
+    clear(): this;
+    /**
+     * Sets text alignment
+     *
+     * @param alignment - Text alignment (left, center, right)
+     * @returns this - For method chaining
+     */
+    align(alignment: TextAlign): this;
+    /**
+     * Sets character size (width and height scale)
+     *
+     * @param width - Width scale factor (1-8)
+     * @param height - Height scale factor (1-8)
+     * @returns this - For method chaining
+     */
+    setSize(width: number, height: number): this;
+    /**
+     * Sets bold text mode
+     *
+     * @param enabled - Enable or disable bold
+     * @returns this - For method chaining
+     */
+    setBold(enabled: boolean): this;
+    /**
+     * Sets underline text mode
+     *
+     * @param enabled - Enable or disable underline
+     * @returns this - For method chaining
+     */
+    setUnderline(enabled: boolean): this;
+    /**
+     * Sets inverse printing mode (white on black)
+     *
+     * @param enabled - Enable or disable inverse
+     * @returns this - For method chaining
+     */
+    setInverse(enabled: boolean): this;
+    /**
+     * Sets multiple text style properties at once
+     *
+     * @param style - Text style configuration
+     * @returns this - For method chaining
+     */
+    setStyle(style: TextStyle): this;
+    /**
+     * Resets all text formatting to default
+     *
+     * @returns this - For method chaining
+     */
+    resetStyle(): this;
+    /**
+     * Adds a 1D barcode to the print queue
+     *
+     * @param content - Barcode content/data
+     * @param options - Barcode options
+     * @returns this - For method chaining
+     */
+    barcode(content: string, options: BarcodeOptions): this;
+    /**
+     * Gets the current buffer
+     *
+     * @returns Uint8Array - Current print buffer
+     */
+    getBuffer(): Uint8Array;
+    /**
+     * Gets the total number of bytes in the buffer
+     *
+     * @returns number - Total bytes
+     */
+    getTotalBytes(): number;
+}

package/dist/types/services/interfaces/IConnectionManager.d.ts

@@ -0,0 +1,49 @@
+import { PrinterState, IPrinterAdapter } from '../../types';
+/**
+ * Connection Manager Interface
+ *
+ * Manages Bluetooth device connections
+ */
+export interface IConnectionManager {
+    /**
+     * Connects to a Bluetooth device
+     *
+     * @param deviceId - Bluetooth device ID
+     * @param options - Connection options
+     * @returns Promise<void>
+     */
+    connect(deviceId: string, options?: {
+        retries?: number;
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Disconnects from the current device
+     *
+     * @returns Promise<void>
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Checks if a device is connected
+     *
+     * @returns boolean - True if connected, false otherwise
+     */
+    isConnected(): boolean;
+    /**
+     * Gets the current device ID
+     *
+     * @returns string | null - Device ID or null if not connected
+     */
+    getDeviceId(): string | null;
+    /**
+     * Gets the current connection state
+     *
+     * @returns PrinterState - Current state
+     */
+    getState(): PrinterState;
+    /**
+     * Gets the printer adapter instance
+     *
+     * @returns IPrinterAdapter - Printer adapter
+     */
+    getAdapter(): IPrinterAdapter;
+}

package/dist/types/services/interfaces/IPrintJobManager.d.ts

@@ -0,0 +1,67 @@
+import { IAdapterOptions } from '../../types';
+/**
+ * Print Job Manager Interface
+ *
+ * Manages print jobs, including pause/resume/cancel functionality
+ */
+export interface IPrintJobManager {
+    /**
+     * Starts a print job
+     *
+     * @param buffer - Print data buffer
+     * @returns Promise<void>
+     */
+    start(buffer: Uint8Array, options?: {
+        jobId?: string;
+    }): Promise<void>;
+    /**
+     * Pauses the current print job
+     */
+    pause(): void;
+    /**
+     * Resumes a paused print job
+     *
+     * @returns Promise<void>
+     */
+    resume(jobId?: string): Promise<void>;
+    /**
+     * Cancels the current print job
+     */
+    cancel(): void;
+    /**
+     * Gets the number of bytes remaining to print
+     *
+     * @returns number - Bytes remaining
+     */
+    remaining(): number;
+    /**
+     * Checks if the print job is paused
+     *
+     * @returns boolean - True if paused, false otherwise
+     */
+    isPaused(): boolean;
+    /**
+     * Checks if a print job is in progress
+     *
+     * @returns boolean - True if in progress, false otherwise
+     */
+    isInProgress(): boolean;
+    /**
+     * Sets adapter options for write operations
+     *
+     * @param options - Adapter options
+     */
+    setOptions(options: IAdapterOptions): void;
+    /**
+     * Sets the progress callback
+     *
+     * @param callback - Progress callback function
+     */
+    setProgressCallback(callback?: (sent: number, total: number) => void): void;
+    /**
+     * Sets the job state change callback
+     *
+     * @param callback - Job state change callback function
+     */
+    setJobStateCallback(callback?: (state: 'in-progress' | 'paused' | 'completed' | 'cancelled') => void): void;
+}