lemma-sdk 0.2.3 → 0.2.5

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,
+    };
+}

package/dist/react/useFlowSession.d.ts

@@ -0,0 +1,39 @@
+import type { LemmaClient } from "../client.js";
+import type { FlowRun, WorkflowRunInputs } from "../types.js";
+export interface UseFlowSessionOptions {
+    client: LemmaClient;
+    podId?: string;
+    flowName?: string;
+    runId?: string | null;
+    autoPoll?: boolean;
+    pollIntervalMs?: number;
+    onRun?: (run: FlowRun) => void;
+    onError?: (error: unknown) => void;
+}
+export interface UseFlowSessionResult {
+    runId: string | null;
+    run: FlowRun | null;
+    status?: string;
+    isPolling: boolean;
+    error: Error | null;
+    setRunId: (runId: string | null) => void;
+    start: (options?: {
+        flowName?: string;
+        inputs?: WorkflowRunInputs;
+        connect?: boolean;
+    }) => Promise<FlowRun>;
+    resume: (options: {
+        runId?: string | null;
+        inputs?: WorkflowRunInputs;
+        connect?: boolean;
+    }) => Promise<FlowRun>;
+    refresh: (runId?: string | null) => Promise<FlowRun | null>;
+    listHistory: (options?: {
+        flowName?: string;
+        limit?: number;
+        pageToken?: string;
+    }) => Promise<FlowRun[]>;
+    cancel: (runId?: string | null) => Promise<void>;
+    retry: (runId?: string | null) => Promise<void>;
+}
+export declare function useFlowSession({ client, podId, flowName, runId: initialRunId, autoPoll, pollIntervalMs, onRun, onError, }: UseFlowSessionOptions): UseFlowSessionResult;

package/dist/react/useFlowSession.js

