lemma-sdk 0.2.28 → 0.2.30

package/dist/react/useDeleteRecord.d.ts

@@ -0,0 +1,21 @@
+import type { LemmaClient } from "../client.js";
+import type { DatastoreMessageResponse } from "../types.js";
+export interface UseDeleteRecordOptions {
+    client: LemmaClient;
+    podId?: string;
+    tableName: string;
+    recordId?: string | null;
+    enabled?: boolean;
+    onSuccess?: (response: DatastoreMessageResponse) => void;
+    onError?: (error: unknown) => void;
+}
+export interface UseDeleteRecordResult {
+    isSubmitting: boolean;
+    error: Error | null;
+    lastMessage: string | null;
+    remove: (overrides?: {
+        recordId?: string | null;
+    }) => Promise<boolean>;
+    reset: () => void;
+}
+export declare function useDeleteRecord({ client, podId, tableName, recordId, enabled, onSuccess, onError, }: UseDeleteRecordOptions): UseDeleteRecordResult;

package/dist/react/useDeleteRecord.js

@@ -0,0 +1,59 @@
+import { useCallback, 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);
+}
+export function useDeleteRecord({ client, podId, tableName, recordId = null, enabled = true, onSuccess, onError, }) {
+    const [isSubmitting, setIsSubmitting] = useState(false);
+    const [error, setError] = useState(null);
+    const [lastMessage, setLastMessage] = useState(null);
+    const trimmedTableName = tableName.trim();
+    const trimmedRecordId = typeof recordId === "string" ? recordId.trim() : "";
+    const isEnabled = enabled && trimmedTableName.length > 0;
+    const remove = useCallback(async (overrides = {}) => {
+        const nextRecordId = typeof overrides.recordId === "string"
+            ? overrides.recordId.trim()
+            : trimmedRecordId;
+        if (!isEnabled || nextRecordId.length === 0) {
+            const disabledError = new Error("Record deletion requires a table and record ID.");
+            setError(disabledError);
+            return false;
+        }
+        setIsSubmitting(true);
+        setError(null);
+        try {
+            const scopedClient = resolvePodClient(client, podId);
+            const response = await scopedClient.records.delete(trimmedTableName, nextRecordId);
+            setLastMessage(response.message ?? "Record deleted.");
+            onSuccess?.(response);
+            return true;
+        }
+        catch (mutationError) {
+            const normalized = normalizeError(mutationError, "Failed to delete record.");
+            setError(normalized);
+            onError?.(mutationError);
+            return false;
+        }
+        finally {
+            setIsSubmitting(false);
+        }
+    }, [client, isEnabled, onError, onSuccess, podId, trimmedRecordId, trimmedTableName]);
+    const reset = useCallback(() => {
+        setError(null);
+        setIsSubmitting(false);
+        setLastMessage(null);
+    }, []);
+    return useMemo(() => ({
+        isSubmitting,
+        error,
+        lastMessage,
+        remove,
+        reset,
+    }), [error, isSubmitting, lastMessage, remove, reset]);
+}

package/dist/react/useForeignKeyOptions.d.ts

@@ -0,0 +1,31 @@
+import type { LemmaClient } from "../client.js";
+import { type ForeignKeyReference } from "../datastore-query.js";
+import type { ColumnSchema, Table } from "../types.js";
+export interface ForeignKeyOption {
+    value: unknown;
+    label: string;
+    record: Record<string, unknown>;
+}
+export interface UseForeignKeyOptionsOptions {
+    client: LemmaClient;
+    podId?: string;
+    tableName: string;
+    columnName: string;
+    labelField?: string;
+    labelFields?: string[];
+    search?: string;
+    limit?: number;
+    enabled?: boolean;
+    autoLoad?: boolean;
+}
+export interface UseForeignKeyOptionsResult {
+    table: Table | null;
+    column: ColumnSchema | null;
+    reference: ForeignKeyReference | null;
+    labelField: string | null;
+    options: ForeignKeyOption[];
+    isLoading: boolean;
+    error: Error | null;
+    refresh: () => Promise<ForeignKeyOption[]>;
+}
+export declare function useForeignKeyOptions({ client, podId, tableName, columnName, labelField, labelFields, search, limit, enabled, autoLoad, }: UseForeignKeyOptionsOptions): UseForeignKeyOptionsResult;

package/dist/react/useForeignKeyOptions.js

