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

package/src/use-users.test.ts

@@ -0,0 +1,264 @@
+/**
+ * Tests for users management hook
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { renderHook, waitFor, act } from '@testing-library/react';
+import { useUsers } from './use-users';
+import { createMockClient, createWrapper } from './test-utils';
+
+describe('useUsers', () => {
+  it('should fetch users on mount when autoFetch is true', async () => {
+    const mockUsers = [
+      { id: '1', email: 'user1@example.com', role: 'user' },
+      { id: '2', email: 'user2@example.com', role: 'admin' },
+    ];
+    const listUsersMock = vi.fn().mockResolvedValue({
+      data: { users: mockUsers, total: 2 },
+      error: null,
+    });
+
+    const client = createMockClient({
+      admin: { listUsers: listUsersMock },
+    } as any);
+
+    const { result } = renderHook(
+      () => useUsers({ autoFetch: true }),
+      { wrapper: createWrapper(client) }
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(result.current.users).toEqual(mockUsers);
+    expect(result.current.total).toBe(2);
+  });
+
+  it('should not fetch users when autoFetch is false', async () => {
+    const listUsersMock = vi.fn();
+
+    const client = createMockClient({
+      admin: { listUsers: listUsersMock },
+    } as any);
+
+    const { result } = renderHook(
+      () => useUsers({ autoFetch: false }),
+      { wrapper: createWrapper(client) }
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(listUsersMock).not.toHaveBeenCalled();
+  });
+
+  it('should pass list options', async () => {
+    const listUsersMock = vi.fn().mockResolvedValue({
+      data: { users: [], total: 0 },
+      error: null,
+    });
+
+    const client = createMockClient({
+      admin: { listUsers: listUsersMock },
+    } as any);
+
+    renderHook(
+      () => useUsers({ autoFetch: true, limit: 10, search: 'test' }),
+      { wrapper: createWrapper(client) }
+    );
+
+    await waitFor(() => {
+      expect(listUsersMock).toHaveBeenCalledWith(
+        expect.objectContaining({ limit: 10, search: 'test' })
+      );
+    });
+  });
+
+  it('should invite user', async () => {
+    const listUsersMock = vi.fn().mockResolvedValue({
+      data: { users: [], total: 0 },
+      error: null,
+    });
+    const inviteUserMock = vi.fn().mockResolvedValue({ data: {}, error: null });
+
+    const client = createMockClient({
+      admin: {
+        listUsers: listUsersMock,
+        inviteUser: inviteUserMock,
+      },
+    } as any);
+
+    const { result } = renderHook(
+      () => useUsers({ autoFetch: true }),
+      { wrapper: createWrapper(client) }
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    await act(async () => {
+      await result.current.inviteUser('new@example.com', 'user');
+    });
+
+    expect(inviteUserMock).toHaveBeenCalledWith({ email: 'new@example.com', role: 'user' });
+    // Should refetch after invite
+    expect(listUsersMock).toHaveBeenCalledTimes(2);
+  });
+
+  it('should update user role', async () => {
+    const listUsersMock = vi.fn().mockResolvedValue({
+      data: { users: [], total: 0 },
+      error: null,
+    });
+    const updateUserRoleMock = vi.fn().mockResolvedValue({ data: {}, error: null });
+
+    const client = createMockClient({
+      admin: {
+        listUsers: listUsersMock,
+        updateUserRole: updateUserRoleMock,
+      },
+    } as any);
+
+    const { result } = renderHook(
+      () => useUsers({ autoFetch: true }),
+      { wrapper: createWrapper(client) }
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    await act(async () => {
+      await result.current.updateUserRole('1', 'admin');
+    });
+
+    expect(updateUserRoleMock).toHaveBeenCalledWith('1', 'admin');
+    // Should refetch after update
+    expect(listUsersMock).toHaveBeenCalledTimes(2);
+  });
+
+  it('should delete user', async () => {
+    const listUsersMock = vi.fn().mockResolvedValue({
+      data: { users: [], total: 0 },
+      error: null,
+    });
+    const deleteUserMock = vi.fn().mockResolvedValue({ data: {}, error: null });
+
+    const client = createMockClient({
+      admin: {
+        listUsers: listUsersMock,
+        deleteUser: deleteUserMock,
+      },
+    } as any);
+
+    const { result } = renderHook(
+      () => useUsers({ autoFetch: true }),
+      { wrapper: createWrapper(client) }
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    await act(async () => {
+      await result.current.deleteUser('1');
+    });
+
+    expect(deleteUserMock).toHaveBeenCalledWith('1');
+    // Should refetch after delete
+    expect(listUsersMock).toHaveBeenCalledTimes(2);
+  });
+
+  it('should reset user password', async () => {
+    const listUsersMock = vi.fn().mockResolvedValue({
+      data: { users: [], total: 0 },
+      error: null,
+    });
+    const resetPasswordMock = vi.fn().mockResolvedValue({
+      data: { message: 'Password reset email sent' },
+      error: null,
+    });
+
+    const client = createMockClient({
+      admin: {
+        listUsers: listUsersMock,
+        resetUserPassword: resetPasswordMock,
+      },
+    } as any);
+
+    const { result } = renderHook(
+      () => useUsers({ autoFetch: true }),
+      { wrapper: createWrapper(client) }
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    let response;
+    await act(async () => {
+      response = await result.current.resetPassword('1');
+    });
+
+    expect(resetPasswordMock).toHaveBeenCalledWith('1');
+    expect(response).toEqual({ message: 'Password reset email sent' });
+  });
+
+  it('should handle fetch error', async () => {
+    const error = new Error('Failed to fetch');
+    const listUsersMock = vi.fn().mockResolvedValue({ data: null, error });
+
+    const client = createMockClient({
+      admin: { listUsers: listUsersMock },
+    } as any);
+
+    const { result } = renderHook(
+      () => useUsers({ autoFetch: true }),
+      { wrapper: createWrapper(client) }
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(result.current.error).toBe(error);
+  });
+
+  it('should set up refetch interval', async () => {
+    vi.useFakeTimers();
+    const listUsersMock = vi.fn().mockResolvedValue({
+      data: { users: [], total: 0 },
+      error: null,
+    });
+
+    const client = createMockClient({
+      admin: { listUsers: listUsersMock },
+    } as any);
+
+    const { unmount } = renderHook(
+      () => useUsers({ autoFetch: true, refetchInterval: 5000 }),
+      { wrapper: createWrapper(client) }
+    );
+
+    // Initial fetch
+    expect(listUsersMock).toHaveBeenCalledTimes(1);
+
+    // Advance timer
+    await act(async () => {
+      vi.advanceTimersByTime(5000);
+    });
+
+    expect(listUsersMock).toHaveBeenCalledTimes(2);
+
+    unmount();
+    vi.useRealTimers();
+  });
+
+  it('should refetch on demand', async () => {
+    const listUsersMock = vi.fn().mockResolvedValue({
+      data: { users: [], total: 0 },
+      error: null,
+    });
+
+    const client = createMockClient({
+      admin: { listUsers: listUsersMock },
+    } as any);
+
+    const { result } = renderHook(
+      () => useUsers({ autoFetch: false }),
+      { wrapper: createWrapper(client) }
+    );
+
+    await act(async () => {
+      await result.current.refetch();
+    });
+
+    expect(listUsersMock).toHaveBeenCalledTimes(1);
+  });
+});

package/src/use-users.ts

@@ -0,0 +1,198 @@
+import { useState, useEffect, useCallback } from 'react'
+import { useFluxbaseClient } from './context'
+import type { EnrichedUser, ListUsersOptions } from '@fluxbase/sdk'
+
+export interface UseUsersOptions extends ListUsersOptions {
+  /**
+   * Whether to automatically fetch users on mount
+   * @default true
+   */
+  autoFetch?: boolean
+
+  /**
+   * Refetch interval in milliseconds (0 to disable)
+   * @default 0
+   */
+  refetchInterval?: number
+}
+
+export interface UseUsersReturn {
+  /**
+   * Array of users
+   */
+  users: EnrichedUser[]
+
+  /**
+   * Total number of users (for pagination)
+   */
+  total: number
+
+  /**
+   * Whether users are being fetched
+   */
+  isLoading: boolean
+
+  /**
+   * Any error that occurred
+   */
+  error: Error | null
+
+  /**
+   * Refetch users
+   */
+  refetch: () => Promise<void>
+
+  /**
+   * Invite a new user
+   */
+  inviteUser: (email: string, role: 'user' | 'admin') => Promise<void>
+
+  /**
+   * Update user role
+   */
+  updateUserRole: (userId: string, role: 'user' | 'admin') => Promise<void>
+
+  /**
+   * Delete a user
+   */
+  deleteUser: (userId: string) => Promise<void>
+
+  /**
+   * Reset user password
+   */
+  resetPassword: (userId: string) => Promise<{ message: string }>
+}
+
+/**
+ * Hook for managing users
+ *
+ * Provides user list with pagination, search, and management functions.
+ *
+ * @example
+ * ```tsx
+ * function UserList() {
+ *   const { users, total, isLoading, refetch, inviteUser, deleteUser } = useUsers({
+ *     limit: 20,
+ *     search: searchTerm
+ *   })
+ *
+ *   return (
+ *     <div>
+ *       {isLoading ? <Spinner /> : (
+ *         <ul>
+ *           {users.map(user => (
+ *             <li key={user.id}>
+ *               {user.email} - {user.role}
+ *               <button onClick={() => deleteUser(user.id)}>Delete</button>
+ *             </li>
+ *           ))}
+ *         </ul>
+ *       )}
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export function useUsers(options: UseUsersOptions = {}): UseUsersReturn {
+  const { autoFetch = true, refetchInterval = 0, ...listOptions } = options
+  const client = useFluxbaseClient()
+
+  const [users, setUsers] = useState<EnrichedUser[]>([])
+  const [total, setTotal] = useState(0)
+  const [isLoading, setIsLoading] = useState(autoFetch)
+  const [error, setError] = useState<Error | null>(null)
+
+  /**
+   * Fetch users from API
+   */
+  const fetchUsers = useCallback(async () => {
+    try {
+      setIsLoading(true)
+      setError(null)
+      const { data, error: apiError } = await client.admin.listUsers(listOptions)
+      if (apiError) {
+        throw apiError
+      }
+      setUsers(data!.users)
+      setTotal(data!.total)
+    } catch (err) {
+      setError(err as Error)
+    } finally {
+      setIsLoading(false)
+    }
+  }, [client, JSON.stringify(listOptions)])
+
+  /**
+   * Invite a new user
+   */
+  const inviteUser = useCallback(
+    async (email: string, role: 'user' | 'admin'): Promise<void> => {
+      await client.admin.inviteUser({ email, role })
+      await fetchUsers() // Refresh list
+    },
+    [client, fetchUsers]
+  )
+
+  /**
+   * Update user role
+   */
+  const updateUserRole = useCallback(
+    async (userId: string, role: 'user' | 'admin'): Promise<void> => {
+      await client.admin.updateUserRole(userId, role)
+      await fetchUsers() // Refresh list
+    },
+    [client, fetchUsers]
+  )
+
+  /**
+   * Delete a user
+   */
+  const deleteUser = useCallback(
+    async (userId: string): Promise<void> => {
+      await client.admin.deleteUser(userId)
+      await fetchUsers() // Refresh list
+    },
+    [client, fetchUsers]
+  )
+
+  /**
+   * Reset user password
+   */
+  const resetPassword = useCallback(
+    async (userId: string): Promise<{ message: string }> => {
+      const { data, error } = await client.admin.resetUserPassword(userId)
+      if (error) {
+        throw error
+      }
+      return data!
+    },
+    [client]
+  )
+
+  // Auto-fetch on mount
+  useEffect(() => {
+    if (autoFetch) {
+      fetchUsers()
+    }
+  }, [autoFetch, fetchUsers])
+
+  // Set up refetch interval
+  useEffect(() => {
+    if (refetchInterval > 0) {
+      const interval = setInterval(fetchUsers, refetchInterval)
+      return () => clearInterval(interval)
+    }
+  }, [refetchInterval, fetchUsers])
+
+  return {
+    users,
+    total,
+    isLoading,
+    error,
+    refetch: fetchUsers,
+    inviteUser,
+    updateUserRole,
+    deleteUser,
+    resetPassword
+  }
+}

