lemma-sdk 0.2.30 → 0.2.32

package/dist/react/useAgentRuns.js

@@ -0,0 +1,149 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { normalizeError, resolvePodClient } from "./utils.js";
+export function useAgentRuns({ client, podId, agentName, enabled = true, autoLoad = true, limit = 100, pageToken, initialTaskId = null, }) {
+    const [runs, setRuns] = useState([]);
+    const [total, setTotal] = useState(0);
+    const [nextPageToken, setNextPageToken] = useState(null);
+    const [selectedTaskId, setSelectedTaskId] = useState(initialTaskId);
+    const [isLoading, setIsLoading] = useState(false);
+    const [isLoadingMore, setIsLoadingMore] = useState(false);
+    const [error, setError] = useState(null);
+    const refresh = useCallback(async (overrides = {}, signal) => {
+        if (!enabled) {
+            setRuns([]);
+            setTotal(0);
+            setNextPageToken(null);
+            setError(null);
+            setIsLoading(false);
+            return [];
+        }
+        setIsLoading(true);
+        setError(null);
+        try {
+            const scopedClient = resolvePodClient(client, podId);
+            const response = await scopedClient.tasks.list({
+                agent_name: agentName,
+                limit: overrides.limit ?? limit,
+                page_token: overrides.pageToken ?? pageToken,
+            });
+            if (signal?.aborted)
+                return [];
+            const nextRuns = response.items ?? [];
+            setRuns(nextRuns);
+            setTotal(response.total ?? nextRuns.length);
+            setNextPageToken(response.next_page_token ?? null);
+            setSelectedTaskId((current) => (current && nextRuns.some((run) => run.id === current) ? current : initialTaskId));
+            return nextRuns;
+        }
+        catch (refreshError) {
+            if (signal?.aborted)
+                return [];
+            const normalized = normalizeError(refreshError, "Failed to load agent runs.");
+            setError(normalized);
+            return [];
+        }
+        finally {
+            if (!signal?.aborted)
+                setIsLoading(false);
+        }
+    }, [agentName, client, enabled, initialTaskId, 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.tasks.list({
+                agent_name: agentName,
+                limit: overrides.limit ?? limit,
+                page_token: nextPageToken,
+            });
+            const moreRuns = response.items ?? [];
+            setRuns((previous) => [...previous, ...moreRuns]);
+            setTotal(response.total ?? runs.length + moreRuns.length);
+            setNextPageToken(response.next_page_token ?? null);
+            return moreRuns;
+        }
+        catch (loadError) {
+            const normalized = normalizeError(loadError, "Failed to load more agent runs.");
+            setError(normalized);
+            return [];
+        }
+        finally {
+            setIsLoadingMore(false);
+        }
+    }, [agentName, client, enabled, isLoading, isLoadingMore, limit, nextPageToken, podId]);
+    useEffect(() => {
+        setSelectedTaskId(initialTaskId);
+    }, [initialTaskId]);
+    useEffect(() => {
+        if (!enabled) {
+            setRuns([]);
+            setTotal(0);
+            setNextPageToken(null);
+            setError(null);
+            setIsLoading(false);
+            setIsLoadingMore(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 agent runs."), "Failed to load agent runs."));
+                }
+            }
+        })();
+        return () => {
+            cancelled = true;
+            controller.abort();
+        };
+    }, [autoLoad, enabled, refresh]);
+    const selectRun = useCallback((taskId) => {
+        setSelectedTaskId(taskId);
+    }, []);
+    const clearSelection = useCallback(() => {
+        setSelectedTaskId(null);
+    }, []);
+    return useMemo(() => {
+        const effectiveSelectedTaskId = selectedTaskId ?? runs[0]?.id ?? null;
+        const selectedRun = effectiveSelectedTaskId
+            ? runs.find((run) => run.id === effectiveSelectedTaskId) ?? null
+            : null;
+        return {
+            runs,
+            total,
+            nextPageToken,
+            selectedTaskId,
+            effectiveSelectedTaskId,
+            selectedRun,
+            isLoading,
+            isLoadingMore,
+            error,
+            selectRun,
+            clearSelection,
+            refresh,
+            loadMore,
+        };
+    }, [
+        clearSelection,
+        error,
+        isLoading,
+        isLoadingMore,
+        loadMore,
+        nextPageToken,
+        refresh,
+        runs,
+        selectRun,
+        selectedTaskId,
+        total,
+    ]);
+}

