@auth0/auth0-acul-react 1.0.0-alpha.0

package/dist/hooks/common/current-screen.d.ts

@@ -0,0 +1,75 @@
+import { type CurrentScreenOptions } from '@auth0/auth0-acul-js';
+/**
+ * React hook that gets the current screen context and state.
+ *
+ * This hook provides access to client configuration, organization details, screen identification,
+ * tenant settings, transaction state, and authorization parameters for building custom authentication UI.
+ *
+ * ## Return Value
+ *
+ * Returns `CurrentScreenOptions` object with the following properties, or `null` if unavailable:
+ *
+ * - **`client`** - Application identifier and metadata
+ * - **`organization`** - Organization ID and metadata (for Auth0 Organizations)
+ * - **`prompt`** - Current prompt name (e.g., "login", "consent", "mfa")
+ * - **`screen`** - Current screen name (e.g., "login-id", "login-password", "mfa-otp-challenge")
+ * - **`tenant`** - Tenant configuration including enabled locales
+ * - **`transaction`** - Transaction state, errors array, and current locale
+ * - **`untrustedData`** - Authorization parameters from the client (validate before use)
+ *
+ * ## Key Points
+ *
+ * - Use `screen.name` for conditional rendering of authentication screens
+ * - Always use optional chaining (`?.`) as nested properties can be `null`
+ * - Check `transaction.errors` for displaying validation errors
+ * - Access `organization.metadata` for organization-specific branding
+ *
+ * @returns {CurrentScreenOptions | null} Current screen context data, or `null` if not available
+ *
+ * @example
+ * Basic screen routing
+ * ```tsx
+ * import { useCurrentScreen } from '@auth0/auth0-acul-react';
+ *
+ * const AuthFlow = () => {
+ *   const screenOptions = useCurrentScreen();
+ *   const screen = screenOptions?.screen?.name || "login-id";
+ *
+ *   switch (screen) {
+ *     case "login-id":
+ *       return <LoginIdScreen />;
+ *     case "login-password":
+ *       return <LoginPasswordScreen />;
+ *     case "mfa-otp-challenge":
+ *       return <MfaOtpChallengeScreen />;
+ *     default:
+ *       return null;
+ *   }
+ * };
+ * ```
+ *
+ * @example
+ * Accessing multiple properties
+ * ```tsx
+ * import { useCurrentScreen } from '@auth0/auth0-acul-react';
+ *
+ * const CustomAuthScreen = () => {
+ *   const screenOptions = useCurrentScreen();
+ *   const organizationId = screenOptions?.organization?.id;
+ *   const errors = screenOptions?.transaction?.errors || [];
+ *   const locale = screenOptions?.transaction?.locale || 'en';
+ *
+ *   return (
+ *     <div>
+ *       {organizationId && <p>Organization: {organizationId}</p>}
+ *       {errors.map((error, i) => (
+ *         <p key={i} className="error">{error.message}</p>
+ *       ))}
+ *       <p>Language: {locale}</p>
+ *     </div>
+ *   );
+ * };
+ * ```
+ *
+ */
+export declare const useCurrentScreen: () => CurrentScreenOptions | null;

package/dist/hooks/common/current-screen.js

@@ -0,0 +1,2 @@
+import{getCurrentScreenOptions as t}from"@auth0/auth0-acul-js";const o=()=>t();export{o as useCurrentScreen};
+//# sourceMappingURL=current-screen.js.map

package/dist/hooks/common/current-screen.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"current-screen.js","sources":["../../../src/hooks/common/current-screen.ts"],"sourcesContent":["import { getCurrentScreenOptions, type CurrentScreenOptions } from '@auth0/auth0-acul-js';\n\n/**\n * React hook that gets the current screen context and state.\n *\n * This hook provides access to client configuration, organization details, screen identification,\n * tenant settings, transaction state, and authorization parameters for building custom authentication UI.\n *\n * ## Return Value\n *\n * Returns `CurrentScreenOptions` object with the following properties, or `null` if unavailable:\n *\n * - **`client`** - Application identifier and metadata\n * - **`organization`** - Organization ID and metadata (for Auth0 Organizations)\n * - **`prompt`** - Current prompt name (e.g., \"login\", \"consent\", \"mfa\")\n * - **`screen`** - Current screen name (e.g., \"login-id\", \"login-password\", \"mfa-otp-challenge\")\n * - **`tenant`** - Tenant configuration including enabled locales\n * - **`transaction`** - Transaction state, errors array, and current locale\n * - **`untrustedData`** - Authorization parameters from the client (validate before use)\n *\n * ## Key Points\n *\n * - Use `screen.name` for conditional rendering of authentication screens\n * - Always use optional chaining (`?.`) as nested properties can be `null`\n * - Check `transaction.errors` for displaying validation errors\n * - Access `organization.metadata` for organization-specific branding\n *\n * @returns {CurrentScreenOptions | null} Current screen context data, or `null` if not available\n *\n * @example\n * Basic screen routing\n * ```tsx\n * import { useCurrentScreen } from '@auth0/auth0-acul-react';\n *\n * const AuthFlow = () => {\n *   const screenOptions = useCurrentScreen();\n *   const screen = screenOptions?.screen?.name || \"login-id\";\n *\n *   switch (screen) {\n *     case \"login-id\":\n *       return <LoginIdScreen />;\n *     case \"login-password\":\n *       return <LoginPasswordScreen />;\n *     case \"mfa-otp-challenge\":\n *       return <MfaOtpChallengeScreen />;\n *     default:\n *       return null;\n *   }\n * };\n * ```\n *\n * @example\n * Accessing multiple properties\n * ```tsx\n * import { useCurrentScreen } from '@auth0/auth0-acul-react';\n *\n * const CustomAuthScreen = () => {\n *   const screenOptions = useCurrentScreen();\n *   const organizationId = screenOptions?.organization?.id;\n *   const errors = screenOptions?.transaction?.errors || [];\n *   const locale = screenOptions?.transaction?.locale || 'en';\n *\n *   return (\n *     <div>\n *       {organizationId && <p>Organization: {organizationId}</p>}\n *       {errors.map((error, i) => (\n *         <p key={i} className=\"error\">{error.message}</p>\n *       ))}\n *       <p>Language: {locale}</p>\n *     </div>\n *   );\n * };\n * ```\n *\n */\nexport const useCurrentScreen = (): CurrentScreenOptions | null => {\n  return getCurrentScreenOptions();\n};\n"],"names":["useCurrentScreen","getCurrentScreenOptions"],"mappings":"+DA2EO,MAAMA,EAAmB,IACvBC"}

package/dist/hooks/common/errors.d.ts

