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

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;
+}

package/src/{use-api-keys.ts → use-client-keys.ts}

@@ -1,20 +1,20 @@
 import { useState, useEffect, useCallback } from 'react'
 import { useFluxbaseClient } from './context'
-import type { APIKey, CreateAPIKeyRequest } from '@fluxbase/sdk'
+import type { ClientKey, CreateClientKeyRequest } from '@fluxbase/sdk'
 
-export interface UseAPIKeysOptions {
+export interface UseClientKeysOptions {
   /**
-   * Whether to automatically fetch API keys on mount
+   * Whether to automatically fetch client keys on mount
    * @default true
    */
   autoFetch?: boolean
 }
 
-export interface UseAPIKeysReturn {
+export interface UseClientKeysReturn {
   /**
-   * Array of API keys
+   * Array of client keys
    */
-  keys: APIKey[]
+  keys: ClientKey[]
 
   /**
    * Whether keys are being fetched
@@ -27,45 +27,45 @@ export interface UseAPIKeysReturn {
   error: Error | null
 
   /**
-   * Refetch API keys
+   * Refetch client keys
    */
   refetch: () => Promise<void>
 
   /**
-   * Create a new API key
+   * Create a new client key
    */
-  createKey: (request: CreateAPIKeyRequest) => Promise<{ key: string; keyData: APIKey }>
+  createKey: (request: CreateClientKeyRequest) => Promise<{ key: string; keyData: ClientKey }>
 
   /**
-   * Update an API key
+   * Update a client key
    */
   updateKey: (keyId: string, update: { name?: string; description?: string }) => Promise<void>
 
   /**
-   * Revoke an API key
+   * Revoke a client key
    */
   revokeKey: (keyId: string) => Promise<void>
 
   /**
-   * Delete an API key
+   * Delete a client key
    */
   deleteKey: (keyId: string) => Promise<void>
 }
 
 /**
- * Hook for managing API keys
+ * Hook for managing client keys
  *
- * Provides API key list and management functions.
+ * Provides client key list and management functions.
  *
  * @example
  * ```tsx
- * function APIKeyManager() {
- *   const { keys, isLoading, createKey, revokeKey } = useAPIKeys()
+ * function ClientKeyManager() {
+ *   const { keys, isLoading, createKey, revokeKey } = useClientKeys()
  *
  *   const handleCreate = async () => {
  *     const { key, keyData } = await createKey({
  *       name: 'Backend Service',
- *       description: 'API key for backend',
+ *       description: 'Client key for backend',
  *       expires_at: new Date(Date.now() + 365 * 24 * 60 * 60 * 1000).toISOString()
  *     })
  *     alert(`Key created: ${key}`)
@@ -85,23 +85,23 @@ export interface UseAPIKeysReturn {
  * }
  * ```
  */
-export function useAPIKeys(options: UseAPIKeysOptions = {}): UseAPIKeysReturn {
+export function useClientKeys(options: UseClientKeysOptions = {}): UseClientKeysReturn {
   const { autoFetch = true } = options
   const client = useFluxbaseClient()
 
-  const [keys, setKeys] = useState<APIKey[]>([])
+  const [keys, setKeys] = useState<ClientKey[]>([])
   const [isLoading, setIsLoading] = useState(autoFetch)
   const [error, setError] = useState<Error | null>(null)
 
   /**
-   * Fetch API keys from API
+   * Fetch client keys from API
    */
   const fetchKeys = useCallback(async () => {
     try {
       setIsLoading(true)
       setError(null)
-      const response = await client.admin.management.apiKeys.list()
-      setKeys(response.api_keys)
+      const response = await client.admin.management.clientKeys.list()
+      setKeys(response.client_keys)
     } catch (err) {
       setError(err as Error)
     } finally {
@@ -110,45 +110,45 @@ export function useAPIKeys(options: UseAPIKeysOptions = {}): UseAPIKeysReturn {
   }, [client])
 
   /**
-   * Create a new API key
+   * Create a new client key
    */
   const createKey = useCallback(
-    async (request: CreateAPIKeyRequest): Promise<{ key: string; keyData: APIKey }> => {
-      const response = await client.admin.management.apiKeys.create(request)
+    async (request: CreateClientKeyRequest): Promise<{ key: string; keyData: ClientKey }> => {
+      const response = await client.admin.management.clientKeys.create(request)
       await fetchKeys() // Refresh list
-      return { key: response.key, keyData: response.api_key }
+      return { key: response.key, keyData: response.client_key }
     },
     [client, fetchKeys]
   )
 
   /**
-   * Update an API key
+   * Update a client key
    */
   const updateKey = useCallback(
     async (keyId: string, update: { name?: string; description?: string }): Promise<void> => {
-      await client.admin.management.apiKeys.update(keyId, update)
+      await client.admin.management.clientKeys.update(keyId, update)
       await fetchKeys() // Refresh list
     },
     [client, fetchKeys]
   )
 
   /**
-   * Revoke an API key
+   * Revoke a client key
    */
   const revokeKey = useCallback(
     async (keyId: string): Promise<void> => {
-      await client.admin.management.apiKeys.revoke(keyId)
+      await client.admin.management.clientKeys.revoke(keyId)
       await fetchKeys() // Refresh list
     },
     [client, fetchKeys]
   )
 
   /**
-   * Delete an API key
+   * Delete a client key
    */
   const deleteKey = useCallback(
     async (keyId: string): Promise<void> => {
-      await client.admin.management.apiKeys.delete(keyId)
+      await client.admin.management.clientKeys.delete(keyId)
       await fetchKeys() // Refresh list
     },
     [client, fetchKeys]
@@ -172,3 +172,14 @@ export function useAPIKeys(options: UseAPIKeysOptions = {}): UseAPIKeysReturn {
     deleteKey
   }
 }
+
+/**
+ * @deprecated Use useClientKeys instead
+ */
+export const useAPIKeys = useClientKeys
+
+/** @deprecated Use UseClientKeysOptions instead */
+export type UseAPIKeysOptions = UseClientKeysOptions
+
+/** @deprecated Use UseClientKeysReturn instead */
+export type UseAPIKeysReturn = UseClientKeysReturn