@incodetech/core 2.0.0-alpha.1

package/src/selfie/selfieManager.ts

@@ -0,0 +1,301 @@
+import {
+  type CreateApiOptions,
+  createManager,
+  type ManagerSnapshot,
+} from '@incodetech/infra';
+import {
+  type CreateSelfieActorOptions,
+  createSelfieActor,
+} from './selfieActor';
+import type { CameraStream } from './selfieServices';
+import type { SelfieMachine } from './selfieStateMachine';
+import type { DetectionStatus, PermissionStatus } from './types';
+
+/** Internal snapshot type for the selfie state machine */
+type SelfieSnapshot = ManagerSnapshot<SelfieMachine>;
+
+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;
+};
+
+/** Selfie capture completed successfully */
+type SelfieFinishedState = {
+  status: 'finished';
+};
+
+/** 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 */
+export type SelfieState =
+  | SelfieIdleState
+  | SelfieLoadingState
+  | SelfieTutorialState
+  | SelfiePermissionsState
+  | SelfieCaptureState
+  | SelfieFinishedState
+  | SelfieClosedState
+  | SelfieErrorState;
+
+function getPermissionStatus(
+  snapshot: SelfieSnapshot,
+): PermissionStatus | undefined {
+  if (!snapshot.matches('permissions')) {
+    return undefined;
+  }
+
+  if (snapshot.matches({ permissions: 'idle' })) {
+    return 'idle';
+  }
+
+  if (snapshot.matches({ permissions: 'learnMore' })) {
+    return 'learnMore';
+  }
+
+  if (snapshot.matches({ permissions: 'requesting' })) {
+    return 'requesting';
+  }
+
+  if (snapshot.matches({ permissions: 'denied' })) {
+    return 'denied';
+  }
+
+  return undefined;
+}
+
+function getCaptureStatus(snapshot: SelfieSnapshot): CaptureStatus | undefined {
+  if (snapshot.matches({ capture: 'initializing' })) return 'initializing';
+  if (snapshot.matches({ capture: 'detecting' })) return 'detecting';
+  if (snapshot.matches({ capture: 'capturing' })) return 'capturing';
+  if (snapshot.matches({ capture: 'capturingManual' })) return 'capturing';
+  if (snapshot.matches({ capture: 'uploading' })) return 'uploading';
+  if (snapshot.matches({ capture: 'uploadError' })) return 'uploadError';
+  if (snapshot.matches({ capture: 'success' })) return 'success';
+  return undefined;
+}
+
+function mapState(snapshot: SelfieSnapshot): SelfieState {
+  const { context } = snapshot;
+
+  if (snapshot.matches('idle')) {
+    return { status: 'idle' };
+  }
+
+  if (snapshot.matches('loading')) {
+    return { status: 'loading' };
+  }
+
+  if (snapshot.matches('tutorial')) {
+    return {
+      status: 'tutorial',
+    };
+  }
+
+  if (snapshot.matches('closed')) {
+    return { status: 'closed' };
+  }
+
+  if (snapshot.matches('permissions')) {
+    const permissionStatus = getPermissionStatus(snapshot);
+    if (permissionStatus === undefined) {
+      return { status: 'permissions', permissionStatus: 'idle' };
+    }
+    return {
+      status: 'permissions',
+      permissionStatus,
+    };
+  }
+
+  if (snapshot.matches('capture')) {
+    const captureStatus = getCaptureStatus(snapshot);
+    return {
+      status: 'capture',
+      captureStatus: captureStatus ?? 'initializing',
+      stream: context.stream,
+      detectionStatus: context.detectionStatus,
+      debugFrame: context.debugFrame,
+      attemptsRemaining: context.attemptsRemaining,
+      uploadError: context.uploadError,
+    };
+  }
+
+  if (snapshot.matches('finished')) {
+    return { status: 'finished' };
+  }
+
+  if (snapshot.matches('error')) {
+    return {
+      status: 'error',
+      error: context.error ?? 'Unknown error',
+    };
+  }
+
+  return { status: 'idle' };
+}
+
+function createApi({ actor }: CreateApiOptions<SelfieMachine>) {
+  return {
+    /**
+     * 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() {
+      actor.send({ type: 'LOAD' });
+    },
+
+    /**
+     * Advances to the next step.
+     * From `tutorial` → permissions or capture (based on permission status).
+     * From `capture` → finished.
+     */
+    nextStep() {
+      actor.send({ type: 'NEXT_STEP' });
+    },
+
+    /**
+     * Requests camera permission via getUserMedia.
+     * Only effective when in `permissions.idle` or `permissions.learnMore` state.
+     */
+    requestPermission() {
+      actor.send({ type: 'REQUEST_PERMISSION' });
+    },
+
+    /**
+     * Navigates to the "learn more" permission screen.
+     * Only effective when in `permissions.idle` state.
+     */
+    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() {
+      actor.send({ type: 'BACK' });
+    },
+
+    /**
+     * Closes the selfie flow and transitions to `closed` state.
+     * Can be called from any state.
+     */
+    close() {
+      actor.send({ type: 'QUIT' });
+    },
+
+    /**
+     * Resets the selfie manager to its initial `idle` state.
+     * Can be called from `finished` or `error` states.
+     */
+    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() {
+      actor.send({ type: 'RETRY_CAPTURE' });
+    },
+
+    /**
+     * Captures a selfie in manual capture mode.
+     * Only effective when in `capture.detecting` state and `detectionStatus === 'manualCapture'`.
+     */
+    capture() {
+      actor.send({ type: 'MANUAL_CAPTURE' });
+    },
+  };
+}
+
+/**
+ * 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();
+ * ```
+ */
+export function createSelfieManager(options: CreateSelfieActorOptions) {
+  const actor = createSelfieActor(options);
+  return createManager({ actor, mapState, createApi });
+}
+
+export type SelfieManager = ReturnType<typeof createSelfieManager>;