@@ -0,0 +1,103 @@
+import { type ErrorItem, type ErrorKind } from '../../state/error-store';
+export interface ErrorsResult extends ReadonlyArray<ErrorItem> {
+    byKind(kind: ErrorKind, opts?: {
+        field?: string;
+    }): ReadonlyArray<ErrorItem>;
+    byField(field: string, opts?: {
+        kind?: ErrorKind;
+    }): ReadonlyArray<ErrorItem>;
+}
+export interface UseErrorOptions {
+    includeDevErrors?: boolean;
+}
+export interface UseErrorsResult {
+    errors: ErrorsResult;
+    hasError: boolean;
+    dismiss: (id: string) => void;
+    dismissAll: () => void;
+}
+/**
+ * React hook for reading and managing errors in ACUL (Advanced Customization of Universal Login).
+ * With all validation and server-side errors. It groups errors into three kinds:
+ * - `server` — errors returned by Auth0 or your own backend.
+ * - `client` — errors from client-side validation (e.g., invalid form input).
+ * - `developer` — errors caused by incorrect integration or SDK misuse.
+ *
+ * @supportedScreens
+ * - The `useErrors` hook is available on every ACUL screen.
+ *
+ * @param options.includeDevErrors - When `true`, developer errors are included in
+ *   the returned list. Defaults to `false`.
+ *
+ * @returns An object of type {@link UseErrorsResult}, containing:
+ * - `errors` — the full error list of type {@link ErrorsResult}, with helpers:
+ *   - `errors.byKind(kind, filter?)` — filter by error kind and optionally by field.
+ *   - `errors.byField(field, filter?)` — filter by field and optionally by kind.
+ * - `hasError` — `true` if any error is currently present.
+ * - `dismiss(id)` — remove a specific error by its ID.
+ * - `dismissAll()` — clear all tracked errors.
+ *
+ * Typical usage is inside a form or screen component where you need to
+ * reactively display errors and provide ways to dismiss them:
+ *
+ * @example
+ * ```tsx
+ * import { useErrors } from "@auth0/auth0-acul-react";
+ *
+ * export function SignupForm() {
+ *   const { errors, hasError, dismiss, dismissAll } = useErrors();
+ *
+ *   return (
+ *     <div>
+ *       {hasError && (
+ *         <div className="mb-4">
+ *           {errors.byKind("server").map(err => (
+ *             <div key={err.id} className="text-red-600">
+ *               {err.message}
+ *               <button onClick={() => dismiss(err.id)}>Dismiss</button>
+ *             </div>
+ *           ))}
+ *         </div>
+ *       )}
+ *
+ *       <button onClick={dismissAll}>Clear All Errors</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * In addition to rendering messages, you can filter by field or kind:
+ * ```ts
+ * console.log(errors.byKind('client')); // all client errors
+ * console.log(errors.byKind('client', { field: 'username' })); // client errors for field 'username'
+ * console.log(errors.byField('username')); // all errors for field 'username'
+ * console.log(errors.byField('username', { kind: 'server' })); // server errors for field 'username'
+ * ```
+ */
+export declare function useErrors(options?: UseErrorOptions): UseErrorsResult;
+declare function withError<T>(actionOrPromise: (() => T | Promise<T>) | Promise<T>): T | Promise<T>;
+/**
+ * @hidden
+ * Internal error manager for use by SDK methods.
+ * Use the `useErrors` hook in React components instead.
+ */
+export declare const errorManager: {
+    withError: typeof withError;
+    replaceClientErrors(list: Array<Omit<ErrorItem, "id">>, opts?: {
+        byField?: string;
+    }): void;
+    clearClientErrors(): void;
+    pushClientErrors(list: Omit<ErrorItem, "id"> | Array<Omit<ErrorItem, "id">>): void;
+    replaceDeveloperErrors(list: Array<Omit<ErrorItem, "id">>, opts?: {
+        byField?: string;
+    }): void;
+    clearDeveloperErrors(): void;
+    pushDeveloperErrors(list: Omit<ErrorItem, "id"> | Array<Omit<ErrorItem, "id">>): void;
+    replaceServerErrors(list: Array<Omit<ErrorItem, "id">>, opts?: {
+        byField?: string;
+    }): void;
+    clearServerErrors(): void;
+    pushServerErrors(list: Omit<ErrorItem, "id"> | Array<Omit<ErrorItem, "id">>): void;
+    syncServerErrors(): void;
+};
+export { ErrorItem, ErrorKind };

package/dist/hooks/common/errors.js

@@ -0,0 +1,2 @@
+import{getErrors as e,UserInputError as r,SDKUsageError as t,Auth0ServerError as n}from"@auth0/auth0-acul-js";import{useSyncExternalStore as c,useRef as o,useEffect as l,useMemo as s,useCallback as i}from"react";import{errorStore as a,ERROR_KINDS as p}from"../../state/error-store.js";function d(e,r){return r?e.filter(e=>e.field===r):e}const u=new WeakMap,v=new WeakMap,f=new WeakMap,h=(e,r)=>{const t="server"===e?u:"client"===e?v:f,n=t.get(r);if(n)return n;const c=Object.freeze(r.map(r=>Object.freeze({...r,kind:e})));return t.set(r,c),c};function b(r={}){const{includeDevErrors:t=!1}=r,n=c(e=>a.subscribe(e),()=>a.snapshot()),u=o(!1);l(()=>{if(u.current)return;u.current=!0;const r=e?.()??[];a.replace("server",r)},[]);const v=s(()=>h("server",n.server),[n.server]),f=s(()=>h("client",n.client),[n.client]),b=s(()=>h("developer",n.developer),[n.developer]),E=s(()=>Object.freeze([...t?b:[],...f,...v]),[t,b,f,v]),y=s(()=>{const e=Object.assign([...E],{byKind(e,r){const t="client"===e?f:"developer"===e?b:v;return r?.field?Object.freeze(d(t,r.field)):t},byField:(r,t)=>t?.kind?e.byKind(t.kind,{field:r}):Object.freeze(d(E,r))});return Object.freeze(e)},[E,f,b,v]),m=E.length>0,k=i(e=>{a.remove(p,e)},[]),w=i(()=>{a.clear(p)},[]);return s(()=>({errors:y,hasError:m,dismiss:k,dismissAll:w}),[y,m,k,w])}const E={withError:function(e){const c=e=>{const c=function(e){return e instanceof r?"client":e instanceof t?"developer":e instanceof n?"server":null}(e),o=function(e){return{code:e?.code??(e instanceof Error?e.name:void 0)??"unknown_error",message:e?.message??"Unknown error",field:e?.field}}(e);switch(c){case"client":E.replaceClientErrors([o]);break;case"developer":E.replaceDeveloperErrors([o]);break;case"server":E.replaceServerErrors([o]);break;default:throw console.error("[auth0-acul-react] Unhandled error:",e),e}};if("function"==typeof e)try{const r=e();return"object"==typeof(o=r)&&null!==o&&"then"in o&&"function"==typeof o.then?r.catch(e=>{throw c(e),e}):r}catch(e){throw c(e),e}var o;return e.catch(e=>{throw c(e),e})},replaceClientErrors(e,r){r?.byField?a.replacePartial("client",e,r.byField):a.replace("client",e)},clearClientErrors(){a.clear(["client"])},pushClientErrors(e){a.push("client",e)},replaceDeveloperErrors(e,r){r?.byField?a.replacePartial("developer",e,r.byField):a.replace("developer",e)},clearDeveloperErrors(){a.clear(["developer"])},pushDeveloperErrors(e){a.push("developer",e)},replaceServerErrors(e,r){r?.byField?a.replacePartial("server",e,r.byField):a.replace("server",e)},clearServerErrors(){a.clear(["server"])},pushServerErrors(e){a.push("server",e)},syncServerErrors(){const r=e?.()??[];a.replace("server",r)}};export{E as errorManager,b as useErrors};
+//# sourceMappingURL=errors.js.map

