lemma-sdk 0.2.33 → 0.2.35

package/dist/react/sql-utils.js

@@ -0,0 +1,62 @@
+function quoteIdentifierPart(value) {
+    return `"${value.replace(/"/g, "\"\"")}"`;
+}
+export function quoteIdentifierPath(value) {
+    return value
+        .split(".")
+        .map((part) => (part === "*" ? part : quoteIdentifierPart(part)))
+        .join(".");
+}
+export function isSimpleIdentifierPath(value) {
+    return /^[A-Za-z_][A-Za-z0-9_$]*(\.(\*|[A-Za-z_][A-Za-z0-9_$]*))*$/.test(value);
+}
+export function renderIdentifierPath(value) {
+    return isSimpleIdentifierPath(value) ? quoteIdentifierPath(value) : value;
+}
+export function escapeSqlString(value) {
+    return value.replace(/'/g, "''");
+}
+export function encodeSqlValue(value) {
+    if (value === null || typeof value === "undefined")
+        return "NULL";
+    if (typeof value === "boolean")
+        return value ? "TRUE" : "FALSE";
+    if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+            throw new Error("SQL values must be finite numbers.");
+        }
+        return String(value);
+    }
+    if (typeof value === "bigint")
+        return String(value);
+    if (value instanceof Date)
+        return `'${escapeSqlString(value.toISOString())}'`;
+    if (Array.isArray(value)) {
+        return `(${value.map((entry) => encodeSqlValue(entry)).join(", ")})`;
+    }
+    if (typeof value === "object") {
+        return `'${escapeSqlString(JSON.stringify(value))}'`;
+    }
+    return `'${escapeSqlString(String(value))}'`;
+}
+export function renderRecordFilter(filter) {
+    const field = filter.field?.trim();
+    if (!field) {
+        throw new Error("Record filters require a field.");
+    }
+    const operator = filter.op.trim().toUpperCase();
+    const lhs = renderIdentifierPath(field);
+    const values = Array.isArray(filter.values) ? filter.values : undefined;
+    if ((operator === "IN" || operator === "NOT IN") && values) {
+        return `${lhs} ${operator} ${encodeSqlValue(values)}`;
+    }
+    if ((operator === "IS" || operator === "IS NOT") && typeof filter.value === "undefined") {
+        return `${lhs} ${operator} NULL`;
+    }
+    return `${lhs} ${operator} ${encodeSqlValue(filter.value)}`;
+}
+export function renderRecordFilters(filters) {
+    if (!filters?.length)
+        return "";
+    return filters.map((filter) => `(${renderRecordFilter(filter)})`).join(" AND ");
+}

package/dist/react/useAddPodMember.d.ts

@@ -0,0 +1,22 @@
+import type { LemmaClient } from "../client.js";
+import { PodRole, type PodMember } from "../types.js";
+export interface AddPodMemberInput {
+    organizationMemberId: string;
+    role?: PodRole;
+}
+export interface UseAddPodMemberOptions {
+    client: LemmaClient;
+    podId?: string;
+    enabled?: boolean;
+    defaultRole?: PodRole;
+    onSuccess?: (member: PodMember) => void;
+    onError?: (error: unknown) => void;
+}
+export interface UseAddPodMemberResult {
+    addedMember: PodMember | null;
+    isSubmitting: boolean;
+    error: Error | null;
+    add: (input: AddPodMemberInput) => Promise<PodMember | null>;
+    reset: () => void;
+}
+export declare function useAddPodMember({ client, podId, enabled, defaultRole, onSuccess, onError, }: UseAddPodMemberOptions): UseAddPodMemberResult;

package/dist/react/useAddPodMember.js

@@ -0,0 +1,51 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { PodRole } from "../types.js";
+import { normalizeError, resolvePodId } from "./utils.js";
+export function useAddPodMember({ client, podId, enabled = true, defaultRole = PodRole.POD_USER, onSuccess, onError, }) {
+    const [addedMember, setAddedMember] = 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 add = useCallback(async (input) => {
+        const organizationMemberId = input.organizationMemberId.trim();
+        if (!enabled || organizationMemberId.length === 0) {
+            return null;
+        }
+        setIsSubmitting(true);
+        setError(null);
+        try {
+            const resolvedPodId = resolvePodId(client, podId);
+            const nextMember = await client.podMembers.add(resolvedPodId, {
+                organization_member_id: organizationMemberId,
+                role: input.role ?? defaultRole,
+            });
+            setAddedMember(nextMember);
+            onSuccessRef.current?.(nextMember);
+            return nextMember;
+        }
+        catch (mutationError) {
+            const normalized = normalizeError(mutationError, "Failed to add pod member.");
+            setError(normalized);
+            onErrorRef.current?.(mutationError);
+            return null;
+        }
+        finally {
+            setIsSubmitting(false);
+        }
+    }, [client, defaultRole, enabled, podId]);
+    const reset = useCallback(() => {
+        setAddedMember(null);
+        setError(null);
+        setIsSubmitting(false);
+    }, []);
+    return useMemo(() => ({
+        addedMember,
+        isSubmitting,
+        error,
+        add,
+        reset,
+    }), [add, addedMember, error, isSubmitting, reset]);
+}

