lemma-sdk 0.2.28 → 0.2.31

package/dist/react/useConversation.js

@@ -0,0 +1,75 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+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 = {}, signal) => {
+        const nextConversationId = typeof overrides.conversationId === "string"
+            ? overrides.conversationId.trim()
+            : trimmedConversationId;
+        if (!enabled || nextConversationId.length === 0) {
+            setConversation(null);
+            setError(null);
+            setIsLoading(false);
+            return null;
+        }
+        setIsLoading(true);
+        setError(null);
+        try {
+            const scopedClient = podId ? client.withPod(podId) : client;
+            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 {
+            if (!signal?.aborted)
+                setIsLoading(false);
+        }
+    }, [client, enabled, podId, trimmedConversationId]);
+    useEffect(() => {
+        if (!isEnabled) {
+            setConversation(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 conversation."), "Failed to load conversation."));
+                }
+            }
+        })();
+        return () => {
+            cancelled = true;
+            controller.abort();
+        };
+    }, [autoLoad, isEnabled, refresh]);
+    return useMemo(() => ({
+        conversation,
+        isLoading,
+        error,
+        refresh,
+    }), [conversation, error, isLoading, refresh]);
+}

package/dist/react/useConversationMessages.d.ts

@@ -0,0 +1,59 @@
+import type { LemmaClient } from "../client.js";
+import type { SseRawEvent } from "../streams.js";
+import type { Conversation, ConversationMessage } from "../types.js";
+import { type CreateConversationInput, type ResumeAssistantOptions, type SendAssistantMessageOptions } from "./useAssistantSession.js";
+export interface UseConversationMessagesOptions {
+    client: LemmaClient;
+    podId?: string;
+    assistantName?: string;
+    /**
+     * @deprecated Use assistantName instead.
+     */
+    assistantId?: string;
+    organizationId?: string;
+    conversationId?: string | null;
+    enabled?: boolean;
+    autoLoad?: boolean;
+    autoResume?: boolean;
+    limit?: number;
+    syncOnTurnEnd?: boolean;
+    onEvent?: (event: SseRawEvent, payload: unknown | null) => void;
+    onStatus?: (status: string) => void;
+    onMessage?: (message: ConversationMessage) => void;
+    onError?: (error: unknown) => void;
+}
+export interface UseConversationMessagesResult {
+    conversationId: string | null;
+    conversation: Conversation | null;
+    messages: ConversationMessage[];
+    status?: string;
+    isRunning: boolean;
+    isStreaming: boolean;
+    isLoading: boolean;
+    isLoadingOlder: boolean;
+    hasOlderMessages: boolean;
+    nextPageToken: string | null;
+    streamingText: string;
+    latestAssistantMessage: ConversationMessage | null;
+    output: ConversationMessage["content"] | null;
+    outputText: string;
+    finalOutput: ConversationMessage["content"] | null;
+    finalOutputText: string;
+    error: Error | null;
+    refresh: (options?: {
+        conversationId?: string | null;
+        limit?: number;
+        pageToken?: string;
+    }) => Promise<ConversationMessage[]>;
+    loadOlder: (options?: {
+        limit?: number;
+    }) => Promise<ConversationMessage[]>;
+    sendMessage: (content: string, options?: SendAssistantMessageOptions) => Promise<Conversation>;
+    resume: (conversationId?: string | null | ResumeAssistantOptions) => Promise<void>;
+    resumeIfRunning: (conversationId?: string | null) => Promise<boolean>;
+    stop: (conversationId?: string | null) => Promise<void>;
+    cancel: () => void;
+    clearMessages: () => void;
+    createConversation: (input?: CreateConversationInput) => Promise<Conversation>;
+}
+export declare function useConversationMessages({ client, podId, assistantName, assistantId, organizationId, conversationId, enabled, autoLoad, autoResume, limit, syncOnTurnEnd, onEvent, onStatus, onMessage, onError, }: UseConversationMessagesOptions): UseConversationMessagesResult;

package/dist/react/useConversationMessages.js