package/dist/hooks/common/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sources":["../../../src/hooks/common/errors.ts"],"sourcesContent":["import {\n  SDKUsageError,\n  UserInputError,\n  Auth0ServerError,\n  getErrors as getServerErrors,\n  type Error as Auth0Error,\n} from '@auth0/auth0-acul-js';\nimport { useEffect, useMemo, useRef, useSyncExternalStore, useCallback } from 'react';\n\nimport { errorStore, ERROR_KINDS, type ErrorItem, type ErrorKind } from '../../state/error-store';\n\nexport interface ErrorsResult extends ReadonlyArray<ErrorItem> {\n  byKind(kind: ErrorKind, opts?: { field?: string }): ReadonlyArray<ErrorItem>;\n  byField(field: string, opts?: { kind?: ErrorKind }): ReadonlyArray<ErrorItem>;\n}\n\nexport interface UseErrorOptions {\n  includeDevErrors?: boolean;\n}\n\nexport interface UseErrorsResult {\n  errors: ErrorsResult;\n  hasError: boolean;\n  dismiss: (id: string) => void;\n  dismissAll: () => void;\n}\n\nfunction classifyKind(e: unknown): ErrorKind | null {\n  if (e instanceof UserInputError) {\n    return 'client';\n  }\n  if (e instanceof SDKUsageError) {\n    return 'developer';\n  }\n  if (e instanceof Auth0ServerError) {\n    return 'server';\n  }\n  return null;\n}\n\nfunction toErrorObject(e: unknown): Omit<ErrorItem, 'id'> {\n  return {\n    code: (e as Auth0Error)?.code ?? (e instanceof Error ? e.name : undefined) ?? 'unknown_error',\n    message: (e as Auth0Error)?.message ?? 'Unknown error',\n    field: (e as Auth0Error)?.field,\n  };\n}\n\nfunction filterByField<T extends { field?: string }>(\n  list: ReadonlyArray<T>,\n  field?: string\n): ReadonlyArray<T> {\n  if (!field) {\n    return list;\n  }\n  return list.filter((e) => e.field === field);\n}\n\n// caches for tagging\nconst cacheServer = new WeakMap<ReadonlyArray<ErrorItem>, ReadonlyArray<ErrorItem>>();\nconst cacheClient = new WeakMap<ReadonlyArray<ErrorItem>, ReadonlyArray<ErrorItem>>();\nconst cacheDev = new WeakMap<ReadonlyArray<ErrorItem>, ReadonlyArray<ErrorItem>>();\n\nconst tag = (kind: ErrorKind, arr: ReadonlyArray<ErrorItem>): ReadonlyArray<ErrorItem> => {\n  const cache = kind === 'server' ? cacheServer : kind === 'client' ? cacheClient : cacheDev;\n  const hit = cache.get(arr);\n  if (hit) {\n    return hit;\n  }\n  const out = Object.freeze(arr.map((e) => Object.freeze({ ...e, kind })));\n  cache.set(arr, out);\n  return out;\n};\n\n/**\n * React hook for reading and managing errors in ACUL (Advanced Customization of Universal Login).\n * With all validation and server-side errors. It groups errors into three kinds:\n * - `server` — errors returned by Auth0 or your own backend.\n * - `client` — errors from client-side validation (e.g., invalid form input).\n * - `developer` — errors caused by incorrect integration or SDK misuse.\n *\n * @supportedScreens\n * - The `useErrors` hook is available on every ACUL screen.\n *\n * @param options.includeDevErrors - When `true`, developer errors are included in\n *   the returned list. Defaults to `false`.\n *\n * @returns An object of type {@link UseErrorsResult}, containing:\n * - `errors` — the full error list of type {@link ErrorsResult}, with helpers:\n *   - `errors.byKind(kind, filter?)` — filter by error kind and optionally by field.\n *   - `errors.byField(field, filter?)` — filter by field and optionally by kind.\n * - `hasError` — `true` if any error is currently present.\n * - `dismiss(id)` — remove a specific error by its ID.\n * - `dismissAll()` — clear all tracked errors.\n *\n * Typical usage is inside a form or screen component where you need to\n * reactively display errors and provide ways to dismiss them:\n *\n * @example\n * ```tsx\n * import { useErrors } from \"@auth0/auth0-acul-react\";\n *\n * export function SignupForm() {\n *   const { errors, hasError, dismiss, dismissAll } = useErrors();\n *\n *   return (\n *     <div>\n *       {hasError && (\n *         <div className=\"mb-4\">\n *           {errors.byKind(\"server\").map(err => (\n *             <div key={err.id} className=\"text-red-600\">\n *               {err.message}\n *               <button onClick={() => dismiss(err.id)}>Dismiss</button>\n *             </div>\n *           ))}\n *         </div>\n *       )}\n *\n *       <button onClick={dismissAll}>Clear All Errors</button>\n *     </div>\n *   );\n * }\n * ```\n *\n * In addition to rendering messages, you can filter by field or kind:\n * ```ts\n * console.log(errors.byKind('client')); // all client errors\n * console.log(errors.byKind('client', { field: 'username' })); // client errors for field 'username'\n * console.log(errors.byField('username')); // all errors for field 'username'\n * console.log(errors.byField('username', { kind: 'server' })); // server errors for field 'username'\n * ```\n */\n\nexport function useErrors(options: UseErrorOptions = {}): UseErrorsResult {\n  const { includeDevErrors = false } = options;\n\n  const snap = useSyncExternalStore(\n    (cb) => errorStore.subscribe(cb),\n    () => errorStore.snapshot()\n  );\n\n  const didInit = useRef(false);\n  useEffect(() => {\n    if (didInit.current) {\n      return;\n    }\n    didInit.current = true;\n\n    // Get server errors directly from TS SDK on first render.\n    const server = (getServerErrors?.() ?? []) as Array<Omit<ErrorItem, 'id'>>;\n    errorStore.replace('server', server);\n  }, []);\n\n  const serverTagged = useMemo(() => tag('server', snap.server), [snap.server]);\n  const clientTagged = useMemo(() => tag('client', snap.client), [snap.client]);\n  const devTagged = useMemo(() => tag('developer', snap.developer), [snap.developer]);\n\n  const all = useMemo<ReadonlyArray<ErrorItem>>(\n    () => Object.freeze([...(includeDevErrors ? devTagged : []), ...clientTagged, ...serverTagged]),\n    [includeDevErrors, devTagged, clientTagged, serverTagged]\n  );\n\n  const errors: ErrorsResult = useMemo(() => {\n    const arr = Object.assign([...all], {\n      byKind(kind: ErrorKind, opts?: { field?: string }): ReadonlyArray<ErrorItem> {\n        const base =\n          kind === 'client' ? clientTagged : kind === 'developer' ? devTagged : serverTagged;\n        return opts?.field ? Object.freeze(filterByField(base, opts.field)) : base;\n      },\n      byField(field: string, opts?: { kind?: ErrorKind }): ReadonlyArray<ErrorItem> {\n        if (opts?.kind) {\n          return arr.byKind(opts.kind, { field });\n        }\n        return Object.freeze(filterByField(all, field));\n      },\n    });\n    return Object.freeze(arr);\n  }, [all, clientTagged, devTagged, serverTagged]);\n\n  const hasError = all.length > 0;\n\n  const dismiss = useCallback((id: string) => {\n    errorStore.remove(ERROR_KINDS, id);\n  }, []);\n\n  const dismissAll = useCallback(() => {\n    errorStore.clear(ERROR_KINDS);\n  }, []);\n\n  return useMemo(\n    () => ({ errors, hasError, dismiss, dismissAll }),\n    [errors, hasError, dismiss, dismissAll]\n  );\n}\n\n// ---------------- INTERNAL (SDK-only) ----------------\nconst isPromise = (v: unknown): v is Promise<unknown> =>\n  typeof v === 'object' &&\n  v !== null &&\n  'then' in v &&\n  typeof (v as { then: unknown }).then === 'function';\n\nfunction withError<T>(actionOrPromise: (() => T | Promise<T>) | Promise<T>): T | Promise<T> {\n  const handle = (e: unknown) => {\n    const kind = classifyKind(e);\n    const normalized = toErrorObject(e);\n    switch (kind) {\n      case 'client':\n        errorManager.replaceClientErrors([normalized]);\n        break;\n      case 'developer':\n        errorManager.replaceDeveloperErrors([normalized]);\n        break;\n      case 'server':\n        errorManager.replaceServerErrors([normalized]);\n        break;\n      default: {\n        console.error('[auth0-acul-react] Unhandled error:', e);\n        throw e;\n      }\n    }\n  };\n\n  if (typeof actionOrPromise === 'function') {\n    try {\n      const result = (actionOrPromise as () => T | Promise<T>)();\n      return isPromise(result)\n        ? result.catch((e) => {\n            handle(e);\n            throw e;\n          })\n        : result;\n    } catch (e) {\n      handle(e);\n      throw e;\n    }\n  }\n\n  return actionOrPromise.catch((e) => {\n    handle(e);\n    throw e;\n  });\n}\n\n/**\n * @hidden\n * Internal error manager for use by SDK methods.\n * Use the `useErrors` hook in React components instead.\n */\nexport const errorManager = {\n  withError,\n\n  replaceClientErrors(list: Array<Omit<ErrorItem, 'id'>>, opts?: { byField?: string }) {\n    if (opts?.byField) {\n      errorStore.replacePartial('client', list, opts.byField);\n    } else {\n      errorStore.replace('client', list);\n    }\n  },\n  clearClientErrors() {\n    errorStore.clear(['client']);\n  },\n  pushClientErrors(list: Omit<ErrorItem, 'id'> | Array<Omit<ErrorItem, 'id'>>) {\n    errorStore.push('client', list);\n  },\n\n  replaceDeveloperErrors(list: Array<Omit<ErrorItem, 'id'>>, opts?: { byField?: string }) {\n    if (opts?.byField) {\n      errorStore.replacePartial('developer', list, opts.byField);\n    } else {\n      errorStore.replace('developer', list);\n    }\n  },\n  clearDeveloperErrors() {\n    errorStore.clear(['developer']);\n  },\n  pushDeveloperErrors(list: Omit<ErrorItem, 'id'> | Array<Omit<ErrorItem, 'id'>>) {\n    errorStore.push('developer', list);\n  },\n\n  replaceServerErrors(list: Array<Omit<ErrorItem, 'id'>>, opts?: { byField?: string }) {\n    if (opts?.byField) {\n      errorStore.replacePartial('server', list, opts.byField);\n    } else {\n      errorStore.replace('server', list);\n    }\n  },\n  clearServerErrors() {\n    errorStore.clear(['server']);\n  },\n  pushServerErrors(list: Omit<ErrorItem, 'id'> | Array<Omit<ErrorItem, 'id'>>) {\n    errorStore.push('server', list);\n  },\n\n  syncServerErrors() {\n    const server = (getServerErrors?.() ?? []) as Array<Omit<ErrorItem, 'id'>>;\n    errorStore.replace('server', server);\n  },\n};\n\nexport { ErrorItem, ErrorKind };\n"],"names":["filterByField","list","field","filter","e","cacheServer","WeakMap","cacheClient","cacheDev","tag","kind","arr","cache","hit","get","out","Object","freeze","map","set","useErrors","options","includeDevErrors","snap","useSyncExternalStore","cb","errorStore","subscribe","snapshot","didInit","useRef","useEffect","current","server","getServerErrors","replace","serverTagged","useMemo","clientTagged","client","devTagged","developer","all","errors","assign","byKind","opts","base","byField","hasError","length","dismiss","useCallback","id","remove","ERROR_KINDS","dismissAll","clear","errorManager","withError","actionOrPromise","handle","UserInputError","SDKUsageError","Auth0ServerError","classifyKind","normalized","code","Error","name","undefined","message","toErrorObject","replaceClientErrors","replaceDeveloperErrors","replaceServerErrors","console","error","result","v","then","catch","replacePartial","clearClientErrors","pushClientErrors","push","clearDeveloperErrors","pushDeveloperErrors","clearServerErrors","pushServerErrors","syncServerErrors"],"mappings":"6RAgDA,SAASA,EACPC,EACAC,GAEA,OAAKA,EAGED,EAAKE,OAAQC,GAAMA,EAAEF,QAAUA,GAF7BD,CAGX,CAGA,MAAMI,EAAc,IAAIC,QAClBC,EAAc,IAAID,QAClBE,EAAW,IAAIF,QAEfG,EAAM,CAACC,EAAiBC,KAC5B,MAAMC,EAAiB,WAATF,EAAoBL,EAAuB,WAATK,EAAoBH,EAAcC,EAC5EK,EAAMD,EAAME,IAAIH,GACtB,GAAIE,EACF,OAAOA,EAET,MAAME,EAAMC,OAAOC,OAAON,EAAIO,IAAKd,GAAMY,OAAOC,OAAO,IAAKb,EAAGM,WAE/D,OADAE,EAAMO,IAAIR,EAAKI,GACRA,GA8DH,SAAUK,EAAUC,EAA2B,IACnD,MAAMC,iBAAEA,GAAmB,GAAUD,EAE/BE,EAAOC,EACVC,GAAOC,EAAWC,UAAUF,GAC7B,IAAMC,EAAWE,YAGbC,EAAUC,GAAO,GACvBC,EAAU,KACR,GAAIF,EAAQG,QACV,OAEFH,EAAQG,SAAU,EAGlB,MAAMC,EAAUC,OAAuB,GACvCR,EAAWS,QAAQ,SAAUF,IAC5B,IAEH,MAAMG,EAAeC,EAAQ,IAAM5B,EAAI,SAAUc,EAAKU,QAAS,CAACV,EAAKU,SAC/DK,EAAeD,EAAQ,IAAM5B,EAAI,SAAUc,EAAKgB,QAAS,CAAChB,EAAKgB,SAC/DC,EAAYH,EAAQ,IAAM5B,EAAI,YAAac,EAAKkB,WAAY,CAAClB,EAAKkB,YAElEC,EAAML,EACV,IAAMrB,OAAOC,OAAO,IAAKK,EAAmBkB,EAAY,MAAQF,KAAiBF,IACjF,CAACd,EAAkBkB,EAAWF,EAAcF,IAGxCO,EAAuBN,EAAQ,KACnC,MAAM1B,EAAMK,OAAO4B,OAAO,IAAIF,GAAM,CAClC,MAAAG,CAAOnC,EAAiBoC,GACtB,MAAMC,EACK,WAATrC,EAAoB4B,EAAwB,cAAT5B,EAAuB8B,EAAYJ,EACxE,OAAOU,GAAM5C,MAAQc,OAAOC,OAAOjB,EAAc+C,EAAMD,EAAK5C,QAAU6C,CACxE,EACAC,QAAO,CAAC9C,EAAe4C,IACjBA,GAAMpC,KACDC,EAAIkC,OAAOC,EAAKpC,KAAM,CAAER,UAE1Bc,OAAOC,OAAOjB,EAAc0C,EAAKxC,MAG5C,OAAOc,OAAOC,OAAON,IACpB,CAAC+B,EAAKJ,EAAcE,EAAWJ,IAE5Ba,EAAWP,EAAIQ,OAAS,EAExBC,EAAUC,EAAaC,IAC3B3B,EAAW4B,OAAOC,EAAaF,IAC9B,IAEGG,EAAaJ,EAAY,KAC7B1B,EAAW+B,MAAMF,IAChB,IAEH,OAAOlB,EACL,KAAA,CAASM,SAAQM,WAAUE,UAASK,eACpC,CAACb,EAAQM,EAAUE,EAASK,GAEhC,CAwDO,MAAME,EAAe,CAC1BC,UAhDF,SAAsBC,GACpB,MAAMC,EAAUzD,IACd,MAAMM,EAjLV,SAAsBN,GACpB,OAAIA,aAAa0D,EACR,SAEL1D,aAAa2D,EACR,YAEL3D,aAAa4D,EACR,SAEF,IACT,CAsKiBC,CAAa7D,GACpB8D,EArKV,SAAuB9D,GACrB,MAAO,CACL+D,KAAO/D,GAAkB+D,OAAS/D,aAAagE,MAAQhE,EAAEiE,UAAOC,IAAc,gBAC9EC,QAAUnE,GAAkBmE,SAAW,gBACvCrE,MAAQE,GAAkBF,MAE9B,CA+JuBsE,CAAcpE,GACjC,OAAQM,GACN,IAAK,SACHgD,EAAae,oBAAoB,CAACP,IAClC,MACF,IAAK,YACHR,EAAagB,uBAAuB,CAACR,IACrC,MACF,IAAK,SACHR,EAAaiB,oBAAoB,CAACT,IAClC,MACF,QAEE,MADAU,QAAQC,MAAM,sCAAuCzE,GAC/CA,IAKZ,GAA+B,mBAApBwD,EACT,IACE,MAAMkB,EAAUlB,IAChB,MA7BS,iBADImB,EA8BID,IA5Bf,OAANC,GACA,SAAUA,GAC+B,mBAAjCA,EAAwBC,KA2BxBF,EAAOG,MAAO7E,IAEZ,MADAyD,EAAOzD,GACDA,IAER0E,CACN,CAAE,MAAO1E,GAEP,MADAyD,EAAOzD,GACDA,CACR,CAvCc,IAAC2E,EA0CjB,OAAOnB,EAAgBqB,MAAO7E,IAE5B,MADAyD,EAAOzD,GACDA,GAEV,EAUE,mBAAAqE,CAAoBxE,EAAoC6C,GAClDA,GAAME,QACRtB,EAAWwD,eAAe,SAAUjF,EAAM6C,EAAKE,SAE/CtB,EAAWS,QAAQ,SAAUlC,EAEjC,EACA,iBAAAkF,GACEzD,EAAW+B,MAAM,CAAC,UACpB,EACA,gBAAA2B,CAAiBnF,GACfyB,EAAW2D,KAAK,SAAUpF,EAC5B,EAEA,sBAAAyE,CAAuBzE,EAAoC6C,GACrDA,GAAME,QACRtB,EAAWwD,eAAe,YAAajF,EAAM6C,EAAKE,SAElDtB,EAAWS,QAAQ,YAAalC,EAEpC,EACA,oBAAAqF,GACE5D,EAAW+B,MAAM,CAAC,aACpB,EACA,mBAAA8B,CAAoBtF,GAClByB,EAAW2D,KAAK,YAAapF,EAC/B,EAEA,mBAAA0E,CAAoB1E,EAAoC6C,GAClDA,GAAME,QACRtB,EAAWwD,eAAe,SAAUjF,EAAM6C,EAAKE,SAE/CtB,EAAWS,QAAQ,SAAUlC,EAEjC,EACA,iBAAAuF,GACE9D,EAAW+B,MAAM,CAAC,UACpB,EACA,gBAAAgC,CAAiBxF,GACfyB,EAAW2D,KAAK,SAAUpF,EAC5B,EAEA,gBAAAyF,GACE,MAAMzD,EAAUC,OAAuB,GACvCR,EAAWS,QAAQ,SAAUF,EAC/B"}

