@incodetech/core 2.0.0-alpha.1

package/src/phone/phoneStateMachine.ts

@@ -0,0 +1,422 @@
+import { assign, fromCallback, fromPromise, setup } from '@incodetech/infra';
+import { addEvent } from '../events/addEvent';
+import {
+  addPhone,
+  addPhoneInstantVerify,
+  fetchPhone,
+  fetchStartInfo,
+  sendOtp,
+  verifyOtp,
+} from './phoneServices';
+import type { PhoneConfig, StartInfo } from './types';
+
+export type PhoneContext = {
+  config: PhoneConfig;
+  phone: string;
+  isValid: boolean;
+  phoneError: string | undefined;
+  countryCode: string;
+  phonePrefix: string;
+  prefilledPhone: string | undefined;
+  optInGranted: boolean;
+  startInfo: StartInfo | undefined;
+  error: string | undefined;
+  otpCode: string;
+  otpError: string | undefined;
+  attemptsRemaining: number;
+  resendTimer: number;
+  resendTimerActive: boolean;
+};
+
+export type PhoneEvent =
+  | { type: 'LOAD' }
+  | { type: 'PHONE_CHANGED'; phone: string; isValid: boolean }
+  | { type: 'OPT_IN_CHANGED'; granted: boolean }
+  | { type: 'SUBMIT' }
+  | { type: 'OTP_CHANGED'; code: string }
+  | { type: 'VERIFY_OTP' }
+  | { type: 'RESEND_OTP' }
+  | { type: 'BACK' }
+  | { type: 'RESET' };
+
+export type PhoneInput = {
+  config: PhoneConfig;
+};
+
+const RESEND_TIMER_SECONDS = 30;
+
+export const phoneMachine = setup({
+  types: {
+    context: {} as PhoneContext,
+    events: {} as PhoneEvent,
+    input: {} as PhoneInput,
+  },
+  actors: {
+    fetchPhone: fromPromise<{ phone: string }, void>(async ({ signal }) => {
+      return fetchPhone(signal);
+    }),
+    fetchStartInfo: fromPromise<StartInfo, void>(async ({ signal }) => {
+      return fetchStartInfo(signal);
+    }),
+    submitPhone: fromPromise<
+      { success: boolean },
+      { phone: string; optInGranted?: boolean; isInstantVerify: boolean }
+    >(async ({ input, signal }) => {
+      if (input.isInstantVerify) {
+        return addPhoneInstantVerify(
+          { phone: input.phone, optInGranted: input.optInGranted },
+          signal,
+        );
+      }
+      return addPhone(
+        { phone: input.phone, optInGranted: input.optInGranted },
+        signal,
+      );
+    }),
+    sendOtp: fromPromise<void, void>(async ({ signal }) => {
+      return sendOtp(signal);
+    }),
+    verifyOtp: fromPromise<{ success: boolean }, { code: string }>(
+      async ({ input, signal }) => {
+        return verifyOtp(input.code, signal);
+      },
+    ),
+    resendTimer: fromCallback(({ sendBack }) => {
+      let seconds = RESEND_TIMER_SECONDS;
+      const interval = setInterval(() => {
+        seconds -= 1;
+        sendBack({ type: 'TICK' });
+        if (seconds <= 0) {
+          clearInterval(interval);
+        }
+      }, 1000);
+      return () => clearInterval(interval);
+    }),
+  },
+  actions: {
+    setStartInfo: assign(({ event }) => {
+      const info = (event as unknown as { output: StartInfo }).output;
+      return {
+        startInfo: info,
+        countryCode: info.ipIsoCode,
+        phonePrefix: info.phonePrefix,
+      };
+    }),
+    setPrefilledPhone: assign(({ event }) => {
+      const phone = (event as unknown as { output: { phone: string } }).output
+        .phone;
+      return {
+        prefilledPhone: phone,
+        phone,
+      };
+    }),
+    setPhone: assign(({ event }) => {
+      const e = event as {
+        type: 'PHONE_CHANGED';
+        phone: string;
+        isValid: boolean;
+      };
+      return {
+        phone: e.phone,
+        isValid: e.isValid,
+        phoneError: e.isValid ? undefined : 'Invalid phone number',
+      };
+    }),
+    setPhoneError: assign(({ event }) => ({
+      phoneError: String((event as unknown as { error: unknown }).error),
+    })),
+    setOptInGranted: assign(({ event }) => ({
+      optInGranted: (event as { type: 'OPT_IN_CHANGED'; granted: boolean })
+        .granted,
+    })),
+    setError: assign(({ event }) => ({
+      error: String((event as unknown as { error: unknown }).error),
+    })),
+    clearError: assign({
+      error: () => undefined,
+    }),
+    clearPhoneError: assign({
+      phoneError: () => undefined,
+    }),
+    setOtpCode: assign(({ event }) => ({
+      otpCode: (event as { type: 'OTP_CHANGED'; code: string }).code,
+      otpError: undefined,
+    })),
+    setOtpError: assign(({ context, event }) => ({
+      otpError: String((event as unknown as { error: unknown }).error),
+      attemptsRemaining: context.attemptsRemaining - 1,
+    })),
+    clearOtpError: assign({
+      otpError: () => undefined,
+      otpCode: () => '',
+    }),
+    startResendTimer: assign({
+      resendTimer: () => RESEND_TIMER_SECONDS,
+      resendTimerActive: () => true,
+    }),
+    tickResendTimer: assign(({ context }) => {
+      const newTimer = Math.max(0, context.resendTimer - 1);
+      return {
+        resendTimer: newTimer,
+        resendTimerActive: newTimer > 0,
+      };
+    }),
+    stopResendTimer: assign({
+      resendTimerActive: () => false,
+    }),
+    resetContext: assign(({ context }) => ({
+      config: context.config,
+      phone: '',
+      isValid: false,
+      phoneError: undefined,
+      countryCode: '',
+      phonePrefix: '',
+      prefilledPhone: undefined,
+      optInGranted: false,
+      startInfo: undefined,
+      error: undefined,
+      otpCode: '',
+      otpError: undefined,
+      attemptsRemaining: context.config.maxOtpAttempts ?? 3,
+      resendTimer: 0,
+      resendTimerActive: false,
+    })),
+    sendPhoneSubmitEvent: () => {
+      addEvent({
+        code: 'continue',
+        module: 'phone',
+        screen: 'phoneInput',
+      });
+    },
+  },
+  guards: {
+    hasPrefill: ({ context }): boolean => context.config.prefill,
+    hasOtpVerification: ({ context }): boolean =>
+      context.config.otpVerification,
+    isValidPhone: ({ context }): boolean => context.isValid,
+    hasAttemptsRemaining: ({ context }): boolean =>
+      context.attemptsRemaining > 0,
+    canResend: ({ context }): boolean => !context.resendTimerActive,
+  },
+}).createMachine({
+  id: 'phone',
+  initial: 'idle',
+  context: ({ input }) => ({
+    config: input.config,
+    phone: '',
+    isValid: false,
+    phoneError: undefined,
+    countryCode: '',
+    phonePrefix: '',
+    prefilledPhone: undefined,
+    optInGranted: false,
+    startInfo: undefined,
+    error: undefined,
+    otpCode: '',
+    otpError: undefined,
+    attemptsRemaining: input.config.maxOtpAttempts ?? 3,
+    resendTimer: 0,
+    resendTimerActive: false,
+  }),
+  states: {
+    idle: {
+      on: {
+        LOAD: [
+          {
+            target: 'loadingPrefill',
+            guard: 'hasPrefill',
+          },
+          {
+            target: 'loadingStartInfo',
+          },
+        ],
+      },
+    },
+
+    loadingPrefill: {
+      invoke: {
+        id: 'fetchPhone',
+        src: 'fetchPhone',
+        onDone: {
+          target: 'loadingStartInfo',
+          actions: 'setPrefilledPhone',
+        },
+        onError: {
+          target: 'loadingStartInfo',
+        },
+      },
+    },
+
+    loadingStartInfo: {
+      invoke: {
+        id: 'fetchStartInfo',
+        src: 'fetchStartInfo',
+        onDone: {
+          target: 'inputting',
+          actions: 'setStartInfo',
+        },
+        onError: {
+          target: 'inputting',
+        },
+      },
+    },
+
+    inputting: {
+      entry: 'clearPhoneError',
+      on: {
+        PHONE_CHANGED: {
+          actions: 'setPhone',
+        },
+        OPT_IN_CHANGED: {
+          actions: 'setOptInGranted',
+        },
+        SUBMIT: {
+          target: 'submitting',
+          guard: 'isValidPhone',
+        },
+      },
+    },
+
+    submitting: {
+      invoke: {
+        id: 'submitPhone',
+        src: 'submitPhone',
+        input: ({ context }) => ({
+          phone: context.phone,
+          optInGranted: context.config.optinEnabled
+            ? context.optInGranted
+            : undefined,
+          isInstantVerify: context.config.isInstantVerify ?? false,
+        }),
+        onDone: [
+          {
+            target: 'sendingOtp',
+            guard: 'hasOtpVerification',
+            actions: 'sendPhoneSubmitEvent',
+          },
+          {
+            target: 'success',
+            actions: 'sendPhoneSubmitEvent',
+          },
+        ],
+        onError: {
+          target: 'inputting',
+          actions: 'setPhoneError',
+        },
+      },
+    },
+
+    sendingOtp: {
+      invoke: {
+        id: 'sendOtp',
+        src: 'sendOtp',
+        onDone: {
+          target: 'awaitingOtp',
+        },
+        onError: {
+          target: 'awaitingOtp',
+          actions: 'setError',
+        },
+      },
+    },
+
+    awaitingOtp: {
+      entry: 'startResendTimer',
+      invoke: {
+        id: 'resendTimer',
+        src: 'resendTimer',
+      },
+      on: {
+        TICK: {
+          actions: 'tickResendTimer',
+        },
+        OTP_CHANGED: {
+          actions: 'setOtpCode',
+        },
+        VERIFY_OTP: {
+          target: 'verifyingOtp',
+        },
+        RESEND_OTP: {
+          target: 'sendingOtp',
+          guard: 'canResend',
+        },
+        BACK: {
+          target: 'inputting',
+        },
+      },
+    },
+
+    verifyingOtp: {
+      invoke: {
+        id: 'verifyOtp',
+        src: 'verifyOtp',
+        input: ({ context }) => ({
+          code: context.otpCode,
+        }),
+        onDone: [
+          {
+            target: 'success',
+            guard: ({ event }) => event.output.success === true,
+          },
+          {
+            target: 'otpError',
+            guard: 'hasAttemptsRemaining',
+            actions: assign(({ context }) => ({
+              otpError: 'Invalid OTP code',
+              attemptsRemaining: context.attemptsRemaining - 1,
+            })),
+          },
+          {
+            target: 'error',
+            actions: assign({
+              error: () => 'Maximum OTP attempts exceeded',
+            }),
+          },
+        ],
+        onError: [
+          {
+            target: 'otpError',
+            guard: 'hasAttemptsRemaining',
+            actions: 'setOtpError',
+          },
+          {
+            target: 'error',
+            actions: 'setError',
+          },
+        ],
+      },
+    },
+
+    otpError: {
+      on: {
+        OTP_CHANGED: {
+          target: 'awaitingOtp',
+          actions: 'setOtpCode',
+        },
+        RESEND_OTP: {
+          target: 'sendingOtp',
+          guard: 'canResend',
+        },
+        BACK: {
+          target: 'inputting',
+        },
+      },
+    },
+
+    success: {
+      type: 'final',
+    },
+
+    error: {
+      on: {
+        RESET: {
+          target: 'idle',
+          actions: 'resetContext',
+        },
+      },
+    },
+  },
+  // biome-ignore lint/suspicious/noExplicitAny: XState type inference issue with guards in declaration files
+}) as any;
+
+export type PhoneMachine = typeof phoneMachine;

