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

package/src/use-knowledge-base.ts

@@ -0,0 +1,296 @@
+/**
+ * Knowledge Base hooks for Fluxbase React SDK
+ * Provides hooks for RAG document management, semantic search, and knowledge graph
+ */
+
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useFluxbaseClient } from "./context";
+import type {
+  CreateKnowledgeBaseRequest,
+  UpdateKnowledgeBaseRequest,
+  AddDocumentRequest,
+  SearchKnowledgeBaseRequest,
+} from "@nimbleflux/fluxbase-sdk";
+
+/**
+ * Hook to list all knowledge bases the user has access to
+ */
+export function useKnowledgeBases() {
+  const client = useFluxbaseClient();
+
+  return useQuery({
+    queryKey: ["fluxbase", "knowledge-base", "list"],
+    queryFn: async () => {
+      const { data, error } = await client.knowledgeBase.list();
+      if (error) throw error;
+      return data || [];
+    },
+  });
+}
+
+/**
+ * Hook to get a single knowledge base by ID
+ */
+export function useKnowledgeBase(kbId: string | null) {
+  const client = useFluxbaseClient();
+
+  return useQuery({
+    queryKey: ["fluxbase", "knowledge-base", kbId],
+    queryFn: async () => {
+      if (!kbId) return null;
+      const { data, error } = await client.knowledgeBase.get(kbId);
+      if (error) throw error;
+      return data;
+    },
+    enabled: !!kbId,
+  });
+}
+
+/**
+ * Hook to create a new knowledge base
+ */
+export function useCreateKnowledgeBase() {
+  const client = useFluxbaseClient();
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async (request: CreateKnowledgeBaseRequest) => {
+      const { data, error } = await client.knowledgeBase.create(request);
+      if (error) throw error;
+      return data;
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({
+        queryKey: ["fluxbase", "knowledge-base", "list"],
+      });
+    },
+  });
+}
+
+/**
+ * Hook to update a knowledge base
+ */
+export function useUpdateKnowledgeBase() {
+  const client = useFluxbaseClient();
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async ({
+      kbId,
+      updates,
+    }: {
+      kbId: string;
+      updates: UpdateKnowledgeBaseRequest;
+    }) => {
+      const { data, error } = await client.knowledgeBase.update(kbId, updates);
+      if (error) throw error;
+      return data;
+    },
+    onSuccess: (_data, variables) => {
+      queryClient.invalidateQueries({
+        queryKey: ["fluxbase", "knowledge-base", "list"],
+      });
+      queryClient.invalidateQueries({
+        queryKey: ["fluxbase", "knowledge-base", variables.kbId],
+      });
+    },
+  });
+}
+
+/**
+ * Hook to delete a knowledge base
+ */
+export function useDeleteKnowledgeBase() {
+  const client = useFluxbaseClient();
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async (kbId: string) => {
+      const { error } = await client.knowledgeBase.delete(kbId);
+      if (error) throw error;
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({
+        queryKey: ["fluxbase", "knowledge-base", "list"],
+      });
+    },
+  });
+}
+
+/**
+ * Hook to list documents in a knowledge base
+ */
+export function useKBDocuments(kbId: string | null) {
+  const client = useFluxbaseClient();
+
+  return useQuery({
+    queryKey: ["fluxbase", "knowledge-base", kbId, "documents"],
+    queryFn: async () => {
+      if (!kbId) return [];
+      const { data, error } = await client.knowledgeBase.listDocuments(kbId);
+      if (error) throw error;
+      return data || [];
+    },
+    enabled: !!kbId,
+  });
+}
+
+/**
+ * Hook to add a document to a knowledge base
+ */
+export function useAddDocument() {
+  const client = useFluxbaseClient();
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async ({
+      kbId,
+      request,
+    }: {
+      kbId: string;
+      request: AddDocumentRequest;
+    }) => {
+      const { data, error } = await client.knowledgeBase.addDocument(
+        kbId,
+        request,
+      );
+      if (error) throw error;
+      return data;
+    },
+    onSuccess: (_data, variables) => {
+      queryClient.invalidateQueries({
+        queryKey: ["fluxbase", "knowledge-base", variables.kbId, "documents"],
+      });
+    },
+  });
+}
+
+/**
+ * Hook to upload a file document to a knowledge base
+ */
+export function useUploadDocument() {
+  const client = useFluxbaseClient();
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async ({
+      kbId,
+      file,
+      filename,
+      metadata,
+    }: {
+      kbId: string;
+      file: File | Blob | ArrayBuffer;
+      filename: string;
+      metadata?: Record<string, string>;
+    }) => {
+      const { data, error } = await client.knowledgeBase.uploadDocument(
+        kbId,
+        file,
+        filename,
+        metadata,
+      );
+      if (error) throw error;
+      return data;
+    },
+    onSuccess: (_data, variables) => {
+      queryClient.invalidateQueries({
+        queryKey: ["fluxbase", "knowledge-base", variables.kbId, "documents"],
+      });
+    },
+  });
+}
+
+/**
+ * Hook to delete a document
+ */
+export function useDeleteDocument() {
+  const client = useFluxbaseClient();
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async ({
+      kbId,
+      docId,
+    }: {
+      kbId: string;
+      docId: string;
+    }) => {
+      const { error } = await client.knowledgeBase.deleteDocument(kbId, docId);
+      if (error) throw error;
+    },
+    onSuccess: (_data, variables) => {
+      queryClient.invalidateQueries({
+        queryKey: ["fluxbase", "knowledge-base", variables.kbId, "documents"],
+      });
+    },
+  });
+}
+
+/**
+ * Hook to search a knowledge base with semantic similarity
+ *
+ * @example
+ * ```tsx
+ * const { data, isPending } = useKBSearch(kbId, {
+ *   query: 'How to configure auth?',
+ *   max_chunks: 5,
+ * })
+ * ```
+ */
+export function useKBSearch(
+  kbId: string | null,
+  request: SearchKnowledgeBaseRequest | null,
+) {
+  const client = useFluxbaseClient();
+
+  return useQuery({
+    queryKey: ["fluxbase", "knowledge-base", kbId, "search", request],
+    queryFn: async () => {
+      if (!kbId || !request) return null;
+      const { data, error } = await client.knowledgeBase.search(kbId, request);
+      if (error) throw error;
+      return data;
+    },
+    enabled: !!kbId && !!request,
+  });
+}
+
+/**
+ * Hook to list entities in a knowledge base
+ */
+export function useKBEntities(kbId: string | null, type?: string) {
+  const client = useFluxbaseClient();
+
+  return useQuery({
+    queryKey: ["fluxbase", "knowledge-base", kbId, "entities", type],
+    queryFn: async () => {
+      if (!kbId) return [];
+      const { data, error } = await client.knowledgeBase.listEntities(
+        kbId,
+        type as any,
+      );
+      if (error) throw error;
+      return data || [];
+    },
+    enabled: !!kbId,
+  });
+}
+
+/**
+ * Hook to get the knowledge graph (entities + relationships)
+ */
+export function useKnowledgeGraph(kbId: string | null) {
+  const client = useFluxbaseClient();
+
+  return useQuery({
+    queryKey: ["fluxbase", "knowledge-base", kbId, "graph"],
+    queryFn: async () => {
+      if (!kbId) return null;
+      const { data, error } = await client.knowledgeBase.getKnowledgeGraph(kbId);
+      if (error) throw error;
+      return data;
+    },
+    enabled: !!kbId,
+  });
+}

