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

package/dist/chunk-C_Yo44FK.esm.js

@@ -0,0 +1,49 @@
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __esm = (fn, res) => function() {
+	return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __commonJS = (cb, mod) => function() {
+	return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+};
+var __export = (all, symbols) => {
+	let target = {};
+	for (var name in all) {
+		__defProp(target, name, {
+			get: all[name],
+			enumerable: true
+		});
+	}
+	if (symbols) {
+		__defProp(target, Symbol.toStringTag, { value: "Module" });
+	}
+	return target;
+};
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") {
+		for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+			key = keys[i];
+			if (!__hasOwnProp.call(to, key) && key !== except) {
+				__defProp(to, key, {
+					get: ((k) => from[k]).bind(null, key),
+					enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+				});
+			}
+		}
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+var __toCommonJS = (mod) => __hasOwnProp.call(mod, "module.exports") ? mod["module.exports"] : __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var __toDynamicImportESM = (isNodeMode) => (mod) => __toESM(mod.default, isNodeMode);
+
+//#endregion
+export { __toDynamicImportESM as a, __toCommonJS as i, __esm as n, __export as r, __commonJS as t };

package/dist/email.d.ts

@@ -0,0 +1,264 @@
+import { t as Manager } from "./Manager-6BwbaI_H.js";
+
+//#region src/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/email/emailStateMachine.d.ts
+
+declare const emailMachine: any;
+//#endregion
+//#region src/email/emailActor.d.ts
+type CreateEmailActorOptions = {
+  config: EmailConfig;
+};
+//#endregion
+//#region src/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 - call `reset()` to start over */
+type EmailSuccessState = {
+  status: 'success';
+};
+/**
+ * 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 | EmailSuccessState | 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;
+};
+/**
+ * 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 { type EmailConfig, type EmailManager, type EmailState, createEmailManager, emailMachine };