lemma-sdk 0.2.28 → 0.2.31

package/dist/react/useUpdateRecord.js

@@ -0,0 +1,55 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { normalizeError, resolvePodClient } from "./utils.js";
+export function useUpdateRecord({ client, podId, tableName, recordId = null, enabled = true, onSuccess, onError, }) {
+    const [updatedRecord, setUpdatedRecord] = useState(null);
+    const [isSubmitting, setIsSubmitting] = useState(false);
+    const [error, setError] = useState(null);
+    const onSuccessRef = useRef(onSuccess);
+    const onErrorRef = useRef(onError);
+    useEffect(() => { onSuccessRef.current = onSuccess; }, [onSuccess]);
+    useEffect(() => { onErrorRef.current = onError; }, [onError]);
+    const trimmedTableName = tableName.trim();
+    const trimmedRecordId = typeof recordId === "string" ? recordId.trim() : "";
+    const isEnabled = enabled && trimmedTableName.length > 0;
+    const update = useCallback(async (data, overrides = {}) => {
+        const nextRecordId = typeof overrides.recordId === "string"
+            ? overrides.recordId.trim()
+            : trimmedRecordId;
+        if (!isEnabled || nextRecordId.length === 0) {
+            return null;
+        }
+        setIsSubmitting(true);
+        setError(null);
+        try {
+            const scopedClient = resolvePodClient(client, podId);
+            const response = await scopedClient.records.update(trimmedTableName, nextRecordId, data);
+            const nextRecord = (response.data ?? null);
+            setUpdatedRecord(nextRecord);
+            if (nextRecord) {
+                onSuccessRef.current?.(nextRecord, response);
+            }
+            return nextRecord;
+        }
+        catch (mutationError) {
+            const normalized = normalizeError(mutationError, "Failed to update record.");
+            setError(normalized);
+            onErrorRef.current?.(mutationError);
+            return null;
+        }
+        finally {
+            setIsSubmitting(false);
+        }
+    }, [client, isEnabled, podId, trimmedRecordId, trimmedTableName]);
+    const reset = useCallback(() => {
+        setUpdatedRecord(null);
+        setError(null);
+        setIsSubmitting(false);
+    }, []);
+    return useMemo(() => ({
+        updatedRecord,
+        isSubmitting,
+        error,
+        update,
+        reset,
+    }), [error, isSubmitting, reset, update, updatedRecord]);
+}

package/dist/react/useWorkflowResume.d.ts

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

package/dist/react/useWorkflowResume.js

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

package/dist/react/useWorkflowRun.d.ts

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

package/dist/react/useWorkflowRun.js

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

package/dist/react/useWorkflowRuns.d.ts

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

package/dist/react/useWorkflowRuns.js