@@ -0,0 +1,167 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { extractConversationMessageText, getLatestAssistantMessage, isConversationRunningStatus, normalizeConversationStatus, sortConversationMessagesByCreatedAt, } from "./assistant-output.js";
+import { useAssistantSession, } from "./useAssistantSession.js";
+function resolveConversationId(preferred, fallback) {
+    return preferred ?? fallback ?? null;
+}
+function isSettledStatus(status, isStreaming) {
+    if (isStreaming)
+        return false;
+    const normalized = normalizeConversationStatus(status);
+    if (!normalized)
+        return true;
+    return !isConversationRunningStatus(normalized);
+}
+export function useConversationMessages({ client, podId, assistantName, assistantId, organizationId, conversationId = null, enabled = true, autoLoad = true, autoResume = false, limit = 100, syncOnTurnEnd = false, onEvent, onStatus, onMessage, onError, }) {
+    const [nextPageToken, setNextPageToken] = useState(null);
+    const [isLoading, setIsLoading] = useState(false);
+    const [isLoadingOlder, setIsLoadingOlder] = useState(false);
+    const { conversation: sessionConversation, conversationId: sessionConversationId, messages: sessionMessages, status, streamingText, isStreaming, error, refreshConversation, loadMessages, sendMessage, resume, resumeIfRunning, stop, cancel, clearMessages: clearSessionMessages, createConversation, } = useAssistantSession({
+        client,
+        podId,
+        assistantName,
+        assistantId,
+        organizationId,
+        conversationId: conversationId ?? undefined,
+        autoLoad: false,
+        autoResume: false,
+        syncOnTurnEnd,
+        onEvent,
+        onStatus,
+        onMessage,
+        onError,
+    });
+    const refresh = useCallback(async (options = {}) => {
+        const targetConversationId = resolveConversationId(options.conversationId, sessionConversationId);
+        if (!enabled || !targetConversationId) {
+            setNextPageToken(null);
+            setIsLoading(false);
+            return [];
+        }
+        setIsLoading(true);
+        try {
+            await refreshConversation(targetConversationId);
+            const response = await loadMessages({
+                conversationId: targetConversationId,
+                limit: options.limit ?? limit,
+                pageToken: options.pageToken,
+            });
+            setNextPageToken(response.next_page_token ?? null);
+            return sortConversationMessagesByCreatedAt(response.items ?? []);
+        }
+        finally {
+            setIsLoading(false);
+        }
+    }, [enabled, limit, loadMessages, refreshConversation, sessionConversationId]);
+    const loadOlder = useCallback(async (options = {}) => {
+        const targetConversationId = sessionConversationId;
+        if (!enabled || !targetConversationId || !nextPageToken || isLoading || isLoadingOlder) {
+            return [];
+        }
+        setIsLoadingOlder(true);
+        try {
+            const response = await loadMessages({
+                conversationId: targetConversationId,
+                limit: options.limit ?? limit,
+                pageToken: nextPageToken,
+            });
+            setNextPageToken(response.next_page_token ?? null);
+            return sortConversationMessagesByCreatedAt(response.items ?? []);
+        }
+        finally {
+            setIsLoadingOlder(false);
+        }
+    }, [enabled, isLoading, isLoadingOlder, limit, loadMessages, nextPageToken, sessionConversationId]);
+    useEffect(() => {
+        if (!enabled || !conversationId) {
+            setNextPageToken(null);
+            setIsLoading(false);
+            setIsLoadingOlder(false);
+            cancel();
+            clearSessionMessages();
+            return;
+        }
+        setNextPageToken(null);
+        if (!autoLoad)
+            return;
+        let cancelled = false;
+        const bootstrap = async () => {
+            await refresh({ conversationId, limit });
+            if (cancelled || !autoResume)
+                return;
+            await resumeIfRunning(conversationId);
+        };
+        void bootstrap();
+        return () => {
+            cancelled = true;
+        };
+    }, [autoLoad, autoResume, cancel, clearSessionMessages, conversationId, enabled, limit, refresh, resumeIfRunning]);
+    const messages = useMemo(() => sortConversationMessagesByCreatedAt(sessionMessages), [sessionMessages]);
+    const latestAssistantMessage = useMemo(() => getLatestAssistantMessage(messages), [messages]);
+    const output = latestAssistantMessage?.content ?? null;
+    const latestAssistantText = latestAssistantMessage
+        ? extractConversationMessageText(latestAssistantMessage.content)
+        : "";
+    const outputText = streamingText.trim() || latestAssistantText;
+    const finalOutput = isSettledStatus(status, isStreaming) ? output : null;
+    const finalOutputText = isSettledStatus(status, isStreaming) ? latestAssistantText : "";
+    const isRunning = isConversationRunningStatus(status) || isStreaming;
+    const clearMessages = useCallback(() => {
+        clearSessionMessages();
+        setNextPageToken(null);
+    }, [clearSessionMessages]);
+    return useMemo(() => ({
+        conversationId: sessionConversationId,
+        conversation: sessionConversation,
+        messages,
+        status,
+        isRunning,
+        isStreaming,
+        isLoading,
+        isLoadingOlder,
+        hasOlderMessages: !!nextPageToken,
+        nextPageToken,
+        streamingText,
+        latestAssistantMessage,
+        output,
+        outputText,
+        finalOutput,
+        finalOutputText,
+        error,
+        refresh,
+        loadOlder,
+        sendMessage,
+        resume,
+        resumeIfRunning,
+        stop,
+        cancel,
+        clearMessages,
+        createConversation,
+    }), [
+        cancel,
+        clearMessages,
+        createConversation,
+        error,
+        finalOutput,
+        finalOutputText,
+        isLoading,
+        isLoadingOlder,
+        isRunning,
+        isStreaming,
+        latestAssistantMessage,
+        loadOlder,
+        messages,
+        nextPageToken,
+        output,
+        outputText,
+        refresh,
+        resume,
+        resumeIfRunning,
+        sendMessage,
+        sessionConversation,
+        sessionConversationId,
+        status,
+        stop,
+        streamingText,
+    ]);
+}

