@oxyhq/services 5.25.0 → 5.26.1

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/utils/platform.ts

@@ -0,0 +1,117 @@
+/**
+ * Platform Detection Utility
+ *
+ * Provides platform detection WITHOUT importing from 'react-native'.
+ * This allows core modules to be used in web/Node.js environments
+ * without bundlers failing on react-native imports.
+ */
+
+export type PlatformOS = 'ios' | 'android' | 'web' | 'windows' | 'macos' | 'unknown';
+
+/**
+ * Detect the current platform without importing react-native
+ *
+ * Detection order:
+ * 1. Check for React Native's Platform object on globalThis (set by RN runtime)
+ * 2. Check for Node.js environment
+ * 3. Check for browser environment
+ * 4. Fall back to 'unknown'
+ */
+function detectPlatform(): PlatformOS {
+  // Check if React Native Platform is available globally (set by RN runtime)
+  // This avoids static imports while still detecting RN environment
+  const rnPlatform = (globalThis as any).__REACT_NATIVE_PLATFORM__;
+  if (rnPlatform) {
+    return rnPlatform as PlatformOS;
+  }
+
+  // Check navigator.product for React Native
+  if (typeof navigator !== 'undefined' && navigator.product === 'ReactNative') {
+    // We're in React Native but Platform wasn't set globally
+    // Try to get OS from userAgent or default to 'unknown'
+    return 'unknown';
+  }
+
+  // Check for Node.js environment
+  if (typeof process !== 'undefined' && process.versions?.node) {
+    return 'web'; // Treat Node.js as 'web' for compatibility (no native features)
+  }
+
+  // Check for browser/web environment
+  if (typeof window !== 'undefined' && typeof document !== 'undefined') {
+    return 'web';
+  }
+
+  return 'unknown';
+}
+
+// Cache the platform detection result
+let cachedPlatform: PlatformOS | null = null;
+
+/**
+ * Get the current platform OS
+ * Safe to call from any environment (web, Node.js, React Native)
+ */
+export function getPlatformOS(): PlatformOS {
+  if (cachedPlatform === null) {
+    cachedPlatform = detectPlatform();
+  }
+  return cachedPlatform;
+}
+
+/**
+ * Check if running on web platform (browser or Node.js)
+ */
+export function isWeb(): boolean {
+  return getPlatformOS() === 'web';
+}
+
+/**
+ * Check if running in a native app (iOS or Android)
+ */
+export function isNative(): boolean {
+  const os = getPlatformOS();
+  return os === 'ios' || os === 'android';
+}
+
+/**
+ * Check if running on iOS
+ */
+export function isIOS(): boolean {
+  return getPlatformOS() === 'ios';
+}
+
+/**
+ * Check if running on Android
+ */
+export function isAndroid(): boolean {
+  return getPlatformOS() === 'android';
+}
+
+/**
+ * Set the platform OS explicitly
+ * Called by React Native entry point to register the platform
+ * This allows lazy detection in environments where react-native is available
+ */
+export function setPlatformOS(os: PlatformOS): void {
+  cachedPlatform = os;
+  (globalThis as any).__REACT_NATIVE_PLATFORM__ = os;
+}
+
+/**
+ * Try to initialize platform from react-native if available
+ * This is called lazily when needed, avoiding top-level imports
+ */
+export async function initPlatformFromReactNative(): Promise<void> {
+  if (cachedPlatform !== null && cachedPlatform !== 'unknown') {
+    return; // Already initialized
+  }
+
+  try {
+    // Dynamic import to avoid bundler issues
+    const { Platform } = await import('react-native');
+    setPlatformOS(Platform.OS as PlatformOS);
+  } catch {
+    // react-native not available, use detected platform
+  }
+}

package/src/web/WebOxyContext.tsx

