@incodetech/core 0.0.0-dev-20260313-486e658 → 0.0.0-dev-20260313-bc2dab4

package/dist/emailManager-DZeOYBQ6.d.ts

@@ -0,0 +1,335 @@
+import { t as Manager } from "./Manager-CXnC-tN_.js";
+import { t as ActorRefFrom } from "./Actor-BAf9LRYf.js";
+
+//#region src/modules/email/types.d.ts
+
+/**
+ * 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,
+ * };
+ * ```
+ */
+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;
+};
+//#endregion
+//#region src/modules/email/emailStateMachine.d.ts
+
+declare const emailMachine: any;
+type EmailMachine = typeof emailMachine;
+//#endregion
+//#region src/modules/email/emailActor.d.ts
+type CreateEmailActorOptions = {
+  config: EmailConfig;
+};
+type EmailActor = ActorRefFrom<EmailMachine>;
+//#endregion
+//#region src/modules/email/emailManager.d.ts
+/** Email manager is in initial state, waiting for `load()` to be called */
+type EmailIdleState = {
+  status: 'idle';
+};
+/** Loading prefilled email address from backend (if prefill is enabled) */
+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
+ */
+type EmailInputtingState = {
+  status: 'inputting';
+  prefilledEmail?: string;
+  emailError?: string;
+};
+/** Email address is being submitted to the backend */
+type EmailSubmittingState = {
+  status: 'submitting';
+};
+/** OTP is being sent to the email address */
+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
+ */
+type EmailAwaitingOtpState = {
+  status: 'awaitingOtp';
+  resendTimer: number;
+  canResend: boolean;
+  attemptsRemaining: number;
+};
+/** OTP code is being verified against the backend */
+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
+ */
+type EmailOtpErrorState = {
+  status: 'otpError';
+  error: string;
+  attemptsRemaining: number;
+};
+/** Email verification completed successfully */
+type EmailFinishedState = {
+  status: 'finished';
+};
+/**
+ * Fatal error occurred - call `reset()` to start over
+ * @property error - Error message describing what went wrong
+ */
+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);
+ * }
+ * ```
+ */
+type EmailState = EmailIdleState | EmailLoadingPrefillState | EmailInputtingState | EmailSubmittingState | EmailSendingOtpState | EmailAwaitingOtpState | EmailVerifyingOtpState | EmailOtpErrorState | EmailFinishedState | EmailErrorState;
+/**
+ * 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)} />;
+ * }
+ * ```
+ */
+declare function createEmailManager(options: CreateEmailActorOptions): Manager<EmailState> & {
+  /**
+   * Initializes the email verification flow.
+   * Transitions from 'idle' to 'loadingPrefill' or 'inputting'.
+   * Must be called before any other method.
+   */
+  load(): void;
+  /**
+   * 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): void;
+  /**
+   * 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(): void;
+  /**
+   * Sets the OTP code without submitting.
+   * Use this for controlled input components.
+   *
+   * @param code - The OTP code entered by the user
+   */
+  setOtpCode(code: string): void;
+  /**
+   * 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): void;
+  /**
+   * Requests a new OTP code to be sent.
+   * Only works when state is 'awaitingOtp' and `canResend` is true.
+   * Resets the resend timer.
+   */
+  resendOtp(): void;
+  /**
+   * 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(): void;
+  /**
+   * 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(): void;
+};
+declare function createEmailManagerFromActor(actor: EmailActor): Manager<EmailState> & {
+  /**
+   * Initializes the email verification flow.
+   * Transitions from 'idle' to 'loadingPrefill' or 'inputting'.
+   * Must be called before any other method.
+   */
+  load(): void;
+  /**
+   * 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): void;
+  /**
+   * 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(): void;
+  /**
+   * Sets the OTP code without submitting.
+   * Use this for controlled input components.
+   *
+   * @param code - The OTP code entered by the user
+   */
+  setOtpCode(code: string): void;
+  /**
+   * 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): void;
+  /**
+   * Requests a new OTP code to be sent.
+   * Only works when state is 'awaitingOtp' and `canResend` is true.
+   * Resets the resend timer.
+   */
+  resendOtp(): void;
+  /**
+   * 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(): void;
+  /**
+   * 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(): void;
+};
+/**
+ * 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
+ */
+type EmailManager = ReturnType<typeof createEmailManager>;
+//#endregion
+export { emailMachine as a, createEmailManagerFromActor as i, EmailState as n, EmailConfig as o, createEmailManager as r, EmailManager as t };