doct-ui-auth-kit 1.0.13 → 1.0.15

package/dist/types/auth/flow.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Auth flow state machine types: state, actions, and context.
+ */
+import type { AuthStep, SSOSession, UserType } from './auth-types';
+/** Identifier type for OTP / profile steps. */
+export type IdentifierType = 'phone' | 'email';
+/** Full state for the auth flow. */
+export interface AuthFlowState {
+    step: AuthStep;
+    /** Previous step for goBack. */
+    lastStep: AuthStep;
+    /** Indian (+91) vs Foreign (non +91); drives layout and OTP routing. */
+    userType: UserType;
+    /** Current identifier value (phone or email) when in OTP or signup. */
+    identifierValue: string;
+    /** Type of identifier (phone vs email). */
+    identifierType: IdentifierType;
+    /** Masked value for display (e.g. "+91 9825910X0X"). */
+    maskedRecipient: string;
+    /** For SIGNUP_DETAILS (Indian): which field to collect (phone or email). */
+    signupCollectField: IdentifierType;
+    /** For REPEAT_LOGIN: last used method label. */
+    lastMethod: string;
+    /** Set when step is AUTHENTICATED. */
+    session: SSOSession | null;
+    /** Foreign flow: phone value when user entered phone before signup details. */
+    pendingPhone: string;
+    /** Foreign flow: signup form data for completeProfile after OTP verify. */
+    pendingFullName: string;
+    pendingEmail: string;
+}
+/** Pure reducer actions. */
+export type AuthFlowAction = {
+    type: 'SET_SESSION';
+    session: SSOSession;
+} | {
+    type: 'SET_STEP_REPEAT_LOGIN';
+    lastMethod: string;
+    maskedIdentifier: string;
+} | {
+    type: 'SET_STEP_METHOD_SELECT';
+} | {
+    type: 'SET_STEP_PHONE_ENTRY';
+} | {
+    type: 'SET_STEP_EMAIL_ENTRY';
+} | {
+    type: 'SET_STEP_OTP_VERIFICATION';
+    userType: UserType;
+    identifierType: IdentifierType;
+    value: string;
+    maskedValue: string;
+    /** Foreign flow: for completeProfile after OTP. */
+    pendingFullName?: string;
+    pendingEmail?: string;
+    pendingPhone?: string;
+} | {
+    type: 'SET_STEP_SIGNUP_DETAILS';
+    userType: UserType;
+    /** Indian: which field to collect (phone or email). Foreign: ignored. */
+    signupCollectField: IdentifierType;
+    /** Foreign only: phone value when user entered phone before signup. */
+    pendingPhone?: string;
+    /** When coming from identifier entry (foreign): preserve for later OTP. */
+    identifierType?: IdentifierType;
+    identifierValue?: string;
+    maskedRecipient?: string;
+} | {
+    type: 'SET_STEP_PROVIDER_PENDING';
+} | {
+    type: 'SET_STEP_AUTHENTICATED';
+    session: SSOSession;
+} | {
+    type: 'GO_BACK';
+} | {
+    type: 'RESET';
+} | {
+    type: 'SIGN_OUT';
+};
+/** Provider config slice exposed to flow for Google/Apple wiring. */
+export interface AuthFlowProviderConfig {
+    google?: {
+        clientId: string;
+        enableOneTap?: boolean;
+    };
+    apple?: {
+        clientId: string;
+        redirectUri: string;
+    };
+}
+/** Async actions that perform I/O and dispatch to the flow reducer. */
+export interface AuthFlowActions {
+    selectMethod: (method: 'phone' | 'email' | 'google' | 'apple') => void;
+    /** From REPEAT_LOGIN: continue with last used method. */
+    continueWithLastMethod: () => void;
+    submitIdentifier: (data: {
+        phone?: string;
+        email?: string;
+        countryCode?: string;
+    }) => void;
+    /** SIGNUP_DETAILS step: submit name + phone/email, then OTP (foreign) or complete (Indian). */
+    submitSignupDetails: (data: {
+        fullName: string;
+        phone?: string;
+        email?: string;
+        countryCode?: string;
+    }) => void;
+    /**
+     * Verifies the OTP against the auth API. Resolves on success (after the
+     * reducer has been advanced) and rejects with an `AuthError` whose
+     * `message` carries the API's failure reason — callers can surface it
+     * as a field-level error.
+     */
+    verifyOtp: (otp: string) => Promise<void>;
+    resendOtp: () => void;
+    providerCallback: (params: {
+        provider: 'google' | 'apple';
+        credential: string;
+    }) => void;
+    goBack: () => void;
+    reset: () => void;
+    signOut: () => void;
+}
+/** Auth flow context value provided by SSOAuthProvider. */
+export interface AuthFlowContextValue {
+    state: AuthFlowState;
+    actions: AuthFlowActions;
+    /** Session when step is AUTHENTICATED. */
+    session: SSOSession | null;
+    /** True while step is CHECKING_SESSION. */
+    isLoading: boolean;
+    /** Provider config for Google/Apple (One Tap, Sign-In button). */
+    providerConfig: AuthFlowProviderConfig | undefined;
+}

