@nimbleflux/fluxbase-sdk-react 2026.3.6-rc.1

package/src/use-captcha.test.ts

@@ -0,0 +1,273 @@
+/**
+ * Tests for CAPTCHA hooks
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { renderHook, waitFor, act } from '@testing-library/react';
+import { useCaptchaConfig, useCaptcha, isCaptchaRequiredForEndpoint } from './use-captcha';
+import { createMockClient, createWrapper } from './test-utils';
+
+describe('useCaptchaConfig', () => {
+  it('should fetch CAPTCHA configuration', async () => {
+    const mockConfig = {
+      enabled: true,
+      provider: 'hcaptcha',
+      site_key: 'test-site-key',
+      endpoints: ['signup', 'login'],
+    };
+    const getCaptchaConfigMock = vi.fn().mockResolvedValue({ data: mockConfig, error: null });
+
+    const client = createMockClient({
+      auth: { getCaptchaConfig: getCaptchaConfigMock },
+    } as any);
+
+    const { result } = renderHook(
+      () => useCaptchaConfig(),
+      { wrapper: createWrapper(client) }
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(result.current.data).toEqual(mockConfig);
+  });
+
+  it('should throw error on fetch failure', async () => {
+    const error = new Error('Failed to fetch');
+    const getCaptchaConfigMock = vi.fn().mockResolvedValue({ data: null, error });
+
+    const client = createMockClient({
+      auth: { getCaptchaConfig: getCaptchaConfigMock },
+    } as any);
+
+    const { result } = renderHook(
+      () => useCaptchaConfig(),
+      { wrapper: createWrapper(client) }
+    );
+
+    await waitFor(() => expect(result.current.isError).toBe(true));
+    expect(result.current.error).toBe(error);
+  });
+});
+
+describe('useCaptcha', () => {
+  it('should initialize with empty state', () => {
+    const client = createMockClient();
+
+    const { result } = renderHook(
+      () => useCaptcha('hcaptcha'),
+      { wrapper: createWrapper(client) }
+    );
+
+    expect(result.current.token).toBeNull();
+    expect(result.current.isLoading).toBe(false);
+    expect(result.current.error).toBeNull();
+  });
+
+  it('should become ready when provider is set', async () => {
+    const client = createMockClient();
+
+    const { result } = renderHook(
+      () => useCaptcha('hcaptcha'),
+      { wrapper: createWrapper(client) }
+    );
+
+    await waitFor(() => expect(result.current.isReady).toBe(true));
+  });
+
+  it('should handle onVerify callback', () => {
+    const client = createMockClient();
+
+    const { result } = renderHook(
+      () => useCaptcha('hcaptcha'),
+      { wrapper: createWrapper(client) }
+    );
+
+    act(() => {
+      result.current.onVerify('test-token');
+    });
+
+    expect(result.current.token).toBe('test-token');
+    expect(result.current.isLoading).toBe(false);
+  });
+
+  it('should handle onExpire callback', () => {
+    const client = createMockClient();
+
+    const { result } = renderHook(
+      () => useCaptcha('hcaptcha'),
+      { wrapper: createWrapper(client) }
+    );
+
+    // First verify
+    act(() => {
+      result.current.onVerify('test-token');
+    });
+
+    expect(result.current.token).toBe('test-token');
+
+    // Then expire
+    act(() => {
+      result.current.onExpire();
+    });
+
+    expect(result.current.token).toBeNull();
+    expect(result.current.isReady).toBe(true);
+  });
+
+  it('should handle onError callback', () => {
+    const client = createMockClient();
+
+    const { result } = renderHook(
+      () => useCaptcha('hcaptcha'),
+      { wrapper: createWrapper(client) }
+    );
+
+    const error = new Error('CAPTCHA error');
+    act(() => {
+      result.current.onError(error);
+    });
+
+    expect(result.current.error).toBe(error);
+    expect(result.current.token).toBeNull();
+    expect(result.current.isLoading).toBe(false);
+  });
+
+  it('should reset state', () => {
+    const client = createMockClient();
+
+    const { result } = renderHook(
+      () => useCaptcha('hcaptcha'),
+      { wrapper: createWrapper(client) }
+    );
+
+    // Set a token
+    act(() => {
+      result.current.onVerify('test-token');
+    });
+
+    expect(result.current.token).toBe('test-token');
+
+    // Reset
+    act(() => {
+      result.current.reset();
+    });
+
+    expect(result.current.token).toBeNull();
+    expect(result.current.error).toBeNull();
+    expect(result.current.isLoading).toBe(false);
+  });
+
+  it('should return existing token in execute', async () => {
+    const client = createMockClient();
+
+    const { result } = renderHook(
+      () => useCaptcha('hcaptcha'),
+      { wrapper: createWrapper(client) }
+    );
+
+    // Set a token
+    act(() => {
+      result.current.onVerify('existing-token');
+    });
+
+    // Execute should return existing token
+    let token;
+    await act(async () => {
+      token = await result.current.execute();
+    });
+
+    expect(token).toBe('existing-token');
+  });
+
+  it('should return empty string in execute when no provider', async () => {
+    const client = createMockClient();
+
+    const { result } = renderHook(
+      () => useCaptcha(undefined),
+      { wrapper: createWrapper(client) }
+    );
+
+    let token;
+    await act(async () => {
+      token = await result.current.execute();
+    });
+
+    expect(token).toBe('');
+  });
+
+  it('should set loading state during execute', async () => {
+    const client = createMockClient();
+
+    const { result } = renderHook(
+      () => useCaptcha('hcaptcha'),
+      { wrapper: createWrapper(client) }
+    );
+
+    // Start execute (returns a promise that needs onVerify to resolve)
+    let executePromise: Promise<string>;
+    act(() => {
+      executePromise = result.current.execute();
+    });
+
+    expect(result.current.isLoading).toBe(true);
+
+    // Resolve by calling onVerify
+    act(() => {
+      result.current.onVerify('new-token');
+    });
+
+    const token = await executePromise!;
+    expect(token).toBe('new-token');
+    expect(result.current.isLoading).toBe(false);
+  });
+
+  it('should reject execute on error', async () => {
+    const client = createMockClient();
+
+    const { result } = renderHook(
+      () => useCaptcha('hcaptcha'),
+      { wrapper: createWrapper(client) }
+    );
+
+    // Start execute
+    let executePromise: Promise<string>;
+    act(() => {
+      executePromise = result.current.execute();
+    });
+
+    // Trigger error
+    const error = new Error('CAPTCHA failed');
+    act(() => {
+      result.current.onError(error);
+    });
+
+    await expect(executePromise!).rejects.toThrow('CAPTCHA failed');
+  });
+});
+
+describe('isCaptchaRequiredForEndpoint', () => {
+  it('should return false when CAPTCHA is disabled', () => {
+    const config = { enabled: false, endpoints: ['signup', 'login'] };
+    expect(isCaptchaRequiredForEndpoint(config as any, 'signup')).toBe(false);
+  });
+
+  it('should return false when config is undefined', () => {
+    expect(isCaptchaRequiredForEndpoint(undefined, 'signup')).toBe(false);
+  });
+
+  it('should return true when endpoint is in list', () => {
+    const config = { enabled: true, endpoints: ['signup', 'login'] };
+    expect(isCaptchaRequiredForEndpoint(config as any, 'signup')).toBe(true);
+    expect(isCaptchaRequiredForEndpoint(config as any, 'login')).toBe(true);
+  });
+
+  it('should return false when endpoint is not in list', () => {
+    const config = { enabled: true, endpoints: ['signup'] };
+    expect(isCaptchaRequiredForEndpoint(config as any, 'login')).toBe(false);
+    expect(isCaptchaRequiredForEndpoint(config as any, 'password_reset')).toBe(false);
+  });
+
+  it('should return false when endpoints is undefined', () => {
+    const config = { enabled: true };
+    expect(isCaptchaRequiredForEndpoint(config as any, 'signup')).toBe(false);
+  });
+});

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