package/src/phone/types.ts

@@ -0,0 +1,83 @@
+/**
+ * Configuration options for phone verification.
+ *
+ * @example Standard OTP verification
+ * ```typescript
+ * const config: PhoneConfig = {
+ *   otpVerification: true,
+ *   otpExpirationInMinutes: 5,
+ *   prefill: false,
+ * };
+ * ```
+ *
+ * @example With all options
+ * ```typescript
+ * const config: PhoneConfig = {
+ *   otpVerification: true,
+ *   otpExpirationInMinutes: 10,
+ *   prefill: true,
+ *   isInstantVerify: false,
+ *   optinEnabled: true,
+ *   maxOtpAttempts: 3,
+ * };
+ * ```
+ */
+export type PhoneConfig = {
+  /**
+   * Whether to require OTP (SMS code) verification.
+   * If false, phone is verified immediately after submission.
+   */
+  otpVerification: boolean;
+
+  /**
+   * How long the OTP code remains valid, in minutes.
+   * After expiration, user must request a new code.
+   */
+  otpExpirationInMinutes: number;
+
+  /**
+   * Whether to pre-populate with user's previously stored phone number.
+   * Useful for returning users.
+   */
+  prefill: boolean;
+
+  /**
+   * Use carrier-based instant verification instead of OTP.
+   * Not available in all regions.
+   * @default false
+   */
+  isInstantVerify?: boolean;
+
+  /**
+   * Show a marketing opt-in checkbox in the UI.
+   * User's preference is sent with the phone submission.
+   * @default false
+   */
+  optinEnabled?: boolean;
+
+  /**
+   * Maximum number of OTP verification attempts before lockout.
+   * After exhausting attempts, user sees an error state.
+   * @default 3
+   */
+  maxOtpAttempts?: number;
+};
+
+export type StartInfo = {
+  phonePrefix: string;
+  country: string;
+  ipIsoCode: string;
+};
+
+export type AddPhoneResponse = {
+  success: boolean;
+};
+
+export type VerifyOtpResponse = {
+  success: boolean;
+};
+
+export type AddPhoneParams = {
+  phone: string;
+  optInGranted?: boolean;
+};