@@ -0,0 +1,149 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { normalizeError, resolvePodClient } from "./utils.js";
+export function useWorkflowRuns({ client, podId, workflowName, enabled = true, autoLoad = true, limit = 100, pageToken, initialRunId = null, }) {
+    const [runs, setRuns] = useState([]);
+    const [total, setTotal] = useState(0);
+    const [nextPageToken, setNextPageToken] = useState(null);
+    const [selectedRunId, setSelectedRunId] = useState(initialRunId);
+    const [isLoading, setIsLoading] = useState(false);
+    const [isLoadingMore, setIsLoadingMore] = useState(false);
+    const [error, setError] = useState(null);
+    const trimmedWorkflowName = workflowName.trim();
+    const isEnabled = enabled && trimmedWorkflowName.length > 0;
+    const refresh = useCallback(async (overrides = {}, signal) => {
+        if (!isEnabled) {
+            setRuns([]);
+            setTotal(0);
+            setNextPageToken(null);
+            setError(null);
+            setIsLoading(false);
+            return [];
+        }
+        setIsLoading(true);
+        setError(null);
+        try {
+            const scopedClient = resolvePodClient(client, podId);
+            const response = await scopedClient.workflows.runs.list(trimmedWorkflowName, {
+                limit: overrides.limit ?? limit,
+                pageToken: overrides.pageToken ?? pageToken,
+            });
+            if (signal?.aborted)
+                return [];
+            const nextRuns = response.items ?? [];
+            setRuns(nextRuns);
+            setTotal(response.total ?? nextRuns.length);
+            setNextPageToken(response.next_page_token ?? null);
+            setSelectedRunId((current) => (current && nextRuns.some((run) => run.id === current) ? current : initialRunId));
+            return nextRuns;
+        }
+        catch (refreshError) {
+            if (signal?.aborted)
+                return [];
+            const normalized = normalizeError(refreshError, "Failed to load workflow runs.");
+            setError(normalized);
+            return [];
+        }
+        finally {
+            if (!signal?.aborted)
+                setIsLoading(false);
+        }
+    }, [client, initialRunId, isEnabled, limit, pageToken, podId, trimmedWorkflowName]);
+    const loadMore = useCallback(async (overrides = {}) => {
+        if (!isEnabled || !nextPageToken || isLoading || isLoadingMore) {
+            return [];
+        }
+        setIsLoadingMore(true);
+        setError(null);
+        try {
+            const scopedClient = resolvePodClient(client, podId);
+            const response = await scopedClient.workflows.runs.list(trimmedWorkflowName, {
+                limit: overrides.limit ?? limit,
+                pageToken: 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 workflow runs.");
+            setError(normalized);
+            return [];
+        }
+        finally {
+            setIsLoadingMore(false);
+        }
+    }, [client, isEnabled, isLoading, isLoadingMore, limit, nextPageToken, podId, trimmedWorkflowName]);
+    useEffect(() => {
+        setSelectedRunId(initialRunId);
+    }, [initialRunId]);
+    useEffect(() => {
+        if (!isEnabled) {
+            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 workflow runs."), "Failed to load workflow runs."));
+                }
+            }
+        })();
+        return () => {
+            cancelled = true;
+            controller.abort();
+        };
+    }, [autoLoad, isEnabled, refresh]);
+    const selectRun = useCallback((runId) => {
+        setSelectedRunId(runId);
+    }, []);
+    const clearSelection = useCallback(() => {
+        setSelectedRunId(null);
+    }, []);
+    return useMemo(() => {
+        const effectiveSelectedRunId = selectedRunId ?? runs[0]?.id ?? null;
+        const selectedRun = effectiveSelectedRunId
+            ? runs.find((run) => run.id === effectiveSelectedRunId) ?? null
+            : null;
+        return {
+            runs,
+            total,
+            nextPageToken,
+            selectedRunId,
+            effectiveSelectedRunId,
+            selectedRun,
+            isLoading,
+            isLoadingMore,
+            error,
+            selectRun,
+            clearSelection,
+            refresh,
+            loadMore,
+        };
+    }, [
+        clearSelection,
+        error,
+        isLoading,
+        isLoadingMore,
+        loadMore,
+        nextPageToken,
+        refresh,
+        runs,
+        selectRun,
+        selectedRunId,
+        total,
+    ]);
+}

package/dist/react/useWorkflowStart.d.ts

@@ -0,0 +1,33 @@
+import type { LemmaClient } from "../client.js";
+import type { FlowRun, FlowStartType, Workflow, WorkflowRunInputs } from "../types.js";
+import { type UseFlowSessionResult } from "./useFlowSession.js";
+export interface UseWorkflowStartOptions {
+    client: LemmaClient;
+    podId?: string;
+    workflowName: string;
+    runId?: string | null;
+    enabled?: boolean;
+    autoLoad?: boolean;
+    autoPoll?: boolean;
+    pollIntervalMs?: number;
+    onRun?: (run: FlowRun) => void;
+    onError?: (error: unknown) => void;
+}
+export interface UseWorkflowStartResult extends Omit<UseFlowSessionResult, "start" | "listHistory"> {
+    workflow: Workflow | null;
+    startType: FlowStartType | "MANUAL";
+    inputSchema: Record<string, unknown> | null;
+    inputUiSchema: Record<string, unknown> | null;
+    isLoadingWorkflow: boolean;
+    isStarting: boolean;
+    error: Error | null;
+    refreshWorkflow: () => Promise<Workflow | null>;
+    listHistory: (options?: {
+        limit?: number;
+        pageToken?: string;
+    }) => Promise<FlowRun[]>;
+    start: (inputs?: WorkflowRunInputs, options?: {
+        forceResume?: boolean;
+    }) => Promise<FlowRun>;
+}
+export declare function useWorkflowStart({ client, podId, workflowName, runId, enabled, autoLoad, autoPoll, pollIntervalMs, onRun, onError, }: UseWorkflowStartOptions): UseWorkflowStartResult;

