lemma-sdk 0.2.30 → 0.2.32

package/dist/react/useTable.js

@@ -1,21 +1,12 @@
 import { useCallback, useEffect, useMemo, useState } from "react";
-function resolvePodClient(client, podId) {
-    if (!podId || podId === client.podId)
-        return client;
-    return client.withPod(podId);
-}
-function normalizeError(error, fallback) {
-    if (error instanceof Error)
-        return error;
-    return new Error(fallback);
-}
+import { normalizeError, resolvePodClient } from "./utils.js";
 export function useTable({ client, podId, tableName, enabled = true, autoLoad = true, }) {
     const [table, setTable] = useState(null);
     const [isLoading, setIsLoading] = useState(false);
     const [error, setError] = useState(null);
     const trimmedTableName = tableName.trim();
     const isEnabled = enabled && trimmedTableName.length > 0;
-    const refresh = useCallback(async () => {
+    const refresh = useCallback(async (signal) => {
         if (!isEnabled) {
             setTable(null);
             setError(null);
@@ -27,16 +18,21 @@ export function useTable({ client, podId, tableName, enabled = true, autoLoad =
         try {
             const scopedClient = resolvePodClient(client, podId);
             const nextTable = await scopedClient.tables.get(trimmedTableName);
+            if (signal?.aborted)
+                return null;
             setTable(nextTable);
             return nextTable;
         }
         catch (refreshError) {
+            if (signal?.aborted)
+                return null;
             const normalized = normalizeError(refreshError, "Failed to load table.");
             setError(normalized);
             return null;
         }
         finally {
-            setIsLoading(false);
+            if (!signal?.aborted)
+                setIsLoading(false);
         }
     }, [client, isEnabled, podId, trimmedTableName]);
     useEffect(() => {
@@ -48,7 +44,22 @@ export function useTable({ client, podId, tableName, enabled = true, autoLoad =
         }
         if (!autoLoad)
             return;
-        void refresh();
+        const controller = new AbortController();
+        let cancelled = false;
+        (async () => {
+            try {
+                await refresh(controller.signal);
+            }
+            catch {
+                if (!cancelled) {
+                    setError(normalizeError(new Error("Failed to load table."), "Failed to load table."));
+                }
+            }
+        })();
+        return () => {
+            cancelled = true;
+            controller.abort();
+        };
     }, [autoLoad, isEnabled, refresh]);
     return useMemo(() => ({
         table,

package/dist/react/useTables.d.ts

@@ -13,10 +13,14 @@ export interface UseTablesResult {
     total: number;
     nextPageToken: string | null;
     isLoading: boolean;
+    isLoadingMore: boolean;
     error: Error | null;
     refresh: (overrides?: {
         limit?: number;
         pageToken?: string;
     }) => Promise<Table[]>;
+    loadMore: (overrides?: {
+        limit?: number;
+    }) => Promise<Table[]>;
 }
 export declare function useTables({ client, podId, enabled, autoLoad, limit, pageToken, }: UseTablesOptions): UseTablesResult;

package/dist/react/useTables.js

@@ -1,21 +1,13 @@
 import { useCallback, useEffect, useMemo, useState } from "react";
-function resolvePodClient(client, podId) {
-    if (!podId || podId === client.podId)
-        return client;
-    return client.withPod(podId);
-}
-function normalizeError(error, fallback) {
-    if (error instanceof Error)
-        return error;
-    return new Error(fallback);
-}
+import { normalizeError, resolvePodClient } from "./utils.js";
 export function useTables({ client, podId, enabled = true, autoLoad = true, limit = 100, pageToken, }) {
     const [tables, setTables] = useState([]);
     const [total, setTotal] = useState(0);
     const [nextPageToken, setNextPageToken] = useState(null);
     const [isLoading, setIsLoading] = useState(false);
+    const [isLoadingMore, setIsLoadingMore] = useState(false);
     const [error, setError] = useState(null);
-    const refresh = useCallback(async (overrides = {}) => {
+    const refresh = useCallback(async (overrides = {}, signal) => {
         if (!enabled) {
             setTables([]);
             setTotal(0);
@@ -32,21 +24,53 @@ export function useTables({ client, podId, enabled = true, autoLoad = true, limi
                 limit: overrides.limit ?? limit,
                 pageToken: overrides.pageToken ?? pageToken,
             });
+            if (signal?.aborted)
+                return [];
             const nextTables = response.items ?? [];
             setTables(nextTables);
-            setTotal(nextTables.length);
+            setTotal(response.total ?? nextTables.length);
             setNextPageToken(response.next_page_token ?? null);
             return nextTables;
         }
         catch (refreshError) {
+            if (signal?.aborted)
+                return [];
             const normalized = normalizeError(refreshError, "Failed to load tables.");
             setError(normalized);
             return [];
         }
         finally {
-            setIsLoading(false);
+            if (!signal?.aborted)
+                setIsLoading(false);
         }
     }, [client, enabled, limit, pageToken, podId]);
+    const loadMore = useCallback(async (overrides = {}) => {
+        if (!enabled || !nextPageToken || isLoading || isLoadingMore) {
+            return [];
+        }
+        setIsLoadingMore(true);
+        setError(null);
+        try {
+            const scopedClient = resolvePodClient(client, podId);
+            const response = await scopedClient.tables.list({
+                limit: overrides.limit ?? limit,
+                pageToken: nextPageToken,
+            });
+            const moreTables = response.items ?? [];
+            setTables((previous) => [...previous, ...moreTables]);
+            setTotal(response.total ?? tables.length + moreTables.length);
+            setNextPageToken(response.next_page_token ?? null);
+            return moreTables;
+        }
+        catch (loadError) {
+            const normalized = normalizeError(loadError, "Failed to load more tables.");
+            setError(normalized);
+            return [];
+        }
+        finally {
+            setIsLoadingMore(false);
+        }
+    }, [client, enabled, isLoading, isLoadingMore, limit, nextPageToken, podId, tables.length]);
     useEffect(() => {
         if (!enabled) {
             setTables([]);
@@ -54,18 +78,36 @@ export function useTables({ client, podId, enabled = true, autoLoad = true, limi
             setNextPageToken(null);
             setError(null);
             setIsLoading(false);
+            setIsLoadingMore(false);
             return;
         }
         if (!autoLoad)
             return;
-        void refresh();
+        const controller = new AbortController();
+        let cancelled = false;
+        (async () => {
+            try {
+                await refresh({}, controller.signal);
+            }
+            catch {
+                if (!cancelled) {
+                    setError(normalizeError(new Error("Failed to load tables."), "Failed to load tables."));
+                }
+            }
+        })();
+        return () => {
+            cancelled = true;
+            controller.abort();
+        };
     }, [autoLoad, enabled, refresh]);
     return useMemo(() => ({
         tables,
         total,
         nextPageToken,
         isLoading,
+        isLoadingMore,
         error,
         refresh,
-    }), [error, isLoading, nextPageToken, refresh, tables, total]);
+        loadMore,
+    }), [error, isLoading, isLoadingMore, loadMore, nextPageToken, refresh, tables, total]);
 }

package/dist/react/useTaskSession.js

@@ -2,18 +2,7 @@ import { useCallback, useEffect, useRef, useState } from "react";
 import { parseSSEJson, readSSE } from "../streams.js";
 import { isTerminalTaskStatus, normalizeRunStatus } from "../run-utils.js";
 import { parseTaskStreamEvent, upsertTaskMessage } from "../task-events.js";
-function resolvePodId(client, podId) {
-    const resolved = podId ?? client.podId;
-    if (!resolved) {
-        throw new Error("podId is required. Pass podId or set it on LemmaClient.");
-    }
-    return resolved;
-}
-function normalizeError(error, fallback) {
-    if (error instanceof Error)
-        return error;
-    return new Error(fallback);
-}
+import { normalizeError, resolvePodClient, resolvePodId } from "./utils.js";
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -92,8 +81,8 @@ export function useTaskSession({ client, podId, taskId: externalTaskId = null, a
         if (!id)
             return null;
         try {
-            client.setPodId(resolvePodId(client, podId));
-            const nextTask = await client.tasks.get(id);
+            const scopedClient = resolvePodClient(client, resolvePodId(client, podId));
+            const nextTask = await scopedClient.tasks.get(id);
             setTask(nextTask);
             setTaskStatus(nextTask.status);
             return nextTask;
@@ -110,8 +99,8 @@ export function useTaskSession({ client, podId, taskId: externalTaskId = null, a
         if (!id)
             return [];
         try {
-            client.setPodId(resolvePodId(client, podId));
-            const response = await client.tasks.messages.list(id, { limit: 100 });
+            const scopedClient = resolvePodClient(client, resolvePodId(client, podId));
+            const response = await scopedClient.tasks.messages.list(id, { limit: 100 });
             const nextMessages = response.items ?? [];
             setMessages(nextMessages);
             return nextMessages;
@@ -141,8 +130,8 @@ export function useTaskSession({ client, podId, taskId: externalTaskId = null, a
                     break;
                 }
                 try {
-                    client.setPodId(resolvePodId(client, podId));
-                    const stream = await client.tasks.stream(id, { signal: controller.signal });
+                    const scopedClient = resolvePodClient(client, resolvePodId(client, podId));
+                    const stream = await scopedClient.tasks.stream(id, { signal: controller.signal });
                     reconnectDelayMs = 1000;
                     for await (const event of readSSE(stream)) {
                         if (controller.signal.aborted) {
@@ -201,8 +190,8 @@ export function useTaskSession({ client, podId, taskId: externalTaskId = null, a
     }, [client, disconnect, podId, setTaskStatus]);
     const start = useCallback(async (input) => {
         setError(null);
-        client.setPodId(resolvePodId(client, podId));
-        const created = await client.tasks.create({
+        const scopedClient = resolvePodClient(client, resolvePodId(client, podId));
+        const created = await scopedClient.tasks.create({
             agent_name: input.agentName,
             input_data: input.inputData,
         });
@@ -221,8 +210,8 @@ export function useTaskSession({ client, podId, taskId: externalTaskId = null, a
         if (!id)
             return null;
         try {
-            client.setPodId(resolvePodId(client, podId));
-            const stopped = await client.tasks.stop(id);
+            const scopedClient = resolvePodClient(client, resolvePodId(client, podId));
+            const stopped = await scopedClient.tasks.stop(id);
             setTask(stopped);
             setTaskStatus(stopped.status);
             return stopped;

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,18 +1,13 @@
-import { useCallback, useMemo, useState } from "react";
-function resolvePodClient(client, podId) {
-    if (!podId || podId === client.podId)
-        return client;
-    return client.withPod(podId);
-}
-function normalizeError(error, fallback) {
-    if (error instanceof Error)
-        return error;
-    return new Error(fallback);
-}
-export function useUpdateRecord({ client, podId, tableName, recordId = null, enabled = true, onSuccess, onError, }) {
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { normalizeError, resolvePodClient } from "./utils.js";
+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);
+    const onSuccessRef = useRef(onSuccess);
+    const onErrorRef = useRef(onError);
+    useEffect(() => { onSuccessRef.current = onSuccess; }, [onSuccess]);
+    useEffect(() => { onErrorRef.current = onError; }, [onError]);
     const trimmedTableName = tableName.trim();
     const trimmedRecordId = typeof recordId === "string" ? recordId.trim() : "";
     const isEnabled = enabled && trimmedTableName.length > 0;
@@ -21,32 +16,41 @@ export function useUpdateRecord({ client, podId, tableName, recordId = null, ena
             ? overrides.recordId.trim()
             : trimmedRecordId;
         if (!isEnabled || nextRecordId.length === 0) {
-            const disabledError = new Error("Record update requires a table and record ID.");
-            setError(disabledError);
             return null;
         }
         setIsSubmitting(true);
         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);
             if (nextRecord) {
-                onSuccess?.(nextRecord, response);
+                onSuccessRef.current?.(nextRecord, response);
             }
             return nextRecord;
         }
         catch (mutationError) {
             const normalized = normalizeError(mutationError, "Failed to update record.");
             setError(normalized);
-            onError?.(mutationError);
+            onErrorRef.current?.(mutationError);
             return null;
         }
         finally {
             setIsSubmitting(false);
         }
-    }, [client, isEnabled, onError, onSuccess, podId, trimmedRecordId, trimmedTableName]);
+    }, [client, isEnabled, podId, trimmedRecordId, trimmedTableName, updateFunctionName, updateVia]);
     const reset = useCallback(() => {
         setUpdatedRecord(null);
         setError(null);

package/dist/react/useWorkflowResume.d.ts

@@ -0,0 +1,18 @@
+import type { LemmaClient } from "../client.js";
+import type { FlowRun, WorkflowRunInputs } from "../types.js";
+export interface UseWorkflowResumeOptions {
+    client: LemmaClient;
+    podId?: string;
+    runId?: string | null;
+    onRun?: (run: FlowRun) => void;
+    onError?: (error: unknown) => void;
+}
+export interface UseWorkflowResumeResult {
+    run: FlowRun | null;
+    isResuming: boolean;
+    error: Error | null;
+    resume: (inputs?: WorkflowRunInputs, options?: {
+        runId?: string | null;
+    }) => Promise<FlowRun>;
+}
+export declare function useWorkflowResume({ client, podId, runId, onRun, onError, }: UseWorkflowResumeOptions): UseWorkflowResumeResult;

package/dist/react/useWorkflowResume.js

@@ -0,0 +1,45 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { normalizeError, resolvePodId } from "./utils.js";
+function resolveRunId(base, override) {
+    const resolved = override ?? base;
+    if (!resolved) {
+        throw new Error("runId is required.");
+    }
+    return resolved;
+}
+export function useWorkflowResume({ client, podId, runId, onRun, onError, }) {
+    const [run, setRun] = useState(null);
+    const [isResuming, setIsResuming] = useState(false);
+    const [error, setError] = useState(null);
+    const onRunRef = useRef(onRun);
+    const onErrorRef = useRef(onError);
+    useEffect(() => { onRunRef.current = onRun; }, [onRun]);
+    useEffect(() => { onErrorRef.current = onError; }, [onError]);
+    const resume = useCallback(async (inputs = {}, options = {}) => {
+        setIsResuming(true);
+        setError(null);
+        try {
+            const resolvedPodId = resolvePodId(client, podId);
+            const resolvedRunId = resolveRunId(runId, options.runId);
+            const nextRun = await client.workflows.runs.resume(resolvedRunId, inputs, resolvedPodId);
+            setRun(nextRun);
+            onRunRef.current?.(nextRun);
+            return nextRun;
+        }
+        catch (resumeError) {
+            const normalized = normalizeError(resumeError, "Failed to resume workflow run.");
+            setError(normalized);
+            onErrorRef.current?.(resumeError);
+            throw normalized;
+        }
+        finally {
+            setIsResuming(false);
+        }
+    }, [client, podId, runId]);
+    return useMemo(() => ({
+        run,
+        isResuming,
+        error,
+        resume,
+    }), [error, isResuming, resume, run]);
+}

package/dist/react/useWorkflowRun.d.ts

@@ -0,0 +1,21 @@
+import type { FlowRun, WorkflowRunInputs } from "../types.js";
+import { type UseFlowSessionOptions, type UseFlowSessionResult } from "./useFlowSession.js";
+export interface UseWorkflowRunOptions extends Omit<UseFlowSessionOptions, "flowName"> {
+    workflowName?: string;
+}
+export interface UseWorkflowRunResult extends Omit<UseFlowSessionResult, "start" | "listHistory"> {
+    output: FlowRun["execution_context"] | null;
+    finalOutput: FlowRun["execution_context"] | null;
+    isWaitingForInput: boolean;
+    isFinished: boolean;
+    start: (inputs?: WorkflowRunInputs, options?: {
+        workflowName?: string;
+        connect?: boolean;
+    }) => Promise<FlowRun>;
+    listRuns: (options?: {
+        workflowName?: string;
+        limit?: number;
+        pageToken?: string;
+    }) => Promise<FlowRun[]>;
+}
+export declare function useWorkflowRun({ workflowName, ...options }: UseWorkflowRunOptions): UseWorkflowRunResult;

package/dist/react/useWorkflowRun.js

@@ -0,0 +1,49 @@
+import { useCallback, useMemo } from "react";
+import { isTerminalFlowStatus, normalizeRunStatus } from "../run-utils.js";
+import { useFlowSession, } from "./useFlowSession.js";
+function resolveWorkflowName(base, override) {
+    const resolved = override ?? base;
+    if (!resolved) {
+        throw new Error("workflowName is required.");
+    }
+    return resolved;
+}
+export function useWorkflowRun({ workflowName, ...options }) {
+    const session = useFlowSession({
+        ...options,
+        flowName: workflowName,
+    });
+    const start = useCallback(async (inputs, startOptions = {}) => {
+        return session.start({
+            flowName: resolveWorkflowName(workflowName, startOptions.workflowName),
+            inputs,
+            connect: startOptions.connect,
+        });
+    }, [session, workflowName]);
+    const listRuns = useCallback(async (listOptions = {}) => {
+        return session.listHistory({
+            flowName: resolveWorkflowName(workflowName, listOptions.workflowName),
+            limit: listOptions.limit,
+            pageToken: listOptions.pageToken,
+        });
+    }, [session, workflowName]);
+    return useMemo(() => {
+        const normalizedStatus = normalizeRunStatus(session.status);
+        const isFinished = isTerminalFlowStatus(normalizedStatus);
+        const isWaitingForInput = normalizedStatus === "WAITING"
+            || !!session.run?.waiting_task_id
+            || !!session.run?.waiting_function_run_id
+            || !!session.run?.waiting_trigger_id;
+        const output = session.run?.execution_context ?? null;
+        const finalOutput = isFinished ? output : null;
+        return {
+            ...session,
+            output,
+            finalOutput,
+            isWaitingForInput,
+            isFinished,
+            start,
+            listRuns,
+        };
+    }, [listRuns, session, start]);
+}

package/dist/react/useWorkflowRuns.d.ts

@@ -0,0 +1,33 @@
+import type { LemmaClient } from "../client.js";
+import type { FlowRun } from "../types.js";
+export interface UseWorkflowRunsOptions {
+    client: LemmaClient;
+    podId?: string;
+    workflowName: string;
+    enabled?: boolean;
+    autoLoad?: boolean;
+    limit?: number;
+    pageToken?: string;
+    initialRunId?: string | null;
+}
+export interface UseWorkflowRunsResult {
+    runs: FlowRun[];
+    total: number;
+    nextPageToken: string | null;
+    selectedRunId: string | null;
+    effectiveSelectedRunId: string | null;
+    selectedRun: FlowRun | null;
+    isLoading: boolean;
+    isLoadingMore: boolean;
+    error: Error | null;
+    selectRun: (runId: string | null) => void;
+    clearSelection: () => void;
+    refresh: (overrides?: {
+        limit?: number;
+        pageToken?: string;
+    }) => Promise<FlowRun[]>;
+    loadMore: (overrides?: {
+        limit?: number;
+    }) => Promise<FlowRun[]>;
+}
+export declare function useWorkflowRuns({ client, podId, workflowName, enabled, autoLoad, limit, pageToken, initialRunId, }: UseWorkflowRunsOptions): UseWorkflowRunsResult;