lemma-sdk 0.2.27 → 0.2.30

package/dist/react/useTable.js

@@ -0,0 +1,59 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+function resolvePodClient(client, podId) {
+    if (!podId || podId === client.podId)
+        return client;
+    return client.withPod(podId);
+}
+function normalizeError(error, fallback) {
+    if (error instanceof Error)
+        return error;
+    return new Error(fallback);
+}
+export function useTable({ client, podId, tableName, enabled = true, autoLoad = true, }) {
+    const [table, setTable] = useState(null);
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const trimmedTableName = tableName.trim();
+    const isEnabled = enabled && trimmedTableName.length > 0;
+    const refresh = useCallback(async () => {
+        if (!isEnabled) {
+            setTable(null);
+            setError(null);
+            setIsLoading(false);
+            return null;
+        }
+        setIsLoading(true);
+        setError(null);
+        try {
+            const scopedClient = resolvePodClient(client, podId);
+            const nextTable = await scopedClient.tables.get(trimmedTableName);
+            setTable(nextTable);
+            return nextTable;
+        }
+        catch (refreshError) {
+            const normalized = normalizeError(refreshError, "Failed to load table.");
+            setError(normalized);
+            return null;
+        }
+        finally {
+            setIsLoading(false);
+        }
+    }, [client, isEnabled, podId, trimmedTableName]);
+    useEffect(() => {
+        if (!isEnabled) {
+            setTable(null);
+            setError(null);
+            setIsLoading(false);
+            return;
+        }
+        if (!autoLoad)
+            return;
+        void refresh();
+    }, [autoLoad, isEnabled, refresh]);
+    return useMemo(() => ({
+        table,
+        isLoading,
+        error,
+        refresh,
+    }), [error, isLoading, refresh, table]);
+}

package/dist/react/useTables.d.ts

@@ -0,0 +1,22 @@
+import type { LemmaClient } from "../client.js";
+import type { Table } from "../types.js";
+export interface UseTablesOptions {
+    client: LemmaClient;
+    podId?: string;
+    enabled?: boolean;
+    autoLoad?: boolean;
+    limit?: number;
+    pageToken?: string;
+}
+export interface UseTablesResult {
+    tables: Table[];
+    total: number;
+    nextPageToken: string | null;
+    isLoading: boolean;
+    error: Error | null;
+    refresh: (overrides?: {
+        limit?: number;
+        pageToken?: string;
+    }) => Promise<Table[]>;
+}
+export declare function useTables({ client, podId, enabled, autoLoad, limit, pageToken, }: UseTablesOptions): UseTablesResult;

package/dist/react/useTables.js

@@ -0,0 +1,71 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+function resolvePodClient(client, podId) {
+    if (!podId || podId === client.podId)
+        return client;
+    return client.withPod(podId);
+}
+function normalizeError(error, fallback) {
+    if (error instanceof Error)
+        return error;
+    return new Error(fallback);
+}
+export function useTables({ client, podId, enabled = true, autoLoad = true, limit = 100, pageToken, }) {
+    const [tables, setTables] = useState([]);
+    const [total, setTotal] = useState(0);
+    const [nextPageToken, setNextPageToken] = useState(null);
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const refresh = useCallback(async (overrides = {}) => {
+        if (!enabled) {
+            setTables([]);
+            setTotal(0);
+            setNextPageToken(null);
+            setError(null);
+            setIsLoading(false);
+            return [];
+        }
+        setIsLoading(true);
+        setError(null);
+        try {
+            const scopedClient = resolvePodClient(client, podId);
+            const response = await scopedClient.tables.list({
+                limit: overrides.limit ?? limit,
+                pageToken: overrides.pageToken ?? pageToken,
+            });
+            const nextTables = response.items ?? [];
+            setTables(nextTables);
+            setTotal(nextTables.length);
+            setNextPageToken(response.next_page_token ?? null);
+            return nextTables;
+        }
+        catch (refreshError) {
+            const normalized = normalizeError(refreshError, "Failed to load tables.");
+            setError(normalized);
+            return [];
+        }
+        finally {
+            setIsLoading(false);
+        }
+    }, [client, enabled, limit, pageToken, podId]);
+    useEffect(() => {
+        if (!enabled) {
+            setTables([]);
+            setTotal(0);
+            setNextPageToken(null);
+            setError(null);
+            setIsLoading(false);
+            return;
+        }
+        if (!autoLoad)
+            return;
+        void refresh();
+    }, [autoLoad, enabled, refresh]);
+    return useMemo(() => ({
+        tables,
+        total,
+        nextPageToken,
+        isLoading,
+        error,
+        refresh,
+    }), [error, isLoading, nextPageToken, refresh, tables, total]);
+}