package/dist/react/useConversations.d.ts

@@ -0,0 +1,52 @@
+import type { LemmaClient } from "../client.js";
+import type { Conversation } from "../types.js";
+import { type CreateConversationInput } from "./useAssistantSession.js";
+export interface UseConversationsOptions {
+    client: LemmaClient;
+    podId?: string;
+    assistantName?: string;
+    /**
+     * @deprecated Use assistantName instead.
+     */
+    assistantId?: string;
+    organizationId?: string;
+    enabled?: boolean;
+    autoLoad?: boolean;
+    autoSelectFirst?: boolean;
+    limit?: number;
+    pageToken?: string;
+    initialConversationId?: string | null;
+}
+export interface UseConversationsResult {
+    conversations: Conversation[];
+    total: number;
+    nextPageToken: string | null;
+    /**
+     * @deprecated Use selectedConversationId instead.
+     */
+    activeConversationId: string | null;
+    /**
+     * @deprecated Use selectedConversation instead.
+     */
+    activeConversation: Conversation | null;
+    selectedConversationId: string | null;
+    effectiveSelectedConversationId: string | null;
+    selectedConversation: Conversation | null;
+    isLoading: boolean;
+    isLoadingMore: boolean;
+    error: Error | null;
+    selectConversation: (conversationId: string | null) => void;
+    clearSelection: () => void;
+    selectLatestConversation: () => string | null;
+    refresh: (overrides?: {
+        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>;
+}
+export declare function useConversations({ client, podId, assistantName, assistantId, organizationId, enabled, autoLoad, autoSelectFirst, limit, pageToken, initialConversationId, }: UseConversationsOptions): UseConversationsResult;

package/dist/react/useConversations.js

@@ -0,0 +1,228 @@
+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();
+        const bTime = new Date(b.updated_at || b.created_at).getTime();
+        return bTime - aTime;
+    });
+}
+export function useConversations({ client, podId, assistantName, assistantId, organizationId, enabled = true, autoLoad = true, autoSelectFirst = true, limit = 20, pageToken, initialConversationId = null, }) {
+    const [conversations, setConversations] = useState([]);
+    const [total, setTotal] = useState(0);
+    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,
+        assistantId: assistantId ?? null,
+        organizationId: organizationId ?? null,
+    }), [assistantId, assistantName, organizationId, podId]);
+    const { error, listConversations, createConversation: sessionCreateConversation, } = useAssistantSession({
+        client,
+        podId,
+        assistantName,
+        assistantId,
+        organizationId,
+        autoLoad: false,
+    });
+    const refresh = useCallback(async (overrides = {}) => {
+        if (!enabled) {
+            setConversations([]);
+            setTotal(0);
+            setNextPageToken(null);
+            setIsLoading(false);
+            return [];
+        }
+        setIsLoading(true);
+        try {
+            const response = await listConversations({
+                limit: overrides.limit ?? limit,
+                pageToken: overrides.pageToken ?? pageToken,
+            });
+            const nextConversations = sortConversationsByUpdatedAt(response.items ?? []);
+            setConversations(nextConversations);
+            setTotal(response.total ?? nextConversations.length);
+            setNextPageToken(response.next_page_token ?? null);
+            setSelectedConversationId((current) => {
+                if (current)
+                    return current;
+                if (initialConversationId)
+                    return initialConversationId;
+                if (!autoSelectFirst)
+                    return null;
+                return nextConversations[0]?.id ?? null;
+            });
+            return nextConversations;
+        }
+        finally {
+            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,
+            podId: input.podId ?? podId ?? undefined,
+            assistantName: input.assistantName ?? assistantName ?? assistantId ?? undefined,
+            organizationId: input.organizationId ?? organizationId ?? undefined,
+            setActive: input.setActive ?? true,
+        });
+        setConversations((previous) => {
+            const nextConversations = sortConversationsByUpdatedAt([
+                createdConversation,
+                ...previous.filter((conversation) => conversation.id !== createdConversation.id),
+            ]);
+            setTotal(nextConversations.length);
+            return nextConversations;
+        });
+        if (input.setActive !== false) {
+            setSelectedConversationId(createdConversation.id);
+        }
+        return createdConversation;
+    }, [assistantId, assistantName, organizationId, podId, sessionCreateConversation]);
+    const createAndSelectConversation = useCallback(async (input = {}) => {
+        return createConversation({
+            ...input,
+            setActive: true,
+        });
+    }, [createConversation]);
+    const selectConversation = useCallback((conversationId) => {
+        setSelectedConversationId(conversationId);
+    }, []);
+    const clearSelection = useCallback(() => {
+        setSelectedConversationId(null);
+    }, []);
+    const selectLatestConversation = useCallback(() => {
+        const latestConversationId = conversations[0]?.id ?? null;
+        setSelectedConversationId(latestConversationId);
+        return latestConversationId;
+    }, []);
+    useEffect(() => {
+        setSelectedConversationId(initialConversationId);
+    }, [initialConversationId]);
+    useEffect(() => {
+        if (!enabled) {
+            setConversations([]);
+            setTotal(0);
+            setNextPageToken(null);
+            setSelectedConversationId(initialConversationId);
+            setIsLoading(false);
+            setIsLoadingMore(false);
+            return;
+        }
+        setConversations([]);
+        setTotal(0);
+        setNextPageToken(null);
+        setSelectedConversationId(initialConversationId);
+        if (!autoLoad)
+            return;
+        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)
+            return selectedConversationId;
+        if (!autoSelectFirst)
+            return null;
+        return conversations[0]?.id ?? null;
+    }, [autoSelectFirst, conversations, selectedConversationId]);
+    const selectedConversation = useMemo(() => conversations.find((conversation) => conversation.id === effectiveSelectedConversationId) ?? null, [conversations, effectiveSelectedConversationId]);
+    const ensureConversation = useCallback(async (input = {}) => {
+        const existingConversation = selectedConversation
+            ?? conversations.find((conversation) => conversation.id === effectiveSelectedConversationId)
+            ?? null;
+        if (existingConversation) {
+            if (selectedConversationId !== existingConversation.id) {
+                setSelectedConversationId(existingConversation.id);
+            }
+            return existingConversation;
+        }
+        return createAndSelectConversation(input);
+    }, [
+        conversations,
+        createAndSelectConversation,
+        effectiveSelectedConversationId,
+        selectedConversation,
+        selectedConversationId,
+    ]);
+    return useMemo(() => ({
+        conversations,
+        total,
+        nextPageToken,
+        activeConversationId: selectedConversationId,
+        activeConversation: selectedConversation,
+        selectedConversationId,
+        effectiveSelectedConversationId,
+        selectedConversation,
+        isLoading,
+        isLoadingMore,
+        error,
+        selectConversation,
+        clearSelection,
+        selectLatestConversation,
+        refresh,
+        loadMore,
+        createConversation,
+        createAndSelectConversation,
+        ensureConversation,
+    }), [
+        clearSelection,
+        conversations,
+        createAndSelectConversation,
+        createConversation,
+        effectiveSelectedConversationId,
+        error,
+        isLoading,
+        isLoadingMore,
+        loadMore,
+        nextPageToken,
+        refresh,
+        ensureConversation,
+        selectConversation,
+        selectLatestConversation,
+        selectedConversation,
+        selectedConversationId,
+        total,
+    ]);
+}

