@incodetech/core 2.0.0-alpha.1

package/src/selfie/selfieStateMachine.ts

@@ -0,0 +1,804 @@
+import {
+  type AnyStateMachine,
+  assign,
+  type FaceCoordinates,
+  type FaceDetectionProvider,
+  fromCallback,
+  fromPromise,
+  type IncodeCanvas,
+  type StateMachine,
+  StreamCanvasCapture,
+  setup,
+} from '@incodetech/infra';
+import { addEvent } from '../events/addEvent';
+import {
+  checkPermission,
+  requestPermission,
+} from '../permissions/permissionServices';
+import {
+  getFaceErrorCodeFromUnknown,
+  validateUploadResponse,
+} from './selfieErrorUtils';
+import {
+  type CameraStream,
+  encryptSelfieImage,
+  initializeCamera,
+  startDetection,
+  startRecordingSession,
+  stopRecording,
+  stopStream,
+  uploadSelfie,
+} from './selfieServices';
+import type {
+  DetectionStatus,
+  FaceErrorCode,
+  PermissionResult,
+  RecordingSession,
+  SelfieConfig,
+  SendFaceImageResponse,
+} from './types';
+import { FACE_ERROR_CODES } from './types';
+
+export type SelfieContext = {
+  config: SelfieConfig;
+  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;
+  recordingSession: RecordingSession | undefined;
+  attemptsRemaining: number;
+  uploadError: FaceErrorCode | undefined;
+  permissionResult: PermissionResult | 'refresh' | undefined;
+  resetDetection: (() => void) | undefined;
+};
+
+export 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' };
+
+export type SelfieInput = {
+  config: SelfieConfig;
+};
+
+const _selfieMachine = setup({
+  types: {
+    context: {} as SelfieContext,
+    events: {} as SelfieEvent,
+    input: {} as SelfieInput,
+  },
+  actors: {
+    checkPermission: fromPromise<PermissionResult, void>(async () => {
+      return checkPermission();
+    }),
+    requestPermission: fromPromise<PermissionResult, void>(async () => {
+      return requestPermission();
+    }),
+    initializeCamera: fromPromise<
+      { stream: CameraStream; provider: FaceDetectionProvider },
+      SelfieConfig
+    >(async ({ input }) => {
+      return initializeCamera(input);
+    }),
+    runDetection: fromCallback<
+      SelfieEvent,
+      {
+        frameCapturer: StreamCanvasCapture | undefined;
+        provider: FaceDetectionProvider | undefined;
+        config: SelfieConfig;
+      }
+    >(({ input, sendBack }) => {
+      if (!input.frameCapturer || !input.provider) {
+        sendBack({ type: 'DETECTION_UPDATE', status: 'error' });
+        return () => {};
+      }
+      const { cleanup, reset } = startDetection({
+        config: input.config,
+        capturer: input.frameCapturer,
+        onUpdate: (status: DetectionStatus) =>
+          sendBack({ type: 'DETECTION_UPDATE', status }),
+        onFrame: (frame: ImageData) =>
+          sendBack({ type: 'DETECTION_FRAME', frame }),
+        onSuccess: (canvas: IncodeCanvas, faceCoordinates?: FaceCoordinates) =>
+          sendBack({ type: 'DETECTION_SUCCESS', canvas, faceCoordinates }),
+        provider: input.provider,
+      });
+      sendBack({ type: 'DETECTION_RESET_READY', reset });
+      return cleanup;
+    }),
+    uploadSelfie: fromPromise<
+      SendFaceImageResponse,
+      { canvas: IncodeCanvas; faceCoordinates?: FaceCoordinates }
+    >(async ({ input, signal }) => {
+      const encryptedBase64Image = await encryptSelfieImage({
+        canvas: input.canvas,
+      });
+      return uploadSelfie({
+        encryptedBase64Image,
+        faceCoordinates: input.faceCoordinates,
+        signal,
+      });
+    }),
+    startRecording: fromPromise<
+      RecordingSession | undefined,
+      {
+        config: SelfieConfig;
+        stream: CameraStream | undefined;
+        existing?: RecordingSession;
+      }
+    >(async ({ input }) => {
+      if (!input.stream) {
+        return undefined;
+      }
+      return startRecordingSession({
+        config: input.config,
+        stream: input.stream,
+        existing: input.existing,
+      });
+    }),
+  },
+  actions: {
+    stopMediaStream: assign(({ context }) => {
+      context.frameCapturer?.dispose();
+      if (context.stream) {
+        stopStream(context.stream);
+      }
+      void context.provider?.dispose();
+      return {
+        stream: undefined,
+        provider: undefined,
+        frameCapturer: undefined,
+      };
+    }),
+    setStreamAndCapturer: assign({
+      stream: ({ event }) => {
+        if ('output' in event) {
+          return (event.output as { stream: CameraStream }).stream;
+        }
+        return undefined;
+      },
+      provider: ({ event }) => {
+        if ('output' in event) {
+          return (event.output as { provider: FaceDetectionProvider }).provider;
+        }
+        return undefined;
+      },
+      frameCapturer: ({ event }) => {
+        if ('output' in event) {
+          return new StreamCanvasCapture(
+            (event.output as { stream: CameraStream }).stream,
+          );
+        }
+        return undefined;
+      },
+    }),
+    trackTutorialSelfie: () => {
+      addEvent({
+        code: 'tutorialSelfie',
+        payload: { tutorialSelfie: true },
+      });
+    },
+    trackContinue: () => {
+      addEvent({
+        code: 'continue',
+      });
+    },
+    resetContext: assign(({ context }) => ({
+      stream: undefined,
+      provider: undefined,
+      frameCapturer: undefined,
+      error: undefined,
+      detectionStatus: 'idle' as DetectionStatus,
+      debugFrame: undefined,
+      capturedImage: undefined,
+      faceCoordinates: undefined,
+      uploadResponse: undefined,
+      recordingSession: undefined,
+      attemptsRemaining: context.config.captureAttempts,
+      uploadError: undefined,
+      permissionResult: undefined,
+      resetDetection: undefined,
+    })),
+    resetDetection: ({ context }) => {
+      context.resetDetection?.();
+    },
+    captureImage: assign({
+      capturedImage: ({ context }) => {
+        if (context.capturedImage) {
+          return context.capturedImage;
+        }
+        return context.frameCapturer?.getLatestCanvas() ?? undefined;
+      },
+    }),
+    captureLatestFrame: assign({
+      capturedImage: ({ context }) => {
+        return context.frameCapturer?.getLatestCanvas() ?? undefined;
+      },
+    }),
+    clearUploadFailure: assign({
+      uploadError: () => undefined,
+      detectionStatus: () => 'idle' as DetectionStatus,
+      capturedImage: () => undefined,
+    }),
+    decrementAttemptsRemaining: assign(({ context }) => ({
+      attemptsRemaining: context.attemptsRemaining - 1,
+    })),
+    setUploadErrorFromUploadValidation: assign({
+      uploadError: ({ context }) =>
+        validateUploadResponse({
+          config: context.config,
+          response: context.uploadResponse,
+        }) ?? FACE_ERROR_CODES.SERVER,
+    }),
+    stopMediaRecording: ({ context }) => {
+      if (context.recordingSession) {
+        stopRecording(context.recordingSession);
+      }
+    },
+    clearRecordingSession: assign({
+      recordingSession: () => undefined,
+    }),
+  },
+  guards: {
+    hasShowTutorial: ({ context }) => context.config.showTutorial,
+    isPermissionGranted: ({ event }) => {
+      if ('output' in event) {
+        return event.output === 'granted';
+      }
+      return false;
+    },
+    isPermissionDeniedError: ({ event }) => {
+      if ('error' in event) {
+        const error = event.error as Error;
+        return (
+          error?.name === 'NotAllowedError' ||
+          error?.name === 'PermissionDeniedError'
+        );
+      }
+      return false;
+    },
+    hasStream: ({ context }) => context.stream !== undefined,
+    hasAttemptsRemaining: ({ context }) => context.attemptsRemaining > 0,
+    hasCapturedImage: ({ context }) => context.capturedImage !== undefined,
+    hasUploadValidationError: ({ context }) =>
+      validateUploadResponse({
+        config: context.config,
+        response: context.uploadResponse,
+      }) !== undefined,
+  },
+}).createMachine({
+  id: 'selfie',
+  initial: 'idle',
+  context: ({ input }) => ({
+    config: input.config,
+    stream: undefined,
+    provider: undefined,
+    frameCapturer: undefined,
+    error: undefined,
+    detectionStatus: 'idle',
+    debugFrame: undefined,
+    capturedImage: undefined,
+    faceCoordinates: undefined,
+    uploadResponse: undefined,
+    recordingSession: undefined,
+    attemptsRemaining: input.config.captureAttempts,
+    uploadError: undefined,
+    permissionResult: undefined,
+    resetDetection: undefined,
+  }),
+  on: {
+    QUIT: {
+      target: '#selfie.closed',
+    },
+  },
+  states: {
+    idle: {
+      on: {
+        LOAD: [
+          {
+            target: 'tutorial',
+            guard: 'hasShowTutorial',
+          },
+          {
+            target: 'loading',
+          },
+        ],
+      },
+    },
+
+    loading: {
+      invoke: {
+        id: 'checkPermissionLoading',
+        src: 'checkPermission',
+        onDone: [
+          {
+            target: 'capture',
+            guard: 'isPermissionGranted',
+            actions: assign({
+              permissionResult: ({ event }) => event.output,
+            }),
+          },
+          {
+            target: 'permissions',
+            actions: assign({
+              permissionResult: ({ event }) => event.output,
+            }),
+          },
+        ],
+      },
+    },
+
+    tutorial: {
+      initial: 'checkingPermission',
+      entry: 'trackTutorialSelfie',
+      states: {
+        checkingPermission: {
+          invoke: {
+            id: 'checkPermissionTutorial',
+            src: 'checkPermission',
+            onDone: [
+              {
+                target: 'initializingCamera',
+                guard: 'isPermissionGranted',
+                actions: assign({
+                  permissionResult: ({ event }) => event.output,
+                }),
+              },
+              {
+                target: 'ready',
+                actions: assign({
+                  permissionResult: ({ event }) => event.output,
+                }),
+              },
+            ],
+          },
+        },
+        initializingCamera: {
+          initial: 'booting',
+          invoke: {
+            id: 'tutorialInitCamera',
+            src: 'initializeCamera',
+            input: ({ context }) => context.config,
+            onDone: {
+              actions: 'setStreamAndCapturer',
+            },
+            onError: [
+              {
+                target: 'ready',
+                guard: 'isPermissionDeniedError',
+                actions: assign({
+                  permissionResult: () => 'denied',
+                }),
+              },
+              {
+                target: 'ready',
+                actions: assign({
+                  error: ({ event }) => String(event.error),
+                }),
+              },
+            ],
+          },
+          states: {
+            booting: {
+              always: [
+                {
+                  target: '#tutorialCameraReady',
+                  guard: 'hasStream',
+                },
+              ],
+              on: {
+                NEXT_STEP: {
+                  target: 'waitingForStream',
+                  actions: 'trackContinue',
+                },
+              },
+            },
+            waitingForStream: {
+              always: [
+                {
+                  target: '#selfie.capture',
+                  guard: 'hasStream',
+                },
+              ],
+            },
+          },
+        },
+        cameraReady: {
+          id: 'tutorialCameraReady',
+          on: {
+            NEXT_STEP: {
+              target: '#selfie.capture',
+              actions: 'trackContinue',
+            },
+          },
+        },
+        ready: {
+          on: {
+            NEXT_STEP: {
+              target: 'waitingForPermission',
+              actions: 'trackContinue',
+            },
+          },
+        },
+        waitingForPermission: {
+          invoke: {
+            id: 'checkPermissionWaiting',
+            src: 'checkPermission',
+            onDone: [
+              {
+                target: '#selfie.capture',
+                guard: 'isPermissionGranted',
+                actions: assign({
+                  permissionResult: ({ event }) => event.output,
+                }),
+              },
+              {
+                target: '#selfie.permissions',
+                actions: assign({
+                  permissionResult: ({ event }) => event.output,
+                }),
+              },
+            ],
+          },
+        },
+      },
+    },
+
+    permissions: {
+      initial: 'idle',
+      states: {
+        idle: {
+          invoke: {
+            id: 'checkPermissionIdle',
+            src: 'checkPermission',
+            onDone: [
+              {
+                target: '#selfie.capture',
+                guard: 'isPermissionGranted',
+                actions: assign({
+                  permissionResult: ({ event }) => event.output,
+                }),
+              },
+              {
+                target: 'denied',
+                guard: ({ event }) => event.output === 'denied',
+                actions: assign({
+                  permissionResult: ({ event }) => event.output,
+                }),
+              },
+            ],
+          },
+          on: {
+            REQUEST_PERMISSION: 'requesting',
+            GO_TO_LEARN_MORE: 'learnMore',
+          },
+        },
+        learnMore: {
+          on: {
+            BACK: 'idle',
+            REQUEST_PERMISSION: 'requesting',
+          },
+        },
+        requesting: {
+          invoke: {
+            id: 'requestPermission',
+            src: 'requestPermission',
+            onDone: [
+              {
+                target: '#selfie.capture',
+                guard: 'isPermissionGranted',
+                actions: assign({
+                  permissionResult: ({ event }) => event.output,
+                }),
+              },
+              {
+                target: 'denied',
+                guard: ({ event }) => event.output === 'denied',
+                actions: assign({
+                  permissionResult: ({ event }) => event.output,
+                }),
+              },
+              {
+                target: 'idle',
+                actions: assign({
+                  permissionResult: ({ event }) => event.output,
+                }),
+              },
+            ],
+            onError: {
+              target: 'denied',
+            },
+          },
+        },
+        denied: {
+          entry: assign({
+            permissionResult: () => 'refresh',
+          }),
+        },
+      },
+    },
+    capture: {
+      initial: 'checkingStream',
+      exit: ['stopMediaRecording', 'clearRecordingSession', 'stopMediaStream'],
+      states: {
+        checkingStream: {
+          always: [
+            {
+              target: 'detecting',
+              guard: 'hasStream',
+            },
+            { target: 'initializing' },
+          ],
+        },
+        initializing: {
+          invoke: {
+            id: 'initializeCamera',
+            src: 'initializeCamera',
+            input: ({ context }) => context.config,
+            onDone: {
+              target: 'detecting',
+              actions: 'setStreamAndCapturer',
+            },
+            onError: [
+              {
+                target: '#selfie.permissions',
+                guard: 'isPermissionDeniedError',
+                actions: assign({
+                  permissionResult: () => 'denied',
+                }),
+              },
+              {
+                target: '#selfie.error',
+                actions: assign({
+                  error: ({ event }) => String(event.error),
+                }),
+              },
+            ],
+          },
+        },
+        detecting: {
+          entry: [
+            assign({
+              detectionStatus: () => 'detecting',
+            }),
+          ],
+          invoke: [
+            {
+              id: 'startRecording',
+              src: 'startRecording',
+              input: ({ context }) => ({
+                config: context.config,
+                stream: context.stream,
+                existing: context.recordingSession,
+              }),
+              onDone: {
+                actions: assign({
+                  recordingSession: ({ context, event }) => {
+                    const output = (event as { output?: RecordingSession })
+                      .output;
+                    return output ?? context.recordingSession;
+                  },
+                }),
+              },
+              onError: {
+                actions: () => undefined,
+              },
+            },
+            {
+              id: 'runDetection',
+              src: 'runDetection',
+              input: ({ context }) => ({
+                frameCapturer: context.frameCapturer,
+                provider: context.provider,
+                config: context.config,
+              }),
+            },
+          ],
+          on: {
+            DETECTION_UPDATE: {
+              actions: assign({
+                detectionStatus: ({ event }) => event.status,
+              }),
+            },
+            DETECTION_FRAME: {
+              actions: assign({
+                debugFrame: ({ event }) => event.frame,
+              }),
+            },
+            DETECTION_RESET_READY: {
+              actions: assign({
+                resetDetection: ({ event }) => event.reset,
+              }),
+            },
+            DETECTION_SUCCESS: {
+              target: 'capturing',
+              actions: assign({
+                capturedImage: ({ event }) => event.canvas,
+                faceCoordinates: ({ event }) => event.faceCoordinates,
+              }),
+            },
+            MANUAL_CAPTURE: {
+              target: 'capturingManual',
+            },
+          },
+        },
+        capturing: {
+          entry: ['captureImage'],
+          always: [
+            {
+              target: 'uploading',
+              guard: 'hasCapturedImage',
+            },
+            {
+              target: 'uploadError',
+              actions: assign(({ context }) => ({
+                uploadError: FACE_ERROR_CODES.SERVER,
+                attemptsRemaining: context.attemptsRemaining - 1,
+              })),
+            },
+          ],
+        },
+        capturingManual: {
+          entry: ['captureLatestFrame'],
+          always: [
+            {
+              target: 'uploading',
+              guard: 'hasCapturedImage',
+            },
+            {
+              target: 'uploadError',
+              actions: assign(({ context }) => ({
+                uploadError: FACE_ERROR_CODES.SERVER,
+                attemptsRemaining: context.attemptsRemaining - 1,
+              })),
+            },
+          ],
+        },
+        uploading: {
+          invoke: {
+            id: 'uploadSelfie',
+            src: 'uploadSelfie',
+            input: ({ context }) => {
+              const canvas = context.capturedImage;
+              if (!canvas) {
+                throw new Error(FACE_ERROR_CODES.SERVER);
+              }
+              return {
+                canvas,
+                faceCoordinates: context.faceCoordinates,
+              };
+            },
+            onDone: {
+              target: 'validatingUpload',
+              actions: assign({
+                uploadResponse: ({ event }) => event.output,
+              }),
+            },
+            onError: {
+              target: 'uploadError',
+              actions: assign(({ context, event }) => ({
+                uploadError:
+                  getFaceErrorCodeFromUnknown(event.error) ??
+                  FACE_ERROR_CODES.SERVER,
+                attemptsRemaining: context.attemptsRemaining - 1,
+              })),
+            },
+          },
+        },
+        validatingUpload: {
+          always: [
+            {
+              target: 'uploadError',
+              guard: 'hasUploadValidationError',
+              actions: [
+                'setUploadErrorFromUploadValidation',
+                'decrementAttemptsRemaining',
+              ],
+            },
+            { target: 'success' },
+          ],
+        },
+        uploadError: {
+          on: {
+            RETRY_CAPTURE: {
+              target: 'detecting',
+              guard: 'hasAttemptsRemaining',
+              actions: ['resetDetection', 'clearUploadFailure'],
+            },
+          },
+        },
+        success: {
+          entry: 'stopMediaRecording',
+          after: {
+            3000: {
+              target: '#selfie.finished',
+            },
+          },
+        },
+      },
+    },
+
+    finished: {
+      entry: 'stopMediaStream',
+      on: {
+        RESET: {
+          target: 'idle',
+          actions: 'resetContext',
+        },
+      },
+    },
+
+    closed: {
+      entry: 'stopMediaStream',
+      type: 'final',
+    },
+    error: {
+      entry: 'stopMediaStream',
+      on: {
+        RESET: {
+          target: 'idle',
+          actions: 'resetContext',
+        },
+      },
+    },
+  },
+});
+
+/**
+ * The selfie capture state machine.
+ *
+ * Note: Uses AnyStateMachine type for declaration file portability.
+ * Type safety is ensured via the machine configuration.
+ */
+export const selfieMachine: AnyStateMachine = _selfieMachine;
+
+/**
+ * Type representing the selfie machine.
+ * For advanced use cases requiring specific machine types.
+ */
+export type SelfieMachine = StateMachine<
+  SelfieContext,
+  SelfieEvent,
+  // biome-ignore lint/suspicious/noExplicitAny: Required for declaration portability
+  any,
+  // biome-ignore lint/suspicious/noExplicitAny: Required for declaration portability
+  any,
+  // biome-ignore lint/suspicious/noExplicitAny: Required for declaration portability
+  any,
+  // biome-ignore lint/suspicious/noExplicitAny: Required for declaration portability
+  any,
+  // biome-ignore lint/suspicious/noExplicitAny: Required for declaration portability
+  any,
+  // biome-ignore lint/suspicious/noExplicitAny: Required for declaration portability
+  any,
+  // biome-ignore lint/suspicious/noExplicitAny: Required for declaration portability
+  any,
+  SelfieInput,
+  // biome-ignore lint/suspicious/noExplicitAny: Required for declaration portability
+  any,
+  // biome-ignore lint/suspicious/noExplicitAny: Required for declaration portability
+  any,
+  // biome-ignore lint/suspicious/noExplicitAny: Required for declaration portability
+  any,
+  // biome-ignore lint/suspicious/noExplicitAny: Required for declaration portability
+  any
+>;