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

package/src/use-admin-hooks.ts

@@ -0,0 +1,309 @@
+/**
+ * Admin Settings and Management Hooks
+ *
+ * Hooks for managing application settings, system settings, and webhooks.
+ */
+
+import { useState, useEffect, useCallback } from 'react'
+import { useFluxbaseClient } from './context'
+import type {
+  AppSettings,
+  UpdateAppSettingsRequest,
+  SystemSetting,
+  UpdateSystemSettingRequest,
+  Webhook,
+  CreateWebhookRequest,
+  UpdateWebhookRequest
+} from '@fluxbase/sdk'
+
+// ============================================================================
+// useAppSettings Hook
+// ============================================================================
+
+export interface UseAppSettingsOptions {
+  autoFetch?: boolean
+}
+
+export interface UseAppSettingsReturn {
+  settings: AppSettings | null
+  isLoading: boolean
+  error: Error | null
+  refetch: () => Promise<void>
+  updateSettings: (update: UpdateAppSettingsRequest) => Promise<void>
+}
+
+/**
+ * Hook for managing application settings
+ *
+ * @example
+ * ```tsx
+ * function SettingsPanel() {
+ *   const { settings, isLoading, updateSettings } = useAppSettings({ autoFetch: true })
+ *
+ *   const handleToggleFeature = async (feature: string, enabled: boolean) => {
+ *     await updateSettings({
+ *       features: { ...settings?.features, [feature]: enabled }
+ *     })
+ *   }
+ *
+ *   return <div>...</div>
+ * }
+ * ```
+ */
+export function useAppSettings(options: UseAppSettingsOptions = {}): UseAppSettingsReturn {
+  const { autoFetch = true } = options
+  const client = useFluxbaseClient()
+
+  const [settings, setSettings] = useState<AppSettings | null>(null)
+  const [isLoading, setIsLoading] = useState(autoFetch)
+  const [error, setError] = useState<Error | null>(null)
+
+  const fetchSettings = useCallback(async () => {
+    try {
+      setIsLoading(true)
+      setError(null)
+      const appSettings = await client.admin.settings.app.get()
+      setSettings(appSettings)
+    } catch (err) {
+      setError(err as Error)
+    } finally {
+      setIsLoading(false)
+    }
+  }, [client])
+
+  const updateSettings = useCallback(
+    async (update: UpdateAppSettingsRequest): Promise<void> => {
+      await client.admin.settings.app.update(update)
+      await fetchSettings()
+    },
+    [client, fetchSettings]
+  )
+
+  useEffect(() => {
+    if (autoFetch) {
+      fetchSettings()
+    }
+  }, [autoFetch, fetchSettings])
+
+  return {
+    settings,
+    isLoading,
+    error,
+    refetch: fetchSettings,
+    updateSettings
+  }
+}
+
+// ============================================================================
+// useSystemSettings Hook
+// ============================================================================
+
+export interface UseSystemSettingsOptions {
+  autoFetch?: boolean
+}
+
+export interface UseSystemSettingsReturn {
+  settings: SystemSetting[]
+  isLoading: boolean
+  error: Error | null
+  refetch: () => Promise<void>
+  getSetting: (key: string) => SystemSetting | undefined
+  updateSetting: (key: string, update: UpdateSystemSettingRequest) => Promise<void>
+  deleteSetting: (key: string) => Promise<void>
+}
+
+/**
+ * Hook for managing system settings (key-value storage)
+ *
+ * @example
+ * ```tsx
+ * function SystemSettings() {
+ *   const { settings, isLoading, updateSetting } = useSystemSettings({ autoFetch: true })
+ *
+ *   const handleUpdateSetting = async (key: string, value: any) => {
+ *     await updateSetting(key, { value })
+ *   }
+ *
+ *   return <div>...</div>
+ * }
+ * ```
+ */
+export function useSystemSettings(options: UseSystemSettingsOptions = {}): UseSystemSettingsReturn {
+  const { autoFetch = true } = options
+  const client = useFluxbaseClient()
+
+  const [settings, setSettings] = useState<SystemSetting[]>([])
+  const [isLoading, setIsLoading] = useState(autoFetch)
+  const [error, setError] = useState<Error | null>(null)
+
+  const fetchSettings = useCallback(async () => {
+    try {
+      setIsLoading(true)
+      setError(null)
+      const response = await client.admin.settings.system.list()
+      setSettings(response.settings)
+    } catch (err) {
+      setError(err as Error)
+    } finally {
+      setIsLoading(false)
+    }
+  }, [client])
+
+  const getSetting = useCallback(
+    (key: string): SystemSetting | undefined => {
+      return settings.find((s) => s.key === key)
+    },
+    [settings]
+  )
+
+  const updateSetting = useCallback(
+    async (key: string, update: UpdateSystemSettingRequest): Promise<void> => {
+      await client.admin.settings.system.update(key, update)
+      await fetchSettings()
+    },
+    [client, fetchSettings]
+  )
+
+  const deleteSetting = useCallback(
+    async (key: string): Promise<void> => {
+      await client.admin.settings.system.delete(key)
+      await fetchSettings()
+    },
+    [client, fetchSettings]
+  )
+
+  useEffect(() => {
+    if (autoFetch) {
+      fetchSettings()
+    }
+  }, [autoFetch, fetchSettings])
+
+  return {
+    settings,
+    isLoading,
+    error,
+    refetch: fetchSettings,
+    getSetting,
+    updateSetting,
+    deleteSetting
+  }
+}
+
+// ============================================================================
+// useWebhooks Hook
+// ============================================================================
+
+export interface UseWebhooksOptions {
+  autoFetch?: boolean
+  refetchInterval?: number
+}
+
+export interface UseWebhooksReturn {
+  webhooks: Webhook[]
+  isLoading: boolean
+  error: Error | null
+  refetch: () => Promise<void>
+  createWebhook: (webhook: CreateWebhookRequest) => Promise<Webhook>
+  updateWebhook: (id: string, update: UpdateWebhookRequest) => Promise<Webhook>
+  deleteWebhook: (id: string) => Promise<void>
+  testWebhook: (id: string) => Promise<void>
+}
+
+/**
+ * Hook for managing webhooks
+ *
+ * @example
+ * ```tsx
+ * function WebhooksManager() {
+ *   const { webhooks, isLoading, createWebhook, deleteWebhook } = useWebhooks({
+ *     autoFetch: true
+ *   })
+ *
+ *   const handleCreate = async () => {
+ *     await createWebhook({
+ *       url: 'https://example.com/webhook',
+ *       events: ['user.created', 'user.updated'],
+ *       enabled: true
+ *     })
+ *   }
+ *
+ *   return <div>...</div>
+ * }
+ * ```
+ */
+export function useWebhooks(options: UseWebhooksOptions = {}): UseWebhooksReturn {
+  const { autoFetch = true, refetchInterval = 0 } = options
+  const client = useFluxbaseClient()
+
+  const [webhooks, setWebhooks] = useState<Webhook[]>([])
+  const [isLoading, setIsLoading] = useState(autoFetch)
+  const [error, setError] = useState<Error | null>(null)
+
+  const fetchWebhooks = useCallback(async () => {
+    try {
+      setIsLoading(true)
+      setError(null)
+      const response = await client.admin.management.webhooks.list()
+      setWebhooks(response.webhooks)
+    } catch (err) {
+      setError(err as Error)
+    } finally {
+      setIsLoading(false)
+    }
+  }, [client])
+
+  const createWebhook = useCallback(
+    async (webhook: CreateWebhookRequest): Promise<Webhook> => {
+      const created = await client.admin.management.webhooks.create(webhook)
+      await fetchWebhooks()
+      return created
+    },
+    [client, fetchWebhooks]
+  )
+
+  const updateWebhook = useCallback(
+    async (id: string, update: UpdateWebhookRequest): Promise<Webhook> => {
+      const updated = await client.admin.management.webhooks.update(id, update)
+      await fetchWebhooks()
+      return updated
+    },
+    [client, fetchWebhooks]
+  )
+
+  const deleteWebhook = useCallback(
+    async (id: string): Promise<void> => {
+      await client.admin.management.webhooks.delete(id)
+      await fetchWebhooks()
+    },
+    [client, fetchWebhooks]
+  )
+
+  const testWebhook = useCallback(
+    async (id: string): Promise<void> => {
+      await client.admin.management.webhooks.test(id)
+    },
+    [client]
+  )
+
+  useEffect(() => {
+    if (autoFetch) {
+      fetchWebhooks()
+    }
+
+    if (refetchInterval > 0) {
+      const interval = setInterval(fetchWebhooks, refetchInterval)
+      return () => clearInterval(interval)
+    }
+  }, [autoFetch, refetchInterval, fetchWebhooks])
+
+  return {
+    webhooks,
+    isLoading,
+    error,
+    refetch: fetchWebhooks,
+    createWebhook,
+    updateWebhook,
+    deleteWebhook,
+    testWebhook
+  }
+}

