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

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@nimbleflux/fluxbase-sdk-react",
+  "version": "2026.3.6-rc.1",
+  "description": "React hooks for Fluxbase SDK",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "docs": "typedoc",
+    "docs:watch": "typedoc --watch",
+    "type-check": "tsc --noEmit",
+    "format": "prettier --write src",
+    "format:check": "prettier --check src",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "keywords": [
+    "fluxbase",
+    "react",
+    "hooks",
+    "database",
+    "realtime"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nimbleflux/fluxbase"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@nimbleflux/fluxbase-sdk": "^2026.3.5",
+    "@tanstack/react-query": "^5.90.21",
+    "react": "^18.0.0 || ^19.0.0",
+    "@fluxbase/sdk": "^2026.3.6-rc.1"
+  },
+  "devDependencies": {
+    "@nimbleflux/fluxbase-sdk": "workspace:*",
+    "@tanstack/react-query": "^5.90.21",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "^19.2.14",
+    "@vitest/coverage-v8": "^4.0.18",
+    "jsdom": "^28.1.0",
+    "prettier": "^3.8.1",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "tsup": "^8.5.1",
+    "typedoc": "^0.28.17",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "engines": {
+    "node": ">=24.14.0"
+  }
+}

package/src/context.test.tsx

@@ -0,0 +1,147 @@
+/**
+ * Tests for FluxbaseProvider and useFluxbaseClient
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen, renderHook } from '@testing-library/react';
+import React from 'react';
+import { FluxbaseProvider, useFluxbaseClient } from './context';
+import { createMockClient } from './test-utils';
+import type { FluxbaseClient } from '@nimbleflux/fluxbase-sdk';
+
+describe('FluxbaseProvider', () => {
+  it('should render children', () => {
+    const client = createMockClient();
+    render(
+      <FluxbaseProvider client={client}>
+        <div data-testid="child">Hello</div>
+      </FluxbaseProvider>
+    );
+
+    expect(screen.getByTestId('child')).toHaveTextContent('Hello');
+  });
+
+  it('should provide client to children', () => {
+    const client = createMockClient();
+    let receivedClient: FluxbaseClient | null = null;
+
+    function TestComponent() {
+      receivedClient = useFluxbaseClient();
+      return null;
+    }
+
+    render(
+      <FluxbaseProvider client={client}>
+        <TestComponent />
+      </FluxbaseProvider>
+    );
+
+    expect(receivedClient).toBe(client);
+  });
+
+  it('should support nested children', () => {
+    const client = createMockClient();
+    render(
+      <FluxbaseProvider client={client}>
+        <div>
+          <span>
+            <p data-testid="nested">Nested content</p>
+          </span>
+        </div>
+      </FluxbaseProvider>
+    );
+
+    expect(screen.getByTestId('nested')).toHaveTextContent('Nested content');
+  });
+});
+
+describe('useFluxbaseClient', () => {
+  it('should return the client from context', () => {
+    const client = createMockClient();
+
+    const { result } = renderHook(() => useFluxbaseClient(), {
+      wrapper: ({ children }) => (
+        <FluxbaseProvider client={client}>{children}</FluxbaseProvider>
+      ),
+    });
+
+    expect(result.current).toBe(client);
+  });
+
+  it('should throw error when used outside provider', () => {
+    // Suppress console.error for this test
+    const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+    expect(() => {
+      renderHook(() => useFluxbaseClient());
+    }).toThrow('useFluxbaseClient must be used within a FluxbaseProvider');
+
+    consoleSpy.mockRestore();
+  });
+
+  it('should provide access to auth methods', () => {
+    const client = createMockClient();
+
+    const { result } = renderHook(() => useFluxbaseClient(), {
+      wrapper: ({ children }) => (
+        <FluxbaseProvider client={client}>{children}</FluxbaseProvider>
+      ),
+    });
+
+    expect(result.current.auth).toBeDefined();
+    expect(result.current.auth.getSession).toBeDefined();
+    expect(result.current.auth.signIn).toBeDefined();
+  });
+
+  it('should provide access to storage methods', () => {
+    const client = createMockClient();
+
+    const { result } = renderHook(() => useFluxbaseClient(), {
+      wrapper: ({ children }) => (
+        <FluxbaseProvider client={client}>{children}</FluxbaseProvider>
+      ),
+    });
+
+    expect(result.current.storage).toBeDefined();
+    expect(result.current.storage.from).toBeDefined();
+  });
+
+  it('should provide access to realtime methods', () => {
+    const client = createMockClient();
+
+    const { result } = renderHook(() => useFluxbaseClient(), {
+      wrapper: ({ children }) => (
+        <FluxbaseProvider client={client}>{children}</FluxbaseProvider>
+      ),
+    });
+
+    expect(result.current.realtime).toBeDefined();
+    expect(result.current.realtime.channel).toBeDefined();
+  });
+
+  it('should provide access to graphql methods', () => {
+    const client = createMockClient();
+
+    const { result } = renderHook(() => useFluxbaseClient(), {
+      wrapper: ({ children }) => (
+        <FluxbaseProvider client={client}>{children}</FluxbaseProvider>
+      ),
+    });
+
+    expect(result.current.graphql).toBeDefined();
+    expect(result.current.graphql.execute).toBeDefined();
+  });
+
+  it('should provide access to admin methods', () => {
+    const client = createMockClient();
+
+    const { result } = renderHook(() => useFluxbaseClient(), {
+      wrapper: ({ children }) => (
+        <FluxbaseProvider client={client}>{children}</FluxbaseProvider>
+      ),
+    });
+
+    expect(result.current.admin).toBeDefined();
+    expect(result.current.admin.me).toBeDefined();
+  });
+});

package/src/context.tsx

@@ -0,0 +1,33 @@
+/**
+ * React context for Fluxbase client
+ */
+
+import { createContext, useContext, type ReactNode } from 'react'
+import type { FluxbaseClient } from '@nimbleflux/fluxbase-sdk'
+
+const FluxbaseContext = createContext<FluxbaseClient | null>(null)
+
+export interface FluxbaseProviderProps {
+  client: FluxbaseClient
+  children: ReactNode
+}
+
+/**
+ * Provider component to make Fluxbase client available throughout the app
+ */
+export function FluxbaseProvider({ client, children }: FluxbaseProviderProps) {
+  return <FluxbaseContext.Provider value={client}>{children}</FluxbaseContext.Provider>
+}
+
+/**
+ * Hook to access the Fluxbase client from context
+ */
+export function useFluxbaseClient(): FluxbaseClient {
+  const client = useContext(FluxbaseContext)
+
+  if (!client) {
+    throw new Error('useFluxbaseClient must be used within a FluxbaseProvider')
+  }
+
+  return client
+}

