lemma-sdk 0.2.28 → 0.2.31

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

@@ -0,0 +1,18 @@
+import type { LemmaClient } from "../client.js";
+export interface UseRecordOptions {
+    client: LemmaClient;
+    podId?: string;
+    tableName: string;
+    recordId?: string | null;
+    enabled?: boolean;
+    autoLoad?: boolean;
+}
+export interface UseRecordResult<TRecord extends Record<string, unknown> = Record<string, unknown>> {
+    record: TRecord | null;
+    isLoading: boolean;
+    error: Error | null;
+    refresh: (overrides?: {
+        recordId?: string | null;
+    }) => Promise<TRecord | null>;
+}
+export declare function useRecord<TRecord extends Record<string, unknown> = Record<string, unknown>>({ client, podId, tableName, recordId, enabled, autoLoad, }: UseRecordOptions): UseRecordResult<TRecord>;

package/dist/react/useRecord.js

@@ -0,0 +1,75 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+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);
+    const [error, setError] = useState(null);
+    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 = {}, signal) => {
+        const nextRecordId = typeof overrides.recordId === "string"
+            ? overrides.recordId.trim()
+            : trimmedRecordId;
+        if (!enabled || trimmedTableName.length === 0 || nextRecordId.length === 0) {
+            setRecord(null);
+            setError(null);
+            setIsLoading(false);
+            return null;
+        }
+        setIsLoading(true);
+        setError(null);
+        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 {
+            if (!signal?.aborted)
+                setIsLoading(false);
+        }
+    }, [client, enabled, podId, trimmedRecordId, trimmedTableName]);
+    useEffect(() => {
+        if (!isEnabled) {
+            setRecord(null);
+            setError(null);
+            setIsLoading(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 record."), "Failed to load record."));
+                }
+            }
+        })();
+        return () => {
+            cancelled = true;
+            controller.abort();
+        };
+    }, [autoLoad, isEnabled, refresh]);
+    return useMemo(() => ({
+        record,
+        isLoading,
+        error,
+        refresh,
+    }), [error, isLoading, record, refresh]);
+}

package/dist/react/useRecordForm.d.ts

@@ -0,0 +1,42 @@
+import type { LemmaClient } from "../client.js";
+import { type RecordSchemaField } from "../record-form.js";
+import type { RecordResponse } from "../types.js";
+import { type UseRecordSchemaResult } from "./useRecordSchema.js";
+export interface UseRecordFormOptions {
+    client: LemmaClient;
+    podId?: string;
+    tableName: string;
+    recordId?: string | null;
+    initialValues?: Record<string, unknown>;
+    mode?: "auto" | "create" | "update";
+    enabled?: boolean;
+    autoLoad?: boolean;
+    onSubmitSuccess?: (record: Record<string, unknown>, response: RecordResponse) => void;
+    onError?: (error: unknown) => void;
+}
+export interface UseRecordFormResult {
+    table: UseRecordSchemaResult["table"];
+    fields: RecordSchemaField[];
+    editableFields: RecordSchemaField[];
+    defaults: Record<string, unknown>;
+    values: Record<string, unknown>;
+    baselineValues: Record<string, unknown>;
+    record: Record<string, unknown> | null;
+    fieldErrors: Record<string, string>;
+    isLoadingSchema: boolean;
+    isLoadingRecord: boolean;
+    isSubmitting: boolean;
+    isDirty: boolean;
+    error: Error | null;
+    refreshSchema: UseRecordSchemaResult["refresh"];
+    refreshRecord: () => Promise<Record<string, unknown> | null>;
+    refresh: () => Promise<void>;
+    setValue: (fieldName: string, value: unknown) => void;
+    setValues: (values: Record<string, unknown>) => void;
+    reset: (nextValues?: Record<string, unknown>) => void;
+    validate: () => boolean;
+    submit: (overrides?: {
+        mode?: "create" | "update";
+    }) => Promise<Record<string, unknown> | null>;
+}
+export declare function useRecordForm({ client, podId, tableName, recordId, initialValues, mode, enabled, autoLoad, onSubmitSuccess, onError, }: UseRecordFormOptions): UseRecordFormResult;

package/dist/react/useRecordForm.js

