@incodetech/core 2.1.0-rc.1 → 2.1.0-rc.3

package/dist/video-selfie.d.ts

@@ -0,0 +1,351 @@
+import { n as WasmPipeline } from "./warmup-BJZPQIiX.js";
+import "./StateMachine-C_AY4cs7.js";
+import "./Actor-CGEelYtQ.js";
+import { t as CameraStream } from "./camera-CNVUo-bC.js";
+import "./types-DgGlgyZT.js";
+import "./types-D_IceWxT.js";
+import "./canvas-CJUmoXSD.js";
+import "./createFaceAvatar-B8pFpy6o.js";
+import { i as FlowModuleConfig } from "./types-BsYXnC5s.js";
+import "./IWasmUtilCapability-d2XvzaCk.js";
+import "./types-Duy2rDxF.js";
+import { n as DetectionStatus } from "./types-CxW2e0Ar.js";
+import * as xstate1577 from "xstate";
+
+//#region src/modules/video-selfie/types.d.ts
+/**
+ * The capture steps a Video Selfie session can run, in flow order. Which steps
+ * are active is derived from the module config (e.g. `checkIdScan` enables
+ * `frontId`/`backId`, `checkVoiceConsent` enables `speech`).
+ */
+type VideoSelfieStep = 'selfie' | 'frontId' | 'backId' | 'poa' | 'questions' | 'speech';
+/**
+ * Public Video Selfie configuration. Mirrors the backend `VIDEO_ONBOARDING`
+ * workflow module.
+ *
+ * The whole session is recorded on-device and streamed to the backend via S3
+ * multipart upload (`internal/recordings/multipartRecordingService`) — the
+ * client-side replacement for V1's server-side OpenVidu recording. See
+ * `docs/features/VIDEO_SELFIE.md`.
+ */
+type VideoSelfieConfig = FlowModuleConfig['VIDEO_ONBOARDING'];
+//#endregion
+//#region ../infra/src/media/CameraCompositor.d.ts
+/**
+ * Composites the *active* camera into a canvas and exposes the canvas as a
+ * single, stable `MediaStream` to record. Switching cameras (front ↔ back)
+ * just repoints what the canvas draws — the output stream and its audio track
+ * are never replaced — so a single `MediaRecorder` produces one continuous
+ * video that follows the camera switches (V1 parity), instead of restarting
+ * per camera.
+ *
+ * The audio track from the initial stream is carried through unchanged across
+ * video switches, so there's no audio glitch when the camera flips.
+ */
+declare class CameraCompositor {
+  private readonly fps;
+  private canvas;
+  private ctx;
+  private video;
+  private rafId;
+  private audioTrack;
+  private videoTrack;
+  private composite;
+  constructor(options?: {
+    fps?: number;
+  });
+  /**
+   * Begin compositing `stream` and return the composite stream to record. The
+   * stream's audio track (if any) is carried through unchanged across later
+   * `switchVideo` calls.
+   */
+  start(stream: CameraStream): MediaStream;
+  /**
+   * Swap the camera feeding the canvas without interrupting the composite
+   * stream. Pass a video-only stream (audio is kept from `start`). The previous
+   * video track is stopped.
+   */
+  switchVideo(stream: CameraStream): void;
+  /** The composite stream being recorded, if compositing is active. */
+  get stream(): MediaStream | undefined;
+  /** Stop compositing and release the canvas, audio, and video tracks. */
+  stop(): void;
+  private setVideoSource;
+  private startDrawLoop;
+}
+//#endregion
+//#region src/internal/recordings/multipartRecordingService.d.ts
+type MultipartRecordingResult = {
+  /**
+   * The completed upload's id, or `null` if recording produced no parts, a
+   * part upload failed, or finalization failed.
+   */
+  recordingId: string | null;
+};
+/**
+ * Records the camera on-device and streams it to the backend as it is
+ * captured, using the S3 multipart upload protocol
+ * (`/omni/video-selfie/upload/*`).
+ *
+ * This is the Video Selfie module's client-side recorder and is deliberately
+ * independent of the face-capture recording services (`LocalRecordingService`
+ * / `OpenViduRecordingService`) — it is the replacement for server-side
+ * (OpenVidu) recording, not a sibling of it.
+ *
+ * Parts upload concurrently with recording, so `stop()` only flushes the final
+ * part and finalizes — keeping the whole session inside the server's
+ * video-selfie timeout regardless of length, with client memory bounded to
+ * ~one part. No client-side encryption: video is encrypted at rest server-side
+ * (S3 SSE-AES-256).
+ */
+declare class MultipartRecordingService {
+  private recorder;
+  private uploadId;
+  private parts;
+  private inflight;
+  private uploadFailed;
+  get isRecording(): boolean;
+  start(stream: MediaStream): Promise<void>;
+  stop(): Promise<MultipartRecordingResult>;
+  cleanup(): void;
+}
+//#endregion
+//#region src/modules/video-selfie/videoSelfieStepDetector.d.ts
+/**
+ * Runs the WASM detection + backend validation for a single capture step over
+ * the given camera stream. Resolves once the step is captured AND validated by
+ * the backend (advance the flow), rejects on a terminal/validation failure
+ * (retry), and never settles for steps that have no auto-capture yet (the UI
+ * advances them manually).
+ */
+type StepDetector = (params: {
+  step: VideoSelfieStep;
+  stream: MediaStream;
+  signal: AbortSignal;
+  onStatus?: (status: DetectionStatus) => void;
+}) => Promise<void>;
+//#endregion
+//#region src/modules/video-selfie/videoSelfieRecordingMachine.d.ts
+type FacingMode = 'user' | 'environment';
+type VideoSelfieRecordingDependencies = {
+  createRecordingService?: () => MultipartRecordingService;
+  createCompositor?: () => CameraCompositor;
+  acquireCamera?: (facingMode: FacingMode, withAudio: boolean) => Promise<CameraStream>;
+  /** Runs WASM detection + backend validation per step; resolves to advance. */
+  detect?: StepDetector;
+};
+//#endregion
+//#region src/modules/video-selfie/videoSelfieRecordingActor.d.ts
+type CreateVideoSelfieRecordingActorOptions = {
+  /** Module config; its flags determine the active capture steps + validations. */
+  config?: VideoSelfieConfig;
+  dependencies?: VideoSelfieRecordingDependencies;
+};
+//#endregion
+//#region src/modules/video-selfie/videoSelfieRecordingManager.d.ts
+type VideoSelfieRecordingStatus = 'idle' | 'starting' | 'recording' | 'switchingCamera' | 'finalizing' | 'finished' | 'error' | 'aborted';
+type VideoSelfieRecordingState = {
+  /** Current lifecycle status. */
+  status: VideoSelfieRecordingStatus;
+  /** The active capture step (e.g. `selfie`, `frontId`). */
+  step: VideoSelfieStep | undefined;
+  /** Zero-based index of the active step. */
+  stepIndex: number;
+  /** Whether the active step is the last one (advancing it finalizes). */
+  isLastStep: boolean;
+  /** The active source camera (raw, per-step facing). */
+  stream: MediaStream | undefined;
+  /**
+   * The composited output stream (what's recorded) — a single canvas-backed
+   * stream that follows camera switches. Preferred for the preview: it has one
+   * camera consumer (the compositor), avoiding the black second-`<video>` that
+   * some devices show when the raw camera track is rendered twice.
+   */
+  composite: MediaStream | undefined;
+  /** Live per-step detection feedback (e.g. `tooFar`, `blur`, `detecting`). */
+  detectionStatus: DetectionStatus | undefined;
+  /** The completed upload id, available once `status === 'finished'`. */
+  recordingId: string | null;
+  /** Failure detail, set when `status === 'error'`. */
+  error: string | undefined;
+};
+/**
+ * Creates a manager for a multi-step, camera-switching Video Selfie recording.
+ *
+ * The whole session records as one continuous video that follows the camera
+ * across steps (front for selfie, rear for ID). Exposes `getState()` /
+ * `subscribe()` (status, step, preview `stream`, `recordingId`) plus `start()`,
+ * `nextStep()`, and `abort()`.
+ */
+declare function createVideoSelfieRecordingManager(options?: CreateVideoSelfieRecordingActorOptions): {
+  stop(): void;
+  getState(): VideoSelfieRecordingState;
+  subscribe(listener: (state: VideoSelfieRecordingState) => void): () => void;
+  /** Acquire the first camera, open the upload, and begin recording. */
+  start(): void;
+  /**
+   * Advance to the next step. Switches the camera when the next step's
+   * facing mode differs; finalizes the upload on the last step.
+   */
+  nextStep(): void;
+  /** Abandon the session without finalizing the upload. */
+  abort(): void;
+};
+type VideoSelfieRecordingManager = ReturnType<typeof createVideoSelfieRecordingManager>;
+//#endregion
+//#region src/modules/video-selfie/videoSelfieSteps.d.ts
+/**
+ * The camera facing mode a given step should use. ID and proof-of-address steps
+ * use the rear camera; selfie / questions / speech use the front camera.
+ */
+declare function facingModeForStep(step: VideoSelfieStep): 'user' | 'environment';
+/**
+ * Resolves the ordered list of active capture steps from the module config.
+ * The order mirrors V1 `getVideoSelfieModules`: the rear-camera document steps
+ * (`frontId` → `backId` → `poa`) run first, then the front-camera steps
+ * (`selfie` → `questions` → `speech`). This keeps the user from flipping the
+ * device between front and rear cameras mid-session. `selfie` is always present;
+ * the document and voice-consent steps are gated by their config flags.
+ *
+ * Both ID sides are captured whenever `checkIdScan` is on (a normal two-sided ID
+ * scan) — mirroring V1, which gated `back` on `checkIdScan`, not on the compare
+ * flags. `compareBackIdEnabled`/`compareBackOcrEnabled` only decide whether the
+ * captured back is *validated* against the backend (see `validateIdFrame` in
+ * `videoSelfieStepDetector`); with both off the back is captured passively on
+ * the first well-framed frame.
+ */
+declare function resolveVideoSelfieSteps(config: VideoSelfieConfig): VideoSelfieStep[];
+/**
+ * The WASM pipelines a Video Selfie session loads. The selfie step always runs
+ * face detection (`videoSelfie`); the ID steps run the simplified ID-capture
+ * pipeline (`videoSelfieId`), gated by `checkIdScan`. Used both for the
+ * flow-level eager warmup ({@link getRequiredWasmPipelines}) and the
+ * tutorial-time lazy warmup (`warmupVideoSelfieWasm`).
+ */
+declare function videoSelfieWasmPipelines(config: VideoSelfieConfig): WasmPipeline[];
+//#endregion
+//#region src/modules/video-selfie/videoSelfieWasm.d.ts
+/**
+ * Warms the WASM pipelines the Video Selfie flow needs (face detection, plus the
+ * ID-capture pipeline when `checkIdScan` is on), reusing the WASM config stored
+ * by `setup({ wasm })`.
+ *
+ * Idempotent and safe to call eagerly — the UI invokes it when the tutorial
+ * mounts so the models finish loading while the user reads the instructions, and
+ * detection is ready the instant recording starts (mirrors how the selfie and ID
+ * modules warm up during their tutorials). No-op when WASM was not configured.
+ */
+declare function warmupVideoSelfieWasm(config: VideoSelfieConfig): Promise<void>;
+//#endregion
+//#region src/modules/video-selfie/videoSelfieCameraWarmer.d.ts
+/**
+ * Warms the camera for a Video Selfie session ahead of time, so tapping "Start"
+ * on the tutorial begins recording without waiting on `getUserMedia` (mirrors how
+ * the selfie tutorial pre-acquires the camera "when possible").
+ *
+ * The acquire is gated on permission already being granted — exactly like the
+ * selfie tutorial — so we never trigger the OS camera/mic prompt while the user
+ * is still reading the instructions.
+ */
+type VideoSelfieCameraWarmer = {
+  /**
+   * Pre-acquire the first step's camera (video + audio) in the background, but
+   * only when camera permission is already granted. Idempotent — safe to call
+   * repeatedly (e.g. on every tutorial render).
+   */
+  warm(): void;
+  /**
+   * The `acquireCamera` dependency to hand to the recording manager. It returns
+   * the warmed stream for the machine's first acquire (matching facing mode +
+   * audio) and falls back to a fresh `getUserMedia` for every other acquire
+   * (e.g. the rear→front camera switch) and when nothing was warmed.
+   */
+  acquireCamera: NonNullable<VideoSelfieRecordingDependencies['acquireCamera']>;
+  /**
+   * Stop a warmed-but-unused stream. Call on unmount when capture never started
+   * so the camera light doesn't stay on. No-op once the stream has been consumed
+   * by the recording machine.
+   */
+  dispose(): void;
+};
+/**
+ * Creates a {@link VideoSelfieCameraWarmer} for the given config. The first
+ * camera (and whether it needs audio) is derived from the resolved step order —
+ * the same first acquire the recording machine performs on `START`.
+ */
+declare function createVideoSelfieCameraWarmer(config: VideoSelfieConfig): VideoSelfieCameraWarmer;
+//#endregion
+//#region src/modules/video-selfie/videoSelfieSpeechService.d.ts
+/** A single random question (and its expected answer) for the challenge step. */
+type VideoSelfieQuestion = {
+  id: string;
+  question: string;
+  answer: string;
+};
+/**
+ * Fetches `count` random challenge questions the user answers out loud. The
+ * spoken answers are captured in the main video recording (no separate upload)
+ * and verified server-side.
+ */
+declare function getVideoSelfieQuestions(count: number): Promise<VideoSelfieQuestion[]>;
+/**
+ * Fetches the voice-consent phrase the user must read aloud. The phrase is the
+ * `answer` of the consent question returned when `returnVoiceConsentQuestion`
+ * is requested with no challenge questions.
+ */
+declare function getVoiceConsentPhrase(): Promise<string>;
+//#endregion
+//#region src/modules/video-selfie/videoSelfieConsentRecorder.d.ts
+/**
+ * Drives the voice-consent audio capture for the Video Selfie speech step:
+ * records the spoken consent phrase as a standalone MP3 (separate from the main
+ * video) and uploads it for speech-to-text validation. The UI owns the start /
+ * submit timing (button taps); this keeps the L0 recorder + upload wiring out
+ * of the L2 component.
+ */
+type ConsentRecorder = {
+  /** Start capturing audio from the given stream (uses its audio tracks). */
+  start(stream: MediaStream): void;
+  /** Stop, encode to MP3 base64, and upload. Resolves the backend verdict. */
+  submit(): Promise<{
+    success: boolean;
+  }>;
+  /** Stop and discard without uploading (consent check disabled, or abort). */
+  cancel(): void;
+};
+declare function createConsentRecorder(): ConsentRecorder;
+//#endregion
+//#region src/modules/video-selfie/videoSelfieFlowModuleMachine.d.ts
+/**
+ * Parked flow-module machine for the `VIDEO_ONBOARDING` step.
+ *
+ * The video-selfie UI component owns the entire capture / streaming / upload
+ * lifecycle (it creates its own {@link createVideoSelfieRecordingManager}) and
+ * signals completion to the flow via `flowManager.completeModule()`
+ * (`MODULE_COMPLETE`). This machine therefore only needs to hold the step open:
+ * it starts in a non-final `running` state and never transitions, so the
+ * orchestrated flow stays in `runningModule` until the UI advances it.
+ *
+ * **Completion contract:** the L2 `incode-video-selfie` web component MUST call
+ * `flowManager.completeModule()` once the recording manager reaches `finished`
+ * (success) or `error` (terminal failure). Until that event is sent, the flow
+ * orchestrator remains in `runningModule` — this is intentional.
+ *
+ * **Abort / unmount:** if the user closes the module or the web component
+ * unmounts before completion, the orchestrated flow manager's existing close /
+ * abort path (`MODULE_CLOSE` / session teardown) is responsible for exiting the
+ * step. This parked machine does not model those paths itself.
+ *
+ * Contrast {@link noOpFlowModuleMachine}, whose initial state is `final` — that
+ * is used for headless steps (e.g. `IP_ADDRESS`) that must complete instantly
+ * with no UI. Using a no-op here would skip the video-selfie UI entirely.
+ */
+declare const videoSelfieFlowModuleMachine: xstate1577.StateMachine<xstate1577.MachineContext, xstate1577.AnyEventObject, {}, never, never, never, never, "running", string, xstate1577.NonReducibleUnknown, xstate1577.NonReducibleUnknown, xstate1577.EventObject, xstate1577.MetaObject, {
+  readonly id: "videoSelfieFlowModule";
+  readonly initial: "running";
+  readonly states: {
+    readonly running: {};
+  };
+}>;
+//#endregion
+export { type ConsentRecorder, type CreateVideoSelfieRecordingActorOptions, type VideoSelfieCameraWarmer, type VideoSelfieConfig, type VideoSelfieQuestion, type VideoSelfieRecordingManager, type VideoSelfieRecordingState, type VideoSelfieRecordingStatus, type VideoSelfieStep, createConsentRecorder, createVideoSelfieCameraWarmer, createVideoSelfieRecordingManager, facingModeForStep, getVideoSelfieQuestions, getVoiceConsentPhrase, resolveVideoSelfieSteps, videoSelfieFlowModuleMachine, videoSelfieWasmPipelines, warmupVideoSelfieWasm };