package/src/use-migrations.test.ts

@@ -0,0 +1,280 @@
+/**
+ * Tests for migration hooks
+ */
+
+import { describe, it, expect, vi } from "vitest";
+import { renderHook, waitFor, act } from "@testing-library/react";
+import {
+  useMigrations,
+  useApplyMigration,
+  useRollbackMigration,
+  useSyncMigrations,
+} from "./use-migrations";
+import { createMockClient, createWrapper } from "./test-utils";
+
+describe("useMigrations", () => {
+  it("should list migrations", async () => {
+    const mockMigrations = [
+      {
+        id: "1",
+        namespace: "default",
+        name: "001_init",
+        up_sql: "CREATE TABLE test();",
+        version: 1,
+        status: "applied" as const,
+        created_at: "",
+        updated_at: "",
+      },
+    ];
+    const client = createMockClient({
+      admin: {
+        migrations: {
+          list: vi.fn().mockResolvedValue({ data: mockMigrations, error: null }),
+        },
+      } as any,
+    });
+
+    const { result } = renderHook(() => useMigrations(), {
+      wrapper: createWrapper(client),
+    });
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(result.current.data).toEqual(mockMigrations);
+  });
+
+  it("should pass namespace to list", async () => {
+    const list = vi.fn().mockResolvedValue({ data: [], error: null });
+    const client = createMockClient({
+      admin: { migrations: { list } } as any,
+    });
+
+    renderHook(() => useMigrations("myapp"), {
+      wrapper: createWrapper(client),
+    });
+
+    await waitFor(() => {
+      expect(list).toHaveBeenCalledWith("myapp");
+    });
+  });
+
+  it("should handle errors", async () => {
+    const client = createMockClient({
+      admin: {
+        migrations: {
+          list: vi
+            .fn()
+            .mockResolvedValue({ data: null, error: new Error("Failed") }),
+        },
+      } as any,
+    });
+
+    const { result } = renderHook(() => useMigrations(), {
+      wrapper: createWrapper(client),
+    });
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(result.current.error).toBeInstanceOf(Error);
+  });
+});
+
+describe("useApplyMigration", () => {
+  it("should apply a migration", async () => {
+    const apply = vi
+      .fn()
+      .mockResolvedValue({ data: { message: "Applied" }, error: null });
+    const client = createMockClient({
+      admin: { migrations: { apply } } as any,
+    });
+
+    const { result } = renderHook(() => useApplyMigration(), {
+      wrapper: createWrapper(client),
+    });
+
+    await act(async () => {
+      await result.current.mutateAsync({ name: "001_init" });
+    });
+
+    expect(apply).toHaveBeenCalledWith("001_init", undefined);
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+  });
+
+  it("should pass namespace to apply", async () => {
+    const apply = vi
+      .fn()
+      .mockResolvedValue({ data: { message: "Applied" }, error: null });
+    const client = createMockClient({
+      admin: { migrations: { apply } } as any,
+    });
+
+    const { result } = renderHook(() => useApplyMigration(), {
+      wrapper: createWrapper(client),
+    });
+
+    await act(async () => {
+      await result.current.mutateAsync({ name: "001_init", namespace: "myapp" });
+    });
+
+    expect(apply).toHaveBeenCalledWith("001_init", "myapp");
+  });
+
+  it("should handle errors", async () => {
+    const client = createMockClient({
+      admin: {
+        migrations: {
+          apply: vi
+            .fn()
+            .mockResolvedValue({ data: null, error: new Error("Failed") }),
+        },
+      } as any,
+    });
+
+    const { result } = renderHook(() => useApplyMigration(), {
+      wrapper: createWrapper(client),
+    });
+
+    await act(async () => {
+      try {
+        await result.current.mutateAsync({ name: "001_init" });
+      } catch {
+        // expected
+      }
+    });
+
+    await waitFor(() => expect(result.current.isError).toBe(true));
+  });
+});
+
+describe("useRollbackMigration", () => {
+  it("should rollback a migration", async () => {
+    const rollback = vi
+      .fn()
+      .mockResolvedValue({ data: { message: "Rolled back" }, error: null });
+    const client = createMockClient({
+      admin: { migrations: { rollback } } as any,
+    });
+
+    const { result } = renderHook(() => useRollbackMigration(), {
+      wrapper: createWrapper(client),
+    });
+
+    await act(async () => {
+      await result.current.mutateAsync({ name: "001_init" });
+    });
+
+    expect(rollback).toHaveBeenCalledWith("001_init", undefined);
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+  });
+
+  it("should handle errors", async () => {
+    const client = createMockClient({
+      admin: {
+        migrations: {
+          rollback: vi
+            .fn()
+            .mockResolvedValue({ data: null, error: new Error("Failed") }),
+        },
+      } as any,
+    });
+
+    const { result } = renderHook(() => useRollbackMigration(), {
+      wrapper: createWrapper(client),
+    });
+
+    await act(async () => {
+      try {
+        await result.current.mutateAsync({ name: "001_init" });
+      } catch {
+        // expected
+      }
+    });
+
+    await waitFor(() => expect(result.current.isError).toBe(true));
+  });
+});
+
+describe("useSyncMigrations", () => {
+  it("should sync migrations", async () => {
+    const mockResult = {
+      message: "Synced",
+      namespace: "default",
+      summary: {
+        created: 1,
+        updated: 0,
+        unchanged: 0,
+        skipped: 0,
+        applied: 0,
+        errors: 0,
+      },
+      details: {
+        created: ["001_init"],
+        updated: [],
+        unchanged: [],
+        skipped: [],
+        applied: [],
+        errors: [],
+      },
+      dry_run: false,
+    };
+    const sync = vi.fn().mockResolvedValue({ data: mockResult, error: null });
+    const client = createMockClient({
+      admin: { migrations: { sync } } as any,
+    });
+
+    const { result } = renderHook(() => useSyncMigrations(), {
+      wrapper: createWrapper(client),
+    });
+
+    await act(async () => {
+      await result.current.mutateAsync();
+    });
+
+    expect(sync).toHaveBeenCalledWith(undefined);
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+    expect(result.current.data).toEqual(mockResult);
+  });
+
+  it("should pass options to sync", async () => {
+    const sync = vi
+      .fn()
+      .mockResolvedValue({ data: null, error: null });
+    const client = createMockClient({
+      admin: { migrations: { sync } } as any,
+    });
+
+    const { result } = renderHook(() => useSyncMigrations(), {
+      wrapper: createWrapper(client),
+    });
+
+    await act(async () => {
+      await result.current.mutateAsync({ auto_apply: true });
+    });
+
+    expect(sync).toHaveBeenCalledWith({ auto_apply: true });
+  });
+
+  it("should handle errors", async () => {
+    const client = createMockClient({
+      admin: {
+        migrations: {
+          sync: vi
+            .fn()
+            .mockResolvedValue({ data: null, error: new Error("Sync failed") }),
+        },
+      } as any,
+    });
+
+    const { result } = renderHook(() => useSyncMigrations(), {
+      wrapper: createWrapper(client),
+    });
+
+    await act(async () => {
+      try {
+        await result.current.mutateAsync();
+      } catch {
+        // expected
+      }
+    });
+
+    await waitFor(() => expect(result.current.isError).toBe(true));
+  });
+});