package/dist/react/useWorkflowStart.js

@@ -0,0 +1,148 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { normalizeRunStatus } from "../run-utils.js";
+import { normalizeError, resolvePodClient } from "./utils.js";
+import { useFlowSession, } from "./useFlowSession.js";
+function findFirstFormNode(workflow) {
+    if (!workflow?.nodes?.length)
+        return null;
+    for (const node of workflow.nodes) {
+        if (!node || typeof node !== "object")
+            continue;
+        if (!("config" in node) || typeof node.config !== "object" || !node.config)
+            continue;
+        if ("input_schema" in node.config) {
+            return node;
+        }
+    }
+    return null;
+}
+function isWaitingFlowRun(run) {
+    if (!run)
+        return false;
+    const normalizedStatus = normalizeRunStatus(run.status);
+    return normalizedStatus === "WAITING"
+        || !!run.waiting_function_run_id
+        || !!run.waiting_task_id
+        || !!run.waiting_trigger_id;
+}
+export function useWorkflowStart({ client, podId, workflowName, runId = null, enabled = true, autoLoad = true, autoPoll = true, pollIntervalMs = 2000, onRun, onError, }) {
+    const [workflow, setWorkflow] = useState(null);
+    const [workflowError, setWorkflowError] = useState(null);
+    const [isLoadingWorkflow, setIsLoadingWorkflow] = useState(false);
+    const [isStarting, setIsStarting] = useState(false);
+    const hasWorkflowName = workflowName.trim().length > 0;
+    const isEnabled = enabled && hasWorkflowName;
+    const session = useFlowSession({
+        client,
+        podId,
+        flowName: workflowName,
+        runId,
+        autoPoll,
+        pollIntervalMs,
+        onRun,
+        onError,
+    });
+    const refreshWorkflow = useCallback(async () => {
+        if (!isEnabled) {
+            setWorkflow(null);
+            setWorkflowError(null);
+            setIsLoadingWorkflow(false);
+            return null;
+        }
+        setIsLoadingWorkflow(true);
+        setWorkflowError(null);
+        try {
+            const scopedClient = resolvePodClient(client, podId);
+            const nextWorkflow = await scopedClient.workflows.get(workflowName);
+            setWorkflow(nextWorkflow);
+            return nextWorkflow;
+        }
+        catch (refreshError) {
+            const normalized = normalizeError(refreshError, "Failed to fetch workflow definition.");
+            setWorkflowError(normalized);
+            return null;
+        }
+        finally {
+            setIsLoadingWorkflow(false);
+        }
+    }, [client, isEnabled, podId, workflowName]);
+    useEffect(() => {
+        if (!isEnabled) {
+            setWorkflow(null);
+            setWorkflowError(null);
+            setIsLoadingWorkflow(false);
+            return;
+        }
+        if (!autoLoad)
+            return;
+        void refreshWorkflow();
+    }, [autoLoad, isEnabled, refreshWorkflow]);
+    const listHistory = useCallback((options = {}) => {
+        return session.listHistory({
+            flowName: workflowName,
+            limit: options.limit,
+            pageToken: options.pageToken,
+        });
+    }, [session, workflowName]);
+    const start = useCallback(async (inputs = {}, options = {}) => {
+        if (!hasWorkflowName) {
+            const missingWorkflowError = new Error("workflowName is required.");
+            setWorkflowError(missingWorkflowError);
+            throw missingWorkflowError;
+        }
+        setIsStarting(true);
+        setWorkflowError(null);
+        try {
+            const currentWorkflow = workflow?.name === workflowName
+                ? workflow
+                : await refreshWorkflow();
+            const startType = currentWorkflow?.start?.type ?? "MANUAL";
+            if (startType === "MANUAL") {
+                const created = await session.start({
+                    flowName: workflowName,
+                    inputs: {},
+                });
+                const shouldResume = !!created.id && (options.forceResume === true
+                    || Object.keys(inputs).length > 0
+                    || isWaitingFlowRun(created));
+                if (!shouldResume || !created.id) {
+                    return created;
+                }
+                return session.resume({
+                    runId: created.id,
+                    inputs,
+                });
+            }
+            return session.start({
+                flowName: workflowName,
+                inputs,
+            });
+        }
+        catch (startError) {
+            const normalized = normalizeError(startError, "Failed to start workflow.");
+            setWorkflowError(normalized);
+            throw normalized;
+        }
+        finally {
+            setIsStarting(false);
+        }
+    }, [hasWorkflowName, refreshWorkflow, session, workflow, workflowName]);
+    return useMemo(() => {
+        const formNode = findFirstFormNode(workflow);
+        const startType = workflow?.start?.type ?? "MANUAL";
+        const error = workflowError ?? session.error;
+        return {
+            ...session,
+            workflow,
+            startType,
+            inputSchema: formNode?.config.input_schema ?? null,
+            inputUiSchema: formNode?.config.ui_schema ?? null,
+            isLoadingWorkflow,
+            isStarting,
+            error,
+            refreshWorkflow,
+            listHistory,
+            start,
+        };
+    }, [isStarting, isLoadingWorkflow, listHistory, refreshWorkflow, session, start, workflow, workflowError]);
+}

