@djangocfg/api 2.1.57 → 2.1.59

package/src/auth/types/form.ts

@@ -0,0 +1,194 @@
+/**
+ * Auth Form Types
+ *
+ * Single source of truth for auth form state and handlers.
+ * Used by both @djangocfg/api/auth hooks and @djangocfg/layouts/AuthLayout.
+ */
+
+import type { MutableRefObject } from 'react';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Channel & Step Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type AuthChannel = 'email' | 'phone';
+export type AuthStep = 'identifier' | 'otp' | '2fa' | '2fa-setup' | 'success';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Form State
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface AuthFormState {
+  /** Email or phone number */
+  identifier: string;
+  /** Current auth channel */
+  channel: AuthChannel;
+  /** OTP code input */
+  otp: string;
+  /** Loading state */
+  isLoading: boolean;
+  /** Terms acceptance state */
+  acceptedTerms: boolean;
+  /** 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;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Form Handlers
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface AuthFormStateHandlers {
+  setIdentifier: (identifier: string) => 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;
+}
+
+export interface AuthFormSubmitHandlers {
+  handleIdentifierSubmit: (e: React.FormEvent) => Promise<void>;
+  handleOTPSubmit: (e: React.FormEvent) => Promise<void>;
+  handleResendOTP: () => Promise<void>;
+  handleBackToIdentifier: () => void;
+  forceOTPStep: () => void;
+  /** 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;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Validation
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface AuthFormValidation {
+  /** Detect channel from identifier string */
+  detectChannelFromIdentifier: (identifier: string) => AuthChannel | null;
+  /** Validate identifier format */
+  validateIdentifier: (identifier: string, channel?: AuthChannel) => boolean;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Auto-submit (for URL-based OTP)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface AuthFormAutoSubmit {
+  /** Ref to track if auto-submit from URL is in progress */
+  isAutoSubmittingFromUrl: MutableRefObject<boolean>;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 2FA State (from useTwoFactor hook)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface AuthForm2FAState {
+  /** Loading state for 2FA verification */
+  is2FALoading: boolean;
+  /** Warning message from 2FA (e.g., low backup codes) */
+  twoFactorWarning: string | null;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Combined Form Interface
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface AuthFormReturn extends
+  AuthFormState,
+  AuthFormStateHandlers,
+  AuthFormSubmitHandlers,
+  AuthFormValidation,
+  AuthFormAutoSubmit,
+  AuthForm2FAState {}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Hook Options
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface UseAuthFormOptions {
+  /** 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;
+  /** If true, user must accept terms before submitting. Default: false */
+  requireTermsAcceptance?: boolean;
+  /** Path to auth page for auto-OTP detection. Default: '/auth' */
+  authPath?: string;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Layout Context (UI-specific additions)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export 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;
+}
+
+export interface AuthFormContextType extends AuthFormReturn, AuthLayoutConfig {}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Layout Props
+// ─────────────────────────────────────────────────────────────────────────────
+
+export 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;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Help Component Props
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface AuthHelpProps {
+  className?: string;
+  variant?: 'default' | 'compact';
+}

package/src/auth/types/index.ts

@@ -0,0 +1,28 @@
+/**
+ * Auth Types - Single source of truth
+ */
+
+// Form types (for auth forms and layouts)
+export type {
+  AuthChannel,
+  AuthStep,
+  AuthFormState,
+  AuthFormStateHandlers,
+  AuthFormSubmitHandlers,
+  AuthFormValidation,
+  AuthFormAutoSubmit,
+  AuthFormReturn,
+  UseAuthFormOptions,
+  AuthLayoutConfig,
+  AuthFormContextType,
+  AuthLayoutProps,
+  AuthHelpProps,
+} from './form';
+
+// Re-export context types
+export type {
+  UserProfile,
+  AuthConfig,
+  AuthContextType,
+  AuthProviderProps,
+} from '../context/types';

package/src/clients.ts

@@ -10,6 +10,7 @@
 
 import { API as AccountsAPIClass, LocalStorageAdapter } from './generated/cfg_accounts';
 import { API as CentrifugoAPIClass } from './generated/cfg_centrifugo';
+import { API as TotpAPIClass } from './generated/cfg_totp';
 import { API as WebPushAPIClass } from './generated/cfg_webpush';
 
 // ============================================================================
@@ -20,6 +21,7 @@ const apiUrl = isStaticBuild ? '' : process.env.NEXT_PUBLIC_API_URL || '';
 const storage = new LocalStorageAdapter();
 
 export const apiAccounts = new AccountsAPIClass(apiUrl, { storage });
+export const apiTotp = new TotpAPIClass(apiUrl, { storage });
 export const apiWebPush = new WebPushAPIClass(apiUrl, { storage });
 export const apiCentrifugo = new CentrifugoAPIClass(apiUrl, { storage });
 
@@ -49,9 +51,17 @@ export * as CentrifugoHooks from './generated/cfg_centrifugo/_utils/hooks';
 export * as CentrifugoFetchers from './generated/cfg_centrifugo/_utils/fetchers';
 export * as CentrifugoTypes from './generated/cfg_centrifugo/_utils/schemas';
 
+// ============================================================================
+// CFG TOTP (namespaced to avoid conflicts)
+// ============================================================================
+export * as TotpHooks from './generated/cfg_totp/_utils/hooks';
+export * as TotpFetchers from './generated/cfg_totp/_utils/fetchers';
+export * as TotpTypes from './generated/cfg_totp/_utils/schemas';
+
 // ============================================================================
 // API Classes (for creating custom instances)
 // ============================================================================
 export { API as AccountsAPI } from './generated/cfg_accounts';
+export { API as TotpAPI } from './generated/cfg_totp';
 export { API as WebPushAPI } from './generated/cfg_webpush';
 export { API as CentrifugoAPI } from './generated/cfg_centrifugo';

package/src/generated/cfg_accounts/_utils/schemas/OAuthTokenResponse.schema.ts

@@ -3,18 +3,41 @@
  *
  * This schema provides runtime validation and type inference.
  *  * Response with JWT tokens after OAuth authentication.
+
+When 2FA is required:
+- requires_2fa: True
+- session_id: UUID of 2FA verification session
+- access/refresh/user: null
+
+When 2FA is not required:
+- requires_2fa: False
+- session_id: null
+- access/refresh/user: populated
  *  */
 import { z } from 'zod'
 
 /**
  * Response with JWT tokens after OAuth authentication.
+
+When 2FA is required:
+- requires_2fa: True
+- session_id: UUID of 2FA verification session
+- access/refresh/user: null
+
+When 2FA is not required:
+- requires_2fa: False
+- session_id: null
+- access/refresh/user: populated
  */
 export const OAuthTokenResponseSchema = z.object({
-  access: z.string(),
-  refresh: z.string(),
-  user: z.record(z.string(), z.any()),
+  requires_2fa: z.boolean().optional(),
+  session_id: z.string().regex(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i).nullable().optional(),
+  access: z.string().nullable().optional(),
+  refresh: z.string().nullable().optional(),
+  user: z.record(z.string(), z.any()).nullable().optional(),
   is_new_user: z.boolean(),
   is_new_connection: z.boolean(),
+  should_prompt_2fa: z.boolean().optional(),
 })
 
 /**

package/src/generated/cfg_accounts/_utils/schemas/OTPVerifyResponse.schema.ts

@@ -3,17 +3,40 @@
  *
  * 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
  *  */
 import { z } from 'zod'
 import { UserSchema } from './User.schema'
 
 /**
  * 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
  */
 export const OTPVerifyResponseSchema = z.object({
-  refresh: z.string(),
-  access: z.string(),
-  user: UserSchema,
+  requires_2fa: z.boolean().optional(),
+  session_id: z.string().regex(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i).nullable().optional(),
+  refresh: z.string().nullable().optional(),
+  access: z.string().nullable().optional(),
+  user: UserSchema.nullable().optional(),
+  should_prompt_2fa: z.boolean().optional(),
 })
 
 /**

package/src/generated/cfg_accounts/accounts/client.ts

@@ -20,7 +20,10 @@ export class Accounts {
   }
 
   /**
-   * Verify OTP code and return JWT tokens.
+   * Verify OTP code and return JWT tokens or 2FA session. If user has 2FA
+   * enabled: - Returns requires_2fa=True with session_id - Client must
+   * complete 2FA verification at /cfg/totp/verify/ If user has no 2FA: -
+   * Returns JWT tokens and user data directly
    */
   async otpVerifyCreate(data: Models.OTPVerifyRequest): Promise<Models.OTPVerifyResponse> {
     const response = await this.client.request('POST', "/cfg/accounts/otp/verify/", { body: data });

package/src/generated/cfg_accounts/accounts/models.ts

@@ -57,16 +57,25 @@ export interface OTPVerifyRequest {
 }
 
 /**
- * OTP verification response.
+ * 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
  * 
  * Response model (includes read-only fields).
  */
 export interface OTPVerifyResponse {
-  /** JWT refresh token */
-  refresh: string;
-  /** JWT access token */
-  access: string;
-  user: User;
+  /** Whether 2FA verification is required */
+  requires_2fa?: boolean;
+  /** 2FA session ID (if requires_2fa is True) */
+  session_id?: string | null;
+  /** JWT refresh token (if requires_2fa is False) */
+  refresh?: string | null;
+  /** JWT access token (if requires_2fa is False) */
+  access?: string | null;
+  user?: User | null;
+  /** Whether user should be prompted to enable 2FA */
+  should_prompt_2fa?: boolean;
 }
 
 /**

package/src/generated/cfg_accounts/accounts__oauth/models.ts

@@ -64,21 +64,30 @@ export interface OAuthCallbackRequestRequest {
 }
 
 /**
- * Response with JWT tokens after OAuth authentication.
+ * Response with JWT tokens after OAuth authentication. When 2FA is required: -
+ * requires_2fa: True - session_id: UUID of 2FA verification session -
+ * access/refresh/user: null When 2FA is not required: - requires_2fa: False -
+ * session_id: null - access/refresh/user: populated
  * 
  * Response model (includes read-only fields).
  */
 export interface OAuthTokenResponse {
-  /** JWT access token */
-  access: string;
-  /** JWT refresh token */
-  refresh: string;
-  /** Authenticated user info */
-  user: Record<string, any>;
+  /** True if 2FA verification is required */
+  requires_2fa?: boolean;
+  /** 2FA session ID (only when requires_2fa=True) */
+  session_id?: string | null;
+  /** JWT access token (null when requires_2fa=True) */
+  access?: string | null;
+  /** JWT refresh token (null when requires_2fa=True) */
+  refresh?: string | null;
+  /** Authenticated user info (null when requires_2fa=True) */
+  user?: Record<string, any> | null;
   /** True if a new user was created during this OAuth flow */
   is_new_user: boolean;
   /** True if a new OAuth connection was created */
   is_new_connection: boolean;
+  /** True if user should be prompted to enable 2FA */
+  should_prompt_2fa?: boolean;
 }
 
 /**

package/src/generated/cfg_accounts/client.ts

@@ -89,6 +89,7 @@ export class APIClient {
       params?: Record<string, any>;
       body?: any;
       formData?: FormData;
+      binaryBody?: Blob | ArrayBuffer;
       headers?: Record<string, string>;
     }
   ): Promise<T> {
@@ -125,6 +126,7 @@ export class APIClient {
       params?: Record<string, any>;
       body?: any;
       formData?: FormData;
+      binaryBody?: Blob | ArrayBuffer;
       headers?: Record<string, string>;
     }
   ): Promise<T> {
@@ -138,8 +140,8 @@ export class APIClient {
       ...(options?.headers || {})
     };
 
-    // Don't set Content-Type for FormData (browser will set it with boundary)
-    if (!options?.formData && !headers['Content-Type']) {
+    // Don't set Content-Type for FormData/binaryBody (browser will set it with boundary)
+    if (!options?.formData && !options?.binaryBody && !headers['Content-Type']) {
       headers['Content-Type'] = 'application/json';
     }
 
@@ -166,6 +168,7 @@ export class APIClient {
         params: options?.params,
         body: options?.body,
         formData: options?.formData,
+        binaryBody: options?.binaryBody,
       });
 
       const duration = Date.now() - startTime;

package/src/generated/cfg_accounts/http.ts

@@ -14,6 +14,8 @@ export interface HttpRequest {
   params?: Record<string, any>;
   /** FormData for file uploads (multipart/form-data) */
   formData?: FormData;
+  /** Binary data for octet-stream uploads */
+  binaryBody?: Blob | ArrayBuffer;
 }
 
 export interface HttpResponse<T = any> {
@@ -37,7 +39,7 @@ export interface HttpClientAdapter {
  */
 export class FetchAdapter implements HttpClientAdapter {
   async request<T = any>(request: HttpRequest): Promise<HttpResponse<T>> {
-    const { method, url, headers, body, params, formData } = request;
+    const { method, url, headers, body, params, formData, binaryBody } = request;
 
     // Build URL with query params
     let finalUrl = url;
@@ -58,12 +60,16 @@ export class FetchAdapter implements HttpClientAdapter {
     const finalHeaders: Record<string, string> = { ...headers };
 
     // Determine body and content-type
-    let requestBody: string | FormData | undefined;
+    let requestBody: string | FormData | Blob | ArrayBuffer | undefined;
 
     if (formData) {
       // For multipart/form-data, let browser set Content-Type with boundary
       requestBody = formData;
       // Don't set Content-Type - browser will set it with boundary
+    } else if (binaryBody) {
+      // Binary upload (application/octet-stream)
+      finalHeaders['Content-Type'] = 'application/octet-stream';
+      requestBody = binaryBody;
     } else if (body) {
       // JSON request
       finalHeaders['Content-Type'] = 'application/json';

package/src/generated/cfg_accounts/schema.json

@@ -326,7 +326,7 @@
     "/cfg/accounts/otp/verify/": {
       "post": {
         "operationId": "cfg_accounts_otp_verify_create",
-        "description": "Verify OTP code and return JWT tokens.",
+        "description": "Verify OTP code and return JWT tokens or 2FA session.\n\nIf user has 2FA enabled:\n- Returns requires_2fa=True with session_id\n- Client must complete 2FA verification at /cfg/totp/verify/\n\nIf user has no 2FA:\n- Returns JWT tokens and user data directly",
         "tags": [
           "accounts"
         ],
@@ -1078,20 +1078,34 @@
       },
       "OAuthTokenResponse": {
         "type": "object",
-        "description": "Response with JWT tokens after OAuth authentication.",
+        "description": "Response with JWT tokens after OAuth authentication.\n\nWhen 2FA is required:\n- requires_2fa: True\n- session_id: UUID of 2FA verification session\n- access/refresh/user: null\n\nWhen 2FA is not required:\n- requires_2fa: False\n- session_id: null\n- access/refresh/user: populated",
         "properties": {
+          "requires_2fa": {
+            "type": "boolean",
+            "default": false,
+            "description": "True if 2FA verification is required"
+          },
+          "session_id": {
+            "type": "string",
+            "format": "uuid",
+            "nullable": true,
+            "description": "2FA session ID (only when requires_2fa=True)"
+          },
           "access": {
             "type": "string",
-            "description": "JWT access token"
+            "nullable": true,
+            "description": "JWT access token (null when requires_2fa=True)"
           },
           "refresh": {
             "type": "string",
-            "description": "JWT refresh token"
+            "nullable": true,
+            "description": "JWT refresh token (null when requires_2fa=True)"
           },
           "user": {
             "type": "object",
             "additionalProperties": {},
-            "description": "Authenticated user info"
+            "nullable": true,
+            "description": "Authenticated user info (null when requires_2fa=True)"
           },
           "is_new_user": {
             "type": "boolean",
@@ -1100,14 +1114,15 @@
           "is_new_connection": {
             "type": "boolean",
             "description": "True if a new OAuth connection was created"
+          },
+          "should_prompt_2fa": {
+            "type": "boolean",
+            "description": "True if user should be prompted to enable 2FA"
           }
         },
         "required": [
-          "access",
           "is_new_connection",
-          "is_new_user",
-          "refresh",
-          "user"
+          "is_new_user"
         ]
       },
       "OTPErrorResponse": {
@@ -1200,15 +1215,28 @@
       },
       "OTPVerifyResponse": {
         "type": "object",
-        "description": "OTP verification response.",
+        "description": "OTP verification response.\n\nWhen 2FA is required:\n- requires_2fa: True\n- session_id: UUID of 2FA verification session\n- refresh/access/user: null\n\nWhen 2FA is not required:\n- requires_2fa: False\n- session_id: null\n- refresh/access/user: populated",
         "properties": {
+          "requires_2fa": {
+            "type": "boolean",
+            "default": false,
+            "description": "Whether 2FA verification is required"
+          },
+          "session_id": {
+            "type": "string",
+            "format": "uuid",
+            "nullable": true,
+            "description": "2FA session ID (if requires_2fa is True)"
+          },
           "refresh": {
             "type": "string",
-            "description": "JWT refresh token"
+            "nullable": true,
+            "description": "JWT refresh token (if requires_2fa is False)"
           },
           "access": {
             "type": "string",
-            "description": "JWT access token"
+            "nullable": true,
+            "description": "JWT access token (if requires_2fa is False)"
           },
           "user": {
             "allOf": [
@@ -1216,14 +1244,14 @@
                 "$ref": "#/components/schemas/User"
               }
             ],
-            "description": "User information"
+            "nullable": true,
+            "description": "User information (if requires_2fa is False)"
+          },
+          "should_prompt_2fa": {
+            "type": "boolean",
+            "description": "Whether user should be prompted to enable 2FA"
           }
-        },
-        "required": [
-          "access",
-          "refresh",
-          "user"
-        ]
+        }
       },
       "PatchedUserProfileUpdateRequest": {
         "type": "object",

package/src/generated/cfg_centrifugo/client.ts

@@ -89,6 +89,7 @@ export class APIClient {
       params?: Record<string, any>;
       body?: any;
       formData?: FormData;
+      binaryBody?: Blob | ArrayBuffer;
       headers?: Record<string, string>;
     }
   ): Promise<T> {
@@ -125,6 +126,7 @@ export class APIClient {
       params?: Record<string, any>;
       body?: any;
       formData?: FormData;
+      binaryBody?: Blob | ArrayBuffer;
       headers?: Record<string, string>;
     }
   ): Promise<T> {
@@ -138,8 +140,8 @@ export class APIClient {
       ...(options?.headers || {})
     };
 
-    // Don't set Content-Type for FormData (browser will set it with boundary)
-    if (!options?.formData && !headers['Content-Type']) {
+    // Don't set Content-Type for FormData/binaryBody (browser will set it with boundary)
+    if (!options?.formData && !options?.binaryBody && !headers['Content-Type']) {
       headers['Content-Type'] = 'application/json';
     }
 
@@ -166,6 +168,7 @@ export class APIClient {
         params: options?.params,
         body: options?.body,
         formData: options?.formData,
+        binaryBody: options?.binaryBody,
       });
 
       const duration = Date.now() - startTime;