@incodetech/core 2.1.1 → 2.2.0-rc.0

package/dist/video-selfie.d.ts

@@ -1,133 +1,64 @@
-import { n as WasmPipeline } from "./warmup-Dd0iq6KF.js";
-import "./StateMachine-D5WO6lHS.js";
-import "./Actor-BwgmOPkb.js";
-import { t as CameraStream } from "./camera-CKU96nwJ.js";
-import "./types-DV3wkhQ4.js";
-import "./types-BgjMAEXl.js";
-import "./canvas-90BqS0NF.js";
-import "./createFaceAvatar-CpdYp9Iy.js";
-import { i as FlowModuleConfig } from "./types-BUgeB2X6.js";
-import "./IWasmUtilCapability-DaSNxgA8.js";
-import "./types-BcF-fii5.js";
-import { n as DetectionStatus } from "./types-fO6KIdol.js";
-import * as xstate1002 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/capabilities/ICameraCapability.d.ts
-type FacingMode = 'user' | 'environment';
-//#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
+import { n as WasmPipeline } from "./warmup-Dv2alr2-.js";
+import { A as StateMachine, _ as MachineContext, c as AnyEventObject, p as EventObject, v as MetaObject, y as NonReducibleUnknown } from "./spawn-D9jgw9pW.js";
+import "./StateMachine-EDpYWy0i.js";
+import "./Actor-iTq7YY48.js";
+import { t as CameraStream } from "./camera-9wWD-pwg.js";
+import { t as DetectionOrientation } from "./IIdCaptureCapability-DHTT3FC2.js";
+import { a as FacingMode, i as CameraCompositor, n as VideoSelfieDetectionStatus, o as VideoSelfieConfig, r as VideoSelfieValidationFailure, s as VideoSelfieStep, t as StepDetector } from "./videoSelfieStepDetector-D3oo2ofo.js";
 //#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.
+   * chunk could not be delivered even after the retry rounds, 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/*`).
+ * captured, using the video-selfie-service multipart upload protocol
+ * (`/v1/video-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
+ * Every ~1 s recorder blob uploads as its own chunk, concurrently with
+ * recording, through {@link VideoSelfieChunkUploader} (keep-until-ack +
+ * retry with backoff — see its doc for the full policy). The service stages
+ * sub-5 MiB chunks and combines them server-side, so `stop()` only drains
+ * the stragglers and finalizes; client memory holds un-acked chunks only.
+ * 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;
+  private timer;
+  private session;
+  private uploader;
+  private chunksEmitted;
   get isRecording(): boolean;
   start(stream: MediaStream): Promise<void>;
   stop(): Promise<MultipartRecordingResult>;
   cleanup(): void;
+  /**
+   * `complete` is idempotent server-side ("safe to repeat if the response
+   * was lost"), so transient failures — network errors, 5xx, 429 — retry a
+   * couple of times before the recording is declared failed. A 4xx (e.g.
+   * `400` naming a missing part) is permanent: after a clean drain every
+   * chunk was acked, so a reported hole cannot be filled from here.
+   */
+  private completeWithRetry;
+  /**
+   * Fire-and-forget abort: the upload can no longer complete, so tell the
+   * backend to fail it immediately rather than at its expiry. Best-effort —
+   * an abort that doesn't land (including a 409 from a newer epoch having
+   * taken over) just means the server falls back to expiry or salvage.
+   */
+  private abandonUpload;
 }
 //#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 VideoSelfieRecordingDependencies = {
   createRecordingService?: () => MultipartRecordingService;
@@ -135,7 +66,16 @@ type VideoSelfieRecordingDependencies = {
   acquireCamera?: (facingMode: FacingMode, withAudio: boolean) => Promise<CameraStream>;
   /** Runs WASM detection + backend validation per step; resolves to advance. */
   detect?: StepDetector;
+  /** Minimum time to hold the switching-camera screen before resuming capture. */
+  switchingCameraMinDwellMs?: number;
 };
