taro-bluetooth-print 2.4.1 → 2.6.0

package/dist/types/utils/uuid.d.ts

@@ -0,0 +1,191 @@
+/**
+ * UUID Utility Module
+ *
+ * Provides UUID generation and parsing utilities for device identification,
+ * job tracking, and unique identifier generation.
+ *
+ * @example
+ * ```typescript
+ * import { generateUUID, parseUUID, isValidUUID } from '@/utils/uuid';
+ *
+ * const id = generateUUID(); // v4 UUID
+ * const parsed = parseUUID(id);
+ * const valid = isValidUUID(id);
+ * ```
+ */
+/**
+ * UUID version numbers
+ */
+export declare enum UUIDVersion {
+    /** Version 1: Timestamp-based */
+    V1 = 1,
+    /** Version 4: Random */
+    V4 = 4,
+    /** Version 7: Unix Epoch time-based (recommended) */
+    V7 = 7
+}
+/**
+ * Parsed UUID structure
+ */
+export interface ParsedUUID {
+    /** Raw UUID string */
+    raw: string;
+    /** UUID version */
+    version: UUIDVersion;
+    /** Variant bits */
+    variant: number;
+    /** Time component (for V1, V7) in milliseconds since epoch */
+    timestamp?: number;
+    /** Node identifier bytes (for V1) */
+    node?: string;
+    /** Random bytes (for V4) */
+    random?: string;
+    /** Whether the UUID is valid */
+    valid: boolean;
+}
+/**
+ * UUID format options
+ */
+export interface UUIDOptions {
+    /** Uppercase hex output */
+    uppercase?: boolean;
+    /** Include hyphens (default: true) */
+    hyphenated?: boolean;
+    /** UUID version to generate (default: V4) */
+    version?: UUIDVersion;
+}
+/**
+ * UUID validation result
+ */
+export interface UUIDValidationResult {
+    /** Whether the UUID is valid */
+    valid: boolean;
+    /** Version of the UUID if valid */
+    version?: UUIDVersion;
+    /** Error message if invalid */
+    error?: string;
+}
+/**
+ * UUID namespace for generating namespaced UUIDs (V5)
+ */
+export interface UUIDNamespace {
+    /** Namespace UUID */
+    uuid: string;
+    /** Namespace name */
+    name: string;
+}
+/**
+ * Predefined namespaces for namespaced UUIDs (RFC 4122)
+ */
+export declare const UUID_NAMESPACES: Record<string, UUIDNamespace>;
+/**
+ * Generate a random UUID
+ *
+ * @param version - UUID version to generate (default: V4)
+ * @param options - Generation options
+ * @returns Generated UUID string
+ *
+ * @example
+ * ```typescript
+ * const uuid = generateUUID();
+ * const uuidV7 = generateUUID(UUIDVersion.V7, { uppercase: true });
+ * ```
+ */
+export declare function generateUUID(version?: UUIDVersion, options?: UUIDOptions): string;
+/**
+ * Parse a UUID string into its components
+ *
+ * @param uuid - UUID string to parse
+ * @returns Parsed UUID structure
+ *
+ * @example
+ * ```typescript
+ * const parsed = parseUUID('550e8400-e29b-41d4-a716-446655440000');
+ * console.log(parsed.version); // 4
+ * console.log(parsed.valid); // true
+ * ```
+ */
+export declare function parseUUID(uuid: string): ParsedUUID;
+/**
+ * Validate a UUID string
+ *
+ * @param uuid - UUID string to validate
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * const result = isValidUUID('550e8400-e29b-41d4-a716-446655440000');
+ * if (result.valid) {
+ *   console.log(`Valid UUID v${result.version}`);
+ * }
+ * ```
+ */
+export declare function isValidUUID(uuid: string): UUIDValidationResult;
+/**
+ * Extract timestamp from a time-based UUID (v1 or v7)
+ *
+ * @param uuid - UUID string
+ * @returns Timestamp in milliseconds, or null if not a time-based UUID
+ *
+ * @example
+ * ```typescript
+ * const timestamp = getUUIDTimestamp('07c450b0-7d4a-11ed-a1eb-0242ac120002');
+ * console.log(new Date(timestamp ?? 0));
+ * ```
+ */
+export declare function getUUIDTimestamp(uuid: string): number | null;
+/**
+ * Compare two UUIDs chronologically (for time-based UUIDs)
+ *
+ * @param uuidA - First UUID
+ * @param uuidB - Second UUID
+ * @returns -1 if A < B, 0 if equal, 1 if A > B
+ *
+ * @example
+ * ```typescript
+ * const order = compareUUIDs(uuid1, uuid2);
+ * ```
+ */
+export declare function compareUUIDs(uuidA: string, uuidB: string): number;
+/**
+ * Convert UUID to bytes (Uint8Array)
+ *
+ * @param uuid - UUID string
+ * @returns UUID as 16-byte array
+ */
+export declare function uuidToBytes(uuid: string): Uint8Array;
+/**
+ * Convert bytes to UUID string
+ *
+ * @param bytes - 16-byte array
+ * @param hyphenated - Include hyphens (default: true)
+ * @returns UUID string
+ */
+export declare function bytesToUUID(bytes: Uint8Array, hyphenated?: boolean): string;
+/**
+ * Generate a short ID (8-12 character hex string)
+ * Useful for display purposes like job IDs
+ *
+ * @param length - Length of ID (default: 8)
+ * @returns Short hex ID
+ *
+ * @example
+ * ```typescript
+ * const shortId = generateShortId(8); // e.g., 'a3f2b1c9'
+ * ```
+ */
+export declare function generateShortId(length?: number): string;
+/**
+ * Generate a namespaced UUID (v5)
+ *
+ * @param namespace - Namespace UUID
+ * @param name - Name within namespace
+ * @param options - Generation options
+ * @returns Namespaced UUID
+ *
+ * @example
+ * ```typescript
+ * const uuid = generateNamespacedUUID(UUID_NAMESPACES.NAMESPACE_DNS, 'example.com');
+ * ```
+ */
+export declare function generateNamespacedUUID(namespace: string, name: string, options?: UUIDOptions): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taro-bluetooth-print",
-  "version": "2.4.1",
+  "version": "2.6.0",
   "description": "Taro 蓝牙打印库 v2.4 - 轻量级、高性能、跨平台支持微信、支付宝、百度、字节跳动小程序及H5 Web Bluetooth",
   "type": "module",
   "main": "dist/index.cjs.js",