package/dist/react/useUpdateRecord.d.ts

@@ -0,0 +1,21 @@
+import type { LemmaClient } from "../client.js";
+import type { RecordResponse } from "../types.js";
+export interface UseUpdateRecordOptions {
+    client: LemmaClient;
+    podId?: string;
+    tableName: string;
+    recordId?: string | null;
+    enabled?: boolean;
+    onSuccess?: (record: Record<string, unknown>, response: RecordResponse) => void;
+    onError?: (error: unknown) => void;
+}
+export interface UseUpdateRecordResult<TRecord extends Record<string, unknown> = Record<string, unknown>> {
+    updatedRecord: TRecord | null;
+    isSubmitting: boolean;
+    error: Error | null;
+    update: (data: Record<string, unknown>, overrides?: {
+        recordId?: string | null;
+    }) => Promise<TRecord | null>;
+    reset: () => void;
+}
+export declare function useUpdateRecord<TRecord extends Record<string, unknown> = Record<string, unknown>>({ client, podId, tableName, recordId, enabled, onSuccess, onError, }: UseUpdateRecordOptions): UseUpdateRecordResult<TRecord>;

package/dist/react/useUpdateRecord.js

@@ -0,0 +1,62 @@
+import { useCallback, useMemo, useState } from "react";
+function resolvePodClient(client, podId) {
+    if (!podId || podId === client.podId)
+        return client;
+    return client.withPod(podId);
+}
+function normalizeError(error, fallback) {
+    if (error instanceof Error)
+        return error;
+    return new Error(fallback);
+}
+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 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) {
+            const disabledError = new Error("Record update requires a table and record ID.");
+            setError(disabledError);
+            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) {
+                onSuccess?.(nextRecord, response);
+            }
+            return nextRecord;
+        }
+        catch (mutationError) {
+            const normalized = normalizeError(mutationError, "Failed to update record.");
+            setError(normalized);
+            onError?.(mutationError);
+            return null;
+        }
+        finally {
+            setIsSubmitting(false);
+        }
+    }, [client, isEnabled, onError, onSuccess, 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/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,155 @@
+import { useCallback, useEffect, useState } from "react";
+import { normalizeRunStatus } from "../run-utils.js";
+import { useFlowSession, } from "./useFlowSession.js";
+function normalizeError(error, fallback) {
+    if (error instanceof Error)
+        return error;
+    return new Error(fallback);
+}
+function resolvePodClient(client, podId) {
+    if (!podId || podId === client.podId)
+        return client;
+    return client.withPod(podId);
+}
+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]);
+    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,
+    };
+}

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;

package/dist/record-form.js

