@djangocfg/api 2.1.10 → 2.1.14

package/src/auth/hooks/useAuthForm.ts

@@ -0,0 +1,332 @@
+"use client"
+
+import { useCallback, useEffect, useState } from 'react';
+
+import { useAuth } from '../context';
+import { useAutoAuth } from './useAutoAuth';
+import { useLocalStorage } from './useLocalStorage';
+import { authLogger } from '../utils/logger';
+
+export interface AuthFormState {
+  identifier: string; // Email or phone number
+  channel: 'email' | 'phone';
+  otp: string;
+  isLoading: boolean;
+  acceptedTerms: boolean;
+  step: 'identifier' | 'otp';
+  error: string;
+}
+
+export interface AuthFormHandlers {
+  setIdentifier: (identifier: string) => void;
+  setChannel: (channel: 'email' | 'phone') => void;
+  setOtp: (otp: string) => void;
+  setAcceptedTerms: (accepted: boolean) => void;
+  setError: (error: string) => void;
+  clearError: () => void;
+  handleIdentifierSubmit: (e: React.FormEvent) => Promise<void>;
+  handleOTPSubmit: (e: React.FormEvent) => Promise<void>;
+  handleResendOTP: () => Promise<void>;
+  handleBackToIdentifier: () => void;
+  forceOTPStep: () => void;
+  // Utility methods
+  detectChannelFromIdentifier: (identifier: string) => 'email' | 'phone' | null;
+  validateIdentifier: (identifier: string, channel?: 'email' | 'phone') => boolean;
+}
+
+export interface UseAuthFormOptions {
+  onIdentifierSuccess?: (identifier: string, channel: 'email' | 'phone') => void;
+  onOTPSuccess?: () => void;
+  onError?: (message: string) => void;
+  sourceUrl: string;
+}
+
+export const useAuthForm = (options: UseAuthFormOptions): AuthFormState & AuthFormHandlers => {
+  const { onIdentifierSuccess, onOTPSuccess, onError, sourceUrl } = options;
+  
+  // Form state
+  const [identifier, setIdentifier] = useState('');
+  const [channel, setChannel] = useState<'email' | 'phone'>('email');
+  const [otp, setOtp] = useState('');
+  const [isLoading, setIsLoading] = useState(false);
+  const [acceptedTerms, setAcceptedTerms] = useState(false);
+  const [step, setStep] = useState<'identifier' | 'otp'>('identifier');
+  const [error, setError] = useState('');
+  
+
+  
+  // Auth hooks
+  const { requestOTP, verifyOTP, getSavedEmail, saveEmail, getSavedPhone, savePhone } = useAuth();
+  const [savedTermsAccepted, setSavedTermsAccepted] = useLocalStorage('auth_terms_accepted', false);
+  const [savedEmail, setSavedEmail] = useLocalStorage('auth_email', '');
+  const [savedPhone, setSavedPhone] = useLocalStorage('auth_phone', '');
+
+  // Utility functions
+  const detectChannelFromIdentifier = useCallback((identifier: string): 'email' | 'phone' | null => {
+    if (!identifier) return null;
+    
+    // Email detection
+    if (identifier.includes('@')) {
+      return 'email';
+    }
+    
+    // Phone detection (starts with + and contains digits)
+    if (identifier.startsWith('+') && /^\+[1-9]\d{6,14}$/.test(identifier)) {
+      return 'phone';
+    }
+    
+    return null;
+  }, []);
+
+  const validateIdentifier = useCallback((identifier: string, channelType?: 'email' | 'phone'): boolean => {
+    if (!identifier) return false;
+    
+    const detectedChannel = channelType || detectChannelFromIdentifier(identifier);
+    
+    if (detectedChannel === 'email') {
+      // Basic email validation
+      return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(identifier);
+    } else if (detectedChannel === 'phone') {
+      // E.164 phone validation
+      return /^\+[1-9]\d{6,14}$/.test(identifier);
+    }
+    
+    return false;
+  }, [detectChannelFromIdentifier]);
+
+  // Load saved data on mount
+  useEffect(() => {
+    const authSavedEmail = getSavedEmail();
+    const authSavedPhone = getSavedPhone();
+    
+    // Prioritize phone over email if both exist
+    if (authSavedPhone) {
+      setIdentifier(authSavedPhone);
+      setChannel('phone');
+    } else if (authSavedEmail) {
+      setIdentifier(authSavedEmail);
+      setChannel('email');
+    }
+    
+    if (savedTermsAccepted) {
+      setAcceptedTerms(savedTermsAccepted);
+    }
+  }, [getSavedEmail, getSavedPhone, savedTermsAccepted]);
+
+  // Auto-detect channel when identifier changes
+  useEffect(() => {
+    if (identifier) {
+      const detectedChannel = detectChannelFromIdentifier(identifier);
+      if (detectedChannel && detectedChannel !== channel) {
+        setChannel(detectedChannel);
+      }
+    }
+  }, [identifier, channel, detectChannelFromIdentifier]);
+
+
+
+  const clearError = useCallback(() => setError(''), []);
+
+  const handleIdentifierSubmit = useCallback(async (e: React.FormEvent) => {
+    e.preventDefault();
+    
+    if (!identifier) {
+      const message = channel === 'phone' ? 'Please enter your phone number' : 'Please enter your email address';
+      setError(message);
+      onError?.(message);
+      return;
+    }
+
+    // Validate identifier format
+    if (!validateIdentifier(identifier, channel)) {
+      const message = channel === 'phone' 
+        ? 'Please enter a valid phone number (e.g., +1234567890)' 
+        : 'Please enter a valid email address';
+      setError(message);
+      onError?.(message);
+      return;
+    }
+
+    if (!acceptedTerms) {
+      const message = 'Please accept the Terms of Service and Privacy Policy';
+      setError(message);
+      onError?.(message);
+      return;
+    }
+
+    setIsLoading(true);
+    clearError();
+    
+    try {
+      const result = await requestOTP(identifier, channel, sourceUrl);
+      
+      if (result.success) {
+        // Save identifier and terms acceptance on successful request, clear opposite channel
+        if (channel === 'email') {
+          saveEmail(identifier);
+          setSavedPhone(''); // Clear phone storage
+        } else if (channel === 'phone') {
+          savePhone(identifier);
+          setSavedEmail(''); // Clear email storage
+        }
+        setSavedTermsAccepted(true);
+        setStep('otp');
+        onIdentifierSuccess?.(identifier, channel);
+      } else {
+        setError(result.message);
+        onError?.(result.message);
+      }
+    } catch (error) {
+      const message = 'An unexpected error occurred';
+      setError(message);
+      onError?.(message);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [identifier, channel, acceptedTerms, validateIdentifier, requestOTP, saveEmail, clearError, setSavedTermsAccepted, onIdentifierSuccess, onError, sourceUrl]);
+
+  const handleOTPSubmit = useCallback(async (e: React.FormEvent) => {
+    e.preventDefault();
+    
+    if (!otp || otp.length < 6) {
+      const message = 'Please enter the 6-digit verification code';
+      setError(message);
+      onError?.(message);
+      return;
+    }
+
+    setIsLoading(true);
+    clearError();
+    
+    try {
+      const result = await verifyOTP(identifier, otp, channel, sourceUrl);
+      
+      if (result.success) {
+        // Save identifier on successful login, clear opposite channel
+        if (channel === 'email') {
+          setSavedEmail(identifier);
+          setSavedPhone(''); // Clear phone storage
+        } else if (channel === 'phone') {
+          setSavedPhone(identifier);
+          setSavedEmail(''); // Clear email storage
+        }
+        onOTPSuccess?.();
+      } else {
+        setError(result.message);
+        onError?.(result.message);
+      }
+    } catch (error) {
+      const message = 'An unexpected error occurred';
+      setError(message);
+      onError?.(message);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [identifier, otp, channel, verifyOTP, clearError, setSavedEmail, onOTPSuccess, onError, sourceUrl]);
+
+  const handleResendOTP = useCallback(async () => {
+    setIsLoading(true);
+    clearError();
+    
+    try {
+      const result = await requestOTP(identifier, channel, sourceUrl);
+      
+      if (result.success) {
+        // Save identifier and clear OTP input, clear opposite channel
+        if (channel === 'email') {
+          saveEmail(identifier);
+          setSavedPhone(''); // Clear phone storage
+        } else if (channel === 'phone') {
+          savePhone(identifier);
+          setSavedEmail(''); // Clear email storage
+        }
+        setOtp('');
+      } else {
+        setError(result.message);
+        onError?.(result.message);
+      }
+    } catch (error) {
+      const message = 'Failed to resend verification code';
+      setError(message);
+      onError?.(message);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [identifier, channel, requestOTP, saveEmail, clearError, setOtp, onError, sourceUrl]);
+
+  const handleBackToIdentifier = useCallback(() => {
+    setStep('identifier');
+    clearError();
+  }, [clearError]);
+
+  const forceOTPStep = useCallback(() => {
+    setStep('otp');
+    clearError();
+  }, [clearError]);
+
+  const handleAcceptedTermsChange = useCallback((checked: boolean) => {
+    setAcceptedTerms(checked);
+    setSavedTermsAccepted(checked);
+  }, [setSavedTermsAccepted]);
+
+  // Auto-detect OTP from URL query parameters
+  useAutoAuth({
+    onOTPDetected: (otp: string) => {
+      authLogger.info('OTP detected, auto-submitting');
+      
+      // Get saved identifier from auth context
+      const savedEmail = getSavedEmail();
+      const savedPhone = getSavedPhone();
+      
+      // Prioritize phone over email if both exist
+      if (savedPhone) {
+        setIdentifier(savedPhone);
+        setChannel('phone');
+      } else if (savedEmail) {
+        setIdentifier(savedEmail);
+        setChannel('email');
+      }
+      
+      // Set OTP and force OTP step
+      setOtp(otp);
+      setStep('otp');
+      
+      // Auto-submit after a short delay to ensure state is updated
+      setTimeout(() => {
+        const fakeEvent = { preventDefault: () => {} } as React.FormEvent;
+        handleOTPSubmit(fakeEvent);
+      }, 200);
+    },
+    cleanupUrl: true,
+  });
+
+  return {
+    // Form state
+    identifier,
+    channel,
+    otp,
+    isLoading,
+    acceptedTerms,
+    step,
+    error,
+    
+    // Form handlers
+    setIdentifier,
+    setChannel,
+    setOtp,
+    setAcceptedTerms: handleAcceptedTermsChange,
+    setError,
+    clearError,
+    
+    // Auth handlers
+    handleIdentifierSubmit,
+    handleOTPSubmit,
+    handleResendOTP,
+    handleBackToIdentifier,
+    forceOTPStep,
+    
+    // Utility methods
+    detectChannelFromIdentifier,
+    validateIdentifier,
+  };
+}; 

package/src/auth/hooks/useAuthGuard.ts

@@ -0,0 +1,25 @@
+"use client"
+
+import { useEffect } from 'react';
+
+import { useAuth } from '../context';
+import { useCfgRouter } from '@djangocfg/ui-nextjs/hooks';
+
+interface UseAuthGuardOptions {
+  redirectTo?: string;
+  requireAuth?: boolean;
+}
+
+export const useAuthGuard = (options: UseAuthGuardOptions = {}) => {
+  const { redirectTo = '/auth', requireAuth = true } = options;
+  const { isAuthenticated, isLoading } = useAuth();
+  const router = useCfgRouter();
+
+  useEffect(() => {
+    if (!isLoading && requireAuth && !isAuthenticated) {
+      router.push(redirectTo);
+    }
+  }, [isAuthenticated, isLoading, router, redirectTo, requireAuth]);
+
+  return { isAuthenticated, isLoading };
+}; 

package/src/auth/hooks/useAuthRedirect.ts

@@ -0,0 +1,51 @@
+import { useSessionStorage } from './useSessionStorage';
+
+const AUTH_REDIRECT_KEY = 'auth_redirect_url';
+
+export interface AuthRedirectOptions {
+  fallbackUrl?: string;
+  clearOnUse?: boolean;
+}
+
+export const useAuthRedirectManager = (options: AuthRedirectOptions = {}) => {
+  const { fallbackUrl = '/dashboard', clearOnUse = true } = options;
+  const [redirectUrl, setRedirectUrl, removeRedirectUrl] = useSessionStorage<string>(AUTH_REDIRECT_KEY, '');
+
+  const setRedirect = (url: string) => {
+    setRedirectUrl(url);
+  };
+
+  const getRedirect = () => {
+    return redirectUrl;
+  };
+
+  const clearRedirect = () => {
+    removeRedirectUrl();
+  };
+
+  const hasRedirect = () => {
+    return redirectUrl.length > 0;
+  };
+
+  const getFinalRedirectUrl = () => {
+    return redirectUrl || fallbackUrl;
+  };
+
+  const useAndClearRedirect = () => {
+    const finalUrl = getFinalRedirectUrl();
+    if (clearOnUse) {
+      clearRedirect();
+    }
+    return finalUrl;
+  };
+
+  return {
+    redirectUrl,
+    setRedirect,
+    getRedirect,
+    clearRedirect,
+    hasRedirect,
+    getFinalRedirectUrl,
+    useAndClearRedirect
+  };
+}; 

package/src/auth/hooks/useAutoAuth.ts

@@ -0,0 +1,49 @@
+'use client';
+
+import { useEffect } from 'react';
+import { usePathname } from 'next/navigation';
+import { useQueryParams, useCfgRouter } from '@djangocfg/ui-nextjs/hooks';
+import { authLogger } from '../utils/logger';
+
+export interface UseAutoAuthOptions {
+  onOTPDetected?: (otp: string) => void;
+  cleanupUrl?: boolean;
+}
+
+/**
+ * Hook for automatic authentication from URL query parameters
+ * Detects OTP from URL and triggers callback
+ */
+export const useAutoAuth = (options: UseAutoAuthOptions = {}) => {
+  const { onOTPDetected, cleanupUrl = true } = options;
+  const queryParams = useQueryParams();
+  const pathname = usePathname();
+  const router = useCfgRouter();
+
+  const isReady = !!pathname && !!queryParams.get('otp');
+  const hasOTP = !!(queryParams.get('otp'));
+
+  useEffect(() => {
+    if (!isReady) return;
+
+    const queryOtp = queryParams.get('otp') as string;
+
+    // Handle OTP detection
+    if (queryOtp && typeof queryOtp === 'string' && queryOtp.length === 6) {
+      authLogger.info('OTP detected in URL:', queryOtp);
+      onOTPDetected?.(queryOtp);
+    }
+
+    // Clean up URL to remove sensitive params for security
+    if (cleanupUrl && queryOtp) {
+      const cleanQuery = Object.fromEntries(queryParams.entries());
+      delete cleanQuery.otp;
+      router.push(`${pathname}?${new URLSearchParams(cleanQuery).toString()}`);
+    }
+  }, [pathname, queryParams, onOTPDetected, cleanupUrl, router]);
+
+  return {
+    isReady,
+    hasOTP,
+  };
+};

package/src/auth/hooks/useGithubAuth.ts

@@ -0,0 +1,184 @@
+'use client';
+
+import { useCallback, useState } from 'react';
+
+import { api as apiAccounts } from '../../';
+import { useCfgRouter } from '@djangocfg/ui-nextjs/hooks';
+import { authLogger } from '../utils/logger';
+import { Analytics, AnalyticsEvent, AnalyticsCategory } from '../utils/analytics';
+
+export interface UseGithubAuthOptions {
+  sourceUrl?: string;
+  onSuccess?: (user: any, isNewUser: boolean) => void;
+  onError?: (error: string) => void;
+  redirectUrl?: string;
+}
+
+export interface UseGithubAuthReturn {
+  isLoading: boolean;
+  error: string | null;
+  startGithubAuth: () => Promise<void>;
+  handleGithubCallback: (code: string, state: string) => Promise<void>;
+}
+
+/**
+ * Hook for GitHub OAuth authentication flow.
+ *
+ * Usage:
+ * 1. Call startGithubAuth() to redirect user to GitHub
+ * 2. After GitHub redirects back, call handleGithubCallback(code, state)
+ *
+ * @example
+ * ```tsx
+ * const { isLoading, error, startGithubAuth } = useGithubAuth({
+ *   onSuccess: (user) => router.push('/dashboard'),
+ *   onError: (error) => console.error(error),
+ * });
+ *
+ * <Button onClick={startGithubAuth} disabled={isLoading}>
+ *   Continue with GitHub
+ * </Button>
+ * ```
+ */
+export const useGithubAuth = (options: UseGithubAuthOptions = {}): UseGithubAuthReturn => {
+  const { sourceUrl, onSuccess, onError, redirectUrl } = options;
+  const router = useCfgRouter();
+
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  /**
+   * Start GitHub OAuth flow - redirects user to GitHub authorization page.
+   */
+  const startGithubAuth = useCallback(async () => {
+    setIsLoading(true);
+    setError(null);
+
+    try {
+      authLogger.info('Starting GitHub OAuth flow...');
+
+      // Track OAuth start
+      Analytics.event(AnalyticsEvent.AUTH_OAUTH_START, {
+        category: AnalyticsCategory.AUTH,
+        label: 'github',
+      });
+
+      // Call API to get authorization URL
+      // The API will auto-generate redirect_uri from config if not provided
+      const response = await apiAccounts.cfg_accounts_oauth.accountsOauthGithubAuthorizeCreate({
+        source_url: sourceUrl || (typeof window !== 'undefined' ? window.location.href : ''),
+      });
+
+      if (!response.authorization_url) {
+        throw new Error('Failed to get authorization URL');
+      }
+
+      authLogger.info('Redirecting to GitHub...', response.authorization_url);
+
+      // Store state in sessionStorage for verification on callback
+      if (typeof window !== 'undefined') {
+        sessionStorage.setItem('oauth_state', response.state);
+        sessionStorage.setItem('oauth_provider', 'github');
+      }
+
+      // Redirect to GitHub
+      window.location.href = response.authorization_url;
+
+    } catch (err) {
+      const errorMessage = err instanceof Error ? err.message : 'Failed to start GitHub authentication';
+      authLogger.error('GitHub OAuth start error:', err);
+      setError(errorMessage);
+      onError?.(errorMessage);
+
+      // Track OAuth error
+      Analytics.event(AnalyticsEvent.AUTH_OAUTH_FAIL, {
+        category: AnalyticsCategory.AUTH,
+        label: 'github',
+      });
+    } finally {
+      setIsLoading(false);
+    }
+  }, [sourceUrl, onError]);
+
+  /**
+   * Handle GitHub OAuth callback - exchanges code for JWT tokens.
+   *
+   * @param code - Authorization code from GitHub callback
+   * @param state - State token for CSRF verification
+   */
+  const handleGithubCallback = useCallback(async (code: string, state: string) => {
+    setIsLoading(true);
+    setError(null);
+
+    try {
+      authLogger.info('Processing GitHub OAuth callback...');
+
+      // Verify state matches what we stored
+      if (typeof window !== 'undefined') {
+        const storedState = sessionStorage.getItem('oauth_state');
+        if (storedState && storedState !== state) {
+          throw new Error('Invalid OAuth state - possible CSRF attack');
+        }
+        // Clear stored state
+        sessionStorage.removeItem('oauth_state');
+        sessionStorage.removeItem('oauth_provider');
+      }
+
+      // Exchange code for tokens
+      // The API will auto-generate redirect_uri from config if not provided
+      const response = await apiAccounts.cfg_accounts_oauth.accountsOauthGithubCallbackCreate({
+        code,
+        state,
+      });
+
+      if (!response.access || !response.refresh) {
+        throw new Error('Invalid response from OAuth callback');
+      }
+
+      authLogger.info('GitHub OAuth successful, user:', response.user);
+
+      // Save tokens using API client
+      apiAccounts.setToken(response.access, response.refresh);
+
+      // Track successful OAuth
+      Analytics.event(AnalyticsEvent.AUTH_LOGIN_SUCCESS, {
+        category: AnalyticsCategory.AUTH,
+        label: 'github',
+      });
+
+      // Set user ID for future tracking
+      if (response.user?.id) {
+        Analytics.setUser(String(response.user.id));
+      }
+
+      // Call success callback
+      onSuccess?.(response.user, response.is_new_user || false);
+
+      // Redirect to dashboard or specified URL
+      // Use hardPush for full page reload - ensures all React contexts reinitialize
+      const finalRedirectUrl = redirectUrl || '/dashboard';
+      router.hardPush(finalRedirectUrl);
+
+    } catch (err) {
+      const errorMessage = err instanceof Error ? err.message : 'GitHub authentication failed';
+      authLogger.error('GitHub OAuth callback error:', err);
+      setError(errorMessage);
+      onError?.(errorMessage);
+
+      // Track OAuth error
+      Analytics.event(AnalyticsEvent.AUTH_OAUTH_FAIL, {
+        category: AnalyticsCategory.AUTH,
+        label: 'github',
+      });
+    } finally {
+      setIsLoading(false);
+    }
+  }, [onSuccess, onError, redirectUrl, router]);
+
+  return {
+    isLoading,
+    error,
+    startGithubAuth,
+    handleGithubCallback,
+  };
+};