@incodetech/core 2.1.1 → 2.2.0-rc.0

package/dist/face-match.d.ts

@@ -1,227 +1,4 @@
-import "./StateMachine-D5WO6lHS.js";
-import { t as Manager } from "./Manager-goNPc_h_.js";
-
-//#region src/modules/face-match/types.d.ts
-/**
- * Face match comparison variant.
- * Determines which images are compared in the face match flow.
- */
-type FaceMatchVariant = 'selfieVsId' | 'selfieVsNfc' | 'idVsNfc' | 'nfc3Way' | 'secondId';
-/**
- * Configuration options for face match module.
- *
- * @example Standard face match with animation
- * ```typescript
- * const config: FaceMatchConfig = {
- *   matchingType: 'selfieVsId',
- *   disableFaceMatchAnimation: false,
- * };
- * ```
- *
- * @example Auto-skip mode (headless)
- * ```typescript
- * const config: FaceMatchConfig = {
- *   matchingType: 'selfieVsId',
- *   disableFaceMatchAnimation: true,
- * };
- * ```
- */
-type FaceMatchConfig = {
-  /**
-   * Which images to compare in the face match flow.
-   * Backend field name: `matchingType`.
-   * @default 'selfieVsId'
-   */
-  matchingType?: FaceMatchVariant;
-  /**
-   * When true, skips the animation UI and auto-completes immediately after fetching data.
-   * Useful for headless integrations or silent verification flows.
-   * @default false
-   */
-  disableFaceMatchAnimation?: boolean;
-};
-/**
- * Cropped face images fetched from the backend.
- */
-type FaceMatchImages = {
-  /**
-   * Cropped face from ID document.
-   */
-  idFace: string | null;
-  /**
-   * Cropped selfie image (from face capture).
-   */
-  selfie: string | null;
-  /**
-   * Cropped face from second ID document (only for 'secondId' variant).
-   */
-  secondIdFace?: string | null;
-};
-/**
- * Face match result parsed from score response.
- */
-type FaceMatchResult = {
-  /**
-   * Whether faces matched (OK = true, FAIL = false, null = unknown).
-   */
-  matched: boolean | null;
-  /**
-   * Whether liveness check passed.
-   */
-  liveness: boolean | null;
-};
-//#endregion
-//#region src/modules/face-match/faceMatchActor.d.ts
-type CreateFaceMatchActorOptions = {
-  config: FaceMatchConfig;
-};
-//#endregion
-//#region src/modules/face-match/faceMatchManager.d.ts
-/** Face match manager is in initial state, waiting for `load()` to be called */
-type FaceMatchIdleState = {
-  status: 'idle';
-};
-/** Fetching images and score from backend */
-type FaceMatchLoadingState = {
-  status: 'loading';
-};
-/**
- * Animation is playing - images are animating.
- * @property images - Cropped face images fetched from backend
- * @property result - Face match result (matched, liveness)
- */
-type FaceMatchAnimatingState = {
-  status: 'animating';
-  images: {
-    idFace: string | null;
-    selfie: string | null;
-    secondIdFace?: string | null;
-  };
-  result: {
-    matched: boolean | null;
-    liveness: boolean | null;
-  };
-};
-/**
- * Showing match result - waiting for user to click continue.
- * @property images - Cropped face images
- * @property result - Face match result
- * @property matched - Whether faces matched (true/false/null)
- */
-type FaceMatchResultState = {
-  status: 'result';
-  images: {
-    idFace: string | null;
-    selfie: string | null;
-    secondIdFace?: string | null;
-  };
-  result: {
-    matched: boolean | null;
-    liveness: boolean | null;
-  };
-  matched: boolean | null;
-};
-/** Face match completed successfully */
-type FaceMatchFinishedState = {
-  status: 'finished';
-  matched: boolean | null;
-};
-/**
- * Fatal error occurred - call `reset()` to start over
- * @property error - Error message describing what went wrong
- */
-type FaceMatchErrorState = {
-  status: 'error';
-  error: string;
-};
-/**
- * Union of all possible face match manager states.
- * Use discriminated union pattern to narrow the type:
- *
- * @example
- * ```typescript
- * const state = faceMatchManager.getState();
- * if (state.status === 'animating') {
- *   // TypeScript knows state has images and result
- *   console.log(state.images.idFace);
- * }
- * ```
- */
-type FaceMatchState = FaceMatchIdleState | FaceMatchLoadingState | FaceMatchAnimatingState | FaceMatchResultState | FaceMatchFinishedState | FaceMatchErrorState;
-/**
- * Creates a face match manager for headless or UI-driven usage.
- *
- * The manager provides a state machine-based API for face comparison
- * with optional animation display.
- *
- * @param options - Configuration options
- * @param options.config - Face match configuration
- * @param options.config.matchingType - Which images to compare (default: 'selfieVsId')
- * @param options.config.disableFaceMatchAnimation - Skip animation and auto-complete (default: false)
- *
- * @returns Face match manager with state, API methods, and subscription
- *
- * @example Headless usage
- * ```typescript
- * const manager = createFaceMatchManager({
- *   config: { matchingType: 'selfieVsId', disableFaceMatchAnimation: true },
- * });
- *
- * manager.subscribe((state) => console.log(state.status));
- * manager.load();
- * // Auto-completes when disableFaceMatchAnimation is true
- * manager.stop();
- * ```
- *
- * @example With React/Preact UI hook
- * ```tsx
- * const [state, manager] = useManager(() => createFaceMatchManager({ config }));
- *
- * if (state.status === 'animating') {
- *   return <Animation images={state.images} />;
- * }
- * ```
- */
-declare function createFaceMatchManager(options: CreateFaceMatchActorOptions): Manager<FaceMatchState> & {
-  /**
-   * Initializes the face match flow.
-   * Transitions from 'idle' to 'loading'.
-   * Must be called before any other method.
-   */
-  load(): void;
-  /**
-   * Signals that the animation has completed.
-   * Should be called when state is 'animating' and your UI animation finishes.
-   * Transitions to 'result' state.
-   */
-  animationComplete(): void;
-  /**
-   * User clicked continue button.
-   * Should be called when state is 'result'.
-   * Transitions to 'finished' state.
-   */
-  continue(): void;
-  /**
-   * Resets the manager to initial state.
-   * Can be called from 'error' state to start over.
-   * Clears all stored data including images and result.
-   */
-  reset(): void;
-};
-/**
- * Type representing a face match manager instance.
- * Includes state access, API methods, and lifecycle management.
- *
- * @property getState - Returns the current FaceMatchState
- * @property subscribe - Subscribes to state changes, returns unsubscribe function
- * @property stop - Stops the manager and cleans up resources
- * @property load - Initializes the face match flow
- * @property animationComplete - Signals animation finished
- * @property continue - User clicked continue button
- * @property reset - Resets to initial state
- */
-type FaceMatchManager = ReturnType<typeof createFaceMatchManager>;
-//#endregion
+import { a as FaceMatchActor, c as FaceMatchResult, i as createFaceMatchManagerFromActor, l as FaceMatchVariant, n as FaceMatchState, o as FaceMatchConfig, r as createFaceMatchManager, s as FaceMatchImages, t as FaceMatchManager } from "./faceMatchManager-BnvrZM2F.js";
 //#region src/modules/face-match/faceMatchStateMachine.d.ts
 declare const faceMatchMachine: any;
 //#endregion
