@oxyhq/services 5.24.0 → 5.26.0

package/src/utils/hookUtils.ts

@@ -172,8 +172,8 @@ export function useLocalStorage<T>(key: string, initialValue: T) {
     try {
       const item = window.localStorage.getItem(key);
       return item ? JSON.parse(item) : initialValue;
-    } catch (error) {
-      console.error(`Error reading localStorage key "${key}":`, error);
+    } catch {
+      // Silently fail and return initial value
       return initialValue;
     }
   });
@@ -185,8 +185,8 @@ export function useLocalStorage<T>(key: string, initialValue: T) {
       if (hasLocalStorage) {
         window.localStorage.setItem(key, JSON.stringify(valueToStore));
       }
-    } catch (error) {
-      console.error(`Error setting localStorage key "${key}":`, error);
+    } catch {
+      // Silently fail - storage might be full or blocked
     }
   }, [key, storedValue]);
 
@@ -202,8 +202,8 @@ export function useSessionStorage<T>(key: string, initialValue: T) {
     try {
       const item = window.sessionStorage.getItem(key);
       return item ? JSON.parse(item) : initialValue;
-    } catch (error) {
-      console.error(`Error reading sessionStorage key "${key}":`, error);
+    } catch {
+      // Silently fail and return initial value
       return initialValue;
     }
   });
@@ -215,8 +215,8 @@ export function useSessionStorage<T>(key: string, initialValue: T) {
       if (hasSessionStorage) {
         window.sessionStorage.setItem(key, JSON.stringify(valueToStore));
       }
-    } catch (error) {
-      console.error(`Error setting sessionStorage key "${key}":`, error);
+    } catch {
+      // Silently fail - storage might be full or blocked
     }
   }, [key, storedValue]);
 

package/src/web/WebOxyContext.tsx