package/dist/react/useCreateFolder.d.ts

@@ -0,0 +1,22 @@
+import type { LemmaClient } from "../client.js";
+import type { FileResponse } from "../types.js";
+export interface CreateFolderInput {
+    directoryPath?: string;
+    parentId?: string;
+    description?: string;
+}
+export interface UseCreateFolderOptions {
+    client: LemmaClient;
+    podId?: string;
+    enabled?: boolean;
+    onSuccess?: (folder: FileResponse) => void;
+    onError?: (error: unknown) => void;
+}
+export interface UseCreateFolderResult<TFile extends FileResponse = FileResponse> {
+    createdFolder: TFile | null;
+    isSubmitting: boolean;
+    error: Error | null;
+    createFolder: (name: string, options?: CreateFolderInput) => Promise<TFile | null>;
+    reset: () => void;
+}
+export declare function useCreateFolder<TFile extends FileResponse = FileResponse>({ client, podId, enabled, onSuccess, onError, }: UseCreateFolderOptions): UseCreateFolderResult<TFile>;

package/dist/react/useCreateFolder.js

@@ -0,0 +1,47 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { normalizeError, resolvePodClient } from "./utils.js";
+export function useCreateFolder({ client, podId, enabled = true, onSuccess, onError, }) {
+    const [createdFolder, setCreatedFolder] = 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 createFolder = useCallback(async (name, options = {}) => {
+        const trimmedName = name.trim();
+        if (!enabled || trimmedName.length === 0) {
+            return null;
+        }
+        setIsSubmitting(true);
+        setError(null);
+        try {
+            const scopedClient = resolvePodClient(client, podId);
+            const nextFolder = await scopedClient.files.folder.create(trimmedName, options);
+            setCreatedFolder(nextFolder);
+            onSuccessRef.current?.(nextFolder);
+            return nextFolder;
+        }
+        catch (createError) {
+            const normalized = normalizeError(createError, "Failed to create folder.");
+            setError(normalized);
+            onErrorRef.current?.(createError);
+            return null;
+        }
+        finally {
+            setIsSubmitting(false);
+        }
+    }, [client, enabled, podId]);
+    const reset = useCallback(() => {
+        setCreatedFolder(null);
+        setError(null);
+        setIsSubmitting(false);
+    }, []);
+    return useMemo(() => ({
+        createdFolder,
+        isSubmitting,
+        error,
+        createFolder,
+        reset,
+    }), [createFolder, createdFolder, error, isSubmitting, reset]);
+}

package/dist/react/useDatastoreQuery.d.ts

@@ -0,0 +1,22 @@
+import type { LemmaClient } from "../client.js";
+import type { DatastoreQueryResponse } from "../types.js";
+export interface UseDatastoreQueryOptions {
+    client: LemmaClient;
+    podId?: string;
+    query?: string | null;
+    enabled?: boolean;
+    autoLoad?: boolean;
+}
+export interface UseDatastoreQueryResult<TRow extends Record<string, unknown> = Record<string, unknown>> {
+    response: DatastoreQueryResponse | null;
+    items: TRow[];
+    total: number;
+    sql: string;
+    isLoading: boolean;
+    error: Error | null;
+    refresh: (overrides?: {
+        query?: string | null;
+    }) => Promise<TRow[]>;
+    reset: () => void;
+}
+export declare function useDatastoreQuery<TRow extends Record<string, unknown> = Record<string, unknown>>({ client, podId, query, enabled, autoLoad, }: UseDatastoreQueryOptions): UseDatastoreQueryResult<TRow>;

package/dist/react/useDatastoreQuery.js