@@ -0,0 +1,199 @@
+import { parseForeignKeyReference } from "./datastore-query.js";
+import { DatastoreDataType } from "./types.js";
+function sentenceCase(value) {
+    return value
+        .replace(/_/g, " ")
+        .replace(/\s+/g, " ")
+        .trim()
+        .replace(/\b\w/g, (match) => match.toUpperCase());
+}
+function isBlank(value) {
+    return value === null || typeof value === "undefined" || (typeof value === "string" && value.trim() === "");
+}
+function isIntegerLike(value) {
+    return Number.isInteger(value);
+}
+function getRawColumnDefault(column) {
+    return column.default;
+}
+function shouldUseTextarea(column) {
+    if (typeof column.max_length === "number" && column.max_length >= 240) {
+        return true;
+    }
+    return /(description|content|body|note|instruction|summary|message)/i.test(column.name);
+}
+function toDateInputValue(value) {
+    if (typeof value === "string") {
+        return value.includes("T") ? value.slice(0, 10) : value;
+    }
+    if (value instanceof Date && !Number.isNaN(value.getTime())) {
+        return value.toISOString().slice(0, 10);
+    }
+    return String(value);
+}
+function toDateTimeLocalInputValue(value) {
+    if (typeof value === "string") {
+        const timestamp = new Date(value);
+        if (!Number.isNaN(timestamp.getTime())) {
+            const pad = (part) => String(part).padStart(2, "0");
+            return [
+                timestamp.getFullYear(),
+                pad(timestamp.getMonth() + 1),
+                pad(timestamp.getDate()),
+            ].join("-") + `T${pad(timestamp.getHours())}:${pad(timestamp.getMinutes())}`;
+        }
+        return value;
+    }
+    if (value instanceof Date && !Number.isNaN(value.getTime())) {
+        const pad = (part) => String(part).padStart(2, "0");
+        return [
+            value.getFullYear(),
+            pad(value.getMonth() + 1),
+            pad(value.getDate()),
+        ].join("-") + `T${pad(value.getHours())}:${pad(value.getMinutes())}`;
+    }
+    return String(value);
+}
+export function getRecordFieldKind(column) {
+    if (column.foreign_key?.references)
+        return "foreign-key";
+    if (column.type === DatastoreDataType.ENUM)
+        return "select";
+    if (column.type === DatastoreDataType.BOOLEAN)
+        return "boolean";
+    if (column.type === DatastoreDataType.JSON || column.type === DatastoreDataType.VECTOR)
+        return "json";
+    if (column.type === DatastoreDataType.INTEGER
+        || column.type === DatastoreDataType.FLOAT
+        || column.type === DatastoreDataType.SERIAL) {
+        return "number";
+    }
+    if (column.type === DatastoreDataType.DATE)
+        return "date";
+    if (column.type === DatastoreDataType.DATETIME)
+        return "datetime";
+    if (column.type === DatastoreDataType.UUID)
+        return "uuid";
+    if (column.type === DatastoreDataType.TEXT && shouldUseTextarea(column))
+        return "textarea";
+    return "text";
+}
+export function buildRecordSchemaFields(table) {
+    return table.columns.map((column) => {
+        const foreignKey = column.foreign_key?.references
+            ? parseForeignKeyReference(column.foreign_key.references)
+            : null;
+        return {
+            name: column.name,
+            label: sentenceCase(column.name),
+            kind: getRecordFieldKind(column),
+            column,
+            required: column.required === true,
+            readOnly: column.system === true || column.computed === true || column.auto === true,
+            system: column.system === true,
+            computed: column.computed === true,
+            auto: column.auto === true,
+            options: column.options ?? [],
+            foreignKey,
+        };
+    });
+}
+export function getEditableRecordFields(table) {
+    return buildRecordSchemaFields(table).filter((field) => !field.readOnly);
+}
+export function formatRecordValueForForm(column, value) {
+    const kind = getRecordFieldKind(column);
+    if (value === null || typeof value === "undefined") {
+        if (kind === "boolean")
+            return false;
+        return "";
+    }
+    if (kind === "boolean") {
+        return Boolean(value);
+    }
+    if (kind === "json") {
+        if (typeof value === "string")
+            return value;
+        try {
+            return JSON.stringify(value, null, 2);
+        }
+        catch {
+            return String(value);
+        }
+    }
+    if (kind === "date") {
+        return toDateInputValue(value);
+    }
+    if (kind === "datetime") {
+        return toDateTimeLocalInputValue(value);
+    }
+    if (kind === "number") {
+        return String(value);
+    }
+    return String(value);
+}
+export function buildRecordFormValues(table, values = {}) {
+    const next = {};
+    buildRecordSchemaFields(table).forEach((field) => {
+        const provided = values[field.name];
+        const rawDefault = getRawColumnDefault(field.column);
+        const source = typeof provided !== "undefined" ? provided : rawDefault;
+        next[field.name] = formatRecordValueForForm(field.column, source);
+    });
+    return next;
+}
+function coerceEmptyValue(mode, name, target) {
+    if (mode === "update") {
+        target[name] = null;
+    }
+}
+export function buildRecordPayload(table, values, options = {}) {
+    const mode = options.mode ?? "create";
+    const data = {};
+    const errors = {};
+    getEditableRecordFields(table).forEach((field) => {
+        const rawValue = values[field.name];
+        const value = typeof rawValue === "string" ? rawValue : rawValue;
+        if (field.kind === "boolean") {
+            data[field.name] = Boolean(rawValue);
+            return;
+        }
+        if (isBlank(value)) {
+            if (field.required) {
+                errors[field.name] = `${field.label} is required.`;
+                return;
+            }
+            coerceEmptyValue(mode, field.name, data);
+            return;
+        }
+        if (field.kind === "number") {
+            const parsed = Number(value);
+            if (!Number.isFinite(parsed)) {
+                errors[field.name] = `${field.label} must be a valid number.`;
+                return;
+            }
+            if ((field.column.type === DatastoreDataType.INTEGER || field.column.type === DatastoreDataType.SERIAL)
+                && !isIntegerLike(parsed)) {
+                errors[field.name] = `${field.label} must be a whole number.`;
+                return;
+            }
+            data[field.name] = parsed;
+            return;
+        }
+        if (field.kind === "json") {
+            try {
+                data[field.name] = typeof value === "string" ? JSON.parse(value) : value;
+            }
+            catch {
+                errors[field.name] = `${field.label} must be valid JSON.`;
+            }
+            return;
+        }
+        data[field.name] = typeof value === "string" ? value : String(value);
+    });
+    return {
+        data,
+        errors,
+        isValid: Object.keys(errors).length === 0,
+    };
+}