lemma-sdk 0.2.34 → 0.2.36

package/dist/react/useGlobalSearch.js

@@ -0,0 +1,170 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { escapeSqlString, quoteIdentifierPath, renderIdentifierPath, renderRecordFilters } from "./sql-utils.js";
+import { normalizeError, resolvePodClient, stringifyComparable } from "./utils.js";
+function buildTableSearchQuery(source, query) {
+    const fields = Array.from(new Set([
+        "id",
+        ...source.searchFields,
+        source.displayField ?? "id",
+        source.subtitleField ?? "",
+    ].filter((value) => value.trim().length > 0)));
+    const searchClauses = source.searchFields.map((field) => `${renderIdentifierPath(field)} ILIKE '%${escapeSqlString(query)}%'`);
+    const filterClause = renderRecordFilters(source.filters);
+    return [
+        `SELECT ${fields.map((field) => renderIdentifierPath(field)).join(", ")}`,
+        `FROM ${quoteIdentifierPath(source.tableName)}`,
+        `WHERE (${searchClauses.join(" OR ")})${filterClause ? ` AND ${filterClause}` : ""}`,
+        `LIMIT ${source.limit ?? 8}`,
+    ].join(" ");
+}
+function readString(value) {
+    if (typeof value === "string" && value.trim().length > 0)
+        return value;
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    return null;
+}
+export function useGlobalSearch({ client, podId, query = "", tables = [], files, enabled = true, autoLoad = true, minQueryLength = 1, }) {
+    const [results, setResults] = useState([]);
+    const [sourceErrors, setSourceErrors] = useState({});
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const trimmedQuery = query.trim();
+    const tablesKey = stringifyComparable(tables);
+    const filesKey = stringifyComparable(files);
+    const stableTables = useMemo(() => tables, [tablesKey]);
+    const stableFiles = useMemo(() => files, [filesKey]);
+    const reset = useCallback(() => {
+        setResults([]);
+        setSourceErrors({});
+        setError(null);
+        setIsLoading(false);
+    }, []);
+    const search = useCallback(async (overrides = {}, signal) => {
+        const nextQuery = (overrides.query ?? trimmedQuery).trim();
+        if (!enabled || nextQuery.length < minQueryLength) {
+            reset();
+            return [];
+        }
+        setIsLoading(true);
+        setError(null);
+        try {
+            const scopedClient = resolvePodClient(client, podId);
+            const searchTasks = [];
+            stableTables.forEach((source, index) => {
+                const sourceKey = source.key?.trim() || source.tableName;
+                searchTasks.push((async () => {
+                    try {
+                        const sql = buildTableSearchQuery(source, nextQuery);
+                        const response = await scopedClient.datastore.query(sql);
+                        const rows = response.items ?? [];
+                        const mapped = rows.map((record) => {
+                            const displayField = source.displayField ?? source.searchFields[0] ?? "id";
+                            const subtitleField = source.subtitleField;
+                            const id = readString(record.id) ?? `${source.tableName}-${index}`;
+                            return {
+                                kind: "record",
+                                sourceKey,
+                                sourceLabel: source.label ?? source.tableName,
+                                tableName: source.tableName,
+                                id,
+                                title: readString(record[displayField]) ?? id,
+                                subtitle: subtitleField ? readString(record[subtitleField]) : null,
+                                record,
+                            };
+                        });
+                        return { key: sourceKey, results: mapped };
+                    }
+                    catch (tableError) {
+                        return {
+                            key: sourceKey,
+                            results: [],
+                            error: normalizeError(tableError, `Failed to search ${source.tableName}.`),
+                        };
+                    }
+                })());
+            });
+            if (stableFiles !== false && stableFiles?.enabled !== false) {
+                searchTasks.push((async () => {
+                    const sourceKey = "files";
+                    try {
+                        const response = await scopedClient.files.search(nextQuery, {
+                            limit: stableFiles?.limit ?? 8,
+                            searchMethod: stableFiles?.searchMethod,
+                        });
+                        const mapped = (response.results ?? []).map((result) => ({
+                            kind: "file",
+                            sourceKey,
+                            sourceLabel: stableFiles?.label ?? "Files",
+                            path: result.path,
+                            title: result.path.split("/").filter(Boolean).pop() || result.path,
+                            subtitle: typeof result.content === "string" && result.content.trim().length > 0
+                                ? result.content.slice(0, 160)
+                                : null,
+                            result,
+                        }));
+                        return { key: sourceKey, results: mapped };
+                    }
+                    catch (fileError) {
+                        return {
+                            key: sourceKey,
+                            results: [],
+                            error: normalizeError(fileError, "Failed to search files."),
+                        };
+                    }
+                })());
+            }
+            const settled = await Promise.all(searchTasks);
+            if (signal?.aborted)
+                return [];
+            const nextErrors = {};
+            const nextResults = settled.flatMap((entry) => {
+                if (entry.error) {
+                    nextErrors[entry.key] = entry.error;
+                }
+                return entry.results;
+            });
+            setSourceErrors(nextErrors);
+            setResults(nextResults);
+            return nextResults;
+        }
+        catch (searchError) {
+            if (signal?.aborted)
+                return [];
+            const normalized = normalizeError(searchError, "Failed to run global search.");
+            setError(normalized);
+            setResults([]);
+            return [];
+        }
+        finally {
+            if (!signal?.aborted)
+                setIsLoading(false);
+        }
+    }, [client, enabled, minQueryLength, podId, reset, stableFiles, stableTables, trimmedQuery]);
+    useEffect(() => {
+        if (!enabled || !autoLoad)
+            return;
+        if (trimmedQuery.length < minQueryLength) {
+            reset();
+            return;
+        }
+        const controller = new AbortController();
+        void search({}, controller.signal);
+        return () => controller.abort();
+    }, [autoLoad, enabled, minQueryLength, reset, search, trimmedQuery]);
+    return useMemo(() => {
+        const recordResults = results.filter((entry) => entry.kind === "record");
+        const fileResults = results.filter((entry) => entry.kind === "file");
+        return {
+            results,
+            recordResults,
+            fileResults,
+            totalResults: results.length,
+            sourceErrors,
+            isLoading,
+            error,
+            search,
+            reset,
+        };
+    }, [error, isLoading, reset, results, search, sourceErrors]);
+}