package/dist/types/auth/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Auth domain types: session, adapter, provider, flow state, errors, device detection.
+ */
+export * from './auth-api-adapter';
+export * from './auth-provider';
+export * from './auth-types';
+export * from './device-detection';
+export * from './flow';
+export * from './router';
+export * from './sso-session';

package/dist/types/auth/router.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Optional URL routing integration for `<AuthFlow/>`.
+ *
+ * The SDK stays router-agnostic: consumers construct an `AuthFlowRouter`
+ * adapter from their app's router (Next.js, React Router, TanStack, etc.)
+ * and a `routes` map of which auth step maps to which URL path.
+ *
+ * Steps omitted from the map render in place without changing the URL
+ * (e.g. `CHECKING_SESSION`, `PROVIDER_PENDING`, `AUTHENTICATED`).
+ */
+import type { AuthStep } from './auth-types';
+/**
+ * URL path for a given auth step. Consumers control the path strings;
+ * the SDK only matches via string equality (returned by `getPath`).
+ */
+export type AuthFlowRoutes = Partial<Record<AuthStep, string>>;
+/**
+ * Router adapter the SDK uses to read and update the URL. Built by the
+ * consumer from their framework's primitives.
+ *
+ * @example Next.js (App Router)
+ * ```tsx
+ * import { usePathname, useRouter } from 'next/navigation';
+ *
+ * function useAuthRouter(): AuthFlowRouter {
+ *   const router = useRouter();
+ *   const pathname = usePathname();
+ *   const pathRef = useRef(pathname);
+ *   pathRef.current = pathname;
+ *   const listenersRef = useRef(new Set<(p: string) => void>());
+ *
+ *   useEffect(() => {
+ *     for (const cb of listenersRef.current) cb(pathname);
+ *   }, [pathname]);
+ *
+ *   return {
+ *     push:    (p) => router.push(p),
+ *     replace: (p) => router.replace(p),
+ *     getPath: () => pathRef.current,
+ *     subscribe: (cb) => {
+ *       listenersRef.current.add(cb);
+ *       return () => listenersRef.current.delete(cb);
+ *     },
+ *   };
+ * }
+ * ```
+ */
+export interface AuthFlowRouter {
+    /** Navigate to `path`, adding a history entry. */
+    push: (path: string) => void;
+    /** Navigate to `path`, replacing the current history entry. */
+    replace: (path: string) => void;
+    /** Return the current URL path (pathname only — no query / hash). */
+    getPath: () => string;
+    /**
+     * Subscribe to path changes (back/forward, programmatic push/replace).
+     * Returns an unsubscribe function.
+     */
+    subscribe: (callback: (path: string) => void) => () => void;
+}

package/dist/types/auth/sso-session.d.ts