package/src/selfie/selfieServices.ts

@@ -0,0 +1,362 @@
+import {
+  type CameraStream,
+  type FaceCoordinates,
+  FaceDetectionProvider,
+  type IncodeCanvas,
+  type IRecordingCapability,
+  OpenViduRecordingProvider,
+  type RecordingConnectionEvents,
+  requestCameraAccess,
+  type StreamCanvasCapture,
+  StreamCanvasProcessingSession,
+  stopCameraStream,
+  WasmUtilProvider,
+} from '@incodetech/infra';
+import { addEvent } from '../events/addEvent';
+import {
+  createRecordingSession,
+  startRecording,
+  stopRecording as stopRecordingApi,
+} from '../recordings/recordingsRepository';
+import { streamingEvents } from '../recordings/streamingEvents';
+import type { DetectionStatus, RecordingSession, SelfieConfig } from './types';
+
+export { type UploadSelfieParams, uploadSelfie } from './selfieUploadService';
+
+export const CAMERA_CONSTRAINTS: MediaStreamConstraints = {
+  video: {
+    facingMode: 'user',
+    height: { ideal: 480 },
+    width: { ideal: 640 },
+  },
+  audio: false,
+};
+export type { CameraStream } from '@incodetech/infra';
+
+export function stopStream(stream: CameraStream): void {
+  stopCameraStream(stream);
+}
+
+export type SelfieCameraInitResult = {
+  stream: CameraStream;
+  provider: FaceDetectionProvider;
+};
+
+export async function initializeCamera(
+  config: SelfieConfig,
+): Promise<SelfieCameraInitResult> {
+  const provider = new FaceDetectionProvider();
+  await provider.initialize({
+    autocaptureInterval: config.autoCaptureTimeout * 1000,
+  });
+
+  provider.setChecksEnabled({
+    lenses: config.validateLenses,
+    mask: config.validateFaceMask,
+    closedEyes: config.validateClosedEyes,
+    headWear: config.validateHeadCover,
+    occlusion: false,
+  });
+
+  const stream = await requestCameraAccess({
+    video: CAMERA_CONSTRAINTS.video,
+  });
+
+  return { stream, provider };
+}
+
+export type EncryptSelfieImageParams = {
+  canvas: IncodeCanvas;
+};
+
+/**
+ * Encrypts the provided selfie image using WASM.
+ */
+export async function encryptSelfieImage({
+  canvas,
+}: EncryptSelfieImageParams): Promise<string> {
+  const base64Image = canvas.getBase64Image();
+  if (!base64Image) {
+    throw new Error('Canvas image is empty or null');
+  }
+  const wasmProvider = await WasmUtilProvider.getInstance();
+  return wasmProvider.encryptImage(base64Image);
+}
+
+export type DetectionCallback = (status: DetectionStatus) => void;
+
+export type StartDetectionParams = {
+  config: SelfieConfig;
+  capturer: StreamCanvasCapture;
+  onUpdate: DetectionCallback;
+  onSuccess: (canvas: IncodeCanvas, faceCoordinates?: FaceCoordinates) => void;
+  onFrame?: (frame: ImageData) => void;
+  provider: FaceDetectionProvider;
+};
+
+/**
+ * Starts WASM-backed face detection and streams detection statuses via callbacks.
+ * Requires `setup({ wasm: ... })` to have been called before.
+ */
+export type StartDetectionResult = {
+  cleanup: () => void;
+  reset: () => void;
+};
+
+export function startDetection(
+  params: StartDetectionParams,
+): StartDetectionResult {
+  let lastStatus: DetectionStatus | undefined;
+  let session: StreamCanvasProcessingSession | undefined;
+  const { provider } = params;
+
+  const setStatus = (status: DetectionStatus): void => {
+    if (session?.isDisposed() === true) {
+      return;
+    }
+    if (lastStatus === status) {
+      return;
+    }
+    lastStatus = status;
+    params.onUpdate(status);
+  };
+
+  const stopDetectionLoop = (): void => {
+    session?.dispose();
+  };
+
+  const reset = (): void => {
+    provider.reset();
+  };
+
+  const cleanup = (): void => {
+    stopDetectionLoop();
+  };
+
+  void (async () => {
+    try {
+      provider.setCallbacks({
+        onFarAway: () => setStatus('tooFar'),
+        onTooClose: () => setStatus('tooClose'),
+        onTooManyFaces: () => setStatus('tooManyFaces'),
+        onNoFace: () => setStatus('idle'),
+        onCenterFace: () => setStatus('centerFace'),
+        onGetReady: () => setStatus('getReady'),
+        onGetReadyFinished: () => setStatus('getReadyFinished'),
+        onDark: () => {
+          if (params.config.validateBrightness) {
+            setStatus('dark');
+          }
+        },
+        onBlur: () => setStatus('blur'),
+        onFaceAngle: () => setStatus('faceAngle'),
+        onLenses: () => {
+          if (params.config.validateLenses) {
+            setStatus('lenses');
+          }
+        },
+        onMask: () => {
+          if (params.config.validateFaceMask) {
+            setStatus('faceMask');
+          }
+        },
+        onEyesClosed: () => {
+          if (params.config.validateClosedEyes) {
+            setStatus('eyesClosed');
+          }
+        },
+        onHeadWear: () => {
+          if (params.config.validateHeadCover) {
+            setStatus('headWear');
+          }
+        },
+        onFaceOccluded: () => {},
+        onSwitchToManualCapture: () => {
+          setStatus('manualCapture');
+          stopDetectionLoop();
+        },
+        onCapture: (canvas: IncodeCanvas, faceCoordinates: FaceCoordinates) => {
+          setStatus('success');
+          params.onSuccess(canvas, faceCoordinates);
+          cleanup();
+        },
+      });
+      setStatus('detecting');
+      session = new StreamCanvasProcessingSession({
+        capturer: params.capturer,
+        provider,
+        onFrame: params.onFrame,
+      });
+    } catch {
+      setStatus('error');
+      cleanup();
+    }
+  })();
+
+  return { cleanup, reset };
+}
+
+function buildResolutionFromStream(stream: MediaStream): string | undefined {
+  const track = stream.getVideoTracks()[0];
+  if (!track) {
+    return undefined;
+  }
+  const settings = track.getSettings();
+  const width = settings.width;
+  const height = settings.height;
+  if (typeof width === 'number' && typeof height === 'number') {
+    return `${width}x${height}`;
+  }
+  return undefined;
+}
+
+export type StartRecordingParams = {
+  config: SelfieConfig;
+  stream: CameraStream;
+  existing?: RecordingSession;
+};
+
+export async function startRecordingSession(
+  params: StartRecordingParams,
+): Promise<RecordingSession | undefined> {
+  if (params.config.enableFaceRecording !== true) {
+    return undefined;
+  }
+  if (params.existing) {
+    return params.existing;
+  }
+
+  const provider: IRecordingCapability =
+    params.config.recording?.capability ?? new OpenViduRecordingProvider();
+
+  const clonedStream = params.stream.clone();
+  const hasAudio = clonedStream.getAudioTracks().length > 0;
+  const resolution = buildResolutionFromStream(clonedStream);
+
+  const session = await createRecordingSession('selfie');
+
+  const events: RecordingConnectionEvents = {
+    onSessionConnected: (sessionId) => {
+      addEvent({
+        code: streamingEvents.strSessionDidConnect,
+        payload: {
+          message: 'Recording session connected',
+          sessionId,
+        },
+      });
+    },
+    onSessionDisconnected: (sessionId) => {
+      addEvent({
+        code: streamingEvents.strSessionDidDisconnect,
+        payload: {
+          message: 'Recording session disconnected',
+          sessionId,
+        },
+      });
+    },
+    onSessionException: (event) => {
+      addEvent({
+        code: streamingEvents.strSessionDidFailWithError,
+        payload: {
+          message: 'Recording session failed due to an error',
+          eventName: event.name,
+          type: 'OpenViduException',
+          errorMessage: event.message,
+          sessionId: event.sessionId,
+        },
+      });
+    },
+    onPublisherCreated: (p) => {
+      addEvent({
+        code: streamingEvents.strStreamPublisherCreated,
+        payload: {
+          message: 'Recording publisher created',
+          sessionId: p.sessionId,
+          streamId: p.streamId,
+        },
+      });
+    },
+    onPublisherError: (p) => {
+      addEvent({
+        code: streamingEvents.strStreamPublisherDidFailWithError,
+        payload: {
+          message: 'Recording publisher failed due to an error',
+          sessionId: p.sessionId,
+          streamId: p.streamId,
+          error: {
+            message: p.message ?? 'Unknown error',
+          },
+        },
+      });
+    },
+  };
+
+  const connection = await provider.connect({
+    sessionToken: session.token,
+    stream: clonedStream,
+    events,
+  });
+
+  await startRecording({
+    videoRecordingId: session.videoRecordingId,
+    type: 'selfie',
+    resolution,
+    hasAudio,
+  });
+
+  addEvent({
+    code: streamingEvents.strStreamVideoCaptureStart,
+    payload: {
+      message: 'Recording capture started',
+      resolution,
+      videoRecordingId: session.videoRecordingId,
+      sessionId: session.sessionId,
+      streamId: connection.publisher.getStreamId(),
+    },
+  });
+
+  return {
+    token: session.token,
+    sessionId: session.sessionId,
+    videoRecordingId: session.videoRecordingId,
+    connection,
+    resolution,
+    hasAudio,
+  };
+}
+
+export function stopRecording(session: RecordingSession): void {
+  void (async () => {
+    try {
+      addEvent({
+        code: streamingEvents.strStreamVideoCaptureStop,
+        payload: {
+          message: 'Recording capture stopped',
+          videoRecordingId: session.videoRecordingId,
+          sessionId: session.sessionId,
+          streamId: session.connection.publisher.getStreamId(),
+        },
+      });
+
+      await stopRecordingApi(session.videoRecordingId);
+
+      addEvent({
+        code: streamingEvents.strStreamPublisherDestroyed,
+        payload: {
+          message: 'Recording publisher destroyed',
+          sessionId: session.sessionId,
+          streamId: session.connection.publisher.getStreamId(),
+        },
+      });
+    } finally {
+      await session.connection.disconnect();
+      addEvent({
+        code: streamingEvents.strSessionDidDisconnect,
+        payload: {
+          message: 'Recording session disconnected',
+          sessionId: session.sessionId,
+        },
+      });
+    }
+  })();
+}