@djangocfg/api 2.1.36 → 2.1.38

package/README.md

@@ -88,13 +88,13 @@ This is handled automatically by `createExtensionAPI()` from `@djangocfg/ext-bas
 
 ## Auth Module
 
-Complete authentication system with React contexts, hooks, and utilities.
+Complete OTP-based authentication system with React contexts, hooks, and utilities.
 
 ### Setup
 
 ```tsx
 // app/layout.tsx
-import { AuthProvider, AccountsProvider } from '@djangocfg/api/auth';
+import { AuthProvider } from '@djangocfg/api/auth';
 
 export default function RootLayout({ children }) {
   return (
@@ -108,9 +108,7 @@ export default function RootLayout({ children }) {
             }
           }}
         >
-          <AccountsProvider>
-            {children}
-          </AccountsProvider>
+          {children}
         </AuthProvider>
       </body>
     </html>
@@ -122,9 +120,9 @@ export default function RootLayout({ children }) {
 
 ```typescript
 import {
-  useAuth,              // Main auth context (user, isAuthenticated, login, logout)
+  useAuth,              // Main auth context (user, isAuthenticated, OTP methods)
   useAuthGuard,         // Protect routes (redirect if not authenticated)
-  useAuthForm,          // Form state management (login, register, reset)
+  useAuthForm,          // OTP form state management (identifier, otp, steps)
   useGithubAuth,        // GitHub OAuth integration
   useAutoAuth,          // Auto-authentication on mount
   useLocalStorage,      // localStorage helper
@@ -134,7 +132,7 @@ import {
 
 ### useAuth
 
-Main authentication hook:
+Main authentication hook with OTP support:
 
 ```tsx
 'use client';
@@ -145,16 +143,15 @@ export function UserProfile() {
     user,              // UserProfile | null
     isAuthenticated,   // boolean
     isLoading,         // boolean
-    login,             // (email, password) => Promise<void>
+    requestOTP,        // (identifier, channel, sourceUrl?) => Promise<{ success, message }>
+    verifyOTP,         // (identifier, otp, channel, sourceUrl?, redirectUrl?) => Promise<{ success, message, user? }>
     logout,            // () => Promise<void>
-    register,          // (data) => Promise<void>
-    updateProfile,     // (data) => Promise<void>
   } = useAuth();
 
   if (isLoading) return <div>Loading...</div>;
 
   if (!isAuthenticated) {
-    return <button onClick={() => login('user@example.com', 'password')}>Login</button>;
+    return <div>Please sign in</div>;
   }
 
   return (
@@ -188,46 +185,98 @@ export default function DashboardPage() {
 
 ### useAuthForm
 
-Manage authentication form state:
+Manage OTP authentication form state (two-step flow):
 
 ```tsx
 'use client';
 import { useAuthForm } from '@djangocfg/api/auth';
 
-export function LoginForm() {
+export function OTPLoginForm() {
   const {
-    email,
-    password,
-    error,
+    // State
+    identifier,        // Email or phone number
+    channel,           // 'email' | 'phone'
+    otp,               // 6-digit OTP code
+    step,              // 'identifier' | 'otp'
     isLoading,
-    setEmail,
-    setPassword,
-    handleLogin,
-    handleRegister,
-    handlePasswordReset,
-  } = useAuthForm();
+    error,
+    acceptedTerms,
+
+    // Setters
+    setIdentifier,
+    setChannel,
+    setOtp,
+    setAcceptedTerms,
+
+    // Handlers
+    handleIdentifierSubmit,  // Request OTP
+    handleOTPSubmit,         // Verify OTP
+    handleResendOTP,         // Resend OTP
+    handleBackToIdentifier,  // Go back to step 1
+
+    // Utilities
+    detectChannelFromIdentifier,
+    validateIdentifier,
+  } = useAuthForm({
+    sourceUrl: window.location.origin,
+    requireTermsAcceptance: false, // Set true if terms/privacy links provided
+    onIdentifierSuccess: (identifier, channel) => {
+      console.log('OTP sent to', identifier);
+    },
+    onOTPSuccess: () => {
+      console.log('Login successful');
+    },
+  });
+
+  if (step === 'identifier') {
+    return (
+      <form onSubmit={handleIdentifierSubmit}>
+        <input
+          type="email"
+          value={identifier}
+          onChange={(e) => setIdentifier(e.target.value)}
+          placeholder="Enter email"
+        />
+        {error && <p className="text-red-500">{error}</p>}
+        <button type="submit" disabled={isLoading}>
+          {isLoading ? 'Sending...' : 'Send verification code'}
+        </button>
+      </form>
+    );
+  }
 
   return (
-    <form onSubmit={(e) => { e.preventDefault(); handleLogin(); }}>
+    <form onSubmit={handleOTPSubmit}>
+      <p>Enter the code sent to {identifier}</p>
       <input
-        type="email"
-        value={email}
-        onChange={(e) => setEmail(e.target.value)}
+        type="text"
+        value={otp}
+        onChange={(e) => setOtp(e.target.value)}
+        placeholder="000000"
+        maxLength={6}
       />
-      <input
-        type="password"
-        value={password}
-        onChange={(e) => setPassword(e.target.value)}
-      />
-      {error && <p>{error}</p>}
-      <button type="submit" disabled={isLoading}>
-        {isLoading ? 'Loading...' : 'Login'}
+      {error && <p className="text-red-500">{error}</p>}
+      <button type="submit" disabled={isLoading || otp.length < 6}>
+        {isLoading ? 'Verifying...' : 'Verify'}
       </button>
+      <button type="button" onClick={handleResendOTP}>Resend</button>
+      <button type="button" onClick={handleBackToIdentifier}>Back</button>
     </form>
   );
 }
 ```
 
+#### useAuthForm Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `sourceUrl` | `string` | required | Application URL for OTP emails |
+| `redirectUrl` | `string` | - | URL to redirect after successful OTP verification |
+| `requireTermsAcceptance` | `boolean` | `false` | Require terms acceptance before submit |
+| `onIdentifierSuccess` | `function` | - | Callback after OTP sent |
+| `onOTPSuccess` | `function` | - | Callback after successful verification |
+| `onError` | `function` | - | Callback on error |
+
 ### useGithubAuth
 
 GitHub OAuth integration:
@@ -238,34 +287,23 @@ import { useGithubAuth } from '@djangocfg/api/auth';
 
 export function GithubLoginButton() {
   const {
-    initiateGithubAuth,  // () => Promise<void>
-    isLoading,           // boolean
-    error,               // string | null
-  } = useGithubAuth();
+    startGithubAuth,   // () => void - redirects to GitHub
+    isLoading,         // boolean
+    error,             // string | null
+  } = useGithubAuth({
+    sourceUrl: window.location.origin,
+  });
 
   return (
-    <button onClick={initiateGithubAuth} disabled={isLoading}>
-      {isLoading ? 'Connecting...' : 'Login with GitHub'}
+    <button onClick={startGithubAuth} disabled={isLoading}>
+      {isLoading ? 'Connecting...' : 'Continue with GitHub'}
     </button>
   );
 }
-
-// app/auth/callback/github/page.tsx
-'use client';
-import { useGithubAuth } from '@djangocfg/api/auth';
-import { useEffect } from 'react';
-
-export default function GithubCallbackPage() {
-  const { handleGithubCallback } = useGithubAuth();
-
-  useEffect(() => {
-    handleGithubCallback();
-  }, []);
-
-  return <div>Processing GitHub login...</div>;
-}
 ```
 
+OAuth callback is handled automatically by `@djangocfg/layouts` AuthLayout component.
+
 ## Server Components & API Routes
 
 Use fetchers for server-side data fetching: