@incodetech/core 2.0.0-alpha.1 → 2.0.0-alpha.10

package/src/email/emailManager.ts

@@ -1,427 +0,0 @@
-/**
- * @module @incodetech/core/email
- *
- * Email verification module for the Incode Web SDK.
- * Supports both headless (programmatic) and UI-driven usage patterns.
- *
- * ## Headless Usage
- *
- * The email manager can be used entirely without UI for backend integrations,
- * custom UI implementations, or automated workflows.
- *
- * @example Basic headless email verification with OTP
- * ```typescript
- * import { createEmailManager } from '@incodetech/core/email';
- * import { setup } from '@incodetech/core';
- *
- * // 1. Configure the SDK (required before using any module)
- * setup({ apiURL: 'https://api.example.com', token: 'your-token' });
- *
- * // 2. Create the email manager
- * const emailManager = createEmailManager({
- *   config: {
- *     otpVerification: true,
- *     otpExpirationInMinutes: 5,
- *     prefill: false,
- *   },
- * });
- *
- * // 3. Subscribe to state changes (optional but recommended)
- * emailManager.subscribe((state) => {
- *   console.log('Email state:', state.status);
- *   if (state.status === 'success') {
- *     console.log('Email verified successfully!');
- *   }
- *   if (state.status === 'error') {
- *     console.error('Error:', state.error);
- *   }
- * });
- *
- * // 4. Start the flow
- * emailManager.load();
- *
- * // 5. When state is 'inputting', set the email address
- * emailManager.setEmail('user@example.com', true);
- *
- * // 6. Submit the email address
- * emailManager.submit();
- *
- * // 7. When state is 'awaitingOtp', submit the OTP code
- * emailManager.submitOtp('ABC123');
- *
- * // 8. Clean up when done
- * emailManager.stop();
- * ```
- *
- * @example Polling-based headless usage
- * ```typescript
- * const emailManager = createEmailManager({ config });
- *
- * emailManager.load();
- *
- * // Poll for state changes
- * const interval = setInterval(() => {
- *   const state = emailManager.getState();
- *
- *   switch (state.status) {
- *     case 'inputting':
- *       emailManager.setEmail('user@example.com', true);
- *       emailManager.submit();
- *       break;
- *     case 'awaitingOtp':
- *       // Get OTP from user or external source
- *       emailManager.submitOtp(otpCode);
- *       break;
- *     case 'success':
- *       clearInterval(interval);
- *       emailManager.stop();
- *       break;
- *     case 'error':
- *       clearInterval(interval);
- *       console.error(state.error);
- *       emailManager.stop();
- *       break;
- *   }
- * }, 100);
- * ```
- */
-import {
-  type CreateApiOptions,
-  createManager,
-  type ManagerSnapshot,
-} from '@incodetech/infra';
-import { type CreateEmailActorOptions, createEmailActor } from './emailActor';
-import type { EmailMachine } from './emailStateMachine';
-
-type EmailSnapshot = ManagerSnapshot<EmailMachine>;
-
-/** Email manager is in initial state, waiting for `load()` to be called */
-export type EmailIdleState = {
-  status: 'idle';
-};
-
-/** Loading prefilled email address from backend (if prefill is enabled) */
-export type EmailLoadingPrefillState = {
-  status: 'loadingPrefill';
-};
-
-/**
- * Ready for email input - use `setEmail()` and `submit()`
- * @property prefilledEmail - Pre-populated email address (if prefill enabled)
- * @property emailError - Validation error message if email was rejected
- */
-export type EmailInputtingState = {
-  status: 'inputting';
-  prefilledEmail?: string;
-  emailError?: string;
-};
-
-/** Email address is being submitted to the backend */
-export type EmailSubmittingState = {
-  status: 'submitting';
-};
-
-/** OTP is being sent to the email address */
-export type EmailSendingOtpState = {
-  status: 'sendingOtp';
-};
-
-/**
- * Waiting for OTP code - use `submitOtp()`, `resendOtp()`, or `back()`
- * @property resendTimer - Seconds remaining before resend is allowed
- * @property canResend - Whether the resend button should be enabled
- * @property attemptsRemaining - Number of OTP verification attempts left
- */
-export type EmailAwaitingOtpState = {
-  status: 'awaitingOtp';
-  resendTimer: number;
-  canResend: boolean;
-  attemptsRemaining: number;
-};
-
-/** OTP code is being verified against the backend */
-export type EmailVerifyingOtpState = {
-  status: 'verifyingOtp';
-};
-
-/**
- * OTP verification failed - user can retry with `submitOtp()`
- * @property error - Error message describing why verification failed
- * @property attemptsRemaining - Number of remaining attempts before lockout
- */
-export type EmailOtpErrorState = {
-  status: 'otpError';
-  error: string;
-  attemptsRemaining: number;
-};
-
-/** Email verification completed successfully - call `reset()` to start over */
-export type EmailSuccessState = {
-  status: 'success';
-};
-
-/**
- * Fatal error occurred - call `reset()` to start over
- * @property error - Error message describing what went wrong
- */
-export type EmailErrorState = {
-  status: 'error';
-  error: string;
-};
-
-/**
- * Union of all possible email manager states.
- * Use discriminated union pattern to narrow the type:
- *
- * @example
- * ```typescript
- * const state = emailManager.getState();
- * if (state.status === 'inputting') {
- *   // TypeScript knows state has prefilledEmail, emailError, etc.
- *   console.log(state.prefilledEmail);
- * }
- * ```
- */
-export type EmailState =
-  | EmailIdleState
-  | EmailLoadingPrefillState
-  | EmailInputtingState
-  | EmailSubmittingState
-  | EmailSendingOtpState
-  | EmailAwaitingOtpState
-  | EmailVerifyingOtpState
-  | EmailOtpErrorState
-  | EmailSuccessState
-  | EmailErrorState;
-
-function mapState(snapshot: EmailSnapshot): EmailState {
-  // Type assertion needed because EmailMachine uses 'as any' for declaration file generation
-  const typedSnapshot = snapshot as EmailSnapshot & {
-    matches: (state: string) => boolean;
-    context: {
-      prefilledEmail?: string;
-      emailError?: string;
-      resendTimer: number;
-      resendTimerActive: boolean;
-      attemptsRemaining: number;
-      otpError?: string;
-      error?: string;
-    };
-  };
-  const { context } = typedSnapshot;
-
-  if (typedSnapshot.matches('idle')) {
-    return { status: 'idle' };
-  }
-
-  if (typedSnapshot.matches('loadingPrefill')) {
-    return { status: 'loadingPrefill' };
-  }
-
-  if (typedSnapshot.matches('inputting')) {
-    return {
-      status: 'inputting',
-      prefilledEmail: context.prefilledEmail,
-      emailError: context.emailError,
-    };
-  }
-
-  if (typedSnapshot.matches('submitting')) {
-    return { status: 'submitting' };
-  }
-
-  if (typedSnapshot.matches('sendingOtp')) {
-    return { status: 'sendingOtp' };
-  }
-
-  if (typedSnapshot.matches('awaitingOtp')) {
-    return {
-      status: 'awaitingOtp',
-      resendTimer: context.resendTimer,
-      canResend: !context.resendTimerActive,
-      attemptsRemaining: context.attemptsRemaining,
-    };
-  }
-
-  if (typedSnapshot.matches('verifyingOtp')) {
-    return { status: 'verifyingOtp' };
-  }
-
-  if (typedSnapshot.matches('otpError')) {
-    return {
-      status: 'otpError',
-      error: context.otpError ?? 'Invalid OTP code',
-      attemptsRemaining: context.attemptsRemaining,
-    };
-  }
-
-  if (typedSnapshot.matches('success')) {
-    return { status: 'success' };
-  }
-
-  if (typedSnapshot.matches('error')) {
-    return {
-      status: 'error',
-      error: context.error ?? 'An error occurred',
-    };
-  }
-
-  return { status: 'idle' };
-}
-
-function createApi({ actor }: CreateApiOptions<EmailMachine>) {
-  return {
-    /**
-     * Initializes the email verification flow.
-     * Transitions from 'idle' to 'loadingPrefill' or 'inputting'.
-     * Must be called before any other method.
-     */
-    load() {
-      actor.send({ type: 'LOAD' });
-    },
-
-    /**
-     * Sets the email address for verification.
-     * Should be called when state is 'inputting'.
-     *
-     * @param email - Email address (e.g., 'user@example.com')
-     * @param isValid - Whether the email address passes validation
-     *
-     * @example
-     * ```typescript
-     * // Using regex for validation
-     * const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
-     * const email = 'user@example.com';
-     * emailManager.setEmail(email, emailRegex.test(email));
-     * ```
-     */
-    setEmail(email: string, isValid: boolean) {
-      actor.send({ type: 'EMAIL_CHANGED', email, isValid });
-    },
-
-    /**
-     * Submits the email address for verification.
-     * Requires a valid email address to be set via `setEmail()`.
-     * Transitions to 'submitting', then to 'sendingOtp' or 'success' (if no OTP).
-     */
-    submit() {
-      actor.send({ type: 'SUBMIT' });
-    },
-
-    /**
-     * Sets the OTP code without submitting.
-     * Use this for controlled input components.
-     *
-     * @param code - The OTP code entered by the user
-     */
-    setOtpCode(code: string) {
-      actor.send({ type: 'OTP_CHANGED', code });
-    },
-
-    /**
-     * Sets and submits the OTP code in one call.
-     * Should be called when state is 'awaitingOtp' or 'otpError'.
-     *
-     * @param code - The complete OTP code (typically 6 alphanumeric characters)
-     *
-     * @example
-     * ```typescript
-     * // Submit OTP when user completes entry
-     * emailManager.submitOtp('HH36LP');
-     * ```
-     */
-    submitOtp(code: string) {
-      actor.send({ type: 'OTP_CHANGED', code });
-      actor.send({ type: 'VERIFY_OTP' });
-    },
-
-    /**
-     * Requests a new OTP code to be sent.
-     * Only works when state is 'awaitingOtp' and `canResend` is true.
-     * Resets the resend timer.
-     */
-    resendOtp() {
-      actor.send({ type: 'RESEND_OTP' });
-    },
-
-    /**
-     * Returns to the email input screen from OTP entry.
-     * Allows the user to change their email address.
-     * Transitions from 'awaitingOtp' or 'otpError' back to 'inputting'.
-     */
-    back() {
-      actor.send({ type: 'BACK' });
-    },
-
-    /**
-     * Resets the manager to initial state.
-     * Can be called from 'success' or 'error' states to start over.
-     * Clears all stored data including email address and OTP.
-     */
-    reset() {
-      actor.send({ type: 'RESET' });
-    },
-  };
-}
-
-/**
- * Creates an email verification manager for headless or UI-driven usage.
- *
- * The manager provides a state machine-based API for email address verification
- * with optional OTP (one-time password) verification.
- *
- * @param options - Configuration options
- * @param options.config - Email verification configuration
- * @param options.config.otpVerification - Whether to require OTP verification
- * @param options.config.otpExpirationInMinutes - How long the OTP is valid
- * @param options.config.prefill - Whether to fetch a pre-filled email address
- * @param options.config.maxOtpAttempts - Maximum OTP verification attempts (default: 3)
- *
- * @returns Email manager with state, API methods, and subscription
- *
- * @example Headless usage
- * ```typescript
- * 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();
- * // ... wait for 'awaitingOtp' state ...
- * manager.submitOtp('ABC123');
- * manager.stop();
- * ```
- *
- * @example With React/Preact UI hook
- * ```tsx
- * const [state, manager] = useManager(() => createEmailManager({ config }));
- *
- * if (state.status === 'inputting') {
- *   return <input onChange={(e) => manager.setEmail(e.target.value, true)} />;
- * }
- * ```
- */
-export function createEmailManager(options: CreateEmailActorOptions) {
-  const actor = createEmailActor(options);
-  return createManager({ actor, mapState, createApi });
-}
-
-/**
- * Type representing an email manager instance.
- * Includes state access, API methods, and lifecycle management.
- *
- * @property getState - Returns the current EmailState
- * @property subscribe - Subscribes to state changes, returns unsubscribe function
- * @property stop - Stops the manager and cleans up resources
- * @property load - Initializes the verification flow
- * @property setEmail - Sets the email address
- * @property submit - Submits the email address
- * @property setOtpCode - Sets OTP code without submitting
- * @property submitOtp - Sets and submits OTP code
- * @property resendOtp - Requests new OTP code
- * @property back - Returns to email input from OTP screen
- * @property reset - Resets to initial state
- */
-export type EmailManager = ReturnType<typeof createEmailManager>;