package/dist/react/utils.d.ts

@@ -0,0 +1,5 @@
+import type { LemmaClient } from "../client.js";
+export declare function normalizeError(error: unknown, fallback: string): Error;
+export declare function resolvePodClient(client: LemmaClient, podId?: string): LemmaClient;
+export declare function resolvePodId(client: LemmaClient, podId?: string): string;
+export declare function stringifyComparable(value: unknown): string;

package/dist/react/utils.js

@@ -0,0 +1,25 @@
+export function normalizeError(error, fallback) {
+    if (error instanceof Error)
+        return error;
+    return new Error(fallback);
+}
+export function resolvePodClient(client, podId) {
+    if (!podId || podId === client.podId)
+        return client;
+    return client.withPod(podId);
+}
+export 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 stringifyComparable(value) {
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}

package/dist/record-form.d.ts

@@ -0,0 +1,30 @@
+import { type ForeignKeyReference } from "./datastore-query.js";
+import { type ColumnSchema, type Table } from "./types.js";
+export type RecordSchemaFieldKind = "text" | "textarea" | "number" | "boolean" | "json" | "date" | "datetime" | "select" | "foreign-key" | "uuid";
+export interface RecordSchemaField {
+    name: string;
+    label: string;
+    kind: RecordSchemaFieldKind;
+    column: ColumnSchema;
+    required: boolean;
+    readOnly: boolean;
+    system: boolean;
+    computed: boolean;
+    auto: boolean;
+    options: string[];
+    foreignKey: ForeignKeyReference | null;
+}
+export interface BuildRecordPayloadOptions {
+    mode?: "create" | "update";
+}
+export interface BuildRecordPayloadResult {
+    data: Record<string, unknown>;
+    errors: Record<string, string>;
+    isValid: boolean;
+}
+export declare function getRecordFieldKind(column: ColumnSchema): RecordSchemaFieldKind;
+export declare function buildRecordSchemaFields(table: Table): RecordSchemaField[];
+export declare function getEditableRecordFields(table: Table): RecordSchemaField[];
+export declare function formatRecordValueForForm(column: ColumnSchema, value: unknown): unknown;
+export declare function buildRecordFormValues(table: Table, values?: Record<string, unknown>): Record<string, unknown>;
+export declare function buildRecordPayload(table: Table, values: Record<string, unknown>, options?: BuildRecordPayloadOptions): BuildRecordPayloadResult;