lemma-sdk 0.2.4 → 0.2.5

package/dist/react/useAssistantRun.js

@@ -1,82 +1,36 @@
-import { useCallback, useRef, useState } from "react";
-import { parseSSEJson, readSSE } from "../streams.js";
+import { useAssistantSession } from "./useAssistantSession.js";
 function requireConversationId(conversationId) {
     if (!conversationId) {
         throw new Error("conversationId is required.");
     }
     return conversationId;
 }
-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;
-}
 export function useAssistantRun({ client, podId, conversationId, onEvent, onError, }) {
-    const [isStreaming, setIsStreaming] = useState(false);
-    const [error, setError] = useState(null);
-    const abortRef = useRef(null);
-    const consume = useCallback(async (stream, controller) => {
-        setIsStreaming(true);
-        setError(null);
-        try {
-            for await (const event of readSSE(stream)) {
-                if (controller.signal.aborted) {
-                    break;
-                }
-                onEvent?.(event, parseSSEJson(event));
-            }
-        }
-        catch (streamError) {
-            if (!(streamError instanceof Error && streamError.name === "AbortError")) {
-                const normalized = streamError instanceof Error
-                    ? streamError
-                    : new Error("Failed to stream assistant run.");
-                setError(normalized);
-                onError?.(streamError);
-            }
-        }
-        finally {
-            if (abortRef.current === controller) {
-                abortRef.current = null;
-            }
-            setIsStreaming(false);
-        }
-    }, [onError, onEvent]);
-    const cancel = useCallback(() => {
-        abortRef.current?.abort();
-        abortRef.current = null;
-    }, []);
-    const sendMessage = useCallback(async (content) => {
-        const id = requireConversationId(conversationId);
-        cancel();
-        const controller = new AbortController();
-        abortRef.current = controller;
-        client.setPodId(resolvePodId(client, podId));
-        const stream = await client.conversations.sendMessageStream(id, { content }, { signal: controller.signal });
-        await consume(stream, controller);
-    }, [cancel, client, consume, conversationId, podId]);
-    const resume = useCallback(async () => {
-        const id = requireConversationId(conversationId);
-        cancel();
-        const controller = new AbortController();
-        abortRef.current = controller;
-        client.setPodId(resolvePodId(client, podId));
-        const stream = await client.conversations.resumeStream(id, { signal: controller.signal });
-        await consume(stream, controller);
-    }, [cancel, client, consume, conversationId, podId]);
-    const stop = useCallback(async () => {
-        const id = requireConversationId(conversationId);
-        client.setPodId(resolvePodId(client, podId));
-        await client.conversations.stopRun(id);
-    }, [client, conversationId, podId]);
+    const session = useAssistantSession({
+        client,
+        podId,
+        conversationId,
+        onEvent,
+        onError,
+    });
+    const sendMessage = async (content) => {
+        await session.sendMessage(content, {
+            conversationId: requireConversationId(conversationId ?? session.conversationId),
+            createIfMissing: false,
+        });
+    };
+    const resume = async () => {
+        await session.resume(requireConversationId(conversationId ?? session.conversationId));
+    };
+    const stop = async () => {
+        await session.stop(requireConversationId(conversationId ?? session.conversationId));
+    };
     return {
-        isStreaming,
-        error,
+        isStreaming: session.isStreaming,
+        error: session.error,
         sendMessage,
         resume,
         stop,
-        cancel,
+        cancel: session.cancel,
     };
 }

package/dist/react/useAssistantRuntime.d.ts

@@ -0,0 +1,13 @@
+import type { ConversationMessage } from "../types.js";
+export interface UseAssistantRuntimeOptions {
+    conversationId?: string | null;
+    sessionMessages?: ConversationMessage[];
+}
+export interface UseAssistantRuntimeResult {
+    runtimeMessages: ConversationMessage[];
+    appendOptimisticUserMessage: (content: string) => ConversationMessage;
+    replaceLoadedMessages: (messages: ConversationMessage[]) => void;
+    mergeMessages: (messages: ConversationMessage[]) => void;
+    clear: () => void;
+}
+export declare function useAssistantRuntime({ conversationId, sessionMessages, }: UseAssistantRuntimeOptions): UseAssistantRuntimeResult;

