@incodetech/core 0.0.0-dev-20260126-4504c5b

package/dist/selfie.d.ts

@@ -0,0 +1,592 @@
+import { a as CameraStream, d as IMLProviderCapability, f as MLProviderConfig, i as StreamCanvasCapture, l as MotionPermissionState, n as PermissionStatus, o as IRecordingCapability, p as IncodeCanvas, r as BaseWasmProvider, t as PermissionResult, u as MotionStatus } from "./types-CRVSv38Q.js";
+import { a as AnyStateMachine, o as StateMachine, r as FlowModuleConfig, s as WasmPipeline, t as Flow } from "./types-CMR6NkxW.js";
+import { t as Manager } from "./Manager-Co-PsiG9.js";
+
+//#region ../infra/src/capabilities/IFaceDetectionCapability.d.ts
+
+/**
+ * Configuration for face detection provider.
+ * Extends base ML provider config with face-detection specific options.
+ */
+interface FaceDetectionConfig extends MLProviderConfig {
+  autocaptureInterval?: number;
+}
+interface FacePositionConstraints {
+  minX: number;
+  minY: number;
+  maxX: number;
+  maxY: number;
+}
+interface FaceDetectionThresholds {
+  brightnessThreshold: number;
+  blurrinessThreshold: number;
+  tiltRotationAngleThreshold: number;
+  minMagicCropSize: number;
+  autocaptureInterval: number;
+  minFaceQualityScore: number;
+  faceOcclusionThreshold: number;
+}
+interface FaceAttributesThresholds {
+  headwearThreshold: number;
+  lensesThreshold: number;
+  closedEyesThreshold: number;
+  maskThreshold: number;
+}
+interface FaceChecksConfig {
+  lenses: boolean;
+  mask: boolean;
+  closedEyes: boolean;
+  headWear: boolean;
+  occlusion: boolean;
+}
+interface FaceData {
+  rect: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  };
+  rightEye: {
+    x: number;
+    y: number;
+  };
+  leftEye: {
+    x: number;
+    y: number;
+  };
+  noseTip: {
+    x: number;
+    y: number;
+  };
+  rightMouthCorner: {
+    x: number;
+    y: number;
+  };
+  leftMouthCorner: {
+    x: number;
+    y: number;
+  };
+  pitch: number;
+  yaw: number;
+  roll: number;
+}
+type FaceCoordinates = {
+  rightEyeX: number;
+  rightEyeY: number;
+  leftEyeX: number;
+  leftEyeY: number;
+  noseTipX: number;
+  noseTipY: number;
+  rightMouthX: number;
+  rightMouthY: number;
+  mouthX: number;
+  mouthY: number;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+};
+interface FaceDetectionCallbacks {
+  onFarAway?: () => void;
+  onTooClose?: () => void;
+  onTooManyFaces?: () => void;
+  onNoFace?: () => void;
+  onCapture?: (canvas: IncodeCanvas, faceCoordinates: FaceCoordinates) => void;
+  onGetReady?: () => void;
+  onGetReadyFinished?: () => void;
+  onCenterFace?: () => void;
+  onDark?: () => void;
+  onBlur?: () => void;
+  onFaceAngle?: () => void;
+  onBestShot?: (face: FaceData) => void;
+  onLenses?: () => void;
+  onMask?: () => void;
+  onEyesClosed?: () => void;
+  onHeadWear?: () => void;
+  onSwitchToManualCapture?: () => void;
+  onFaceOccluded?: () => void;
+}
+/**
+ * Capability interface for face detection and selfie capture.
+ * Extends the base ML provider capability with face-detection specific methods.
+ */
+interface IFaceDetectionCapability extends IMLProviderCapability<FaceDetectionConfig> {
+  /**
+   * Sets callbacks for face detection events.
+   * @param callbacks - Object containing callback functions for various detection events
+   */
+  setCallbacks(callbacks: FaceDetectionCallbacks): void;
+  /**
+   * Sets position constraints for face detection.
+   * @param constraints - Bounding box constraints for valid face position
+   */
+  setPositionConstraints(constraints: FacePositionConstraints): void;
+  /**
+   * Sets detection thresholds for quality checks.
+   * @param thresholds - Threshold values for various quality metrics
+   */
+  setThresholds(thresholds: FaceDetectionThresholds): void;
+  /**
+   * Sets thresholds for face attribute detection.
+   * @param thresholds - Threshold values for attribute detection (headwear, lenses, etc.)
+   */
+  setAttributesThresholds(thresholds: FaceAttributesThresholds): void;
+  /**
+   * Enables or disables specific face checks.
+   * @param config - Configuration for which checks to enable
+   */
+  setChecksEnabled(config: FaceChecksConfig): void;
+  /**
+   * Sets video selfie mode.
+   * @param enabled - Whether to enable video selfie mode
+   */
+  setVideoSelfieMode(enabled: boolean): void;
+}
+//#endregion
+//#region ../infra/src/capabilities/IStorageCapability.d.ts
+/**
+ * Storage capability interface for abstracting storage operations.
+ * Enables swapping between browser localStorage and future WASM-based storage.
+ */
+interface IStorageCapability {
+  /**
+   * Retrieves a value from storage.
+   * @param key - The storage key
+   * @returns The stored value or null if not found
+   */
+  get<T>(key: string): Promise<T | null>;
+  /**
+   * Stores a value in storage.
+   * @param key - The storage key
+   * @param value - The value to store (will be serialized)
+   */
+  set<T>(key: string, value: T): Promise<void>;
+  /**
+   * Removes a value from storage.
+   * @param key - The storage key to remove
+   */
+  remove(key: string): Promise<void>;
+  /**
+   * Clears all values from storage.
+   */
+  clear(): Promise<void>;
+}
+//#endregion
+//#region ../infra/src/capabilities/IWasmUtilCapability.d.ts
+type WasmUtilConfig = MLProviderConfig & {
+  pipelines?: WasmPipeline[];
+};
+type VirtualCameraCheckOutput = {
+  canvas: HTMLCanvasElement | null;
+  itr: boolean | null;
+  skipped: boolean | null;
+};
+type IWasmUtilCapability = {
+  /**
+   * Whether the provider has been initialized and is ready to be used.
+   */
+  readonly initialized: boolean;
+  /**
+   * Initializes the provider with the given configuration.
+   * If WASM was already warmed up via `warmupWasm()`, this returns almost instantly.
+   * @param config - Provider configuration including WASM paths
+   */
+  initialize(config: WasmUtilConfig): Promise<void>;
+  /**
+   * Encrypts a base64 image using the WASM utility API.
+   * @param image - Base64 image string (no data URL prefix)
+   * @returns Encrypted string
+   */
+  encryptImage(image: string): string;
+  setSdkVersion(version: string): void;
+  setSdkPlatform(platform: string): void;
+  setDeviceInfo(deviceInfo: object, overrideExisting?: boolean): void;
+  setBrowserInfo(browserInfo: object, overrideExisting?: boolean): void;
+  setCameraInfo(cameraInfo: object, overrideExisting?: boolean): void;
+  setMotionStatus(status: string): void;
+  setBackgroundMode(backgroundMode: boolean): void;
+  setZc(zc: string): void;
+  setInspectorOpened(opened: boolean): void;
+  getMetadata(): string;
+  analyzeFrame(image: ImageData): Promise<void>;
+  getCheck(): string;
+  estimatePerformance(): string;
+  isVirtualCamera(label: string | null): boolean;
+  prc(): Promise<void>;
+  poc(output: VirtualCameraCheckOutput): Promise<void>;
+  ckvcks(data: ArrayBuffer): void;
+  getVersions(): Promise<unknown>;
+  /**
+   * Disposes of resources and resets initialization state.
+   */
+  dispose(): Promise<void>;
+};
+//#endregion
+//#region ../infra/src/providers/wasm/FaceDetectionProvider.d.ts
+declare class FaceDetectionProvider extends BaseWasmProvider implements IFaceDetectionCapability {
+  private defaultThresholds;
+  private currentThresholds;
+  private currentFrame;
+  private bestCanvas;
+  private bestFace;
+  constructor();
+  processFrame(image: ImageData): Promise<void>;
+  initialize(config: FaceDetectionConfig): Promise<void>;
+  setCallbacks(callbacks: FaceDetectionCallbacks): void;
+  setPositionConstraints(constraints: FacePositionConstraints): void;
+  applyDefaults(autocaptureInterval?: number): void;
+  setAutocaptureInterval(interval: number): void;
+  setThresholds(thresholds: FaceDetectionThresholds): void;
+  setAttributesThresholds(thresholds: FaceAttributesThresholds): void;
+  setChecksEnabled(config: FaceChecksConfig): void;
+  setVideoSelfieMode(enabled: boolean): void;
+  reset(): void;
+  private createDefaultFaceCoordinates;
+  private formatFaceCoordinates;
+}
+//#endregion
+//#region src/internal/deepsight/metadataService.d.ts
+type MetadataService = {
+  initialize(sdkVersion: string, disableIpify?: boolean): Promise<void>;
+  updateCameraInfo(videoTrack: MediaStreamTrack): void;
+  checkForVirtualCameraByLabel(videoTrack: MediaStreamTrack | null): Promise<boolean>;
+  analyzeFrame(imageData: ImageData): Promise<void>;
+  setMotionStatus(status: string): void;
+  setBackgroundMode(backgroundMode: boolean): void;
+  estimatePerformance(): string;
+  getMetadata(): string;
+  getCheck(): string;
+};
+//#endregion
+//#region src/internal/deepsight/motionStatusService.d.ts
+type MotionStatusService = {
+  requestPermission(): Promise<MotionPermissionState>;
+  start(): Promise<void>;
+  stop(): void;
+  check(): MotionStatus;
+  readonly isRunning: boolean;
+  readonly hasPermission: boolean;
+};
+//#endregion
+//#region src/internal/virtualCameraCheck.d.ts
+declare const frameSources: {
+  readonly front: "FRONT_ID";
+  readonly back: "BACK_ID";
+  readonly selfie: "SELFIE";
+};
+type FrameSource = (typeof frameSources)[keyof typeof frameSources];
+//#endregion
+//#region src/internal/deepsight/deepsightService.d.ts
+type DeepsightService = {
+  readonly metadata: MetadataService;
+  readonly motion: MotionStatusService;
+  initialize(disableIpify?: boolean): Promise<void>;
+  requestMotionPermission(): Promise<'granted' | 'denied' | 'not-required'>;
+  startMotionSensors(): Promise<void>;
+  stopMotionSensors(): void;
+  checkVirtualCamera(videoTrack: MediaStreamTrack): Promise<boolean>;
+  performVirtualCameraCheck(sessionToken: string | null, source: FrameSource): Promise<void>;
+  /**
+   * Runs PRC warmup and stores DS flag using infrastructure providers.
+   */
+  performPrcCheck(params: DeepsightPrcCheckParams): Promise<void>;
+  analyzeFrame(imageData: ImageData): Promise<void>;
+  getMetadata(): string;
+  cleanup(): void;
+};
+type DeepsightPrcCheckParams = {
+  constraints: MediaStreamConstraints;
+  ds?: boolean;
+  storage: IStorageCapability;
+};
+//#endregion
+//#region src/modules/selfie/types.d.ts
+type SelfieConfig = FlowModuleConfig['SELFIE'] & {
+  recording?: {
+    capability?: IRecordingCapability;
+  };
+  ds?: Flow['ds'];
+};
+type SelfieDependencies = {
+  storage: IStorageCapability;
+  getWasmUtil: () => Promise<IWasmUtilCapability>;
+};
+type DetectionStatus = 'idle' | 'detecting' | 'noFace' | 'tooManyFaces' | 'tooClose' | 'tooFar' | 'blur' | 'dark' | 'faceAngle' | 'headWear' | 'lenses' | 'eyesClosed' | 'faceMask' | 'centerFace' | 'manualCapture' | 'success' | 'error' | 'capturing' | 'getReady' | 'getReadyFinished' | 'offline';
+type SendFaceImageResponse = {
+  age: number;
+  confidence: number;
+  hasClosedEyes: boolean;
+  hasFaceMask: boolean;
+  hasHeadCover: boolean;
+  hasLenses: boolean;
+  isBright: boolean;
+  liveness: boolean;
+  imageBase64: string;
+  sessionStatus: string;
+};
+declare const FACE_ERROR_CODES: {
+  readonly FACE_OCCLUDED: "FACE_OCCLUDED";
+  readonly LIVENESS: "LIVENESS_ERROR";
+  readonly BRIGHTNESS: "BRIGHTNESS_ERROR";
+  readonly LENSES: "LENSES_ERROR";
+  readonly MASK: "MASK_ERROR";
+  readonly CLOSED_EYES: "CLOSED_EYES_ERROR";
+  readonly HEAD_COVER: "HEAD_COVER_ERROR";
+  readonly SERVER: "SERVER_ERROR";
+  readonly FACE_NOT_FOUND: "FACE_NOT_FOUND";
+  readonly MULTIPLE_FACES: "MULTIPLE_FACES";
+  readonly TOO_BLURRY: "TOO_BLURRY_ERROR";
+  readonly TOO_DARK: "TOO_DARK_ERROR";
+  readonly USER_IS_NOT_RECOGNIZED: "USER_IS_NOT_RECOGNIZED";
+  readonly SPOOF_ATTEMPT_DETECTED: "SPOOF_ATTEMPT_DETECTED";
+  readonly FACE_TOO_DARK: "FACE_TOO_DARK";
+  readonly LENSES_DETECTED: "LENSES_DETECTED";
+  readonly FACE_MASK_DETECTED: "FACE_MASK_DETECTED";
+  readonly CLOSED_EYES_DETECTED: "CLOSED_EYES_DETECTED";
+  readonly HEAD_COVER_DETECTED: "HEAD_COVER_DETECTED";
+  readonly FACE_CROPPING_FAILED: "FACE_CROPPING_FAILED";
+  readonly FACE_TOO_SMALL: "FACE_TOO_SMALL";
+  readonly FACE_TOO_BLURRY: "FACE_TOO_BLURRY";
+  readonly BAD_PHOTO_QUALITY: "BAD_PHOTO_QUALITY";
+  readonly PROCESSING_ERROR: "PROCESSING_ERROR";
+  readonly BAD_REQUEST: "BAD_REQUEST";
+  readonly NONEXISTENT_CUSTOMER: "NONEXISTENT_CUSTOMER";
+  readonly HINT_NOT_PROVIDED: "HINT_NOT_PROVIDED";
+  readonly SELFIE_IMAGE_LOW_QUALITY: "SELFIE_IMAGE_LOW_QUALITY";
+};
+type FaceErrorCode = (typeof FACE_ERROR_CODES)[keyof typeof FACE_ERROR_CODES];
+//#endregion
+//#region src/modules/selfie/selfieUploadService.d.ts
+type ProcessFaceImageType = 'selfie' | 'videoSelfie';
+type ProcessFaceResponse = {
+  faceMatch: boolean;
+  confidence: number;
+  existingUser: boolean;
+};
+declare function processFace(imageType?: ProcessFaceImageType, signal?: AbortSignal): Promise<ProcessFaceResponse>;
+//#endregion
+//#region src/modules/selfie/recordingService.d.ts
+type RecordingService = {
+  start(stream: MediaStream): Promise<void>;
+  stop(): Promise<{
+    recordingId: string | null;
+  }>;
+  cleanup(): void;
+};
+//#endregion
+//#region src/modules/selfie/selfieStateMachine.d.ts
+type SelfieContext = {
+  config: SelfieConfig;
+  dependencies: SelfieDependencies;
+  stream: CameraStream | undefined;
+  provider: FaceDetectionProvider | undefined;
+  frameCapturer: StreamCanvasCapture | undefined;
+  error: string | undefined;
+  detectionStatus: DetectionStatus;
+  debugFrame: ImageData | undefined;
+  capturedImage: IncodeCanvas | undefined;
+  faceCoordinates: FaceCoordinates | undefined;
+  uploadResponse: SendFaceImageResponse | undefined;
+  processResponse: ProcessFaceResponse | undefined;
+  recordingService: RecordingService | undefined;
+  attemptsRemaining: number;
+  uploadError: FaceErrorCode | undefined;
+  permissionResult: PermissionResult | 'refresh' | undefined;
+  resetDetection: (() => void) | undefined;
+  deepsightService: DeepsightService | undefined;
+};
+type SelfieEvent = {
+  type: 'LOAD';
+} | {
+  type: 'NEXT_STEP';
+} | {
+  type: 'REQUEST_PERMISSION';
+} | {
+  type: 'GO_TO_LEARN_MORE';
+} | {
+  type: 'BACK';
+} | {
+  type: 'QUIT';
+} | {
+  type: 'RESET';
+} | {
+  type: 'MANUAL_CAPTURE';
+} | {
+  type: 'DETECTION_UPDATE';
+  status: DetectionStatus;
+} | {
+  type: 'DETECTION_FRAME';
+  frame: ImageData;
+} | {
+  type: 'DETECTION_SUCCESS';
+  canvas: IncodeCanvas;
+  faceCoordinates?: FaceCoordinates;
+} | {
+  type: 'DETECTION_RESET_READY';
+  reset: () => void;
+} | {
+  type: 'RETRY_CAPTURE';
+};
+type SelfieInput = {
+  config: SelfieConfig;
+  dependencies: SelfieDependencies;
+};
+/**
+ * The selfie capture state machine.
+ *
+ * Note: Uses AnyStateMachine type for declaration file portability.
+ * Type safety is ensured via the machine configuration.
+ */
+declare const selfieMachine: AnyStateMachine;
+/**
+ * Type representing the selfie machine.
+ * For advanced use cases requiring specific machine types.
+ */
+type SelfieMachine = StateMachine<SelfieContext, SelfieEvent, any, any, any, any, any, any, any, SelfieInput, any, any, any, any>;
+//#endregion
+//#region src/modules/selfie/selfieActor.d.ts
+type CreateSelfieActorOptions = {
+  config: SelfieConfig;
+  dependencies?: SelfieDependencies;
+};
+//#endregion
+//#region src/modules/selfie/selfieManager.d.ts
+type CaptureStatus = 'initializing' | 'detecting' | 'capturing' | 'uploading' | 'uploadError' | 'success';
+/** Selfie manager is waiting to be started */
+type SelfieIdleState = {
+  status: 'idle';
+};
+/** Checking camera permissions (when no tutorial) */
+type SelfieLoadingState = {
+  status: 'loading';
+};
+/** Showing selfie tutorial */
+type SelfieTutorialState = {
+  status: 'tutorial';
+};
+/** Handling camera permissions */
+type SelfiePermissionsState = {
+  status: 'permissions';
+  /** Current permission sub-state: initial, requesting, denied, or learnMore */
+  permissionStatus: PermissionStatus;
+};
+/** Camera is ready for selfie capture */
+type SelfieCaptureState = {
+  status: 'capture';
+  /** Current capture sub-state */
+  captureStatus: CaptureStatus;
+  /** The active camera stream */
+  stream: CameraStream | undefined;
+  /** Current face detection status */
+  detectionStatus: DetectionStatus;
+  /** Latest frame processed in the detection loop (for UI debug rendering) */
+  debugFrame: ImageData | undefined;
+  /** Number of capture attempts remaining */
+  attemptsRemaining: number;
+  /** Error message from failed upload */
+  uploadError: string | undefined;
+};
+/** Processing the captured selfie */
+type SelfieProcessingState = {
+  status: 'processing';
+};
+/** Selfie capture completed successfully */
+type SelfieFinishedState = {
+  status: 'finished';
+  /** Face processing result (face match, confidence, existing user) */
+  processResponse: ProcessFaceResponse | undefined;
+};
+/** User closed the selfie flow */
+type SelfieClosedState = {
+  status: 'closed';
+};
+/** An error occurred during the flow */
+type SelfieErrorState = {
+  status: 'error';
+  /** The error message */
+  error: string;
+};
+/** Union of all possible selfie states */
+type SelfieState = SelfieIdleState | SelfieLoadingState | SelfieTutorialState | SelfiePermissionsState | SelfieCaptureState | SelfieProcessingState | SelfieFinishedState | SelfieClosedState | SelfieErrorState;
+/**
+ * Creates a selfie manager instance for handling selfie capture flow.
+ *
+ * The selfie manager provides:
+ * - State management with statuses: `idle`, `loading`, `tutorial`, `permissions`, `capture`, `finished`, `closed`, `error`
+ * - Permission handling with nested states: `idle`, `requesting`, `denied`, `learnMore`
+ * - Capture handling with nested states: `initializing`, `startingRecorder`, `recordingActive`, `detecting`, `capturing`, `uploading`, `uploadError`, `success`
+ * - Camera stream access when in `capture` state
+ * - Detection status feedback during face detection
+ * - Attempt tracking with `attemptsRemaining`
+ *
+ * @param options - Configuration for the selfie actor
+ * @param options.config - The selfie module configuration from the flow
+ * @returns A manager instance with state subscription, API methods, and lifecycle controls
+ *
+ * @example
+ * ```ts
+ * const selfieManager = createSelfieManager({ config: selfieConfig });
+ *
+ * selfieManager.subscribe((state) => {
+ *   if (state.status === 'capture') {
+ *     console.log('Camera ready:', state.stream);
+ *     console.log('Detection status:', state.detectionStatus);
+ *   }
+ * });
+ *
+ * selfieManager.load();
+ * ```
+ */
+declare function createSelfieManager(options: CreateSelfieActorOptions): Manager<SelfieState> & {
+  /**
+   * Starts the selfie flow.
+   * Goes to `tutorial` if showTutorial is true, otherwise to `loading`.
+   * Requires setup() to have been called with a token first.
+   */
+  load(): void;
+  /**
+   * Advances to the next step.
+   * From `tutorial` → permissions or capture (based on permission status).
+   * From `capture` → finished.
+   */
+  nextStep(): void;
+  /**
+   * Requests camera permission via getUserMedia.
+   * Only effective when in `permissions.idle` or `permissions.learnMore` state.
+   */
+  requestPermission(): void;
+  /**
+   * Navigates to the "learn more" permission screen.
+   * Only effective when in `permissions.idle` state.
+   */
+  goToLearnMore(): void;
+  /**
+   * Goes back from "learn more" to the initial permission screen.
+   * Only effective when in `permissions.learnMore` state.
+   */
+  back(): void;
+  /**
+   * Closes the selfie flow and transitions to `closed` state.
+   * Can be called from any state.
+   */
+  close(): void;
+  /**
+   * Resets the selfie manager to its initial `idle` state.
+   * Can be called from `error` state. Not available from `finished` (final state).
+   */
+  reset(): void;
+  /**
+   * Retries the capture after an upload error.
+   * Only effective when in `capture.uploadError` state and `attemptsRemaining > 0`.
+   * If no attempts remaining, the transition is blocked.
+   */
+  retryCapture(): void;
+  /**
+   * Captures a selfie in manual capture mode.
+   * Only effective when in `capture.detecting` state and `detectionStatus === 'manualCapture'`.
+   */
+  capture(): void;
+};
+type SelfieManager = ReturnType<typeof createSelfieManager>;
+//#endregion
+export { type CameraStream, type DeepsightService, type DetectionStatus, type FaceErrorCode, type PermissionResult, type PermissionStatus, type ProcessFaceResponse, type SelfieConfig, type SelfieMachine, type SelfieManager, type SelfieState, createSelfieManager, processFace, selfieMachine };