package/dist/react/useCreateRecord.d.ts

@@ -0,0 +1,18 @@
+import type { LemmaClient } from "../client.js";
+import type { RecordResponse } from "../types.js";
+export interface UseCreateRecordOptions {
+    client: LemmaClient;
+    podId?: string;
+    tableName: string;
+    enabled?: boolean;
+    onSuccess?: (record: Record<string, unknown>, response: RecordResponse) => void;
+    onError?: (error: unknown) => void;
+}
+export interface UseCreateRecordResult<TRecord extends Record<string, unknown> = Record<string, unknown>> {
+    createdRecord: TRecord | null;
+    isSubmitting: boolean;
+    error: Error | null;
+    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>;

package/dist/react/useCreateRecord.js

@@ -0,0 +1,51 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { normalizeError, resolvePodClient } from "./utils.js";
+export function useCreateRecord({ client, podId, tableName, enabled = true, onSuccess, onError, }) {
+    const [createdRecord, setCreatedRecord] = 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 isEnabled = enabled && trimmedTableName.length > 0;
+    const create = useCallback(async (data) => {
+        if (!isEnabled) {
+            return null;
+        }
+        setIsSubmitting(true);
+        setError(null);
+        try {
+            const scopedClient = resolvePodClient(client, podId);
+            const response = await scopedClient.records.create(trimmedTableName, data);
+            const nextRecord = (response.data ?? null);
+            setCreatedRecord(nextRecord);
+            if (nextRecord) {
+                onSuccessRef.current?.(nextRecord, response);
+            }
+            return nextRecord;
+        }
+        catch (mutationError) {
+            const normalized = normalizeError(mutationError, "Failed to create record.");
+            setError(normalized);
+            onErrorRef.current?.(mutationError);
+            return null;
+        }
+        finally {
+            setIsSubmitting(false);
+        }
+    }, [client, isEnabled, podId, trimmedTableName]);
+    const reset = useCallback(() => {
+        setCreatedRecord(null);
+        setError(null);
+        setIsSubmitting(false);
+    }, []);
+    return useMemo(() => ({
+        createdRecord,
+        isSubmitting,
+        error,
+        create,
+        reset,
+    }), [create, createdRecord, error, isSubmitting, reset]);
+}

package/dist/react/useCurrentUser.d.ts

@@ -0,0 +1,14 @@
+import type { LemmaClient } from "../client.js";
+import type { User } from "../types.js";
+export interface UseCurrentUserOptions {
+    client: LemmaClient;
+    enabled?: boolean;
+    autoLoad?: boolean;
+}
+export interface UseCurrentUserResult {
+    user: User | null;
+    isLoading: boolean;
+    error: Error | null;
+    refresh: () => Promise<User | null>;
+}
+export declare function useCurrentUser({ client, enabled, autoLoad, }: UseCurrentUserOptions): UseCurrentUserResult;