@@ -0,0 +1,33 @@
+/**
+ * SSO session and token storage types.
+ */
+/** How/where the SSO token is stored for cross-app access. */
+export interface TokenStorageStrategy {
+    get(): string | null;
+    set(token: string, expiresAt: number): void;
+    remove(): void;
+}
+/** Minimal request config type for the interceptor (no axios import). */
+export interface AxiosRequestConfig {
+    headers?: Record<string, string> | {
+        [key: string]: string;
+    };
+    withCredentials?: boolean;
+}
+/**
+ * Axios instance shape needed to attach auth interceptors (avoids hard axios dependency).
+ * Use createAxiosAuthInterceptors with your axios instance.
+ */
+export interface AxiosAuthInterceptorInstance {
+    interceptors: {
+        request: {
+            use(onFulfilled?: (config: AxiosRequestConfig) => AxiosRequestConfig | Promise<AxiosRequestConfig>, onRejected?: (err: unknown) => unknown): number;
+        };
+        response: {
+            use(onFulfilled?: (res: unknown) => unknown, onRejected?: (err: unknown) => unknown): number;
+        };
+    };
+    defaults: {
+        withCredentials?: boolean;
+    };
+}

package/dist/types/components/auth-layout-types.d.ts

@@ -0,0 +1,92 @@
+import type { ReactNode } from 'react';
+/**
+ * Layout configuration types
+ */
+export type AuthLayoutVariant = 'mobile' | 'desktop';
+export type AuthLayoutMaxWidth = 'sm' | 'md' | 'lg';
+/** Text/alignment variant for Logo, Title, Description slots */
+export type AuthLayoutAlign = 'left' | 'center' | 'right';
+/**
+ * Props for AuthLayout.Root component
+ */
+export interface AuthLayoutRootProps {
+    /** Main content (compound components) */
+    children: ReactNode;
+    /** Layout variation for spacing and alignment */
+    variant?: AuthLayoutVariant;
+    /** Maximum width constraint for the content area */
+    maxWidth?: AuthLayoutMaxWidth;
+    /** Additional className for the root container */
+    className?: string;
+}
+/**
+ * Props for AuthLayout.Header component
+ */
+export interface AuthLayoutHeaderProps {
+    /** Header content */
+    children: ReactNode;
+    /** Additional className */
+    className?: string;
+}
+/**
+ * Props for AuthLayout.Logo component
+ */
+export interface AuthLayoutLogoProps {
+    /** Logo content */
+    children: ReactNode;
+    /** Alignment: left, center (default), or right */
+    align?: AuthLayoutAlign;
+    /** Additional className */
+    className?: string;
+}
+/**
+ * Props for AuthLayout.Title component
+ */
+export interface AuthLayoutTitleProps {
+    /** Title content */
+    children: ReactNode;
+    /** Alignment: left, center (default), or right */
+    align?: AuthLayoutAlign;
+    /** Additional className */
+    className?: string;
+}
+/**
+ * Props for AuthLayout.Description component
+ */
+export interface AuthLayoutDescriptionProps {
+    /** Description content */
+    children: ReactNode;
+    /** Alignment: left, center (default), or right */
+    align?: AuthLayoutAlign;
+    /** Additional className */
+    className?: string;
+}
+/**
+ * Props for AuthLayout.Body component
+ */
+export interface AuthLayoutBodyProps {
+    /** Body content (forms, buttons, etc.) */
+    children: ReactNode;
+    /** Additional className */
+    className?: string;
+}
+/**
+ * Props for AuthLayout.Main component
+ */
+export interface AuthLayoutMainProps {
+    /** Main content (Logo, Title, Description, Body slots) */
+    children: ReactNode;
+    /** When true, constrains main content width to 320px (max-w-[320px]) */
+    sm?: boolean;
+    /** Additional className */
+    className?: string;
+}
+/**
+ * Props for AuthLayout.Footer component
+ */
+export interface AuthLayoutFooterProps {
+    /** Footer content */
+    children: ReactNode;
+    /** Additional className */
+    className?: string;
+}

package/dist/types/components/forms.d.ts

