lemma-sdk 0.2.30 → 0.2.32

package/dist/react/useOrganizationMembers.js

@@ -0,0 +1,113 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { normalizeError } from "./utils.js";
+export function useOrganizationMembers({ client, organizationId, 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 trimmedOrganizationId = organizationId.trim();
+    const isEnabled = enabled && trimmedOrganizationId.length > 0;
+    const refresh = useCallback(async (overrides = {}, signal) => {
+        if (!isEnabled) {
+            setMembers([]);
+            setTotal(0);
+            setNextPageToken(null);
+            setError(null);
+            setIsLoading(false);
+            return [];
+        }
+        setIsLoading(true);
+        setError(null);
+        try {
+            const response = await client.organizations.members.list(trimmedOrganizationId, {
+                limit: overrides.limit ?? limit,
+                pageToken: overrides.pageToken ?? pageToken,
+            });
+            if (signal?.aborted)
+                return [];
+            const nextMembers = response.items ?? [];
+            setMembers(nextMembers);
+            setTotal(response.total ?? nextMembers.length);
+            setNextPageToken(response.next_page_token ?? null);
+            return nextMembers;
+        }
+        catch (refreshError) {
+            if (signal?.aborted)
+                return [];
+            const normalized = normalizeError(refreshError, "Failed to load organization members.");
+            setError(normalized);
+            return [];
+        }
+        finally {
+            if (!signal?.aborted)
+                setIsLoading(false);
+        }
+    }, [client, isEnabled, limit, pageToken, trimmedOrganizationId]);
+    const loadMore = useCallback(async (overrides = {}) => {
+        if (!isEnabled || !nextPageToken || isLoading || isLoadingMore) {
+            return [];
+        }
+        setIsLoadingMore(true);
+        setError(null);
+        try {
+            const response = await client.organizations.members.list(trimmedOrganizationId, {
+                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 organization members.");
+            setError(normalized);
+            return [];
+        }
+        finally {
+            setIsLoadingMore(false);
+        }
+    }, [client, isEnabled, isLoading, isLoadingMore, limit, members.length, nextPageToken, trimmedOrganizationId]);
+    useEffect(() => {
+        if (!isEnabled) {
+            setMembers([]);
+            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 organization members."), "Failed to load organization members."));
+                }
+            }
+        })();
+        return () => {
+            cancelled = true;
+            controller.abort();
+        };
+    }, [autoLoad, isEnabled, refresh]);
+    return useMemo(() => ({
+        members,
+        total,
+        nextPageToken,
+        isLoading,
+        isLoadingMore,
+        error,
+        refresh,
+        loadMore,
+    }), [error, isLoading, isLoadingMore, loadMore, members, nextPageToken, refresh, total]);
+}

package/dist/react/usePodAccess.d.ts

@@ -0,0 +1,22 @@
+import type { LemmaClient } from "../client.js";
+import type { PodJoinRequest, PodMember, User } from "../types.js";
+export type PodAccessStatus = "idle" | "checking" | "member" | "missing" | "pending" | "error";
+export interface UsePodAccessOptions {
+    client: LemmaClient;
+    podId?: string;
+    enabled?: boolean;
+    autoLoad?: boolean;
+}
+export interface UsePodAccessResult {
+    status: PodAccessStatus;
+    hasAccess: boolean;
+    user: User | null;
+    member: PodMember | null;
+    joinRequest: PodJoinRequest | null;
+    isLoading: boolean;
+    isRequestingAccess: boolean;
+    error: Error | null;
+    refresh: () => Promise<PodAccessStatus>;
+    requestAccess: () => Promise<PodJoinRequest>;
+}
+export declare function usePodAccess({ client, podId, enabled, autoLoad, }: UsePodAccessOptions): UsePodAccessResult;

package/dist/react/usePodAccess.js