package/src/adapters/AdapterFactory.ts

@@ -9,6 +9,7 @@ import { TaroAdapter } from './TaroAdapter';
 import { AlipayAdapter } from './AlipayAdapter';
 import { BaiduAdapter } from './BaiduAdapter';
 import { ByteDanceAdapter } from './ByteDanceAdapter';
+import { QQAdapter } from './QQAdapter';
 import { WebBluetoothAdapter } from './WebBluetoothAdapter';
 import { PlatformType, detectPlatform } from '@/utils/platform';
 import { BluetoothPrintError, ErrorCode } from '@/errors/BluetoothError';
@@ -35,6 +36,8 @@ export class AdapterFactory {
         return new BaiduAdapter();
       case PlatformType.BYTEDANCE:
         return new ByteDanceAdapter();
+      case PlatformType.QQ:
+        return new QQAdapter();
       case PlatformType.WEB:
         if (WebBluetoothAdapter.isSupported()) {
           return new WebBluetoothAdapter();
@@ -68,6 +71,8 @@ export class AdapterFactory {
         return new BaiduAdapter();
       case PlatformType.BYTEDANCE:
         return new ByteDanceAdapter();
+      case PlatformType.QQ:
+        return new QQAdapter();
       case PlatformType.WEB:
         if (WebBluetoothAdapter.isSupported()) {
           return new WebBluetoothAdapter();

package/src/adapters/QQAdapter.ts

@@ -0,0 +1,36 @@
+/**
+ * QQ Mini Program Bluetooth Adapter
+ * Implements the IPrinterAdapter interface for QQ Mini Program
+ */
+
+import { MiniProgramAdapter, MiniProgramBLEApi } from './BaseAdapter';
+
+// Declare QQ global for TypeScript
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+interface QQGlobal extends MiniProgramBLEApi {}
+
+declare const qq: QQGlobal;
+
+/**
+ * QQ Mini Program Bluetooth Low Energy adapter
+ *
+ * Uses the QQ mini-program's BLE APIs (qq.xxx).
+ * All connection, write, and service discovery logic is inherited from MiniProgramAdapter.
+ *
+ * @example
+ * ```typescript
+ * const adapter = new QQAdapter();
+ * await adapter.connect('device-id-123');
+ * await adapter.write('device-id-123', buffer);
+ * await adapter.disconnect('device-id-123');
+ * ```
+ */
+export class QQAdapter extends MiniProgramAdapter {
+  /**
+   * Returns the QQ mini-program BLE API object
+   * @returns The qq global object providing BLE capabilities
+   */
+  protected getApi(): MiniProgramBLEApi {
+    return qq;
+  }
+}