@fluxbase/sdk-react 0.1.0-rc.1 → 2026.1.1-rc.2

package/src/use-admin-auth.ts

@@ -1,14 +1,14 @@
-import { useState, useEffect, useCallback } from 'react'
-import { useFluxbaseClient } from './context'
-import type { AdminAuthResponse } from '@fluxbase/sdk'
+import { useState, useEffect, useCallback } from "react";
+import { useFluxbaseClient } from "./context";
+import type { AdminAuthResponse, DataResponse } from "@fluxbase/sdk";
 
 /**
  * Simplified admin user type returned by authentication
  */
 export interface AdminUser {
-  id: string
-  email: string
-  role: string
+  id: string;
+  email: string;
+  role: string;
 }
 
 export interface UseAdminAuthOptions {
@@ -16,44 +16,44 @@ export interface UseAdminAuthOptions {
    * Automatically check authentication status on mount
    * @default true
    */
-  autoCheck?: boolean
+  autoCheck?: boolean;
 }
 
 export interface UseAdminAuthReturn {
   /**
    * Current admin user if authenticated
    */
-  user: AdminUser | null
+  user: AdminUser | null;
 
   /**
    * Whether the admin is authenticated
    */
-  isAuthenticated: boolean
+  isAuthenticated: boolean;
 
   /**
    * Whether the authentication check is in progress
    */
-  isLoading: boolean
+  isLoading: boolean;
 
   /**
    * Any error that occurred during authentication
    */
-  error: Error | null
+  error: Error | null;
 
   /**
    * Login as admin
    */
-  login: (email: string, password: string) => Promise<AdminAuthResponse>
+  login: (email: string, password: string) => Promise<AdminAuthResponse>;
 
   /**
    * Logout admin
    */
-  logout: () => Promise<void>
+  logout: () => Promise<void>;
 
   /**
    * Refresh admin user info
    */
-  refresh: () => Promise<void>
+  refresh: () => Promise<void>;
 }
 
 /**
@@ -78,30 +78,35 @@ export interface UseAdminAuthReturn {
  * }
  * ```
  */
-export function useAdminAuth(options: UseAdminAuthOptions = {}): UseAdminAuthReturn {
-  const { autoCheck = true } = options
-  const client = useFluxbaseClient()
+export function useAdminAuth(
+  options: UseAdminAuthOptions = {},
+): UseAdminAuthReturn {
+  const { autoCheck = true } = options;
+  const client = useFluxbaseClient();
 
-  const [user, setUser] = useState<AdminUser | null>(null)
-  const [isLoading, setIsLoading] = useState(autoCheck)
-  const [error, setError] = useState<Error | null>(null)
+  const [user, setUser] = useState<AdminUser | null>(null);
+  const [isLoading, setIsLoading] = useState(autoCheck);
+  const [error, setError] = useState<Error | null>(null);
 
   /**
    * Check current authentication status
    */
   const checkAuth = useCallback(async () => {
     try {
-      setIsLoading(true)
-      setError(null)
-      const { user } = await client.admin.me()
-      setUser(user)
+      setIsLoading(true);
+      setError(null);
+      const { data, error: apiError } = await client.admin.me();
+      if (apiError) {
+        throw apiError;
+      }
+      setUser(data!.user);
     } catch (err) {
-      setUser(null)
-      setError(err as Error)
+      setUser(null);
+      setError(err as Error);
     } finally {
-      setIsLoading(false)
+      setIsLoading(false);
     }
-  }, [client])
+  }, [client]);
 
   /**
    * Login as admin
@@ -109,52 +114,58 @@ export function useAdminAuth(options: UseAdminAuthOptions = {}): UseAdminAuthRet
   const login = useCallback(
     async (email: string, password: string): Promise<AdminAuthResponse> => {
       try {
-        setIsLoading(true)
-        setError(null)
-        const response = await client.admin.login({ email, password })
-        setUser(response.user)
-        return response
+        setIsLoading(true);
+        setError(null);
+        const { data, error: apiError } = await client.admin.login({
+          email,
+          password,
+        });
+        if (apiError) {
+          throw apiError;
+        }
+        setUser(data!.user);
+        return data!;
       } catch (err) {
-        setError(err as Error)
-        throw err
+        setError(err as Error);
+        throw err;
       } finally {
-        setIsLoading(false)
+        setIsLoading(false);
       }
     },
-    [client]
-  )
+    [client],
+  );
 
   /**
    * Logout admin
    */
   const logout = useCallback(async (): Promise<void> => {
     try {
-      setIsLoading(true)
-      setError(null)
+      setIsLoading(true);
+      setError(null);
       // Clear user state
-      setUser(null)
+      setUser(null);
       // Note: Add logout endpoint call here when available
     } catch (err) {
-      setError(err as Error)
-      throw err
+      setError(err as Error);
+      throw err;
     } finally {
-      setIsLoading(false)
+      setIsLoading(false);
     }
-  }, [])
+  }, []);
 
   /**
    * Refresh admin user info
    */
   const refresh = useCallback(async (): Promise<void> => {
-    await checkAuth()
-  }, [checkAuth])
+    await checkAuth();
+  }, [checkAuth]);
 
   // Auto-check authentication on mount
   useEffect(() => {
     if (autoCheck) {
-      checkAuth()
+      checkAuth();
     }
-  }, [autoCheck, checkAuth])
+  }, [autoCheck, checkAuth]);
 
   return {
     user,
@@ -163,6 +174,6 @@ export function useAdminAuth(options: UseAdminAuthOptions = {}): UseAdminAuthRet
     error,
     login,
     logout,
-    refresh
-  }
+    refresh,
+  };
 }