package/src/email/emailServices.ts

@@ -1,66 +0,0 @@
-import { api } from '../http/api';
-import { endpoints } from '../http/endpoints';
-import type {
-  AddEmailParams,
-  AddEmailResponse,
-  VerifyOtpResponse,
-} from './types';
-
-export async function fetchEmail(
-  signal?: AbortSignal,
-): Promise<{ email: string }> {
-  const res = await api.get<{ email: string }>(endpoints.getEmail, { signal });
-  if (!res.ok) {
-    throw new Error(
-      `GET ${endpoints.getEmail} failed: ${res.status} ${res.statusText}`,
-    );
-  }
-  return res.data as { email: string };
-}
-
-export async function addEmail(
-  params: AddEmailParams,
-  signal?: AbortSignal,
-): Promise<AddEmailResponse> {
-  const res = await api.post<AddEmailResponse>(
-    endpoints.email,
-    {
-      email: params.email,
-    },
-    { signal },
-  );
-  if (!res.ok) {
-    throw new Error(
-      `POST ${endpoints.email} failed: ${res.status} ${res.statusText}`,
-    );
-  }
-  return res.data as AddEmailResponse;
-}
-
-export async function sendEmailOtp(signal?: AbortSignal): Promise<void> {
-  const res = await api.get(
-    `${endpoints.sendSmsOtp}?communicationchannel=EMAIL`,
-    { signal },
-  );
-  if (!res.ok) {
-    throw new Error(
-      `GET ${endpoints.sendSmsOtp} failed: ${res.status} ${res.statusText}`,
-    );
-  }
-}
-
-export async function verifyEmailOtp(
-  code: string,
-  signal?: AbortSignal,
-): Promise<VerifyOtpResponse> {
-  const res = await api.get<VerifyOtpResponse>(
-    `${endpoints.compareOtp}?code=${code}&channel=EMAIL`,
-    { signal },
-  );
-  if (!res.ok) {
-    throw new Error(
-      `GET ${endpoints.compareOtp} failed: ${res.status} ${res.statusText}`,
-    );
-  }
-  return res.data as VerifyOtpResponse;
-}