package/dist/hooks/context/index.d.ts

@@ -0,0 +1,120 @@
+import { type BaseMembers } from '@auth0/auth0-acul-js';
+/**
+ * Factory class that creates context hooks for accessing Auth0 Universal Login data.
+ * These hooks provide access to various aspects of the authentication flow and tenant configuration.
+ */
+export declare class ContextHooks<T extends BaseMembers> {
+    private instance;
+    constructor(instance: T);
+    /**
+     * Hook to access user information and profile data.
+     * @returns User object containing profile information, attributes, and user-specific data
+     * @example
+     * ```jsx
+     * import { useUser } from '@auth0/auth0-acul-react/login-id';
+     * function UserProfile() {
+     *   const user = useUser();
+     * }
+     * ```
+     */
+    useUser: () => T["user"];
+    /**
+     * Hook to access tenant configuration and settings.
+     * @returns Tenant object containing domain, region, and tenant-specific configuration
+     * @example
+     * ```jsx
+     * import { useTenant } from '@auth0/auth0-acul-react/login-id';
+     * function TenantInfo() {
+     *   const tenant = useTenant();
+     * }
+     * ```
+     */
+    useTenant: () => T["tenant"];
+    /**
+     * Hook to access branding and theme configuration.
+     * @returns Branding object containing colors, logos, fonts, and visual customization settings
+     * @example
+     * ```jsx
+     * import { useBranding } from '@auth0/auth0-acul-react/login-id';
+     * function CustomTheme() {
+     *   const branding = useBranding();
+     * }
+     * ```
+     */
+    useBranding: () => T["branding"];
+    /**
+     * Hook to access Auth0 application (client) configuration.
+     * @returns Client object containing application settings, callbacks, and client-specific data
+     * @example
+     * ```jsx
+     * import { useClient } from '@auth0/auth0-acul-react/login-id';
+     * function AppInfo() {
+     *   const client = useClient();
+     * }
+     * ```
+     */
+    useClient: () => T["client"];
+    /**
+     * Hook to access organization context and settings.
+     * @returns Organization object containing org-specific data, metadata, and configuration
+     * @example
+     * ```jsx
+     * import { useOrganization } from '@auth0/auth0-acul-react/login-id';
+     * function OrgSelector() {
+     *   const organization = useOrganization();
+     *   if (!organization) {
+     *     return <p>No organization context</p>;
+     *   }
+     * }
+     * ```
+     */
+    useOrganization: () => T["organization"];
+    /**
+     * Hook to access prompt configuration and flow settings.
+     * @returns Prompt object containing flow configuration, screen settings, and prompt-specific data
+     * @example
+     * ```jsx
+     * import { usePrompt } from '@auth0/auth0-acul-react/login-id';
+     * function FlowInfo() {
+     *   const prompt = usePrompt();
+     * }
+     * ```
+     */
+    usePrompt: () => T["prompt"];
+    /**
+     * Hook to access untrusted data from URL parameters and form submissions.
+     * @returns Object containing untrusted user input that should be validated before use
+     * @example
+     * ```jsx
+     * import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
+     * function PrefilledForm() {
+     *   const untrustedData = useUntrustedData();
+     * }
+     * ```
+     */
+    useUntrustedData: () => T["untrustedData"];
+    /**
+     * Hook to access current screen information and metadata.
+     * @returns Screen object containing current screen name, configuration, and screen-specific data
+     * @example
+     * ```jsx
+     * import { useScreen } from '@auth0/auth0-acul-react/login-id';
+     * function ScreenDebug() {
+     *   const screen = useScreen();
+     * }
+     * ```
+     */
+    useScreen: () => T["screen"];
+    /**
+     * Hook to access transaction state and authentication flow data.
+     * @returns Transaction object containing flow state, session data, and transaction-specific information
+     * @example
+     * ```jsx
+     * import { useTransaction } from '@auth0/auth0-acul-react/login-id';
+     * function TransactionInfo() {
+     *   const transaction = useTransaction();
+     * }
+     * ```
+     */
+    useTransaction: () => T["transaction"];
+}