package/src/use-auth.ts

@@ -2,132 +2,149 @@
  * Authentication hooks for Fluxbase SDK
  */
 
-import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
-import { useFluxbaseClient } from './context'
-import type { SignInCredentials, SignUpCredentials, User, AuthSession } from '@fluxbase/sdk'
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useFluxbaseClient } from "./context";
+import type {
+  SignInCredentials,
+  SignUpCredentials,
+  User,
+  AuthSession,
+} from "@fluxbase/sdk";
 
 /**
  * Hook to get the current user
  */
 export function useUser() {
-  const client = useFluxbaseClient()
+  const client = useFluxbaseClient();
 
   return useQuery({
-    queryKey: ['fluxbase', 'auth', 'user'],
+    queryKey: ["fluxbase", "auth", "user"],
     queryFn: async () => {
-      const session = client.auth.getSession()
-      if (!session) {
-        return null
+      const { data } = await client.auth.getSession();
+      if (!data?.session) {
+        return null;
       }
 
       try {
-        return await client.auth.getCurrentUser()
+        const result = await client.auth.getCurrentUser();
+        return result.data?.user ?? null;
       } catch {
-        return null
+        return null;
       }
     },
     staleTime: 1000 * 60 * 5, // 5 minutes
-  })
+  });
 }
 
 /**
  * Hook to get the current session
  */
 export function useSession() {
-  const client = useFluxbaseClient()
+  const client = useFluxbaseClient();
 
   return useQuery<AuthSession | null>({
-    queryKey: ['fluxbase', 'auth', 'session'],
-    queryFn: () => client.auth.getSession(),
+    queryKey: ["fluxbase", "auth", "session"],
+    queryFn: async () => {
+      const { data } = await client.auth.getSession();
+      return data?.session ?? null;
+    },
     staleTime: 1000 * 60 * 5, // 5 minutes
-  })
+  });
 }
 
 /**
  * Hook for signing in
  */
 export function useSignIn() {
-  const client = useFluxbaseClient()
-  const queryClient = useQueryClient()
+  const client = useFluxbaseClient();
+  const queryClient = useQueryClient();
 
   return useMutation({
     mutationFn: async (credentials: SignInCredentials) => {
-      return await client.auth.signIn(credentials)
+      return await client.auth.signIn(credentials);
     },
     onSuccess: (session) => {
-      queryClient.setQueryData(['fluxbase', 'auth', 'session'], session)
+      queryClient.setQueryData(["fluxbase", "auth", "session"], session);
       // Only set user if this is a complete auth session (not 2FA required)
-      if ('user' in session) {
-        queryClient.setQueryData(['fluxbase', 'auth', 'user'], session.user)
+      if ("user" in session) {
+        queryClient.setQueryData(["fluxbase", "auth", "user"], session.user);
       }
     },
-  })
+  });
 }
 
 /**
  * Hook for signing up
  */
 export function useSignUp() {
-  const client = useFluxbaseClient()
-  const queryClient = useQueryClient()
+  const client = useFluxbaseClient();
+  const queryClient = useQueryClient();
 
   return useMutation({
     mutationFn: async (credentials: SignUpCredentials) => {
-      return await client.auth.signUp(credentials)
+      return await client.auth.signUp(credentials);
     },
-    onSuccess: (session) => {
-      queryClient.setQueryData(['fluxbase', 'auth', 'session'], session)
-      queryClient.setQueryData(['fluxbase', 'auth', 'user'], session.user)
+    onSuccess: (response) => {
+      if (response.data) {
+        queryClient.setQueryData(
+          ["fluxbase", "auth", "session"],
+          response.data.session,
+        );
+        queryClient.setQueryData(
+          ["fluxbase", "auth", "user"],
+          response.data.user,
+        );
+      }
     },
-  })
+  });
 }
 
 /**
  * Hook for signing out
  */
 export function useSignOut() {
-  const client = useFluxbaseClient()
-  const queryClient = useQueryClient()
+  const client = useFluxbaseClient();
+  const queryClient = useQueryClient();
 
   return useMutation({
     mutationFn: async () => {
-      await client.auth.signOut()
+      await client.auth.signOut();
     },
     onSuccess: () => {
-      queryClient.setQueryData(['fluxbase', 'auth', 'session'], null)
-      queryClient.setQueryData(['fluxbase', 'auth', 'user'], null)
-      queryClient.invalidateQueries({ queryKey: ['fluxbase'] })
+      queryClient.setQueryData(["fluxbase", "auth", "session"], null);
+      queryClient.setQueryData(["fluxbase", "auth", "user"], null);
+      queryClient.invalidateQueries({ queryKey: ["fluxbase"] });
     },
-  })
+  });
 }
 
 /**
  * Hook for updating the current user
  */
 export function useUpdateUser() {
-  const client = useFluxbaseClient()
-  const queryClient = useQueryClient()
+  const client = useFluxbaseClient();
+  const queryClient = useQueryClient();
 
   return useMutation({
-    mutationFn: async (data: Partial<Pick<User, 'email' | 'metadata'>>) => {
-      return await client.auth.updateUser(data)
+    mutationFn: async (data: Partial<Pick<User, "email" | "metadata">>) => {
+      return await client.auth.updateUser(data);
     },
     onSuccess: (user) => {
-      queryClient.setQueryData(['fluxbase', 'auth', 'user'], user)
+      queryClient.setQueryData(["fluxbase", "auth", "user"], user);
     },
-  })
+  });
 }
 
 /**
  * Combined auth hook with all auth state and methods
  */
 export function useAuth() {
-  const { data: user, isLoading: isLoadingUser } = useUser()
-  const { data: session, isLoading: isLoadingSession } = useSession()
-  const signIn = useSignIn()
-  const signUp = useSignUp()
-  const signOut = useSignOut()
-  const updateUser = useUpdateUser()
+  const { data: user, isLoading: isLoadingUser } = useUser();
+  const { data: session, isLoading: isLoadingSession } = useSession();
+  const signIn = useSignIn();
+  const signUp = useSignUp();
+  const signOut = useSignOut();
+  const updateUser = useUpdateUser();
 
   return {
     user,
@@ -142,5 +159,5 @@ export function useAuth() {
     isSigningUp: signUp.isPending,
     isSigningOut: signOut.isPending,
     isUpdating: updateUser.isPending,
-  }
+  };
 }

