id-scanner-lib 1.7.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "id-scanner-lib",
-  "version": "1.7.0",
+  "version": "2.0.0",
   "description": "Browser-based ID card, QR code, and face recognition scanner with liveness detection",
   "main": "dist/id-scanner-lib.js",
   "module": "dist/id-scanner-lib.esm.js",

package/src/compat/index.ts

@@ -0,0 +1,7 @@
+/**
+ * @file Compat Index
+ * @description Compatibility layer for v1 API
+ * @module compat
+ */
+
+export {};

package/src/compat/v1-adapter.ts

@@ -0,0 +1,84 @@
+/**
+ * @file V1 Adapter (Compatibility Layer)
+ * @description Provides backward compatibility with v1 IDScanner API
+ * @module compat/v1-adapter
+ */
+
+import { Scanner, ScannerConfig } from '../core/scanner';
+import { EventEmitter } from '../core/event-emitter';
+
+/**
+ * V1 IDScanner configuration
+ */
+export interface IDScannerConfig {
+  /** Debug mode */
+  debug?: boolean;
+  /** Callback when faces are detected */
+  onFaceDetected?: (faces: any[]) => void;
+  /** Callback on error */
+  onError?: (error: Error) => void;
+}
+
+/**
+ * IDScanner class - provides v1 API compatibility
+ * Wraps the new Scanner class with the old IDScanner interface
+ */
+export class IDScanner {
+  private _scanner: Scanner;
+  private _config: IDScannerConfig;
+  private _eventEmitter: EventEmitter;
+
+  /**
+   * Create a new IDScanner instance
+   * @param config Configuration
+   */
+  constructor(config: IDScannerConfig = {}) {
+    this._config = config;
+    this._scanner = new Scanner({ debug: config.debug });
+    this._eventEmitter = new EventEmitter();
+  }
+
+  /**
+   * Initialize the scanner
+   */
+  async initialize(): Promise<void> {
+    await this._scanner.initialize();
+  }
+
+  /**
+   * Start face recognition on a video element
+   * @param video Video element to process
+   */
+  async startFaceRecognition(video: HTMLVideoElement): Promise<void> {
+    const faces = await this._scanner.detectFace(video);
+    if (this._config.onFaceDetected) {
+      this._config.onFaceDetected(faces);
+    }
+    this._eventEmitter.emit('faceDetected', faces);
+  }
+
+  /**
+   * Stop the scanner and release resources
+   */
+  async stop(): Promise<void> {
+    await this._scanner.destroy();
+  }
+
+  /**
+   * Register an event handler
+   * @param event Event name
+   * @param handler Event handler
+   */
+  on(event: string, handler: (data?: any) => void): void {
+    this._eventEmitter.on(event, handler);
+  }
+
+  /**
+   * Unregister an event handler
+   * @param event Event name
+   * @param handler Event handler
+   */
+  off(event: string, handler: (data?: any) => void): void {
+    this._eventEmitter.off(event, handler);
+  }
+}

package/src/core/config.ts

@@ -1,37 +1,23 @@
 /**
- * @file 配置管理器
- * @description 提供全局配置管理功能
+ * @file 配置管理器 + Scanner 配置
+ * @description 提供全局配置管理功能 + Scanner v2.0 配置接口
  * @module core/config
  */
 