@@ -0,0 +1,150 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { parseForeignKeyReference } from "../datastore-query.js";
+const EMPTY_LABEL_FIELDS = [];
+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 readRecordValue(record, field) {
+    if (!field)
+        return undefined;
+    return record[field];
+}
+function pickResolvedLabelField(records, referenceColumn, explicitLabelField, explicitLabelFields) {
+    const candidates = [
+        explicitLabelField,
+        ...(explicitLabelFields ?? []),
+        "name",
+        "title",
+        "label",
+        "email",
+        "slug",
+        referenceColumn,
+        "id",
+    ].filter((value) => typeof value === "string" && value.trim().length > 0);
+    for (const candidate of candidates) {
+        if (records.some((record) => {
+            const value = record[candidate];
+            return typeof value === "string"
+                ? value.trim().length > 0
+                : typeof value !== "undefined" && value !== null;
+        })) {
+            return candidate;
+        }
+    }
+    return null;
+}
+function matchesSearch(record, search, fields) {
+    const normalized = search.trim().toLowerCase();
+    if (!normalized)
+        return true;
+    return fields.some((field) => {
+        const value = record[field];
+        if (typeof value === "string") {
+            return value.toLowerCase().includes(normalized);
+        }
+        if (typeof value === "number" || typeof value === "boolean") {
+            return String(value).toLowerCase().includes(normalized);
+        }
+        return false;
+    });
+}
+export function useForeignKeyOptions({ client, podId, tableName, columnName, labelField, labelFields = EMPTY_LABEL_FIELDS, search, limit = 50, enabled = true, autoLoad = true, }) {
+    const [table, setTable] = useState(null);
+    const [column, setColumn] = useState(null);
+    const [reference, setReference] = useState(null);
+    const [resolvedLabelField, setResolvedLabelField] = useState(null);
+    const [options, setOptions] = useState([]);
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const labelFieldsKey = useMemo(() => JSON.stringify(labelFields), [labelFields]);
+    const stableLabelFields = useMemo(() => labelFields, [labelFieldsKey]);
+    const refresh = useCallback(async () => {
+        if (!enabled)
+            return [];
+        setIsLoading(true);
+        setError(null);
+        try {
+            const resolvedPodId = resolvePodId(client, podId);
+            const scopedClient = resolvedPodId === client.podId ? client : client.withPod(resolvedPodId);
+            const nextTable = await scopedClient.tables.get(tableName);
+            const nextColumn = nextTable.columns.find((entry) => entry.name === columnName) ?? null;
+            const nextReference = nextColumn?.foreign_key?.references
+                ? parseForeignKeyReference(nextColumn.foreign_key.references)
+                : null;
+            setTable(nextTable);
+            setColumn(nextColumn);
+            setReference(nextReference);
+            if (!nextColumn) {
+                throw new Error(`Column "${columnName}" was not found on table "${tableName}".`);
+            }
+            if (!nextReference) {
+                setResolvedLabelField(null);
+                setOptions([]);
+                return [];
+            }
+            const canFilterOnServer = !!labelField && !!search?.trim();
+            const response = await scopedClient.records.list(nextReference.table, {
+                limit: canFilterOnServer ? Math.max(limit, 100) : (search ? Math.max(limit * 5, 100) : limit),
+                filters: canFilterOnServer
+                    ? [{ field: labelField, op: "ilike", value: `%${search?.trim()}%` }]
+                    : undefined,
+            });
+            const records = response.items ?? [];
+            const nextResolvedLabelField = pickResolvedLabelField(records, nextReference.column, labelField, stableLabelFields);
+            const searchableFields = Array.from(new Set([nextResolvedLabelField, ...stableLabelFields, nextReference.column, "id"]
+                .filter((value) => typeof value === "string" && value.trim().length > 0)));
+            const filteredRecords = canFilterOnServer || !search?.trim()
+                ? records
+                : records.filter((record) => matchesSearch(record, search, searchableFields));
+            const nextOptions = filteredRecords
+                .slice(0, limit)
+                .map((record) => {
+                const value = readRecordValue(record, nextReference.column);
+                const labelValue = readRecordValue(record, nextResolvedLabelField);
+                return {
+                    value,
+                    label: typeof labelValue === "string" && labelValue.trim().length > 0
+                        ? labelValue
+                        : String(value ?? ""),
+                    record,
+                };
+            })
+                .filter((option) => typeof option.value !== "undefined" && option.value !== null);
+            setResolvedLabelField(nextResolvedLabelField);
+            setOptions(nextOptions);
+            return nextOptions;
+        }
+        catch (refreshError) {
+            const normalized = normalizeError(refreshError, "Failed to load foreign key options.");
+            setError(normalized);
+            return [];
+        }
+        finally {
+            setIsLoading(false);
+        }
+    }, [client, columnName, enabled, labelField, limit, podId, search, stableLabelFields, tableName]);
+    useEffect(() => {
+        if (!enabled || !autoLoad)
+            return;
+        void refresh();
+    }, [autoLoad, enabled, refresh]);
+    return useMemo(() => ({
+        table,
+        column,
+        reference,
+        labelField: resolvedLabelField,
+        options,
+        isLoading,
+        error,
+        refresh,
+    }), [column, error, isLoading, options, reference, refresh, resolvedLabelField, table]);
+}

package/dist/react/useJoinedRecords.d.ts

