@incodetech/core 2.0.0-alpha.2 → 2.0.0-alpha.3

package/src/phone/phoneManager.ts

@@ -1,458 +0,0 @@
-/**
- * @module @incodetech/core/phone
- *
- * Phone verification module for the Incode Web SDK.
- * Supports both headless (programmatic) and UI-driven usage patterns.
- *
- * ## Headless Usage
- *
- * The phone manager can be used entirely without UI for backend integrations,
- * custom UI implementations, or automated workflows.
- *
- * @example Basic headless phone verification with OTP
- * ```typescript
- * import { createPhoneManager } from '@incodetech/core/phone';
- * 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 phone manager
- * const phoneManager = createPhoneManager({
- *   config: {
- *     otpVerification: true,
- *     otpExpirationInMinutes: 5,
- *     prefill: false,
- *     maxOtpAttempts: 3,
- *   },
- * });
- *
- * // 3. Subscribe to state changes (optional but recommended)
- * phoneManager.subscribe((state) => {
- *   console.log('Phone state:', state.status);
- *   if (state.status === 'success') {
- *     console.log('Phone verified successfully!');
- *   }
- *   if (state.status === 'error') {
- *     console.error('Error:', state.error);
- *   }
- * });
- *
- * // 4. Start the flow
- * phoneManager.load();
- *
- * // 5. When state is 'inputting', set the phone number
- * phoneManager.setPhoneNumber('+14155551234', true);
- *
- * // 6. Submit the phone number
- * phoneManager.submit();
- *
- * // 7. When state is 'awaitingOtp', submit the OTP code
- * phoneManager.submitOtp('ABC123');
- *
- * // 8. Clean up when done
- * phoneManager.stop();
- * ```
- *
- * @example Polling-based headless usage
- * ```typescript
- * const phoneManager = createPhoneManager({ config });
- *
- * phoneManager.load();
- *
- * // Poll for state changes
- * const interval = setInterval(() => {
- *   const state = phoneManager.getState();
- *
- *   switch (state.status) {
- *     case 'inputting':
- *       phoneManager.setPhoneNumber('+14155551234', true);
- *       phoneManager.submit();
- *       break;
- *     case 'awaitingOtp':
- *       // Get OTP from user or external source
- *       phoneManager.submitOtp(otpCode);
- *       break;
- *     case 'success':
- *       clearInterval(interval);
- *       phoneManager.stop();
- *       break;
- *     case 'error':
- *       clearInterval(interval);
- *       console.error(state.error);
- *       phoneManager.stop();
- *       break;
- *   }
- * }, 100);
- * ```
- */
-import {
-  type CreateApiOptions,
-  createManager,
-  type ManagerSnapshot,
-} from '@incodetech/infra';
-import { type CreatePhoneActorOptions, createPhoneActor } from './phoneActor';
-import type { PhoneMachine } from './phoneStateMachine';
-
-type PhoneSnapshot = ManagerSnapshot<PhoneMachine>;
-
-/** Phone manager is in initial state, waiting for `load()` to be called */
-export type PhoneIdleState = {
-  status: 'idle';
-};
-
-/** Loading prefilled phone number from backend (if prefill is enabled) */
-export type PhoneLoadingPrefillState = {
-  status: 'loadingPrefill';
-};
-
-/**
- * Ready for phone input - use `setPhoneNumber()` and `submit()`
- * @property countryCode - ISO country code (e.g., 'US', 'MX')
- * @property phonePrefix - International dialing prefix (e.g., '+1', '+52')
- * @property prefilledPhone - Pre-populated phone number (if prefill enabled)
- * @property phoneError - Validation error message if phone was rejected
- */
-export type PhoneInputtingState = {
-  status: 'inputting';
-  countryCode: string;
-  phonePrefix: string;
-  prefilledPhone?: string;
-  phoneError?: string;
-};
-
-/** Phone number is being submitted to the backend */
-export type PhoneSubmittingState = {
-  status: 'submitting';
-};
-
-/** OTP is being sent to the phone number */
-export type PhoneSendingOtpState = {
-  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 PhoneAwaitingOtpState = {
-  status: 'awaitingOtp';
-  resendTimer: number;
-  canResend: boolean;
-  attemptsRemaining: number;
-};
-
-/** OTP code is being verified against the backend */
-export type PhoneVerifyingOtpState = {
-  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 PhoneOtpErrorState = {
-  status: 'otpError';
-  error: string;
-  attemptsRemaining: number;
-};
-
-/** Phone verification completed successfully - call `reset()` to start over */
-export type PhoneSuccessState = {
-  status: 'success';
-};
-
-/**
- * Fatal error occurred - call `reset()` to start over
- * @property error - Error message describing what went wrong
- */
-export type PhoneErrorState = {
-  status: 'error';
-  error: string;
-};
-
-/**
- * Union of all possible phone manager states.
- * Use discriminated union pattern to narrow the type:
- *
- * @example
- * ```typescript
- * const state = phoneManager.getState();
- * if (state.status === 'inputting') {
- *   // TypeScript knows state has countryCode, phonePrefix, etc.
- *   console.log(state.countryCode);
- * }
- * ```
- */
-export type PhoneState =
-  | PhoneIdleState
-  | PhoneLoadingPrefillState
-  | PhoneInputtingState
-  | PhoneSubmittingState
-  | PhoneSendingOtpState
-  | PhoneAwaitingOtpState
-  | PhoneVerifyingOtpState
-  | PhoneOtpErrorState
-  | PhoneSuccessState
-  | PhoneErrorState;
-
-function mapState(snapshot: PhoneSnapshot): PhoneState {
-  // Type assertion needed because PhoneMachine uses 'as any' for declaration file generation
-  const typedSnapshot = snapshot as PhoneSnapshot & {
-    matches: (state: string) => boolean;
-    context: {
-      countryCode: string;
-      phonePrefix: string;
-      prefilledPhone?: string;
-      phoneError?: 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('loadingStartInfo')) {
-    return {
-      status: 'inputting',
-      countryCode: context.countryCode,
-      phonePrefix: context.phonePrefix,
-      prefilledPhone: context.prefilledPhone,
-    };
-  }
-
-  if (typedSnapshot.matches('inputting')) {
-    return {
-      status: 'inputting',
-      countryCode: context.countryCode,
-      phonePrefix: context.phonePrefix,
-      prefilledPhone: context.prefilledPhone,
-      phoneError: context.phoneError,
-    };
-  }
-
-  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<PhoneMachine>) {
-  return {
-    /**
-     * Initializes the phone verification flow.
-     * Transitions from 'idle' to 'loadingPrefill' or 'inputting'.
-     * Must be called before any other method.
-     */
-    load() {
-      actor.send({ type: 'LOAD' });
-    },
-
-    /**
-     * Sets the phone number for verification.
-     * Should be called when state is 'inputting'.
-     *
-     * @param phone - Full phone number with country code (e.g., '+14155551234')
-     * @param isValid - Whether the phone number passes validation
-     *
-     * @example
-     * ```typescript
-     * // Using libphonenumber-js for validation
-     * import { isValidPhoneNumber } from 'libphonenumber-js';
-     * const phone = '+14155551234';
-     * phoneManager.setPhoneNumber(phone, isValidPhoneNumber(phone));
-     * ```
-     */
-    setPhoneNumber(phone: string, isValid: boolean) {
-      actor.send({ type: 'PHONE_CHANGED', phone, isValid });
-    },
-
-    /**
-     * Sets the marketing opt-in preference.
-     * Only relevant if `config.optinEnabled` is true.
-     *
-     * @param granted - Whether the user consented to receive marketing messages
-     */
-    setOptInGranted(granted: boolean) {
-      actor.send({ type: 'OPT_IN_CHANGED', granted });
-    },
-
-    /**
-     * Submits the phone number for verification.
-     * Requires a valid phone number to be set via `setPhoneNumber()`.
-     * 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
-     * phoneManager.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 phone input screen from OTP entry.
-     * Allows the user to change their phone number.
-     * 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 phone number and OTP.
-     */
-    reset() {
-      actor.send({ type: 'RESET' });
-    },
-  };
-}
-
-/**
- * Creates a phone verification manager for headless or UI-driven usage.
- *
- * The manager provides a state machine-based API for phone number verification
- * with optional OTP (one-time password) verification.
- *
- * @param options - Configuration options
- * @param options.config - Phone 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 phone number
- * @param options.config.isInstantVerify - Use instant verification API
- * @param options.config.optinEnabled - Show marketing opt-in checkbox
- * @param options.config.maxOtpAttempts - Maximum OTP verification attempts (default: 3)
- *
- * @returns Phone manager with state, API methods, and subscription
- *
- * @example Headless usage
- * ```typescript
- * const manager = createPhoneManager({
- *   config: { otpVerification: true, otpExpirationInMinutes: 5, prefill: false },
- * });
- *
- * manager.subscribe((state) => console.log(state.status));
- * manager.load();
- * manager.setPhoneNumber('+14155551234', true);
- * manager.submit();
- * // ... wait for 'awaitingOtp' state ...
- * manager.submitOtp('ABC123');
- * manager.stop();
- * ```
- *
- * @example With React/Preact UI hook
- * ```tsx
- * const [state, manager] = useManager(() => createPhoneManager({ config }));
- *
- * if (state.status === 'inputting') {
- *   return <input onChange={(e) => manager.setPhoneNumber(e.target.value, true)} />;
- * }
- * ```
- */
-export function createPhoneManager(options: CreatePhoneActorOptions) {
-  const actor = createPhoneActor(options);
-  return createManager({ actor, mapState, createApi });
-}
-
-/**
- * Type representing a phone manager instance.
- * Includes state access, API methods, and lifecycle management.
- *
- * @property getState - Returns the current PhoneState
- * @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 setPhoneNumber - Sets the phone number
- * @property setOptInGranted - Sets marketing opt-in preference
- * @property submit - Submits the phone number
- * @property setOtpCode - Sets OTP code without submitting
- * @property submitOtp - Sets and submits OTP code
- * @property resendOtp - Requests new OTP code
- * @property back - Returns to phone input from OTP screen
- * @property reset - Resets to initial state
- */
-export type PhoneManager = ReturnType<typeof createPhoneManager>;

package/src/phone/phoneServices.ts

@@ -1,98 +0,0 @@
-import { api } from '../http/api';
-import { endpoints } from '../http/endpoints';
-import type {
-  AddPhoneParams,
-  AddPhoneResponse,
-  StartInfo,
-  VerifyOtpResponse,
-} from './types';
-
-export async function fetchPhone(
-  signal?: AbortSignal,
-): Promise<{ phone: string }> {
-  const res = await api.get<{ phone: string }>(endpoints.getPhone, { signal });
-  if (!res.ok) {
-    throw new Error(
-      `GET ${endpoints.getPhone} failed: ${res.status} ${res.statusText}`,
-    );
-  }
-  return res.data as { phone: string };
-}
-
-export async function fetchStartInfo(signal?: AbortSignal): Promise<StartInfo> {
-  const res = await api.get<StartInfo>(endpoints.startInfo, { signal });
-  if (!res.ok) {
-    throw new Error(
-      `GET ${endpoints.startInfo} failed: ${res.status} ${res.statusText}`,
-    );
-  }
-  return res.data as StartInfo;
-}
-
-export async function addPhone(
-  params: AddPhoneParams,
-  signal?: AbortSignal,
-): Promise<AddPhoneResponse> {
-  const res = await api.post<AddPhoneResponse>(
-    endpoints.phone,
-    {
-      phone: params.phone,
-      optInGranted: params.optInGranted,
-    },
-    { signal },
-  );
-  if (!res.ok) {
-    throw new Error(
-      `POST ${endpoints.phone} failed: ${res.status} ${res.statusText}`,
-    );
-  }
-  return res.data as AddPhoneResponse;
-}
-
-export async function addPhoneInstantVerify(
-  params: AddPhoneParams,
-  signal?: AbortSignal,
-): Promise<AddPhoneResponse> {
-  const res = await api.post<AddPhoneResponse>(
-    endpoints.phoneInstant,
-    {
-      phone: params.phone,
-      optInGranted: params.optInGranted,
-    },
-    { signal },
-  );
-  if (!res.ok) {
-    throw new Error(
-      `POST ${endpoints.phoneInstant} failed: ${res.status} ${res.statusText}`,
-    );
-  }
-  return res.data as AddPhoneResponse;
-}
-
-export async function sendOtp(signal?: AbortSignal): Promise<void> {
-  const res = await api.get(
-    `${endpoints.sendSmsOtp}?communicationchannel=SMS`,
-    { signal },
-  );
-  if (!res.ok) {
-    throw new Error(
-      `GET ${endpoints.sendSmsOtp} failed: ${res.status} ${res.statusText}`,
-    );
-  }
-}
-
-export async function verifyOtp(
-  code: string,
-  signal?: AbortSignal,
-): Promise<VerifyOtpResponse> {
-  const res = await api.get<VerifyOtpResponse>(
-    `${endpoints.compareOtp}?code=${code}&channel=SMS`,
-    { signal },
-  );
-  if (!res.ok) {
-    throw new Error(
-      `GET ${endpoints.compareOtp} failed: ${res.status} ${res.statusText}`,
-    );
-  }
-  return res.data as VerifyOtpResponse;
-}