@djangocfg/api 2.1.37 → 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:

package/dist/auth.cjs

@@ -3953,7 +3953,6 @@ var defaultRoutes = {
 var AuthContext = (0, import_react2.createContext)(void 0);
 var EMAIL_STORAGE_KEY = "auth_email";
 var PHONE_STORAGE_KEY = "auth_phone";
-var AUTH_REDIRECT_KEY = "auth_redirect_url";
 var hasValidTokens = /* @__PURE__ */ __name(() => {
   if (typeof window === "undefined") return false;
   return api.isAuthenticated();
@@ -3973,7 +3972,6 @@ var AuthProviderInternal = /* @__PURE__ */ __name(({ children, config }) => {
   const queryParams = (0, import_hooks2.useQueryParams)();
   const [storedEmail, setStoredEmail, clearStoredEmail] = (0, import_hooks2.useLocalStorage)(EMAIL_STORAGE_KEY, null);
   const [storedPhone, setStoredPhone, clearStoredPhone] = (0, import_hooks2.useLocalStorage)(PHONE_STORAGE_KEY, null);
-  const [redirectUrl, setRedirectUrl, clearRedirectUrl] = (0, import_hooks2.useLocalStorage)(AUTH_REDIRECT_KEY, null);
   const user = accounts.profile;
   const userRef = (0, import_react2.useRef)(user);
   const configRef = (0, import_react2.useRef)(config);
@@ -4155,7 +4153,7 @@ var AuthProviderInternal = /* @__PURE__ */ __name(({ children, config }) => {
     [accounts]
   );
   const verifyOTP = (0, import_react2.useCallback)(
-    async (identifier, otpCode, channel, sourceUrl) => {
+    async (identifier, otpCode, channel, sourceUrl, redirectUrl) => {
       try {
         const channelValue = channel === "phone" ? enums_exports.OTPVerifyRequestChannel.PHONE : enums_exports.OTPVerifyRequestChannel.EMAIL;
         const result = await accounts.verifyOTP({
@@ -4185,13 +4183,8 @@ var AuthProviderInternal = /* @__PURE__ */ __name(({ children, config }) => {
         if (result.user?.id) {
           Analytics.setUser(String(result.user.id));
         }
-        const defaultCallback = config?.routes?.defaultCallback || defaultRoutes.defaultCallback;
-        if (redirectUrl && redirectUrl !== defaultCallback) {
-          clearRedirectUrl();
-          router.hardPush(redirectUrl);
-        } else {
-          router.hardPush(defaultCallback);
-        }
+        const finalRedirectUrl = redirectUrl || config?.routes?.defaultCallback || defaultRoutes.defaultCallback;
+        router.hardPush(finalRedirectUrl);
         return {
           success: true,
           message: "Login successful",
@@ -4209,7 +4202,7 @@ var AuthProviderInternal = /* @__PURE__ */ __name(({ children, config }) => {
         };
       }
     },
-    [setStoredEmail, setStoredPhone, clearStoredEmail, clearStoredPhone, redirectUrl, clearRedirectUrl, config?.routes?.defaultCallback, accounts]
+    [setStoredEmail, setStoredPhone, clearStoredEmail, clearStoredPhone, config?.routes?.defaultCallback, accounts, router]
   );
   const refreshToken = (0, import_react2.useCallback)(async () => {
     try {
@@ -4244,15 +4237,6 @@ var AuthProviderInternal = /* @__PURE__ */ __name(({ children, config }) => {
       };
     }
   }, [clearAuthState, accounts]);
-  const clearRedirect = (0, import_react2.useCallback)(() => {
-    clearRedirectUrl();
-  }, [clearRedirectUrl]);
-  const saveCurrentUrlForRedirect = (0, import_react2.useCallback)(() => {
-    if (typeof window !== "undefined") {
-      const currentUrl = window.location.pathname + window.location.search;
-      setRedirectUrl(currentUrl);
-    }
-  }, [setRedirectUrl]);
   const logout = (0, import_react2.useCallback)(async () => {
     const performLogout = /* @__PURE__ */ __name(() => {
       Analytics.event("auth_logout" /* AUTH_LOGOUT */, {
@@ -4282,31 +4266,6 @@ var AuthProviderInternal = /* @__PURE__ */ __name(({ children, config }) => {
       }
     }
   }, [accounts, config?.routes?.defaultAuthCallback, router]);
-  const getSavedRedirectUrl = (0, import_react2.useCallback)(() => {
-    if (typeof window !== "undefined") {
-      return sessionStorage.getItem(AUTH_REDIRECT_KEY);
-    }
-    return null;
-  }, []);
-  const saveRedirectUrl = (0, import_react2.useCallback)((url) => {
-    if (typeof window !== "undefined") {
-      sessionStorage.setItem(AUTH_REDIRECT_KEY, url);
-    }
-  }, []);
-  const clearSavedRedirectUrl = (0, import_react2.useCallback)(() => {
-    if (typeof window !== "undefined") {
-      sessionStorage.removeItem(AUTH_REDIRECT_KEY);
-    }
-  }, []);
-  const getFinalRedirectUrl = (0, import_react2.useCallback)(() => {
-    const savedUrl = getSavedRedirectUrl();
-    return savedUrl || (config?.routes?.defaultCallback || defaultRoutes.defaultCallback);
-  }, [getSavedRedirectUrl, config?.routes?.defaultCallback]);
-  const useAndClearRedirectUrl = (0, import_react2.useCallback)(() => {
-    const finalUrl = getFinalRedirectUrl();
-    clearSavedRedirectUrl();
-    return finalUrl;
-  }, [getFinalRedirectUrl, clearSavedRedirectUrl]);
   const isAdminUser = (0, import_react2.useMemo)(() => {
     return Boolean(user?.is_staff || user?.is_superuser);
   }, [user]);
@@ -4330,13 +4289,7 @@ var AuthProviderInternal = /* @__PURE__ */ __name(({ children, config }) => {
       requestOTP,
       verifyOTP,
       refreshToken,
-      logout,
-      getSavedRedirectUrl,
-      saveRedirectUrl,
-      clearSavedRedirectUrl,
-      getFinalRedirectUrl,
-      useAndClearRedirectUrl,
-      saveCurrentUrlForRedirect
+      logout
     }),
     [
       user,
@@ -4353,13 +4306,7 @@ var AuthProviderInternal = /* @__PURE__ */ __name(({ children, config }) => {
       requestOTP,
       verifyOTP,
       refreshToken,
-      logout,
-      getSavedRedirectUrl,
-      saveRedirectUrl,
-      clearSavedRedirectUrl,
-      getFinalRedirectUrl,
-      useAndClearRedirectUrl,
-      saveCurrentUrlForRedirect
+      logout
     ]
   );
   return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(AuthContext.Provider, { value, children });
@@ -4517,10 +4464,10 @@ function useSessionStorage(key, initialValue) {
 __name(useSessionStorage, "useSessionStorage");
 
 // src/auth/hooks/useAuthRedirect.ts
-var AUTH_REDIRECT_KEY2 = "auth_redirect_url";
+var AUTH_REDIRECT_KEY = "auth_redirect_url";
 var useAuthRedirectManager = /* @__PURE__ */ __name((options = {}) => {
   const { fallbackUrl = "/dashboard", clearOnUse = true } = options;
-  const [redirectUrl, setRedirectUrl, removeRedirectUrl] = useSessionStorage(AUTH_REDIRECT_KEY2, "");
+  const [redirectUrl, setRedirectUrl, removeRedirectUrl] = useSessionStorage(AUTH_REDIRECT_KEY, "");
   const setRedirect = /* @__PURE__ */ __name((url) => {
     setRedirectUrl(url);
   }, "setRedirect");
@@ -4764,7 +4711,7 @@ var useAutoAuth = /* @__PURE__ */ __name((options = {}) => {
 
 // src/auth/hooks/useAuthForm.ts
 var useAuthForm = /* @__PURE__ */ __name((options) => {
-  const { onIdentifierSuccess, onOTPSuccess, onError, sourceUrl } = options;
+  const { onIdentifierSuccess, onOTPSuccess, onError, sourceUrl, redirectUrl, requireTermsAcceptance = false } = options;
   const [identifier, setIdentifier] = (0, import_react7.useState)("");
   const [channel, setChannel] = (0, import_react7.useState)("email");
   const [otp, setOtp] = (0, import_react7.useState)("");
@@ -4833,7 +4780,7 @@ var useAuthForm = /* @__PURE__ */ __name((options) => {
       onError?.(message);
       return;
     }
-    if (!acceptedTerms) {
+    if (requireTermsAcceptance && !acceptedTerms) {
       const message = "Please accept the Terms of Service and Privacy Policy";
       setError(message);
       onError?.(message);
@@ -4877,7 +4824,7 @@ var useAuthForm = /* @__PURE__ */ __name((options) => {
     setIsLoading(true);
     clearError();
     try {
-      const result = await verifyOTP(identifier, otp, channel, sourceUrl);
+      const result = await verifyOTP(identifier, otp, channel, sourceUrl, redirectUrl);
       if (result.success) {
         if (channel === "email") {
           setSavedEmail(identifier);
@@ -4898,7 +4845,7 @@ var useAuthForm = /* @__PURE__ */ __name((options) => {
     } finally {
       setIsLoading(false);
     }
-  }, [identifier, otp, channel, verifyOTP, clearError, setSavedEmail, onOTPSuccess, onError, sourceUrl]);
+  }, [identifier, otp, channel, verifyOTP, clearError, setSavedEmail, onOTPSuccess, onError, sourceUrl, redirectUrl]);
   const handleResendOTP = (0, import_react7.useCallback)(async () => {
     setIsLoading(true);
     clearError();