@@ -0,0 +1,67 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { normalizeError, resolvePodClient } from "./utils.js";
+export function useDatastoreQuery({ client, podId, query = null, enabled = true, autoLoad = true, }) {
+    const [response, setResponse] = useState(null);
+    const [sql, setSql] = useState("");
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const trimmedQuery = typeof query === "string" ? query.trim() : "";
+    const isEnabled = enabled && trimmedQuery.length > 0;
+    const reset = useCallback(() => {
+        setResponse(null);
+        setSql("");
+        setError(null);
+        setIsLoading(false);
+    }, []);
+    const refresh = useCallback(async (overrides = {}, signal) => {
+        const nextQuery = typeof overrides.query === "string"
+            ? overrides.query.trim()
+            : trimmedQuery;
+        if (!enabled || nextQuery.length === 0) {
+            reset();
+            return [];
+        }
+        setIsLoading(true);
+        setError(null);
+        setSql(nextQuery);
+        try {
+            const scopedClient = resolvePodClient(client, podId);
+            const nextResponse = await scopedClient.datastore.query(nextQuery);
+            if (signal?.aborted)
+                return [];
+            setResponse(nextResponse);
+            return (nextResponse.items ?? []);
+        }
+        catch (queryError) {
+            if (signal?.aborted)
+                return [];
+            setError(normalizeError(queryError, "Failed to execute datastore query."));
+            setResponse(null);
+            return [];
+        }
+        finally {
+            if (!signal?.aborted)
+                setIsLoading(false);
+        }
+    }, [client, enabled, podId, reset, trimmedQuery]);
+    useEffect(() => {
+        if (!isEnabled || !autoLoad) {
+            if (!isEnabled)
+                reset();
+            return;
+        }
+        const controller = new AbortController();
+        void refresh({}, controller.signal);
+        return () => controller.abort();
+    }, [autoLoad, isEnabled, refresh, reset]);
+    return useMemo(() => ({
+        response,
+        items: (response?.items ?? []),
+        total: response?.total ?? 0,
+        sql,
+        isLoading,
+        error,
+        refresh,
+        reset,
+    }), [error, isLoading, refresh, reset, response, sql]);
+}

package/dist/react/useDeleteFile.d.ts

@@ -0,0 +1,19 @@
+import type { LemmaClient } from "../client.js";
+export interface UseDeleteFileOptions {
+    client: LemmaClient;
+    podId?: string;
+    path?: string | null;
+    enabled?: boolean;
+    onSuccess?: (path: string) => void;
+    onError?: (error: unknown) => void;
+}
+export interface UseDeleteFileResult {
+    deletedPath: string | null;
+    isSubmitting: boolean;
+    error: Error | null;
+    remove: (overrides?: {
+        path?: string | null;
+    }) => Promise<boolean>;
+    reset: () => void;
+}
+export declare function useDeleteFile({ client, podId, path, enabled, onSuccess, onError, }: UseDeleteFileOptions): UseDeleteFileResult;

package/dist/react/useDeleteFile.js

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

package/dist/react/useGlobalSearch.d.ts

@@ -0,0 +1,62 @@
+import type { LemmaClient } from "../client.js";
+import type { FileSearchResultSchema, RecordFilter, SearchMethod } from "../types.js";
+export interface GlobalSearchTableSource {
+    key?: string;
+    tableName: string;
+    label?: string;
+    searchFields: string[];
+    displayField?: string;
+    subtitleField?: string;
+    limit?: number;
+    filters?: RecordFilter[];
+}
+export interface GlobalSearchFilesSource {
+    enabled?: boolean;
+    label?: string;
+    limit?: number;
+    searchMethod?: SearchMethod;
+}
+export interface GlobalSearchRecordResult {
+    kind: "record";
+    sourceKey: string;
+    sourceLabel: string;
+    tableName: string;
+    id: string;
+    title: string;
+    subtitle: string | null;
+    record: Record<string, unknown>;
+}
+export interface GlobalSearchFileResult {
+    kind: "file";
+    sourceKey: string;
+    sourceLabel: string;
+    path: string;
+    title: string;
+    subtitle: string | null;
+    result: FileSearchResultSchema;
+}
+export type GlobalSearchResult = GlobalSearchRecordResult | GlobalSearchFileResult;
+export interface UseGlobalSearchOptions {
+    client: LemmaClient;
+    podId?: string;
+    query?: string;
+    tables?: GlobalSearchTableSource[];
+    files?: GlobalSearchFilesSource | false;
+    enabled?: boolean;
+    autoLoad?: boolean;
+    minQueryLength?: number;
+}
+export interface UseGlobalSearchResult {
+    results: GlobalSearchResult[];
+    recordResults: GlobalSearchRecordResult[];
+    fileResults: GlobalSearchFileResult[];
+    totalResults: number;
+    sourceErrors: Record<string, Error>;
+    isLoading: boolean;
+    error: Error | null;
+    search: (overrides?: {
+        query?: string;
+    }) => Promise<GlobalSearchResult[]>;
+    reset: () => void;
+}
+export declare function useGlobalSearch({ client, podId, query, tables, files, enabled, autoLoad, minQueryLength, }: UseGlobalSearchOptions): UseGlobalSearchResult;

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>;