-/**
- * 配置管理器
- * 负责存储和管理应用程序的配置
- */
+// ============================================================
+// 原有 ConfigManager（保持向后兼容）
+// ============================================================
+
 export class ConfigManager {
-  /** 单例实例 */
   private static instance: ConfigManager;
-  
-  /** 配置存储 */
   private config: Record<string, any> = {};
-  
-  /** 配置变更回调 */
   private changeCallbacks: Map<string, Array<(value: any, oldValue: any) => void>> = new Map();
-  
-  /** 初始化状态 */
   private initialized = false;
-  
-  /**
-   * 私有构造函数
-   */
+
   private constructor() {
-    // 设置默认配置
     this._resetDefaults();
   }
-  
-  /**
-   * 获取单例实例
-   */
+
   public static getInstance(): ConfigManager {
     if (!ConfigManager.instance) {
       ConfigManager.instance = new ConfigManager();
@@ -39,285 +25,145 @@ export class ConfigManager {
     return ConfigManager.instance;
   }
 
-  /**
-   * 重置单例实例（主要用于测试）
-   */
   public static resetInstance(): void {
     ConfigManager.instance = undefined as any;
   }
 
-  /**
-   * 重置为默认配置
-   */
   private _resetDefaults(): void {
     this.config = {
       debug: false,
       logLevel: 'info',
-      camera: {
-        resolution: {
-          width: 1280,
-          height: 720
-        },
-        frameRate: 30,
-        facingMode: 'environment'
+      modelPath: '/models',
+      maxRetries: 3,
+      retryDelay: 1000,
+      detectionInterval: 100,
+      face: {
+        enabled: true,
+        confidenceThreshold: 0.5,
+        maxFaces: 10,
+      },
+      idCard: {
+        enabled: false,
+      },
+      qr: {
+        enabled: false,
       },
-      performance: {
-        useCache: true
-      }
     };
     this.initialized = true;
   }
-  
-  /**
-   * 获取配置值
-   * @param key 配置键，支持点号分隔的路径
-   * @param defaultValue 默认值
-   */
-  get<T = any>(key: string, defaultValue?: T): T {
-    const value = this.getNestedValue(this.config, key);
-    return (value !== undefined) ? value : (defaultValue as T);
-  }
-  
-  /**
-   * 设置配置值
-   * @param key 配置键，支持点号分隔的路径
-   * @param value 配置值
-   */
-  set<T = any>(key: string, value: T): void {
-    const oldValue = this.get(key);
-    
-    // 如果值相同，不做任何事
-    if (oldValue === value) {
-      return;
+
+  public get<T = any>(key: string, defaultValue?: T): T {
+    const keys = key.split('.');
+    let value: any = this.config;
+    for (const k of keys) {
+      value = value?.[k];
     }
-    
-    this.setNestedValue(this.config, key, value);
-    
-    // 触发变更回调
-    this.triggerChangeCallbacks(key, value, oldValue);
+    return (value !== undefined ? value : defaultValue) as T;
   }
-  
-  /**
-   * 批量更新配置
-   * @param config 配置对象
-   */
-  updateConfig(config: Record<string, any>): void {
-    Object.entries(config).forEach(([key, value]) => {
-      this.set(key, value);
-    });
-  }
-  
-  /**
-   * 重置为默认配置
-   */
-  reset(): void {
-    const oldConfig = { ...this.config };
-    
-    // 使用私有 reset 方法重建默认配置
-    this.config = {
-      debug: false,
-      logLevel: 'info',
-      camera: {
-        resolution: {
-          width: 1280,
-          height: 720
-        },
-        frameRate: 30,
-        facingMode: 'environment'
-      },
-      performance: {
-        useCache: true
-      }
-    };
-    
-    // 触发所有回调
-    Object.keys(oldConfig).forEach(key => {
-      this.triggerChangeCallbacks(key, this.get(key), oldConfig[key]);
-    });
+
+  public set(key: string, value: any): void {
+    const keys = key.split('.');
+    let target: any = this.config;
+    for (let i = 0; i < keys.length - 1; i++) {
+      if (!target[keys[i]]) target[keys[i]] = {};
+      target = target[keys[i]];
+    }
+    const oldValue = target[keys[keys.length - 1]];
+    target[keys[keys.length - 1]] = value;
+    const callbacks = this.changeCallbacks.get(key);
+    if (callbacks) {
+      callbacks.forEach(cb => cb(value, oldValue));
+    }
   }
-  
-  /**
-   * 注册配置变更回调
-   * @param key 配置键
-   * @param callback 回调函数
-   */
-  onConfigChange<T = any>(key: string, callback: (value: T, oldValue: T) => void): void {
+
+  public onChange(key: string, callback: (value: any, oldValue: any) => void): void {
     if (!this.changeCallbacks.has(key)) {
       this.changeCallbacks.set(key, []);
     }
-    
     this.changeCallbacks.get(key)!.push(callback);
   }
-  
-  /**
-   * 移除配置变更回调
-   * @param key 配置键
-   * @param callback 特定回调函数，如不提供则移除所有
-   */
-  offConfigChange<T = any>(key: string, callback?: (value: T, oldValue: T) => void): void {
-    if (!this.changeCallbacks.has(key)) {
-      return;
-    }
-    
-    if (callback) {
-      // 移除特定回调
-      const callbacks = this.changeCallbacks.get(key)!;
-      const index = callbacks.indexOf(callback as any);
-      if (index !== -1) {
-        callbacks.splice(index, 1);
-      }
-      
-      // 如果没有回调，删除键
-      if (callbacks.length === 0) {
-        this.changeCallbacks.delete(key);
-      }
-    } else {
-      // 移除所有回调
-      this.changeCallbacks.delete(key);
-    }
-  }
-  
-  /**
-   * 获取嵌套值
-   * @param obj 对象
-   * @param path 路径
-   */
-  private getNestedValue(obj: Record<string, any>, path: string): any {
-    // 处理根路径
-    if (!path) {
-      return obj;
-    }
-    
-    // 处理嵌套路径
-    const parts = path.split('.');
-    let current = obj;
-    
-    for (const part of parts) {
-      if (current === undefined || current === null) {
-        return undefined;
-      }
-      
-      current = current[part];
-    }
-    
-    return current;
-  }
-  
-  /**
-   * 设置嵌套值
-   * @param obj 对象
-   * @param path 路径
-   * @param value 值
-   */
-  private setNestedValue(obj: Record<string, any>, path: string, value: any): void {
-    // 处理根路径
-    if (!path) {
-      return;
-    }
-    
-    // 处理嵌套路径
-    const parts = path.split('.');
-    let current = obj;
-    
-    // 遍历路径，直到倒数第二部分
-    for (let i = 0; i < parts.length - 1; i++) {
-      const part = parts[i];
-      
-      // 如果不存在，创建新对象
-      if (current[part] === undefined || current[part] === null || typeof current[part] !== 'object') {
-        current[part] = {};
-      }
-      
-      current = current[part];
-    }
-    
-    // 设置最终值
-    current[parts[parts.length - 1]] = value;
+
+  /** @deprecated Use onChange instead */
+  public onConfigChange<T = any>(key: string, callback: (value: T, oldValue: T) => void): void {
+    this.onChange(key, callback);
   }
-  
-  /**
-   * 触发变更回调
-   * @param key 配置键
-   * @param value 新值
-   * @param oldValue 旧值
-   */
-  private triggerChangeCallbacks(key: string, value: any, oldValue: any): void {
-    // 触发特定键的回调
-    if (this.changeCallbacks.has(key)) {
-      const callbacks = this.changeCallbacks.get(key)!;
-      callbacks.forEach(callback => {
-        try {
-          callback(value, oldValue);
-        } catch (error) {
-          console.error(`Error in config change callback for key ${key}:`, error);
-        }
-      });
-    }
-    
-    // 触发父路径的回调
-    const parts = key.split('.');
-    while (parts.length > 1) {
-      parts.pop();
-      const parentKey = parts.join('.');
-      
-      if (this.changeCallbacks.has(parentKey)) {
-        const parentValue = this.get(parentKey);
-        this.changeCallbacks.get(parentKey)!.forEach(callback => {
-          try {
-            callback(parentValue, parentValue);
-          } catch (error) {
-            console.error(`Error in config change callback for parent key ${parentKey}:`, error);
-          }
-        });
-      }
+
+  public removeChangeCallback(key: string, callback: (value: any, oldValue: any) => void): void {
+    const callbacks = this.changeCallbacks.get(key);
+    if (callbacks) {
+      const index = callbacks.indexOf(callback);
+      if (index > -1) callbacks.splice(index, 1);
     }
   }
 
-  /**
-   * 检查模块是否启用
-   * @param moduleName 模块名称
-   */
-  public isModuleEnabled(moduleName: string): boolean {
-    const key = `modules.${moduleName}.enabled`;
-    return this.get(key) ?? false;
+  public reset(): void {
+    this.config = {};
+    this._resetDefaults();
   }
 }
 
+// ============================================================
+// Scanner v2.0 配置接口
+// ============================================================
+
 /**
- * 全局配置接口
+ * Scanner configuration interface (v2.0)
  */
-export interface GlobalConfig {
-  /** 版本号 */
-  version: string;
-  /** 调试模式 */
-  debug: boolean;
-  /** 日志级别 */
-  logLevel: string;
-  /** 摄像头配置 */
-  camera: {
-    resolution: { width: number; height: number };
-    frameRate: number;
-    facingMode: string;
+export interface ScannerConfig {
+  debug?: boolean;
+  modules?: {
+    face?: boolean;
+    faceComparator?: boolean;
+    faceLiveness?: boolean;
+    idCard?: boolean;
+    qr?: boolean;
   };
-  /** 性能配置 */
-  performance: {
-    useCache: boolean;
+  performance?: {
+    maxCanvasWidth?: number;
+    useWorker?: boolean;
+    lazyLoad?: boolean;
   };
-  /** 模块配置 */
-  modules: {
-    face: { enabled: boolean };
-    idcard: { enabled: boolean };
-    qrcode: { enabled: boolean };
+}
+
+/**
+ * Scanner module interface
+ * All modules must implement this interface
+ */
+export interface ScannerModule {
+  initialize(): Promise<void>;
+  destroy(): Promise<void>;
+}
+
+/**
+ * Image source types
+ */
+export type ImageSource = HTMLVideoElement | HTMLCanvasElement | HTMLImageElement | ImageData | string;
+
+/**
+ * Face detection result
+ */
+export interface Face {
+  box: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  };
+  confidence: number;
+  keypoints?: {
+    leftEye?: { x: number; y: number };
+    rightEye?: { x: number; y: number };
+    nose?: { x: number; y: number };
+    leftMouth?: { x: number; y: number };
+    rightMouth?: { x: number; y: number };
   };
-} 
+  embedding?: number[];
+}
 
 /**
- * 模块配置接口
- * 定义所有模块共享的基础配置属性
+ * Module configuration
  */
 export interface ModuleConfig {
-  /** 是否启用该模块 */
-  enabled: boolean;
-  /** 其他模块特定配置 */
+  enabled?: boolean;
   [key: string]: any;
-} 
+}