lemma-sdk 0.2.31 → 0.2.33

package/dist/react/useRecordForm.js

@@ -3,7 +3,7 @@ import { buildRecordFormValues, buildRecordPayload, } from "../record-form.js";
 import { normalizeError, resolvePodClient, stringifyComparable } from "./utils.js";
 import { useRecordSchema, } from "./useRecordSchema.js";
 const EMPTY_VALUES = {};
-export function useRecordForm({ client, podId, tableName, recordId = null, initialValues = EMPTY_VALUES, mode = "auto", enabled = true, autoLoad = true, onSubmitSuccess, onError, }) {
+export function useRecordForm({ client, podId, tableName, recordId = null, initialValues = EMPTY_VALUES, mode = "auto", enabled = true, autoLoad = true, visibleFields, hiddenFields, submitVia = "direct", submitFunctionName, submitFunctionInput, onSubmitSuccess, onError, }) {
     const schema = useRecordSchema({
         client,
         podId,
@@ -11,6 +11,30 @@ export function useRecordForm({ client, podId, tableName, recordId = null, initi
         enabled,
         autoLoad,
     });
+    const visibleSet = useMemo(() => visibleFields ? new Set(visibleFields) : null, [visibleFields]);
+    const hiddenSet = useMemo(() => hiddenFields ? new Set(hiddenFields) : null, [hiddenFields]);
+    const filteredFields = useMemo(() => {
+        if (!visibleSet && !hiddenSet)
+            return schema.fields;
+        return schema.fields.filter((field) => {
+            if (visibleSet)
+                return visibleSet.has(field.name);
+            if (hiddenSet)
+                return !hiddenSet.has(field.name);
+            return true;
+        });
+    }, [hiddenSet, schema.fields, visibleSet]);
+    const filteredEditableFields = useMemo(() => {
+        if (!visibleSet && !hiddenSet)
+            return schema.editableFields;
+        return schema.editableFields.filter((field) => {
+            if (visibleSet)
+                return visibleSet.has(field.name);
+            if (hiddenSet)
+                return !hiddenSet.has(field.name);
+            return true;
+        });
+    }, [hiddenSet, schema.editableFields, visibleSet]);
     const [record, setRecord] = useState(null);
     const [values, setValuesState] = useState({});
     const [baselineValues, setBaselineValues] = useState({});
@@ -147,6 +171,19 @@ export function useRecordForm({ client, podId, tableName, recordId = null, initi
         setRecordError(null);
         try {
             const scopedClient = resolvePodClient(client, podId);
+            if (submitVia === "function") {
+                const functionName = submitFunctionName ?? tableName;
+                const functionInput = submitFunctionInput ? submitFunctionInput(payload.data) : payload.data;
+                const run = await scopedClient.functions.runs.create(functionName, { input: functionInput });
+                const nextRecord = run.output_data ?? { id: run.id, ...functionInput };
+                setRecord(nextRecord);
+                hydrateValues({
+                    ...(nextRecord ?? {}),
+                    ...stableInitialValues,
+                });
+                onSubmitSuccess?.(nextRecord ?? {}, run);
+                return nextRecord;
+            }
             const response = resolvedMode === "update" && recordId
                 ? await scopedClient.records.update(tableName, recordId, payload.data)
                 : await scopedClient.records.create(tableName, payload.data);
@@ -168,14 +205,14 @@ export function useRecordForm({ client, podId, tableName, recordId = null, initi
         finally {
             setIsSubmitting(false);
         }
-    }, [client, hydrateValues, mode, onError, onSubmitSuccess, podId, recordId, schemaTable, stableInitialValues, tableName, values]);
+    }, [client, hydrateValues, mode, onError, onSubmitSuccess, podId, recordId, schemaTable, stableInitialValues, submitFunctionInput, submitFunctionName, submitVia, tableName, values]);
     const isDirty = useMemo(() => {
         return stringifyComparable(values) !== stringifyComparable(baselineValues);
     }, [baselineValues, values]);
     return useMemo(() => ({
         table: schema.table,
-        fields: schema.fields,
-        editableFields: schema.editableFields,
+        fields: filteredFields,
+        editableFields: filteredEditableFields,
         defaults: schema.defaults,
         values,
         baselineValues,
@@ -197,6 +234,8 @@ export function useRecordForm({ client, podId, tableName, recordId = null, initi
     }), [
         baselineValues,
         fieldErrors,
+        filteredEditableFields,
+        filteredFields,
         isDirty,
         isLoadingRecord,
         isSubmitting,
@@ -206,9 +245,7 @@ export function useRecordForm({ client, podId, tableName, recordId = null, initi
         refreshRecord,
         reset,
         schema.defaults,
-        schema.editableFields,
         schema.error,
-        schema.fields,
         schema.isLoading,
         schema.refresh,
         schema.table,

package/dist/react/useRecords.js

@@ -72,7 +72,10 @@ export function useRecords({ client, podId, tableName, filters, sort, limit = 20
         trimmedTableName,
     ]);
     const loadMore = useCallback(async (overrides = {}) => {
-        if (!isEnabled || !nextPageToken || isLoading || isLoadingMore) {
+        const loadedCount = records.length;
+        const canLoadWithCursor = Boolean(nextPageToken);
+        const canLoadWithOffset = loadedCount < total;
+        if (!isEnabled || isLoading || isLoadingMore || (!canLoadWithCursor && !canLoadWithOffset)) {
             return [];
         }
         setIsLoadingMore(true);
@@ -83,15 +86,15 @@ export function useRecords({ client, podId, tableName, filters, sort, limit = 20
                 filters: stableFilters,
                 sort: stableSort,
                 limit: overrides.limit ?? limit,
-                pageToken: nextPageToken,
-                offset: overrides.offset,
+                pageToken: overrides.pageToken ?? nextPageToken ?? undefined,
+                offset: overrides.offset ?? (nextPageToken ? undefined : (offset ?? 0) + loadedCount),
                 sortBy: overrides.sortBy ?? sortBy,
                 order: overrides.order ?? order,
                 params: overrides.params ?? stableParams,
             });
             const moreRecords = (response.items ?? []);
             setRecords((previous) => [...previous, ...moreRecords]);
-            setTotal(response.total ?? records.length + moreRecords.length);
+            setTotal(response.total ?? loadedCount + moreRecords.length);
             setNextPageToken(response.next_page_token ?? null);
             return moreRecords;
         }
@@ -103,7 +106,7 @@ export function useRecords({ client, podId, tableName, filters, sort, limit = 20
         finally {
             setIsLoadingMore(false);
         }
-    }, [client, isEnabled, isLoading, isLoadingMore, limit, nextPageToken, offset, order, podId, records.length, sortBy, stableFilters, stableParams, stableSort, trimmedTableName]);
+    }, [client, isEnabled, isLoading, isLoadingMore, limit, nextPageToken, offset, order, podId, records.length, sortBy, stableFilters, stableParams, stableSort, total, trimmedTableName]);
     useEffect(() => {
         if (!isEnabled) {
             setRecords([]);

package/dist/react/useReferencingRecords.d.ts

@@ -0,0 +1,66 @@
+import type { LemmaClient } from "../client.js";
+import type { Table } from "../types.js";
+/**
+ * React hook for fetching records from a referencing table that point back
+ * to a specific record via a foreign key.
+ *
+ * Unlike `useReverseRelatedRecords` which starts from a parent table and
+ * discovers what references it, this hook starts from the child table and
+ * says "give me all rows in this table where this FK column equals this ID."
+ *
+ * @example Fetch all comments for an issue
+ * ```tsx
+ * const { records, isLoading } = useReferencingRecords({
+ *   client,
+ *   table: "comments",
+ *   foreignKey: "issue_id",
+ *   recordId: "issue_123",
+ * });
+ * ```
+ *
+ * @example Fetch history entries
+ * ```tsx
+ * const { records, columns, isLoading } = useReferencingRecords({
+ *   client,
+ *   table: "issue_history",
+ *   foreignKey: "issue_id",
+ *   recordId: selectedIssueId,
+ *   sortBy: "created_at",
+ *   order: "desc",
+ * });
+ * ```
+ */
+export interface ReferencingRecordsColumn {
+    key: string;
+    field: string;
+    label: string;
+}
+export interface UseReferencingRecordsOptions {
+    client: LemmaClient;
+    podId?: string;
+    /** The referencing (child) table, e.g. "comments". */
+    table: string;
+    /** The foreign-key column in the referencing table, e.g. "issue_id". */
+    foreignKey: string;
+    /** The record ID value to match against the foreign-key column. */
+    recordId?: string | null;
+    /** Fields to select. Auto-resolved from the table schema if omitted. */
+    fields?: string[];
+    limit?: number;
+    offset?: number;
+    sortBy?: string;
+    order?: "asc" | "desc" | string;
+    enabled?: boolean;
+    autoLoad?: boolean;
+}
+export interface UseReferencingRecordsResult<TRow extends Record<string, unknown> = Record<string, unknown>> {
+    referencedTable: Table | null;
+    columns: ReferencingRecordsColumn[];
+    records: TRow[];
+    total: number;
+    nextPageToken: string | null;
+    isLoading: boolean;
+    error: Error | null;
+    refresh: () => Promise<TRow[]>;
+}
+export declare function useReferencingRecords<TRow extends Record<string, unknown> = Record<string, unknown>>({ client, podId, table, foreignKey, recordId, fields, limit, offset, sortBy, order, enabled, autoLoad, }: UseReferencingRecordsOptions): UseReferencingRecordsResult<TRow>;

package/dist/react/useReferencingRecords.js

@@ -0,0 +1,159 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { normalizeError, resolvePodClient, stringifyComparable } from "./utils.js";
+function sentenceCase(value) {
+    return value
+        .replace(/[_\.]/g, " ")
+        .replace(/\s+/g, " ")
+        .trim()
+        .replace(/\b\w/g, (match) => match.toUpperCase());
+}
+function pickDefaultFields(table, foreignKey) {
+    const names = table.columns
+        .map((column) => column.name)
+        .filter((name) => name !== "created_at" && name !== "updated_at");
+    const prioritized = ["id", "name", "title", "label", "status", foreignKey];
+    const next = [];
+    prioritized.forEach((name) => {
+        if (names.includes(name) && !next.includes(name)) {
+            next.push(name);
+        }
+    });
+    names.forEach((name) => {
+        if (!next.includes(name)) {
+            next.push(name);
+        }
+    });
+    return next.slice(0, 6);
+}
+export function useReferencingRecords({ client, podId, table, foreignKey, recordId = null, fields, limit = 20, offset, sortBy, order, enabled = true, autoLoad = true, }) {
+    const [referencedTable, setReferencedTable] = useState(null);
+    const [columns, setColumns] = useState([]);
+    const [records, setRecords] = useState([]);
+    const [total, setTotal] = useState(0);
+    const [nextPageToken, setNextPageToken] = useState(null);
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const trimmedTable = table.trim();
+    const trimmedRecordId = typeof recordId === "string" ? recordId.trim() : "";
+    const fieldsKey = stringifyComparable(fields);
+    const stableFields = useMemo(() => fields, [fieldsKey]);
+    const isEnabled = enabled && trimmedTable.length > 0 && trimmedRecordId.length > 0;
+    const refresh = useCallback(async (signal) => {
+        if (!isEnabled) {
+            setReferencedTable(null);
+            setColumns([]);
+            setRecords([]);
+            setTotal(0);
+            setNextPageToken(null);
+            setError(null);
+            setIsLoading(false);
+            return [];
+        }
+        setIsLoading(true);
+        setError(null);
+        try {
+            const scopedClient = resolvePodClient(client, podId);
+            const tableResponse = await scopedClient.tables.get(trimmedTable);
+            if (signal?.aborted)
+                return [];
+            setReferencedTable(tableResponse);
+            const resolvedFields = (stableFields?.length ? stableFields : pickDefaultFields(tableResponse, foreignKey))
+                .filter((field, index, allFields) => field.trim().length > 0 && allFields.indexOf(field) === index);
+            const response = await scopedClient.records.list(trimmedTable, {
+                filters: [{
+                        field: foreignKey,
+                        op: "eq",
+                        value: trimmedRecordId,
+                    }],
+                limit,
+                offset,
+                sortBy,
+                order,
+            });
+            if (signal?.aborted)
+                return [];
+            const nextRecords = (response.items ?? []);
+            setColumns(resolvedFields.map((field) => ({
+                key: field,
+                field,
+                label: sentenceCase(field),
+            })));
+            setRecords(nextRecords);
+            setTotal(response.total ?? nextRecords.length);
+            setNextPageToken(response.next_page_token ?? null);
+            return nextRecords;
+        }
+        catch (refreshError) {
+            if (signal?.aborted)
+                return [];
+            const normalized = normalizeError(refreshError, "Failed to load referencing records.");
+            setError(normalized);
+            return [];
+        }
+        finally {
+            if (!signal?.aborted)
+                setIsLoading(false);
+        }
+    }, [
+        client,
+        foreignKey,
+        isEnabled,
+        limit,
+        offset,
+        order,
+        podId,
+        sortBy,
+        stableFields,
+        trimmedRecordId,
+        trimmedTable,
+    ]);
+    useEffect(() => {
+        if (!isEnabled) {
+            setReferencedTable(null);
+            setColumns([]);
+            setRecords([]);
+            setTotal(0);
+            setNextPageToken(null);
+            setError(null);
+            setIsLoading(false);
+            return;
+        }
+        if (!autoLoad)
+            return;
+        const controller = new AbortController();
+        let cancelled = false;
+        (async () => {
+            try {
+                await refresh(controller.signal);
+            }
+            catch {
+                if (!cancelled) {
+                    setError(normalizeError(new Error("Failed to load referencing records."), "Failed to load referencing records."));
+                }
+            }
+        })();
+        return () => {
+            cancelled = true;
+            controller.abort();
+        };
+    }, [autoLoad, isEnabled, refresh]);
+    return useMemo(() => ({
+        referencedTable,
+        columns,
+        records,
+        total,
+        nextPageToken,
+        isLoading,
+        error,
+        refresh,
+    }), [
+        columns,
+        error,
+        isLoading,
+        nextPageToken,
+        records,
+        refresh,
+        referencedTable,
+        total,
+    ]);
+}

package/dist/react/useRelatedRecords.d.ts

@@ -1,5 +1,22 @@
 import type { LemmaClient } from "../client.js";
 import type { Table } from "../types.js";
+/**
+ * React hook for fetching base-table rows with their FK-related data
+ * joined in a single query. You specify which FK columns to include and
+ * the hook auto-resolves the referenced table and join columns.
+ *
+ * The result has nested objects: `{ id, name, team: { id, name } }`.
+ *
+ * @example Issues with their team
+ * ```tsx
+ * const { records, isLoading } = useRelatedRecords({
+ *   client,
+ *   tableName: "issues",
+ *   include: [{ foreignKey: "team_id" }],
+ * });
+ * // records[0] = { id: "1", title: "Bug", team: { id: "t1", name: "Eng" } }
+ * ```
+ */
 export interface RelatedRecordsInclude {
     foreignKey: string;
     as?: string;

package/dist/react/useReverseRelatedRecords.d.ts

@@ -1,5 +1,26 @@
 import type { LemmaClient } from "../client.js";
 import type { Table } from "../types.js";
+/**
+ * React hook for finding records in *other* tables that reference a given
+ * record. Starts from the parent table, discovers all tables with FK
+ * columns pointing back to it, and fetches the referencing rows.
+ *
+ * For the simpler case where you already know the referencing table and
+ * FK column, prefer `useReferencingRecords` — it has a more intuitive API.
+ *
+ * @example All comments and history entries for an issue
+ * ```tsx
+ * const { relations, records, isLoading } = useReverseRelatedRecords({
+ *   client,
+ *   tableName: "issues",
+ *   recordId: "issue_123",
+ *   relation: { tableName: "comments", foreignKey: "issue_id" },
+ * });
+ * ```
+ *
+ * @see useReferencingRecords — flipped-perspective alias for the common
+ *   "show me all rows in table X where FK = Y" pattern.
+ */
 export interface ReverseRelationSelector {
     tableName: string;
     foreignKey: string;

package/dist/react/useUpdateRecord.d.ts

@@ -1,12 +1,43 @@
 import type { LemmaClient } from "../client.js";
-import type { RecordResponse } from "../types.js";
+import type { FunctionRun, RecordResponse } from "../types.js";
+/**
+ * React hook for updating a single record. Manages loading/error state and
+ * exposes an `update` function you can call from event handlers.
+ *
+ * Supports two modes:
+ * - `"direct"` (default): calls `records.update` directly.
+ * - `"function"`: calls `functions.runs.create`, routing the update through
+ *   a pod function (e.g. for status transitions that log history).
+ *
+ * @example Direct update
+ * ```tsx
+ * const { update, isSubmitting } = useUpdateRecord({ client, tableName: "issues", recordId: "123" });
+ * await update({ status: "closed" });
+ * ```
+ *
+ * @example Function-backed update
+ * ```tsx
+ * const { update, isSubmitting } = useUpdateRecord({
+ *   client,
+ *   tableName: "issues",
+ *   recordId: "123",
+ *   updateVia: "function",
+ *   updateFunctionName: "update-issue-status",
+ * });
+ * await update({ status: "in_progress" });
+ * ```
+ */
 export interface UseUpdateRecordOptions {
     client: LemmaClient;
     podId?: string;
     tableName: string;
     recordId?: string | null;
     enabled?: boolean;
-    onSuccess?: (record: Record<string, unknown>, response: RecordResponse) => void;
+    /** How the record is updated. `"direct"` calls `records.update`. `"function"` calls `functions.runs.create`. */
+    updateVia?: "direct" | "function";
+    /** Function name to run when `updateVia` is `"function"`. Falls back to `tableName` if omitted. */
+    updateFunctionName?: string;
+    onSuccess?: (record: Record<string, unknown>, response: RecordResponse | FunctionRun) => void;
     onError?: (error: unknown) => void;
 }
 export interface UseUpdateRecordResult<TRecord extends Record<string, unknown> = Record<string, unknown>> {
@@ -18,4 +49,4 @@ export interface UseUpdateRecordResult<TRecord extends Record<string, unknown> =
     }) => Promise<TRecord | null>;
     reset: () => void;
 }
-export declare function useUpdateRecord<TRecord extends Record<string, unknown> = Record<string, unknown>>({ client, podId, tableName, recordId, enabled, onSuccess, onError, }: UseUpdateRecordOptions): UseUpdateRecordResult<TRecord>;
+export declare function useUpdateRecord<TRecord extends Record<string, unknown> = Record<string, unknown>>({ client, podId, tableName, recordId, enabled, updateVia, updateFunctionName, onSuccess, onError, }: UseUpdateRecordOptions): UseUpdateRecordResult<TRecord>;

package/dist/react/useUpdateRecord.js

@@ -1,6 +1,6 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { normalizeError, resolvePodClient } from "./utils.js";
-export function useUpdateRecord({ client, podId, tableName, recordId = null, enabled = true, onSuccess, onError, }) {
+export function useUpdateRecord({ client, podId, tableName, recordId = null, enabled = true, updateVia = "direct", updateFunctionName, onSuccess, onError, }) {
     const [updatedRecord, setUpdatedRecord] = useState(null);
     const [isSubmitting, setIsSubmitting] = useState(false);
     const [error, setError] = useState(null);
@@ -22,6 +22,17 @@ export function useUpdateRecord({ client, podId, tableName, recordId = null, ena
         setError(null);
         try {
             const scopedClient = resolvePodClient(client, podId);
+            if (updateVia === "function") {
+                const functionName = updateFunctionName ?? trimmedTableName;
+                const input = { ...data, id: nextRecordId, record_id: nextRecordId };
+                const run = await scopedClient.functions.runs.create(functionName, { input });
+                const nextRecord = (run.output_data ?? { id: nextRecordId, ...data });
+                setUpdatedRecord(nextRecord);
+                if (nextRecord) {
+                    onSuccessRef.current?.(nextRecord, run);
+                }
+                return nextRecord;
+            }
             const response = await scopedClient.records.update(trimmedTableName, nextRecordId, data);
             const nextRecord = (response.data ?? null);
             setUpdatedRecord(nextRecord);
@@ -39,7 +50,7 @@ export function useUpdateRecord({ client, podId, tableName, recordId = null, ena
         finally {
             setIsSubmitting(false);
         }
-    }, [client, isEnabled, podId, trimmedRecordId, trimmedTableName]);
+    }, [client, isEnabled, podId, trimmedRecordId, trimmedTableName, updateFunctionName, updateVia]);
     const reset = useCallback(() => {
         setUpdatedRecord(null);
         setError(null);

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import type { AgentResponse, AssistantResponse, AvailableModels, ColumnSchema, ConversationMessageResponse, ConversationResponse, CreateAgentRequest, CreateAssistantRequest, CreateTaskRequest, DatastoreQueryResponse, FlowRunEntity, FlowResponse, FunctionRunResponse, IconUploadResponse, OrganizationInvitationResponse, OrganizationMemberResponse, OrganizationResponse, PodConfigResponse, PodJoinRequestCreateResponse, PodMemberResponse, PodResponse, TableResponse, TaskMessageResponse, TaskResponse, UpdateAgentRequest, UpdateAssistantRequest, UserResponse } from "./openapi_client/index.js";
+import type { AgentResponse, AssistantResponse, AvailableModels, ColumnSchema, ConversationMessageResponse, ConversationResponse, CreateAgentRequest, CreateAssistantRequest, CreateTaskRequest, DatastoreQueryResponse, DirectoryTreeNode, DirectoryTreeResponse, FileResponse, FileSearchResponse, FileSearchResultSchema, FlowRunEntity, FlowResponse, FunctionRunResponse, IconUploadResponse, OrganizationInvitationResponse, OrganizationMemberResponse, OrganizationResponse, PodConfigResponse, PodJoinRequestCreateResponse, PodMemberResponse, PodResponse, TableResponse, TaskMessageResponse, TaskResponse, UpdateAgentRequest, UpdateAssistantRequest, UserResponse } from "./openapi_client/index.js";
 /** Public ergonomic types. */
 export interface PageResult<T> {
     items: T[];
@@ -55,6 +55,11 @@ export type Workflow = FlowResponse;
 export type Table = TableResponse;
 export type TableColumn = ColumnSchema;
 export type DatastoreQueryResult = DatastoreQueryResponse;
+export type DatastoreFile = FileResponse;
+export type DatastoreFileSearchResponse = FileSearchResponse;
+export type DatastoreFileSearchResult = FileSearchResultSchema;
+export type DatastoreDirectoryTree = DirectoryTreeResponse;
+export type DatastoreDirectoryTreeNode = DirectoryTreeNode;
 export type Pod = PodResponse;
 export type PodConfig = PodConfigResponse;
 export type PodMember = PodMemberResponse;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lemma-sdk",
-  "version": "0.2.31",
+  "version": "0.2.33",
   "description": "Official TypeScript SDK for Lemma pod-scoped APIs",
   "type": "module",
   "main": "dist/index.js",
@@ -45,6 +45,7 @@
     "build:bundle": "tsc -p tsconfig.bundle.json && node ./scripts/build_browser_bundle.mjs",
     "clean": "node -e \"require('fs').rmSync('dist', { recursive: true, force: true, maxRetries: 10, retryDelay: 100 })\"",
     "registry:build": "shadcn build ./registry.json -o ./public/r",
+    "registry:check": "npm run registry:build && node ./scripts/check_registry_blocks.mjs",
     "prepublishOnly": "npm run build",
     "release:check": "npm run build && npm_config_cache=.npm-cache npm pack --dry-run"
   },