@@ -0,0 +1,18 @@
+import type { LemmaClient } from "../client.js";
+import { type JoinedRecordsQueryDefinition } from "../datastore-query.js";
+export interface UseJoinedRecordsOptions {
+    client: LemmaClient;
+    podId?: string;
+    query: JoinedRecordsQueryDefinition;
+    enabled?: boolean;
+    autoLoad?: boolean;
+}
+export interface UseJoinedRecordsResult<TRecord extends Record<string, unknown> = Record<string, unknown>> {
+    records: TRecord[];
+    total: number;
+    sql: string;
+    isLoading: boolean;
+    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>;

package/dist/react/useJoinedRecords.js

@@ -0,0 +1,79 @@
+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);
+    }
+}
+export function useJoinedRecords({ client, podId, query, enabled = true, autoLoad = true, }) {
+    const [records, setRecords] = useState([]);
+    const [total, setTotal] = useState(0);
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const queryKey = stringifyComparable(query);
+    const stableQuery = useMemo(() => query, [queryKey]);
+    const sql = useMemo(() => buildJoinedRecordsQuery(stableQuery), [stableQuery]);
+    const refresh = useCallback(async () => {
+        if (!enabled) {
+            setRecords([]);
+            setTotal(0);
+            setError(null);
+            setIsLoading(false);
+            return [];
+        }
+        setIsLoading(true);
+        setError(null);
+        try {
+            const resolvedPodId = resolvePodId(client, podId);
+            const scopedClient = resolvedPodId === client.podId ? client : client.withPod(resolvedPodId);
+            const response = await scopedClient.datastore.query(sql);
+            const nextRecords = (response.items ?? []);
+            setRecords(nextRecords);
+            setTotal(response.total ?? nextRecords.length);
+            return nextRecords;
+        }
+        catch (refreshError) {
+            const normalized = normalizeError(refreshError, "Failed to load joined records.");
+            setError(normalized);
+            return [];
+        }
+        finally {
+            setIsLoading(false);
+        }
+    }, [client, enabled, podId, sql]);
+    useEffect(() => {
+        if (!enabled) {
+            setRecords([]);
+            setTotal(0);
+            setError(null);
+            setIsLoading(false);
+            return;
+        }
+        if (!autoLoad)
+            return;
+        void refresh();
+    }, [autoLoad, enabled, refresh]);
+    return useMemo(() => ({
+        records,
+        total,
+        sql,
+        isLoading,
+        error,
+        refresh,
+    }), [error, isLoading, records, refresh, sql, total]);
+}

package/dist/react/useMembers.d.ts

@@ -0,0 +1,22 @@
+import type { LemmaClient } from "../client.js";
+import type { PodMember } from "../types.js";
+export interface UseMembersOptions {
+    client: LemmaClient;
+    podId?: string;
+    enabled?: boolean;
+    autoLoad?: boolean;
+    limit?: number;
+    pageToken?: string;
+}
+export interface UseMembersResult {
+    members: PodMember[];
+    total: number;
+    nextPageToken: string | null;
+    isLoading: boolean;
+    error: Error | null;
+    refresh: (overrides?: {
+        limit?: number;
+        pageToken?: string;
+    }) => Promise<PodMember[]>;
+}
+export declare function useMembers({ client, podId, enabled, autoLoad, limit, pageToken, }: UseMembersOptions): UseMembersResult;

package/dist/react/useMembers.js

@@ -0,0 +1,59 @@
+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);
+}
+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 [error, setError] = useState(null);
+    const refresh = useCallback(async (overrides = {}) => {
+        if (!enabled)
+            return [];
+        setIsLoading(true);
+        setError(null);
+        try {
+            const resolvedPodId = resolvePodId(client, podId);
+            const response = await client.podMembers.list(resolvedPodId, {
+                limit: overrides.limit ?? limit,
+                pageToken: overrides.pageToken ?? pageToken,
+            });
+            const nextMembers = response.items ?? [];
+            setMembers(nextMembers);
+            setTotal(response.total ?? nextMembers.length);
+            setNextPageToken(response.next_page_token ?? null);
+            return nextMembers;
+        }
+        catch (refreshError) {
+            const normalized = normalizeError(refreshError, "Failed to load pod members.");
+            setError(normalized);
+            return [];
+        }
+        finally {
+            setIsLoading(false);
+        }
+    }, [client, enabled, limit, pageToken, podId]);
+    useEffect(() => {
+        if (!enabled || !autoLoad)
+            return;
+        void refresh();
+    }, [autoLoad, enabled, refresh]);
+    return useMemo(() => ({
+        members,
+        total,
+        nextPageToken,
+        isLoading,
+        error,
+        refresh,
+    }), [error, isLoading, members, nextPageToken, refresh, total]);
+}

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,64 @@
+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);
+}
+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 = {}) => {
+        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);
+            const nextRecord = (response.data ?? null);
+            setRecord(nextRecord);
+            return nextRecord;
+        }
+        catch (refreshError) {
+            const normalized = normalizeError(refreshError, "Failed to load record.");
+            setError(normalized);
+            return null;
+        }
+        finally {
+            setIsLoading(false);
+        }
+    }, [client, enabled, podId, trimmedRecordId, trimmedTableName]);
+    useEffect(() => {
+        if (!isEnabled) {
+            setRecord(null);
+            setError(null);
+            setIsLoading(false);
+            return;
+        }
+        if (!autoLoad)
+            return;
+        void refresh();
+    }, [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;