@djangocfg/layouts 2.0.7 → 2.0.9

package/README.md

@@ -71,15 +71,21 @@ import { AppLayout } from '@djangocfg/layouts';
 
 ## Auth
 
-Complete authentication system with context, hooks, and middleware.
+Complete authentication system with OTP and OAuth support.
 
 ```tsx
 import { AuthProvider, useAuth } from '@djangocfg/layouts/auth';
-import { AuthDialog } from '@djangocfg/layouts/snippets';
-
-<AuthProvider>
-  <AuthDialog trigger={<Button>Sign In</Button>} />
-</AuthProvider>
+import { AuthLayout, OAuthCallback } from '@djangocfg/layouts';
+
+// Basic auth page with OTP and GitHub OAuth
+<AuthLayout
+  enablePhoneAuth={false}
+  enableGithubAuth={true}
+  termsUrl="/legal/terms"
+  privacyUrl="/legal/privacy"
+>
+  <h1>Welcome Back</h1>
+</AuthLayout>
 ```
 
 | Export | Description |
@@ -89,8 +95,59 @@ import { AuthDialog } from '@djangocfg/layouts/snippets';
 | `useAuthGuard` | Route protection hook |
 | `useAuthRedirect` | Redirect hook for auth flows |
 | `useAutoAuth` | Auto-authentication hook |
+| `useGithubAuth` | GitHub OAuth hook |
 | `authMiddleware` | Next.js middleware |
 