package/src/index.test.ts

@@ -0,0 +1,255 @@
+/**
+ * Tests for module exports
+ */
+
+import { describe, it, expect } from 'vitest';
+import * as exports from './index';
+
+describe('Module Exports', () => {
+  describe('Context exports', () => {
+    it('should export FluxbaseProvider', () => {
+      expect(exports.FluxbaseProvider).toBeDefined();
+    });
+
+    it('should export useFluxbaseClient', () => {
+      expect(exports.useFluxbaseClient).toBeDefined();
+    });
+  });
+
+  describe('Auth hook exports', () => {
+    it('should export useAuth', () => {
+      expect(exports.useAuth).toBeDefined();
+    });
+
+    it('should export useUser', () => {
+      expect(exports.useUser).toBeDefined();
+    });
+
+    it('should export useSession', () => {
+      expect(exports.useSession).toBeDefined();
+    });
+
+    it('should export useSignIn', () => {
+      expect(exports.useSignIn).toBeDefined();
+    });
+
+    it('should export useSignUp', () => {
+      expect(exports.useSignUp).toBeDefined();
+    });
+
+    it('should export useSignOut', () => {
+      expect(exports.useSignOut).toBeDefined();
+    });
+
+    it('should export useUpdateUser', () => {
+      expect(exports.useUpdateUser).toBeDefined();
+    });
+  });
+
+  describe('CAPTCHA hook exports', () => {
+    it('should export useCaptchaConfig', () => {
+      expect(exports.useCaptchaConfig).toBeDefined();
+    });
+
+    it('should export useCaptcha', () => {
+      expect(exports.useCaptcha).toBeDefined();
+    });
+
+    it('should export isCaptchaRequiredForEndpoint', () => {
+      expect(exports.isCaptchaRequiredForEndpoint).toBeDefined();
+    });
+  });
+
+  describe('Auth config exports', () => {
+    it('should export useAuthConfig', () => {
+      expect(exports.useAuthConfig).toBeDefined();
+    });
+  });
+
+  describe('SAML hook exports', () => {
+    it('should export useSAMLProviders', () => {
+      expect(exports.useSAMLProviders).toBeDefined();
+    });
+
+    it('should export useGetSAMLLoginUrl', () => {
+      expect(exports.useGetSAMLLoginUrl).toBeDefined();
+    });
+
+    it('should export useSignInWithSAML', () => {
+      expect(exports.useSignInWithSAML).toBeDefined();
+    });
+
+    it('should export useHandleSAMLCallback', () => {
+      expect(exports.useHandleSAMLCallback).toBeDefined();
+    });
+
+    it('should export useSAMLMetadataUrl', () => {
+      expect(exports.useSAMLMetadataUrl).toBeDefined();
+    });
+  });
+
+  describe('GraphQL hook exports', () => {
+    it('should export useGraphQLQuery', () => {
+      expect(exports.useGraphQLQuery).toBeDefined();
+    });
+
+    it('should export useGraphQLMutation', () => {
+      expect(exports.useGraphQLMutation).toBeDefined();
+    });
+
+    it('should export useGraphQLIntrospection', () => {
+      expect(exports.useGraphQLIntrospection).toBeDefined();
+    });
+
+    it('should export useGraphQL', () => {
+      expect(exports.useGraphQL).toBeDefined();
+    });
+  });
+
+  describe('Database query hook exports', () => {
+    it('should export useFluxbaseQuery', () => {
+      expect(exports.useFluxbaseQuery).toBeDefined();
+    });
+
+    it('should export useTable', () => {
+      expect(exports.useTable).toBeDefined();
+    });
+
+    it('should export useInsert', () => {
+      expect(exports.useInsert).toBeDefined();
+    });
+
+    it('should export useUpdate', () => {
+      expect(exports.useUpdate).toBeDefined();
+    });
+
+    it('should export useUpsert', () => {
+      expect(exports.useUpsert).toBeDefined();
+    });
+
+    it('should export useDelete', () => {
+      expect(exports.useDelete).toBeDefined();
+    });
+  });
+
+  describe('Realtime hook exports', () => {
+    it('should export useRealtime', () => {
+      expect(exports.useRealtime).toBeDefined();
+    });
+
+    it('should export useTableSubscription', () => {
+      expect(exports.useTableSubscription).toBeDefined();
+    });
+
+    it('should export useTableInserts', () => {
+      expect(exports.useTableInserts).toBeDefined();
+    });
+
+    it('should export useTableUpdates', () => {
+      expect(exports.useTableUpdates).toBeDefined();
+    });
+
+    it('should export useTableDeletes', () => {
+      expect(exports.useTableDeletes).toBeDefined();
+    });
+  });
+
+  describe('Storage hook exports', () => {
+    it('should export useStorageList', () => {
+      expect(exports.useStorageList).toBeDefined();
+    });
+
+    it('should export useStorageUpload', () => {
+      expect(exports.useStorageUpload).toBeDefined();
+    });
+
+    it('should export useStorageUploadWithProgress', () => {
+      expect(exports.useStorageUploadWithProgress).toBeDefined();
+    });
+
+    it('should export useStorageDownload', () => {
+      expect(exports.useStorageDownload).toBeDefined();
+    });
+
+    it('should export useStorageDelete', () => {
+      expect(exports.useStorageDelete).toBeDefined();
+    });
+
+    it('should export useStoragePublicUrl', () => {
+      expect(exports.useStoragePublicUrl).toBeDefined();
+    });
+
+    it('should export useStorageTransformUrl', () => {
+      expect(exports.useStorageTransformUrl).toBeDefined();
+    });
+
+    it('should export useStorageSignedUrl', () => {
+      expect(exports.useStorageSignedUrl).toBeDefined();
+    });
+
+    it('should export useStorageSignedUrlWithOptions', () => {
+      expect(exports.useStorageSignedUrlWithOptions).toBeDefined();
+    });
+
+    it('should export useStorageMove', () => {
+      expect(exports.useStorageMove).toBeDefined();
+    });
+
+    it('should export useStorageCopy', () => {
+      expect(exports.useStorageCopy).toBeDefined();
+    });
+
+    it('should export useStorageBuckets', () => {
+      expect(exports.useStorageBuckets).toBeDefined();
+    });
+
+    it('should export useCreateBucket', () => {
+      expect(exports.useCreateBucket).toBeDefined();
+    });
+
+    it('should export useDeleteBucket', () => {
+      expect(exports.useDeleteBucket).toBeDefined();
+    });
+  });
+
+  describe('Admin hook exports', () => {
+    it('should export useAdminAuth', () => {
+      expect(exports.useAdminAuth).toBeDefined();
+    });
+
+    it('should export useUsers', () => {
+      expect(exports.useUsers).toBeDefined();
+    });
+
+    it('should export useClientKeys', () => {
+      expect(exports.useClientKeys).toBeDefined();
+    });
+
+    it('should export useAPIKeys (deprecated alias)', () => {
+      expect(exports.useAPIKeys).toBeDefined();
+      expect(exports.useAPIKeys).toBe(exports.useClientKeys);
+    });
+
+    it('should export useWebhooks', () => {
+      expect(exports.useWebhooks).toBeDefined();
+    });
+
+    it('should export useAppSettings', () => {
+      expect(exports.useAppSettings).toBeDefined();
+    });
+
+    it('should export useSystemSettings', () => {
+      expect(exports.useSystemSettings).toBeDefined();
+    });
+  });
+
+  describe('Total export count', () => {
+    it('should export the expected number of items', () => {
+      // Count the exports (functions and types are counted)
+      const exportKeys = Object.keys(exports);
+
+      // We expect at least 50 exports (hooks, types, etc.)
+      expect(exportKeys.length).toBeGreaterThanOrEqual(50);
+    });
+  });
+});