package/dist/react/useAssistantRuntime.js

@@ -0,0 +1,108 @@
+import { useCallback, useEffect, useState } from "react";
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function messageText(content) {
+    if (typeof content === "string") {
+        return content.trim();
+    }
+    if (isRecord(content)) {
+        if (typeof content.content === "string")
+            return content.content.trim();
+        if (typeof content.text === "string")
+            return content.text.trim();
+    }
+    return "";
+}
+function messageTime(message) {
+    const timestamp = new Date(message.created_at).getTime();
+    return Number.isFinite(timestamp) ? timestamp : 0;
+}
+function isOptimisticId(messageId) {
+    return messageId.startsWith("optimistic-user-");
+}
+function upsertRuntimeMessage(previous, incoming) {
+    const next = [...previous];
+    const directIndex = next.findIndex((message) => message.id === incoming.id);
+    if (directIndex >= 0) {
+        next[directIndex] = incoming;
+        return next;
+    }
+    if (incoming.role === "user") {
+        const incomingText = messageText(incoming.content);
+        if (incomingText) {
+            const optimisticIndex = next.findIndex((message) => (message.role === "user"
+                && isOptimisticId(message.id)
+                && messageText(message.content) === incomingText));
+            if (optimisticIndex >= 0) {
+                next[optimisticIndex] = incoming;
+                return next;
+            }
+        }
+    }
+    next.push(incoming);
+    return next;
+}
+function toRuntimeMessage(message) {
+    return message;
+}
+function buildOptimisticId() {
+    if (typeof globalThis.crypto !== "undefined" && typeof globalThis.crypto.randomUUID === "function") {
+        return `optimistic-user-${globalThis.crypto.randomUUID()}`;
+    }
+    return `optimistic-user-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+}
+export function useAssistantRuntime({ conversationId = null, sessionMessages = [], }) {
+    const [runtimeMessages, setRuntimeMessages] = useState([]);
+    const mergeMessages = useCallback((messages) => {
+        setRuntimeMessages((previous) => {
+            const merged = messages.reduce((accumulator, message) => upsertRuntimeMessage(accumulator, toRuntimeMessage(message)), previous);
+            return [...merged].sort((a, b) => messageTime(a) - messageTime(b));
+        });
+    }, []);
+    const replaceLoadedMessages = useCallback((messages) => {
+        setRuntimeMessages((previous) => {
+            const next = messages.reduce((accumulator, message) => upsertRuntimeMessage(accumulator, toRuntimeMessage(message)), previous);
+            return [...next].sort((a, b) => messageTime(a) - messageTime(b));
+        });
+    }, []);
+    const appendOptimisticUserMessage = useCallback((content) => {
+        const trimmed = content.trim();
+        const optimistic = {
+            id: buildOptimisticId(),
+            role: "user",
+            content: { content: trimmed },
+            created_at: new Date().toISOString(),
+            metadata: null,
+            ...(conversationId ? { conversation_id: conversationId } : {}),
+        };
+        setRuntimeMessages((previous) => {
+            const next = upsertRuntimeMessage(previous, optimistic);
+            return [...next].sort((a, b) => messageTime(a) - messageTime(b));
+        });
+        return optimistic;
+    }, [conversationId]);
+    const clear = useCallback(() => {
+        setRuntimeMessages([]);
+    }, []);
+    useEffect(() => {
+        setRuntimeMessages([]);
+    }, [conversationId]);
+    useEffect(() => {
+        if (sessionMessages.length === 0)
+            return;
+        const normalized = sessionMessages
+            .map((message) => toRuntimeMessage(message))
+            .filter((message) => !conversationId || !message.conversation_id || message.conversation_id === conversationId);
+        if (normalized.length === 0)
+            return;
+        mergeMessages(normalized);
+    }, [conversationId, mergeMessages, sessionMessages]);
+    return {
+        runtimeMessages,
+        appendOptimisticUserMessage,
+        replaceLoadedMessages,
+        mergeMessages,
+        clear,
+    };
+}

package/dist/react/useAssistantSession.d.ts

@@ -0,0 +1,61 @@
+import type { LemmaClient } from "../client.js";
+import { type SseRawEvent } from "../streams.js";
+import type { Conversation, ConversationMessage, ConversationModel, CursorPage } from "../types.js";
+interface ConversationScope {
+    podId?: string | null;
+    assistantId?: string | null;
+    organizationId?: string | null;
+}
+export interface UseAssistantSessionOptions {
+    client: LemmaClient;
+    podId?: string;
+    assistantId?: string;
+    organizationId?: string;
+    conversationId?: string | null;
+    autoLoad?: boolean;
+    onEvent?: (event: SseRawEvent, payload: unknown | null) => void;
+    onStatus?: (status: string) => void;
+    onMessage?: (message: ConversationMessage) => void;
+    onError?: (error: unknown) => void;
+}
+export interface CreateConversationInput {
+    title?: string | null;
+    model?: ConversationModel | null;
+    podId?: string | null;
+    assistantId?: string | null;
+    organizationId?: string | null;
+    setActive?: boolean;
+}
+export interface SendAssistantMessageOptions {
+    conversationId?: string | null;
+    createIfMissing?: boolean;
+    createConversation?: CreateConversationInput;
+}
+export interface UseAssistantSessionResult {
+    conversationId: string | null;
+    conversation: Conversation | null;
+    status?: string;
+    messages: ConversationMessage[];
+    isStreaming: boolean;
+    error: Error | null;
+    setConversationId: (conversationId: string | null) => void;
+    listConversations: (options?: {
+        limit?: number;
+        pageToken?: string;
+        scope?: ConversationScope;
+    }) => Promise<CursorPage<Conversation>>;
+    createConversation: (input?: CreateConversationInput) => Promise<Conversation>;
+    refreshConversation: (conversationId?: string | null) => Promise<Conversation | null>;
+    loadMessages: (options?: {
+        conversationId?: string | null;
+        limit?: number;
+        pageToken?: string;
+    }) => Promise<CursorPage<ConversationMessage>>;
+    sendMessage: (content: string, options?: SendAssistantMessageOptions) => Promise<Conversation>;
+    resume: (conversationId?: string | null) => Promise<void>;
+    stop: (conversationId?: string | null) => Promise<void>;
+    cancel: () => void;
+    clearMessages: () => void;
+}
+export declare function useAssistantSession(options: UseAssistantSessionOptions): UseAssistantSessionResult;
+export {};

package/dist/react/useAssistantSession.js

@@ -0,0 +1,278 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { parseSSEJson, readSSE } from "../streams.js";
+import { parseAssistantStreamEvent, upsertConversationMessage } from "../assistant-events.js";
+function resolveOptionalPodId(client, podId) {
+    return podId ?? client.podId;
+}
+function applyPodScope(client, podId) {
+    const resolvedPodId = resolveOptionalPodId(client, podId);
+    if (resolvedPodId) {
+        client.setPodId(resolvedPodId);
+    }
+    return resolvedPodId;
+}
+function requireConversationId(conversationId) {
+    if (!conversationId) {
+        throw new Error("conversationId is required.");
+    }
+    return conversationId;
+}
+function normalizeError(error, fallback) {
+    if (error instanceof Error)
+        return error;
+    return new Error(fallback);
+}
+function normalizeScope(client, options, override) {
+    return {
+        podId: override?.podId ?? options.podId ?? client.podId ?? null,
+        assistantId: override?.assistantId ?? options.assistantId ?? null,
+        organizationId: override?.organizationId ?? options.organizationId ?? null,
+    };
+}
+export function useAssistantSession(options) {
+    const { client, conversationId: externalConversationId = null, autoLoad = true, onEvent, onStatus, onMessage, onError, } = options;
+    const [conversationId, setConversationIdState] = useState(externalConversationId);
+    const [conversation, setConversation] = useState(null);
+    const [status, setStatus] = useState(undefined);
+    const [messages, setMessages] = useState([]);
+    const [isStreaming, setIsStreaming] = useState(false);
+    const [error, setError] = useState(null);
+    const abortRef = useRef(null);
+    const setConversationId = useCallback((nextConversationId) => {
+        setConversationIdState(nextConversationId);
+        if (!nextConversationId) {
+            setConversation(null);
+            setStatus(undefined);
+            setMessages([]);
+        }
+    }, []);
+    useEffect(() => {
+        setConversationIdState(externalConversationId);
+    }, [externalConversationId]);
+    const cancel = useCallback(() => {
+        abortRef.current?.abort();
+        abortRef.current = null;
+    }, []);
+    const listConversations = useCallback(async (input = {}) => {
+        try {
+            const scope = normalizeScope(client, options, input.scope);
+            applyPodScope(client, scope.podId);
+            const response = await client.conversations.list({
+                pod_id: scope.podId ?? undefined,
+                assistant_id: scope.assistantId ?? undefined,
+                organization_id: scope.organizationId ?? undefined,
+                limit: input.limit,
+                page_token: input.pageToken,
+            });
+            return {
+                items: response.items ?? [],
+                limit: response.limit ?? input.limit ?? 20,
+                next_page_token: response.next_page_token,
+            };
+        }
+        catch (listError) {
+            const normalized = normalizeError(listError, "Failed to list conversations.");
+            setError(normalized);
+            onError?.(listError);
+            return {
+                items: [],
+                limit: input.limit ?? 20,
+                next_page_token: null,
+            };
+        }
+    }, [client, onError, options]);
+    const createConversation = useCallback(async (input = {}) => {
+        applyPodScope(client, input.podId ?? options.podId ?? null);
+        const payload = {
+            title: input.title ?? undefined,
+            pod_id: input.podId ?? options.podId ?? client.podId ?? undefined,
+            assistant_id: input.assistantId ?? options.assistantId ?? undefined,
+            organization_id: input.organizationId ?? options.organizationId ?? undefined,
+            model: typeof input.model === "undefined"
+                ? undefined
+                : input.model,
+        };
+        const created = await client.conversations.create(payload);
+        if (input.setActive !== false) {
+            setConversationIdState(created.id);
+            setConversation(created);
+            setStatus(typeof created.status === "string" ? created.status.toUpperCase() : undefined);
+            setMessages([]);
+        }
+        return created;
+    }, [client, options.assistantId, options.organizationId, options.podId]);
+    const refreshConversation = useCallback(async (explicitConversationId) => {
+        const id = explicitConversationId ?? conversationId;
+        if (!id)
+            return null;
+        try {
+            const scope = normalizeScope(client, options);
+            applyPodScope(client, scope.podId);
+            const nextConversation = await client.conversations.get(id, {
+                pod_id: scope.podId ?? undefined,
+            });
+            setConversation(nextConversation);
+            const nextStatus = typeof nextConversation.status === "string"
+                ? nextConversation.status.toUpperCase()
+                : undefined;
+            setStatus(nextStatus);
+            if (nextStatus) {
+                onStatus?.(nextStatus);
+            }
+            return nextConversation;
+        }
+        catch (refreshError) {
+            const normalized = normalizeError(refreshError, "Failed to fetch conversation.");
+            setError(normalized);
+            onError?.(refreshError);
+            return null;
+        }
+    }, [client, conversationId, onError, onStatus, options]);
+    const loadMessages = useCallback(async (input = {}) => {
+        const id = input.conversationId ?? conversationId;
+        if (!id) {
+            return { items: [], limit: input.limit ?? 20, next_page_token: null };
+        }
+        try {
+            const scope = normalizeScope(client, options);
+            applyPodScope(client, scope.podId);
+            const response = await client.conversations.messages.list(id, {
+                pod_id: scope.podId ?? undefined,
+                limit: input.limit,
+                page_token: input.pageToken,
+            });
+            const nextMessages = response.items ?? [];
+            setMessages(nextMessages);
+            return {
+                items: nextMessages,
+                limit: response.limit ?? input.limit ?? 20,
+                next_page_token: response.next_page_token,
+            };
+        }
+        catch (messageError) {
+            const normalized = normalizeError(messageError, "Failed to fetch conversation messages.");
+            setError(normalized);
+            onError?.(messageError);
+            return {
+                items: [],
+                limit: input.limit ?? 20,
+                next_page_token: null,
+            };
+        }
+    }, [client, conversationId, onError, options]);
+    const consume = useCallback(async (stream, controller) => {
+        setIsStreaming(true);
+        setError(null);
+        try {
+            for await (const event of readSSE(stream)) {
+                if (controller.signal.aborted) {
+                    break;
+                }
+                const payload = parseSSEJson(event);
+                onEvent?.(event, payload);
+                const parsed = parseAssistantStreamEvent(payload);
+                if (parsed.message) {
+                    setMessages((previous) => upsertConversationMessage(previous, parsed.message));
+                    onMessage?.(parsed.message);
+                }
+                if (parsed.status) {
+                    setStatus(parsed.status);
+                    onStatus?.(parsed.status);
+                }
+            }
+        }
+        catch (streamError) {
+            if (!(streamError instanceof Error && streamError.name === "AbortError")) {
+                const normalized = normalizeError(streamError, "Failed to stream assistant run.");
+                setError(normalized);
+                onError?.(streamError);
+            }
+        }
+        finally {
+            if (abortRef.current === controller) {
+                abortRef.current = null;
+            }
+            setIsStreaming(false);
+        }
+    }, [onError, onEvent, onMessage, onStatus]);
+    const ensureConversation = useCallback(async (overrideConversationId, options) => {
+        const existingId = overrideConversationId ?? conversationId;
+        if (existingId) {
+            const existing = await refreshConversation(existingId);
+            if (existing)
+                return existing;
+            throw new Error("Failed to resolve existing conversation.");
+        }
+        if (options?.createIfMissing !== true) {
+            throw new Error("conversationId is required.");
+        }
+        return createConversation({
+            ...(options.createConversation ?? {}),
+            setActive: true,
+        });
+    }, [conversationId, createConversation, refreshConversation]);
+    const sendMessage = useCallback(async (content, input = {}) => {
+        const resolvedConversation = await ensureConversation(input.conversationId, input);
+        const resolvedConversationId = requireConversationId(resolvedConversation.id);
+        cancel();
+        const controller = new AbortController();
+        abortRef.current = controller;
+        const scope = normalizeScope(client, options, input.createConversation);
+        applyPodScope(client, scope.podId);
+        const stream = await client.conversations.sendMessageStream(resolvedConversationId, { content }, {
+            pod_id: scope.podId ?? undefined,
+            signal: controller.signal,
+        });
+        await consume(stream, controller);
+        return resolvedConversation;
+    }, [cancel, client, consume, ensureConversation, options]);
+    const resume = useCallback(async (explicitConversationId) => {
+        const id = requireConversationId(explicitConversationId ?? conversationId);
+        cancel();
+        const controller = new AbortController();
+        abortRef.current = controller;
+        const scope = normalizeScope(client, options);
+        applyPodScope(client, scope.podId);
+        const stream = await client.conversations.resumeStream(id, {
+            pod_id: scope.podId ?? undefined,
+            signal: controller.signal,
+        });
+        await consume(stream, controller);
+    }, [cancel, client, consume, conversationId, options]);
+    const stop = useCallback(async (explicitConversationId) => {
+        const id = requireConversationId(explicitConversationId ?? conversationId);
+        const scope = normalizeScope(client, options);
+        applyPodScope(client, scope.podId);
+        await client.conversations.stopRun(id, {
+            pod_id: scope.podId ?? undefined,
+        });
+    }, [client, conversationId, options]);
+    const clearMessages = useCallback(() => {
+        setMessages([]);
+    }, []);
+    useEffect(() => {
+        if (!autoLoad || !conversationId) {
+            return;
+        }
+        void refreshConversation(conversationId);
+        void loadMessages({ conversationId });
+    }, [autoLoad, conversationId, loadMessages, refreshConversation]);
+    return {
+        conversationId,
+        conversation,
+        status,
+        messages,
+        isStreaming,
+        error,
+        setConversationId,
+        listConversations,
+        createConversation,
+        refreshConversation,
+        loadMessages,
+        sendMessage,
+        resume,
+        stop,
+        cancel,
+        clearMessages,
+    };
+}

package/dist/react/useFlowRunHistory.d.ts

@@ -0,0 +1,19 @@
+import type { FlowRun } from "../types.js";
+import type { UseFlowSessionResult } from "./useFlowSession.js";
+export interface UseFlowRunHistoryOptions {
+    session: Pick<UseFlowSessionResult, "run" | "runId" | "setRunId" | "listHistory">;
+    flowName: string;
+    limit?: number;
+    autoRefresh?: boolean;
+}
+export interface UseFlowRunHistoryResult {
+    runs: FlowRun[];
+    selectedRunId: string | null;
+    effectiveSelectedRunId: string | null;
+    selectedRun: FlowRun | null;
+    isLoading: boolean;
+    error: Error | null;
+    setSelectedRunId: (runId: string | null) => void;
+    refresh: () => Promise<FlowRun[]>;
+}
+export declare function useFlowRunHistory({ session, flowName, limit, autoRefresh, }: UseFlowRunHistoryOptions): UseFlowRunHistoryResult;

package/dist/react/useFlowRunHistory.js

@@ -0,0 +1,77 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+function normalizeError(error, fallback) {
+    if (error instanceof Error)
+        return error;
+    return new Error(fallback);
+}
+export function useFlowRunHistory({ session, flowName, limit = 100, autoRefresh = true, }) {
+    const { listHistory, run: liveRun, runId: liveRunId, setRunId } = session;
+    const [runs, setRuns] = useState([]);
+    const [selectedRunId, setSelectedRunId] = useState(null);
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const effectiveSelectedRunId = selectedRunId ?? runs[0]?.id ?? null;
+    const refresh = useCallback(async () => {
+        setIsLoading(true);
+        setError(null);
+        try {
+            const nextRuns = await listHistory({ flowName, limit });
+            setRuns(nextRuns);
+            setSelectedRunId((previous) => (previous && nextRuns.some((run) => run.id === previous) ? previous : null));
+            return nextRuns;
+        }
+        catch (refreshError) {
+            const normalized = normalizeError(refreshError, "Failed to list flow runs.");
+            setError(normalized);
+            return [];
+        }
+        finally {
+            setIsLoading(false);
+        }
+    }, [flowName, limit, listHistory]);
+    useEffect(() => {
+        if (!autoRefresh)
+            return;
+        void refresh();
+    }, [autoRefresh, flowName, refresh]);
+    useEffect(() => {
+        if (!autoRefresh || !liveRunId)
+            return;
+        void refresh();
+    }, [autoRefresh, liveRunId, refresh]);
+    useEffect(() => {
+        if (!effectiveSelectedRunId)
+            return;
+        setRunId(effectiveSelectedRunId);
+    }, [effectiveSelectedRunId, setRunId]);
+    useEffect(() => {
+        if (!liveRun?.id)
+            return;
+        setRuns((previous) => {
+            const index = previous.findIndex((run) => run.id === liveRun.id);
+            if (index === -1) {
+                return [liveRun, ...previous];
+            }
+            const next = [...previous];
+            next[index] = { ...next[index], ...liveRun };
+            return next;
+        });
+    }, [liveRun]);
+    const selectedRun = useMemo(() => {
+        if (!effectiveSelectedRunId)
+            return null;
+        if (liveRun?.id === effectiveSelectedRunId)
+            return liveRun;
+        return runs.find((run) => run.id === effectiveSelectedRunId) ?? null;
+    }, [effectiveSelectedRunId, liveRun, runs]);
+    return {
+        runs,
+        selectedRunId,
+        effectiveSelectedRunId,
+        selectedRun,
+        isLoading,
+        error,
+        setSelectedRunId,
+        refresh,
+    };
+}