package/dist/hooks/context/index.js

@@ -0,0 +1,2 @@
+class t{constructor(t){this.instance=t,this.useUser=()=>this.instance.user,this.useTenant=()=>this.instance.tenant,this.useBranding=()=>this.instance.branding,this.useClient=()=>this.instance.client,this.useOrganization=()=>this.instance.organization,this.usePrompt=()=>this.instance.prompt,this.useUntrustedData=()=>this.instance.untrustedData,this.useScreen=()=>this.instance.screen,this.useTransaction=()=>this.instance.transaction}}export{t as ContextHooks};
+//# sourceMappingURL=index.js.map

package/dist/hooks/context/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../../../src/hooks/context/index.tsx"],"sourcesContent":["import { type BaseMembers } from '@auth0/auth0-acul-js';\n\n/**\n * Factory class that creates context hooks for accessing Auth0 Universal Login data.\n * These hooks provide access to various aspects of the authentication flow and tenant configuration.\n */\nexport class ContextHooks<T extends BaseMembers> {\n  constructor(private instance: T) {}\n\n  /**\n   * Hook to access user information and profile data.\n   * @returns User object containing profile information, attributes, and user-specific data\n   * @example\n   * ```jsx\n   * import { useUser } from '@auth0/auth0-acul-react/login-id';\n   * function UserProfile() {\n   *   const user = useUser();\n   * }\n   * ```\n   */\n  useUser = () => this.instance.user as T['user'];\n\n  /**\n   * Hook to access tenant configuration and settings.\n   * @returns Tenant object containing domain, region, and tenant-specific configuration\n   * @example\n   * ```jsx\n   * import { useTenant } from '@auth0/auth0-acul-react/login-id';\n   * function TenantInfo() {\n   *   const tenant = useTenant();\n   * }\n   * ```\n   */\n  useTenant = () => this.instance.tenant as T['tenant'];\n\n  /**\n   * Hook to access branding and theme configuration.\n   * @returns Branding object containing colors, logos, fonts, and visual customization settings\n   * @example\n   * ```jsx\n   * import { useBranding } from '@auth0/auth0-acul-react/login-id';\n   * function CustomTheme() {\n   *   const branding = useBranding();\n   * }\n   * ```\n   */\n  useBranding = () => this.instance.branding as T['branding'];\n\n  /**\n   * Hook to access Auth0 application (client) configuration.\n   * @returns Client object containing application settings, callbacks, and client-specific data\n   * @example\n   * ```jsx\n   * import { useClient } from '@auth0/auth0-acul-react/login-id';\n   * function AppInfo() {\n   *   const client = useClient();\n   * }\n   * ```\n   */\n  useClient = () => this.instance.client as T['client'];\n\n  /**\n   * Hook to access organization context and settings.\n   * @returns Organization object containing org-specific data, metadata, and configuration\n   * @example\n   * ```jsx\n   * import { useOrganization } from '@auth0/auth0-acul-react/login-id';\n   * function OrgSelector() {\n   *   const organization = useOrganization();\n   *   if (!organization) {\n   *     return <p>No organization context</p>;\n   *   }\n   * }\n   * ```\n   */\n  useOrganization = () => this.instance.organization as T['organization'];\n\n  /**\n   * Hook to access prompt configuration and flow settings.\n   * @returns Prompt object containing flow configuration, screen settings, and prompt-specific data\n   * @example\n   * ```jsx\n   * import { usePrompt } from '@auth0/auth0-acul-react/login-id';\n   * function FlowInfo() {\n   *   const prompt = usePrompt();\n   * }\n   * ```\n   */\n  usePrompt = () => this.instance.prompt as T['prompt'];\n\n  /**\n   * Hook to access untrusted data from URL parameters and form submissions.\n   * @returns Object containing untrusted user input that should be validated before use\n   * @example\n   * ```jsx\n   * import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';\n   * function PrefilledForm() {\n   *   const untrustedData = useUntrustedData();\n   * }\n   * ```\n   */\n  useUntrustedData = () => this.instance.untrustedData as T['untrustedData'];\n\n  /**\n   * Hook to access current screen information and metadata.\n   * @returns Screen object containing current screen name, configuration, and screen-specific data\n   * @example\n   * ```jsx\n   * import { useScreen } from '@auth0/auth0-acul-react/login-id';\n   * function ScreenDebug() {\n   *   const screen = useScreen();\n   * }\n   * ```\n   */\n  useScreen = () => this.instance.screen as T['screen'];\n\n  /**\n   * Hook to access transaction state and authentication flow data.\n   * @returns Transaction object containing flow state, session data, and transaction-specific information\n   * @example\n   * ```jsx\n   * import { useTransaction } from '@auth0/auth0-acul-react/login-id';\n   * function TransactionInfo() {\n   *   const transaction = useTransaction();\n   * }\n   * ```\n   */\n  useTransaction = () => this.instance.transaction as T['transaction'];\n}\n"],"names":["ContextHooks","constructor","instance","this","useUser","user","useTenant","tenant","useBranding","branding","useClient","client","useOrganization","organization","usePrompt","prompt","useUntrustedData","untrustedData","useScreen","screen","useTransaction","transaction"],"mappings":"MAMaA,EACX,WAAAC,CAAoBC,GAAAC,KAAAD,SAAAA,EAapBC,KAAAC,QAAU,IAAMD,KAAKD,SAASG,KAa9BF,KAAAG,UAAY,IAAMH,KAAKD,SAASK,OAahCJ,KAAAK,YAAc,IAAML,KAAKD,SAASO,SAalCN,KAAAO,UAAY,IAAMP,KAAKD,SAASS,OAgBhCR,KAAAS,gBAAkB,IAAMT,KAAKD,SAASW,aAatCV,KAAAW,UAAY,IAAMX,KAAKD,SAASa,OAahCZ,KAAAa,iBAAmB,IAAMb,KAAKD,SAASe,cAavCd,KAAAe,UAAY,IAAMf,KAAKD,SAASiB,OAahChB,KAAAiB,eAAiB,IAAMjB,KAAKD,SAASmB,WAxHH"}