package/src/use-auth-config.test.ts

@@ -0,0 +1,145 @@
+/**
+ * Tests for auth configuration hook
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { renderHook, waitFor } from '@testing-library/react';
+import { useAuthConfig } from './use-auth-config';
+import { createMockClient, createWrapper } from './test-utils';
+
+describe('useAuthConfig', () => {
+  it('should fetch auth configuration', async () => {
+    const mockConfig = {
+      signup_enabled: true,
+      email_verification_required: true,
+      magic_link_enabled: true,
+      mfa_enabled: true,
+      password_min_length: 8,
+      password_require_uppercase: true,
+      password_require_lowercase: true,
+      password_require_number: true,
+      password_require_special: false,
+      oauth_providers: [
+        { provider: 'google', display_name: 'Google', authorize_url: 'https://google.com/oauth' },
+      ],
+      saml_providers: [],
+      captcha: { enabled: false },
+    };
+
+    const getAuthConfigMock = vi.fn().mockResolvedValue({ data: mockConfig, error: null });
+
+    const client = createMockClient({
+      auth: { getAuthConfig: getAuthConfigMock },
+    } as any);
+
+    const { result } = renderHook(
+      () => useAuthConfig(),
+      { wrapper: createWrapper(client) }
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(result.current.data).toEqual(mockConfig);
+    expect(getAuthConfigMock).toHaveBeenCalled();
+  });
+
+  it('should throw error on fetch failure', async () => {
+    const error = new Error('Failed to fetch config');
+    const getAuthConfigMock = vi.fn().mockResolvedValue({ data: null, error });
+
+    const client = createMockClient({
+      auth: { getAuthConfig: getAuthConfigMock },
+    } as any);
+
+    const { result } = renderHook(
+      () => useAuthConfig(),
+      { wrapper: createWrapper(client) }
+    );
+
+    await waitFor(() => expect(result.current.isError).toBe(true));
+    expect(result.current.error).toBe(error);
+  });
+
+  it('should have appropriate stale time', async () => {
+    const mockConfig = { signup_enabled: true };
+    const getAuthConfigMock = vi.fn().mockResolvedValue({ data: mockConfig, error: null });
+
+    const client = createMockClient({
+      auth: { getAuthConfig: getAuthConfigMock },
+    } as any);
+
+    const { result } = renderHook(
+      () => useAuthConfig(),
+      { wrapper: createWrapper(client) }
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    // The config should be cached with a stale time of 5 minutes
+    // Verify the data is available
+    expect(result.current.data).toEqual(mockConfig);
+  });
+
+  it('should return signup enabled status', async () => {
+    const mockConfig = { signup_enabled: false };
+    const getAuthConfigMock = vi.fn().mockResolvedValue({ data: mockConfig, error: null });
+
+    const client = createMockClient({
+      auth: { getAuthConfig: getAuthConfigMock },
+    } as any);
+
+    const { result } = renderHook(
+      () => useAuthConfig(),
+      { wrapper: createWrapper(client) }
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(result.current.data?.signup_enabled).toBe(false);
+  });
+
+  it('should return OAuth providers', async () => {
+    const mockConfig = {
+      oauth_providers: [
+        { provider: 'google', display_name: 'Google', authorize_url: 'https://google.com' },
+        { provider: 'github', display_name: 'GitHub', authorize_url: 'https://github.com' },
+      ],
+    };
+    const getAuthConfigMock = vi.fn().mockResolvedValue({ data: mockConfig, error: null });
+
+    const client = createMockClient({
+      auth: { getAuthConfig: getAuthConfigMock },
+    } as any);
+
+    const { result } = renderHook(
+      () => useAuthConfig(),
+      { wrapper: createWrapper(client) }
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(result.current.data?.oauth_providers).toHaveLength(2);
+  });
+
+  it('should return password requirements', async () => {
+    const mockConfig = {
+      password_min_length: 12,
+      password_require_uppercase: true,
+      password_require_lowercase: true,
+      password_require_number: true,
+      password_require_special: true,
+    };
+    const getAuthConfigMock = vi.fn().mockResolvedValue({ data: mockConfig, error: null });
+
+    const client = createMockClient({
+      auth: { getAuthConfig: getAuthConfigMock },
+    } as any);
+
+    const { result } = renderHook(
+      () => useAuthConfig(),
+      { wrapper: createWrapper(client) }
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(result.current.data?.password_min_length).toBe(12);
+    expect(result.current.data?.password_require_uppercase).toBe(true);
+    expect(result.current.data?.password_require_special).toBe(true);
+  });
+});

package/src/use-auth-config.ts

@@ -0,0 +1,101 @@
+/**
+ * Auth configuration hooks for Fluxbase SDK
+ *
+ * Provides hooks to fetch comprehensive authentication configuration
+ * from the server including signup status, OAuth/SAML providers,
+ * password requirements, and CAPTCHA settings.
+ */
+
+import { useQuery } from "@tanstack/react-query";
+import { useFluxbaseClient } from "./context";
+import type { AuthConfig } from "@fluxbase/sdk";
+
+/**
+ * Hook to get the complete authentication configuration from the server
+ *
+ * Returns all public auth settings in a single request including:
+ * - Signup enabled status
+ * - Email verification requirements
+ * - Magic link availability
+ * - MFA availability
+ * - Password requirements (length, complexity)
+ * - Available OAuth providers (Google, GitHub, etc.)
+ * - Available SAML providers (enterprise SSO)
+ * - CAPTCHA configuration
+ *
+ * Use this to conditionally render UI elements based on server configuration,
+ * such as hiding signup forms when signup is disabled or displaying available
+ * OAuth provider buttons.
+ *
+ * @returns Query result with authentication configuration
+ *
+ * @example
+ * ```tsx
+ * function AuthPage() {
+ *   const { data: config, isLoading } = useAuthConfig();
+ *
+ *   if (isLoading) return <Loading />;
+ *
+ *   return (
+ *     <div>
+ *       {config?.signup_enabled && (
+ *         <SignupForm passwordMinLength={config.password_min_length} />
+ *       )}
+ *
+ *       {config?.oauth_providers.map(provider => (
+ *         <OAuthButton
+ *           key={provider.provider}
+ *           provider={provider.provider}
+ *           displayName={provider.display_name}
+ *           authorizeUrl={provider.authorize_url}
+ *         />
+ *       ))}
+ *
+ *       {config?.saml_providers.map(provider => (
+ *         <SAMLButton
+ *           key={provider.provider}
+ *           provider={provider.provider}
+ *           displayName={provider.display_name}
+ *         />
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example Showing password requirements
+ * ```tsx
+ * function PasswordInput() {
+ *   const { data: config } = useAuthConfig();
+ *
+ *   return (
+ *     <div>
+ *       <input type="password" minLength={config?.password_min_length} />
+ *       <ul>
+ *         <li>Minimum {config?.password_min_length || 8} characters</li>
+ *         {config?.password_require_uppercase && <li>One uppercase letter</li>}
+ *         {config?.password_require_lowercase && <li>One lowercase letter</li>}
+ *         {config?.password_require_number && <li>One number</li>}
+ *         {config?.password_require_special && <li>One special character</li>}
+ *       </ul>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useAuthConfig() {
+  const client = useFluxbaseClient();
+
+  return useQuery<AuthConfig>({
+    queryKey: ["fluxbase", "auth", "config"],
+    queryFn: async () => {
+      const { data, error } = await client.auth.getAuthConfig();
+      if (error) {
+        throw error;
+      }
+      return data!;
+    },
+    staleTime: 1000 * 60 * 5, // Cache for 5 minutes (config changes infrequently)
+    gcTime: 1000 * 60 * 60, // Keep in cache for 1 hour
+  });
+}