@@ -244,4 +21,4 @@ declare const ID_FACE_EXTRACTION_SKIPPED_CODE = 4084;
  */
 declare function isFaceExtractionSkippedError(error: unknown): boolean;
 //#endregion
-export { type FaceMatchConfig, type FaceMatchImages, type FaceMatchManager, type FaceMatchResult, type FaceMatchState, type FaceMatchVariant, ID_FACE_EXTRACTION_SKIPPED_CODE, createFaceMatchManager, faceMatchMachine, isFaceExtractionSkippedError };
+export { type FaceMatchActor, type FaceMatchConfig, type FaceMatchImages, type FaceMatchManager, type FaceMatchResult, type FaceMatchState, type FaceMatchVariant, ID_FACE_EXTRACTION_SKIPPED_CODE, createFaceMatchManager, createFaceMatchManagerFromActor, faceMatchMachine, isFaceExtractionSkippedError };

package/dist/face-match.esm.js

@@ -1,173 +1,3 @@
-import "./api-DsbUi7TO.esm.js";
-import { n as eventModuleNames, s as createManagerInstrumentation } from "./events-1wxZ97yf.esm.js";
-import "./endpoints-CwrFQfW7.esm.js";
-import { l as createManager, s as createActor } from "./xstate.esm-nY3M5UYm.esm.js";
-import { n as ID_FACE_EXTRACTION_SKIPPED_CODE, r as isFaceExtractionSkippedError, t as faceMatchMachine } from "./faceMatchStateMachine-MDb30gCm.esm.js";
-
-//#region src/modules/face-match/faceMatchActor.ts
-function createFaceMatchActor(options) {
-	return createActor(faceMatchMachine, { input: { config: options.config } }).start();
-}
-
-//#endregion
-//#region src/modules/face-match/faceMatchManager.ts
-/**
-* @module @incodetech/core/face-match
-*
-* Face match module for the Incode Web SDK.
-* Supports both headless (programmatic) and UI-driven usage patterns.
-*
-* ## Headless Usage
-*
-* The face match manager can be used entirely without UI for backend integrations,
-* custom UI implementations, or automated workflows.
-*
-* @example Basic headless face match with auto-skip
-* ```typescript
-* import { createFaceMatchManager } from '@incodetech/core/face-match';
-* import { setup } from '@incodetech/core';
-*
-* // 1. Configure the SDK (required before using any module)
-* setup({ apiURL: 'https://api.example.com', token: 'your-token' });
-*
-* // 2. Create the face match manager
-* const faceMatchManager = createFaceMatchManager({
-*   config: {
-*     matchingType: 'selfieVsId',
-*     disableFaceMatchAnimation: true,
-*   },
-* });
-*
-* // 3. Subscribe to state changes (optional but recommended)
-* faceMatchManager.subscribe((state) => {
-*   console.log('Face match state:', state.status);
-*   if (state.status === 'finished') {
-*     console.log('Face match complete!', state.matched);
-*   }
-*   if (state.status === 'error') {
-*     console.error('Error:', state.error);
-*   }
-* });
-*
-* // 4. Start the flow
-* faceMatchManager.load();
-*
-* // 5. Auto-completes when disableFaceMatchAnimation is true
-* // Or call faceMatchManager.continue() after animation in custom UI
-*
-* // 6. Clean up when done
-* faceMatchManager.stop();
-* ```
-*
-* @example Headless face match with custom UI
-* ```typescript
-* const faceMatchManager = createFaceMatchManager({
-*   config: { matchingType: 'selfieVsId', disableFaceMatchAnimation: false },
-* });
-*
-* faceMatchManager.subscribe((state) => {
-*   if (state.status === 'animating') {
-*     // Render your custom animation
-*     renderAnimation(state.images, state.result);
-*   }
-*   if (state.status === 'result') {
-*     // Show result and wait for user to click continue
-*     showResult(state.matched);
-*   }
-* });
-*
-* faceMatchManager.load();
-* // When animation completes in your UI:
-* faceMatchManager.animationComplete();
-* // When user clicks continue:
-* faceMatchManager.continue();
-* ```
-*/
-function mapState(snapshot) {
-	const typedSnapshot = snapshot;
-	const { context } = typedSnapshot;
-	if (typedSnapshot.matches("idle")) return { status: "idle" };
-	if (typedSnapshot.matches("loading")) return { status: "loading" };
-	if (typedSnapshot.matches("animating")) return {
-		status: "animating",
-		images: context.images,
-		result: context.result
-	};
-	if (typedSnapshot.matches("result")) return {
-		status: "result",
-		images: context.images,
-		result: context.result,
-		matched: context.result.matched
-	};
-	if (typedSnapshot.matches("finished")) return {
-		status: "finished",
-		matched: context.result?.matched ?? null
-	};
-	if (typedSnapshot.matches("error")) return {
-		status: "error",
-		error: context.error ?? "An error occurred"
-	};
-	return { status: "idle" };
-}
-function createApi({ actor, trackElementClicked }) {
-	return {
-		load() {
-			actor.send({ type: "LOAD" });
-		},
-		animationComplete() {
-			actor.send({ type: "ANIMATION_COMPLETE" });
-		},
-		continue() {
-			trackElementClicked?.("continue");
-			actor.send({ type: "CONTINUE" });
-		},
-		reset() {
-			actor.send({ type: "RESET" });
-		}
-	};
-}
-/**
-* Creates a face match manager for headless or UI-driven usage.
-*
-* The manager provides a state machine-based API for face comparison
-* with optional animation display.
-*
-* @param options - Configuration options
-* @param options.config - Face match configuration
-* @param options.config.matchingType - Which images to compare (default: 'selfieVsId')
-* @param options.config.disableFaceMatchAnimation - Skip animation and auto-complete (default: false)
-*
-* @returns Face match manager with state, API methods, and subscription
-*
-* @example Headless usage
-* ```typescript
-* const manager = createFaceMatchManager({
-*   config: { matchingType: 'selfieVsId', disableFaceMatchAnimation: true },
-* });
-*
-* manager.subscribe((state) => console.log(state.status));
-* manager.load();
-* // Auto-completes when disableFaceMatchAnimation is true
-* manager.stop();
-* ```
-*
-* @example With React/Preact UI hook
-* ```tsx
-* const [state, manager] = useManager(() => createFaceMatchManager({ config }));
-*
-* if (state.status === 'animating') {
-*   return <Animation images={state.images} />;
-* }
-* ```
-*/
-function createFaceMatchManager(options) {
-	return createManager({
-		actor: createFaceMatchActor(options),
-		mapState,
-		createApi,
-		instrumentation: createManagerInstrumentation(eventModuleNames.faceMatch)
-	});
-}
-
-//#endregion
-export { ID_FACE_EXTRACTION_SKIPPED_CODE, createFaceMatchManager, faceMatchMachine, isFaceExtractionSkippedError };
+import { n as ID_FACE_EXTRACTION_SKIPPED_CODE, r as isFaceExtractionSkippedError, t as faceMatchMachine } from "./faceMatchStateMachine-CJiO2yLO.esm.js";
+import { n as createFaceMatchManagerFromActor, t as createFaceMatchManager } from "./faceMatchManager-BXp2WUT-.esm.js";
+export { ID_FACE_EXTRACTION_SKIPPED_CODE, createFaceMatchManager, createFaceMatchManagerFromActor, faceMatchMachine, isFaceExtractionSkippedError };