package/dist/hooks/index.d.ts

@@ -0,0 +1,10 @@
+export { useAuth0Themes } from './common/auth0-themes';
+export { useCurrentScreen } from './common/current-screen';
+export { errorManager, useErrors, type UseErrorOptions, type UseErrorsResult, type ErrorsResult, type ErrorKind, type ErrorItem, } from './common/errors';
+export { ContextHooks } from './context';
+export { useLoginIdentifiers } from './utility/login-identifiers';
+export { useSignupIdentifiers } from './utility/signup-identifiers';
+export { useMfaPolling, type MfaPollingResult, type ULError } from './utility/polling-manager';
+export { useResend, type UseResendReturn, type UseResendOptions } from './utility/resend-manager';
+export { usePasswordValidation, type PasswordValidationResult, type PasswordComplexityRule, } from './utility/validate-password';
+export { useUsernameValidation, type UsernameValidationResult, type UsernameValidationError, } from './utility/validate-username';

package/dist/hooks/utility/login-identifiers.d.ts

@@ -0,0 +1,26 @@
+import { IdentifierType } from '@auth0/auth0-acul-js';
+/**
+ * Returns a list of active identifier types (such as `'email'`, `'phone'`, or `'username'`)
+ * currently in use in the authentication flow or login process.
+ *
+ * @supportedScreens
+ * - `login`
+ * - `login-id`
+ * - `reset-password-request`
+ *
+ * @returns An array of {@link IdentifierType} representing active identifiers.
+ *
+ * @example This example shows how to use the hook in a functional component on "login" screen.
+ * ```tsx
+ * import { useLoginIdentifiers } from '@auth0/auth0-acul-react/login';
+ *
+ * const loginIdentifiers = useLoginIdentifiers();
+ * const hasEmail = loginIdentifiers.includes('email');
+ * const hasPhone = loginIdentifiers.includes('phone');
+ * const hasUsername = loginIdentifiers.includes('username');
+ *
+ * // loginIdentifiers could be:
+ * // ['email', 'username']
+ * ```
+ */
+export declare const useLoginIdentifiers: () => IdentifierType[];

package/dist/hooks/utility/login-identifiers.js

@@ -0,0 +1,2 @@
+import{getScreen as t}from"../../state/instance-store.js";const e=()=>t().getLoginIdentifiers();export{e as useLoginIdentifiers};
+//# sourceMappingURL=login-identifiers.js.map

package/dist/hooks/utility/login-identifiers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"login-identifiers.js","sources":["../../../src/hooks/utility/login-identifiers.ts"],"sourcesContent":["import { IdentifierType } from '@auth0/auth0-acul-js';\n\nimport { getScreen } from '../../state/instance-store';\n\ninterface WithLoginIdentifiers {\n  getLoginIdentifiers: () => IdentifierType[];\n}\n\n/**\n * Returns a list of active identifier types (such as `'email'`, `'phone'`, or `'username'`)\n * currently in use in the authentication flow or login process.\n *\n * @supportedScreens\n * - `login`\n * - `login-id`\n * - `reset-password-request`\n *\n * @returns An array of {@link IdentifierType} representing active identifiers.\n *\n * @example This example shows how to use the hook in a functional component on \"login\" screen.\n * ```tsx\n * import { useLoginIdentifiers } from '@auth0/auth0-acul-react/login';\n *\n * const loginIdentifiers = useLoginIdentifiers();\n * const hasEmail = loginIdentifiers.includes('email');\n * const hasPhone = loginIdentifiers.includes('phone');\n * const hasUsername = loginIdentifiers.includes('username');\n *\n * // loginIdentifiers could be:\n * // ['email', 'username']\n * ```\n */\n\nexport const useLoginIdentifiers = (): IdentifierType[] => {\n  const instance = getScreen<WithLoginIdentifiers>();\n  return instance.getLoginIdentifiers();\n};\n"],"names":["useLoginIdentifiers","getScreen","getLoginIdentifiers"],"mappings":"0DAiCO,MAAMA,EAAsB,IAChBC,IACDC"}

package/dist/hooks/utility/polling-manager.d.ts

@@ -0,0 +1,93 @@
+import type { MfaPollingOptions, Error as ULError } from '@auth0/auth0-acul-js';
+/**
+ * Result object returned by {@link useMfaPolling}.
+ *
+ * @public
+ */
+export interface MfaPollingResult {
+    /**
+     * Indicates whether the MFA push polling process is currently active.
+     *
+     * - `true` — Polling is running and awaiting completion.
+     * - `false` — Polling has stopped, either due to completion,
+     *   manual cancellation, or component unmount.
+     */
+    isRunning: boolean;
+    /**
+     * Starts or resumes the polling process.
+     *
+     * - If polling is already active, this call has no effect.
+     * - If previously stopped, calling this restarts the polling loop.
+     */
+    startPolling: () => void;
+    /**
+     * Stops the polling process immediately.
+     *
+     * - Cancels any scheduled timers or in-flight requests.
+     * - Safe to call multiple times; subsequent calls have no effect.
+     */
+    stopPolling: () => void;
+}
+/**
+ * React hook to manage MFA push polling (e.g., waiting for a push notification approval)
+ * on an Auth0 Advanced Customization of Universal Login (ACUL) screen.
+ *
+ * This hook sets up and controls a long-running polling loop that repeatedly checks
+ * the MFA push challenge endpoint until one of the following occurs:
+ *
+ * - The challenge is **approved or denied** by the user, triggering `options.onCompleted`.
+ * - An **error** occurs (network error, non-200/429 response), triggering `options.onError`.
+ * - The **component unmounts** or `stopPolling()` is called, which cancels polling.
+ *
+ * ### Key Features
+ * - `isRunning` is **reactive** — it updates automatically if the polling loop
+ *   stops internally or is canceled.
+ * - Uses a **stable single polling instance** (`useRef`) to prevent
+ *   duplicate network calls and unintended restarts during React re-renders.
+ * - **Automatic cleanup** on unmount: no orphan timers or leaked XHR requests.
+ *
+ * @param options - {@link MfaPollingOptions} specifying the polling interval,
+ *                  success callback (`onCompleted`), and optional error handler (`onError`).
+ *
+ *@supportedScreens
+ * - `mfa-push-challenge-push`
+ * - `reset-password-mfa-push-challenge-push`
+ *
+ * @returns object {@link MfaPollingResult} containing:
+ * - `isRunning` — `true` while polling is active.
+ * - `startPolling()` — starts or resumes polling.
+ * - `stopPolling()` — stops polling immediately.
+ *
+ * @example
+ * ```tsx
+ * import { useMfaPolling } from '@auth0/auth0-acul-react/mfa-push-challenge-push';
+ *
+ * export function MfaPushStatus() {
+ *   const { isRunning, startPolling, stopPolling } = useMfaPolling({
+ *     intervalMs: 5000,
+ *     onCompleted: () => console.log('Push approved!/denied'),
+ *     onError: (error) => console.error('Polling error:', error)
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={startPolling} disabled={isRunning}>
+ *         {isRunning ? 'Waiting for approval…' : 'Start MFA Polling'}
+ *       </button>
+ *       {isRunning && <button onClick={stopPolling}>Cancel</button>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @remarks
+ * - The `onError` callback receives an {@link ULError} object
+ *   with `status` and `responseText` describing the server response.
+ * - Internal rate-limit responses (`429`) are automatically handled:
+ *   polling waits for the reset window before retrying.
+ * - Calling `startPolling()` repeatedly while running is safe and idempotent.
+ *
+ * @public
+ */
+export declare function useMfaPolling(options?: MfaPollingOptions): MfaPollingResult;
+export type { MfaPollingOptions, ULError };

package/dist/hooks/utility/polling-manager.js

@@ -0,0 +1,2 @@
+import{useState as r,useMemo as n,useRef as o,useCallback as t,useEffect as e}from"react";import{getScreen as s}from"../../state/instance-store.js";import{errorManager as l}from"../common/errors.js";function i(i){const[u,c]=r(!1),m=n(()=>{const r=i??{};return{...r,onCompleted:()=>{c(!1),r.onCompleted?.()},onError:n=>{c(!1),l.pushServerErrors([n]),r.onError?.(n)}}},[i]),p=n(()=>s(),[]),a=o(null);null===a.current&&(a.current=p.pollingManager(m));const g=a.current,f=t(()=>{g.startPolling(),c(!0)},[g]),P=t(()=>{g.stopPolling(),c(!1)},[g]);return e(()=>{let r=!0;const n=()=>{if(!r)return;const o=g.isRunning();c(o),o&&requestAnimationFrame(n)};return n(),()=>{r=!1,g.stopPolling()}},[g]),{isRunning:u,startPolling:f,stopPolling:P}}export{i as useMfaPolling};
+//# sourceMappingURL=polling-manager.js.map