package/dist/react/useRecordAggregates.d.ts

@@ -0,0 +1,35 @@
+import type { LemmaClient } from "../client.js";
+import type { RecordFilter } from "../types.js";
+export interface RecordAggregateMetric {
+    key: string;
+    op: "count" | "sum" | "avg" | "min" | "max";
+    field?: string;
+    distinct?: boolean;
+}
+export interface RecordAggregateOrderBy {
+    field: string;
+    direction?: "asc" | "desc";
+}
+export interface UseRecordAggregatesOptions {
+    client: LemmaClient;
+    podId?: string;
+    tableName: string;
+    metrics: RecordAggregateMetric[];
+    groupBy?: string | string[];
+    filters?: RecordFilter[];
+    limit?: number;
+    offset?: number;
+    orderBy?: RecordAggregateOrderBy[];
+    enabled?: boolean;
+    autoLoad?: boolean;
+}
+export interface UseRecordAggregatesResult<TRow extends Record<string, unknown> = Record<string, unknown>> {
+    rows: TRow[];
+    row: TRow | null;
+    total: number;
+    sql: string;
+    isLoading: boolean;
+    error: Error | null;
+    refresh: () => Promise<TRow[]>;
+}
+export declare function useRecordAggregates<TRow extends Record<string, unknown> = Record<string, unknown>>({ client, podId, tableName, metrics, groupBy, filters, limit, offset, orderBy, enabled, autoLoad, }: UseRecordAggregatesOptions): UseRecordAggregatesResult<TRow>;

package/dist/react/useRecordAggregates.js