package/src/index.ts

@@ -0,0 +1,175 @@
+/**
+ * Fluxbase React Hooks
+ *
+ * @example
+ * ```tsx
+ * import { createClient } from '@nimbleflux/fluxbase-sdk'
+ * import { FluxbaseProvider, useAuth, useTable } from '@nimbleflux/fluxbase-sdk-react'
+ * import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+ *
+ * const client = createClient({ url: 'http://localhost:8080' })
+ * const queryClient = new QueryClient()
+ *
+ * function App() {
+ *   return (
+ *     <QueryClientProvider client={queryClient}>
+ *       <FluxbaseProvider client={client}>
+ *         <MyComponent />
+ *       </FluxbaseProvider>
+ *     </QueryClientProvider>
+ *   )
+ * }
+ *
+ * function MyComponent() {
+ *   const { user, signIn, signOut } = useAuth()
+ *   const { data: products } = useTable('products', (q) => q.select('*').eq('active', true))
+ *
+ *   return <div>...</div>
+ * }
+ * ```
+ */
+
+// Context and provider
+export { FluxbaseProvider, useFluxbaseClient } from "./context";
+
+// Auth hooks
+export {
+  useAuth,
+  useUser,
+  useSession,
+  useSignIn,
+  useSignUp,
+  useSignOut,
+  useUpdateUser,
+} from "./use-auth";
+
+// CAPTCHA hooks
+export {
+  useCaptchaConfig,
+  useCaptcha,
+  isCaptchaRequiredForEndpoint,
+  type CaptchaState,
+} from "./use-captcha";
+
+// Auth configuration hooks
+export { useAuthConfig } from "./use-auth-config";
+
+// SAML SSO hooks
+export {
+  useSAMLProviders,
+  useGetSAMLLoginUrl,
+  useSignInWithSAML,
+  useHandleSAMLCallback,
+  useSAMLMetadataUrl,
+} from "./use-saml";
+
+// GraphQL hooks
+export {
+  useGraphQLQuery,
+  useGraphQLMutation,
+  useGraphQLIntrospection,
+  useGraphQL,
+  type UseGraphQLQueryOptions,
+  type UseGraphQLMutationOptions,
+} from "./use-graphql";
+
+// Database query hooks
+export {
+  useFluxbaseQuery,
+  useTable,
+  useInsert,
+  useUpdate,
+  useUpsert,
+  useDelete,
+} from "./use-query";
+
+// Realtime hooks
+export {
+  useRealtime,
+  useTableSubscription,
+  useTableInserts,
+  useTableUpdates,
+  useTableDeletes,
+} from "./use-realtime";
+
+// Storage hooks
+export {
+  useStorageList,
+  useStorageUpload,
+  useStorageUploadWithProgress,
+  useStorageDownload,
+  useStorageDelete,
+  useStoragePublicUrl,
+  useStorageTransformUrl,
+  useStorageSignedUrl,
+  useStorageSignedUrlWithOptions,
+  useStorageMove,
+  useStorageCopy,
+  useStorageBuckets,
+  useCreateBucket,
+  useDeleteBucket,
+} from "./use-storage";
+
+// Admin hooks
+export { useAdminAuth } from "./use-admin-auth";
+export { useUsers } from "./use-users";
+export { useClientKeys, useAPIKeys } from "./use-client-keys";
+export {
+  useWebhooks,
+  useAppSettings,
+  useSystemSettings,
+} from "./use-admin-hooks";
+
+// Table export hooks
+export {
+  useTableDetails,
+  useExportTable,
+  useTableExportSyncs,
+  useCreateTableExportSync,
+  useUpdateTableExportSync,
+  useDeleteTableExportSync,
+  useTriggerTableExportSync,
+  type UseTableDetailsOptions,
+  type UseTableDetailsReturn,
+  type UseExportTableReturn,
+  type UseTableExportSyncsOptions,
+  type UseTableExportSyncsReturn,
+  type UseCreateTableExportSyncReturn,
+  type UseUpdateTableExportSyncReturn,
+  type UseDeleteTableExportSyncReturn,
+  type UseTriggerTableExportSyncReturn,
+} from "./use-table-export";
+
+// Re-export types from SDK
+export type {
+  FluxbaseClient,
+  AuthSession,
+  User,
+  SignInCredentials,
+  SignUpCredentials,
+  PostgrestResponse,
+  RealtimeChangePayload,
+  StorageObject,
+  AdminUser,
+  EnrichedUser,
+  ClientKey,
+  APIKey, // Deprecated alias
+  Webhook,
+  AppSettings,
+  SystemSetting,
+  CaptchaConfig,
+  CaptchaProvider,
+  TransformOptions,
+  ImageFitMode,
+  ImageFormat,
+  SignedUrlOptions,
+  SAMLProvider,
+  SAMLProvidersResponse,
+  SAMLLoginOptions,
+  SAMLLoginResponse,
+  SAMLSession,
+  GraphQLResponse,
+  GraphQLError,
+  GraphQLErrorLocation,
+  GraphQLRequestOptions,
+} from "@nimbleflux/fluxbase-sdk";

package/src/test-setup.ts

@@ -0,0 +1,22 @@
+/**
+ * Test setup file for Fluxbase React SDK
+ */
+
+import { vi } from 'vitest';
+import '@testing-library/react';
+import '@testing-library/jest-dom/vitest';
+
+// Mock window.location for tests that need it
+Object.defineProperty(window, 'location', {
+  value: {
+    href: 'http://localhost:3000',
+    origin: 'http://localhost:3000',
+    pathname: '/',
+    search: '',
+    hash: '',
+    assign: vi.fn(),
+    replace: vi.fn(),
+    reload: vi.fn(),
+  },
+  writable: true,
+});