package/src/recordings/recordingsRepository.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it, vi } from 'vitest';
+import { endpoints } from '../http/endpoints';
+import {
+  createRecordingSession,
+  startRecording,
+  stopRecording,
+} from './recordingsRepository';
+
+vi.mock('../http/api', () => ({
+  api: {
+    post: vi.fn(),
+  },
+}));
+
+describe('recordingsRepository', () => {
+  it('creates a recording session using the v2 endpoint', async () => {
+    const { api } = await import('../http/api');
+    vi.mocked(api.post).mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      statusText: 'OK',
+      url: 'x',
+      headers: {},
+      data: {
+        token: 't',
+        videoRecordingId: 'v',
+        sessionId: 's',
+      },
+    });
+
+    await expect(createRecordingSession('selfie')).resolves.toEqual({
+      token: 't',
+      videoRecordingId: 'v',
+      sessionId: 's',
+    });
+
+    expect(api.post).toHaveBeenCalledWith(endpoints.recordingCreateSessionV2, {
+      type: 'selfie',
+    });
+  });
+
+  it('starts recording with v2 endpoint and composed output', async () => {
+    const { api } = await import('../http/api');
+    vi.mocked(api.post).mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      statusText: 'OK',
+      url: 'x',
+      headers: {},
+      data: { ok: true },
+    });
+
+    await startRecording({
+      videoRecordingId: 'vid',
+      type: 'selfie',
+      resolution: '640x480',
+      hasAudio: true,
+    });
+
+    expect(api.post).toHaveBeenCalledWith(endpoints.recordingStartV2, {
+      videoRecordingId: 'vid',
+      frameRate: 30,
+      outputMode: 'COMPOSED',
+      resolution: '640x480',
+      type: 'selfie',
+      hasAudio: true,
+    });
+  });
+
+  it('stops recording with v2 endpoint', async () => {
+    const { api } = await import('../http/api');
+    vi.mocked(api.post).mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      statusText: 'OK',
+      url: 'x',
+      headers: {},
+      data: { ok: true },
+    });
+
+    await stopRecording('vid');
+
+    expect(api.post).toHaveBeenCalledWith(endpoints.recordingStopV2, {
+      videoRecordingId: 'vid',
+    });
+  });
+});