@@ -0,0 +1,221 @@
+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 = {};
+export function useRecordForm({ client, podId, tableName, recordId = null, initialValues = EMPTY_VALUES, mode = "auto", enabled = true, autoLoad = true, onSubmitSuccess, onError, }) {
+    const schema = useRecordSchema({
+        client,
+        podId,
+        tableName,
+        enabled,
+        autoLoad,
+    });
+    const [record, setRecord] = useState(null);
+    const [values, setValuesState] = useState({});
+    const [baselineValues, setBaselineValues] = useState({});
+    const [fieldErrors, setFieldErrors] = useState({});
+    const [recordError, setRecordError] = useState(null);
+    const [isLoadingRecord, setIsLoadingRecord] = useState(false);
+    const [isSubmitting, setIsSubmitting] = useState(false);
+    const initialValuesKey = stringifyComparable(initialValues);
+    const stableInitialValues = useMemo(() => initialValues, [initialValuesKey]);
+    const schemaTable = schema.table;
+    const refreshSchema = schema.refresh;
+    const hydrateValues = useCallback((source) => {
+        if (!schemaTable)
+            return;
+        const nextValues = buildRecordFormValues(schemaTable, source);
+        setValuesState(nextValues);
+        setBaselineValues(nextValues);
+        setFieldErrors({});
+    }, [schemaTable]);
+    const refreshRecord = useCallback(async () => {
+        if (!enabled || !recordId) {
+            setRecord(null);
+            return null;
+        }
+        setIsLoadingRecord(true);
+        setRecordError(null);
+        try {
+            const scopedClient = resolvePodClient(client, podId);
+            const response = await scopedClient.records.get(tableName, recordId);
+            const nextRecord = response.data ?? null;
+            setRecord(nextRecord);
+            return nextRecord;
+        }
+        catch (refreshError) {
+            const normalized = normalizeError(refreshError, "Failed to load record.");
+            setRecordError(normalized);
+            onError?.(refreshError);
+            return null;
+        }
+        finally {
+            setIsLoadingRecord(false);
+        }
+    }, [client, enabled, onError, podId, recordId, tableName]);
+    useEffect(() => {
+        if (!enabled) {
+            setRecord(null);
+            setValuesState({});
+            setBaselineValues({});
+            setFieldErrors({});
+            setRecordError(null);
+            setIsLoadingRecord(false);
+            setIsSubmitting(false);
+            return;
+        }
+        if (!autoLoad || !recordId)
+            return;
+        void refreshRecord();
+    }, [autoLoad, enabled, recordId, refreshRecord]);
+    const recordKey = stringifyComparable(record);
+    useEffect(() => {
+        if (!schemaTable)
+            return;
+        const source = {
+            ...(record ?? {}),
+            ...stableInitialValues,
+        };
+        hydrateValues(source);
+    }, [hydrateValues, recordKey, schemaTable, stableInitialValues]);
+    const refresh = useCallback(async () => {
+        const nextTable = await refreshSchema();
+        if (recordId) {
+            const nextRecord = await refreshRecord();
+            if (nextTable && nextRecord) {
+                hydrateValues({
+                    ...nextRecord,
+                    ...stableInitialValues,
+                });
+            }
+            return;
+        }
+        if (nextTable) {
+            hydrateValues(stableInitialValues);
+        }
+    }, [hydrateValues, recordId, refreshRecord, refreshSchema, stableInitialValues]);
+    const setValue = useCallback((fieldName, value) => {
+        setValuesState((current) => ({
+            ...current,
+            [fieldName]: value,
+        }));
+        setFieldErrors((current) => {
+            if (!(fieldName in current))
+                return current;
+            const next = { ...current };
+            delete next[fieldName];
+            return next;
+        });
+    }, []);
+    const setValues = useCallback((nextValues) => {
+        setValuesState((current) => ({
+            ...current,
+            ...nextValues,
+        }));
+    }, []);
+    const reset = useCallback((nextValues) => {
+        if (!schemaTable)
+            return;
+        const source = nextValues ?? {
+            ...(record ?? {}),
+            ...stableInitialValues,
+        };
+        hydrateValues(source);
+    }, [hydrateValues, record, schemaTable, stableInitialValues]);
+    const validate = useCallback(() => {
+        if (!schemaTable)
+            return false;
+        const resolvedMode = mode === "auto" ? (recordId ? "update" : "create") : mode;
+        const result = buildRecordPayload(schemaTable, values, { mode: resolvedMode });
+        setFieldErrors(result.errors);
+        return result.isValid;
+    }, [mode, recordId, schemaTable, values]);
+    const submit = useCallback(async (overrides = {}) => {
+        if (!schemaTable) {
+            const error = new Error("Record schema is not loaded.");
+            setRecordError(error);
+            return null;
+        }
+        const resolvedMode = overrides.mode ?? (mode === "auto" ? (recordId ? "update" : "create") : mode);
+        const payload = buildRecordPayload(schemaTable, values, { mode: resolvedMode });
+        setFieldErrors(payload.errors);
+        if (!payload.isValid) {
+            return null;
+        }
+        setIsSubmitting(true);
+        setRecordError(null);
+        try {
+            const scopedClient = resolvePodClient(client, podId);
+            const response = resolvedMode === "update" && recordId
+                ? await scopedClient.records.update(tableName, recordId, payload.data)
+                : await scopedClient.records.create(tableName, payload.data);
+            const nextRecord = response.data ?? null;
+            setRecord(nextRecord);
+            hydrateValues({
+                ...(nextRecord ?? {}),
+                ...stableInitialValues,
+            });
+            onSubmitSuccess?.(nextRecord ?? {}, response);
+            return nextRecord;
+        }
+        catch (submitError) {
+            const normalized = normalizeError(submitError, "Failed to save record.");
+            setRecordError(normalized);
+            onError?.(submitError);
+            return null;
+        }
+        finally {
+            setIsSubmitting(false);
+        }
+    }, [client, hydrateValues, mode, onError, onSubmitSuccess, podId, recordId, schemaTable, stableInitialValues, tableName, values]);
+    const isDirty = useMemo(() => {
+        return stringifyComparable(values) !== stringifyComparable(baselineValues);
+    }, [baselineValues, values]);
+    return useMemo(() => ({
+        table: schema.table,
+        fields: schema.fields,
+        editableFields: schema.editableFields,
+        defaults: schema.defaults,
+        values,
+        baselineValues,
+        record,
+        fieldErrors,
+        isLoadingSchema: schema.isLoading,
+        isLoadingRecord,
+        isSubmitting,
+        isDirty,
+        error: schema.error ?? recordError,
+        refreshSchema: schema.refresh,
+        refreshRecord,
+        refresh,
+        setValue,
+        setValues,
+        reset,
+        validate,
+        submit,
+    }), [
+        baselineValues,
+        fieldErrors,
+        isDirty,
+        isLoadingRecord,
+        isSubmitting,
+        record,
+        recordError,
+        refresh,
+        refreshRecord,
+        reset,
+        schema.defaults,
+        schema.editableFields,
+        schema.error,
+        schema.fields,
+        schema.isLoading,
+        schema.refresh,
+        schema.table,
+        setValue,
+        setValues,
+        submit,
+        validate,
+        values,
+    ]);
+}

