@incodetech/core 2.0.0-alpha.8 → 2.0.0-rc.0

package/dist/emailManager-DIfnS5g1.d.ts

@@ -0,0 +1,352 @@
+import { t as Manager } from "./Manager-C8PrhBOx.js";
+import { t as ActorRefFrom } from "./Actor-CI32dTbG.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.
+   * @default false
+   */
+  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
+ * @property otpVerification - Whether OTP email verification is enabled (from module config). When omitted, treat as `false`.
+ */
+type EmailInputtingState = {
+  status: 'inputting';
+  prefilledEmail?: string;
+  emailError?: string;
+  otpVerification?: boolean;
+};
+/** Email address is being submitted to the backend */
+type EmailSubmittingState = {
+  status: 'submitting';
+};
+/** OTP is being sent to the email address */
+type EmailResendingOtpState = {
+  status: 'resendingOtp';
+};
+/** OTP is being sent initialy to the email address */
+type EmailSendingInitialOtpState = {
+  status: 'sendingInitialOtp';
+};
+/**
+ * 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
+ * @property resendTimer - Seconds remaining on resend cooldown (unchanged while verifying)
+ * @property canResend - Whether resend is allowed (cooldown finished)
+ */
+type EmailVerifyingOtpState = {
+  status: 'verifyingOtp';
+  resendTimer: number;
+  canResend: boolean;
+};
+/**
+ * OTP verification failed - user can retry with `submitOtp()`
+ * @property error - Error message describing why verification failed
+ * @property attemptsRemaining - Number of remaining attempts before lockout
+ * @property resendTimer - Seconds remaining on resend cooldown (same as awaiting OTP)
+ * @property canResend - Whether resend is allowed (cooldown finished)
+ */
+type EmailOtpErrorState = {
+  status: 'otpError';
+  otpError: string;
+  attemptsRemaining: number;
+  resendTimer: number;
+  canResend: boolean;
+};
+/** 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 | EmailResendingOtpState | EmailSendingInitialOtpState | 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@]{2,}$/;
+   * 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 'sendingInitialOtp' 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@]{2,}$/;
+   * 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 'sendingInitialOtp' 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 };

package/dist/emailManager-wAV0LE-H.esm.js

@@ -0,0 +1,238 @@
+import { n as eventModuleNames, o as createManagerInstrumentation } from "./events-D6-e4vok.esm.js";
+import { c as createManager, s as createActor } from "./xstate.esm-B70JrNqo.esm.js";
+import { t as emailMachine } from "./emailStateMachine-DOf4j58N.esm.js";
+
+//#region src/modules/email/emailActor.ts
+function createEmailActor(options) {
+	return createActor(emailMachine, { input: { config: options.config } }).start();
+}
+
+//#endregion
+//#region src/modules/email/emailManager.ts
+/**
+* @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 === 'finished') {
+*     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 'finished':
+*       clearInterval(interval);
+*       emailManager.stop();
+*       break;
+*     case 'error':
+*       clearInterval(interval);
+*       console.error(state.error);
+*       emailManager.stop();
+*       break;
+*   }
+* }, 100);
+* ```
+*/
+function mapState(snapshot) {
+	const typedSnapshot = snapshot;
+	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,
+		otpVerification: context.config.otpVerification
+	};
+	if (typedSnapshot.matches("submitting")) return { status: "submitting" };
+	if (typedSnapshot.matches("resendingOtp")) return { status: "resendingOtp" };
+	if (typedSnapshot.matches("sendingInitialOtp")) return { status: "sendingInitialOtp" };
+	if (typedSnapshot.matches("awaitingOtp")) return {
+		status: "awaitingOtp",
+		resendTimer: context.resendTimer,
+		canResend: !context.resendTimerActive,
+		attemptsRemaining: context.attemptsRemaining
+	};
+	if (typedSnapshot.matches("verifyingOtp")) return {
+		status: "verifyingOtp",
+		resendTimer: context.resendTimer,
+		canResend: !context.resendTimerActive
+	};
+	if (typedSnapshot.matches("otpError")) return {
+		status: "otpError",
+		otpError: context.otpError ?? "Invalid OTP code",
+		attemptsRemaining: context.attemptsRemaining,
+		resendTimer: context.resendTimer,
+		canResend: !context.resendTimerActive
+	};
+	if (typedSnapshot.matches("finished")) return { status: "finished" };
+	if (typedSnapshot.matches("error")) return {
+		status: "error",
+		error: context.error ?? "An error occurred"
+	};
+	return { status: "idle" };
+}
+function createApi({ actor, trackElementClicked }) {
+	return {
+		load() {
+			actor.send({ type: "LOAD" });
+		},
+		setEmail(email, isValid) {
+			actor.send({
+				type: "EMAIL_CHANGED",
+				email,
+				isValid
+			});
+		},
+		submit() {
+			trackElementClicked?.("submit");
+			actor.send({ type: "SUBMIT" });
+		},
+		setOtpCode(code) {
+			actor.send({
+				type: "OTP_CHANGED",
+				code
+			});
+		},
+		submitOtp(code) {
+			trackElementClicked?.("submitOtp");
+			actor.send({
+				type: "OTP_CHANGED",
+				code
+			});
+			actor.send({ type: "VERIFY_OTP" });
+		},
+		resendOtp() {
+			trackElementClicked?.("resendOtp");
+			actor.send({ type: "RESEND_OTP" });
+		},
+		back() {
+			trackElementClicked?.("back");
+			actor.send({ type: "BACK" });
+		},
+		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)} />;
+* }
+* ```
+*/
+function createEmailManager(options) {
+	return createManager({
+		actor: createEmailActor(options),
+		mapState,
+		createApi,
+		instrumentation: createManagerInstrumentation(eventModuleNames.email)
+	});
+}
+function createEmailManagerFromActor(actor) {
+	return createManager({
+		actor,
+		mapState,
+		createApi,
+		instrumentation: createManagerInstrumentation(eventModuleNames.email)
+	});
+}
+
+//#endregion
+export { createEmailManagerFromActor as n, createEmailManager as t };