@@ -0,0 +1,77 @@
+/** Form types used by auth SDK form components. */
+import type { ComponentProps, KeyboardEvent } from 'react';
+import { DoctPhoneInput } from 'docthub-core-components';
+import type { Control, FieldValues } from 'react-hook-form';
+/** Base props shared by RHF form field components. */
+export interface BaseFormFieldProps {
+    /** Field name used by react-hook-form for registration and validation. */
+    name: string;
+    /** Visible label rendered above or beside the input. */
+    label?: string;
+    /** Placeholder text shown when the input is empty. */
+    placeholder?: string;
+    /** Whether the field is required for form submission. */
+    required?: boolean;
+    /** Whether the field is disabled (non-interactive). */
+    disabled?: boolean;
+    /** Additional CSS class name(s) applied to the field wrapper. */
+    className?: string;
+    /** Validation error message to display below the input. */
+    error?: string;
+    /** Supplementary helper text shown below the input when there is no error. */
+    helperText?: string;
+    /** Focus this field when form/screen opens (PRODUCT_PROTOCOLS #26). */
+    autoFocus?: boolean;
+}
+/** Props for the text/email/number input field component. */
+export interface RHFInputFieldProps extends BaseFormFieldProps {
+    /** HTML input type. Allowed: `'text'`, `'email'`, `'password'`, `'number'`, `'tel'`, `'url'`, `'search'`. */
+    type?: 'text' | 'email' | 'password' | 'number' | 'tel' | 'url' | 'search';
+    /** HTML `autocomplete` attribute value (e.g. `'email'`, `'tel'`). */
+    autoComplete?: string;
+    /** Maximum character length enforced on the input. */
+    maxLength?: number;
+    /** Minimum character length enforced on the input. */
+    minLength?: number;
+    /** Regex pattern string for native HTML validation. */
+    pattern?: string;
+    /** react-hook-form `Control` instance. When omitted, the field uses the nearest `FormProvider`. */
+    control?: Control<FieldValues>;
+    /** Called when a key is pressed while the input is focused. */
+    onKeyDown?: (event: KeyboardEvent<HTMLInputElement>) => void;
+    /** When true, restricts input to numeric characters only. */
+    numericOnly?: boolean;
+}
+/** Props for RHF wrapper around DoctPhoneInput (docthub-core-components). */
+type DoctPhoneInputProps = ComponentProps<typeof DoctPhoneInput>;
+/** Props for RHF wrapper around DoctPhoneInput (docthub-core-components). */
+export interface RHFDoctPhoneInputFieldProps extends BaseFormFieldProps, Omit<DoctPhoneInputProps, 'id' | 'name' | 'value' | 'error' | 'helperText' | 'onBlur' | 'onPhoneChange'> {
+    /** Country code used when no `countryCodeName` field is configured (e.g. `'91'`). */
+    countryCode?: string;
+    /** Optional RHF field that stores country code independently. */
+    countryCodeName?: string;
+    /** Optional RHF field that stores the `DoctPhoneInput` values object. */
+    phoneArrayName?: string;
+    /** Optional RHF field that stores selected country metadata. */
+    selectedCountryName?: string;
+    /** react-hook-form `Control` instance. When omitted, the field uses the nearest `FormProvider`. */
+    control?: Control<FieldValues>;
+}
+/** Props for the OTP input field component. */
+export interface RHFOtpInputFieldProps extends BaseFormFieldProps {
+    /** Number of OTP digit boxes to render. @default 6 */
+    length?: number;
+    /** Input type for each OTP box: `'text'`, `'number'`, or `'password'` (masked). */
+    type?: 'text' | 'number' | 'password';
+    /** Focus the first OTP box on mount. */
+    autoFocus?: boolean;
+    /** Automatically trigger submission when all boxes are filled. */
+    autoSubmit?: boolean;
+    /** Called with the complete OTP string once all boxes are filled. */
+    onComplete?: (otp: string) => void;
+    /** CSS class name(s) applied to each individual OTP input box. */
+    inputClassName?: string;
+    /** react-hook-form `Control` instance. When omitted, the field uses the nearest `FormProvider`. */
+    control?: Control<FieldValues>;
+}
+export {};

package/dist/types/components/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Component prop types: form fields, layouts, auth-layout compound, presets.
+ */
+export * from './auth-layout-types';
+export * from './forms';
+export * from './layout';
+export * from './layout-presets';

