@djangocfg/api 2.1.57 → 2.1.58

package/dist/auth.d.ts

@@ -1,4 +1,4 @@
-import React$1, { ReactNode } from 'react';
+import React$1, { ReactNode, MutableRefObject } from 'react';
 import { z } from 'zod';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as consola from 'consola';
@@ -86,15 +86,37 @@ type OTPVerifyRequest = z.infer<typeof OTPVerifyRequestSchema>;
  *
  * This schema provides runtime validation and type inference.
  *  * OTP verification response.
+
+When 2FA is required:
+- requires_2fa: True
+- session_id: UUID of 2FA verification session
+- refresh/access/user: null
+
+When 2FA is not required:
+- requires_2fa: False
+- session_id: null
+- refresh/access/user: populated
  *  */
 
 /**
  * OTP verification response.
+
+When 2FA is required:
+- requires_2fa: True
+- session_id: UUID of 2FA verification session
+- refresh/access/user: null
+
+When 2FA is not required:
+- requires_2fa: False
+- session_id: null
+- refresh/access/user: populated
  */
 declare const OTPVerifyResponseSchema: z.ZodObject<{
-    refresh: z.ZodString;
-    access: z.ZodString;
-    user: z.ZodObject<{
+    requires_2fa: z.ZodOptional<z.ZodBoolean>;
+    session_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    refresh: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    access: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    user: z.ZodOptional<z.ZodNullable<z.ZodObject<{
         id: z.ZodInt;
         email: z.ZodEmail;
         first_name: z.ZodOptional<z.ZodString>;
@@ -117,7 +139,8 @@ declare const OTPVerifyResponseSchema: z.ZodObject<{
             expires_at: z.ZodISODateTime;
             channels: z.ZodArray<z.ZodString>;
         }, z.core.$strip>>;
-    }, z.core.$strip>;
+    }, z.core.$strip>>>;
+    should_prompt_2fa: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 /**
  * Infer TypeScript type from Zod schema
@@ -260,10 +283,13 @@ interface AuthContextType {
         success: boolean;
         message: string;
     }>;
-    verifyOTP: (identifier: string, otpCode: string, channel?: 'email' | 'phone', sourceUrl?: string, redirectUrl?: string) => Promise<{
+    verifyOTP: (identifier: string, otpCode: string, channel?: 'email' | 'phone', sourceUrl?: string, redirectUrl?: string, skipRedirect?: boolean) => Promise<{
         success: boolean;
         message: string;
         user?: UserProfile;
+        requires_2fa?: boolean;
+        session_id?: string | null;
+        should_prompt_2fa?: boolean;
     }>;
     refreshToken: () => Promise<{
         success: boolean;
@@ -302,76 +328,92 @@ interface AccountsProviderProps {
 declare function AccountsProvider({ children }: AccountsProviderProps): react_jsx_runtime.JSX.Element;
 declare function useAccountsContext(): AccountsContextValue;
 
-interface AuthRedirectOptions {
-    fallbackUrl?: string;
-    clearOnUse?: boolean;
-}
-declare const useAuthRedirectManager: (options?: AuthRedirectOptions) => {
-    redirectUrl: string;
-    setRedirect: (url: string) => void;
-    getRedirect: () => string;
-    clearRedirect: () => void;
-    hasRedirect: () => boolean;
-    getFinalRedirectUrl: () => string;
-    useAndClearRedirect: () => string;
-};
-
-interface UseAuthGuardOptions {
-    redirectTo?: string;
-    requireAuth?: boolean;
-    /** Whether to save current URL for redirect after auth (default: true) */
-    saveRedirectUrl?: boolean;
-}
-declare const useAuthGuard: (options?: UseAuthGuardOptions) => {
-    isAuthenticated: boolean;
-    isLoading: boolean;
-    isRedirecting: boolean;
-};
-
-/**
- * Simple sessionStorage hook with better error handling
- * @param key - Storage key
- * @param initialValue - Default value if key doesn't exist
- * @returns [value, setValue, removeValue] - Current value, setter function, and remove function
- */
-declare function useSessionStorage<T>(key: string, initialValue: T): readonly [T, (value: T | ((val: T) => T)) => void, () => void];
-
 /**
- * Simple localStorage hook with better error handling
- * @param key - Storage key
- * @param initialValue - Default value if key doesn't exist
- * @returns [value, setValue, removeValue] - Current value, setter function, and remove function
+ * Auth Form Types
+ *
+ * Single source of truth for auth form state and handlers.
+ * Used by both @djangocfg/api/auth hooks and @djangocfg/layouts/AuthLayout.
  */