package/src/use-migrations.ts

@@ -0,0 +1,107 @@
+/**
+ * Migration hooks for Fluxbase React SDK
+ * Provides hooks for listing, applying, rolling back, and syncing database migrations
+ */
+
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import { useFluxbaseClient } from "./context";
+import type { SyncMigrationsOptions } from "@nimbleflux/fluxbase-sdk";
+
+/**
+ * Hook to list migrations in a namespace
+ */
+export function useMigrations(namespace?: string) {
+  const client = useFluxbaseClient();
+
+  return useQuery({
+    queryKey: ["fluxbase", "migrations", namespace],
+    queryFn: async () => {
+      const { data, error } = await client.admin.migrations.list(namespace);
+      if (error) throw error;
+      return data || [];
+    },
+  });
+}
+
+/**
+ * Hook to apply a specific migration
+ */
+export function useApplyMigration() {
+  const client = useFluxbaseClient();
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async ({
+      name,
+      namespace,
+    }: {
+      name: string;
+      namespace?: string;
+    }) => {
+      const { data, error } = await client.admin.migrations.apply(
+        name,
+        namespace,
+      );
+      if (error) throw error;
+      return data;
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({
+        queryKey: ["fluxbase", "migrations"],
+      });
+    },
+  });
+}
+
+/**
+ * Hook to rollback a specific migration
+ */
+export function useRollbackMigration() {
+  const client = useFluxbaseClient();
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async ({
+      name,
+      namespace,
+    }: {
+      name: string;
+      namespace?: string;
+    }) => {
+      const { data, error } = await client.admin.migrations.rollback(
+        name,
+        namespace,
+      );
+      if (error) throw error;
+      return data;
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({
+        queryKey: ["fluxbase", "migrations"],
+      });
+    },
+  });
+}
+
+/**
+ * Hook to sync registered migrations
+ */
+export function useSyncMigrations() {
+  const client = useFluxbaseClient();
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async (options: SyncMigrationsOptions | void) => {
+      const { data, error } = await client.admin.migrations.sync(
+        options ?? undefined,
+      );
+      if (error) throw error;
+      return data;
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({
+        queryKey: ["fluxbase", "migrations"],
+      });
+    },
+  });
+}