@@ -0,0 +1,195 @@
+import { useCallback, useEffect, useState } from "react";
+import { isTerminalFlowStatus, normalizeRunStatus, sleep } from "../run-utils.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 resolveFlowName(base, override) {
+    const resolved = override ?? base;
+    if (!resolved) {
+        throw new Error("flowName is required.");
+    }
+    return resolved;
+}
+function resolveRunId(base, override) {
+    const resolved = override ?? base;
+    if (!resolved) {
+        throw new Error("runId is required.");
+    }
+    return resolved;
+}
+function normalizeError(error, fallback) {
+    if (error instanceof Error)
+        return error;
+    return new Error(fallback);
+}
+export function useFlowSession({ client, podId, flowName, runId: initialRunId = null, autoPoll = true, pollIntervalMs = 2000, onRun, onError, }) {
+    const [runId, setRunIdState] = useState(initialRunId);
+    const [run, setRun] = useState(null);
+    const [status, setStatus] = useState(undefined);
+    const [isPolling, setIsPolling] = useState(false);
+    const [error, setError] = useState(null);
+    const setRunId = useCallback((nextRunId) => {
+        setRunIdState(nextRunId);
+        if (!nextRunId) {
+            setRun(null);
+            setStatus(undefined);
+        }
+    }, []);
+    const refresh = useCallback(async (explicitRunId) => {
+        const id = explicitRunId ?? runId;
+        if (!id)
+            return null;
+        try {
+            const resolvedPodId = resolvePodId(client, podId);
+            const nextRun = await client.workflows.runs.get(id, resolvedPodId);
+            setRun(nextRun);
+            const nextStatus = normalizeRunStatus(nextRun.status);
+            setStatus(nextStatus);
+            onRun?.(nextRun);
+            return nextRun;
+        }
+        catch (refreshError) {
+            const normalized = normalizeError(refreshError, "Failed to fetch flow run.");
+            setError(normalized);
+            onError?.(refreshError);
+            return null;
+        }
+    }, [client, onError, onRun, podId, runId]);
+    const listHistory = useCallback(async (options = {}) => {
+        try {
+            client.setPodId(resolvePodId(client, podId));
+            const name = resolveFlowName(flowName, options.flowName);
+            const response = await client.workflows.runs.list(name, {
+                limit: options.limit,
+                pageToken: options.pageToken,
+            });
+            return response.items ?? [];
+        }
+        catch (listError) {
+            const normalized = normalizeError(listError, "Failed to list flow runs.");
+            setError(normalized);
+            onError?.(listError);
+            return [];
+        }
+    }, [client, flowName, onError, podId]);
+    const start = useCallback(async (options = {}) => {
+        setError(null);
+        client.setPodId(resolvePodId(client, podId));
+        const name = resolveFlowName(flowName, options.flowName);
+        const created = await client.workflows.runs.start(name, options.inputs);
+        setRun(created);
+        setRunIdState(created.id ?? null);
+        const nextStatus = normalizeRunStatus(created.status);
+        setStatus(nextStatus);
+        onRun?.(created);
+        if (options.connect !== false && created.id) {
+            await refresh(created.id);
+        }
+        return created;
+    }, [client, flowName, onRun, podId, refresh]);
+    const resume = useCallback(async (options) => {
+        setError(null);
+        const resolvedPodId = resolvePodId(client, podId);
+        const id = resolveRunId(runId, options.runId);
+        const resumed = await client.workflows.runs.resume(id, options.inputs, resolvedPodId);
+        setRun(resumed);
+        setRunIdState(resumed.id ?? id);
+        const nextStatus = normalizeRunStatus(resumed.status);
+        setStatus(nextStatus);
+        onRun?.(resumed);
+        if (options.connect !== false) {
+            await refresh(resumed.id ?? id);
+        }
+        return resumed;
+    }, [client, onRun, podId, refresh, runId]);
+    const cancel = useCallback(async (explicitRunId) => {
+        try {
+            const resolvedPodId = resolvePodId(client, podId);
+            const id = resolveRunId(runId, explicitRunId);
+            await client.workflows.runs.cancel(id, resolvedPodId);
+            await refresh(id);
+        }
+        catch (cancelError) {
+            const normalized = normalizeError(cancelError, "Failed to cancel flow run.");
+            setError(normalized);
+            onError?.(cancelError);
+        }
+    }, [client, onError, podId, refresh, runId]);
+    const retry = useCallback(async (explicitRunId) => {
+        try {
+            const resolvedPodId = resolvePodId(client, podId);
+            const id = resolveRunId(runId, explicitRunId);
+            await client.workflows.runs.retry(id, resolvedPodId);
+            await refresh(id);
+        }
+        catch (retryError) {
+            const normalized = normalizeError(retryError, "Failed to retry flow run.");
+            setError(normalized);
+            onError?.(retryError);
+        }
+    }, [client, onError, podId, refresh, runId]);
+    useEffect(() => {
+        if (!runId) {
+            return;
+        }
+        void refresh(runId);
+    }, [refresh, runId]);
+    useEffect(() => {
+        if (!autoPoll || !runId) {
+            return;
+        }
+        let active = true;
+        const abortController = new AbortController();
+        const loop = async () => {
+            setIsPolling(true);
+            while (active) {
+                const latest = await refresh(runId);
+                if (!latest) {
+                    break;
+                }
+                const latestStatus = normalizeRunStatus(latest?.status);
+                if (latestStatus && isTerminalFlowStatus(latestStatus)) {
+                    break;
+                }
+                try {
+                    await sleep(pollIntervalMs, abortController.signal);
+                }
+                catch (sleepError) {
+                    if (sleepError instanceof Error && sleepError.name === "AbortError") {
+                        break;
+                    }
+                    throw sleepError;
+                }
+            }
+            setIsPolling(false);
+        };
+        void loop().catch((pollError) => {
+            const normalized = normalizeError(pollError, "Failed while polling flow run.");
+            setError(normalized);
+            onError?.(pollError);
+            setIsPolling(false);
+        });
+        return () => {
+            active = false;
+            abortController.abort();
+        };
+    }, [autoPoll, onError, pollIntervalMs, refresh, runId]);
+    return {
+        runId,
+        run,
+        status,
+        isPolling,
+        error,
+        setRunId,
+        start,
+        resume,
+        refresh,
+        listHistory,
+        cancel,
+        retry,
+    };
+}