package/dist/hooks/utility/polling-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"polling-manager.js","sources":["../../../src/hooks/utility/polling-manager.ts"],"sourcesContent":["import { useCallback, useEffect, useMemo, useRef, useState } from 'react';\n\nimport { getScreen } from '../../state/instance-store';\nimport { errorManager } from '../common/errors';\n\nimport type {\n  MfaPollingOptions,\n  MfaPushPollingControl,\n  Error as ULError,\n} from '@auth0/auth0-acul-js';\n\n/**\n * Result object returned by {@link useMfaPolling}.\n *\n * @public\n */\nexport interface MfaPollingResult {\n  /**\n   * Indicates whether the MFA push polling process is currently active.\n   *\n   * - `true` — Polling is running and awaiting completion.\n   * - `false` — Polling has stopped, either due to completion,\n   *   manual cancellation, or component unmount.\n   */\n  isRunning: boolean;\n\n  /**\n   * Starts or resumes the polling process.\n   *\n   * - If polling is already active, this call has no effect.\n   * - If previously stopped, calling this restarts the polling loop.\n   */\n  startPolling: () => void;\n\n  /**\n   * Stops the polling process immediately.\n   *\n   * - Cancels any scheduled timers or in-flight requests.\n   * - Safe to call multiple times; subsequent calls have no effect.\n   */\n  stopPolling: () => void;\n}\n\n/**\n * React hook to manage MFA push polling (e.g., waiting for a push notification approval)\n * on an Auth0 Advanced Customization of Universal Login (ACUL) screen.\n *\n * This hook sets up and controls a long-running polling loop that repeatedly checks\n * the MFA push challenge endpoint until one of the following occurs:\n *\n * - The challenge is **approved or denied** by the user, triggering `options.onCompleted`.\n * - An **error** occurs (network error, non-200/429 response), triggering `options.onError`.\n * - The **component unmounts** or `stopPolling()` is called, which cancels polling.\n *\n * ### Key Features\n * - `isRunning` is **reactive** — it updates automatically if the polling loop\n *   stops internally or is canceled.\n * - Uses a **stable single polling instance** (`useRef`) to prevent\n *   duplicate network calls and unintended restarts during React re-renders.\n * - **Automatic cleanup** on unmount: no orphan timers or leaked XHR requests.\n *\n * @param options - {@link MfaPollingOptions} specifying the polling interval,\n *                  success callback (`onCompleted`), and optional error handler (`onError`).\n *\n *@supportedScreens\n * - `mfa-push-challenge-push`\n * - `reset-password-mfa-push-challenge-push`\n *\n * @returns object {@link MfaPollingResult} containing:\n * - `isRunning` — `true` while polling is active.\n * - `startPolling()` — starts or resumes polling.\n * - `stopPolling()` — stops polling immediately.\n *\n * @example\n * ```tsx\n * import { useMfaPolling } from '@auth0/auth0-acul-react/mfa-push-challenge-push';\n *\n * export function MfaPushStatus() {\n *   const { isRunning, startPolling, stopPolling } = useMfaPolling({\n *     intervalMs: 5000,\n *     onCompleted: () => console.log('Push approved!/denied'),\n *     onError: (error) => console.error('Polling error:', error)\n *   });\n *\n *   return (\n *     <div>\n *       <button onClick={startPolling} disabled={isRunning}>\n *         {isRunning ? 'Waiting for approval…' : 'Start MFA Polling'}\n *       </button>\n *       {isRunning && <button onClick={stopPolling}>Cancel</button>}\n *     </div>\n *   );\n * }\n * ```\n *\n * @remarks\n * - The `onError` callback receives an {@link ULError} object\n *   with `status` and `responseText` describing the server response.\n * - Internal rate-limit responses (`429`) are automatically handled:\n *   polling waits for the reset window before retrying.\n * - Calling `startPolling()` repeatedly while running is safe and idempotent.\n *\n * @public\n */\nexport function useMfaPolling(options?: MfaPollingOptions): MfaPollingResult {\n  const [isRunning, setIsRunning] = useState(false);\n\n  // Wrap callbacks safely to immediately update `isRunning` on completion/error.\n  const wrappedOptions: MfaPollingOptions = useMemo(() => {\n    const safe = options ?? {};\n    return {\n      ...safe,\n      onCompleted: () => {\n        setIsRunning(false);\n        safe.onCompleted?.();\n      },\n      onError: (error: ULError) => {\n        setIsRunning(false);\n        errorManager.pushServerErrors([error]);\n        safe.onError?.(error);\n      },\n    };\n  }, [options]);\n\n  // Stable screen instance\n  const screen = useMemo(\n    () => getScreen<{ pollingManager: (o: MfaPollingOptions) => MfaPushPollingControl }>(),\n    []\n  );\n\n  // Single polling control instance per component\n  const pollingControlRef = useRef<MfaPushPollingControl | null>(null);\n  if (pollingControlRef.current === null) {\n    pollingControlRef.current = screen.pollingManager(wrappedOptions);\n  }\n  const pollingControl = pollingControlRef.current;\n\n  const startPolling = useCallback(() => {\n    pollingControl.startPolling();\n    setIsRunning(true);\n  }, [pollingControl]);\n\n  const stopPolling = useCallback(() => {\n    pollingControl.stopPolling();\n    setIsRunning(false);\n  }, [pollingControl]);\n\n  // One effect handles cleanup and state sync\n  useEffect(() => {\n    let mounted = true;\n\n    const tick = () => {\n      if (!mounted) {\n        return;\n      }\n      const running = pollingControl.isRunning();\n      setIsRunning(running);\n      if (running) {\n        requestAnimationFrame(tick);\n      }\n    };\n    tick();\n\n    return () => {\n      mounted = false;\n      pollingControl.stopPolling();\n    };\n  }, [pollingControl]);\n\n  return { isRunning, startPolling, stopPolling };\n}\n\nexport type { MfaPollingOptions, ULError };\n"],"names":["useMfaPolling","options","isRunning","setIsRunning","useState","wrappedOptions","useMemo","safe","onCompleted","onError","error","errorManager","pushServerErrors","screen","getScreen","pollingControlRef","useRef","current","pollingManager","pollingControl","startPolling","useCallback","stopPolling","useEffect","mounted","tick","running","requestAnimationFrame"],"mappings":"uMAwGM,SAAUA,EAAcC,GAC5B,MAAOC,EAAWC,GAAgBC,GAAS,GAGrCC,EAAoCC,EAAQ,KAChD,MAAMC,EAAON,GAAW,CAAA,EACxB,MAAO,IACFM,EACHC,YAAa,KACXL,GAAa,GACbI,EAAKC,iBAEPC,QAAUC,IACRP,GAAa,GACbQ,EAAaC,iBAAiB,CAACF,IAC/BH,EAAKE,UAAUC,MAGlB,CAACT,IAGEY,EAASP,EACb,IAAMQ,IACN,IAIIC,EAAoBC,EAAqC,MAC7B,OAA9BD,EAAkBE,UACpBF,EAAkBE,QAAUJ,EAAOK,eAAeb,IAEpD,MAAMc,EAAiBJ,EAAkBE,QAEnCG,EAAeC,EAAY,KAC/BF,EAAeC,eACfjB,GAAa,IACZ,CAACgB,IAEEG,EAAcD,EAAY,KAC9BF,EAAeG,cACfnB,GAAa,IACZ,CAACgB,IAwBJ,OArBAI,EAAU,KACR,IAAIC,GAAU,EAEd,MAAMC,EAAO,KACX,IAAKD,EACH,OAEF,MAAME,EAAUP,EAAejB,YAC/BC,EAAauB,GACTA,GACFC,sBAAsBF,IAK1B,OAFAA,IAEO,KACLD,GAAU,EACVL,EAAeG,gBAEhB,CAACH,IAEG,CAAEjB,YAAWkB,eAAcE,cACpC"}

package/dist/hooks/utility/resend-manager.d.ts

