@djangocfg/api 2.1.459 → 2.1.462

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/api",
-  "version": "2.1.459",
+  "version": "2.1.462",
   "description": "Auto-generated TypeScript API client with React hooks, SWR integration, and Zod validation for Django REST Framework backends",
   "keywords": [
     "django",
@@ -84,7 +84,7 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@djangocfg/typescript-config": "^2.1.459",
+    "@djangocfg/typescript-config": "^2.1.462",
     "@testing-library/react": "^16.3.2",
     "@types/node": "^25.2.3",
     "@types/react": "^19.2.15",

package/src/auth/__tests__/useAuthForm.2fa.test.ts

@@ -35,8 +35,8 @@ vi.mock('../context', () => ({
   }),
 }));
 
-vi.mock('../hooks/useTwoFactor', () => ({
-  useTwoFactor: () => ({
+vi.mock('../hooks/useTwoFactorVerify', () => ({
+  useTwoFactorVerify: () => ({
     isLoading: false,
     warning: null,
     verifyTOTP: vi.fn(),

package/src/auth/hooks/index.ts

@@ -20,19 +20,23 @@ export { useAutoAuth, type UseAutoAuthOptions } from './useAutoAuth';
 // OAuth
 export { useGithubAuth, type UseGithubAuthOptions, type UseGithubAuthReturn } from './useGithubAuth';
 
-// 2FA hooks
-export { useTwoFactor, type UseTwoFactorOptions, type UseTwoFactorReturn } from './useTwoFactor';
+// 2FA — one consolidated hook (verify / setup / status namespaces),
+// plus the underlying sub-hooks for single-concern consumers.
 export {
+  useTwoFactor,
+  useTwoFactorVerify,
   useTwoFactorSetup,
+  useTwoFactorStatus,
+  type UseTwoFactorOptions,
+  type UseTwoFactorReturn,
+  type UseTwoFactorVerifyOptions,
+  type UseTwoFactorVerifyReturn,
   type UseTwoFactorSetupOptions,
   type UseTwoFactorSetupReturn,
-  type TwoFactorSetupData,
-} from './useTwoFactorSetup';
-export {
-  useTwoFactorStatus,
   type UseTwoFactorStatusReturn,
+  type TwoFactorSetupData,
   type TwoFactorDevice,
-} from './useTwoFactorStatus';
+} from './useTwoFactor';
 
 // Auth guards and redirects
 export {

package/src/auth/hooks/twoFactor.shared.ts

@@ -0,0 +1,54 @@
+'use client';
+
+import { APIError } from '../../_api/generated/helpers';
+
+/**
+ * Shared internals for the 2FA hook family (verify / setup / status).
+ *
+ * Before consolidation each of the three hooks re-implemented error extraction
+ * and 6-digit validation slightly differently — three copies that drifted. This
+ * module is the single source for both, so every 2FA verb reports errors and
+ * validates codes identically.
+ */
+
+const TOTP_CODE_LENGTH = 6;
+
+/** A 2FA API error body may carry any of these message-ish fields. */
+interface TwoFactorErrorBody {
+  error?: unknown;
+  detail?: unknown;
+  message?: unknown;
+  attempts_remaining?: unknown;
+}
+
+/**
+ * Extract a human-readable message from a thrown error, unwrapping the
+ * APIError response body (error → detail → message) before falling back.
+ */
+export function extractTwoFactorError(err: unknown, fallback: string): string {
+  if (err instanceof APIError) {
+    const body = (err.response ?? null) as TwoFactorErrorBody | null;
+    if (typeof body?.error === 'string') return body.error;
+    if (typeof body?.detail === 'string') return body.detail;
+    if (typeof body?.message === 'string') return body.message;
+    return err.errorMessage ?? err.message;
+  }
+  if (err instanceof Error) return err.message;
+  return fallback;
+}
+
+/** Pull `attempts_remaining` off an APIError body, or null if absent. */
+export function extractAttemptsRemaining(err: unknown): number | null {
+  if (err instanceof APIError) {
+    const body = (err.response ?? null) as TwoFactorErrorBody | null;
+    if (typeof body?.attempts_remaining === 'number') return body.attempts_remaining;
+  }
+  return null;
+}
+
+/** True when `code` is a well-formed 6-digit TOTP code. */
+export function isValidTotpCode(code: string): boolean {
+  return !!code && code.length === TOTP_CODE_LENGTH;
+}
+
+export { TOTP_CODE_LENGTH };

package/src/auth/hooks/useAuthForm.ts

@@ -8,7 +8,7 @@ import { authLogger } from '../utils/logger';
 import { useAuthFormState } from './useAuthFormState';
 import { useAuthValidation } from './useAuthValidation';
 import { useAutoAuth } from './useAutoAuth';
-import { useTwoFactor } from './useTwoFactor';
+import { useTwoFactorVerify } from './useTwoFactorVerify';
 
 import type { AuthFormReturn, UseAuthFormOptions } from '../types';
 /**
@@ -70,7 +70,7 @@ export const useAuthForm = (options: UseAuthFormOptions): AuthFormReturn => {
   } = formState;
 
   // 2FA verification hook - skip redirect so we can show success screen
-  const twoFactor = useTwoFactor({
+  const twoFactor = useTwoFactorVerify({
     onSuccess: () => {
       authLogger.info('2FA verification successful, showing success screen');
       setStep('success');

package/src/auth/hooks/useTwoFactor.ts

@@ -1,262 +1,76 @@
 'use client';
 
-import { useCallback, useState } from 'react';
-
-import { apiTotp } from '../../clients';
-import { auth } from '../../_api/generated/helpers/auth';
-import { APIError } from '../../_api/generated/helpers';
-import { CfgTotp, CfgTotpVerify } from '../../_api/generated/sdk.gen';
-import { Analytics, AnalyticsCategory, AnalyticsEvent } from '../utils/analytics';
-import { authLogger } from '../utils/logger';
-import { consumeSavedRedirect } from './useAuthRedirect';
-import { useCfgRouter } from './useCfgRouter';
+import {
+  useTwoFactorVerify,
+  type UseTwoFactorVerifyOptions,
+  type UseTwoFactorVerifyReturn,
+} from './useTwoFactorVerify';
+import {
+  useTwoFactorSetup,
+  type TwoFactorSetupData,
+  type UseTwoFactorSetupOptions,
+  type UseTwoFactorSetupReturn,
+} from './useTwoFactorSetup';
+import {
+  useTwoFactorStatus,
+  type TwoFactorDevice,
+  type UseTwoFactorStatusReturn,
+} from './useTwoFactorStatus';
 
 export 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;
+  /** Options for the login-time verification namespace */
+  verify?: UseTwoFactorVerifyOptions;
+  /** Options for the setup (enable) namespace */
+  setup?: UseTwoFactorSetupOptions;
 }
 
 export 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;
-  /** Remaining verification attempts before lockout */
-  attemptsRemaining: 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;
+  /** Verify a 2FA challenge during login (TOTP / backup code). */
+  verify: UseTwoFactorVerifyReturn;
+  /** Enable 2FA — QR provisioning → confirm → backup codes. */
+  setup: UseTwoFactorSetupReturn;
+  /** Read device list / enabled flag and disable 2FA. */
+  status: UseTwoFactorStatusReturn;
 }
 
 /**
- * Hook for 2FA verification during login.
+ * Single entry point for all two-factor authentication flows.
  *
- * 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
+ * The three concerns — **verify** (login), **setup** (enable) and **status**
+ * (manage/disable) — are distinct verbs over the same `CfgTotp*` API, so each
+ * is exposed as its own namespace with an independent loading/error surface:
  *
  * @example
  * ```tsx
- * const { isLoading, error, verifyTOTP, verifyBackupCode } = useTwoFactor({
- *   onSuccess: (user) => console.log('Logged in:', user),
- *   onError: (error) => console.error(error),
- *   redirectUrl: '/dashboard',
- * });
+ * const two = useTwoFactor({ verify: { redirectUrl: '/dashboard' } });
  *
- * const handleSubmit = async (code: string) => {
- *   if (useBackupCode) {
- *     await verifyBackupCode(sessionId, code);
- *   } else {
- *     await verifyTOTP(sessionId, code);
- *   }
- * };
+ * await two.verify.verifyTOTP(sessionId, code); // login
+ * await two.setup.startSetup('My iPhone');       // enable
+ * await two.status.fetchStatus();                // manage
  * ```
+ *
+ * Consumers that only need one concern can compose the underlying hooks
+ * directly (`useTwoFactorVerify` / `useTwoFactorSetup` / `useTwoFactorStatus`),
+ * all re-exported alongside this one, to avoid mounting the others' state.
  */
 export const useTwoFactor = (options: UseTwoFactorOptions = {}): UseTwoFactorReturn => {
-  const { onSuccess, onError, redirectUrl, skipRedirect = false } = options;
-  const router = useCfgRouter();
-
-  const [isLoading, setIsLoading] = useState(false);
-  const [error, setError] = useState<string | null>(null);
-  const [warning, setWarning] = useState<string | null>(null);
-  const [remainingBackupCodes, setRemainingBackupCodes] = useState<number | null>(null);
-  const [attemptsRemaining, setAttemptsRemaining] = useState<number | null>(null);
-
-  const clearError = useCallback(() => {
-    setError(null);
-  }, []);
-
-  /**
-   * Handle successful 2FA verification
-   */
-  const handleSuccess = useCallback((response: {
-    access_token: string;
-    refresh_token: string;
-    user: any;
-    warning?: string;
-    remaining_backup_codes?: number;
-  }) => {
-    // Save tokens — the ONE write path (atomic pair + session notification).
-    auth.setSession({ access: response.access_token, refresh: response.refresh_token });
-
-    // Set warning if any
-    if (response.warning) {
-      setWarning(response.warning);
-    }
-
-    // Set remaining backup codes if provided
-    if (response.remaining_backup_codes !== undefined) {
-      setRemainingBackupCodes(response.remaining_backup_codes);
-    }
-
-    // Track successful 2FA
-    Analytics.event(AnalyticsEvent.AUTH_LOGIN_SUCCESS, {
-      category: AnalyticsCategory.AUTH,
-      label: '2fa',
-    });
-
-    // Set user ID for tracking
-    if (response.user?.id) {
-      Analytics.setUser(String(response.user.id));
-    }
-
-    // Call success callback
-    onSuccess?.(response.user);
-
-    // Redirect (unless skipRedirect is true).
-    // Priority: saved back-url (guard intent) > explicit option > default.
-    if (!skipRedirect) {
-      const finalRedirectUrl = consumeSavedRedirect() || redirectUrl || '/';
-      authLogger.info('2FA successful, redirecting to:', finalRedirectUrl);
-      router.hardPush(finalRedirectUrl);
-    }
-  }, [onSuccess, redirectUrl, router, skipRedirect]);
-
-  /**
-   * Verify TOTP code from authenticator app
-   */
-  const verifyTOTP = useCallback(async (sessionId: string, code: string): Promise<boolean> => {
-    if (!sessionId) {
-      const msg = 'Missing 2FA session ID';
-      setError(msg);
-      onError?.(msg);
-      return false;
-    }
-
-    if (!code || code.length !== 6) {
-      const msg = 'Please enter a 6-digit code';
-      setError(msg);
-      onError?.(msg);
-      return false;
-    }
-
-    setIsLoading(true);
-    setError(null);
-
-    try {
-      authLogger.info('Verifying TOTP code...');
-
-      const result = await CfgTotpVerify.cfgTotpVerifyCreate({
-        body: { session_id: sessionId, code },
-        throwOnError: true,
-      });
-      const response = result.data;
+  const verify = useTwoFactorVerify(options.verify);
+  const setup = useTwoFactorSetup(options.setup);
+  const status = useTwoFactorStatus();
 
-      if (!response.access_token || !response.refresh_token) {
-        throw new Error('Invalid response from 2FA verification');
-      }
-
-      handleSuccess(response);
-      return true;
-
-    } catch (err) {
-      authLogger.error('2FA TOTP verification error:', err);
-      const errorMessage = err instanceof APIError
-        ? (err.response?.error || err.response?.detail || err.response?.message || err.errorMessage)
-        : (err instanceof Error ? err.message : 'Invalid verification code');
-      if (err instanceof APIError && typeof err.response?.attempts_remaining === 'number') {
-        setAttemptsRemaining(err.response.attempts_remaining);
-      }
-      setError(errorMessage);
-      onError?.(errorMessage);
-
-      // Track failed 2FA
-      Analytics.event(AnalyticsEvent.AUTH_OTP_VERIFY_FAIL, {
-        category: AnalyticsCategory.AUTH,
-        label: '2fa-totp',
-      });
-
-      return false;
-    } finally {
-      setIsLoading(false);
-    }
-  }, [handleSuccess, onError]);
-
-  /**
-   * Verify backup recovery code
-   */
-  const verifyBackupCode = useCallback(async (sessionId: string, backupCode: string): Promise<boolean> => {
-    if (!sessionId) {
-      const msg = 'Missing 2FA session ID';
-      setError(msg);
-      onError?.(msg);
-      return false;
-    }
-
-    if (!backupCode || backupCode.length < 8) {
-      const msg = 'Please enter your backup code';
-      setError(msg);
-      onError?.(msg);
-      return false;
-    }
-
-    setIsLoading(true);
-    setError(null);
-
-    try {
-      authLogger.info('Verifying backup code...');
-
-      const result = await CfgTotpVerify.cfgTotpVerifyBackupCreate({
-        body: {
-          session_id: sessionId,
-          backup_code: backupCode.replace(/\s+/g, ''),
-        },
-        throwOnError: true,
-      });
-      const response = result.data;
-
-      if (!response.access_token || !response.refresh_token) {
-        throw new Error('Invalid response from backup code verification');
-      }
-
-      handleSuccess(response);
-      return true;
-
-    } catch (err) {
-      authLogger.error('2FA backup code verification error:', err);
-      const errorMessage = err instanceof APIError
-        ? (err.response?.error || err.response?.detail || err.response?.message || err.errorMessage)
-        : (err instanceof Error ? err.message : 'Invalid backup code');
-      if (err instanceof APIError && typeof err.response?.attempts_remaining === 'number') {
-        setAttemptsRemaining(err.response.attempts_remaining);
-      }
-      setError(errorMessage);
-      onError?.(errorMessage);
-
-      // Track failed 2FA
-      Analytics.event(AnalyticsEvent.AUTH_OTP_VERIFY_FAIL, {
-        category: AnalyticsCategory.AUTH,
-        label: '2fa-backup',
-      });
-
-      return false;
-    } finally {
-      setIsLoading(false);
-    }
-  }, [handleSuccess, onError]);
+  return { verify, setup, status };
+};
 
-  return {
-    isLoading,
-    error,
-    warning,
-    remainingBackupCodes,
-    attemptsRemaining,
-    verifyTOTP,
-    verifyBackupCode,
-    clearError,
-  };
+// Namespaced sub-hooks — use directly when only one concern is needed.
+export {
+  useTwoFactorVerify,
+  useTwoFactorSetup,
+  useTwoFactorStatus,
+  type UseTwoFactorVerifyOptions,
+  type UseTwoFactorVerifyReturn,
+  type UseTwoFactorSetupOptions,
+  type UseTwoFactorSetupReturn,
+  type UseTwoFactorStatusReturn,
+  type TwoFactorSetupData,
+  type TwoFactorDevice,
 };

package/src/auth/hooks/useTwoFactorSetup.ts

@@ -2,9 +2,9 @@
 
 import { useCallback, useState } from 'react';
 
-import { apiTotp } from '../../clients';
 import { CfgTotpSetup } from '../../_api/generated/sdk.gen';
 import { authLogger } from '../utils/logger';
+import { extractTwoFactorError, isValidTotpCode } from './twoFactor.shared';
 
 export interface TwoFactorSetupData {
   /** Device ID to use for confirmation */
@@ -50,40 +50,13 @@ export interface UseTwoFactorSetupReturn {
 }
 
 /**
- * Hook for 2FA setup (enabling TOTP authentication).
+ * 2FA setup — enabling TOTP (internal, composed by {@link useTwoFactor}).
  *
- * 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');
- * ```
+ * Flow: startSetup() → user scans QR → confirmSetup(code) → show backup codes.
  */
-export const useTwoFactorSetup = (options: UseTwoFactorSetupOptions = {}): UseTwoFactorSetupReturn => {
+export const useTwoFactorSetup = (
+  options: UseTwoFactorSetupOptions = {},
+): UseTwoFactorSetupReturn => {
   const { onComplete, onError } = options;
 
   const [isLoading, setIsLoading] = useState(false);
@@ -105,9 +78,6 @@ export const useTwoFactorSetup = (options: UseTwoFactorSetupOptions = {}): UseTw
     setError(null);
   }, []);
 
-  /**
-   * Start 2FA setup - generates QR code and secret
-   */
   const startSetup = useCallback(async (deviceName?: string): Promise<TwoFactorSetupData | null> => {
     setIsLoading(true);
     setError(null);
@@ -134,9 +104,8 @@ export const useTwoFactorSetup = (options: UseTwoFactorSetupOptions = {}): UseTw
       authLogger.info('2FA setup initiated, expires in:', data.expiresIn, 'seconds');
 
       return data;
-
     } catch (err) {
-      const errorMessage = err instanceof Error ? err.message : 'Failed to start 2FA setup';
+      const errorMessage = extractTwoFactorError(err, 'Failed to start 2FA setup');
       authLogger.error('2FA setup error:', err);
       setError(errorMessage);
       setSetupStep('idle');
@@ -147,9 +116,6 @@ export const useTwoFactorSetup = (options: UseTwoFactorSetupOptions = {}): UseTw
     }
   }, [onError]);
 
-  /**
-   * Confirm 2FA setup with TOTP code from authenticator app
-   */
   const confirmSetup = useCallback(async (code: string): Promise<string[] | null> => {
     if (!setupData) {
       const msg = 'Setup not started. Call startSetup() first.';
@@ -157,8 +123,7 @@ export const useTwoFactorSetup = (options: UseTwoFactorSetupOptions = {}): UseTw
       onError?.(msg);
       return null;
     }
-
-    if (!code || code.length !== 6) {
+    if (!isValidTotpCode(code)) {
       const msg = 'Please enter a 6-digit code';
       setError(msg);
       onError?.(msg);
@@ -185,13 +150,10 @@ export const useTwoFactorSetup = (options: UseTwoFactorSetupOptions = {}): UseTw
 
       authLogger.info('2FA setup confirmed, backup codes generated:', codes.length);
 
-      // Call completion callback
       onComplete?.(codes);
-
       return codes;
-
     } catch (err) {
-      const errorMessage = err instanceof Error ? err.message : 'Invalid code. Please try again.';
+      const errorMessage = extractTwoFactorError(err, 'Invalid code. Please try again.');
       authLogger.error('2FA setup confirmation error:', err);
       setError(errorMessage);
       setSetupStep('scanning'); // Go back to scanning step

package/src/auth/hooks/useTwoFactorStatus.ts

@@ -2,10 +2,9 @@
 
 import { useCallback, useState } from 'react';
 
-import { apiTotp } from '../../clients';
-import { APIError } from '../../_api/generated/helpers';
 import { CfgTotp } from '../../_api/generated/sdk.gen';
 import { authLogger } from '../utils/logger';
+import { extractTwoFactorError, isValidTotpCode } from './twoFactor.shared';
 
 export interface TwoFactorDevice {
   id: string;
@@ -33,35 +32,10 @@ export interface UseTwoFactorStatusReturn {
 }
 
 /**
- * Hook for checking and managing 2FA status.
+ * Read and manage 2FA status (internal, composed by {@link useTwoFactor}).
  *
- * @example
- * ```tsx
- * const { has2FAEnabled, devices, fetchStatus, disable2FA, isLoading } = useTwoFactorStatus();
- *
- * useEffect(() => {
- *   fetchStatus();
- * }, [fetchStatus]);
- *
- * if (has2FAEnabled) {
- *   // Show disable button
- * } else {
- *   // Show enable button
- * }
- * ```
+ * Fetches the device list / enabled flag and disables 2FA.
  */
-/** Extract a human-readable message from a thrown error. */
-function extractErrorMessage(err: unknown, fallback: string): string {
-  if (err instanceof APIError) {
-    const body = err.response as Record<string, unknown> | null;
-    if (typeof body?.error === 'string') return body.error;
-    if (typeof body?.detail === 'string') return body.detail;
-    return err.message;
-  }
-  if (err instanceof Error) return err.message;
-  return fallback;
-}
-
 export const useTwoFactorStatus = (): UseTwoFactorStatusReturn => {
   const [isLoading, setIsLoading] = useState(false);
   const [error, setError] = useState<string | null>(null);
@@ -72,9 +46,6 @@ export const useTwoFactorStatus = (): UseTwoFactorStatusReturn => {
     setError(null);
   }, []);
 
-  /**
-   * Fetch current 2FA status and devices
-   */
   const fetchStatus = useCallback(async (): Promise<void> => {
     setIsLoading(true);
     setError(null);
@@ -98,9 +69,8 @@ export const useTwoFactorStatus = (): UseTwoFactorStatusReturn => {
       setHas2FAEnabled(response.has_2fa_enabled);
 
       authLogger.info('2FA status:', response.has_2fa_enabled ? 'enabled' : 'disabled');
-
     } catch (err) {
-      const errorMessage = extractErrorMessage(err, 'Failed to fetch 2FA status');
+      const errorMessage = extractTwoFactorError(err, 'Failed to fetch 2FA status');
       authLogger.error('Failed to fetch 2FA status:', err);
       setError(errorMessage);
     } finally {
@@ -108,11 +78,8 @@ export const useTwoFactorStatus = (): UseTwoFactorStatusReturn => {
     }
   }, []);
 
-  /**
-   * Disable 2FA for the account
-   */
   const disable2FA = useCallback(async (code: string): Promise<boolean> => {
-    if (!code || code.length !== 6) {
+    if (!isValidTotpCode(code)) {
       setError('Please enter a 6-digit code');
       return false;
     }
@@ -130,9 +97,8 @@ export const useTwoFactorStatus = (): UseTwoFactorStatusReturn => {
 
       authLogger.info('2FA disabled successfully');
       return true;
-
     } catch (err: unknown) {
-      const errorMessage = extractErrorMessage(err, 'Invalid verification code');
+      const errorMessage = extractTwoFactorError(err, 'Invalid verification code');
       authLogger.error('Failed to disable 2FA:', err);
       setError(errorMessage);
       return false;