+/**
+ * Why the module errored: `connection` means a transport-level failure the
+ * user can fix by getting back online (the UI shows the connection-error
+ * copy); `technical` is everything else (raw detail stays in `error` for
+ * diagnostics/hosts, the UI shows its generic fallback).
+ */
+type VideoSelfieErrorKind = 'connection' | 'technical';
 //#endregion
 //#region src/modules/video-selfie/videoSelfieRecordingActor.d.ts
 type CreateVideoSelfieRecordingActorOptions = {
@@ -145,7 +85,7 @@ type CreateVideoSelfieRecordingActorOptions = {
 };
 //#endregion
 //#region src/modules/video-selfie/videoSelfieRecordingManager.d.ts
-type VideoSelfieRecordingStatus = 'idle' | 'starting' | 'recording' | 'switchingCamera' | 'finalizing' | 'finished' | 'error' | 'aborted';
+type VideoSelfieRecordingStatus = 'idle' | 'starting' | 'recording' | 'validationFeedback' | 'flippingId' | 'switchingCamera' | 'finalizing' | 'success' | 'finished' | 'error' | 'aborted';
 type VideoSelfieRecordingState = {
   /** Current lifecycle status. */
   status: VideoSelfieRecordingStatus;
@@ -158,18 +98,32 @@ type VideoSelfieRecordingState = {
   /** 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.
+   * The composited recording output — a bounded canvas-backed stream that
+   * follows camera switches while the preview renders the raw source stream.
    */
   composite: MediaStream | undefined;
   /** Live per-step detection feedback (e.g. `tooFar`, `blur`, `detecting`). */
-  detectionStatus: DetectionStatus | undefined;
-  /** The completed upload id, available once `status === 'finished'`. */
+  detectionStatus: VideoSelfieDetectionStatus | undefined;
+  /**
+   * Live document orientation from the ID detector, when the pipeline
+   * reports one — the mask follows a rotated ID. `undefined` keeps the
+   * default fixed frame.
+   */
+  orientation: DetectionOrientation | undefined;
+  /** Validation failure shown during the current retry/exhaustion dwell. */
+  validationFailure: VideoSelfieValidationFailure | undefined;
+  /** Remaining validation attempts for the active capture step; `-1` means unlimited. */
+  attemptsRemaining: number;
+  /** The completed upload id, available during `success` and `finished`. */
   recordingId: string | null;
   /** Failure detail, set when `status === 'error'`. */
   error: string | undefined;
+  /**
+   * Why the module errored: `connection` (transport failure — the UI shows
+   * the connection-error copy; raw detail stays in `error` for diagnostics)
+   * or `technical` (everything else). Set when `status === 'error'`.
+   */
+  errorKind: VideoSelfieErrorKind | undefined;
 };
 /**
  * Creates a manager for a multi-step, camera-switching Video Selfie recording.
@@ -185,6 +139,7 @@ declare function createVideoSelfieRecordingManager(options?: CreateVideoSelfieRe
   subscribe(listener: (state: VideoSelfieRecordingState) => void): () => void;
   /** Acquire the first camera, open the upload, and begin recording. */
   start(): void;
+  retry(): void;
   /**
    * Advance to the next step. Switches the camera when the next step's
    * facing mode differs; finalizes the upload on the last step.
@@ -328,10 +283,9 @@ declare function createConsentRecorder(): ConsentRecorder;
  * 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.
+ * **Completion contract:** the L2 `incode-video-selfie` web component calls
+ * `flowManager.completeModule()` once the recording manager reaches `finished`.
+ * Recoverable errors stay inside the module until the user retries.
  *
  * **Abort / unmount:** if the user closes the module or the web component
  * unmounts before completion, the orchestrated flow manager's existing close /
@@ -342,7 +296,7 @@ declare function createConsentRecorder(): ConsentRecorder;
  * 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: xstate1002.StateMachine<xstate1002.MachineContext, xstate1002.AnyEventObject, {}, never, never, never, never, "running", string, xstate1002.NonReducibleUnknown, xstate1002.NonReducibleUnknown, xstate1002.EventObject, xstate1002.MetaObject, {
+declare const videoSelfieFlowModuleMachine: StateMachine<MachineContext, AnyEventObject, {}, never, never, never, never, "running", string, NonReducibleUnknown, NonReducibleUnknown, EventObject, MetaObject, {
   readonly id: "videoSelfieFlowModule";
   readonly initial: "running";
   readonly states: {