@nimbleflux/fluxbase-sdk-react 2026.5.4 → 2026.5.5-rc.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nimbleflux/fluxbase-sdk-react",
-  "version": "2026.5.4",
+  "version": "2026.5.5-rc.2",
   "description": "React hooks for Fluxbase SDK",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -39,7 +39,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@nimbleflux/fluxbase-sdk": "^2026.5.4",
+    "@nimbleflux/fluxbase-sdk": "^2026.5.5-rc.2",
     "@tanstack/react-query": "^5.96.2",
     "react": "^18.0.0 || ^19.0.0"
   },

package/src/index.ts

@@ -135,6 +135,15 @@ export {
   type UseTableDetailsReturn,
 } from "./use-table-export";
 
+// Function hooks
+export { useInvokeFunction } from "./use-functions";
+
+// Job hooks
+export { useSubmitJob, useJobStatus } from "./use-jobs";
+
+// Branching hooks
+export { useBranches } from "./use-branches";
+
 // Re-export types from SDK
 export type {
   FluxbaseClient,
@@ -144,6 +153,7 @@ export type {
   SignUpCredentials,
   PostgrestResponse,
   RealtimeChangePayload,
+  // @deprecated backward compat aliases
   StorageObject,
   AdminUser,
   EnrichedUser,

package/src/use-branches.ts

@@ -0,0 +1,21 @@
+import { useQuery } from "@tanstack/react-query"
+import { useFluxbaseClient } from "./context"
+
+export interface UseBranchesOptions {
+  status?: "creating" | "ready" | "migrating" | "error" | "deleting" | "deleted";
+  type?: "main" | "preview" | "persistent";
+  limit?: number;
+  offset?: number;
+}
+
+export function useBranches(options?: UseBranchesOptions) {
+  const client = useFluxbaseClient()
+  return useQuery({
+    queryKey: ["fluxbase", "branches", options],
+    queryFn: async (): Promise<unknown> => {
+      const { data, error } = await client.branching.list(options)
+      if (error) throw error
+      return data
+    },
+  })
+}

package/src/use-functions.ts

@@ -0,0 +1,13 @@
+import { useMutation } from "@tanstack/react-query"
+import { useFluxbaseClient } from "./context"
+
+export function useInvokeFunction() {
+  const client = useFluxbaseClient()
+  return useMutation({
+    mutationFn: async ({ name, payload, method }: { name: string; payload?: unknown; method?: "GET" | "POST" | "PUT" | "DELETE" | "PATCH" }) => {
+      const { data, error } = await client.functions.invoke(name, { body: payload, method })
+      if (error) throw error
+      return data
+    },
+  })
+}

package/src/use-jobs.ts

@@ -0,0 +1,33 @@
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query"
+import { useFluxbaseClient } from "./context"
+
+export function useSubmitJob() {
+  const client = useFluxbaseClient()
+  const queryClient = useQueryClient()
+  return useMutation({
+    mutationFn: async (params: { name: string; payload?: unknown }): Promise<unknown> => {
+      const { data, error } = await client.jobs.submit(params.name, params.payload)
+      if (error) throw error
+      return data
+    },
+    onSuccess: () => { queryClient.invalidateQueries({ queryKey: ["fluxbase", "jobs"] }) },
+  })
+}
+
+export function useJobStatus(jobId: string | null) {
+  const client = useFluxbaseClient()
+  return useQuery({
+    queryKey: ["fluxbase", "jobs", jobId],
+    queryFn: async (): Promise<unknown> => {
+      if (!jobId) return null
+      const { data, error } = await client.jobs.get(jobId)
+      if (error) throw error
+      return data
+    },
+    enabled: !!jobId,
+    refetchInterval: (query) => {
+      const status = (query.state.data as Record<string, unknown> | null)?.status as string | undefined
+      return status === "pending" || status === "running" ? 2000 : false
+    },
+  })
+}

package/src/use-query.ts

@@ -43,17 +43,22 @@ export function useFluxbaseQuery<T = any>(
   options?: UseFluxbaseQueryOptions<T>,
 ) {
   const client = useFluxbaseClient();
+  const tenantId = client.getTenantId();
+
+  const { queryKey: customKey, ...queryOptions } = options || {};
 
   // Require queryKey for stable caching - function.toString() is not reliable
   // as it can vary between renders for inline functions
-  if (!options?.queryKey) {
+  if (!customKey) {
     console.warn(
       "[useFluxbaseQuery] No queryKey provided. This may cause cache misses. " +
         "Please provide a stable queryKey in options.",
     );
   }
 
-  const queryKey = options?.queryKey || ["fluxbase", "query", "unstable"];
+  const queryKey = customKey
+    ? ["fluxbase", tenantId ?? null, ...customKey]
+    : ["fluxbase", tenantId ?? null, "query", "unstable"];
 
   return useQuery({
     queryKey,
@@ -67,7 +72,7 @@ export function useFluxbaseQuery<T = any>(
 
       return (Array.isArray(data) ? data : data ? [data] : []) as T[];
     },
-    ...options,
+    ...queryOptions,
   });
 }
 
@@ -113,8 +118,7 @@ export function useTable<T = any>(
     },
     {
       ...options,
-      // Use table name as base key, or custom key if provided
-      queryKey: options?.queryKey || ["fluxbase", "table", table],
+      queryKey: options?.queryKey || ["table", table],
     },
   );
 }
@@ -138,8 +142,10 @@ export function useInsert<T = any>(table: string) {
       return result;
     },
     onSuccess: () => {
-      // Invalidate all queries for this table
-      queryClient.invalidateQueries({ queryKey: ["fluxbase", "table", table] });
+      const tenantId = client.getTenantId();
+      queryClient.invalidateQueries({
+        queryKey: ["fluxbase", tenantId ?? null, "table", table],
+      });
     },
   });
 }