@@ -0,0 +1,126 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { encodeSqlValue, quoteIdentifierPath, renderIdentifierPath, renderRecordFilters } from "./sql-utils.js";
+import { normalizeError, resolvePodClient, stringifyComparable } from "./utils.js";
+function buildMetricExpression(metric) {
+    const fn = metric.op.toUpperCase();
+    if (metric.op === "count" && !metric.field) {
+        return `${fn}(*) AS ${quoteIdentifierPath(metric.key)}`;
+    }
+    if (!metric.field) {
+        throw new Error(`Aggregate metric "${metric.key}" requires a field.`);
+    }
+    const renderedField = renderIdentifierPath(metric.field);
+    const distinct = metric.distinct ? "DISTINCT " : "";
+    return `${fn}(${distinct}${renderedField}) AS ${quoteIdentifierPath(metric.key)}`;
+}
+function buildRecordAggregatesQuery({ tableName, metrics, groupBy, filters, limit, offset, orderBy, }) {
+    const groups = (Array.isArray(groupBy) ? groupBy : groupBy ? [groupBy] : [])
+        .map((field) => field.trim())
+        .filter((field) => field.length > 0);
+    const selectParts = [
+        ...groups.map((field) => `${renderIdentifierPath(field)} AS ${quoteIdentifierPath(field)}`),
+        ...metrics.map((metric) => buildMetricExpression(metric)),
+    ];
+    const whereClause = renderRecordFilters(filters);
+    const orderClause = orderBy?.length
+        ? ` ORDER BY ${orderBy.map((entry) => `${renderIdentifierPath(entry.field)} ${(entry.direction ?? "desc").toUpperCase()}`).join(", ")}`
+        : "";
+    const groupClause = groups.length
+        ? ` GROUP BY ${groups.map((field) => renderIdentifierPath(field)).join(", ")}`
+        : "";
+    const limitClause = typeof limit === "number" ? ` LIMIT ${encodeSqlValue(limit)}` : "";
+    const offsetClause = typeof offset === "number" ? ` OFFSET ${encodeSqlValue(offset)}` : "";
+    return [
+        `SELECT ${selectParts.join(", ")}`,
+        `FROM ${quoteIdentifierPath(tableName)}`,
+        whereClause ? `WHERE ${whereClause}` : "",
+        groupClause,
+        orderClause,
+        limitClause,
+        offsetClause,
+    ].filter(Boolean).join(" ");
+}
+export function useRecordAggregates({ client, podId, tableName, metrics, groupBy, filters = [], limit, offset, orderBy, enabled = true, autoLoad = true, }) {
+    const [rows, setRows] = useState([]);
+    const [total, setTotal] = useState(0);
+    const [sql, setSql] = useState("");
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const metricsKey = stringifyComparable(metrics);
+    const filtersKey = stringifyComparable(filters);
+    const groupByKey = stringifyComparable(groupBy);
+    const orderByKey = stringifyComparable(orderBy);
+    const stableMetrics = useMemo(() => metrics, [metricsKey]);
+    const stableFilters = useMemo(() => filters, [filtersKey]);
+    const stableGroupBy = useMemo(() => groupBy, [groupByKey]);
+    const stableOrderBy = useMemo(() => orderBy, [orderByKey]);
+    const trimmedTableName = tableName.trim();
+    const isEnabled = enabled && trimmedTableName.length > 0 && stableMetrics.length > 0;
+    const refresh = useCallback(async (signal) => {
+        if (!isEnabled) {
+            setRows([]);
+            setTotal(0);
+            setSql("");
+            setError(null);
+            setIsLoading(false);
+            return [];
+        }
+        setIsLoading(true);
+        setError(null);
+        try {
+            const scopedClient = resolvePodClient(client, podId);
+            const nextSql = buildRecordAggregatesQuery({
+                tableName: trimmedTableName,
+                metrics: stableMetrics,
+                groupBy: stableGroupBy,
+                filters: stableFilters,
+                limit,
+                offset,
+                orderBy: stableOrderBy,
+            });
+            setSql(nextSql);
+            const response = await scopedClient.datastore.query(nextSql);
+            if (signal?.aborted)
+                return [];
+            const nextRows = (response.items ?? []);
+            setRows(nextRows);
+            setTotal(response.total ?? nextRows.length);
+            return nextRows;
+        }
+        catch (aggregateError) {
+            if (signal?.aborted)
+                return [];
+            const normalized = normalizeError(aggregateError, "Failed to load record aggregates.");
+            setError(normalized);
+            return [];
+        }
+        finally {
+            if (!signal?.aborted)
+                setIsLoading(false);
+        }
+    }, [client, isEnabled, limit, offset, podId, stableFilters, stableGroupBy, stableMetrics, stableOrderBy, trimmedTableName]);
+    useEffect(() => {
+        if (!isEnabled) {
+            setRows([]);
+            setTotal(0);
+            setSql("");
+            setError(null);
+            setIsLoading(false);
+            return;
+        }
+        if (!autoLoad)
+            return;
+        const controller = new AbortController();
+        void refresh(controller.signal);
+        return () => controller.abort();
+    }, [autoLoad, isEnabled, refresh]);
+    return useMemo(() => ({
+        rows,
+        row: rows[0] ?? null,
+        total,
+        sql,
+        isLoading,
+        error,
+        refresh,
+    }), [error, isLoading, refresh, rows, sql, total]);
+}