@@ -0,0 +1,74 @@
+/** Return type for {@link useResend}. */
+export interface UseResendReturn {
+    /** Seconds remaining until the next resend attempt is allowed. */
+    remaining: number;
+    /** Whether the resend action is currently disabled. */
+    disabled: boolean;
+    /** Start a resend attempt immediately, if allowed. */
+    startResend: () => void;
+}
+/** Optional configuration for {@link useResend}. */
+export interface UseResendOptions {
+    /**
+     * Countdown duration (in seconds) before another resend is allowed.
+     * Defaults to `10`.
+     */
+    timeoutSeconds?: number;
+    /**
+     * Callback fired when the countdown finishes and the resend
+     * action becomes available again.
+     */
+    onTimeout?: () => void;
+}
+/**
+ * This React hook manages "resend" actions (e.g., resending a verification code) on ACUL screens.
+ *
+ * This hook:
+ * - Tracks the remaining cooldown time.
+ * - Tells you whether the resend button should be disabled.
+ * - Provides a `startResend` function to trigger a resend immediately.
+ *
+ * @supportedScreens
+ * - `email-identifier-challenge`
+ * - `email-otp-challenge`
+ * - `login-email-verification`
+ * - `login-passwordless-email-code`
+ * - `login-passwordless-sms-otp`
+ * - `mfa-email-challenge`
+ * - `mfa-sms-challenge`
+ * - `mfa-voice-challenge`
+ * - `phone-identifier-challenge`
+ * - `reset-password-mfa-email-challenge`
+ * - `reset-password-mfa-sms-challenge`
+ * - `reset-password-mfa-voice-challenge`
+ *
+ * @param options - Optional configuration such as `timeoutSeconds` and `onTimeout`.
+ *
+ * @returns An object with:
+ * - `remaining` — seconds left until the next resend is permitted.
+ * - `disabled` — `true` if resending is currently blocked.
+ * - `startResend` — call to initiate a resend immediately (if allowed).
+ *
+ * @example
+ * ```tsx
+ * import { useResend } from '@auth0/auth0-acul-react/mfa-sms-challenge';
+ *
+ * export function ResendButton() {
+ *   const { remaining, disabled, startResend } = useResend({
+ *     timeoutSeconds: 30,
+ *     onTimeout: () => console.log('You can resend again'),
+ *   });
+ *
+ *   return (
+ *     <button onClick={startResend} disabled={disabled}>
+ *       {disabled ? `Resend in ${remaining}s` : 'Resend Code'}
+ *     </button>
+ *   );
+ * }
+ * ```
+ *
+ * @remarks
+ * - The underlying `ResendControl` has no explicit teardown method; the hook does not require manual cleanup.
+ * - The hook re-initializes the resend manager if `timeoutSeconds` or `onTimeout` change.
+ */
+export declare function useResend(options?: UseResendOptions): UseResendReturn;

package/dist/hooks/utility/resend-manager.js

@@ -0,0 +1,2 @@
+import{useMemo as t,useState as e,useRef as n,useCallback as r,useEffect as o}from"react";import{getScreen as s}from"../../state/instance-store.js";function a(a){const{timeoutSeconds:i=10,onTimeout:u}=a??{},m=t(()=>s(),[]),[c,d]=e(0),[f,g]=e(!1),l=n(null),p=r((t,e)=>{d(t),g(e)},[]);o(()=>{l.current=m.resendManager({timeoutSeconds:i,onStatusChange:p,...u&&{onTimeout:u}})},[m,i,p,u]);return{remaining:c,disabled:f,startResend:r(()=>{l.current?.startResend()},[])}}export{a as useResend};
+//# sourceMappingURL=resend-manager.js.map

package/dist/hooks/utility/resend-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resend-manager.js","sources":["../../../src/hooks/utility/resend-manager.ts"],"sourcesContent":["import { useCallback, useEffect, useMemo, useRef, useState } from 'react';\n\nimport { getScreen } from '../../state/instance-store';\n\nimport type { StartResendOptions, ResendControl } from '@auth0/auth0-acul-js';\n\n/** Return type for {@link useResend}. */\nexport interface UseResendReturn {\n  /** Seconds remaining until the next resend attempt is allowed. */\n  remaining: number;\n  /** Whether the resend action is currently disabled. */\n  disabled: boolean;\n  /** Start a resend attempt immediately, if allowed. */\n  startResend: () => void;\n}\n\n/** Optional configuration for {@link useResend}. */\nexport interface UseResendOptions {\n  /**\n   * Countdown duration (in seconds) before another resend is allowed.\n   * Defaults to `10`.\n   */\n  timeoutSeconds?: number;\n  /**\n   * Callback fired when the countdown finishes and the resend\n   * action becomes available again.\n   */\n  onTimeout?: () => void;\n}\n\n/** Screens that support resend operations expose a `resendManager` method. */\ninterface WithResendManager {\n  resendManager(options?: StartResendOptions): ResendControl;\n}\n\n/**\n * This React hook manages \"resend\" actions (e.g., resending a verification code) on ACUL screens.\n *\n * This hook:\n * - Tracks the remaining cooldown time.\n * - Tells you whether the resend button should be disabled.\n * - Provides a `startResend` function to trigger a resend immediately.\n *\n * @supportedScreens\n * - `email-identifier-challenge`\n * - `email-otp-challenge`\n * - `login-email-verification`\n * - `login-passwordless-email-code`\n * - `login-passwordless-sms-otp`\n * - `mfa-email-challenge`\n * - `mfa-sms-challenge`\n * - `mfa-voice-challenge`\n * - `phone-identifier-challenge`\n * - `reset-password-mfa-email-challenge`\n * - `reset-password-mfa-sms-challenge`\n * - `reset-password-mfa-voice-challenge`\n *\n * @param options - Optional configuration such as `timeoutSeconds` and `onTimeout`.\n *\n * @returns An object with:\n * - `remaining` — seconds left until the next resend is permitted.\n * - `disabled` — `true` if resending is currently blocked.\n * - `startResend` — call to initiate a resend immediately (if allowed).\n *\n * @example\n * ```tsx\n * import { useResend } from '@auth0/auth0-acul-react/mfa-sms-challenge';\n *\n * export function ResendButton() {\n *   const { remaining, disabled, startResend } = useResend({\n *     timeoutSeconds: 30,\n *     onTimeout: () => console.log('You can resend again'),\n *   });\n *\n *   return (\n *     <button onClick={startResend} disabled={disabled}>\n *       {disabled ? `Resend in ${remaining}s` : 'Resend Code'}\n *     </button>\n *   );\n * }\n * ```\n *\n * @remarks\n * - The underlying `ResendControl` has no explicit teardown method; the hook does not require manual cleanup.\n * - The hook re-initializes the resend manager if `timeoutSeconds` or `onTimeout` change.\n */\nexport function useResend(options?: UseResendOptions): UseResendReturn {\n  const { timeoutSeconds = 10, onTimeout } = options ?? {};\n  const screen = useMemo(() => getScreen<WithResendManager>(), []);\n\n  const [remaining, setRemaining] = useState(0);\n  const [disabled, setDisabled] = useState(false);\n  const controlRef = useRef<ResendControl | null>(null);\n\n  // Update state whenever the manager reports a change\n  const handleStatusChange = useCallback((secs: number, isDisabled: boolean) => {\n    setRemaining(secs);\n    setDisabled(isDisabled);\n  }, []);\n\n  // Initialize the resend manager; re-run if options that affect its behavior change\n  useEffect(() => {\n    controlRef.current = screen.resendManager({\n      timeoutSeconds,\n      onStatusChange: handleStatusChange,\n      ...(onTimeout && { onTimeout }),\n    });\n  }, [screen, timeoutSeconds, handleStatusChange, onTimeout]);\n\n  const startResend = useCallback(() => {\n    controlRef.current?.startResend();\n  }, []);\n\n  return { remaining, disabled, startResend };\n}\n"],"names":["useResend","options","timeoutSeconds","onTimeout","screen","useMemo","getScreen","remaining","setRemaining","useState","disabled","setDisabled","controlRef","useRef","handleStatusChange","useCallback","secs","isDisabled","useEffect","current","resendManager","onStatusChange","startResend"],"mappings":"oJAsFM,SAAUA,EAAUC,GACxB,MAAMC,eAAEA,EAAiB,GAAEC,UAAEA,GAAcF,GAAW,CAAA,EAChDG,EAASC,EAAQ,IAAMC,IAAgC,KAEtDC,EAAWC,GAAgBC,EAAS,IACpCC,EAAUC,GAAeF,GAAS,GACnCG,EAAaC,EAA6B,MAG1CC,EAAqBC,EAAY,CAACC,EAAcC,KACpDT,EAAaQ,GACbL,EAAYM,IACX,IAGHC,EAAU,KACRN,EAAWO,QAAUf,EAAOgB,cAAc,CACxClB,iBACAmB,eAAgBP,KACZX,GAAa,CAAEA,gBAEpB,CAACC,EAAQF,EAAgBY,EAAoBX,IAMhD,MAAO,CAAEI,YAAWG,WAAUY,YAJVP,EAAY,KAC9BH,EAAWO,SAASG,eACnB,IAGL"}