@@ -1,6 +1,11 @@
 /**
  * Web-Only Oxy Context
- * Clean implementation with ZERO React Native dependencies
+ *
+ * Clean implementation with ZERO React Native dependencies.
+ * Provides FedCM, popup, and redirect authentication methods.
+ * Uses centralized AuthManager for token and session management.
+ *
+ * @module web/WebOxyContext
  */
 
 import {
@@ -8,11 +13,15 @@ import {
   useCallback,
   useContext,
   useEffect,
+  useMemo,
   useState,
   type ReactNode,
 } from 'react';
-import { OxyServices } from '../core';
+import { OxyServices } from '../core/OxyServices';
+import { CrossDomainAuth } from '../core/CrossDomainAuth';
+import { AuthManager, createAuthManager } from '../core/AuthManager';
 import type { User } from '../models/interfaces';
+import type { SessionLoginResponse, MinimalUserData } from '../models/session';
 import { QueryClientProvider } from '@tanstack/react-query';
 import { createQueryClient } from '../ui/hooks/queryClient';
 
@@ -24,57 +33,195 @@ export interface WebAuthState {
 }
 
 export interface WebAuthActions {
+  /**
+   * Sign in using the best available method (FedCM → Popup → Redirect)
+   */
   signIn: () => Promise<void>;
+
+  /**
+   * Sign in using FedCM (browser-native, Google-style)
+   * Falls back to popup if FedCM is not supported
+   */
+  signInWithFedCM: () => Promise<void>;
+
+  /**
+   * Sign in using popup window
+   */
+  signInWithPopup: () => Promise<void>;
+
+  /**
+   * Sign in using redirect (full page redirect to auth.oxy.so)
+   */
+  signInWithRedirect: () => void;
+
+  /**
+   * Sign out and clear session
+   */
   signOut: () => Promise<void>;
+
+  /**
+   * Check if FedCM is supported in the current browser
+   */
+  isFedCMSupported: () => boolean;
 }
 
 export interface WebOxyContextValue extends WebAuthState, WebAuthActions {
   oxyServices: OxyServices;
+  crossDomainAuth: CrossDomainAuth;
+  authManager: AuthManager;
 }
 
 const WebOxyContext = createContext<WebOxyContextValue | null>(null);
 
 export interface WebOxyProviderProps {
   children: ReactNode;
+  /** Base URL for the Oxy API (e.g., 'https://api.oxy.so') */
   baseURL: string;
+  /** Optional auth web URL for popup/redirect (defaults to 'https://auth.oxy.so') */
   authWebUrl?: string;
+  /** Callback when auth state changes */
   onAuthStateChange?: (user: User | null) => void;
+  /** Callback when an error occurs */
+  onError?: (error: Error) => void;
+  /** Preferred auth method: 'auto' (default), 'fedcm', 'popup', or 'redirect' */
+  preferredAuthMethod?: 'auto' | 'fedcm' | 'popup' | 'redirect';
+  /** Skip automatic session check on mount */
+  skipAutoCheck?: boolean;
 }
 
 /**
  * Web-only Oxy Provider
- * Minimal, clean implementation for web apps
+ *
+ * Provides authentication context for pure web applications (React, Next.js, Vite).
+ * Supports FedCM, popup, and redirect authentication methods.
+ *
+ * @example
+ * ```tsx
+ * import { WebOxyProvider, useAuth } from '@oxyhq/services/web';
+ *
+ * function App() {
+ *   return (
+ *     <WebOxyProvider baseURL="https://api.oxy.so">
+ *       <YourApp />
+ *     </WebOxyProvider>
+ *   );
+ * }
+ *
+ * function LoginButton() {
+ *   const { signIn, isLoading, isFedCMSupported } = useAuth();
+ *   return (
+ *     <button onClick={signIn} disabled={isLoading}>
+ *       {isFedCMSupported() ? 'Sign in with Oxy' : 'Sign in'}
+ *     </button>
+ *   );
+ * }
+ * ```
  */
 export function WebOxyProvider({
   children,
   baseURL,
   authWebUrl,
   onAuthStateChange,
+  onError,
+  preferredAuthMethod = 'auto',
+  skipAutoCheck = false,
 }: WebOxyProviderProps) {
+  // Initialize services with centralized AuthManager
   const [oxyServices] = useState(() => new OxyServices({ baseURL, authWebUrl }));
+  const [crossDomainAuth] = useState(() => new CrossDomainAuth(oxyServices));
+  const [authManager] = useState(() => createAuthManager(oxyServices, { autoRefresh: true }));
+  const [queryClient] = useState(() => createQueryClient());
+
+  // Auth state
   const [user, setUser] = useState<User | null>(null);
-  const [isLoading, setIsLoading] = useState(true);
+  const [isLoading, setIsLoading] = useState(!skipAutoCheck);
   const [error, setError] = useState<string | null>(null);
-  const [queryClient] = useState(() => createQueryClient());
 
   const isAuthenticated = !!user;
 
-  // Initialize - check for existing session
+  /**
+   * Handles successful authentication via AuthManager
+   */
+  const handleAuthSuccess = useCallback(async (session: SessionLoginResponse, method: 'fedcm' | 'popup' | 'redirect' | 'credentials' = 'credentials') => {
+    // Use centralized AuthManager for token/session storage
+    await authManager.handleAuthSuccess(session, method);
+
+    // Fetch full user profile (session.user only contains MinimalUserData)
+    try {
+      const fullUser = await oxyServices.getCurrentUser();
+      if (fullUser) {
+        setUser(fullUser);
+      } else {
+        // Fallback to minimal data if full profile unavailable
+        setUser(session.user as User);
+      }
+    } catch {
+      // Fallback to minimal data on error
+      setUser(session.user as User);
+    }
+
+    setError(null);
+    setIsLoading(false);
+  }, [authManager, oxyServices]);
+
+  /**
+   * Handles authentication errors
+   */
+  const handleAuthError = useCallback((err: unknown) => {
+    const errorMessage = err instanceof Error ? err.message : 'Authentication failed';
+    setError(errorMessage);
+    setIsLoading(false);
+    onError?.(err instanceof Error ? err : new Error(errorMessage));
+  }, [onError]);
+
+  // Initialize - check for existing session or redirect callback
   useEffect(() => {
+    if (skipAutoCheck) return;
+
     let mounted = true;
 
     const initAuth = async () => {
       try {
-        // Try to get current user (will use existing auth token if available)
-        const currentUser = await oxyServices.getCurrentUser();
+        // 1. Check for redirect callback (user returning from auth.oxy.so)
+        const callbackSession = crossDomainAuth.handleRedirectCallback();
+        if (callbackSession && mounted) {
+          await handleAuthSuccess(callbackSession, 'redirect');
+          return;
+        }
 
-        if (mounted && currentUser) {
-          setUser(currentUser);
+        // 2. Try to restore session from AuthManager (handles token refresh automatically)
+        const restoredUser = await authManager.initialize();
+        if (restoredUser && mounted) {
+          // Verify token is still valid by fetching current user
+          try {
+            const currentUser = await oxyServices.getCurrentUser();
+            if (mounted && currentUser) {
+              setUser(currentUser);
+              setIsLoading(false);
+              return;
+            }
+          } catch {
+            // Token invalid, AuthManager will handle clearing
+            await authManager.signOut();
+          }
+        }
+
+        // 3. Try silent sign-in (FedCM or iframe-based SSO)
+        try {
+          const session = await crossDomainAuth.silentSignIn();
+          if (mounted && session?.user) {
+            await handleAuthSuccess(session, 'fedcm');
+            return;
+          }
+        } catch {
+          // Silent sign-in failed, that's fine
+        }
+
+        // No session found
+        if (mounted) {
+          setIsLoading(false);
         }
       } catch (err) {
-        // No active session - this is fine
-        console.log('[WebOxy] No active session');
-      } finally {
         if (mounted) {
           setIsLoading(false);
         }
@@ -86,98 +233,147 @@ export function WebOxyProvider({
     return () => {
       mounted = false;
     };
-  }, [oxyServices]);
+  }, [oxyServices, crossDomainAuth, authManager, skipAutoCheck, handleAuthSuccess]);
 
   // Notify parent of auth state changes
   useEffect(() => {
     onAuthStateChange?.(user);
   }, [user, onAuthStateChange]);
 
+  /**
+   * Sign in with automatic method selection
+   */
   const signIn = useCallback(async () => {
     setError(null);
     setIsLoading(true);
 
+    let selectedMethod: 'fedcm' | 'popup' | 'redirect' = 'popup';
+
     try {
-      // Open popup to auth.oxy.so
-      const popup = window.open(
-        `${authWebUrl || 'https://auth.oxy.so'}/login?origin=${encodeURIComponent(window.location.origin)}`,
-        'oxy-auth',
-        'width=500,height=700,popup=yes'
-      );
-
-      if (!popup) {
-        throw new Error('Popup blocked. Please allow popups for this site.');
+      const session = await crossDomainAuth.signIn({
+        method: preferredAuthMethod,
+        onMethodSelected: (method) => {
+          selectedMethod = method as 'fedcm' | 'popup' | 'redirect';
+        },
+      });
+
+      if (session) {
+        await handleAuthSuccess(session, selectedMethod);
+      } else {
+        // Redirect method - page will reload
+        setIsLoading(false);
       }
+    } catch (err) {
+      handleAuthError(err);
+    }
+  }, [crossDomainAuth, preferredAuthMethod, handleAuthSuccess, handleAuthError]);
 
-      // Listen for message from popup
-      const handleMessage = async (event: MessageEvent) => {
-        if (event.origin !== (authWebUrl || 'https://auth.oxy.so')) {
-          return;
-        }
-
-        if (event.data.type === 'oxy-auth-success') {
-          const { accessToken, user: authUser } = event.data;
-
-          // Store the access token for API requests
-          if (typeof window !== 'undefined' && accessToken) {
-            localStorage.setItem('oxy-access-token', accessToken);
-          }
-
-          setUser(authUser);
-          setIsLoading(false);
+  /**
+   * Sign in with FedCM specifically
+   */
+  const signInWithFedCM = useCallback(async () => {
+    setError(null);
+    setIsLoading(true);
 
-          window.removeEventListener('message', handleMessage);
-          popup.close();
-        } else if (event.data.type === 'oxy-auth-error') {
-          setError(event.data.error || 'Authentication failed');
-          setIsLoading(false);
-          window.removeEventListener('message', handleMessage);
-          popup.close();
-        }
-      };
+    try {
+      const session = await crossDomainAuth.signInWithFedCM();
+      await handleAuthSuccess(session, 'fedcm');
+    } catch (err) {
+      handleAuthError(err);
+    }
+  }, [crossDomainAuth, handleAuthSuccess, handleAuthError]);
 
-      window.addEventListener('message', handleMessage);
+  /**
+   * Sign in with popup specifically
+   */
+  const signInWithPopup = useCallback(async () => {
+    setError(null);
+    setIsLoading(true);
 
-      // Check if popup was closed
-      const checkClosed = setInterval(() => {
-        if (popup.closed) {
-          clearInterval(checkClosed);
-          window.removeEventListener('message', handleMessage);
-          setIsLoading(false);
-        }
-      }, 500);
+    try {
+      const session = await crossDomainAuth.signInWithPopup();
+      await handleAuthSuccess(session, 'popup');
     } catch (err) {
-      console.error('[WebOxy] Sign in error:', err);
-      setError(err instanceof Error ? err.message : 'Sign in failed');
-      setIsLoading(false);
+      handleAuthError(err);
     }
-  }, [authWebUrl]);
+  }, [crossDomainAuth, handleAuthSuccess, handleAuthError]);
 
+  /**
+   * Sign in with redirect specifically
+   */
+  const signInWithRedirect = useCallback(() => {
+    setError(null);
+    crossDomainAuth.signInWithRedirect({
+      redirectUri: typeof window !== 'undefined' ? window.location.href : undefined,
+    });
+  }, [crossDomainAuth]);
+
+  /**
+   * Check if FedCM is supported
+   */
+  const isFedCMSupported = useCallback(() => {
+    return crossDomainAuth.isFedCMSupported();
+  }, [crossDomainAuth]);
+
+  /**
+   * Sign out via AuthManager (handles FedCM revocation and storage cleanup)
+   */
   const signOut = useCallback(async () => {
     setError(null);
 
     try {
-      // Clear stored token
-      if (typeof window !== 'undefined') {
-        localStorage.removeItem('oxy-access-token');
-      }
+      // Use centralized AuthManager for sign out (handles FedCM, storage cleanup)
+      await authManager.signOut();
 
+      // Clear user state
       setUser(null);
     } catch (err) {
-      console.error('[WebOxy] Sign out error:', err);
-      setError(err instanceof Error ? err.message : 'Sign out failed');
+      const errorMessage = err instanceof Error ? err.message : 'Sign out failed';
+      setError(errorMessage);
+      onError?.(err instanceof Error ? err : new Error(errorMessage));
     }
-  }, []);
+  }, [authManager, onError]);
 
-  const contextValue: WebOxyContextValue = {
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => {
+      authManager.destroy();
+    };
+  }, [authManager]);
+
+  // Memoize context value to prevent unnecessary re-renders
+  const contextValue = useMemo<WebOxyContextValue>(() => ({
+    // State
     user,
     isAuthenticated,
     isLoading,
     error,
+    // Services
+    oxyServices,
+    crossDomainAuth,
+    authManager,
+    // Actions
     signIn,
+    signInWithFedCM,
+    signInWithPopup,
+    signInWithRedirect,
     signOut,
+    isFedCMSupported,
+  }), [
+    user,
+    isAuthenticated,
+    isLoading,
+    error,
     oxyServices,
-  };
+    crossDomainAuth,
+    authManager,
+    signIn,
+    signInWithFedCM,
+    signInWithPopup,
+    signInWithRedirect,
+    signOut,
+    isFedCMSupported,
+  ]);
 
   return (
     <QueryClientProvider client={queryClient}>
@@ -188,7 +384,13 @@ export function WebOxyProvider({
   );
 }
 
-export function useWebOxy() {
+/**
+ * Hook to access the full Web Oxy context.
+ *
+ * @returns Full context value including oxyServices and crossDomainAuth
+ * @throws Error if used outside WebOxyProvider
+ */
+export function useWebOxy(): WebOxyContextValue {
   const context = useContext(WebOxyContext);
   if (!context) {
     throw new Error('useWebOxy must be used within WebOxyProvider');
@@ -196,17 +398,73 @@ export function useWebOxy() {
   return context;
 }
 
+/**
+ * Hook for authentication in web apps.
+ *
+ * Provides a simplified interface for common auth operations.
+ *
+ * @returns Auth state and actions
+ * @throws Error if used outside WebOxyProvider
+ *
+ * @example
+ * ```tsx
+ * function LoginPage() {
+ *   const { user, isAuthenticated, isLoading, signIn, signOut, isFedCMSupported } = useAuth();
+ *
+ *   if (isLoading) return <Spinner />;
+ *
+ *   if (isAuthenticated) {
+ *     return (
+ *       <div>
+ *         <p>Welcome, {user.username}!</p>
+ *         <button onClick={signOut}>Sign Out</button>
+ *       </div>
+ *     );
+ *   }
+ *
+ *   return (
+ *     <button onClick={signIn}>
+ *       {isFedCMSupported() ? 'Sign in with Oxy' : 'Sign in'}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
 export function useAuth() {
-  const { user, isAuthenticated, isLoading, error, signIn, signOut, oxyServices } = useWebOxy();
+  const {
+    user,
+    isAuthenticated,
+    isLoading,
+    error,
+    signIn,
+    signInWithFedCM,
+    signInWithPopup,
+    signInWithRedirect,
+    signOut,
+    isFedCMSupported,
+    oxyServices,
+    authManager,
+  } = useWebOxy();
 
   return {
+    // State
     user,
     isAuthenticated,
     isLoading,
     isReady: !isLoading,
     error,
+    // Actions
     signIn,
+    signInWithFedCM,
+    signInWithPopup,
+    signInWithRedirect,
     signOut,
+    // Utilities
+    isFedCMSupported,
     oxyServices,
+    authManager,
   };
 }
+
+// Default export for convenience
+export default WebOxyProvider;

package/src/web/index.ts

@@ -7,7 +7,7 @@
  * Features:
  * - WebOxyProvider for React context
  * - useAuth hook for authentication
- * - Cross-domain SSO via FedCM
+ * - Cross-domain SSO via FedCM, popup, or redirect
  * - Full TypeScript support
  * - Zero bundler configuration needed
  *
@@ -24,8 +24,13 @@
  * }
  *
  * function YourApp() {
- *   const { user, isAuthenticated, signIn, signOut } = useAuth();
- *   // ... your app logic
+ *   const { user, isAuthenticated, signIn, signOut, isFedCMSupported } = useAuth();
+ *
+ *   return (
+ *     <button onClick={signIn}>
+ *       {isFedCMSupported() ? 'Sign in with Oxy' : 'Sign in'}
+ *     </button>
+ *   );
  * }
  * ```
  */
@@ -41,17 +46,79 @@ export {
   CrossDomainAuth,
   createCrossDomainAuth,
   DeviceManager,
+  // Centralized auth management
+  AuthManager,
+  createAuthManager,
 } from '../core';
 
 export type {
   CrossDomainAuthOptions,
   DeviceFingerprint,
   StoredDeviceInfo,
+  // Auth manager types
+  StorageAdapter,
+  AuthStateChangeCallback,
+  AuthMethod,
+  AuthManagerConfig,
 } from '../core';
 
 // ==================== Web Components ====================
-export { WebOxyProvider, useWebOxy, useAuth } from './WebOxyContext';
-export type { WebOxyProviderProps, WebAuthState, WebAuthActions, WebOxyContextValue } from './WebOxyContext';
+export {
+  WebOxyProvider,
+  useWebOxy,
+  useAuth,
+} from './WebOxyContext';
+
+export type {
+  WebOxyProviderProps,
+  WebAuthState,
+  WebAuthActions,
+  WebOxyContextValue,
+} from './WebOxyContext';
+
+// ==================== Shared Utilities ====================
+// Re-export shared utilities that work everywhere
+export {
+  // Color utilities
+  darkenColor,
+  lightenColor,
+  hexToRgb,
+  rgbToHex,
+  withOpacity,
+  isLightColor,
+  getContrastTextColor,
+} from '../shared/utils/colorUtils';
+
+export {
+  // Theme utilities
+  normalizeTheme,
+  normalizeColorScheme,
+  getOppositeTheme,
+  systemPrefersDarkMode,
+  getSystemColorScheme,
+} from '../shared/utils/themeUtils';
+export type { ThemeValue } from '../shared/utils/themeUtils';
+
+export {
+  // Error utilities
+  HttpStatus,
+  getErrorStatus,
+  getErrorMessage,
+  isAlreadyRegisteredError,
+  isUnauthorizedError,
+  isForbiddenError,
+  isNotFoundError,
+  isRateLimitError,
+  isServerError,
+  isNetworkError,
+  isRetryableError,
+} from '../shared/utils/errorUtils';
+
+export {
+  // Network utilities
+  delay,
+  withRetry,
+} from '../shared/utils/networkUtils';
 
 // ==================== Models & Types ====================
 // Re-export commonly used types
@@ -66,12 +133,15 @@ export type {
   KarmaRule,
   Transaction,
   DeviceSession,
+  LoginResponse,
 } from '../models/interfaces';
 
+export type { SessionLoginResponse } from '../models/session';
+
 // Re-export session types
-export type { ClientSession } from '../models/session';
+export type { ClientSession, MinimalUserData } from '../models/session';
 
-// ==================== Utilities ====================
+// ==================== Language Utilities ====================
 export {
   SUPPORTED_LANGUAGES,
   getLanguageMetadata,