package/dist/{faceCaptureManagerFactory-C9TiGbkA.esm.js → faceCaptureManagerFactory-BDAsBCkh.esm.js}

@@ -1,14 +1,14 @@
-import { n as eventModuleNames, o as topLevelStateName, r as eventScreenNames, s as createManagerInstrumentation } from "./events-1wxZ97yf.esm.js";
-import { l as createManager } from "./xstate.esm-nY3M5UYm.esm.js";
-import { n as concealmentToAvatar } from "./faceCaptureSetup-BqhqfFHL.esm.js";
-import { t as setWasmDsFlagSync } from "./wasmDsFlagSync-Ch0mFJNT.esm.js";
-import { t as BrowserVisibilityObserverProvider } from "./BrowserVisibilityObserverProvider-GBS6XSii.esm.js";
-import { r as primeMotionFromUserGestureIfNeeded } from "./permissionServices-C_kxhNeo.esm.js";
-
+import { n as eventModuleNames, o as createManagerInstrumentation, r as eventScreenNames } from "./events-CxfNJVZW.esm.js";
+import { t as topLevelStateName } from "./topLevelStateName-B5i2avbh.esm.js";
+import { c as createManager } from "./xstate.esm-Cf4e0Cfd.esm.js";
+import { n as concealmentToAvatar } from "./faceCaptureSetup-C7Qv79fA.esm.js";
+import { t as setWasmDsFlagSync } from "./wasmDsFlagSync-BqUCwLY8.esm.js";
+import { t as BrowserVisibilityObserverProvider } from "./BrowserVisibilityObserverProvider-BX1BiLDK.esm.js";
+import { r as primeMotionFromUserGestureIfNeeded } from "./permissionServices-UvUcOSRb.esm.js";
 //#region src/internal/faceCapture/faceCaptureManagerFactory.ts
 function getPermissionStatus(snapshot) {
 	if (!snapshot.matches("permissions")) return;
-	if (snapshot.matches({ permissions: "idle" })) return "idle";
+	if (snapshot.matches({ permissions: "idle" })) return "checking";
 	if (snapshot.matches({ permissions: "waitingForUser" })) return "idle";
 	if (snapshot.matches({ permissions: "learnMore" })) return "learnMore";
 	if (snapshot.matches({ permissions: "requesting" })) return "requesting";
@@ -54,10 +54,10 @@ function mapState(snapshot) {
 			captureStatus: captureStatus ?? "initializing",
 			stream: context.stream,
 			detectionStatus: context.detectionStatus ?? "idle",
-			debugFrame: context.debugFrame,
 			attemptsRemaining: context.attemptsRemaining ?? 0,
 			uploadError: context.uploadError,
 			assistedOnboarding: context.config?.assistedOnboarding ?? false,
+			usingBackCamera: context.usingBackCamera ?? false,
 			ageAssurance: context.config?.ageAssurance === true,
 			onDeviceMode: context.config?.onDeviceFaceResultsSubmissionEnabled === true,
 			obfuscateWithAvatar,
@@ -114,8 +114,6 @@ function getCapturingScreen(detectionStatus) {
 		case "detecting":
 		case "idle":
 		case "offline": return "faceCapture.genericErrors.noConnection";
-		case "success":
-		case "error":
 		default: return "faceCapture.capturing.initiatingState";
 	}
 }
@@ -141,11 +139,6 @@ function getResultErrorScreen(errorCode, attemptsRemaining) {
 		case "SERVER_ERROR":
 		case "PROCESSING_ERROR":
 		case "BAD_REQUEST": return `faceCapture.resultError.processingFailed${exhaustedSuffix}`;
-		case "FACE_NOT_FOUND":
-		case "MULTIPLE_FACES":
-		case "FACE_CROPPING_FAILED":
-		case "FACE_TOO_SMALL":
-		case "LIVENESS_ERROR":
 		default: return `faceCapture.resultError.faceNotAligned${exhaustedSuffix}`;
 	}
 }