package/dist/types/components/layout-presets.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Layout preset types for the Auth SDK.
+ * Presets control structure only: width, alignment, slider vs standalone.
+ * They do NOT control auth methods, MFA, or flow behavior.
+ */
+import type { AuthLayoutAlign, AuthLayoutMaxWidth, AuthLayoutVariant } from './auth-layout-types';
+/** Layout type: two-panel with slider vs single centered column. */
+export type LayoutType = 'withSlider' | 'standalone';
+/**
+ * Named presets for auth screens. Kept minimal to avoid preset explosion.
+ * Add new presets only for distinct layout structures, not for auth methods.
+ */
+export type LayoutPresetName = 'login' | 'signup' | 'verification' | '';
+/**
+ * Structure-only config derived from a preset.
+ * Used by AuthLayout to render the correct shell (slider, width, alignment).
+ */
+export interface LayoutPresetConfig {
+    /** Whether to show the two-panel slider (e.g. login) or standalone column. */
+    layoutType: LayoutType;
+    /** Mobile vs desktop spacing/breakpoints. */
+    variant: AuthLayoutVariant;
+    /** Max width of the content area. */
+    maxWidth: AuthLayoutMaxWidth;
+    /** Constrain main content to 320px when 'sm'. */
+    contentWidth: 'sm' | 'default';
+    /** Title/description alignment. */
+    align: AuthLayoutAlign;
+}

package/dist/types/components/layout.d.ts