package/tsconfig.json

@@ -0,0 +1,28 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "jsx": "react-jsx",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "baseUrl": ".",
+    "paths": {
+      "@fluxbase/sdk": ["../sdk/dist/index.d.ts"]
+    }
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["./src/context.tsx","./src/index.ts","./src/use-admin-auth.ts","./src/use-admin-hooks.ts","./src/use-client-keys.ts","./src/use-auth.ts","./src/use-query.ts","./src/use-realtime.ts","./src/use-rpc.ts","./src/use-storage.ts","./src/use-users.ts"],"version":"5.9.3"}

package/tsup.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from 'tsup'
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'],
+  dts: true,
+  splitting: false,
+  sourcemap: true,
+  clean: true,
+  external: ['react', '@tanstack/react-query', '@fluxbase/sdk'],
+})

package/typedoc.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://typedoc.org/schema.json",
+  "entryPoints": ["src/index.ts"],
+  "out": "../docs/static/api/sdk-react",
+  "name": "@nimbleflux/fluxbase-sdk-react",
+  "readme": "README.md",
+  "plugin": [],
+  "excludePrivate": true,
+  "excludeProtected": false,
+  "excludeInternal": true,
+  "includeVersion": true,
+  "searchInComments": true,
+  "validation": {
+    "notExported": true,
+    "invalidLink": true,
+    "notDocumented": false
+  },
+  "categorizeByGroup": true,
+  "categoryOrder": [
+    "Context",
+    "Authentication Hooks",
+    "Database Hooks",
+    "Realtime Hooks",
+    "Storage Hooks",
+    "RPC Hooks",
+    "Types",
+    "*"
+  ],
+  "navigationLinks": {
+    "GitHub": "https://github.com/nimbleflux/fluxbase",
+    "Documentation": "https://fluxbase.eu"
+  }
+}

package/vitest.config.ts

@@ -0,0 +1,22 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'jsdom',
+    globals: true,
+    setupFiles: ['./src/test-setup.ts'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html', 'lcov'],
+      reportsDirectory: './coverage',
+      include: ['src/**/*.ts', 'src/**/*.tsx'],
+      exclude: ['src/**/*.test.ts', 'src/**/*.test.tsx', 'src/**/*.d.ts', 'src/test-setup.ts'],
+      thresholds: {
+        statements: 80,
+        branches: 80,
+        functions: 60,
+        lines: 80
+      }
+    }
+  }
+});