@incodetech/core 2.0.0-alpha.1

package/src/email/emailStateMachine.ts

@@ -0,0 +1,367 @@
+import { assign, fromCallback, fromPromise, setup } from '@incodetech/infra';
+import { addEvent } from '../events/addEvent';
+import {
+  addEmail,
+  fetchEmail,
+  sendEmailOtp,
+  verifyEmailOtp,
+} from './emailServices';
+import type { EmailConfig } from './types';
+
+export type EmailContext = {
+  config: EmailConfig;
+  email: string;
+  isValid: boolean;
+  emailError: string | undefined;
+  prefilledEmail: string | undefined;
+  error: string | undefined;
+  otpCode: string;
+  otpError: string | undefined;
+  attemptsRemaining: number;
+  resendTimer: number;
+  resendTimerActive: boolean;
+};
+
+export type EmailEvent =
+  | { type: 'LOAD' }
+  | { type: 'EMAIL_CHANGED'; email: string; isValid: boolean }
+  | { type: 'SUBMIT' }
+  | { type: 'OTP_CHANGED'; code: string }
+  | { type: 'VERIFY_OTP' }
+  | { type: 'RESEND_OTP' }
+  | { type: 'BACK' }
+  | { type: 'RESET' }
+  | { type: 'TICK' };
+
+export type EmailInput = {
+  config: EmailConfig;
+};
+
+const RESEND_TIMER_SECONDS = 30;
+
+export const emailMachine = setup({
+  types: {
+    context: {} as EmailContext,
+    events: {} as EmailEvent,
+    input: {} as EmailInput,
+  },
+  actors: {
+    fetchEmail: fromPromise<{ email: string }, void>(async ({ signal }) => {
+      return fetchEmail(signal);
+    }),
+    submitEmail: fromPromise<{ success: boolean }, { email: string }>(
+      async ({ input, signal }) => {
+        return addEmail({ email: input.email }, signal);
+      },
+    ),
+    sendOtp: fromPromise<void, void>(async ({ signal }) => {
+      return sendEmailOtp(signal);
+    }),
+    verifyOtp: fromPromise<{ success: boolean }, { code: string }>(
+      async ({ input, signal }) => {
+        return verifyEmailOtp(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: {
+    setPrefilledEmail: assign(({ event }) => {
+      const email = (event as unknown as { output: { email: string } }).output
+        .email;
+      return {
+        prefilledEmail: email,
+        email,
+      };
+    }),
+    setEmail: assign(({ event }) => {
+      const e = event as {
+        type: 'EMAIL_CHANGED';
+        email: string;
+        isValid: boolean;
+      };
+      return {
+        email: e.email,
+        isValid: e.isValid,
+        emailError: e.isValid ? undefined : 'Invalid email address',
+      };
+    }),
+    setEmailError: assign(({ event }) => ({
+      emailError: String((event as unknown as { error: unknown }).error),
+    })),
+    setError: assign(({ event }) => ({
+      error: String((event as unknown as { error: unknown }).error),
+    })),
+    clearError: assign({
+      error: () => undefined,
+    }),
+    clearEmailError: assign({
+      emailError: () => 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,
+      email: '',
+      isValid: false,
+      emailError: undefined,
+      prefilledEmail: undefined,
+      error: undefined,
+      otpCode: '',
+      otpError: undefined,
+      attemptsRemaining: context.config.maxOtpAttempts ?? 3,
+      resendTimer: 0,
+      resendTimerActive: false,
+    })),
+    sendEmailSubmitEvent: () => {
+      addEvent({
+        code: 'continue',
+        module: 'email',
+        screen: 'emailInput',
+      });
+    },
+  },
+  guards: {
+    hasPrefill: ({ context }): boolean => context.config.prefill,
+    hasOtpVerification: ({ context }): boolean =>
+      context.config.otpVerification,
+    isValidEmail: ({ context }): boolean => context.isValid,
+    hasAttemptsRemaining: ({ context }): boolean =>
+      context.attemptsRemaining > 0,
+    canResend: ({ context }): boolean => !context.resendTimerActive,
+  },
+}).createMachine({
+  id: 'email',
+  initial: 'idle',
+  context: ({ input }) => ({
+    config: input.config,
+    email: '',
+    isValid: false,
+    emailError: undefined,
+    prefilledEmail: undefined,
+    error: undefined,
+    otpCode: '',
+    otpError: undefined,
+    attemptsRemaining: input.config.maxOtpAttempts ?? 3,
+    resendTimer: 0,
+    resendTimerActive: false,
+  }),
+  states: {
+    idle: {
+      on: {
+        LOAD: [
+          {
+            target: 'loadingPrefill',
+            guard: 'hasPrefill',
+          },
+          {
+            target: 'inputting',
+          },
+        ],
+      },
+    },
+
+    loadingPrefill: {
+      invoke: {
+        id: 'fetchEmail',
+        src: 'fetchEmail',
+        onDone: {
+          target: 'inputting',
+          actions: 'setPrefilledEmail',
+        },
+        onError: {
+          target: 'inputting',
+        },
+      },
+    },
+
+    inputting: {
+      entry: 'clearEmailError',
+      on: {
+        EMAIL_CHANGED: {
+          actions: 'setEmail',
+        },
+        SUBMIT: {
+          target: 'submitting',
+          guard: 'isValidEmail',
+        },
+      },
+    },
+
+    submitting: {
+      invoke: {
+        id: 'submitEmail',
+        src: 'submitEmail',
+        input: ({ context }) => ({
+          email: context.email,
+        }),
+        onDone: [
+          {
+            target: 'sendingOtp',
+            guard: 'hasOtpVerification',
+            actions: 'sendEmailSubmitEvent',
+          },
+          {
+            target: 'success',
+            actions: 'sendEmailSubmitEvent',
+          },
+        ],
+        onError: {
+          target: 'inputting',
+          actions: 'setEmailError',
+        },
+      },
+    },
+
+    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: {
+      on: {
+        RESET: {
+          target: 'idle',
+          actions: 'resetContext',
+        },
+      },
+    },
+
+    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 EmailMachine = typeof emailMachine;

package/src/email/index.ts

@@ -0,0 +1,39 @@
+/**
+ * Email verification module - supports headless and UI-driven usage.
+ *
+ * ## Headless Usage (Programmatic)
+ *
+ * Use `createEmailManager` to control email verification without any UI.
+ * Perfect for custom UI implementations, backend integrations, or automated testing.
+ *
+ * ```typescript
+ * import { createEmailManager } from '@incodetech/core/email';
+ *
+ * const manager = createEmailManager({
+ *   config: { otpVerification: true, otpExpirationInMinutes: 5, prefill: false },
+ * });
+ *
+ * manager.subscribe((state) => console.log(state.status));
+ * manager.load();
+ * manager.setEmail('user@example.com', true);
+ * manager.submit();
+ * manager.submitOtp('ABC123');
+ * manager.stop();
+ * ```
+ *
+ * ## UI Usage
+ *
+ * For a ready-to-use UI, import the Email component from `@incodetech/ui/email`.
+ *
+ * @module @incodetech/core/email
+ * @see {@link createEmailManager} for headless API documentation
+ * @see {@link EmailConfig} for configuration options
+ * @see {@link EmailState} for state machine states
+ */
+export {
+  createEmailManager,
+  type EmailManager,
+  type EmailState,
+} from './emailManager';
+export { emailMachine } from './emailStateMachine';
+export type { EmailConfig } from './types';

package/src/email/types.ts

@@ -0,0 +1,60 @@
+/**
+ * Configuration options for email verification.
+ *
+ * @example Standard OTP verification
+ * ```typescript
+ * const config: EmailConfig = {
+ *   otpVerification: true,
+ *   otpExpirationInMinutes: 5,
+ *   prefill: false,
+ * };
+ * ```
+ *
+ * @example With all options
+ * ```typescript
+ * const config: EmailConfig = {
+ *   otpVerification: true,
+ *   otpExpirationInMinutes: 10,
+ *   prefill: true,
+ *   maxOtpAttempts: 3,
+ * };
+ * ```
+ */
+export type EmailConfig = {
+  /**
+   * Whether to require OTP (email code) verification.
+   * If false, email 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 email address.
+   * Useful for returning users.
+   */
+  prefill: boolean;
+
+  /**
+   * Maximum number of OTP verification attempts before lockout.
+   * After exhausting attempts, user sees an error state.
+   * @default 3
+   */
+  maxOtpAttempts?: number;
+};
+
+export type AddEmailResponse = {
+  success: boolean;
+};
+
+export type VerifyOtpResponse = {
+  success: boolean;
+};
+
+export type AddEmailParams = {
+  email: string;
+};

package/src/events/addEvent.ts

@@ -0,0 +1,20 @@
+import { api } from '../http/api';
+import { endpoints } from '../http/endpoints';
+import type { Event } from './types';
+
+export function addEvent(event: Event): Promise<void> {
+  const { code, module, screen, clientTimestamp, payload = {} } = event;
+
+  return api
+    .post(endpoints.events, [
+      {
+        code,
+        module,
+        screen,
+        clientTimestamp: clientTimestamp ?? Date.now(),
+        payload,
+      },
+    ])
+    .then(() => undefined)
+    .catch(() => undefined);
+}

package/src/events/types.ts

@@ -0,0 +1,7 @@
+export type Event = {
+  code: string;
+  module?: string;
+  screen?: string;
+  payload?: Record<string, unknown>;
+  clientTimestamp?: number;
+};

package/src/flow/__mocks__/flowMocks.ts

@@ -0,0 +1,84 @@
+import { vi } from 'vitest';
+import type { Flow, FlowModule } from '../types';
+
+export const mockTutorialIdModule: FlowModule = {
+  key: 'TUTORIAL_ID',
+  configuration: {
+    showTutorial: true,
+    enableId: true,
+    enablePassport: false,
+    onlyFront: false,
+    onlyBack: false,
+    barcodeCapture: false,
+    fetchAdditionalPage: false,
+    secondId: false,
+    thirdId: false,
+    autoCaptureTimeout: 30,
+    deviceIdleTimeout: 60,
+    captureAttempts: 3,
+    manualUploadIdCapture: false,
+    digitalIdsUpload: false,
+    showDocumentChooserScreen: false,
+    enableIdRecording: false,
+    usSmartCapture: false,
+    perCountryPerDocOverrides: {},
+  },
+};
+
+export const mockSelfieModule: FlowModule = {
+  key: 'SELFIE',
+  configuration: {
+    showTutorial: false,
+    showPreview: true,
+    assistedOnboarding: false,
+    enableFaceRecording: false,
+    autoCaptureTimeout: 30,
+    captureAttempts: 3,
+    validateLenses: false,
+    validateFaceMask: false,
+    validateHeadCover: false,
+    validateClosedEyes: false,
+    validateBrightness: false,
+    deepsightLiveness: 'SINGLE_FRAME',
+  },
+};
+
+export const mockFaceMatchModule: FlowModule = {
+  key: 'FACE_MATCH',
+  configuration: {
+    matchingType: 'selfieVsId',
+    disableFaceMatchAnimation: false,
+  },
+};
+
+export const mockModules: FlowModule[] = [
+  mockTutorialIdModule,
+  mockSelfieModule,
+  mockFaceMatchModule,
+];
+
+export function createMockFlow(modules: FlowModule[] = mockModules): Flow {
+  return {
+    flowId: 'test-flow-id',
+    name: 'Test Flow',
+    flowModules: modules,
+  };
+}
+
+export const mockFlow = createMockFlow();
+
+export function createMockGetFlow(flow: Flow = mockFlow) {
+  return vi.fn().mockResolvedValue(flow);
+}
+
+export function createFailingGetFlow(error: string) {
+  return vi.fn().mockRejectedValue(new Error(error));
+}
+
+export function createDelayedGetFlow(flow: Flow = mockFlow, delayMs = 1000) {
+  return vi
+    .fn()
+    .mockImplementation(
+      () => new Promise((resolve) => setTimeout(() => resolve(flow), delayMs)),
+    );
+}

package/src/flow/flowActor.ts

@@ -0,0 +1,13 @@
+import { createActor } from '@incodetech/infra';
+import { getFlow as defaultGetFlow, type GetFlow } from './flowServices';
+import { flowMachine } from './flowStateMachine';
+
+export type CreateFlowActorOptions = {
+  getFlow?: GetFlow;
+};
+
+export function createFlowActor(options?: CreateFlowActorOptions) {
+  const getFlow = options?.getFlow ?? defaultGetFlow;
+
+  return createActor(flowMachine, { input: { getFlow } }).start();
+}