package/dist/react/useFunctionSession.d.ts

@@ -0,0 +1,32 @@
+import type { LemmaClient } from "../client.js";
+import type { FunctionRun } from "../types.js";
+export interface UseFunctionSessionOptions {
+    client: LemmaClient;
+    podId?: string;
+    functionName?: string;
+    runId?: string | null;
+    autoPoll?: boolean;
+    pollIntervalMs?: number;
+    onRun?: (run: FunctionRun) => void;
+    onError?: (error: unknown) => void;
+}
+export interface UseFunctionSessionResult {
+    runId: string | null;
+    run: FunctionRun | null;
+    status?: string;
+    isPolling: boolean;
+    error: Error | null;
+    setRunId: (runId: string | null) => void;
+    start: (options?: {
+        functionName?: string;
+        input?: Record<string, unknown>;
+        connect?: boolean;
+    }) => Promise<FunctionRun>;
+    refresh: (runId?: string | null) => Promise<FunctionRun | null>;
+    listHistory: (options?: {
+        functionName?: string;
+        limit?: number;
+        pageToken?: string;
+    }) => Promise<FunctionRun[]>;
+}
+export declare function useFunctionSession({ client, podId, functionName, runId: initialRunId, autoPoll, pollIntervalMs, onRun, onError, }: UseFunctionSessionOptions): UseFunctionSessionResult;

package/dist/react/useFunctionSession.js