package/src/recordings/recordingsRepository.ts

@@ -0,0 +1,48 @@
+import { api } from '../http/api';
+import { endpoints } from '../http/endpoints';
+
+export type CreateRecordingSessionResponse = {
+  token: string;
+  videoRecordingId: string;
+  sessionId: string;
+};
+
+export async function createRecordingSession(
+  type: string,
+): Promise<CreateRecordingSessionResponse> {
+  const response = await api.post<CreateRecordingSessionResponse>(
+    endpoints.recordingCreateSessionV2,
+    { type },
+  );
+  return response.data;
+}
+
+export type StartRecordingParams = {
+  videoRecordingId: string;
+  type?: string;
+  resolution?: string;
+  hasAudio?: boolean;
+};
+
+export async function startRecording(
+  params: StartRecordingParams,
+): Promise<unknown> {
+  const response = await api.post(endpoints.recordingStartV2, {
+    videoRecordingId: params.videoRecordingId,
+    frameRate: 30,
+    outputMode: 'COMPOSED',
+    resolution: params.resolution,
+    type: params.type,
+    hasAudio: params.hasAudio ?? false,
+  });
+  return response.data;
+}
+
+export async function stopRecording(
+  videoRecordingId: string,
+): Promise<unknown> {
+  const response = await api.post(endpoints.recordingStopV2, {
+    videoRecordingId,
+  });
+  return response.data;
+}