package/dist/react/useTaskSession.js

@@ -30,12 +30,13 @@ export function useTaskSession({ client, podId, taskId: externalTaskId = null, a
         }
     }, []);
     const setTaskId = useCallback((nextTaskId) => {
-        abortRef.current?.abort();
-        abortRef.current = null;
         setTaskIdState((currentTaskId) => {
             if (currentTaskId === nextTaskId) {
                 return currentTaskId;
             }
+            abortRef.current?.abort();
+            abortRef.current = null;
+            taskIdRef.current = nextTaskId;
             setError(null);
             setIsStreaming(false);
             if (!nextTaskId) {

package/dist/react/useUpdateFile.d.ts

@@ -0,0 +1,29 @@
+import type { LemmaClient } from "../client.js";
+import type { FileResponse } from "../types.js";
+export interface UpdateFileInput {
+    file?: Blob;
+    name?: string;
+    description?: string;
+    directoryPath?: string;
+    parentId?: string;
+    newPath?: string;
+    searchEnabled?: boolean;
+}
+export interface UseUpdateFileOptions {
+    client: LemmaClient;
+    podId?: string;
+    path?: string | null;
+    enabled?: boolean;
+    onSuccess?: (file: FileResponse) => void;
+    onError?: (error: unknown) => void;
+}
+export interface UseUpdateFileResult<TFile extends FileResponse = FileResponse> {
+    updatedFile: TFile | null;
+    isSubmitting: boolean;
+    error: Error | null;
+    update: (input?: UpdateFileInput, overrides?: {
+        path?: string | null;
+    }) => Promise<TFile | null>;
+    reset: () => void;
+}
+export declare function useUpdateFile<TFile extends FileResponse = FileResponse>({ client, podId, path, enabled, onSuccess, onError, }: UseUpdateFileOptions): UseUpdateFileResult<TFile>;

package/dist/react/useUpdateFile.js

@@ -0,0 +1,51 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { normalizeError, resolvePodClient } from "./utils.js";
+export function useUpdateFile({ client, podId, path = null, enabled = true, onSuccess, onError, }) {
+    const [updatedFile, setUpdatedFile] = 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 trimmedPath = typeof path === "string" ? path.trim() : "";
+    const isEnabled = enabled && trimmedPath.length > 0;
+    const update = useCallback(async (input = {}, overrides = {}) => {
+        const nextPath = typeof overrides.path === "string"
+            ? overrides.path.trim()
+            : trimmedPath;
+        if (!isEnabled || nextPath.length === 0) {
+            return null;
+        }
+        setIsSubmitting(true);
+        setError(null);
+        try {
+            const scopedClient = resolvePodClient(client, podId);
+            const nextFile = await scopedClient.files.update(nextPath, input);
+            setUpdatedFile(nextFile);
+            onSuccessRef.current?.(nextFile);
+            return nextFile;
+        }
+        catch (updateError) {
+            const normalized = normalizeError(updateError, "Failed to update file.");
+            setError(normalized);
+            onErrorRef.current?.(updateError);
+            return null;
+        }
+        finally {
+            setIsSubmitting(false);
+        }
+    }, [client, isEnabled, podId, trimmedPath]);
+    const reset = useCallback(() => {
+        setUpdatedFile(null);
+        setError(null);
+        setIsSubmitting(false);
+    }, []);
+    return useMemo(() => ({
+        updatedFile,
+        isSubmitting,
+        error,
+        update,
+        reset,
+    }), [error, isSubmitting, reset, update, updatedFile]);
+}

package/dist/react/useUploadFile.d.ts

@@ -0,0 +1,24 @@
+import type { LemmaClient } from "../client.js";
+import type { FileResponse } from "../types.js";
+export interface UploadFileInput {
+    name?: string;
+    directoryPath?: string;
+    parentId?: string;
+    searchEnabled?: boolean;
+    description?: string;
+}
+export interface UseUploadFileOptions {
+    client: LemmaClient;
+    podId?: string;
+    enabled?: boolean;
+    onSuccess?: (file: FileResponse) => void;
+    onError?: (error: unknown) => void;
+}
+export interface UseUploadFileResult<TFile extends FileResponse = FileResponse> {
+    uploadedFile: TFile | null;
+    isSubmitting: boolean;
+    error: Error | null;
+    upload: (file: Blob, options?: UploadFileInput) => Promise<TFile | null>;
+    reset: () => void;
+}
+export declare function useUploadFile<TFile extends FileResponse = FileResponse>({ client, podId, enabled, onSuccess, onError, }: UseUploadFileOptions): UseUploadFileResult<TFile>;

package/dist/react/useUploadFile.js

@@ -0,0 +1,46 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { normalizeError, resolvePodClient } from "./utils.js";
+export function useUploadFile({ client, podId, enabled = true, onSuccess, onError, }) {
+    const [uploadedFile, setUploadedFile] = 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 upload = useCallback(async (file, options = {}) => {
+        if (!enabled) {
+            return null;
+        }
+        setIsSubmitting(true);
+        setError(null);
+        try {
+            const scopedClient = resolvePodClient(client, podId);
+            const nextFile = await scopedClient.files.upload(file, options);
+            setUploadedFile(nextFile);
+            onSuccessRef.current?.(nextFile);
+            return nextFile;
+        }
+        catch (uploadError) {
+            const normalized = normalizeError(uploadError, "Failed to upload file.");
+            setError(normalized);
+            onErrorRef.current?.(uploadError);
+            return null;
+        }
+        finally {
+            setIsSubmitting(false);
+        }
+    }, [client, enabled, podId]);
+    const reset = useCallback(() => {
+        setUploadedFile(null);
+        setError(null);
+        setIsSubmitting(false);
+    }, []);
+    return useMemo(() => ({
+        uploadedFile,
+        isSubmitting,
+        error,
+        upload,
+        reset,
+    }), [error, isSubmitting, reset, uploadedFile, upload]);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lemma-sdk",
-  "version": "0.2.34",
+  "version": "0.2.36",
   "description": "Official TypeScript SDK for Lemma pod-scoped APIs",
   "type": "module",
   "main": "dist/index.js",

package/dist/openapi_client/models/AppDescriptorResponse.d.ts

@@ -1,5 +0,0 @@
-export type AppDescriptorResponse = {
-    app_name: string;
-    description: string;
-    operation_count: number;
-};

package/dist/openapi_client/models/OperationListResponse.d.ts

@@ -1,6 +0,0 @@
-import type { OperationSummary } from './OperationSummary.js';
-export type OperationListResponse = {
-    items: Array<OperationSummary>;
-    limit: number;
-    next_page_token?: (string | null);
-};