@@ -213,11 +206,6 @@ function getAuthFaceScreenName(snapshot) {
 		case "capture": return getAuthFaceCaptureSubstateScreen(snapshot);
 		case "finished": return eventScreenNames.authFaceUploadSuccess;
 		case "error": return eventScreenNames.authFaceUploadFailed;
-		case "idle":
-		case "loading":
-		case "permissions":
-		case "processing":
-		case "closed":
 		default: return eventScreenNames.authFace;
 	}
 }
@@ -244,16 +232,26 @@ function createApi({ actor, trackElementClicked, trackCaptureAttemptFinished })
 	const snapshot = actor.getSnapshot();
 	snapshot.context.dependencies.trackCaptureAttemptFinished = trackCaptureAttemptFinished;
 	return {
+		/**
+		* Starts the face capture flow.
+		* Goes to `tutorial` if showTutorial is true, otherwise to `loading`.
+		* Requires setup() to have been called with a token first.
+		*/
 		load() {
 			const { config } = actor.getSnapshot().context;
 			if (config.ds === true) setWasmDsFlagSync(true);
 			actor.send({ type: "LOAD" });
 		},
+		/**
+		* Advances to the next step.
+		* From `tutorial` → permissions or capture (based on permission status).
+		* From `capture` → finished.
+		*/
 		async nextStep() {
 			trackElementClicked?.("nextStep");
-			const snapshot$1 = actor.getSnapshot();
-			if (snapshot$1.matches("tutorial")) {
-				const { config, permissionResult } = snapshot$1.context;
+			const snapshot = actor.getSnapshot();
+			if (snapshot.matches("tutorial")) {
+				const { config, permissionResult } = snapshot.context;
 				await primeMotionFromUserGestureIfNeeded({
 					ds: config.ds,
 					cameraGranted: permissionResult === "granted"
@@ -261,29 +259,58 @@ function createApi({ actor, trackElementClicked, trackCaptureAttemptFinished })
 			}
 			actor.send({ type: "NEXT_STEP" });
 		},
+		/**
+		* Requests camera permission via getUserMedia.
+		* Only effective when in `permissions.idle` or `permissions.learnMore` state.
+		*/
 		requestPermission() {
 			trackElementClicked?.("requestPermission");
 			actor.send({ type: "REQUEST_PERMISSION" });
 		},
+		/**
+		* Navigates to the "learn more" permission screen.
+		* Only effective when in `permissions.idle` state.
+		*/
 		goToLearnMore() {
 			trackElementClicked?.("goToLearnMore");
 			actor.send({ type: "GO_TO_LEARN_MORE" });
 		},
+		/**
+		* Goes back from "learn more" to the initial permission screen.
+		* Only effective when in `permissions.learnMore` state.
+		*/
 		back() {
 			trackElementClicked?.("back");
 			actor.send({ type: "BACK" });
 		},
+		/**
+		* Closes the face capture flow and transitions to `closed` state.
+		* Can be called from any state.
+		*/
 		close() {
 			trackElementClicked?.("close");
 			actor.send({ type: "QUIT" });
 		},
+		/**
+		* Resets the face capture manager to its initial `idle` state.
+		* Can be called from `error` state. Not available from `finished` (final state).
+		*/
 		reset() {
 			actor.send({ type: "RESET" });
 		},
+		/**
+		* 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() {
 			trackElementClicked?.("retryCapture");
 			actor.send({ type: "RETRY_CAPTURE" });
 		},
+		/**
+		* Captures a face in manual capture mode.
+		* Only effective when in `capture.detecting` state and `detectionStatus === 'manualCapture'`.
+		*/
 		capture() {
 			trackElementClicked?.("capture");
 			actor.send({ type: "MANUAL_CAPTURE" });
@@ -317,11 +344,6 @@ function getFaceErrorReason(errorCode) {
 		case "SERVER_ERROR":
 		case "PROCESSING_ERROR":
 		case "BAD_REQUEST": return "processingFailed";
-		case "FACE_NOT_FOUND":
-		case "MULTIPLE_FACES":
-		case "FACE_CROPPING_FAILED":
-		case "FACE_TOO_SMALL":
-		case "LIVENESS_ERROR":
 		default: return "faceNotAligned";
 	}
 }
@@ -391,6 +413,5 @@ function createFaceCaptureManagerFromActor(actor, moduleName, visibilityObserver
 		})
 	});
 }
-
 //#endregion
-export { createFaceCaptureManagerFromActor as t };
+export { createFaceCaptureManagerFromActor as t };