-declare function useLocalStorage<T>(key: string, initialValue: T): readonly [T, (value: T | ((val: T) => T)) => void, () => void];
 
+type AuthChannel = 'email' | 'phone';
+type AuthStep = 'identifier' | 'otp' | '2fa' | '2fa-setup' | 'success';
 interface AuthFormState {
+    /** Email or phone number */
     identifier: string;
-    channel: 'email' | 'phone';
+    /** Current auth channel */
+    channel: AuthChannel;
+    /** OTP code input */
     otp: string;
+    /** Loading state */
     isLoading: boolean;
+    /** Terms acceptance state */
     acceptedTerms: boolean;
-    step: 'identifier' | 'otp';
+    /** Current form step */
+    step: AuthStep;
+    /** Error message */
     error: string;
+    /** 2FA session ID from OTP/OAuth verification */
+    twoFactorSessionId: string | null;
+    /** Whether user should be prompted to enable 2FA */
+    shouldPrompt2FA: boolean;
+    /** 2FA code input */
+    twoFactorCode: string;
+    /** Using backup code instead of TOTP */
+    useBackupCode: boolean;
 }
-interface AuthFormHandlers {
+interface AuthFormStateHandlers {
     setIdentifier: (identifier: string) => void;
-    setChannel: (channel: 'email' | 'phone') => void;
+    setChannel: (channel: AuthChannel) => void;
     setOtp: (otp: string) => void;
     setAcceptedTerms: (accepted: boolean) => void;
     setError: (error: string) => void;
     clearError: () => void;
+    setStep: (step: AuthStep) => void;
+    setIsLoading: (loading: boolean) => void;
+    setTwoFactorSessionId: (sessionId: string | null) => void;
+    setShouldPrompt2FA: (prompt: boolean) => void;
+    setTwoFactorCode: (code: string) => void;
+    setUseBackupCode: (useBackup: boolean) => void;
+}
+interface AuthFormSubmitHandlers {
     handleIdentifierSubmit: (e: React.FormEvent) => Promise<void>;
     handleOTPSubmit: (e: React.FormEvent) => Promise<void>;
     handleResendOTP: () => Promise<void>;
     handleBackToIdentifier: () => void;
     forceOTPStep: () => void;
-    detectChannelFromIdentifier: (identifier: string) => 'email' | 'phone' | null;
-    validateIdentifier: (identifier: string, channel?: 'email' | 'phone') => boolean;
+    /** Handle 2FA TOTP/backup code verification */
+    handle2FASubmit: (e: React.FormEvent) => Promise<void>;
+    /** Switch to backup code input */
+    handleUseBackupCode: () => void;
+    /** Switch back to TOTP input */
+    handleUseTOTP: () => void;
+}
+interface AuthFormValidation {
+    /** Detect channel from identifier string */
+    detectChannelFromIdentifier: (identifier: string) => AuthChannel | null;
+    /** Validate identifier format */
+    validateIdentifier: (identifier: string, channel?: AuthChannel) => boolean;
+}
+interface AuthFormAutoSubmit {
+    /** Ref to track if auto-submit from URL is in progress */
+    isAutoSubmittingFromUrl: MutableRefObject<boolean>;
+}
+interface AuthForm2FAState {
+    /** Loading state for 2FA verification */
+    is2FALoading: boolean;
+    /** Warning message from 2FA (e.g., low backup codes) */
+    twoFactorWarning: string | null;
+}
+interface AuthFormReturn extends AuthFormState, AuthFormStateHandlers, AuthFormSubmitHandlers, AuthFormValidation, AuthFormAutoSubmit, AuthForm2FAState {
 }
 interface UseAuthFormOptions {
-    onIdentifierSuccess?: (identifier: string, channel: 'email' | 'phone') => void;
+    /** Callback when identifier step succeeds */
+    onIdentifierSuccess?: (identifier: string, channel: AuthChannel) => void;
+    /** Callback when OTP verification succeeds */
     onOTPSuccess?: () => void;
+    /** Callback on any error */
     onError?: (message: string) => void;
+    /** Source URL for tracking */
     sourceUrl: string;
     /** URL to redirect after successful OTP verification */
     redirectUrl?: string;
@@ -380,7 +422,66 @@ interface UseAuthFormOptions {
     /** Path to auth page for auto-OTP detection. Default: '/auth' */
     authPath?: string;
 }
-declare const useAuthForm: (options: UseAuthFormOptions) => AuthFormState & AuthFormHandlers;
+interface AuthLayoutConfig {
+    /** Support page URL */
+    supportUrl?: string;
+    /** Terms of service URL */
+    termsUrl?: string;
+    /** Privacy policy URL */
+    privacyUrl?: string;
+    /** Source URL for tracking */
+    sourceUrl: string;
+    /** Enable phone authentication tab */
+    enablePhoneAuth?: boolean;
+    /** Enable GitHub OAuth button */
+    enableGithubAuth?: boolean;
+    /** Logo URL for success screen (SVG recommended) */
+    logoUrl?: string;
+    /** URL to redirect after successful auth (default: /dashboard) */
+    redirectUrl?: string;
+}
+interface AuthFormContextType extends AuthFormReturn, AuthLayoutConfig {
+}
+interface AuthLayoutProps extends AuthLayoutConfig {
+    children?: React.ReactNode;
+    className?: string;
+    /** URL to redirect after successful auth (default: /dashboard) */
+    redirectUrl?: string;
+    /** Callback when identifier step succeeds */
+    onIdentifierSuccess?: (identifier: string, channel: AuthChannel) => void;
+    /** Callback when OTP verification succeeds */
+    onOTPSuccess?: () => void;
+    /** Callback when OAuth succeeds */
+    onOAuthSuccess?: (user: any, isNewUser: boolean, provider: string) => void;
+    /** Callback on any error */
+    onError?: (message: string) => void;
+}
+interface AuthHelpProps {
+    className?: string;
+    variant?: 'default' | 'compact';
+}
+
+interface UseAuthFormStateReturn extends AuthFormState, AuthFormStateHandlers {
+}
+/**
+ * Hook for auth form state management.
+ * Pure state - no side effects, no API calls.
+ */
+declare const useAuthFormState: (initialIdentifier?: string, initialChannel?: AuthChannel) => UseAuthFormStateReturn;
+
+/**
+ * Hook for auth identifier validation.
+ * Pure functions - no state, no side effects.
+ */
+declare const useAuthValidation: () => AuthFormValidation;
+declare const detectChannelFromIdentifier: (id: string) => AuthChannel | null;
+declare const validateIdentifier: (id: string, channelType?: AuthChannel) => boolean;
+
+/**
+ * Complete auth form hook.
+ * Composes smaller hooks for state, validation, and submission.
+ */
+declare const useAuthForm: (options: UseAuthFormOptions) => AuthFormReturn;
 
 interface UseAutoAuthOptions {
     onOTPDetected?: (otp: string) => void;
@@ -402,7 +503,11 @@ interface UseGithubAuthOptions {
     sourceUrl?: string;
     onSuccess?: (user: any, isNewUser: boolean) => void;
     onError?: (error: string) => void;
+    /** Callback when 2FA is required */
+    onRequires2FA?: (sessionId: string, shouldPrompt2FA: boolean) => void;
     redirectUrl?: string;
+    /** Skip automatic redirect after success (caller handles navigation) */
+    skipRedirect?: boolean;
 }
 interface UseGithubAuthReturn {
     isLoading: boolean;
@@ -431,6 +536,199 @@ interface UseGithubAuthReturn {
  */
 declare const useGithubAuth: (options?: UseGithubAuthOptions) => UseGithubAuthReturn;
 
+interface UseTwoFactorOptions {
+    /** Callback on successful 2FA verification */
+    onSuccess?: (user: any) => void;
+    /** Callback on error */
+    onError?: (error: string) => void;
+    /** URL to redirect after successful verification */
+    redirectUrl?: string;
+    /** Skip automatic redirect after success (caller handles navigation) */
+    skipRedirect?: boolean;
+}
+interface UseTwoFactorReturn {
+    /** Loading state */
+    isLoading: boolean;
+    /** Error message */
+    error: string | null;
+    /** Warning message (e.g., low backup codes) */
+    warning: string | null;
+    /** Remaining backup codes (if backup code was used) */
+    remainingBackupCodes: number | null;
+    /** Verify TOTP code */
+    verifyTOTP: (sessionId: string, code: string) => Promise<boolean>;
+    /** Verify backup code */
+    verifyBackupCode: (sessionId: string, backupCode: string) => Promise<boolean>;
+    /** Clear error */
+    clearError: () => void;
+}
+/**
+ * Hook for 2FA verification during login.
+ *
+ * Usage:
+ * 1. After OTP/OAuth verification returns requires_2fa=true and session_id
+ * 2. Show 2FA form and collect TOTP code from user
+ * 3. Call verifyTOTP(sessionId, code) to complete authentication
+ *
+ * @example
+ * ```tsx
+ * const { isLoading, error, verifyTOTP, verifyBackupCode } = useTwoFactor({
+ *   onSuccess: (user) => console.log('Logged in:', user),
+ *   onError: (error) => console.error(error),
+ *   redirectUrl: '/dashboard',
+ * });
+ *
+ * const handleSubmit = async (code: string) => {
+ *   if (useBackupCode) {
+ *     await verifyBackupCode(sessionId, code);
+ *   } else {
+ *     await verifyTOTP(sessionId, code);
+ *   }
+ * };
+ * ```
+ */
+declare const useTwoFactor: (options?: UseTwoFactorOptions) => UseTwoFactorReturn;
+
+interface TwoFactorSetupData {
+    /** Device ID to use for confirmation */
+    deviceId: string;
+    /** Base32-encoded TOTP secret (for manual entry) */
+    secret: string;
+    /** otpauth:// URI for QR code generation */
+    provisioningUri: string;
+    /** Base64-encoded QR code image (data URI) */
+    qrCodeBase64: string;
+    /** Seconds until setup expires */
+    expiresIn: number;
+}
+interface UseTwoFactorSetupOptions {
+    /** Callback when setup is confirmed and backup codes are generated */
+    onComplete?: (backupCodes: string[]) => void;
+    /** Callback on error */
+    onError?: (error: string) => void;
+}
+interface UseTwoFactorSetupReturn {
+    /** Loading state */
+    isLoading: boolean;
+    /** Error message */
+    error: string | null;
+    /** Setup data (QR code, secret, etc.) */
+    setupData: TwoFactorSetupData | null;
+    /** Backup codes after confirmation */
+    backupCodes: string[] | null;
+    /** Warning message about backup codes */
+    backupCodesWarning: string | null;
+    /** Current setup step */
+    setupStep: 'idle' | 'scanning' | 'confirming' | 'complete';
+    /** Start 2FA setup - returns QR code data */
+    startSetup: (deviceName?: string) => Promise<TwoFactorSetupData | null>;
+    /** Confirm setup with TOTP code - returns backup codes */
+    confirmSetup: (code: string) => Promise<string[] | null>;
+    /** Reset setup state */
+    resetSetup: () => void;
+    /** Clear error */
+    clearError: () => void;
+}
+/**
+ * Hook for 2FA setup (enabling TOTP authentication).
+ *
+ * Flow:
+ * 1. Call startSetup() to get QR code and provisioning URI
+ * 2. User scans QR code with authenticator app
+ * 3. Call confirmSetup(code) with the 6-digit code from app
+ * 4. Show backup codes to user (they must save these!)
+ *
+ * @example
+ * ```tsx
+ * const {
+ *   isLoading,
+ *   error,
+ *   setupData,
+ *   backupCodes,
+ *   setupStep,
+ *   startSetup,
+ *   confirmSetup,
+ * } = useTwoFactorSetup({
+ *   onComplete: (codes) => console.log('Backup codes:', codes),
+ *   onError: (error) => console.error(error),
+ * });
+ *
+ * // Start setup
+ * const data = await startSetup('My iPhone');
+ *
+ * // Show QR code
+ * <QRCodeSVG value={data.provisioningUri} />
+ *
+ * // Confirm with code from app
+ * const codes = await confirmSetup('123456');
+ * ```
+ */
+declare const useTwoFactorSetup: (options?: UseTwoFactorSetupOptions) => UseTwoFactorSetupReturn;
+
+interface AuthRedirectOptions {
+    fallbackUrl?: string;
+    clearOnUse?: boolean;
+}
+declare const useAuthRedirectManager: (options?: AuthRedirectOptions) => {
+    redirectUrl: string;
+    setRedirect: (url: string) => void;
+    getRedirect: () => string;
+    clearRedirect: () => void;
+    hasRedirect: () => boolean;
+    getFinalRedirectUrl: () => string;
+    useAndClearRedirect: () => string;
+};
+
+interface UseAuthGuardOptions {
+    redirectTo?: string;
+    requireAuth?: boolean;
+    /** Whether to save current URL for redirect after auth (default: true) */
+    saveRedirectUrl?: boolean;
+}
+declare const useAuthGuard: (options?: UseAuthGuardOptions) => {
+    isAuthenticated: boolean;
+    isLoading: boolean;
+    isRedirecting: boolean;
+};
+
+/**
+ * Simple sessionStorage hook with better error handling
+ * @param key - Storage key
+ * @param initialValue - Default value if key doesn't exist
+ * @returns [value, setValue, removeValue] - Current value, setter function, and remove function
+ */
+declare function useSessionStorage<T>(key: string, initialValue: T): readonly [T, (value: T | ((val: T) => T)) => void, () => void];
+
+/**
+ * Simple localStorage hook with better error handling
+ * @param key - Storage key
+ * @param initialValue - Default value if key doesn't exist
+ * @returns [value, setValue, removeValue] - Current value, setter function, and remove function
+ */
+declare function useLocalStorage<T>(key: string, initialValue: T): readonly [T, (value: T | ((val: T) => T)) => void, () => void];
+
+/**
+ * Encode string to base64
+ * @param data - String data to encode
+ * @returns Base64 encoded string (or original in dev mode)
+ */
+declare function encodeBase64(data: string): string;
+/**
+ * Decode base64 to string
+ * @param encoded - Base64 encoded string
+ * @returns Decoded string (or original in dev mode)
+ */
+declare function decodeBase64(encoded: string): string;
+/**
+ * Hook for base64 encoding/decoding
+ * @returns Object with encode and decode functions
+ */
+declare function useBase64(): {
+    encode: typeof encodeBase64;
+    decode: typeof decodeBase64;
+    isDev: boolean;
+};
+
 /**
  * Profile Cache Hook
  *
@@ -473,28 +771,6 @@ declare function getCacheMetadata(): {
     expiresIn?: number;
 } | null;
 
-/**
- * Encode string to base64
- * @param data - String data to encode
- * @returns Base64 encoded string (or original in dev mode)
- */
-declare function encodeBase64(data: string): string;
-/**
- * Decode base64 to string
- * @param encoded - Base64 encoded string
- * @returns Decoded string (or original in dev mode)
- */
-declare function decodeBase64(encoded: string): string;
-/**
- * Hook for base64 encoding/decoding
- * @returns Object with encode and decode functions
- */
-declare function useBase64(): {
-    encode: typeof encodeBase64;
-    decode: typeof decodeBase64;
-    isDev: boolean;
-};
-
 /**
  * Email validation utility
  */
@@ -554,4 +830,4 @@ declare const Analytics: {
     setUser(userId: string): void;
 };
 
-export { type AccountsContextValue, AccountsProvider, Analytics, AnalyticsCategory, type AnalyticsCategoryType, AnalyticsEvent, type AnalyticsEventType, type AuthConfig, type AuthContextType, AuthProvider, type AuthProviderProps, type PatchedUserProfileUpdateRequest, PatchedUserProfileUpdateRequestSchema, type ProfileCacheOptions, type UseGithubAuthOptions, type UseGithubAuthReturn, type UserProfile, authLogger, clearProfileCache, decodeBase64, encodeBase64, formatAuthError, getCacheMetadata, getCachedProfile, hasValidCache, logger, setCachedProfile, useAccountsContext, useAuth, useAuthForm, useAuthGuard, useAuthRedirectManager, useAutoAuth, useBase64, useGithubAuth, useLocalStorage, useSessionStorage, validateEmail };
+export { type AccountsContextValue, AccountsProvider, Analytics, AnalyticsCategory, type AnalyticsCategoryType, AnalyticsEvent, type AnalyticsEventType, type AuthChannel, type AuthConfig, type AuthContextType, type AuthFormAutoSubmit, type AuthFormContextType, type AuthFormReturn, type AuthFormState, type AuthFormStateHandlers, type AuthFormSubmitHandlers, type AuthFormValidation, type AuthHelpProps, type AuthLayoutConfig, type AuthLayoutProps, AuthProvider, type AuthProviderProps, type AuthStep, type PatchedUserProfileUpdateRequest, PatchedUserProfileUpdateRequestSchema, type ProfileCacheOptions, type TwoFactorSetupData, type UseAuthFormOptions, type UseAuthFormStateReturn, type UseAutoAuthOptions, type UseGithubAuthOptions, type UseGithubAuthReturn, type UseTwoFactorOptions, type UseTwoFactorReturn, type UseTwoFactorSetupOptions, type UseTwoFactorSetupReturn, type UserProfile, authLogger, clearProfileCache, decodeBase64, detectChannelFromIdentifier, encodeBase64, formatAuthError, getCacheMetadata, getCachedProfile, hasValidCache, logger, setCachedProfile, useAccountsContext, useAuth, useAuthForm, useAuthFormState, useAuthGuard, useAuthRedirectManager, useAuthValidation, useAutoAuth, useBase64, useGithubAuth, useLocalStorage, useSessionStorage, useTwoFactor, useTwoFactorSetup, validateEmail, validateIdentifier };