package/dist/react/useAssistantRun.js

@@ -1,3 +1,4 @@
+import { useCallback, useMemo } from "react";
 import { useConversationMessages } from "./useConversationMessages.js";
 function requireConversationId(conversationId) {
     if (!conversationId) {
@@ -15,19 +16,19 @@ export function useAssistantRun({ client, podId, conversationId, onEvent, onErro
         onEvent,
         onError,
     });
-    const sendMessage = async (content) => {
+    const sendMessage = useCallback(async (content) => {
         await messages.sendMessage(content, {
             conversationId: requireConversationId(conversationId ?? messages.conversationId),
             createIfMissing: false,
         });
-    };
-    const resume = async () => {
+    }, [conversationId, messages]);
+    const resume = useCallback(async () => {
         await messages.resume(requireConversationId(conversationId ?? messages.conversationId));
-    };
-    const stop = async () => {
+    }, [conversationId, messages]);
+    const stop = useCallback(async () => {
         await messages.stop(requireConversationId(conversationId ?? messages.conversationId));
-    };
-    return {
+    }, [conversationId, messages]);
+    return useMemo(() => ({
         isStreaming: messages.isStreaming,
         error: messages.error,
         status: messages.status,
@@ -37,10 +38,10 @@ export function useAssistantRun({ client, podId, conversationId, onEvent, onErro
         finalOutput: messages.finalOutput,
         finalOutputText: messages.finalOutputText,
         latestAssistantMessage: messages.latestAssistantMessage,
-        refresh: () => messages.refresh(),
+        refresh: messages.refresh,
         sendMessage,
         resume,
         stop,
         cancel: messages.cancel,
-    };
+    }), [messages, sendMessage, resume, stop]);
 }

package/dist/react/useAssistantSession.js

@@ -2,15 +2,13 @@ import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { parseSSEJson, readSSE } from "../streams.js";
 import { parseAssistantStreamEvent, upsertConversationMessage } from "../assistant-events.js";
 import { extractConversationMessageText, getLatestAssistantMessage, } from "./assistant-output.js";
-function resolveOptionalPodId(client, podId) {
-    return podId ?? client.podId;
-}
+import { normalizeError } from "./utils.js";
 function applyPodScope(client, podId) {
-    const resolvedPodId = resolveOptionalPodId(client, podId);
-    if (resolvedPodId) {
-        client.setPodId(resolvedPodId);
+    const resolvedPodId = podId ?? client.podId;
+    if (resolvedPodId && resolvedPodId !== client.podId) {
+        return client.withPod(resolvedPodId);
     }
-    return resolvedPodId;
+    return client;
 }
 function requireConversationId(conversationId) {
     if (!conversationId) {
@@ -18,11 +16,6 @@ function requireConversationId(conversationId) {
     }
     return conversationId;
 }
-function normalizeError(error, fallback) {
-    if (error instanceof Error)
-        return error;
-    return new Error(fallback);
-}
 function normalizeScope(client, defaults, override) {
     const resolvedAssistantName = override?.assistantName
         ?? override?.assistantId
@@ -144,8 +137,8 @@ export function useAssistantSession(options) {
         setError(null);
         try {
             const scope = normalizeScope(client, defaultScope, input.scope);
-            applyPodScope(client, scope.podId);
-            const response = await client.conversations.list({
+            const scopedClient = applyPodScope(client, scope.podId);
+            const response = await scopedClient.conversations.list({
                 pod_id: scope.podId ?? undefined,
                 assistant_name: scope.assistantName ?? scope.assistantId ?? undefined,
                 organization_id: scope.organizationId ?? undefined,
@@ -156,6 +149,7 @@ export function useAssistantSession(options) {
                 items: response.items ?? [],
                 limit: response.limit ?? input.limit ?? 20,
                 next_page_token: response.next_page_token,
+                total: response.total,
             };
         }
         catch (listError) {
@@ -172,10 +166,10 @@ export function useAssistantSession(options) {
     const createConversation = useCallback(async (input = {}) => {
         setError(null);
         try {
-            applyPodScope(client, input.podId ?? defaultPodId ?? null);
+            const scopedClient = applyPodScope(client, input.podId ?? defaultPodId ?? null);
             const payload = {
                 title: input.title ?? undefined,
-                pod_id: input.podId ?? defaultPodId ?? client.podId ?? undefined,
+                pod_id: input.podId ?? defaultPodId ?? scopedClient.podId ?? undefined,
                 assistant_name: input.assistantName
                     ?? input.assistantId
                     ?? defaultAssistantName
@@ -186,7 +180,7 @@ export function useAssistantSession(options) {
                     ? undefined
                     : input.model,
             };
-            const created = await client.conversations.create(payload);
+            const created = await scopedClient.conversations.create(payload);
             if (input.setActive !== false) {
                 setConversationIdState(created.id);
                 setConversation(created);
@@ -219,8 +213,8 @@ export function useAssistantSession(options) {
         setError(null);
         try {
             const scope = normalizeScope(client, defaultScope);
-            applyPodScope(client, scope.podId);
-            const nextConversation = await client.conversations.get(id, {
+            const scopedClient = applyPodScope(client, scope.podId);
+            const nextConversation = await scopedClient.conversations.get(id, {
                 pod_id: scope.podId ?? undefined,
             });
             setConversation(nextConversation);
@@ -372,8 +366,8 @@ export function useAssistantSession(options) {
             const controller = new AbortController();
             abortRef.current = controller;
             const scope = normalizeScope(client, defaultScope, input.createConversation);
-            applyPodScope(client, scope.podId);
-            const stream = await client.conversations.sendMessageStream(resolvedConversationId, { content }, {
+            const scopedClient = applyPodScope(client, scope.podId);
+            const stream = await scopedClient.conversations.sendMessageStream(resolvedConversationId, { content }, {
                 pod_id: scope.podId ?? undefined,
                 signal: controller.signal,
             });
@@ -405,8 +399,8 @@ export function useAssistantSession(options) {
             const controller = new AbortController();
             abortRef.current = controller;
             const scope = normalizeScope(client, defaultScope);
-            applyPodScope(client, scope.podId);
-            const stream = await client.conversations.resumeStream(id, {
+            const scopedClient = applyPodScope(client, scope.podId);
+            const stream = await scopedClient.conversations.resumeStream(id, {
                 pod_id: scope.podId ?? undefined,
                 signal: controller.signal,
             });
@@ -464,8 +458,8 @@ export function useAssistantSession(options) {
         try {
             const id = requireConversationId(explicitConversationId ?? conversationId);
             const scope = normalizeScope(client, defaultScope);
-            applyPodScope(client, scope.podId);
-            await client.conversations.stopRun(id, {
+            const scopedClient = applyPodScope(client, scope.podId);
+            await scopedClient.conversations.stopRun(id, {
                 pod_id: scope.podId ?? undefined,
             });
             setConversationStatus("WAITING");
@@ -493,6 +487,7 @@ export function useAssistantSession(options) {
         if (!autoLoad || !conversationId) {
             return;
         }
+        const controller = new AbortController();
         let cancelled = false;
         const bootstrapConversation = async () => {
             const latestConversation = await refreshConversation(conversationId);
@@ -511,6 +506,7 @@ export function useAssistantSession(options) {
         void bootstrapConversation();
         return () => {
             cancelled = true;
+            controller.abort();
         };
     }, [autoLoad, autoResume, conversationId, loadMessages, refreshConversation, resumeIfRunning]);
     const latestAssistantMessage = useMemo(() => getLatestAssistantMessage(messages), [messages]);

package/dist/react/useBulkRecords.js

@@ -1,24 +1,17 @@
-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);
-}
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { normalizeError, resolvePodClient } from "./utils.js";
 export function useBulkRecords({ client, podId, tableName, enabled = true, onSuccess, onError, }) {
     const [isSubmitting, setIsSubmitting] = useState(false);
     const [error, setError] = useState(null);
     const [lastMessage, setLastMessage] = 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 isEnabled = enabled && trimmedTableName.length > 0;
     const runBulkOperation = useCallback(async (action, fallbackError) => {
         if (!isEnabled) {
-            const disabledError = new Error("Bulk record operations are disabled.");
-            setError(disabledError);
             return null;
         }
         setIsSubmitting(true);
@@ -27,19 +20,19 @@ export function useBulkRecords({ client, podId, tableName, enabled = true, onSuc
             const scopedClient = resolvePodClient(client, podId);
             const response = await action(scopedClient);
             setLastMessage(response.message ?? null);
-            onSuccess?.(response);
+            onSuccessRef.current?.(response);
             return response;
         }
         catch (mutationError) {
             const normalized = normalizeError(mutationError, fallbackError);
             setError(normalized);
-            onError?.(mutationError);
+            onErrorRef.current?.(mutationError);
             return null;
         }
         finally {
             setIsSubmitting(false);
         }
-    }, [client, isEnabled, onError, onSuccess, podId]);
+    }, [client, isEnabled, podId]);
     const createMany = useCallback(async (records) => {
         if (records.length === 0)
             return null;

package/dist/react/useConversation.js

@@ -1,16 +1,12 @@
 import { useCallback, useEffect, useMemo, useState } from "react";
-function normalizeError(error, fallback) {
-    if (error instanceof Error)
-        return error;
-    return new Error(fallback);
-}
+import { normalizeError } from "./utils.js";
 export function useConversation({ client, podId, conversationId = null, enabled = true, autoLoad = true, }) {
     const [conversation, setConversation] = useState(null);
     const [isLoading, setIsLoading] = useState(false);
     const [error, setError] = useState(null);
     const trimmedConversationId = typeof conversationId === "string" ? conversationId.trim() : "";
     const isEnabled = enabled && trimmedConversationId.length > 0;
-    const refresh = useCallback(async (overrides = {}) => {
+    const refresh = useCallback(async (overrides = {}, signal) => {
         const nextConversationId = typeof overrides.conversationId === "string"
             ? overrides.conversationId.trim()
             : trimmedConversationId;
@@ -27,16 +23,21 @@ export function useConversation({ client, podId, conversationId = null, enabled
             const nextConversation = await scopedClient.conversations.get(nextConversationId, {
                 pod_id: podId,
             });
+            if (signal?.aborted)
+                return null;
             setConversation(nextConversation);
             return nextConversation;
         }
         catch (refreshError) {
+            if (signal?.aborted)
+                return null;
             const normalized = normalizeError(refreshError, "Failed to load conversation.");
             setError(normalized);
             return null;
         }
         finally {
-            setIsLoading(false);
+            if (!signal?.aborted)
+                setIsLoading(false);
         }
     }, [client, enabled, podId, trimmedConversationId]);
     useEffect(() => {
@@ -48,7 +49,22 @@ export function useConversation({ client, podId, conversationId = null, enabled
         }
         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 conversation."), "Failed to load conversation."));
+                }
+            }
+        })();
+        return () => {
+            cancelled = true;
+            controller.abort();
+        };
     }, [autoLoad, isEnabled, refresh]);
     return useMemo(() => ({
         conversation,

package/dist/react/useConversations.d.ts

@@ -33,6 +33,7 @@ export interface UseConversationsResult {
     effectiveSelectedConversationId: string | null;
     selectedConversation: Conversation | null;
     isLoading: boolean;
+    isLoadingMore: boolean;
     error: Error | null;
     selectConversation: (conversationId: string | null) => void;
     clearSelection: () => void;
@@ -41,6 +42,9 @@ export interface UseConversationsResult {
         limit?: number;
         pageToken?: string;
     }) => Promise<Conversation[]>;
+    loadMore: (overrides?: {
+        limit?: number;
+    }) => Promise<Conversation[]>;
     createConversation: (input?: CreateConversationInput) => Promise<Conversation>;
     createAndSelectConversation: (input?: Omit<CreateConversationInput, "setActive">) => Promise<Conversation>;
     ensureConversation: (input?: Omit<CreateConversationInput, "setActive">) => Promise<Conversation>;

package/dist/react/useConversations.js

@@ -1,5 +1,6 @@
 import { useCallback, useEffect, useMemo, useState } from "react";
 import { useAssistantSession, } from "./useAssistantSession.js";
+import { normalizeError } from "./utils.js";
 function sortConversationsByUpdatedAt(conversations) {
     return [...conversations].sort((a, b) => {
         const aTime = new Date(a.updated_at || a.created_at).getTime();
@@ -13,6 +14,7 @@ export function useConversations({ client, podId, assistantName, assistantId, or
     const [nextPageToken, setNextPageToken] = useState(null);
     const [selectedConversationId, setSelectedConversationId] = useState(initialConversationId);
     const [isLoading, setIsLoading] = useState(false);
+    const [isLoadingMore, setIsLoadingMore] = useState(false);
     const scopeKey = useMemo(() => JSON.stringify({
         podId: podId ?? null,
         assistantName: assistantName ?? assistantId ?? null,
@@ -43,7 +45,7 @@ export function useConversations({ client, podId, assistantName, assistantId, or
             });
             const nextConversations = sortConversationsByUpdatedAt(response.items ?? []);
             setConversations(nextConversations);
-            setTotal(nextConversations.length);
+            setTotal(response.total ?? nextConversations.length);
             setNextPageToken(response.next_page_token ?? null);
             setSelectedConversationId((current) => {
                 if (current)
@@ -60,6 +62,30 @@ export function useConversations({ client, podId, assistantName, assistantId, or
             setIsLoading(false);
         }
     }, [autoSelectFirst, enabled, initialConversationId, limit, listConversations, pageToken]);
+    const loadMore = useCallback(async (overrides = {}) => {
+        if (!enabled || !nextPageToken || isLoading || isLoadingMore) {
+            return [];
+        }
+        setIsLoadingMore(true);
+        try {
+            const response = await listConversations({
+                limit: overrides.limit ?? limit,
+                pageToken: nextPageToken,
+            });
+            const moreConversations = sortConversationsByUpdatedAt(response.items ?? []);
+            setConversations((previous) => [...previous, ...moreConversations]);
+            setTotal(response.total ?? conversations.length + moreConversations.length);
+            setNextPageToken(response.next_page_token ?? null);
+            return moreConversations;
+        }
+        catch (loadError) {
+            const normalized = normalizeError(loadError, "Failed to load more conversations.");
+            throw normalized;
+        }
+        finally {
+            setIsLoadingMore(false);
+        }
+    }, [conversations.length, enabled, isLoading, isLoadingMore, limit, listConversations, nextPageToken]);
     const createConversation = useCallback(async (input = {}) => {
         const createdConversation = await sessionCreateConversation({
             ...input,
@@ -108,6 +134,7 @@ export function useConversations({ client, podId, assistantName, assistantId, or
             setNextPageToken(null);
             setSelectedConversationId(initialConversationId);
             setIsLoading(false);
+            setIsLoadingMore(false);
             return;
         }
         setConversations([]);
@@ -116,7 +143,22 @@ export function useConversations({ client, podId, assistantName, assistantId, or
         setSelectedConversationId(initialConversationId);
         if (!autoLoad)
             return;
-        void refresh();
+        const controller = new AbortController();
+        let cancelled = false;
+        (async () => {
+            try {
+                await refresh();
+            }
+            catch {
+                if (!cancelled) {
+                    // refresh handles errors internally
+                }
+            }
+        })();
+        return () => {
+            cancelled = true;
+            controller.abort();
+        };
     }, [autoLoad, enabled, initialConversationId, refresh, scopeKey]);
     const effectiveSelectedConversationId = useMemo(() => {
         if (selectedConversationId)
@@ -154,11 +196,13 @@ export function useConversations({ client, podId, assistantName, assistantId, or
         effectiveSelectedConversationId,
         selectedConversation,
         isLoading,
+        isLoadingMore,
         error,
         selectConversation,
         clearSelection,
         selectLatestConversation,
         refresh,
+        loadMore,
         createConversation,
         createAndSelectConversation,
         ensureConversation,
@@ -168,7 +212,10 @@ export function useConversations({ client, podId, assistantName, assistantId, or
         createAndSelectConversation,
         createConversation,
         effectiveSelectedConversationId,
+        error,
         isLoading,
+        isLoadingMore,
+        loadMore,
         nextPageToken,
         refresh,
         ensureConversation,
@@ -176,7 +223,6 @@ export function useConversations({ client, podId, assistantName, assistantId, or
         selectLatestConversation,
         selectedConversation,
         selectedConversationId,
-        error,
         total,
     ]);
 }

package/dist/react/useCreateRecord.d.ts

@@ -1,11 +1,41 @@
 import type { LemmaClient } from "../client.js";
-import type { RecordResponse } from "../types.js";
+import type { FunctionRun, RecordResponse } from "../types.js";
+/**
+ * React hook for creating a single record. Manages loading/error state and
+ * exposes a `create` function you can call from event handlers.
+ *
+ * Supports two modes:
+ * - `"direct"` (default): calls `records.create` directly.
+ * - `"function"`: calls `functions.runs.create`, routing the create through
+ *   a pod function that may enforce business logic.
+ *
+ * @example Direct create
+ * ```tsx
+ * const { create, isSubmitting } = useCreateRecord({ client, tableName: "comments" });
+ * await create({ body: "Hello", issue_id: "123" });
+ * ```
+ *
+ * @example Function-backed create
+ * ```tsx
+ * const { create, isSubmitting } = useCreateRecord({
+ *   client,
+ *   tableName: "issues",
+ *   createVia: "function",
+ *   createFunctionName: "create-issue",
+ * });
+ * await create({ title: "Bug", team_id: "team_1" });
+ * ```
+ */
 export interface UseCreateRecordOptions {
     client: LemmaClient;
     podId?: string;
     tableName: string;
     enabled?: boolean;
-    onSuccess?: (record: Record<string, unknown>, response: RecordResponse) => void;
+    /** How the record is created. `"direct"` calls `records.create`. `"function"` calls `functions.runs.create`. */
+    createVia?: "direct" | "function";
+    /** Function name to run when `createVia` is `"function"`. Falls back to `tableName` if omitted. */
+    createFunctionName?: string;
+    onSuccess?: (record: Record<string, unknown>, response: RecordResponse | FunctionRun) => void;
     onError?: (error: unknown) => void;
 }
 export interface UseCreateRecordResult<TRecord extends Record<string, unknown> = Record<string, unknown>> {
@@ -15,4 +45,4 @@ export interface UseCreateRecordResult<TRecord extends Record<string, unknown> =
     create: (data: Record<string, unknown>) => Promise<TRecord | null>;
     reset: () => void;
 }
-export declare function useCreateRecord<TRecord extends Record<string, unknown> = Record<string, unknown>>({ client, podId, tableName, enabled, onSuccess, onError, }: UseCreateRecordOptions): UseCreateRecordResult<TRecord>;
+export declare function useCreateRecord<TRecord extends Record<string, unknown> = Record<string, unknown>>({ client, podId, tableName, enabled, createVia, createFunctionName, onSuccess, onError, }: UseCreateRecordOptions): UseCreateRecordResult<TRecord>;