@stigmer/react 3.2.3 → 3.3.0

package/src/datastore/useDeleteDatastore.ts

@@ -0,0 +1,87 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import type { Datastore } from "@stigmer/protos/ai/stigmer/agentic/datastore/v1/api_pb";
+import { useStigmer } from "../hooks.js";
+import { toError } from "../internal/toError.js";
+
+/** Arguments for {@link UseDeleteDatastoreReturn.deleteDatastore}. */
+export interface DeleteDatastoreArgs {
+  /** Datastore resource id (`dst_…`). */
+  readonly resourceId: string;
+  /**
+   * Acknowledgment that the datastore's records will be destroyed.
+   * Required for non-empty datastores (the server's GuardNonEmpty
+   * rejects without it, reporting record and collection counts);
+   * meaningless for empty ones. `DeleteDatastoreDialog` arms it only
+   * after the operator types the datastore slug.
+   */
+  readonly force?: boolean;
+}
+
+/** Return value of {@link useDeleteDatastore}. */
+export interface UseDeleteDatastoreReturn {
+  /**
+   * Delete a datastore through its two server guards (DD-003), in
+   * order:
+   *
+   * 1. **Agent-reference block** — a datastore referenced by any
+   *    agent's `datastore_usages` cannot be deleted, force or not; the
+   *    `FAILED_PRECONDITION` names the referencing agents (detach
+   *    first).
+   * 2. **Non-empty acknowledgment** — held records require `force`;
+   *    without it the error reports current record/collection counts.
+   *
+   * Rejects — and sets `error` — when a guard refuses; the message is
+   * the server's authoritative text with fresh counts, so on drift the
+   * dialog re-renders the guard rather than pre-empting it (DD-008
+   * invariant 6).
+   */
+  readonly deleteDatastore: (args: DeleteDatastoreArgs) => Promise<Datastore>;
+  /** `true` while the delete is in flight. */
+  readonly isDeleting: boolean;
+  /** Error from the last refused or failed delete, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Reset `error` to `null`. */
+  readonly clearError: () => void;
+}
+
+/**
+ * Behavior hook for the platform's only record-destroying resource
+ * delete.
+ *
+ * Deliberately domain-local rather than a new arm in the generic
+ * `useDeleteResource` kind-switch: datastore deletion carries an
+ * acknowledgment protocol (`force`) and guard-error rendering that the
+ * generic one-shot delete contract must not absorb (DD-003 — extending
+ * it would leak record-destruction semantics platform-wide). No
+ * success/failure toasts here; `DeleteDatastoreDialog` owns the UX.
+ */
+export function useDeleteDatastore(): UseDeleteDatastoreReturn {
+  const stigmer = useStigmer();
+  const [isDeleting, setIsDeleting] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const deleteDatastore = useCallback(
+    async (args: DeleteDatastoreArgs): Promise<Datastore> => {
+      setIsDeleting(true);
+      setError(null);
+      try {
+        return await stigmer.datastore.delete({
+          resourceId: args.resourceId,
+          force: args.force,
+        });
+      } catch (err) {
+        setError(toError(err));
+        throw err;
+      } finally {
+        setIsDeleting(false);
+      }
+    },
+    [stigmer],
+  );
+
+  return { deleteDatastore, isDeleting, error, clearError };
+}

package/src/datastore/useDeleteRecord.ts

