lemma-sdk 0.2.30 → 0.2.32

package/dist/react/useFunctionRuns.js

@@ -0,0 +1,149 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { normalizeError, resolvePodClient } from "./utils.js";
+export function useFunctionRuns({ client, podId, functionName, 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 trimmedFunctionName = functionName.trim();
+    const isEnabled = enabled && trimmedFunctionName.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.functions.runs.list(trimmedFunctionName, {
+                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 function runs.");
+            setError(normalized);
+            return [];
+        }
+        finally {
+            if (!signal?.aborted)
+                setIsLoading(false);
+        }
+    }, [client, initialRunId, isEnabled, limit, pageToken, podId, trimmedFunctionName]);
+    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.functions.runs.list(trimmedFunctionName, {
+                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 function runs.");
+            setError(normalized);
+            return [];
+        }
+        finally {
+            setIsLoadingMore(false);
+        }
+    }, [client, isEnabled, isLoading, isLoadingMore, limit, nextPageToken, podId, trimmedFunctionName]);
+    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 function runs."), "Failed to load function 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/useFunctionSession.js

@@ -1,12 +1,6 @@
-import { useCallback, useEffect, useState } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 import { isTerminalFunctionStatus, normalizeRunStatus, sleep } from "../run-utils.js";
-function resolvePodId(client, podId) {
-    const resolved = podId ?? client.podId;
-    if (!resolved) {
-        throw new Error("podId is required. Pass podId or set it on LemmaClient.");
-    }
-    return resolved;
-}
+import { normalizeError, resolvePodClient, resolvePodId } from "./utils.js";
 function resolveFunctionName(base, override) {
     const resolved = override ?? base;
     if (!resolved) {
@@ -14,17 +8,16 @@ function resolveFunctionName(base, override) {
     }
     return resolved;
 }
-function normalizeError(error, fallback) {
-    if (error instanceof Error)
-        return error;
-    return new Error(fallback);
-}
 export function useFunctionSession({ client, podId, functionName, runId: externalRunId = null, autoPoll = true, pollIntervalMs = 2000, onRun, onError, }) {
     const [runId, setRunIdState] = useState(externalRunId);
     const [run, setRun] = useState(null);
     const [status, setStatus] = useState(undefined);
     const [isPolling, setIsPolling] = 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 setRunId = useCallback((nextRunId) => {
         setRunIdState(nextRunId);
         if (!nextRunId) {
@@ -44,27 +37,27 @@ export function useFunctionSession({ client, podId, functionName, runId: externa
         if (!id)
             return null;
         try {
-            client.setPodId(resolvePodId(client, podId));
+            const scopedClient = resolvePodClient(client, resolvePodId(client, podId));
             const name = resolveFunctionName(functionName);
-            const nextRun = await client.functions.runs.get(name, id);
+            const nextRun = await scopedClient.functions.runs.get(name, id);
             setRun(nextRun);
             const nextStatus = normalizeRunStatus(nextRun.status);
             setStatus(nextStatus);
-            onRun?.(nextRun);
+            onRunRef.current?.(nextRun);
             return nextRun;
         }
         catch (refreshError) {
             const normalized = normalizeError(refreshError, "Failed to fetch function run.");
             setError(normalized);
-            onError?.(refreshError);
+            onErrorRef.current?.(refreshError);
             return null;
         }
-    }, [client, functionName, onError, onRun, podId, runId]);
+    }, [client, functionName, podId, runId]);
     const listHistory = useCallback(async (options = {}) => {
         try {
-            client.setPodId(resolvePodId(client, podId));
+            const scopedClient = resolvePodClient(client, resolvePodId(client, podId));
             const name = resolveFunctionName(functionName, options.functionName);
-            const response = await client.functions.runs.list(name, {
+            const response = await scopedClient.functions.runs.list(name, {
                 limit: options.limit,
                 pageToken: options.pageToken,
             });
@@ -73,32 +66,47 @@ export function useFunctionSession({ client, podId, functionName, runId: externa
         catch (listError) {
             const normalized = normalizeError(listError, "Failed to list function runs.");
             setError(normalized);
-            onError?.(listError);
+            onErrorRef.current?.(listError);
             return [];
         }
-    }, [client, functionName, onError, podId]);
+    }, [client, functionName, podId]);
     const start = useCallback(async (options = {}) => {
         setError(null);
-        client.setPodId(resolvePodId(client, podId));
+        const scopedClient = resolvePodClient(client, resolvePodId(client, podId));
         const name = resolveFunctionName(functionName, options.functionName);
-        const created = await client.functions.runs.create(name, {
+        const created = await scopedClient.functions.runs.create(name, {
             input: options.input,
         });
         setRun(created);
         setRunIdState(created.id);
         const nextStatus = normalizeRunStatus(created.status);
         setStatus(nextStatus);
-        onRun?.(created);
+        onRunRef.current?.(created);
         if (options.connect !== false) {
             await refresh(created.id);
         }
         return created;
-    }, [client, functionName, onRun, podId, refresh]);
+    }, [client, functionName, podId, refresh]);
     useEffect(() => {
         if (!runId) {
             return;
         }
-        void refresh(runId);
+        const controller = new AbortController();
+        let cancelled = false;
+        (async () => {
+            try {
+                await refresh(runId);
+            }
+            catch {
+                if (!cancelled) {
+                    // refresh handles errors internally
+                }
+            }
+        })();
+        return () => {
+            cancelled = true;
+            controller.abort();
+        };
     }, [refresh, runId]);
     useEffect(() => {
         if (!autoPoll || !runId) {
@@ -132,14 +140,14 @@ export function useFunctionSession({ client, podId, functionName, runId: externa
         void loop().catch((pollError) => {
             const normalized = normalizeError(pollError, "Failed while polling function run.");
             setError(normalized);
-            onError?.(pollError);
+            onErrorRef.current?.(pollError);
             setIsPolling(false);
         });
         return () => {
             active = false;
             abortController.abort();
         };
-    }, [autoPoll, onError, pollIntervalMs, refresh, runId]);
+    }, [autoPoll, pollIntervalMs, refresh, runId]);
     return {
         runId,
         run,

package/dist/react/useJoinedRecords.d.ts

@@ -1,9 +1,64 @@
 import type { LemmaClient } from "../client.js";
 import { type JoinedRecordsQueryDefinition } from "../datastore-query.js";
+/**
+ * A simplified join descriptor. The hook auto-resolves the join condition
+ * from the foreign-key metadata on the base table's column named by `on`.
+ */
+export interface JoinedRecordsShorthandJoin {
+    /** The table to join into (e.g. "teams"). */
+    table: string;
+    /**
+     * The FK column on the base table that references the join table
+     * (e.g. "team_id"). The hook reads the FK metadata on this column
+     * to determine the join condition automatically.
+     */
+    on: string;
+    /** Optional alias for the joined table. Defaults to the table name. */
+    alias?: string;
+    /** Join type. Defaults to "left". */
+    type?: "inner" | "left" | "left outer" | "right" | "right outer" | "full" | "full outer";
+}
+/**
+ * React hook for cross-table join queries. Supports two API styles:
+ *
+ * 1. **Full query** via the `query` option — for complex joins with custom
+ *    select lists, filters, and expressions.
+ *
+ * 2. **Shorthand** via `baseTable` + `joins` — the hook auto-resolves the
+ *    join conditions from the schema's foreign-key metadata, so you don't
+ *    need to spell out the `on` condition manually.
+ *
+ * @example Full query (existing API)
+ * ```tsx
+ * const { records, isLoading } = useJoinedRecords({
+ *   client,
+ *   query: {
+ *     from: "issues",
+ *     joins: [{ table: "teams", on: { left: "issues.team_id", right: "teams.id" } }],
+ *   },
+ * });
+ * ```
+ *
+ * @example Shorthand with FK auto-resolution
+ * ```tsx
+ * const { records, isLoading } = useJoinedRecords({
+ *   client,
+ *   baseTable: "issues",
+ *   joins: [{ table: "teams", on: "team_id" }],
+ * });
+ * // The hook reads the FK metadata on issues.team_id to find that
+ * // it references teams.id, and builds the join automatically.
+ * ```
+ */
 export interface UseJoinedRecordsOptions {
     client: LemmaClient;
     podId?: string;
-    query: JoinedRecordsQueryDefinition;
+    /** Full join query definition. Mutually exclusive with `baseTable` + `joins`. */
+    query?: JoinedRecordsQueryDefinition;
+    /** Base table for shorthand mode. Mutually exclusive with `query`. */
+    baseTable?: string;
+    /** Shorthand join descriptors. Auto-resolves join conditions from FK metadata. */
+    joins?: JoinedRecordsShorthandJoin[];
     enabled?: boolean;
     autoLoad?: boolean;
 }
@@ -15,4 +70,4 @@ export interface UseJoinedRecordsResult<TRecord extends Record<string, unknown>
     error: Error | null;
     refresh: () => Promise<TRecord[]>;
 }
-export declare function useJoinedRecords<TRecord extends Record<string, unknown> = Record<string, unknown>>({ client, podId, query, enabled, autoLoad, }: UseJoinedRecordsOptions): UseJoinedRecordsResult<TRecord>;
+export declare function useJoinedRecords<TRecord extends Record<string, unknown> = Record<string, unknown>>({ client, podId, query, baseTable, joins: shorthandJoins, enabled, autoLoad, }: UseJoinedRecordsOptions): UseJoinedRecordsResult<TRecord>;

package/dist/react/useJoinedRecords.js

@@ -1,37 +1,51 @@
 import { useCallback, useEffect, useMemo, useState } from "react";
-import { buildJoinedRecordsQuery } from "../datastore-query.js";
-function resolvePodId(client, podId) {
-    const resolved = podId ?? client.podId;
-    if (!resolved) {
-        throw new Error("podId is required. Pass podId or set it on LemmaClient.");
-    }
-    return resolved;
-}
-function normalizeError(error, fallback) {
-    if (error instanceof Error)
-        return error;
-    return new Error(fallback);
-}
-function stringifyComparable(value) {
-    try {
-        return JSON.stringify(value);
-    }
-    catch {
-        return String(value);
-    }
+import { buildJoinedRecordsQuery, parseForeignKeyReference, } from "../datastore-query.js";
+import { normalizeError, resolvePodId, stringifyComparable } from "./utils.js";
+async function buildShorthandQuery(client, podId, baseTableName, shorthandJoins) {
+    const resolvedPodId = resolvePodId(client, podId);
+    const scopedClient = resolvedPodId === client.podId ? client : client.withPod(resolvedPodId);
+    const baseTable = await scopedClient.tables.get(baseTableName.trim());
+    const joins = await Promise.all(shorthandJoins.map(async (entry) => {
+        const baseColumn = baseTable.columns.find((col) => col.name === entry.on) ?? null;
+        const reference = baseColumn?.foreign_key?.references
+            ? parseForeignKeyReference(baseColumn.foreign_key.references)
+            : null;
+        if (!baseColumn) {
+            throw new Error(`Column "${entry.on}" was not found on table "${baseTableName}".`);
+        }
+        if (!reference) {
+            throw new Error(`Column "${entry.on}" on "${baseTableName}" is not a foreign key. Use the full query API for non-FK joins.`);
+        }
+        return {
+            type: entry.type ?? "left",
+            table: entry.table,
+            alias: entry.alias,
+            on: {
+                left: { table: baseTableName, column: entry.on },
+                right: { table: entry.alias ?? entry.table, column: reference.column },
+            },
+        };
+    }));
+    return {
+        from: { table: baseTableName, alias: baseTableName },
+        joins,
+    };
 }
-export function useJoinedRecords({ client, podId, query, enabled = true, autoLoad = true, }) {
+export function useJoinedRecords({ client, podId, query, baseTable, joins: shorthandJoins, enabled = true, autoLoad = true, }) {
     const [records, setRecords] = useState([]);
     const [total, setTotal] = useState(0);
+    const [sql, setSql] = useState("");
     const [isLoading, setIsLoading] = useState(false);
     const [error, setError] = useState(null);
+    const hasShorthand = !query && !!baseTable && !!shorthandJoins?.length;
     const queryKey = stringifyComparable(query);
+    const shorthandKey = stringifyComparable({ baseTable, shorthandJoins });
     const stableQuery = useMemo(() => query, [queryKey]);
-    const sql = useMemo(() => buildJoinedRecordsQuery(stableQuery), [stableQuery]);
-    const refresh = useCallback(async () => {
+    const refresh = useCallback(async (signal) => {
         if (!enabled) {
             setRecords([]);
             setTotal(0);
+            setSql("");
             setError(null);
             setIsLoading(false);
             return [];
@@ -41,32 +55,68 @@ export function useJoinedRecords({ client, podId, query, enabled = true, autoLoa
         try {
             const resolvedPodId = resolvePodId(client, podId);
             const scopedClient = resolvedPodId === client.podId ? client : client.withPod(resolvedPodId);
-            const response = await scopedClient.datastore.query(sql);
+            let resolvedQuery = stableQuery;
+            if (hasShorthand && baseTable && shorthandJoins) {
+                resolvedQuery = await buildShorthandQuery(client, podId, baseTable, shorthandJoins);
+            }
+            if (!resolvedQuery) {
+                setRecords([]);
+                setTotal(0);
+                setSql("");
+                setIsLoading(false);
+                return [];
+            }
+            if (signal?.aborted)
+                return [];
+            const nextSql = buildJoinedRecordsQuery(resolvedQuery);
+            setSql(nextSql);
+            const response = await scopedClient.datastore.query(nextSql);
+            if (signal?.aborted)
+                return [];
             const nextRecords = (response.items ?? []);
             setRecords(nextRecords);
             setTotal(response.total ?? nextRecords.length);
             return nextRecords;
         }
         catch (refreshError) {
+            if (signal?.aborted)
+                return [];
             const normalized = normalizeError(refreshError, "Failed to load joined records.");
             setError(normalized);
             return [];
         }
         finally {
-            setIsLoading(false);
+            if (!signal?.aborted)
+                setIsLoading(false);
         }
-    }, [client, enabled, podId, sql]);
+    }, [client, enabled, hasShorthand, baseTable, podId, shorthandJoins, stableQuery]);
     useEffect(() => {
         if (!enabled) {
             setRecords([]);
             setTotal(0);
+            setSql("");
             setError(null);
             setIsLoading(false);
             return;
         }
         if (!autoLoad)
             return;
-        void refresh();
+        const controller = new AbortController();
+        let cancelled = false;
+        (async () => {
+            try {
+                await refresh(controller.signal);
+            }
+            catch {
+                if (!cancelled) {
+                    setError(normalizeError(new Error("Failed to load joined records."), "Failed to load joined records."));
+                }
+            }
+        })();
+        return () => {
+            cancelled = true;
+            controller.abort();
+        };
     }, [autoLoad, enabled, refresh]);
     return useMemo(() => ({
         records,

package/dist/react/useMembers.d.ts

@@ -13,10 +13,14 @@ export interface UseMembersResult {
     total: number;
     nextPageToken: string | null;
     isLoading: boolean;
+    isLoadingMore: boolean;
     error: Error | null;
     refresh: (overrides?: {
         limit?: number;
         pageToken?: string;
     }) => Promise<PodMember[]>;
+    loadMore: (overrides?: {
+        limit?: number;
+    }) => Promise<PodMember[]>;
 }
 export declare function useMembers({ client, podId, enabled, autoLoad, limit, pageToken, }: UseMembersOptions): UseMembersResult;

package/dist/react/useMembers.js

@@ -1,23 +1,13 @@
 import { useCallback, useEffect, useMemo, useState } from "react";
-function resolvePodId(client, podId) {
-    const resolved = podId ?? client.podId;
-    if (!resolved) {
-        throw new Error("podId is required. Pass podId or set it on LemmaClient.");
-    }
-    return resolved;
-}
-function normalizeError(error, fallback) {
-    if (error instanceof Error)
-        return error;
-    return new Error(fallback);
-}
+import { normalizeError, resolvePodId } from "./utils.js";
 export function useMembers({ client, podId, enabled = true, autoLoad = true, limit = 100, pageToken, }) {
     const [members, setMembers] = useState([]);
     const [total, setTotal] = useState(0);
     const [nextPageToken, setNextPageToken] = useState(null);
     const [isLoading, setIsLoading] = useState(false);
+    const [isLoadingMore, setIsLoadingMore] = useState(false);
     const [error, setError] = useState(null);
-    const refresh = useCallback(async (overrides = {}) => {
+    const refresh = useCallback(async (overrides = {}, signal) => {
         if (!enabled)
             return [];
         setIsLoading(true);
@@ -28,6 +18,8 @@ export function useMembers({ client, podId, enabled = true, autoLoad = true, lim
                 limit: overrides.limit ?? limit,
                 pageToken: overrides.pageToken ?? pageToken,
             });
+            if (signal?.aborted)
+                return [];
             const nextMembers = response.items ?? [];
             setMembers(nextMembers);
             setTotal(response.total ?? nextMembers.length);
@@ -35,25 +27,72 @@ export function useMembers({ client, podId, enabled = true, autoLoad = true, lim
             return nextMembers;
         }
         catch (refreshError) {
+            if (signal?.aborted)
+                return [];
             const normalized = normalizeError(refreshError, "Failed to load pod members.");
             setError(normalized);
             return [];
         }
         finally {
-            setIsLoading(false);
+            if (!signal?.aborted)
+                setIsLoading(false);
         }
     }, [client, enabled, limit, pageToken, podId]);
+    const loadMore = useCallback(async (overrides = {}) => {
+        if (!enabled || !nextPageToken || isLoading || isLoadingMore) {
+            return [];
+        }
+        setIsLoadingMore(true);
+        setError(null);
+        try {
+            const resolvedPodId = resolvePodId(client, podId);
+            const response = await client.podMembers.list(resolvedPodId, {
+                limit: overrides.limit ?? limit,
+                pageToken: nextPageToken,
+            });
+            const moreMembers = response.items ?? [];
+            setMembers((previous) => [...previous, ...moreMembers]);
+            setTotal(response.total ?? members.length + moreMembers.length);
+            setNextPageToken(response.next_page_token ?? null);
+            return moreMembers;
+        }
+        catch (loadError) {
+            const normalized = normalizeError(loadError, "Failed to load more pod members.");
+            setError(normalized);
+            return [];
+        }
+        finally {
+            setIsLoadingMore(false);
+        }
+    }, [client, enabled, isLoading, isLoadingMore, limit, members.length, nextPageToken, podId]);
     useEffect(() => {
         if (!enabled || !autoLoad)
             return;
-        void refresh();
+        const controller = new AbortController();
+        let cancelled = false;
+        (async () => {
+            try {
+                await refresh({}, controller.signal);
+            }
+            catch {
+                if (!cancelled) {
+                    setError(normalizeError(new Error("Failed to load pod members."), "Failed to load pod members."));
+                }
+            }
+        })();
+        return () => {
+            cancelled = true;
+            controller.abort();
+        };
     }, [autoLoad, enabled, refresh]);
     return useMemo(() => ({
         members,
         total,
         nextPageToken,
         isLoading,
+        isLoadingMore,
         error,
         refresh,
-    }), [error, isLoading, members, nextPageToken, refresh, total]);
+        loadMore,
+    }), [error, isLoading, isLoadingMore, loadMore, members, nextPageToken, refresh, total]);
 }

package/dist/react/useOrganizationMembers.d.ts

@@ -0,0 +1,26 @@
+import type { LemmaClient } from "../client.js";
+import type { OrganizationMember } from "../types.js";
+export interface UseOrganizationMembersOptions {
+    client: LemmaClient;
+    organizationId: string;
+    enabled?: boolean;
+    autoLoad?: boolean;
+    limit?: number;
+    pageToken?: string;
+}
+export interface UseOrganizationMembersResult {
+    members: OrganizationMember[];
+    total: number;
+    nextPageToken: string | null;
+    isLoading: boolean;
+    isLoadingMore: boolean;
+    error: Error | null;
+    refresh: (overrides?: {
+        limit?: number;
+        pageToken?: string;
+    }) => Promise<OrganizationMember[]>;
+    loadMore: (overrides?: {
+        limit?: number;
+    }) => Promise<OrganizationMember[]>;
+}
+export declare function useOrganizationMembers({ client, organizationId, enabled, autoLoad, limit, pageToken, }: UseOrganizationMembersOptions): UseOrganizationMembersResult;