@@ -0,0 +1,147 @@
+import { useCallback, useEffect, useState } from "react";
+import { isTerminalFunctionStatus, normalizeRunStatus, sleep } from "../run-utils.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 resolveFunctionName(base, override) {
+    const resolved = override ?? base;
+    if (!resolved) {
+        throw new Error("functionName is required.");
+    }
+    return resolved;
+}
+function normalizeError(error, fallback) {
+    if (error instanceof Error)
+        return error;
+    return new Error(fallback);
+}
+export function useFunctionSession({ client, podId, functionName, runId: initialRunId = null, autoPoll = true, pollIntervalMs = 2000, onRun, onError, }) {
+    const [runId, setRunIdState] = useState(initialRunId);
+    const [run, setRun] = useState(null);
+    const [status, setStatus] = useState(undefined);
+    const [isPolling, setIsPolling] = useState(false);
+    const [error, setError] = useState(null);
+    const setRunId = useCallback((nextRunId) => {
+        setRunIdState(nextRunId);
+        if (!nextRunId) {
+            setRun(null);
+            setStatus(undefined);
+        }
+    }, []);
+    const refresh = useCallback(async (explicitRunId) => {
+        const id = explicitRunId ?? runId;
+        if (!id)
+            return null;
+        try {
+            client.setPodId(resolvePodId(client, podId));
+            const name = resolveFunctionName(functionName);
+            const nextRun = await client.functions.runs.get(name, id);
+            setRun(nextRun);
+            const nextStatus = normalizeRunStatus(nextRun.status);
+            setStatus(nextStatus);
+            onRun?.(nextRun);
+            return nextRun;
+        }
+        catch (refreshError) {
+            const normalized = normalizeError(refreshError, "Failed to fetch function run.");
+            setError(normalized);
+            onError?.(refreshError);
+            return null;
+        }
+    }, [client, functionName, onError, onRun, podId, runId]);
+    const listHistory = useCallback(async (options = {}) => {
+        try {
+            client.setPodId(resolvePodId(client, podId));
+            const name = resolveFunctionName(functionName, options.functionName);
+            const response = await client.functions.runs.list(name, {
+                limit: options.limit,
+                pageToken: options.pageToken,
+            });
+            return response.items ?? [];
+        }
+        catch (listError) {
+            const normalized = normalizeError(listError, "Failed to list function runs.");
+            setError(normalized);
+            onError?.(listError);
+            return [];
+        }
+    }, [client, functionName, onError, podId]);
+    const start = useCallback(async (options = {}) => {
+        setError(null);
+        client.setPodId(resolvePodId(client, podId));
+        const name = resolveFunctionName(functionName, options.functionName);
+        const created = await client.functions.runs.create(name, {
+            input: options.input,
+        });
+        setRun(created);
+        setRunIdState(created.id);
+        const nextStatus = normalizeRunStatus(created.status);
+        setStatus(nextStatus);
+        onRun?.(created);
+        if (options.connect !== false) {
+            await refresh(created.id);
+        }
+        return created;
+    }, [client, functionName, onRun, podId, refresh]);
+    useEffect(() => {
+        if (!runId) {
+            return;
+        }
+        void refresh(runId);
+    }, [refresh, runId]);
+    useEffect(() => {
+        if (!autoPoll || !runId) {
+            return;
+        }
+        let active = true;
+        const abortController = new AbortController();
+        const loop = async () => {
+            setIsPolling(true);
+            while (active) {
+                const latest = await refresh(runId);
+                if (!latest) {
+                    break;
+                }
+                const latestStatus = normalizeRunStatus(latest?.status);
+                if (latestStatus && isTerminalFunctionStatus(latestStatus)) {
+                    break;
+                }
+                try {
+                    await sleep(pollIntervalMs, abortController.signal);
+                }
+                catch (sleepError) {
+                    if (sleepError instanceof Error && sleepError.name === "AbortError") {
+                        break;
+                    }
+                    throw sleepError;
+                }
+            }
+            setIsPolling(false);
+        };
+        void loop().catch((pollError) => {
+            const normalized = normalizeError(pollError, "Failed while polling function run.");
+            setError(normalized);
+            onError?.(pollError);
+            setIsPolling(false);
+        });
+        return () => {
+            active = false;
+            abortController.abort();
+        };
+    }, [autoPoll, onError, pollIntervalMs, refresh, runId]);
+    return {
+        runId,
+        run,
+        status,
+        isPolling,
+        error,
+        setRunId,
+        start,
+        refresh,
+        listHistory,
+    };
+}

package/dist/react/useTaskSession.d.ts

@@ -0,0 +1,35 @@
+import type { LemmaClient } from "../client.js";
+import { type SseRawEvent } from "../streams.js";
+import type { Task, TaskMessage } from "../types.js";
+export interface CreateTaskInput {
+    agentName: string;
+    inputData?: Record<string, unknown> | null;
+}
+export interface UseTaskSessionOptions {
+    client: LemmaClient;
+    podId?: string;
+    taskId?: string | null;
+    autoConnect?: boolean;
+    autoConnectOnStart?: boolean;
+    onEvent?: (event: SseRawEvent, payload: unknown | null) => void;
+    onStatus?: (status: string) => void;
+    onMessage?: (message: TaskMessage) => void;
+    onError?: (error: unknown) => void;
+}
+export interface UseTaskSessionResult {
+    taskId: string | null;
+    task: Task | null;
+    status?: string;
+    messages: TaskMessage[];
+    isStreaming: boolean;
+    error: Error | null;
+    setTaskId: (taskId: string | null) => void;
+    start: (input: CreateTaskInput) => Promise<Task>;
+    refreshTask: (taskId?: string | null) => Promise<Task | null>;
+    loadMessages: (taskId?: string | null) => Promise<TaskMessage[]>;
+    connect: (taskId?: string | null) => Promise<void>;
+    disconnect: () => void;
+    stop: () => Promise<Task | null>;
+    clearMessages: () => void;
+}
+export declare function useTaskSession({ client, podId, taskId: externalTaskId, autoConnect, autoConnectOnStart, onEvent, onStatus, onMessage, onError, }: UseTaskSessionOptions): UseTaskSessionResult;