@@ -0,0 +1,77 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import { create } from "@bufbuild/protobuf";
+import {
+  DeleteRecordRequestSchema,
+  type RecordEnvelope,
+} from "@stigmer/protos/ai/stigmer/agentic/datastore/v1/record_io_pb";
+import { useStigmer } from "../hooks.js";
+import { toError } from "../internal/toError.js";
+import type { RecordScope } from "./useRecordList.js";
+
+/** Arguments for a single record delete. */
+export interface DeleteRecordArgs extends RecordScope {
+  /** Record id (`dsr_…`). */
+  readonly id: string;
+}
+
+/** Return value of {@link useDeleteRecord}. */
+export interface UseDeleteRecordReturn {
+  /**
+   * Delete one record by id. Resolves with the deleted record's final
+   * envelope (usable for an undo-by-reinsert growth path). Rejects —
+   * and sets `error` — on denial; the error's message is the server's
+   * relayable text, byte-for-byte.
+   */
+  readonly deleteRecord: (args: DeleteRecordArgs) => Promise<RecordEnvelope>;
+  /** `true` while the delete is in flight. */
+  readonly isDeleting: boolean;
+  /** Error from the last failed delete, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Reset `error` to `null`. */
+  readonly clearError: () => void;
+}
+
+/**
+ * Behavior hook that wraps `datastore.deleteRecord()` with loading and
+ * error state.
+ *
+ * Record deletes are id-addressed with a blast radius of one — the
+ * standard destructive confirm suffices (DD-008 SD-4). Deleting the
+ * datastore itself is a different, guarded operation: see
+ * {@link useDeleteDatastore}.
+ */
+export function useDeleteRecord(): UseDeleteRecordReturn {
+  const stigmer = useStigmer();
+  const [isDeleting, setIsDeleting] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const deleteRecord = useCallback(
+    async (args: DeleteRecordArgs): Promise<RecordEnvelope> => {
+      setIsDeleting(true);
+      setError(null);
+      try {
+        return await stigmer.datastore.deleteRecord(
+          create(DeleteRecordRequestSchema, {
+            org: args.org,
+            datastore: args.datastore,
+            collection: args.collection,
+            partition: args.partition ?? "",
+            id: args.id,
+          }),
+        );
+      } catch (err) {
+        setError(toError(err));
+        throw err;
+      } finally {
+        setIsDeleting(false);
+      }
+    },
+    [stigmer],
+  );
+
+  return { deleteRecord, isDeleting, error, clearError };
+}

package/src/datastore/useInsertRecord.ts

@@ -0,0 +1,92 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import { create, type JsonObject } from "@bufbuild/protobuf";
+import {
+  InsertRecordRequestSchema,
+  type RecordEnvelope,
+} from "@stigmer/protos/ai/stigmer/agentic/datastore/v1/record_io_pb";
+import { useStigmer } from "../hooks.js";
+import { toError } from "../internal/toError.js";
+import type { RecordScope } from "./useRecordList.js";
+
+/** Arguments for a single record insert. */
+export interface InsertRecordArgs extends RecordScope {
+  /**
+   * Declared field values in their canonical encodings (DD-004). System
+   * field names (`id`, `created_at`, …) are rejected by the server.
+   */
+  readonly record: JsonObject;
+}
+
+/** Return value of {@link useInsertRecord}. */
+export interface UseInsertRecordReturn {
+  /**
+   * Insert one record. Resolves with the server-stamped envelope (id,
+   * timestamps, attribution). Rejects — and sets `error` — on denial or
+   * constraint violation; the error's message is the server's relayable
+   * text, byte-for-byte (render it verbatim, DD-008 invariant 4).
+   */
+  readonly insertRecord: (args: InsertRecordArgs) => Promise<RecordEnvelope>;
+  /** `true` while the insert is in flight. */
+  readonly isInserting: boolean;
+  /** Error from the last failed insert, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Reset `error` to `null`. */
+  readonly clearError: () => void;
+}
+
+/**
+ * Behavior hook that wraps `datastore.insertRecord()` with loading and
+ * error state.
+ *
+ * Constraint violations (`ALREADY_EXISTS` for uniques,
+ * `FAILED_PRECONDITION` for checks) carry the constraint's declared
+ * message plus a `google.rpc.ErrorInfo` naming the constraint — use
+ * `getRecordConstraint` from `@stigmer/sdk` to place the message next
+ * to the fields it covers.
+ *
+ * @example
+ * ```tsx
+ * const { insertRecord, isInserting, error } = useInsertRecord();
+ * await insertRecord({
+ *   org: "acme",
+ *   datastore: "clinic",
+ *   collection: "bookings",
+ *   record: { slot_date: "2026-07-22", slot_time: "09:30:00" },
+ * });
+ * ```
+ */
+export function useInsertRecord(): UseInsertRecordReturn {
+  const stigmer = useStigmer();
+  const [isInserting, setIsInserting] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const insertRecord = useCallback(
+    async (args: InsertRecordArgs): Promise<RecordEnvelope> => {
+      setIsInserting(true);
+      setError(null);
+      try {
+        return await stigmer.datastore.insertRecord(
+          create(InsertRecordRequestSchema, {
+            org: args.org,
+            datastore: args.datastore,
+            collection: args.collection,
+            partition: args.partition ?? "",
+            record: args.record,
+          }),
+        );
+      } catch (err) {
+        setError(toError(err));
+        throw err;
+      } finally {
+        setIsInserting(false);
+      }
+    },
+    [stigmer],
+  );
+
+  return { insertRecord, isInserting, error, clearError };
+}

