Add CLAUDE.md for project documentation and examples of multi-provider OAuth usage

examples/oauth_usage.py

@@ -0,0 +1,89 @@
+#!/usr/bin/env python3
+"""
+Example demonstrating the multi-provider OAuth implementation.
+This script shows how to use the new generic OAuth system.
+"""
+
+# Example usage of the new multi-provider OAuth system
+
+# 1. Environment variables setup:
+"""
+# Required for sessions and JWT
+export SECRET_KEY="your_secret_key_for_sessions"
+export JWT_SECRET_KEY="your_jwt_secret_key"
+
+# OAuth Providers (configure as needed)
+# Google OAuth
+export GOOGLE_CLIENT_ID="your_google_client_id"
+export GOOGLE_CLIENT_SECRET="your_google_client_secret"
+
+# GitHub OAuth  
+export GITHUB_CLIENT_ID="your_github_client_id"
+export GITHUB_CLIENT_SECRET="your_github_client_secret"
+"""
+
+# 2. Available endpoints:
+"""
+GET /api/auth/providers
+    Returns: {"providers": {"google": {"name": "google", "display_name": "Google"}, ...}}
+
+GET /api/auth/login/google
+GET /api/auth/login/github
+    Redirects to OAuth provider login
+
+GET /api/auth/callback/google  
+GET /api/auth/callback/github
+    Handles OAuth callback and sets JWT cookies
+
+GET /api/auth/login (backward compatibility - defaults to Google)
+GET /api/auth/callback (backward compatibility - defaults to Google)
+
+GET /api/auth/me
+    Returns current user info including provider field
+
+GET /api/auth/logout
+    Clears authentication cookies
+"""
+
+# 3. Frontend integration example:
+"""
+// Get available providers
+const providersResponse = await fetch('/api/auth/providers');
+const { providers } = await providersResponse.json();
+
+// Redirect to OAuth provider
+window.location.href = `/api/auth/login/${provider}`; // 'google' or 'github'
+
+// After successful login, user info will include:
+{
+  "id": "user_id", 
+  "email": "user@example.com",
+  "name": "User Name", 
+  "picture": "https://avatar.url",
+  "provider": "google" // or "github"
+}
+"""
+
+# 4. Adding new OAuth providers:
+"""
+To add a new provider (e.g., Microsoft):
+
+1. Create app/services/oauth_providers/microsoft.py:
+   - Inherit from OAuthProvider
+   - Implement required methods (name, display_name, get_client_config, get_user_info)
+
+2. Add to registry.py:
+   - Add Microsoft provider initialization in _initialize_providers()
+   - Include environment variable checks
+
+3. Add environment variables:
+   - MICROSOFT_CLIENT_ID
+   - MICROSOFT_CLIENT_SECRET
+
+4. The routes automatically support the new provider via:
+   - GET /api/auth/login/microsoft
+   - GET /api/auth/callback/microsoft
+"""
+
+print("OAuth multi-provider system ready!")
+print("Configure environment variables and start the Flask app to use.")