@djangocfg/layouts 2.0.6 → 2.0.8

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.6",
+  "version": "2.0.8",
   "description": "Simple, straightforward layout components for Next.js - import and use with props",
   "keywords": [
     "layouts",
@@ -92,28 +92,29 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/api": "^1.4.36",
-    "@djangocfg/centrifugo": "^1.4.36",
-    "@djangocfg/ui": "^1.4.36",
+    "@djangocfg/api": "^1.4.38",
+    "@djangocfg/centrifugo": "^1.4.38",
+    "@djangocfg/ui": "^1.4.38",
     "@hookform/resolvers": "^5.2.0",
     "consola": "^3.4.2",
-    "lucide-react": "^0.468.0",
-    "next": "^15.4.4",
+    "lucide-react": "^0.545.0",
+    "next": ">=15.0.0",
     "p-retry": "^7.0.0",
-    "react": "^19.1.0",
-    "react-dom": "^19.1.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
     "react-hook-form": "7.65.0",
-    "sonner": "2.0.6",
+    "sonner": "2.0.7",
     "swr": "^2.3.0",
-    "tailwindcss": "^4.0.0",
+    "tailwindcss": "^4.1.14",
     "tailwindcss-animate": "^1.0.7",
-    "zod": "^4.0.10"
+    "zod": "^4.1.13"
   },
   "dependencies": {
-    "react-ga4": "^2.1.0"
+    "react-ga4": "^2.1.0",
+    "uuid": "^11.1.0"
   },
   "devDependencies": {
-    "@djangocfg/typescript-config": "^1.4.36",
+    "@djangocfg/typescript-config": "^1.4.38",
     "@types/node": "^24.7.2",
     "@types/react": "19.2.2",
     "@types/react-dom": "19.2.1",

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/useGithubAuth.ts

@@ -0,0 +1,183 @@
+'use client';
+
+import { useCallback, useState } from 'react';
+import { useRouter } from 'next/navigation';
+
+import { api } from '@djangocfg/api';
+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 = useRouter();
+
+  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
+      const finalRedirectUrl = redirectUrl || '/dashboard';
+      router.push(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/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>

package/src/layouts/AuthLayout/OAuthCallback.tsx

@@ -0,0 +1,172 @@
+'use client';
+
+import React, { useEffect, useState } from 'react';
+import { useSearchParams } from 'next/navigation';
+import { Loader2, AlertCircle, CheckCircle } from 'lucide-react';
+
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@djangocfg/ui/components';
+
+import { useGithubAuth } from '../../auth/hooks';
+
+export interface OAuthCallbackProps {
+  onSuccess?: (user: any, isNewUser: boolean, provider: string) => void;
+  onError?: (error: string) => void;
+  redirectUrl?: string;
+}
+
+type CallbackStatus = 'processing' | 'success' | 'error';
+
+/**
+ * OAuth Callback Handler Component
+ *
+ * Processes OAuth callback from providers (GitHub, etc.).
+ * Reads code, state, and provider from URL params and exchanges for tokens.
+ *
+ * Usage:
+ * Place this component on your /auth page to handle OAuth callbacks.
+ *
+ * @example
+ * ```tsx
+ * // app/auth/page.tsx
+ * import { OAuthCallback, AuthLayout } from '@djangocfg/layouts';
+ *
+ * export default function AuthPage() {
+ *   return (
+ *     <>
+ *       <OAuthCallback
+ *         onSuccess={(user) => console.log('OAuth success:', user)}
+ *         onError={(error) => console.error('OAuth error:', error)}
+ *       />
+ *       <AuthLayout enableGithubAuth>
+ *         {/* Your auth content *\/}
+ *       </AuthLayout>
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export const OAuthCallback: React.FC<OAuthCallbackProps> = ({
+  onSuccess,
+  onError,
+  redirectUrl,
+}) => {
+  const searchParams = useSearchParams();
+  const [status, setStatus] = useState<CallbackStatus | null>(null);
+  const [errorMessage, setErrorMessage] = useState<string | null>(null);
+
+  const provider = searchParams.get('provider');
+  const code = searchParams.get('code');
+  const state = searchParams.get('state');
+  const error = searchParams.get('error');
+  const errorDescription = searchParams.get('error_description');
+
+  const {
+    handleGithubCallback,
+    isLoading,
+    error: githubError,
+  } = useGithubAuth({
+    onSuccess: (user, isNewUser) => {
+      setStatus('success');
+      onSuccess?.(user, isNewUser, 'github');
+    },
+    onError: (err) => {
+      setStatus('error');
+      setErrorMessage(err);
+      onError?.(err);
+    },
+    redirectUrl,
+  });
+
+  // Process OAuth callback on mount
+  useEffect(() => {
+    // Check if this is an OAuth callback
+    if (!provider || !code || !state) {
+      // Not an OAuth callback, don't show anything
+      return;
+    }
+
+    // Check for error from provider
+    if (error) {
+      setStatus('error');
+      setErrorMessage(errorDescription || error);
+      onError?.(errorDescription || error);
+      return;
+    }
+
+    // Process based on provider
+    const processCallback = async () => {
+      setStatus('processing');
+
+      if (provider === 'github') {
+        await handleGithubCallback(code, state);
+      } else {
+        setStatus('error');
+        setErrorMessage(`Unsupported OAuth provider: ${provider}`);
+        onError?.(`Unsupported OAuth provider: ${provider}`);
+      }
+    };
+
+    processCallback();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [provider, code, state, error]);
+
+  // Don't render if not an OAuth callback
+  if (!provider || (!code && !error)) {
+    return null;
+  }
+
+  return (
+    <div className="fixed inset-0 bg-background/80 backdrop-blur-sm z-50 flex items-center justify-center">
+      <Card className="w-full max-w-md mx-4 shadow-lg">
+        <CardHeader className="text-center">
+          {status === 'processing' && (
+            <>
+              <div className="mx-auto w-12 h-12 bg-primary/10 rounded-full flex items-center justify-center mb-4">
+                <Loader2 className="w-6 h-6 text-primary animate-spin" />
+              </div>
+              <CardTitle>Signing you in...</CardTitle>
+              <CardDescription>
+                Please wait while we complete your {provider} authentication.
+              </CardDescription>
+            </>
+          )}
+
+          {status === 'success' && (
+            <>
+              <div className="mx-auto w-12 h-12 bg-green-100 dark:bg-green-900/20 rounded-full flex items-center justify-center mb-4">
+                <CheckCircle className="w-6 h-6 text-green-600 dark:text-green-400" />
+              </div>
+              <CardTitle>Success!</CardTitle>
+              <CardDescription>
+                You have been signed in successfully. Redirecting...
+              </CardDescription>
+            </>
+          )}
+
+          {status === 'error' && (
+            <>
+              <div className="mx-auto w-12 h-12 bg-destructive/10 rounded-full flex items-center justify-center mb-4">
+                <AlertCircle className="w-6 h-6 text-destructive" />
+              </div>
+              <CardTitle>Authentication Failed</CardTitle>
+              <CardDescription className="text-destructive">
+                {errorMessage || githubError || 'An error occurred during authentication.'}
+              </CardDescription>
+            </>
+          )}
+        </CardHeader>
+
+        {status === 'error' && (
+          <CardContent className="text-center">
+            <a
+              href="/auth"
+              className="text-primary hover:underline text-sm"
+            >
+              Try again
+            </a>
+          </CardContent>
+        )}
+      </Card>
+    </div>
+  );
+};

package/src/layouts/AuthLayout/OAuthProviders.tsx

@@ -0,0 +1,85 @@
+'use client';
+
+import React from 'react';
+import { Github, Loader2 } from 'lucide-react';
+
+import { Button } from '@djangocfg/ui/components';
+
+import { useGithubAuth } from '../../auth/hooks';
+import { useAuthContext } from './AuthContext';
+
+/**
+ * OAuth Providers Component
+ *
+ * Shows OAuth login buttons (GitHub, etc.) when enabled.
+ * Handles the OAuth flow initiation.
+ */
+export const OAuthProviders: React.FC = () => {
+  const { enableGithubAuth, sourceUrl, error: contextError, setError } = useAuthContext();
+
+  const {
+    isLoading: isGithubLoading,
+    error: githubError,
+    startGithubAuth,
+  } = useGithubAuth({
+    sourceUrl,
+    onError: (error) => {
+      setError(error);
+    },
+  });
+
+  // Don't render if no OAuth providers are enabled
+  if (!enableGithubAuth) {
+    return null;
+  }
+
+  const error = githubError || contextError;
+
+  return (
+    <div className="space-y-4">
+      {/* Divider */}
+      <div className="relative">
+        <div className="absolute inset-0 flex items-center">
+          <div className="w-full border-t border-border" />
+        </div>
+        <div className="relative flex justify-center text-xs uppercase">
+          <span className="bg-card px-2 text-muted-foreground">
+            Or continue with
+          </span>
+        </div>
+      </div>
+
+      {/* OAuth Buttons */}
+      <div className="grid gap-3">
+        {enableGithubAuth && (
+          <Button
+            type="button"
+            variant="outline"
+            className="w-full h-11 text-base font-medium"
+            onClick={startGithubAuth}
+            disabled={isGithubLoading}
+          >
+            {isGithubLoading ? (
+              <div className="flex items-center gap-2">
+                <Loader2 className="w-5 h-5 animate-spin" />
+                Connecting...
+              </div>
+            ) : (
+              <div className="flex items-center gap-2">
+                <Github className="w-5 h-5" />
+                Continue with GitHub
+              </div>
+            )}
+          </Button>
+        )}
+      </div>
+
+      {/* Error Message */}
+      {error && (
+        <div className="text-sm text-destructive bg-destructive/10 p-3 rounded-md border border-destructive/20">
+          {error}
+        </div>
+      )}
+    </div>
+  );
+};