package/dist/react/useRecordSchema.d.ts

@@ -0,0 +1,20 @@
+import type { LemmaClient } from "../client.js";
+import { type RecordSchemaField } from "../record-form.js";
+import type { Table } from "../types.js";
+export interface UseRecordSchemaOptions {
+    client: LemmaClient;
+    podId?: string;
+    tableName: string;
+    enabled?: boolean;
+    autoLoad?: boolean;
+}
+export interface UseRecordSchemaResult {
+    table: Table | null;
+    fields: RecordSchemaField[];
+    editableFields: RecordSchemaField[];
+    defaults: Record<string, unknown>;
+    isLoading: boolean;
+    error: Error | null;
+    refresh: () => Promise<Table | null>;
+}
+export declare function useRecordSchema({ client, podId, tableName, enabled, autoLoad, }: UseRecordSchemaOptions): UseRecordSchemaResult;

package/dist/react/useRecordSchema.js

@@ -0,0 +1,24 @@
+import { useMemo } from "react";
+import { buildRecordFormValues, buildRecordSchemaFields, getEditableRecordFields, } from "../record-form.js";
+import { useTable } from "./useTable.js";
+export function useRecordSchema({ client, podId, tableName, enabled = true, autoLoad = true, }) {
+    const tableState = useTable({
+        client,
+        podId,
+        tableName,
+        enabled,
+        autoLoad,
+    });
+    const fields = useMemo(() => (tableState.table ? buildRecordSchemaFields(tableState.table) : []), [tableState.table]);
+    const editableFields = useMemo(() => (tableState.table ? getEditableRecordFields(tableState.table) : []), [tableState.table]);
+    const defaults = useMemo(() => (tableState.table ? buildRecordFormValues(tableState.table) : {}), [tableState.table]);
+    return useMemo(() => ({
+        table: tableState.table,
+        fields,
+        editableFields,
+        defaults,
+        isLoading: tableState.isLoading,
+        error: tableState.error,
+        refresh: tableState.refresh,
+    }), [defaults, editableFields, fields, tableState.error, tableState.isLoading, tableState.refresh, tableState.table]);
+}

package/dist/react/useRecords.d.ts

@@ -0,0 +1,20 @@
+import type { LemmaClient } from "../client.js";
+import type { ListRecordsOptions } from "../types.js";
+export interface UseRecordsOptions extends ListRecordsOptions {
+    client: LemmaClient;
+    podId?: string;
+    tableName: string;
+    enabled?: boolean;
+    autoLoad?: boolean;
+}
+export interface UseRecordsResult<TRecord extends Record<string, unknown> = Record<string, unknown>> {
+    records: TRecord[];
+    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>;