@@ -0,0 +1,128 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { ApiError } from "../http.js";
+import { normalizeError, resolvePodId } from "./utils.js";
+function isMissingAccessError(error) {
+    return error instanceof ApiError && (error.statusCode === 403 || error.statusCode === 404);
+}
+export function usePodAccess({ client, podId, enabled = true, autoLoad = true, }) {
+    const [status, setStatus] = useState("idle");
+    const [user, setUser] = useState(null);
+    const [member, setMember] = useState(null);
+    const [joinRequest, setJoinRequest] = useState(null);
+    const [isLoading, setIsLoading] = useState(false);
+    const [isRequestingAccess, setIsRequestingAccess] = useState(false);
+    const [error, setError] = useState(null);
+    const refresh = useCallback(async () => {
+        if (!enabled) {
+            setStatus("idle");
+            setUser(null);
+            setMember(null);
+            setJoinRequest(null);
+            setError(null);
+            setIsLoading(false);
+            return "idle";
+        }
+        setStatus("checking");
+        setIsLoading(true);
+        setError(null);
+        try {
+            const resolvedPodId = resolvePodId(client, podId);
+            const currentUser = await client.users.current();
+            setUser(currentUser);
+            try {
+                const nextMember = await client.podMembers.get(resolvedPodId, currentUser.id);
+                setMember(nextMember);
+                setJoinRequest(null);
+                setStatus("member");
+                return "member";
+            }
+            catch (membershipError) {
+                if (!isMissingAccessError(membershipError)) {
+                    throw membershipError;
+                }
+            }
+            setMember(null);
+            try {
+                const request = await client.podJoinRequests.me(resolvedPodId);
+                setJoinRequest(request);
+                const nextStatus = request?.status === "PENDING" ? "pending" : "missing";
+                setStatus(nextStatus);
+                return nextStatus;
+            }
+            catch (joinRequestError) {
+                if (!isMissingAccessError(joinRequestError)) {
+                    throw joinRequestError;
+                }
+            }
+            setJoinRequest(null);
+            setStatus("missing");
+            return "missing";
+        }
+        catch (refreshError) {
+            const normalized = normalizeError(refreshError, "Failed to check pod access.");
+            setError(normalized);
+            setStatus("error");
+            return "error";
+        }
+        finally {
+            setIsLoading(false);
+        }
+    }, [client, enabled, podId]);
+    const requestAccess = useCallback(async () => {
+        setIsRequestingAccess(true);
+        setError(null);
+        try {
+            const resolvedPodId = resolvePodId(client, podId);
+            const request = await client.podJoinRequests.create(resolvedPodId);
+            setJoinRequest(request);
+            setMember(null);
+            setStatus(request.status === "PENDING" ? "pending" : "missing");
+            return request;
+        }
+        catch (requestError) {
+            const normalized = normalizeError(requestError, "Failed to request pod access.");
+            setError(normalized);
+            setStatus("error");
+            throw normalized;
+        }
+        finally {
+            setIsRequestingAccess(false);
+        }
+    }, [client, podId]);
+    useEffect(() => {
+        if (!enabled) {
+            setStatus("idle");
+            setUser(null);
+            setMember(null);
+            setJoinRequest(null);
+            setError(null);
+            setIsLoading(false);
+            return;
+        }
+        if (!autoLoad)
+            return;
+        void refresh();
+    }, [autoLoad, enabled, refresh]);
+    return useMemo(() => ({
+        status,
+        hasAccess: status === "member",
+        user,
+        member,
+        joinRequest,
+        isLoading,
+        isRequestingAccess,
+        error,
+        refresh,
+        requestAccess,
+    }), [
+        error,
+        isLoading,
+        isRequestingAccess,
+        joinRequest,
+        member,
+        refresh,
+        requestAccess,
+        status,
+        user,
+    ]);
+}

package/dist/react/useRecord.d.ts

@@ -1,4 +1,20 @@
 import type { LemmaClient } from "../client.js";