+### GitHub OAuth
+
+Complete GitHub OAuth flow with automatic token handling:
+
+```tsx
+// app/auth/page.tsx
+import { AuthLayout } from '@djangocfg/layouts';
+
+export default function AuthPage() {
+  return (
+    <AuthLayout
+      enableGithubAuth={true}
+      redirectUrl="/dashboard"
+      onOAuthSuccess={(user, isNewUser, provider) => console.log('Success!', user)}
+      onError={(error) => console.error(error)}
+    >
+      <h1>Sign In</h1>
+    </AuthLayout>
+  );
+}
+```
+
+**OAuth Flow:**
+1. User clicks "Continue with GitHub"
+2. Redirects to GitHub authorization page
+3. GitHub redirects to `/auth?provider=github&code=XXX&state=YYY`
+4. `AuthLayout` automatically handles callback and exchanges code for JWT tokens
+5. User is logged in and redirected to `redirectUrl`
+
+> **Note:** OAuth callback handling is built into `AuthLayout` when `enableGithubAuth={true}`. No need to add `OAuthCallback` separately!
+
+**Using the hook directly:**
+
+```tsx
+import { useGithubAuth } from '@djangocfg/layouts';
+
+function CustomGithubButton() {
+  const { isLoading, startGithubAuth } = useGithubAuth({
+    onSuccess: (user) => console.log('Logged in!', user),
+    onError: (error) => console.error(error),
+  });
+
+  return (
+    <button onClick={startGithubAuth} disabled={isLoading}>
+      {isLoading ? 'Connecting...' : 'Login with GitHub'}
+    </button>
+  );
+}
+```
+
 ### Auth Context
 
 ```tsx
@@ -152,6 +209,7 @@ Analytics.setUser('user-123');
 | Category | Events |
 |----------|--------|
 | **Auth** | `AUTH_OTP_REQUEST`, `AUTH_LOGIN_SUCCESS`, `AUTH_OTP_VERIFY_FAIL`, `AUTH_LOGOUT`, `AUTH_SESSION_EXPIRED`, `AUTH_TOKEN_REFRESH` |
+| **OAuth** | `AUTH_OAUTH_START`, `AUTH_OAUTH_SUCCESS`, `AUTH_OAUTH_FAIL` |
 | **Error** | `ERROR_BOUNDARY`, `ERROR_API`, `ERROR_VALIDATION`, `ERROR_NETWORK` |
 | **Navigation** | `NAV_ADMIN_ENTER`, `NAV_DASHBOARD_ENTER`, `NAV_PAGE_VIEW` |
 | **Engagement** | `THEME_CHANGE`, `SIDEBAR_TOGGLE`, `MOBILE_MENU_OPEN` |
@@ -162,6 +220,7 @@ Built-in tracking for:
 - **Page views** - on every route change
 - **User ID** - automatically set when user is authenticated
 - **Auth events** - login, logout, OTP, session expiry
+- **OAuth events** - GitHub OAuth start, success, failure
 - **Errors** - React ErrorBoundary errors
 
 ## Snippets

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/layouts",
-  "version": "2.0.7",
+  "version": "2.0.9",
   "description": "Simple, straightforward layout components for Next.js - import and use with props",
   "keywords": [
     "layouts",
@@ -92,9 +92,9 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/api": "^1.4.37",
-    "@djangocfg/centrifugo": "^1.4.37",
-    "@djangocfg/ui": "^1.4.37",
+    "@djangocfg/api": "^1.4.39",
+    "@djangocfg/centrifugo": "^1.4.39",
+    "@djangocfg/ui": "^1.4.39",
     "@hookform/resolvers": "^5.2.0",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
@@ -114,7 +114,7 @@
     "uuid": "^11.1.0"
   },
   "devDependencies": {
-    "@djangocfg/typescript-config": "^1.4.37",
+    "@djangocfg/typescript-config": "^1.4.39",
     "@types/node": "^24.7.2",
     "@types/react": "19.2.2",
     "@types/react-dom": "19.2.1",

package/src/auth/context/AuthContext.tsx

@@ -8,7 +8,7 @@ import React, {
 
 import { api, Enums } from '@djangocfg/api';
 import { useAccountsContext, AccountsProvider } from './AccountsContext';
-import { useLocalStorage, useQueryParams, useRouter } from '@djangocfg/ui/hooks';
+import { useLocalStorage, useQueryParams, useCfgRouter } from '@djangocfg/ui/hooks';
 import { getCachedProfile, clearProfileCache } from '../hooks/useProfileCache';
 
 import { authLogger } from '../../utils/logger';
@@ -50,7 +50,7 @@ const AuthProviderInternal: React.FC<AuthProviderProps> = ({ children, config })
   });
 
   const [initialized, setInitialized] = useState(false);
-  const router = useRouter();
+  const router = useCfgRouter();
   const pathname = usePathname();
   const queryParams = useQueryParams();
 
@@ -362,13 +362,14 @@ const AuthProviderInternal: React.FC<AuthProviderProps> = ({ children, config })
         }
 
         // Handle redirect logic here
+        // Use hardPush for full page reload - ensures all React contexts reinitialize
         const defaultCallback = config?.routes?.defaultCallback || defaultRoutes.defaultCallback;
 
         if (redirectUrl && redirectUrl !== defaultCallback) {
           clearRedirectUrl();
-          router.push(redirectUrl);
+          router.hardPush(redirectUrl);
         } else {
-          router.push(defaultCallback);
+          router.hardPush(defaultCallback);
         }
 
         return {
@@ -460,7 +461,11 @@ const AuthProviderInternal: React.FC<AuthProviderProps> = ({ children, config })
       accounts.logout(); // Clear tokens and profile
       setInitialized(true);
       setIsLoading(false);
-      pushToDefaultAuthCallbackUrl();
+
+      // Use hardReplace for full page reload + replace history
+      // This ensures contexts reinitialize AND back button won't return to protected page
+      const authCallbackUrl = config?.routes?.defaultAuthCallback || defaultRoutes.defaultAuthCallback;
+      router.hardReplace(authCallbackUrl);
     };
 
     // Use config.onConfirm if provided, otherwise use a simple confirm
@@ -482,7 +487,7 @@ const AuthProviderInternal: React.FC<AuthProviderProps> = ({ children, config })
         performLogout();
       }
     }
-  }, [accounts, pushToDefaultAuthCallbackUrl]);
+  }, [accounts, config?.routes?.defaultAuthCallback, router]);
 
   // Redirect URL methods
   const getSavedRedirectUrl = useCallback((): string | null => {

package/src/auth/hooks/index.ts

@@ -6,6 +6,7 @@ export { useSessionStorage } from './useSessionStorage';
 export { useLocalStorage } from './useLocalStorage';
 export { useAuthForm } from './useAuthForm';
 export { useAutoAuth } from './useAutoAuth';
+export { useGithubAuth, type UseGithubAuthOptions, type UseGithubAuthReturn } from './useGithubAuth';
 export {
   getCachedProfile,
   setCachedProfile,

package/src/auth/hooks/useAuthGuard.ts

@@ -3,7 +3,7 @@
 import { useEffect } from 'react';
 
 import { useAuth } from '../context';
-import { useRouter } from '@djangocfg/ui/hooks';
+import { useCfgRouter } from '@djangocfg/ui/hooks';
 
 interface UseAuthGuardOptions {
   redirectTo?: string;
@@ -13,7 +13,7 @@ interface UseAuthGuardOptions {
 export const useAuthGuard = (options: UseAuthGuardOptions = {}) => {
   const { redirectTo = '/auth', requireAuth = true } = options;
   const { isAuthenticated, isLoading } = useAuth();
-  const router = useRouter();
+  const router = useCfgRouter();
 
   useEffect(() => {
     if (!isLoading && requireAuth && !isAuthenticated) {

package/src/auth/hooks/useAutoAuth.ts

@@ -2,7 +2,7 @@
 
 import { useEffect } from 'react';
 import { usePathname } from 'next/navigation';
-import { useQueryParams, useRouter } from '@djangocfg/ui/hooks';
+import { useQueryParams, useCfgRouter } from '@djangocfg/ui/hooks';
 import { authLogger } from '../../utils/logger';
 
 export interface UseAutoAuthOptions {
@@ -18,7 +18,7 @@ export const useAutoAuth = (options: UseAutoAuthOptions = {}) => {
   const { onOTPDetected, cleanupUrl = true } = options;
   const queryParams = useQueryParams();
   const pathname = usePathname();
-  const router = useRouter();
+  const router = useCfgRouter();
 
   const isReady = !!pathname && !!queryParams.get('otp');
   const hasOTP = !!(queryParams.get('otp'));

package/src/auth/hooks/useGithubAuth.ts

@@ -0,0 +1,184 @@
+'use client';
+
+import { useCallback, useState } from 'react';
+
+import { api } from '@djangocfg/api';
+import { useCfgRouter } from '@djangocfg/ui/hooks';
+import { authLogger } from '../../utils/logger';
+import { Analytics, AnalyticsEvent, AnalyticsCategory } from '../../snippets/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 api.cfg_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 api.cfg_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
+      api.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,
+  };
+};

package/src/components/RedirectPage/RedirectPage.tsx

@@ -2,7 +2,7 @@
 
 import { useEffect } from 'react';
 import { useAuth } from '../../auth';
-import { useRouter } from '@djangocfg/ui/hooks';
+import { useCfgRouter } from '@djangocfg/ui/hooks';
 import { Preloader } from '@djangocfg/ui/components';
 
 export interface RedirectPageProps {
@@ -49,7 +49,7 @@ export function RedirectPage({
   loadingText = 'Loading...',
 }: RedirectPageProps) {
   const { isAuthenticated } = useAuth();
-  const router = useRouter();
+  const router = useCfgRouter();
 
   useEffect(() => {
     if (!isAuthenticated) {

package/src/layouts/AuthLayout/AuthContext.tsx

@@ -15,6 +15,7 @@ export const AuthProvider: React.FC<AuthProps> = ({
   termsUrl,
   privacyUrl,
   enablePhoneAuth = false, // Default to false for backward compatibility
+  enableGithubAuth = false, // Default to false for backward compatibility
   onIdentifierSuccess,
   onOTPSuccess,
   onError,
@@ -39,6 +40,7 @@ export const AuthProvider: React.FC<AuthProps> = ({
     termsUrl,
     privacyUrl,
     enablePhoneAuth,
+    enableGithubAuth,
   };
 
   return <AuthContext.Provider value={value}>{children}</AuthContext.Provider>;

package/src/layouts/AuthLayout/AuthLayout.tsx

@@ -1,19 +1,22 @@
 /**
  * Auth Layout
- * 
- * Layout for authentication pages with OTP authentication (email/phone)
+ *
+ * Layout for authentication pages with OTP (email/phone) and OAuth (GitHub) support.
  * Supports two-step authentication flow: identifier input → OTP verification
- * 
+ * Also handles OAuth callbacks automatically when enableGithubAuth is true.
+ *
  * @example
  * ```tsx
  * import { AuthLayout } from '@djangocfg/layouts';