package/src/recordings/streamingEvents.ts

@@ -0,0 +1,10 @@
+export const streamingEvents = {
+  strSessionDidConnect: 'strSessionDidConnect',
+  strSessionDidDisconnect: 'strSessionDidDisconnect',
+  strSessionDidFailWithError: 'strSessionDidFailWithError',
+  strStreamVideoCaptureStart: 'strStreamVideoCaptureStart',
+  strStreamVideoCaptureStop: 'strStreamVideoCaptureStop',
+  strStreamPublisherCreated: 'strStreamPublisherCreated',
+  strStreamPublisherDestroyed: 'strStreamPublisherDestroyed',
+  strStreamPublisherDidFailWithError: 'strStreamPublisherDidFailWithError',
+} as const;

package/src/selfie/__mocks__/selfieMocks.ts

@@ -0,0 +1,26 @@
+import type { SelfieConfig } from '../types';
+
+export const mockSelfieConfig: SelfieConfig = {
+  showTutorial: false,
+  showPreview: false,
+  assistedOnboarding: false,
+  enableFaceRecording: false,
+  autoCaptureTimeout: 10_000,
+  captureAttempts: 2,
+  validateLenses: false,
+  validateFaceMask: false,
+  validateHeadCover: false,
+  validateClosedEyes: false,
+  validateBrightness: false,
+  deepsightLiveness: 'SINGLE_FRAME',
+};
+
+export const mockSelfieConfigWithTutorial: SelfieConfig = {
+  ...mockSelfieConfig,
+  showTutorial: true,
+};
+
+export const mockSelfieConfigWithOneAttempt: SelfieConfig = {
+  ...mockSelfieConfig,
+  captureAttempts: 1,
+};

package/src/selfie/index.ts

@@ -0,0 +1,14 @@
+export {
+  createSelfieManager,
+  type SelfieManager,
+  type SelfieState,
+} from './selfieManager';
+export type { CameraStream } from './selfieServices';
+export { type SelfieMachine, selfieMachine } from './selfieStateMachine';
+export type {
+  DetectionStatus,
+  FaceErrorCode,
+  PermissionResult,
+  PermissionStatus,
+  SelfieConfig,
+} from './types';

package/src/selfie/selfieActor.ts

@@ -0,0 +1,17 @@
+import { type ActorRefFrom, createActor } from '@incodetech/infra';
+import { type SelfieMachine, selfieMachine } from './selfieStateMachine';
+import type { SelfieConfig } from './types';
+
+export type CreateSelfieActorOptions = {
+  config: SelfieConfig;
+};
+
+export type SelfieActor = ActorRefFrom<SelfieMachine>;
+
+export function createSelfieActor(
+  options: CreateSelfieActorOptions,
+): SelfieActor {
+  return createActor(selfieMachine, {
+    input: { config: options.config },
+  }).start();
+}