+/**
+ * React hook for fetching a single record by ID. Unwraps `.data`
+ * automatically so `record` is the plain object, not the API envelope.
+ *
+ * Perfect for detail panels — pair with `useRecords` for the list.
+ *
+ * @example
+ * ```tsx
+ * const { record, isLoading } = useRecord({
+ *   client,
+ *   tableName: "issues",
+ *   recordId: selectedId,
+ * });
+ * // record is the issue object directly (or null)
+ * ```
+ */
 export interface UseRecordOptions {
     client: LemmaClient;
     podId?: string;

package/dist/react/useRecord.js

@@ -1,14 +1,5 @@
 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);
-}
+import { normalizeError, resolvePodClient } from "./utils.js";
 export function useRecord({ client, podId, tableName, recordId = null, enabled = true, autoLoad = true, }) {
     const [record, setRecord] = useState(null);
     const [isLoading, setIsLoading] = useState(false);
@@ -16,7 +7,7 @@ export function useRecord({ client, podId, tableName, recordId = null, enabled =
     const trimmedTableName = tableName.trim();
     const trimmedRecordId = typeof recordId === "string" ? recordId.trim() : "";
     const isEnabled = enabled && trimmedTableName.length > 0 && trimmedRecordId.length > 0;
-    const refresh = useCallback(async (overrides = {}) => {
+    const refresh = useCallback(async (overrides = {}, signal) => {
         const nextRecordId = typeof overrides.recordId === "string"
             ? overrides.recordId.trim()
             : trimmedRecordId;
@@ -31,17 +22,22 @@ export function useRecord({ client, podId, tableName, recordId = null, enabled =
         try {
             const scopedClient = resolvePodClient(client, podId);
             const response = await scopedClient.records.get(trimmedTableName, nextRecordId);
+            if (signal?.aborted)
+                return null;
             const nextRecord = (response.data ?? null);
             setRecord(nextRecord);
             return nextRecord;
         }
         catch (refreshError) {
+            if (signal?.aborted)
+                return null;
             const normalized = normalizeError(refreshError, "Failed to load record.");
             setError(normalized);
             return null;
         }
         finally {
-            setIsLoading(false);
+            if (!signal?.aborted)
+                setIsLoading(false);
         }
     }, [client, enabled, podId, trimmedRecordId, trimmedTableName]);
     useEffect(() => {
@@ -53,7 +49,22 @@ export function useRecord({ client, podId, tableName, recordId = null, enabled =
         }
         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 record."), "Failed to load record."));
+                }
+            }
+        })();
+        return () => {
+            cancelled = true;
+            controller.abort();
+        };
     }, [autoLoad, isEnabled, refresh]);
     return useMemo(() => ({
         record,

package/dist/react/useRecordForm.d.ts

@@ -1,7 +1,36 @@
 import type { LemmaClient } from "../client.js";
 import { type RecordSchemaField } from "../record-form.js";
-import type { RecordResponse } from "../types.js";
+import type { FunctionRun, RecordResponse } from "../types.js";
 import { type UseRecordSchemaResult } from "./useRecordSchema.js";
+/**
+ * React hook for schema-driven record forms with validation, dirty tracking,
+ * and create/update auto-detection.
+ *
+ * Supports two submit modes:
+ * - `"direct"` (default): persists via `records.create` / `records.update`.
+ * - `"function"`: persists via `functions.runs.create`, routing the form
+ *   payload through a pod function that may enforce business logic
+ *   (e.g. auto-generating identifiers, logging history).
+ *
+ * @example Direct create/update form
+ * ```tsx
+ * const form = useRecordForm({ client, tableName: "issues" });
+ * // form.fields → all schema fields, form.editableFields → user-fillable fields
+ * await form.submit(); // calls records.create or records.update
+ * ```
+ *
+ * @example Function-backed form
+ * ```tsx
+ * const form = useRecordForm({
+ *   client,
+ *   tableName: "issues",
+ *   submitVia: "function",
+ *   submitFunctionName: "create-issue",
+ *   hiddenFields: ["identifier", "created_at"],
+ * });
+ * await form.submit(); // calls functions.runs.create("create-issue", { input: payload })
+ * ```
+ */
 export interface UseRecordFormOptions {
     client: LemmaClient;
     podId?: string;
@@ -11,7 +40,17 @@ export interface UseRecordFormOptions {
     mode?: "auto" | "create" | "update";
     enabled?: boolean;
     autoLoad?: boolean;
-    onSubmitSuccess?: (record: Record<string, unknown>, response: RecordResponse) => void;
+    /** Field names to include in `fields` and `editableFields`. Takes precedence over `hiddenFields`. */
+    visibleFields?: string[];
+    /** Field names to exclude from `fields` and `editableFields`. Ignored for any field also listed in `visibleFields`. */
+    hiddenFields?: string[];
+    /** How the form persists data. `"direct"` calls `records.create`/`records.update`. `"function"` calls `functions.runs.create`. */
+    submitVia?: "direct" | "function";
+    /** Function name to run when `submitVia` is `"function"`. Required when `submitVia` is `"function"`. */
+    submitFunctionName?: string;
+    /** Transforms the form payload before passing it as function input. Receives the validated payload, returns the function input object. */
+    submitFunctionInput?: (payload: Record<string, unknown>) => Record<string, unknown>;
+    onSubmitSuccess?: (record: Record<string, unknown>, response: RecordResponse | FunctionRun) => void;
     onError?: (error: unknown) => void;
 }
 export interface UseRecordFormResult {
@@ -39,4 +78,4 @@ export interface UseRecordFormResult {
         mode?: "create" | "update";
     }) => Promise<Record<string, unknown> | null>;
 }
-export declare function useRecordForm({ client, podId, tableName, recordId, initialValues, mode, enabled, autoLoad, onSubmitSuccess, onError, }: UseRecordFormOptions): UseRecordFormResult;
+export declare function useRecordForm({ client, podId, tableName, recordId, initialValues, mode, enabled, autoLoad, visibleFields, hiddenFields, submitVia, submitFunctionName, submitFunctionInput, onSubmitSuccess, onError, }: UseRecordFormOptions): UseRecordFormResult;

package/dist/react/useRecordForm.js

@@ -1,26 +1,9 @@
 import { useCallback, useEffect, useMemo, useState } from "react";
 import { buildRecordFormValues, buildRecordPayload, } from "../record-form.js";
+import { normalizeError, resolvePodClient, stringifyComparable } from "./utils.js";
 import { useRecordSchema, } from "./useRecordSchema.js";
 const EMPTY_VALUES = {};
-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 stringifyComparable(value) {
-    try {
-        return JSON.stringify(value);
-    }
-    catch {
-        return String(value);
-    }
-}
-export function useRecordForm({ client, podId, tableName, recordId = null, initialValues = EMPTY_VALUES, mode = "auto", enabled = true, autoLoad = true, onSubmitSuccess, onError, }) {
+export function useRecordForm({ client, podId, tableName, recordId = null, initialValues = EMPTY_VALUES, mode = "auto", enabled = true, autoLoad = true, visibleFields, hiddenFields, submitVia = "direct", submitFunctionName, submitFunctionInput, onSubmitSuccess, onError, }) {
     const schema = useRecordSchema({
         client,
         podId,
@@ -28,6 +11,30 @@ export function useRecordForm({ client, podId, tableName, recordId = null, initi
         enabled,
         autoLoad,
     });
+    const visibleSet = useMemo(() => visibleFields ? new Set(visibleFields) : null, [visibleFields]);
+    const hiddenSet = useMemo(() => hiddenFields ? new Set(hiddenFields) : null, [hiddenFields]);
+    const filteredFields = useMemo(() => {
+        if (!visibleSet && !hiddenSet)
+            return schema.fields;
+        return schema.fields.filter((field) => {
+            if (visibleSet)
+                return visibleSet.has(field.name);
+            if (hiddenSet)
+                return !hiddenSet.has(field.name);
+            return true;
+        });
+    }, [hiddenSet, schema.fields, visibleSet]);
+    const filteredEditableFields = useMemo(() => {
+        if (!visibleSet && !hiddenSet)
+            return schema.editableFields;
+        return schema.editableFields.filter((field) => {
+            if (visibleSet)
+                return visibleSet.has(field.name);
+            if (hiddenSet)
+                return !hiddenSet.has(field.name);
+            return true;
+        });
+    }, [hiddenSet, schema.editableFields, visibleSet]);
     const [record, setRecord] = useState(null);
     const [values, setValuesState] = useState({});
     const [baselineValues, setBaselineValues] = useState({});
@@ -164,6 +171,19 @@ export function useRecordForm({ client, podId, tableName, recordId = null, initi
         setRecordError(null);
         try {
             const scopedClient = resolvePodClient(client, podId);
+            if (submitVia === "function") {
+                const functionName = submitFunctionName ?? tableName;
+                const functionInput = submitFunctionInput ? submitFunctionInput(payload.data) : payload.data;
+                const run = await scopedClient.functions.runs.create(functionName, { input: functionInput });
+                const nextRecord = run.output_data ?? { id: run.id, ...functionInput };
+                setRecord(nextRecord);
+                hydrateValues({
+                    ...(nextRecord ?? {}),
+                    ...stableInitialValues,
+                });
+                onSubmitSuccess?.(nextRecord ?? {}, run);
+                return nextRecord;
+            }
             const response = resolvedMode === "update" && recordId
                 ? await scopedClient.records.update(tableName, recordId, payload.data)
                 : await scopedClient.records.create(tableName, payload.data);
@@ -185,14 +205,14 @@ export function useRecordForm({ client, podId, tableName, recordId = null, initi
         finally {
             setIsSubmitting(false);
         }
-    }, [client, hydrateValues, mode, onError, onSubmitSuccess, podId, recordId, schemaTable, stableInitialValues, tableName, values]);
+    }, [client, hydrateValues, mode, onError, onSubmitSuccess, podId, recordId, schemaTable, stableInitialValues, submitFunctionInput, submitFunctionName, submitVia, tableName, values]);
     const isDirty = useMemo(() => {
         return stringifyComparable(values) !== stringifyComparable(baselineValues);
     }, [baselineValues, values]);
     return useMemo(() => ({
         table: schema.table,
-        fields: schema.fields,
-        editableFields: schema.editableFields,
+        fields: filteredFields,
+        editableFields: filteredEditableFields,
         defaults: schema.defaults,
         values,
         baselineValues,
@@ -214,6 +234,8 @@ export function useRecordForm({ client, podId, tableName, recordId = null, initi
     }), [
         baselineValues,
         fieldErrors,
+        filteredEditableFields,
+        filteredFields,
         isDirty,
         isLoadingRecord,
         isSubmitting,
@@ -223,9 +245,7 @@ export function useRecordForm({ client, podId, tableName, recordId = null, initi
         refreshRecord,
         reset,
         schema.defaults,
-        schema.editableFields,
         schema.error,
-        schema.fields,
         schema.isLoading,
         schema.refresh,
         schema.table,

package/dist/react/useRecords.d.ts

@@ -12,7 +12,9 @@ export interface UseRecordsResult<TRecord extends Record<string, unknown> = Reco
     total: number;
     nextPageToken: string | null;
     isLoading: boolean;
+    isLoadingMore: boolean;
     error: Error | null;
     refresh: (overrides?: Partial<ListRecordsOptions>) => Promise<TRecord[]>;
+    loadMore: (overrides?: Partial<ListRecordsOptions>) => Promise<TRecord[]>;
 }
 export declare function useRecords<TRecord extends Record<string, unknown> = Record<string, unknown>>({ client, podId, tableName, filters, sort, limit, pageToken, offset, sortBy, order, params, enabled, autoLoad, }: UseRecordsOptions): UseRecordsResult<TRecord>;