- * 
+ *
  * <AuthLayout
  *   sourceUrl="https://example.com"
  *   supportUrl="https://example.com/support"
  *   termsUrl="https://example.com/terms"
  *   privacyUrl="https://example.com/privacy"
- *   enablePhoneAuth={true}
+ *   enablePhoneAuth={false}
+ *   enableGithubAuth={true}
+ *   redirectUrl="/dashboard"
  * >
  *   {/* Optional custom content above forms *\/}
  * </AuthLayout>
@@ -27,6 +30,7 @@ import React from 'react';
 import { AuthProvider, useAuthContext } from './AuthContext';
 import { IdentifierForm } from './IdentifierForm';
 import { OTPForm } from './OTPForm';
+import { OAuthCallback } from './OAuthCallback';
 import { Suspense } from '../../components';
 
 import type { AuthProps } from './types';
@@ -34,8 +38,21 @@ import type { AuthProps } from './types';
 export type AuthLayoutProps = AuthProps;
 
 export const AuthLayout: React.FC<AuthProps> = (props) => {
+  const { enableGithubAuth, redirectUrl = '/dashboard', onOAuthSuccess, onError } = props;
+
   return (
     <Suspense>
+      {/* Handle OAuth callback when GitHub auth is enabled */}
+      {enableGithubAuth && (
+        <Suspense fallback={null}>
+          <OAuthCallback
+            redirectUrl={redirectUrl}
+            onSuccess={onOAuthSuccess ? (user, isNewUser) => onOAuthSuccess(user, isNewUser, 'github') : undefined}
+            onError={onError}
+          />
+        </Suspense>
+      )}
+
       <AuthProvider {...props}>
         <div
           className={`min-h-screen flex flex-col items-center justify-center bg-background py-6 px-4 sm:py-12 sm:px-6 lg:px-8 ${props.className || ''}`}

package/src/layouts/AuthLayout/IdentifierForm.tsx

@@ -22,6 +22,7 @@ import {
 
 import { useAuthContext } from './AuthContext';
 import { AuthHelp } from './AuthHelp';
+import { OAuthProviders } from './OAuthProviders';
 
 export const IdentifierForm: React.FC = () => {
   const {
@@ -328,6 +329,9 @@ export const IdentifierForm: React.FC = () => {
           </form>
         )}
 
+        {/* OAuth Providers (GitHub, etc.) */}
+        <OAuthProviders />
+
         {/* Help Section */}
         <AuthHelp />
       </CardContent>