@@ -1,7 +1,11 @@
 /**
  * Web-Only Oxy Context
- * Clean implementation with ZERO React Native dependencies
- * Uses CrossDomainAuth for proper SSO flow
+ *
+ * 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 {
@@ -9,75 +13,215 @@ import {
   useCallback,
   useContext,
   useEffect,
+  useMemo,
   useState,
   type ReactNode,
 } from 'react';
-import { OxyServices, createCrossDomainAuth } 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 { MinimalUserData } from '../models/session';
+import type { SessionLoginResponse, MinimalUserData } from '../models/session';
 import { QueryClientProvider } from '@tanstack/react-query';
 import { createQueryClient } from '../ui/hooks/queryClient';
 
 export interface WebAuthState {
-  user: MinimalUserData | null;
+  user: User | null;
   isAuthenticated: boolean;
   isLoading: boolean;
   error: string | null;
 }
 
 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;
-  onAuthStateChange?: (user: MinimalUserData | null) => void;
+  /** 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
- * Uses CrossDomainAuth for automatic SSO with FedCM/Popup/Redirect fallback
+ *
+ * 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(() => createCrossDomainAuth(oxyServices));
-  const [user, setUser] = useState<MinimalUserData | null>(null);
-  const [isLoading, setIsLoading] = useState(true);
-  const [error, setError] = useState<string | null>(null);
+  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(!skipAutoCheck);
+  const [error, setError] = useState<string | null>(null);
+
   const isAuthenticated = !!user;
 
-  // Initialize - handle callbacks, restore session, try silent sign-in
+  /**
+   * 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 {
-        // Complete initialization: handles callbacks, restores session, tries silent sign-in
-        const session = await crossDomainAuth.initialize();
+        // 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 && session?.user) {
-          setUser(session.user);
+        // 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);
         }
@@ -89,63 +233,147 @@ export function WebOxyProvider({
     return () => {
       mounted = false;
     };
-  }, [crossDomainAuth]);
+  }, [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 {
-      // Sign in with automatic method selection (FedCM → Popup → Redirect)
       const session = await crossDomainAuth.signIn({
-        method: 'auto', // Automatic fallback
+        method: preferredAuthMethod,
         onMethodSelected: (method) => {
-          console.log('[WebOxy] Using auth method:', method);
+          selectedMethod = method as 'fedcm' | 'popup' | 'redirect';
         },
       });
 
-      if (session?.user) {
-        setUser(session.user);
+      if (session) {
+        await handleAuthSuccess(session, selectedMethod);
+      } else {
+        // Redirect method - page will reload
+        setIsLoading(false);
       }
     } catch (err) {
-      console.error('[WebOxy] Sign in error:', err);
-      setError(err instanceof Error ? err.message : 'Sign in failed');
-    } finally {
-      setIsLoading(false);
+      handleAuthError(err);
     }
+  }, [crossDomainAuth, preferredAuthMethod, handleAuthSuccess, handleAuthError]);
+
+  /**
+   * Sign in with FedCM specifically
+   */
+  const signInWithFedCM = useCallback(async () => {
+    setError(null);
+    setIsLoading(true);
+
+    try {
+      const session = await crossDomainAuth.signInWithFedCM();
+      await handleAuthSuccess(session, 'fedcm');
+    } catch (err) {
+      handleAuthError(err);
+    }
+  }, [crossDomainAuth, handleAuthSuccess, handleAuthError]);
+
+  /**
+   * Sign in with popup specifically
+   */
+  const signInWithPopup = useCallback(async () => {
+    setError(null);
+    setIsLoading(true);
+
+    try {
+      const session = await crossDomainAuth.signInWithPopup();
+      await handleAuthSuccess(session, 'popup');
+    } catch (err) {
+      handleAuthError(err);
+    }
+  }, [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 session
-      if (typeof window !== 'undefined') {
-        localStorage.removeItem('oxy-session');
-        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]);
+
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => {
+      authManager.destroy();
+    };
+  }, [authManager]);
 
-  const contextValue: WebOxyContextValue = {
+  // 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}>
@@ -156,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');
@@ -164,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;