@@ -167,7 +173,10 @@ export function useUpdate<T = any>(table: string) {
       return result;
     },
     onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ["fluxbase", "table", table] });
+      const tenantId = client.getTenantId();
+      queryClient.invalidateQueries({
+        queryKey: ["fluxbase", tenantId ?? null, "table", table],
+      });
     },
   });
 }
@@ -191,7 +200,10 @@ export function useUpsert<T = any>(table: string) {
       return result;
     },
     onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ["fluxbase", "table", table] });
+      const tenantId = client.getTenantId();
+      queryClient.invalidateQueries({
+        queryKey: ["fluxbase", tenantId ?? null, "table", table],
+      });
     },
   });
 }
@@ -216,7 +228,10 @@ export function useDelete<T = any>(table: string) {
       }
     },
     onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ["fluxbase", "table", table] });
+      const tenantId = client.getTenantId();
+      queryClient.invalidateQueries({
+        queryKey: ["fluxbase", tenantId ?? null, "table", table],
+      });
     },
   });
 }

package/src/use-tenant.ts

@@ -4,7 +4,8 @@
  * @module use-tenant
  */
 
-import { useState, useEffect, useCallback } from "react";
+import { useState, useCallback } from "react";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
 import { useFluxbaseClient } from "./context";
 import type {
   Tenant,
@@ -98,58 +99,55 @@ export interface UseTenantsReturn {
 export function useTenants(options: UseTenantsOptions = {}): UseTenantsReturn {
   const { autoFetch = true } = options;
   const client = useFluxbaseClient();
+  const queryClient = useQueryClient();
 
-  const [tenants, setTenants] = useState<TenantWithRole[]>([]);
-  const [isLoading, setIsLoading] = useState(autoFetch);
-  const [error, setError] = useState<Error | null>(null);
   const [currentTenantId, setCurrentTenantId] = useState<string | undefined>(
     client.getTenantId(),
   );
 
-  const fetchTenants = useCallback(async () => {
-    try {
-      setIsLoading(true);
-      setError(null);
-      const { data, error: fetchError } = await client.tenant.listMine();
-      if (fetchError) {
-        setError(fetchError);
-      } else {
-        setTenants(data || []);
-      }
-    } catch (err) {
-      setError(err as Error);
-    } finally {
-      setIsLoading(false);
-    }
-  }, [client]);
+  const query = useQuery({
+    queryKey: ["fluxbase", "tenants", "mine"],
+    queryFn: async () => {
+      const { data, error } = await client.tenant.listMine();
+      if (error) throw error;
+      return data || ([] as TenantWithRole[]);
+    },
+    enabled: autoFetch,
+  });
 
   const createTenant = useCallback(
     async (opts: CreateTenantOptions): Promise<Tenant> => {
       const { data, error: createError } = await client.tenant.create(opts);
       if (createError) throw createError;
-      await fetchTenants();
+      await queryClient.invalidateQueries({
+        queryKey: ["fluxbase", "tenants"],
+      });
       return data!;
     },
-    [client, fetchTenants],
+    [client, queryClient],
   );
 
   const updateTenant = useCallback(
     async (id: string, opts: UpdateTenantOptions): Promise<Tenant> => {
       const { data, error: updateError } = await client.tenant.update(id, opts);
       if (updateError) throw updateError;
-      await fetchTenants();
+      await queryClient.invalidateQueries({
+        queryKey: ["fluxbase", "tenants"],
+      });
       return data!;
     },
-    [client, fetchTenants],
+    [client, queryClient],
   );
 
   const deleteTenant = useCallback(
     async (id: string): Promise<void> => {
       const { error: deleteError } = await client.tenant.delete(id);
       if (deleteError) throw deleteError;
-      await fetchTenants();
+      await queryClient.invalidateQueries({
+        queryKey: ["fluxbase", "tenants"],
+      });
     },
-    [client, fetchTenants],
+    [client, queryClient],
   );
 
   const setCurrentTenant = useCallback(
@@ -160,17 +158,13 @@ export function useTenants(options: UseTenantsOptions = {}): UseTenantsReturn {
     [client],
   );
 
-  useEffect(() => {
-    if (autoFetch) {
-      fetchTenants();
-    }
-  }, [autoFetch, fetchTenants]);
-
   return {
-    tenants,
-    isLoading,
-    error,
-    refetch: fetchTenants,
+    tenants: query.data ?? [],
+    isLoading: autoFetch ? query.isLoading : false,
+    error: query.error,
+    refetch: async () => {
+      await query.refetch();
+    },
     createTenant,
     updateTenant,
     deleteTenant,
@@ -249,31 +243,17 @@ export interface UseTenantReturn {
 export function useTenant(options: UseTenantOptions): UseTenantReturn {
   const { tenantId, autoFetch = true } = options;
   const client = useFluxbaseClient();
-
-  const [tenant, setTenant] = useState<Tenant | null>(null);
-  const [isLoading, setIsLoading] = useState(autoFetch);
-  const [error, setError] = useState<Error | null>(null);
-
-  const fetchTenant = useCallback(async () => {
-    if (!tenantId) return;
-
-    try {
-      setIsLoading(true);
-      setError(null);
-      const { data, error: fetchError } = await client.tenant.get(tenantId);
-      if (fetchError) {
-        setError(fetchError);
-        setTenant(null);
-      } else {
-        setTenant(data);
-      }
-    } catch (err) {
-      setError(err as Error);
-      setTenant(null);
-    } finally {
-      setIsLoading(false);
-    }
-  }, [client, tenantId]);
+  const queryClient = useQueryClient();
+
+  const query = useQuery({
+    queryKey: ["fluxbase", "tenant", tenantId],
+    queryFn: async () => {
+      const { data, error } = await client.tenant.get(tenantId);
+      if (error) throw error;
+      return data;
+    },
+    enabled: autoFetch && !!tenantId,
+  });
 
   const update = useCallback(
     async (opts: UpdateTenantOptions): Promise<Tenant> => {
@@ -282,29 +262,29 @@ export function useTenant(options: UseTenantOptions): UseTenantReturn {
         opts,
       );
       if (updateError) throw updateError;
-      setTenant(data);
+      await queryClient.invalidateQueries({
+        queryKey: ["fluxbase", "tenant", tenantId],
+      });
       return data!;
     },
-    [client, tenantId],
+    [client, tenantId, queryClient],
   );
 
   const remove = useCallback(async (): Promise<void> => {
     const { error: deleteError } = await client.tenant.delete(tenantId);
     if (deleteError) throw deleteError;
-    setTenant(null);
-  }, [client, tenantId]);
-
-  useEffect(() => {
-    if (autoFetch && tenantId) {
-      fetchTenant();
-    }
-  }, [autoFetch, fetchTenant, tenantId]);
+    await queryClient.invalidateQueries({
+      queryKey: ["fluxbase", "tenant", tenantId],
+    });
+  }, [client, tenantId, queryClient]);
 
   return {
-    tenant,
-    isLoading,
-    error,
-    refetch: fetchTenant,
+    tenant: query.data ?? null,
+    isLoading: autoFetch ? query.isLoading : false,
+    error: query.error,
+    refetch: async () => {
+      await query.refetch();
+    },
     update,
     remove,
   };