package/src/datastore/useRecordCollection.ts

@@ -0,0 +1,256 @@
+"use client";
+
+import { useCallback, useMemo, useRef } from "react";
+import {
+  getCoreRowModel,
+  useReactTable,
+  type ColumnDef,
+  type SortingState,
+  type Table,
+} from "@tanstack/react-table";
+import { create, toJsonString } from "@bufbuild/protobuf";
+import {
+  FindRecordsRequestSchema,
+  RecordFilterSchema,
+  RecordOrderBySchema,
+  RecordSortDirection,
+  type RecordEnvelope,
+  type RecordFilter,
+} from "@stigmer/protos/ai/stigmer/agentic/datastore/v1/record_io_pb";
+import { useStigmer } from "../hooks.js";
+import { useFetch } from "../internal/useFetch.js";
+import type { SortDirection, SortValue, WorkbenchColumnDef } from "../resource-workbench/types.js";
+
+/** Column definition for the records grid — a row is a {@link RecordEnvelope}. */
+export type RecordColumnDef = WorkbenchColumnDef<RecordEnvelope>;
+
+/** Options for {@link useRecordCollection}. */
+export interface UseRecordCollectionOptions {
+  /** Organization slug. Pass `null` to disable fetching. */
+  readonly org: string | null;
+  /** Datastore slug. Pass `null` to disable fetching. */
+  readonly datastore: string | null;
+  /** Collection name. Pass `null` to disable fetching. */
+  readonly collection: string | null;
+  /** Data partition. Empty or omitted means `"default"` (DD-010). */
+  readonly partition?: string;
+  /**
+   * Typed AND-only filter in the proto shape (DD-005 grammar). The hook
+   * adds no grammar — anything expressible here is exactly what
+   * `findRecords` serves (DD-008 invariant 1).
+   */
+  readonly filter?: RecordFilter;
+  /** Current page number (1-indexed). @default 1 */
+  readonly page?: number;
+  /**
+   * Page size, 1–100 (the RPC max — one surface, one limit).
+   * @default 25 (the RPC default)
+   */
+  readonly pageSize?: number;
+  /**
+   * Active sort: `id` is a sortable field name (declared non-json
+   * field, or system `id`/`created_at`/`updated_at`). `null` keeps the
+   * server default (`created_at` desc, `id` tiebreak).
+   */
+  readonly sort?: SortValue | null;
+  /** Called when the user changes the sort via a column header click. */
+  readonly onSortChange?: (sort: SortValue | null) => void;
+  /** Column definitions for the grid, converted to TanStack columns internally. */
+  readonly columns?: readonly RecordColumnDef[];
+}
+
+/** Return value of {@link useRecordCollection}. */
+export interface UseRecordCollectionReturn {
+  /** Records in the current page. */
+  readonly records: readonly RecordEnvelope[];
+  /** Total records matching the filter (across all pages). */
+  readonly total: number;
+  /** Total number of pages at the current page size. */
+  readonly totalPages: number;
+  /** The current page number (mirrors input). */
+  readonly currentPage: number;
+  /** `true` during the initial fetch (no data yet). */
+  readonly isLoading: boolean;
+  /** `true` during a background refetch while stale data is shown. */
+  readonly isRefetching: boolean;
+  /**
+   * Error from the last failed fetch, or `null`. A record-layer
+   * `PERMISSION_DENIED` lands here carrying the server's relayable
+   * message verbatim — render it as the denied panel, never a silently
+   * empty grid (DD-008 SD-3).
+   */
+  readonly error: Error | null;
+  /** Imperatively trigger a refetch (e.g. after a record write). */
+  readonly refetch: () => void;
+  /**
+   * The TanStack Table instance for `ResourceTable` (or custom
+   * renderers). `null` when no columns are provided.
+   */
+  readonly table: Table<RecordEnvelope> | null;
+}
+
+const DEFAULT_PAGE_SIZE = 25;
+const MAX_PAGE_SIZE = 100;
+
+interface RecordCollectionData {
+  readonly records: readonly RecordEnvelope[];
+  readonly total: number;
+}
+
+const INITIAL_DATA: RecordCollectionData = { records: [], total: 0 };
+
+/**
+ * Headless hook that manages records-grid state: `findRecords` fetching,
+ * server-side sort, and RPC limit/offset pagination.
+ *
+ * The deliberate sibling of `useResourceCollection` (DD-008 SD-2):
+ * same headless shape — `useFetch` underneath, TanStack table with
+ * `manualPagination`/`manualSorting`, controlled sort via
+ * `sort`/`onSortChange` — but the record data contract, which the
+ * resource collection structurally cannot carry (its fetch path is
+ * hardcoded to `ListParams`/`SearchResult`). Mirrored, not retrofitted,
+ * so the SDK stays learnable; the produced table feeds the same
+ * presentational `ResourceTable`.
+ *
+ * Everything is server-side: filtering (the typed proto filter),
+ * sorting (single-field `order_by`), and pagination (limit/offset,
+ * default 25, max 100). The hook performs no client-side filtering or
+ * sorting — one query surface (DD-008 invariant 1).
+ *
+ * @example
+ * ```tsx
+ * const collection = useRecordCollection({
+ *   org: "acme",
+ *   datastore: "clinic",
+ *   collection: "bookings",
+ *   partition,
+ *   filter,
+ *   page,
+ *   sort,
+ *   onSortChange: setSort,
+ *   columns: recordColumns,
+ * });
+ * return <ResourceTable table={collection.table} />;
+ * ```
+ */
+export function useRecordCollection(
+  options: UseRecordCollectionOptions,
+): UseRecordCollectionReturn {
+  const {
+    org,
+    datastore,
+    collection,
+    partition = "",
+    filter,
+    page = 1,
+    pageSize = DEFAULT_PAGE_SIZE,
+    sort = null,
+    onSortChange,
+    columns = [],
+  } = options;
+
+  const stigmer = useStigmer();
+
+  const limit = Math.min(Math.max(pageSize, 1), MAX_PAGE_SIZE);
+  const offset = (Math.max(page, 1) - 1) * limit;
+
+  // Proto messages are typically rebuilt each render; serialized JSON is
+  // the stable identity for dependency comparison.
+  const filterKey = filter ? toJsonString(RecordFilterSchema, filter) : "";
+
+  const orderBy = useMemo(() => {
+    if (!sort) return undefined;
+    return create(RecordOrderBySchema, {
+      field: sort.id,
+      direction: sort.direction === "desc" ? RecordSortDirection.desc : RecordSortDirection.asc,
+    });
+  }, [sort]);
+  const orderByKey = orderBy ? toJsonString(RecordOrderBySchema, orderBy) : "";
+
+  // --- Data fetching via useFetch -----------------------------------------
+  const { data, isLoading, isRefetching, error, refetch } = useFetch<RecordCollectionData>(
+    org && datastore && collection
+      ? async () => {
+          const result = await stigmer.datastore.findRecords(
+            create(FindRecordsRequestSchema, {
+              org,
+              datastore,
+              collection,
+              partition,
+              filter,
+              orderBy,
+              limit,
+              offset,
+            }),
+          );
+          return { records: result.records, total: result.total };
+        }
+      : null,
+    [org, datastore, collection, partition, filterKey, orderByKey, limit, offset, stigmer],
+    INITIAL_DATA,
+  );
+
+  // --- TanStack Table sorting bridge --------------------------------------
+  const sortingState: SortingState = useMemo(() => {
+    if (!sort) return [];
+    return [{ id: sort.id, desc: sort.direction === "desc" }];
+  }, [sort]);
+
+  const onSortChangeRef = useRef(onSortChange);
+  onSortChangeRef.current = onSortChange;
+
+  const handleSortingChange = useCallback(
+    (updater: SortingState | ((prev: SortingState) => SortingState)) => {
+      const next = typeof updater === "function" ? updater(sortingState) : updater;
+      if (next.length === 0) {
+        onSortChangeRef.current?.(null);
+      } else {
+        const col = next[0];
+        onSortChangeRef.current?.({
+          id: col.id,
+          direction: (col.desc ? "desc" : "asc") as SortDirection,
+        });
+      }
+    },
+    [sortingState],
+  );
+
+  // --- TanStack Table column conversion -----------------------------------
+  const tanstackColumns = useMemo<ColumnDef<RecordEnvelope, unknown>[]>(() => {
+    return columns.map((col) => ({
+      id: col.id,
+      header: col.header,
+      cell: (info) => col.cell(info.row.original),
+      enableSorting: col.sortable ?? false,
+      size: col.minWidth,
+      minSize: col.minWidth,
+    }));
+  }, [columns]);
+
+  // --- TanStack Table instance -------------------------------------------
+  // No getSortedRowModel: sorting is entirely server-side (manualSorting)
+  // and the page arrives in server order — a client sort model would be
+  // dead code implying a second sorting authority.
+  const table = useReactTable<RecordEnvelope>({
+    data: data.records as RecordEnvelope[],
+    columns: tanstackColumns,
+    state: { sorting: sortingState },
+    onSortingChange: handleSortingChange,
+    getCoreRowModel: getCoreRowModel(),
+    getRowId: (row) => row.id,
+    manualPagination: true,
+    manualSorting: true,
+  });
+
+  return {
+    records: data.records,
+    total: data.total,
+    totalPages: Math.ceil(data.total / limit),
+    currentPage: page,
+    isLoading,
+    isRefetching,
+    error,
+    refetch,
+    table: tanstackColumns.length > 0 ? table : null,
+  };
+}