@@ -0,0 +1,57 @@
+import type { ReactNode } from 'react';
+/** Props for the ImageSlider component. */
+export interface ImageSliderProps {
+    /** Array of image URLs to display */
+    images: string[];
+    /** Auto-play interval in milliseconds (0 to disable) */
+    autoPlayInterval?: number;
+    /** Additional className for the root container */
+    className?: string;
+    /** Whether to hide the built-in slider indicators */
+    hideIndicators?: boolean;
+    /** Optional callback fired whenever the active slide changes */
+    onSlideChange?: (index: number) => void;
+    /** Controlled active index (makes component controlled) */
+    activeIndex?: number;
+    /** Callback for manual slide navigation in controlled mode */
+    onNavigate?: (index: number) => void;
+}
+/**
+ * Props for the MainLayout component.
+ * Two-panel auth page: left panel (marketing/slider), right panel (auth content).
+ */
+export interface MainLayoutProps {
+    /** Array of image URLs for the slider */
+    sliderImages?: string[];
+    /** Auto-play interval for slider in milliseconds (0 to disable) */
+    sliderAutoPlayInterval?: number;
+    /** Call-to-action text displayed above the image card. Set to null to hide */
+    ctaText?: ReactNode | null;
+    /** Per-slide title/CTA (overrides ctaText when provided; uses active slide index) */
+    sliderTitles?: (ReactNode | string)[] | undefined;
+    /** Additional className for the root container */
+    className?: string;
+    /** Additional className for the marketing panel (left side) */
+    marketingClassName?: string;
+    /** Additional className for the content panel (right side) */
+    contentClassName?: string;
+    /** Main authentication content (typically AuthLayout.Root with slots) */
+    children: ReactNode;
+}
+/** Props for the MarketingPanel component (left side). */
+export interface MarketingPanelProps {
+    /** Array of image URLs for the slider */
+    sliderImages: string[];
+    /** Auto-play interval for slider in milliseconds */
+    sliderAutoPlayInterval: number;
+    /** Active slide index (controlled) */
+    activeSlideIndex: number;
+    /** Callback when slide changes */
+    onSlideChange: (index: number) => void;
+    /** Call-to-action text */
+    ctaText?: ReactNode | null;
+    /** Per-slide title/CTA (overrides ctaText when provided) */
+    sliderTitles?: (ReactNode | string)[] | undefined;
+    /** Additional className */
+    className?: string;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Central export for all types and interfaces.
+ * Organized by domain: auth (SSO), components (props), pages (page-specific).
+ */
+export * from './auth';
+export * from './components';
+export * from './pages';

package/dist/types/pages/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Page-specific types: props, form values, hook options/return types.
+ */
+export * from './login-form';
+export * from './main-login';
+export * from './otp-verification';
+export * from './pages';
+export * from './repeat-login';
+export * from './signup-form';

package/dist/types/pages/login-form.d.ts

@@ -0,0 +1,57 @@
+import type { UseFormReturn } from 'react-hook-form';
+import type { z } from 'zod';
+import type { loginEmailFormSchema, loginPhoneFormSchema } from '../../validations';
+/** Login mode: phone number or email */
+export type LoginEntryMode = 'phone' | 'email';
+/** Form values for phone-based login, inferred from the Zod schema. */
+export type PhoneFormValues = z.infer<typeof loginPhoneFormSchema>;
+/** Form values for email-based login, inferred from the Zod schema. */
+export type EmailFormValues = z.infer<typeof loginEmailFormSchema>;
+/** Discriminated union of phone or email login form values. */
+export type LoginEntryFormValues = PhoneFormValues | EmailFormValues;
+/** Payload when login entry form is valid (phone or email). */
+export type LoginEntrySubmitData = {
+    phone?: string;
+    email?: string;
+    countryCode?: string;
+};
+/**
+ * Params passed to onSuccess after submitApi resolves.
+ * Lets the consumer redirect to OTP with mode and recipient (for recipientDisplay) without storing them in refs.
+ */
+export interface LoginEntrySuccessParams {
+    /** Current login entry mode (phone or email). */
+    mode: LoginEntryMode;
+    /** Submitted phone or email string; use for OTP page recipientDisplay or verify API. */
+    recipient: string;
+}
+export interface UseLoginEntryFormOptions {
+    mode: LoginEntryMode;
+    /**
+     * Sync callback with valid form data. Used when parent owns API (e.g. AuthFlow passes actions.submitIdentifier).
+     * Ignored when submitApi is provided.
+     */
+    onSubmit?: ((data: LoginEntrySubmitData) => void) | undefined;
+    /**
+     * When provided, hook runs business logic: validate → call submitApi(data) → onSuccess(params).
+     * Use from consumer (e.g. Next.js): submitApi = sendOtp, onSuccess = (params) => router.push(`/otp?mode=${params.mode}&recipient=${encodeURIComponent(params.recipient)}`).
+     */
+    submitApi?: ((data: LoginEntrySubmitData) => Promise<void>) | undefined;
+    /** Called after submitApi resolves successfully; receives mode and recipient for OTP redirect/display. */
+    onSuccess?: ((params: LoginEntrySuccessParams) => void) | undefined;
+    /** Called when submitApi rejects or throws. */
+    onError?: ((error: unknown) => void) | undefined;
+}
+/** Return value of the `useLoginEntryForm` hook, providing form state and mode info. */
+export interface UseLoginEntryFormReturn {
+    /** react-hook-form methods bound to the current login mode's schema. */
+    methods: UseFormReturn<LoginEntryFormValues>;
+    /** Submit handler to pass to the form's `onSubmit`. Validates and dispatches the login data. */
+    handleSubmit: (data: LoginEntryFormValues) => void;
+    /** True when the current mode is `'phone'`; use for conditional field rendering. */
+    isPhone: boolean;
+    /** True when current form values pass validation (for disabling Continue until valid – edge cases 3, 4). */
+    isFormValid: (data: LoginEntryFormValues) => boolean;
+    /** True while submitApi is in flight. Use to disable Continue button and show loading. */
+    isSubmitting: boolean;
+}

package/dist/types/pages/otp-verification.d.ts

@@ -1,6 +1,6 @@
 import type { UseFormReturn } from 'react-hook-form';
 import type { z } from 'zod';
-import type { OtpVerificationMode, otpFormSchema } from '@/validations';
+import type { OtpVerificationMode, otpFormSchema } from '../../validations';
 export type { OtpVerificationMode };
 /** Form values for the OTP verification form, inferred from the Zod schema. */
 export type OtpFormValues = z.infer<typeof otpFormSchema>;

package/dist/types/pages/repeat-login.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Hook options and return type for repeat login (continue with last method).
+ */
+export interface UseRepeatLoginOptions {
+    /**
+     * Last used authentication method shown in the primary button label.
+     * @default "Mobile"
+     */
+    lastUsedMethod?: string | undefined;
+    /** Sync handler for primary action. Use when caller owns API (e.g. AuthFlow). Ignored when continueApi is provided. */
+    onContinueWithLastMethod?: (() => void) | undefined;
+    /** Handler for the secondary action (choose another method). */
+    onUseAnotherMethod?: (() => void) | undefined;
+    /** Async API for continue (e.g. validate session). When provided, hook runs: continueApi() → onSuccess(). */
+    continueApi?: (() => Promise<void>) | undefined;
+    /** Called after continueApi succeeds (e.g. router.push('/dashboard')). */
+    onSuccess?: (() => void) | undefined;
+    /** Called when continueApi fails. */
+    onError?: ((error: unknown) => void) | undefined;
+}
+/** Return value of the `useRepeatLogin` hook, providing continue handler and display state. */
+export interface UseRepeatLoginReturn {
+    /** Call this when the user clicks "Continue with {lastUsedMethod}". */
+    handleContinue: () => void;
+    /** True while continueApi is in flight. */
+    isSubmitting: boolean;
+    /** Resolved lastUsedMethod for display (default "Mobile"). */
+    lastUsedMethod: string;
+}

package/dist/types/pages/signup-form.d.ts

@@ -0,0 +1,49 @@
+import type { UseFormReturn } from 'react-hook-form';
+import type { z } from 'zod';
+import type { signupEmailFormSchema, signupForeignFormSchema, signupPhoneFormSchema } from '../../validations';
+/** Signup mode: phone, email as second field, or foreign (full name + email + phone). */
+export type SignupEntryMode = 'phone' | 'email' | 'foreign';
+/** Form values for phone-based signup, inferred from the Zod schema. */
+export type SignupPhoneFormValues = z.infer<typeof signupPhoneFormSchema>;
+/** Form values for email-based signup, inferred from the Zod schema. */
+export type SignupEmailFormValues = z.infer<typeof signupEmailFormSchema>;
+/** Form values for foreign signup (full name + email + phone), inferred from the Zod schema. */
+export type SignupForeignFormValues = z.infer<typeof signupForeignFormSchema>;
+/** Discriminated union of all signup form value shapes. */
+export type SignupFormValues = SignupPhoneFormValues | SignupEmailFormValues | SignupForeignFormValues;
+/** Payload when signup form is valid. */
+export type SignupSubmitData = {
+    fullName: string;
+    phone?: string;
+    email?: string;
+    countryCode?: string;
+};
+export interface UseSignupFormOptions {
+    /** Mode: phone, email as second field, or foreign (name + email + phone) */
+    mode: SignupEntryMode;
+    /** For foreign mode: pre-fill phone when user already entered it. */
+    defaultPhone?: string | undefined;
+    /** Sync callback with valid data. Use when parent owns API (e.g. AuthFlow). Ignored when submitApi is provided. */
+    onSubmit?: ((data: SignupSubmitData) => void) | undefined;
+    /** When provided, hook runs: validate → submitApi(data) → onSuccess(). Consumer passes redirect in onSuccess. */
+    submitApi?: ((data: SignupSubmitData) => Promise<void>) | undefined;
+    /** Called after submitApi succeeds (e.g. router.push('/otp') or next step). */
+    onSuccess?: (() => void) | undefined;
+    /** Called when submitApi rejects or throws. */
+    onError?: ((error: unknown) => void) | undefined;
+}
+/** Return value of the `useSignupForm` hook, providing form state and mode flags. */
+export interface UseSignupFormReturn {
+    /** react-hook-form methods bound to the current signup mode's schema. */
+    methods: UseFormReturn<SignupFormValues>;
+    /** Submit handler to pass to the form's `onSubmit`. Validates and dispatches signup data. */
+    handleSubmit: (data: SignupFormValues) => void;
+    /** True when mode is 'phone', false when mode is 'email'. For 'foreign' same as (mode === 'phone') for layout. */
+    isPhone: boolean;
+    /** True when mode is 'foreign' (full name + email + phone). */
+    isForeign: boolean;
+    /** True when current form values pass validation (for disabling Continue – edge cases 9, 16, 19). */
+    isFormValid: (data: SignupFormValues) => boolean;
+    /** True while submitApi is in flight. */
+    isSubmitting: boolean;
+}