package/src/use-captcha.ts

@@ -0,0 +1,250 @@
+/**
+ * CAPTCHA hooks for Fluxbase SDK
+ *
+ * Provides hooks to:
+ * - Fetch CAPTCHA configuration from the server
+ * - Manage CAPTCHA widget state
+ */
+
+import { useQuery } from "@tanstack/react-query";
+import { useFluxbaseClient } from "./context";
+import type { CaptchaConfig, CaptchaProvider } from "@fluxbase/sdk";
+import { useCallback, useEffect, useRef, useState } from "react";
+
+/**
+ * Hook to get the CAPTCHA configuration from the server
+ * Use this to determine which CAPTCHA provider to load
+ *
+ * @example
+ * ```tsx
+ * function AuthPage() {
+ *   const { data: captchaConfig, isLoading } = useCaptchaConfig();
+ *
+ *   if (isLoading) return <Loading />;
+ *
+ *   return captchaConfig?.enabled ? (
+ *     <CaptchaWidget provider={captchaConfig.provider} siteKey={captchaConfig.site_key} />
+ *   ) : null;
+ * }
+ * ```
+ */
+export function useCaptchaConfig() {
+  const client = useFluxbaseClient();
+
+  return useQuery<CaptchaConfig>({
+    queryKey: ["fluxbase", "auth", "captcha", "config"],
+    queryFn: async () => {
+      const { data, error } = await client.auth.getCaptchaConfig();
+      if (error) {
+        throw error;
+      }
+      return data!;
+    },
+    staleTime: 1000 * 60 * 60, // Cache for 1 hour (config rarely changes)
+    gcTime: 1000 * 60 * 60 * 24, // Keep in cache for 24 hours
+  });
+}
+
+/**
+ * CAPTCHA widget state for managing token generation
+ */
+export interface CaptchaState {
+  /** Current CAPTCHA token (null until solved) */
+  token: string | null;
+  /** Whether the CAPTCHA widget is ready */
+  isReady: boolean;
+  /** Whether a token is being generated */
+  isLoading: boolean;
+  /** Any error that occurred */
+  error: Error | null;
+  /** Reset the CAPTCHA widget */
+  reset: () => void;
+  /** Execute/trigger the CAPTCHA (for invisible CAPTCHA like reCAPTCHA v3) */
+  execute: () => Promise<string>;
+  /** Callback to be called when CAPTCHA is verified */
+  onVerify: (token: string) => void;
+  /** Callback to be called when CAPTCHA expires */
+  onExpire: () => void;
+  /** Callback to be called when CAPTCHA errors */
+  onError: (error: Error) => void;
+}
+
+/**
+ * Hook to manage CAPTCHA widget state
+ *
+ * This hook provides a standardized interface for managing CAPTCHA tokens
+ * across different providers (hCaptcha, reCAPTCHA v3, Turnstile, Cap).
+ *
+ * Supported providers:
+ * - hcaptcha: Privacy-focused visual challenge
+ * - recaptcha_v3: Google's invisible risk-based CAPTCHA
+ * - turnstile: Cloudflare's invisible CAPTCHA
+ * - cap: Self-hosted proof-of-work CAPTCHA (https://capjs.js.org/)
+ *
+ * @param provider - The CAPTCHA provider type
+ * @returns CAPTCHA state and callbacks
+ *
+ * @example
+ * ```tsx
+ * function LoginForm() {
+ *   const captcha = useCaptcha('hcaptcha');
+ *
+ *   const handleSubmit = async (e: FormEvent) => {
+ *     e.preventDefault();
+ *
+ *     // Get CAPTCHA token
+ *     const captchaToken = captcha.token || await captcha.execute();
+ *
+ *     // Sign in with CAPTCHA token
+ *     await signIn({
+ *       email,
+ *       password,
+ *       captchaToken
+ *     });
+ *   };
+ *
+ *   return (
+ *     <form onSubmit={handleSubmit}>
+ *       <input name="email" />
+ *       <input name="password" type="password" />
+ *
+ *       <HCaptcha
+ *         sitekey={siteKey}
+ *         onVerify={captcha.onVerify}
+ *         onExpire={captcha.onExpire}
+ *         onError={captcha.onError}
+ *       />
+ *
+ *       <button type="submit" disabled={!captcha.isReady}>
+ *         Sign In
+ *       </button>
+ *     </form>
+ *   );
+ * }
+ * ```
+ *
+ * @example Cap provider
+ * ```tsx
+ * function LoginForm() {
+ *   const { data: config } = useCaptchaConfig();
+ *   const captcha = useCaptcha(config?.provider);
+ *
+ *   // For Cap, load the widget from cap_server_url
+ *   // <script src={`${config.cap_server_url}/widget.js`} />
+ *   // <cap-widget data-cap-url={config.cap_server_url} />
+ * }
+ * ```
+ */
+export function useCaptcha(provider?: CaptchaProvider): CaptchaState {
+  const [token, setToken] = useState<string | null>(null);
+  const [isReady, setIsReady] = useState(false);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  // Promise resolver for execute() method
+  const executeResolverRef = useRef<((token: string) => void) | null>(null);
+  const executeRejecterRef = useRef<((error: Error) => void) | null>(null);
+
+  // Callback when CAPTCHA is verified
+  const onVerify = useCallback((newToken: string) => {
+    setToken(newToken);
+    setIsLoading(false);
+    setError(null);
+    setIsReady(true);
+
+    // Resolve the execute() promise if waiting
+    if (executeResolverRef.current) {
+      executeResolverRef.current(newToken);
+      executeResolverRef.current = null;
+      executeRejecterRef.current = null;
+    }
+  }, []);
+
+  // Callback when CAPTCHA expires
+  const onExpire = useCallback(() => {
+    setToken(null);
+    setIsReady(true);
+  }, []);
+
+  // Callback when CAPTCHA errors
+  const onError = useCallback((err: Error) => {
+    setError(err);
+    setIsLoading(false);
+    setToken(null);
+
+    // Reject the execute() promise if waiting
+    if (executeRejecterRef.current) {
+      executeRejecterRef.current(err);
+      executeResolverRef.current = null;
+      executeRejecterRef.current = null;
+    }
+  }, []);
+
+  // Reset the CAPTCHA
+  const reset = useCallback(() => {
+    setToken(null);
+    setError(null);
+    setIsLoading(false);
+  }, []);
+
+  // Execute/trigger the CAPTCHA (for invisible CAPTCHA)
+  const execute = useCallback(async (): Promise<string> => {
+    // If we already have a token, return it
+    if (token) {
+      return token;
+    }
+
+    // If CAPTCHA is not configured, return empty string
+    if (!provider) {
+      return "";
+    }
+
+    setIsLoading(true);
+    setError(null);
+
+    // Return a promise that will be resolved by onVerify
+    return new Promise<string>((resolve, reject) => {
+      executeResolverRef.current = resolve;
+      executeRejecterRef.current = reject;
+
+      // For invisible CAPTCHAs, the widget should call onVerify when done
+      // The actual execution is handled by the CAPTCHA widget component
+    });
+  }, [token, provider]);
+
+  // Mark as ready when provider is set
+  useEffect(() => {
+    if (provider) {
+      setIsReady(true);
+    }
+  }, [provider]);
+
+  return {
+    token,
+    isReady,
+    isLoading,
+    error,
+    reset,
+    execute,
+    onVerify,
+    onExpire,
+    onError,
+  };
+}
+
+/**
+ * Check if CAPTCHA is required for a specific endpoint
+ *
+ * @param config - CAPTCHA configuration from useCaptchaConfig
+ * @param endpoint - The endpoint to check (e.g., 'signup', 'login', 'password_reset')
+ * @returns Whether CAPTCHA is required for this endpoint
+ */
+export function isCaptchaRequiredForEndpoint(
+  config: CaptchaConfig | undefined,
+  endpoint: string
+): boolean {
+  if (!config?.enabled) {
+    return false;
+  }
+  return config.endpoints?.includes(endpoint) ?? false;
+}