package/src/datastore/useRecordList.ts

@@ -0,0 +1,131 @@
+"use client";
+
+import { create, toJsonString } from "@bufbuild/protobuf";
+import {
+  FindRecordsRequestSchema,
+  RecordFilterSchema,
+  RecordOrderBySchema,
+  type RecordEnvelope,
+  type RecordFilter,
+  type RecordOrderBy,
+} from "@stigmer/protos/ai/stigmer/agentic/datastore/v1/record_io_pb";
+import { useStigmer } from "../hooks.js";
+import { useFetch } from "../internal/useFetch.js";
+
+/**
+ * Addressing shared by every record read/write: which datastore, which
+ * collection, and which data partition (DD-010 — every record operation
+ * is partition-scoped; empty means the `"default"` partition).
+ */
+export interface RecordScope {
+  /** Organization slug. Required for cloud direct callers; OSS defaults it. */
+  readonly org: string;
+  /** Datastore slug. */
+  readonly datastore: string;
+  /** Collection name. */
+  readonly collection: string;
+  /** Data partition. Empty or omitted means `"default"`. */
+  readonly partition?: string;
+}
+
+/** Query parameters for {@link useRecordList}. */
+export interface UseRecordListParams extends RecordScope {
+  /**
+   * Typed AND-only filter in the proto shape (DD-005 grammar). The hook
+   * adds no grammar of its own — anything expressible here is exactly
+   * what `findRecords` serves.
+   */
+  readonly filter?: RecordFilter;
+  /** Sort directive. Omitted keeps the default: `created_at` desc, `id` tiebreak. */
+  readonly orderBy?: RecordOrderBy;
+  /** Page size, 1–100. Zero or omitted applies the RPC default of 25. */
+  readonly limit?: number;
+  /** Row offset for pagination. */
+  readonly offset?: number;
+}
+
+/** Return value of {@link useRecordList}. */
+export interface UseRecordListReturn {
+  /** Records in the current page. */
+  readonly records: readonly RecordEnvelope[];
+  /** Total records matching the filter (across all pages). */
+  readonly total: number;
+  /** `true` while the initial fetch is in flight. */
+  readonly isLoading: boolean;
+  /** `true` while a background refetch is in flight. */
+  readonly isRefetching: boolean;
+  /** Error from the last failed request, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Discard cached data and re-fetch the current page from the server. */
+  readonly refetch: () => void;
+}
+
+interface RecordListData {
+  readonly records: readonly RecordEnvelope[];
+  readonly total: number;
+}
+
+const INITIAL_DATA: RecordListData = { records: [], total: 0 };
+
+/**
+ * Data hook that fetches a page of records via `findRecords` — the one
+ * query surface (DD-008 invariant 1): server-side filtering with the
+ * DD-005 grammar, RPC limit/offset pagination, no client-side
+ * filtering.
+ *
+ * A record-layer `PERMISSION_DENIED` (caller holds no read grant on the
+ * collection) surfaces as `error` carrying the server's relayable
+ * message verbatim; consumers render it as the denied panel, never a
+ * silently empty grid.
+ *
+ * Pass `null` to skip fetching (stable no-op) — e.g. while the
+ * collection is not yet selected.
+ *
+ * For the full grid experience (TanStack table, sort bridge, page
+ * state), use {@link useRecordCollection}, which builds on the same
+ * RPC.
+ */
+export function useRecordList(
+  params: UseRecordListParams | null,
+): UseRecordListReturn {
+  const stigmer = useStigmer();
+
+  // Proto messages are typically rebuilt each render; serialized JSON is
+  // the stable identity for dependency comparison.
+  const filterKey = params?.filter ? toJsonString(RecordFilterSchema, params.filter) : "";
+  const orderByKey = params?.orderBy ? toJsonString(RecordOrderBySchema, params.orderBy) : "";
+
+  const { data, isLoading, isRefetching, error, refetch } = useFetch<RecordListData>(
+    params
+      ? async () => {
+          const result = await stigmer.datastore.findRecords(
+            create(FindRecordsRequestSchema, {
+              org: params.org,
+              datastore: params.datastore,
+              collection: params.collection,
+              partition: params.partition ?? "",
+              filter: params.filter,
+              orderBy: params.orderBy,
+              limit: params.limit ?? 0,
+              offset: params.offset ?? 0,
+            }),
+          );
+          return { records: result.records, total: result.total };
+        }
+      : null,
+    [
+      params?.org,
+      params?.datastore,
+      params?.collection,
+      params?.partition,
+      filterKey,
+      orderByKey,
+      params?.limit,
+      params?.offset,
+      stigmer,
+    ],
+    INITIAL_DATA,
+  );
+
+  return { records: data.records, total: data.total, isLoading, isRefetching, error, refetch };
+}