@geniee-inc/sfa-kit 1.6.0

package/src/lib/components/RecordList.js

@@ -0,0 +1,139 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useMemo, useRef } from 'react';
+import { useRecordList } from '../hooks/useRecordList';
+import { color, font, radius, space, baseContainerStyle, baseButtonStyle, } from '../theme';
+import { SFA_KIT_VERSION } from '../version';
+import { FieldRenderer } from './FieldRenderer';
+const MAX_AUTO_COLUMNS = 8;
+/**
+ * @description Fetches and displays a paginated list of SFA/CRM records as a table.
+ */
+export function RecordList({ collection, columns, params, pageSize = 20, showPagination = true, onRowClick, onError, }) {
+    const listParams = useMemo(() => (Object.assign(Object.assign({}, params), { limit: pageSize })), [params, pageSize]);
+    const { items, totalCount, hasMore, pageIndex, isLoading, error, goToPage } = useRecordList(collection, listParams);
+    // Use a ref so inline onError callbacks don't re-fire the effect on
+    // every parent render when error is present.
+    const onErrorRef = useRef(onError);
+    onErrorRef.current = onError;
+    useEffect(() => {
+        var _a;
+        if (error)
+            (_a = onErrorRef.current) === null || _a === void 0 ? void 0 : _a.call(onErrorRef, error);
+    }, [error]);
+    if (error) {
+        return (_jsxs("div", { style: styles.container, children: [_jsx("div", { style: styles.error, children: error.message }), _jsxs("div", { style: styles.versionFooter, children: ["@geniee-inc/sfa-kit v", SFA_KIT_VERSION] })] }));
+    }
+    const resolvedColumns = columns !== null && columns !== void 0 ? columns : autoDetectColumns(items);
+    const totalPages = Math.max(1, Math.ceil(totalCount / pageSize));
+    const rangeStart = pageIndex * pageSize + 1;
+    const rangeEnd = Math.min((pageIndex + 1) * pageSize, totalCount);
+    return (_jsxs("div", { style: styles.container, children: [_jsxs("div", { style: styles.header, children: [_jsx("span", { style: styles.collectionName, children: collection }), !isLoading && _jsxs("span", { style: styles.count, children: [totalCount, " records"] })] }), _jsx("div", { style: styles.tableWrapper, children: _jsxs("table", { style: styles.table, children: [_jsx("thead", { children: _jsx("tr", { children: resolvedColumns.map(col => {
+                                    var _a;
+                                    return (_jsx("th", { style: Object.assign(Object.assign({}, styles.th), { width: col.width }), children: (_a = col.header) !== null && _a !== void 0 ? _a : col.fieldName }, col.fieldName));
+                                }) }) }), _jsxs("tbody", { children: [isLoading && (_jsx("tr", { children: _jsx("td", { colSpan: resolvedColumns.length, style: styles.loadingCell, children: "Loading..." }) })), !isLoading && items.length === 0 && (_jsx("tr", { children: _jsx("td", { colSpan: resolvedColumns.length, style: styles.emptyCell, children: "No records found" }) })), !isLoading &&
+                                    items.length > 0 &&
+                                    items.map(record => (_jsx("tr", { style: onRowClick ? styles.clickableRow : styles.row, onClick: onRowClick ? () => onRowClick(record) : undefined, children: resolvedColumns.map(col => {
+                                            const fieldValue = record.fields[col.fieldName];
+                                            return (_jsx("td", { style: styles.td, children: fieldValue ? (_jsx(FieldRenderer, { fieldValue: fieldValue, fieldName: col.fieldName })) : (_jsx("span", { style: styles.emptyValue, children: "\u2014" })) }, col.fieldName));
+                                        }) }, record.record_id)))] })] }) }), showPagination && totalCount > 0 && (_jsxs("div", { style: styles.pagination, children: [_jsx("button", { style: styles.pageButton, disabled: pageIndex === 0 || isLoading, onClick: () => goToPage(pageIndex - 1), type: "button", children: "Prev" }), _jsxs("span", { style: styles.pageInfo, children: ["Page ", pageIndex + 1, " of ", totalPages] }), _jsx("button", { style: styles.pageButton, disabled: !hasMore || isLoading, onClick: () => goToPage(pageIndex + 1), type: "button", children: "Next" }), _jsxs("span", { style: styles.rangeInfo, children: ["Showing ", rangeStart, "-", rangeEnd, " of ", totalCount] })] })), _jsxs("div", { style: styles.versionFooter, children: ["@geniee-inc/sfa-kit v", SFA_KIT_VERSION] })] }));
+}
+function autoDetectColumns(items) {
+    const first = items[0];
+    if (!first)
+        return [];
+    return Object.keys(first.fields)
+        .slice(0, MAX_AUTO_COLUMNS)
+        .map(fieldName => ({ fieldName }));
+}
+const styles = {
+    container: Object.assign(Object.assign({}, baseContainerStyle), { margin: `${space.lg}px auto`, padding: space.lg, border: `1px solid ${color.border}`, borderRadius: radius.sm, backgroundColor: color.bgSurface }),
+    header: {
+        display: 'flex',
+        justifyContent: 'space-between',
+        alignItems: 'center',
+        marginBottom: space.sm,
+    },
+    collectionName: {
+        fontSize: font.sizeXl,
+        fontWeight: font.weightMedium,
+    },
+    count: {
+        fontSize: font.sizeMd,
+        color: color.textSecondary,
+    },
+    tableWrapper: {
+        overflowX: 'auto',
+    },
+    table: {
+        width: '100%',
+        borderCollapse: 'collapse',
+        fontSize: font.sizeMd,
+    },
+    th: {
+        textAlign: 'left',
+        padding: `${space.sm}px ${space.sm}px`,
+        borderBottom: `2px solid ${color.border}`,
+        fontWeight: font.weightMedium,
+        color: color.textSecondary,
+        fontSize: font.sizeSm,
+        whiteSpace: 'nowrap',
+    },
+    row: {
+        borderBottom: `1px solid ${color.borderLight}`,
+    },
+    clickableRow: {
+        borderBottom: `1px solid ${color.borderLight}`,
+        cursor: 'pointer',
+    },
+    td: {
+        padding: `${space.sm}px ${space.sm}px`,
+        verticalAlign: 'top',
+        maxWidth: 300,
+        overflow: 'hidden',
+        textOverflow: 'ellipsis',
+    },
+    loadingCell: {
+        padding: space.xl,
+        textAlign: 'center',
+        color: color.textMuted,
+    },
+    emptyCell: {
+        padding: space.xl,
+        textAlign: 'center',
+        color: color.textMuted,
+    },
+    emptyValue: {
+        color: color.textMuted,
+    },
+    pagination: {
+        display: 'flex',
+        alignItems: 'center',
+        gap: space.sm,
+        marginTop: space.sm,
+        fontSize: font.sizeMd,
+        color: color.textSecondary,
+    },
+    pageButton: Object.assign(Object.assign({}, baseButtonStyle), { padding: `${space.xs}px ${space.sm}px`, border: `1px solid ${color.border}`, backgroundColor: color.bgSurface, color: color.textPrimary }),
+    pageInfo: {
+        fontWeight: font.weightMedium,
+    },
+    rangeInfo: {
+        marginLeft: 'auto',
+        fontSize: font.sizeSm,
+        color: color.textMuted,
+    },
+    error: {
+        padding: space.sm,
+        backgroundColor: color.errorLight,
+        border: `1px solid ${color.error}`,
+        borderRadius: radius.sm,
+        color: color.error,
+        fontSize: font.sizeMd,
+    },
+    versionFooter: {
+        textAlign: 'right',
+        fontSize: font.sizeXs,
+        color: color.textMuted,
+        marginTop: space.sm,
+    },
+};

package/src/lib/components/RecordView.d.ts

@@ -0,0 +1,14 @@
+import type { FieldGroupSpec } from '../provider/types';
+interface RecordViewProps {
+    readonly collection: string;
+    readonly recordId: string;
+    readonly title?: string;
+    readonly fields?: readonly string[];
+    readonly fieldGroups?: readonly FieldGroupSpec[];
+    readonly onError?: (error: Error) => void;
+}
+/**
+ * @description Fetches and displays a single SFA/CRM record in a label-value grid.
+ */
+export declare function RecordView({ collection, recordId, title, fields, fieldGroups, onError, }: RecordViewProps): JSX.Element;
+export {};

package/src/lib/components/RecordView.js

@@ -0,0 +1,153 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef } from 'react';
+import { useRecord } from '../hooks/useRecord';
+import { color, font, radius, space, baseContainerStyle } from '../theme';
+import { SFA_KIT_VERSION } from '../version';
+import { FieldRenderer } from './FieldRenderer';
+/**
+ * @description Fetches and displays a single SFA/CRM record in a label-value grid.
+ */
+export function RecordView({ collection, recordId, title, fields, fieldGroups, onError, }) {
+    var _a;
+    const { record, isLoading, error } = useRecord(collection, recordId);
+    // Use a ref so inline onError callbacks don't re-fire the effect on
+    // every parent render when error is present.
+    const onErrorRef = useRef(onError);
+    onErrorRef.current = onError;
+    useEffect(() => {
+        var _a;
+        if (error)
+            (_a = onErrorRef.current) === null || _a === void 0 ? void 0 : _a.call(onErrorRef, error);
+    }, [error]);
+    if (error) {
+        return (_jsxs("div", { style: styles.container, children: [_jsx("div", { style: styles.error, children: error.message }), _jsxs("div", { style: styles.versionFooter, children: ["@geniee-inc/sfa-kit v", SFA_KIT_VERSION] })] }));
+    }
+    if (isLoading || !record) {
+        return (_jsxs("div", { style: styles.container, children: [_jsx("div", { style: styles.loading, children: "Loading..." }), _jsxs("div", { style: styles.versionFooter, children: ["@geniee-inc/sfa-kit v", SFA_KIT_VERSION] })] }));
+    }
+    const displayTitle = (_a = title !== null && title !== void 0 ? title : record.title) !== null && _a !== void 0 ? _a : buildTitle(record.fields, record.titleFields);
+    const hasGroups = fieldGroups && fieldGroups.length > 0;
+    return (_jsxs("div", { style: styles.container, children: [displayTitle && _jsx("h2", { style: styles.title, children: displayTitle }), _jsxs("div", { style: styles.meta, children: [collection, " / ", record.record_id] }), hasGroups
+                ? renderFieldGroups(record.fields, fieldGroups)
+                : renderFlatFields(record.fields, fields), _jsxs("div", { style: styles.versionFooter, children: ["@geniee-inc/sfa-kit v", SFA_KIT_VERSION] })] }));
+}
+const LAYOUT_COLUMNS = {
+    '1-col': 1,
+    '2-col': 2,
+    '3-col': 3,
+};
+function renderFlatFields(mapping, fields) {
+    const entries = getFieldEntries(mapping, fields);
+    if (entries.length === 0) {
+        return _jsx("div", { style: styles.empty, children: "No fields to display" });
+    }
+    return (_jsx("div", { style: styles.grid, children: entries.map(([name, value]) => (_jsxs("div", { style: styles.row, children: [_jsx("div", { style: styles.label, children: name }), _jsx("div", { style: styles.value, children: _jsx(FieldRenderer, { fieldValue: value, fieldName: name }) })] }, name))) }));
+}
+function renderFieldGroups(mapping, groups) {
+    return (_jsx("div", { style: styles.groupsContainer, children: groups.map((group, groupIndex) => {
+            var _a;
+            const entries = getFieldEntries(mapping, group.fields);
+            if (entries.length === 0)
+                return null;
+            const columnCount = LAYOUT_COLUMNS[(_a = group.layout) !== null && _a !== void 0 ? _a : '1-col'];
+            const gridStyle = {
+                display: 'grid',
+                gridTemplateColumns: `repeat(${columnCount}, 1fr)`,
+                gap: '0 24px',
+            };
+            return (_jsxs("div", { style: styles.group, children: [group.title && _jsx("h4", { style: styles.groupTitle, children: group.title }), _jsx("div", { style: gridStyle, children: entries.map(([name, value]) => (_jsxs("div", { style: styles.row, children: [_jsx("div", { style: styles.label, children: name }), _jsx("div", { style: styles.value, children: _jsx(FieldRenderer, { fieldValue: value, fieldName: name }) })] }, name))) })] }, groupIndex));
+        }) }));
+}
+function buildTitle(mapping, titleFields) {
+    return titleFields
+        .map(name => { var _a; return (_a = mapping[name]) === null || _a === void 0 ? void 0 : _a.label; })
+        .filter(Boolean)
+        .join(' ');
+}
+function getFieldEntries(mapping, fields) {
+    if (fields) {
+        return fields
+            .filter(name => mapping[name] != null)
+            .map(name => [name, mapping[name]]);
+    }
+    return Object.entries(mapping);
+}
+const styles = {
+    container: Object.assign(Object.assign({}, baseContainerStyle), { maxWidth: 720, margin: `${space.lg}px auto`, padding: space.lg, border: `1px solid ${color.border}`, borderRadius: radius.sm, backgroundColor: color.bgSurface }),
+    title: {
+        fontSize: font.sizeTitle,
+        fontWeight: font.weightMedium,
+        margin: '0 0 4px',
+    },
+    meta: {
+        fontSize: font.sizeSm,
+        color: color.textMuted,
+        fontFamily: 'monospace',
+        marginBottom: space.md,
+    },
+    grid: {
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 0,
+    },
+    row: {
+        display: 'flex',
+        padding: `${space.sm}px 0`,
+        borderBottom: `1px solid ${color.borderLight}`,
+        gap: space.md,
+        fontSize: font.sizeLg,
+    },
+    label: {
+        fontWeight: font.weightRegular,
+        color: color.textSecondary,
+        minWidth: 180,
+        flexShrink: 0,
+        fontSize: font.sizeSm,
+    },
+    value: {
+        color: color.textPrimary,
+        wordBreak: 'break-all',
+        flex: 1,
+    },
+    groupsContainer: {
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 20,
+    },
+    group: {
+        borderTop: `1px solid ${color.border}`,
+        paddingTop: space.sm,
+    },
+    groupTitle: {
+        fontSize: font.sizeMd,
+        fontWeight: font.weightMedium,
+        color: color.textPrimary,
+        margin: `0 0 ${space.sm}px`,
+    },
+    loading: {
+        padding: space.lg,
+        textAlign: 'center',
+        color: color.textMuted,
+        fontSize: font.sizeLg,
+    },
+    error: {
+        padding: space.sm,
+        backgroundColor: color.errorLight,
+        border: `1px solid ${color.error}`,
+        borderRadius: radius.sm,
+        color: color.error,
+        fontSize: font.sizeMd,
+    },
+    empty: {
+        padding: space.lg,
+        textAlign: 'center',
+        color: color.textMuted,
+        fontSize: font.sizeLg,
+    },
+    versionFooter: {
+        textAlign: 'right',
+        fontSize: font.sizeXs,
+        color: color.textMuted,
+        marginTop: space.sm,
+    },
+};

package/src/lib/errors.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @description sfa-kit のユーザー向けエラーメッセージ定数。
+ * AI 生成ページ内で表示されるため、日本語で記載する。
+ */
+/** SfaProvider コンテキスト外で hook が使用された場合 */
+export declare const ERR_NO_PROVIDER = "SfaProvider \u304C\u898B\u3064\u304B\u308A\u307E\u305B\u3093\u3002\u3053\u306E\u30D5\u30C3\u30AF\u306F SfaProvider \u306E\u5185\u90E8\u3067\u4F7F\u7528\u3057\u3066\u304F\u3060\u3055\u3044\u3002";
+/**
+ * プレビューモード（JAI Studio）で書き込み操作が試行された場合。
+ * 本番の SFA/CRM に埋め込まれたページでのみ書き込みが許可される。
+ */
+export declare const ERR_READ_ONLY = "\u66F8\u304D\u8FBC\u307F\u64CD\u4F5C\u306F\u30D7\u30EC\u30D3\u30E5\u30FC\u30E2\u30FC\u30C9\u3067\u306F\u7121\u52B9\u3067\u3059\u3002\u30C7\u30FC\u30BF\u3092\u5909\u66F4\u3059\u308B\u306B\u306F\u3001\u3053\u306E\u30DA\u30FC\u30B8\u3092 GENIEE SFA/CRM \u306B\u30A2\u30C3\u30D7\u30ED\u30FC\u30C9\u3057\u3066\u3054\u5229\u7528\u304F\u3060\u3055\u3044\u3002";
+/** proxy モードで mutation メソッドが呼ばれた場合（開発者向け） */
+export declare const ERR_DIRECT_MODE_REQUIRED = "\u3053\u306E\u64CD\u4F5C\u306F direct \u30E2\u30FC\u30C9\uFF08Keystone v1 API\uFF09\u3067\u306E\u307F\u5229\u7528\u53EF\u80FD\u3067\u3059\u3002";
+/** record_id が空の状態で API 呼び出しが試行された場合 */
+export declare const ERR_EMPTY_RECORD_ID = "\u30EC\u30B3\u30FC\u30C9 ID \u304C\u6307\u5B9A\u3055\u308C\u3066\u3044\u307E\u305B\u3093\u3002\u8868\u793A\u3059\u308B\u30EC\u30B3\u30FC\u30C9\u3092\u9078\u629E\u3057\u3066\u304F\u3060\u3055\u3044\u3002";

package/src/lib/errors.js

@@ -0,0 +1,15 @@
+/**
+ * @description sfa-kit のユーザー向けエラーメッセージ定数。
+ * AI 生成ページ内で表示されるため、日本語で記載する。
+ */
+/** SfaProvider コンテキスト外で hook が使用された場合 */
+export const ERR_NO_PROVIDER = 'SfaProvider が見つかりません。このフックは SfaProvider の内部で使用してください。';
+/**
+ * プレビューモード（JAI Studio）で書き込み操作が試行された場合。
+ * 本番の SFA/CRM に埋め込まれたページでのみ書き込みが許可される。
+ */
+export const ERR_READ_ONLY = '書き込み操作はプレビューモードでは無効です。データを変更するには、このページを GENIEE SFA/CRM にアップロードしてご利用ください。';
+/** proxy モードで mutation メソッドが呼ばれた場合（開発者向け） */
+export const ERR_DIRECT_MODE_REQUIRED = 'この操作は direct モード（Keystone v1 API）でのみ利用可能です。';
+/** record_id が空の状態で API 呼び出しが試行された場合 */
+export const ERR_EMPTY_RECORD_ID = 'レコード ID が指定されていません。表示するレコードを選択してください。';

package/src/lib/hooks/useCreateRecord.d.ts

@@ -0,0 +1,17 @@
+import type { SfaCreateOptions, SfaRecord } from '../provider/types';
+export interface UseCreateRecordResult {
+    /** Call to create a new record. Returns the created record with its version. */
+    readonly create: (fields: Record<string, unknown>, options?: SfaCreateOptions) => Promise<SfaRecord>;
+    /** The most recently created record, or null before the first create. */
+    readonly data: SfaRecord | null;
+    readonly isLoading: boolean;
+    readonly error: Error | null;
+    /** Reset data and error state to initial values. */
+    readonly reset: () => void;
+}
+/**
+ * @description Imperative hook for creating a single record. Unlike query
+ * hooks, this does not auto-fetch on mount. Call `create(fields)` to trigger
+ * the POST and track loading/error/data state.
+ */
+export declare function useCreateRecord(collection: string): UseCreateRecordResult;

package/src/lib/hooks/useCreateRecord.js

@@ -0,0 +1,48 @@
+import { __awaiter } from "tslib";
+import { useCallback, useRef, useState } from 'react';
+import { ERR_READ_ONLY } from '../errors';
+import { useSfaContext } from '../provider/useSfaClient';
+/**
+ * @description Imperative hook for creating a single record. Unlike query
+ * hooks, this does not auto-fetch on mount. Call `create(fields)` to trigger
+ * the POST and track loading/error/data state.
+ */
+export function useCreateRecord(collection) {
+    const { client, readOnly } = useSfaContext();
+    const [data, setData] = useState(null);
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const callId = useRef(0);
+    const create = useCallback((fields, options) => __awaiter(this, void 0, void 0, function* () {
+        callId.current += 1;
+        const currentCallId = callId.current;
+        if (readOnly) {
+            throw new Error(ERR_READ_ONLY);
+        }
+        setIsLoading(true);
+        setError(null);
+        try {
+            const record = yield client.create(collection, fields, options);
+            if (currentCallId === callId.current) {
+                setData(record);
+                setIsLoading(false);
+            }
+            return record;
+        }
+        catch (e) {
+            if (currentCallId === callId.current) {
+                const err = e instanceof Error ? e : new Error(String(e));
+                setError(err);
+                setIsLoading(false);
+            }
+            throw e;
+        }
+    }), [client, collection, readOnly]);
+    const reset = useCallback(() => {
+        callId.current += 1;
+        setData(null);
+        setError(null);
+        setIsLoading(false);
+    }, []);
+    return { create, data, isLoading, error, reset };
+}

package/src/lib/hooks/useDeleteRecord.d.ts

@@ -0,0 +1,16 @@
+export interface UseDeleteRecordResult {
+    /** Call to delete a record. Requires the record's current version for optimistic locking. */
+    readonly remove: (recordId: string, version: string) => Promise<void>;
+    readonly isLoading: boolean;
+    readonly error: Error | null;
+    /** True after a successful delete, until reset() is called. */
+    readonly isSuccess: boolean;
+    /** Reset error and success state to initial values. */
+    readonly reset: () => void;
+}
+/**
+ * @description Imperative hook for deleting a single record with optimistic
+ * locking. Tracks loading, error, and success state. DELETE returns no body
+ * (204), so this hook exposes `isSuccess` instead of `data`.
+ */
+export declare function useDeleteRecord(collection: string): UseDeleteRecordResult;

package/src/lib/hooks/useDeleteRecord.js

@@ -0,0 +1,48 @@
+import { __awaiter } from "tslib";
+import { useCallback, useRef, useState } from 'react';
+import { ERR_READ_ONLY } from '../errors';
+import { useSfaContext } from '../provider/useSfaClient';
+/**
+ * @description Imperative hook for deleting a single record with optimistic
+ * locking. Tracks loading, error, and success state. DELETE returns no body
+ * (204), so this hook exposes `isSuccess` instead of `data`.
+ */
+export function useDeleteRecord(collection) {
+    const { client, readOnly } = useSfaContext();
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const [isSuccess, setIsSuccess] = useState(false);
+    const callId = useRef(0);
+    const remove = useCallback((recordId, version) => __awaiter(this, void 0, void 0, function* () {
+        callId.current += 1;
+        const currentCallId = callId.current;
+        if (readOnly) {
+            throw new Error(ERR_READ_ONLY);
+        }
+        setIsLoading(true);
+        setError(null);
+        setIsSuccess(false);
+        try {
+            yield client.delete(collection, recordId, version);
+            if (currentCallId === callId.current) {
+                setIsSuccess(true);
+                setIsLoading(false);
+            }
+        }
+        catch (e) {
+            if (currentCallId === callId.current) {
+                const err = e instanceof Error ? e : new Error(String(e));
+                setError(err);
+                setIsLoading(false);
+            }
+            throw e;
+        }
+    }), [client, collection, readOnly]);
+    const reset = useCallback(() => {
+        callId.current += 1;
+        setError(null);
+        setIsSuccess(false);
+        setIsLoading(false);
+    }, []);
+    return { remove, isLoading, error, isSuccess, reset };
+}

package/src/lib/hooks/useDescribe.d.ts

@@ -0,0 +1,16 @@
+import type { SfaObjectDetail } from '../provider/types';
+interface UseDescribeOptions {
+    readonly enabled?: boolean;
+}
+interface UseDescribeResult {
+    readonly object: SfaObjectDetail | null;
+    readonly isLoading: boolean;
+    readonly error: Error | null;
+    readonly refetch: () => void;
+}
+/**
+ * @description Fetches metadata for an object: fields, types, relationships, permissions.
+ * The AI agent calls this to discover schema before rendering.
+ */
+export declare function useDescribe(objectKey: string, options?: UseDescribeOptions): UseDescribeResult;
+export {};

package/src/lib/hooks/useDescribe.js

@@ -0,0 +1,40 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { useSfaClient } from '../provider/useSfaClient';
+/**
+ * @description Fetches metadata for an object: fields, types, relationships, permissions.
+ * The AI agent calls this to discover schema before rendering.
+ */
+export function useDescribe(objectKey, options) {
+    var _a;
+    const client = useSfaClient();
+    const enabled = (_a = options === null || options === void 0 ? void 0 : options.enabled) !== null && _a !== void 0 ? _a : true;
+    const [object, setObject] = useState(null);
+    const [isLoading, setIsLoading] = useState(enabled && !!objectKey);
+    const [error, setError] = useState(null);
+    const fetchIdRef = useRef(0);
+    const doFetch = useCallback(() => {
+        if (!objectKey || !enabled)
+            return;
+        const fetchId = ++fetchIdRef.current;
+        setIsLoading(true);
+        setError(null);
+        client
+            .describe(objectKey)
+            .then(result => {
+            if (fetchId !== fetchIdRef.current)
+                return;
+            setObject(result.object);
+            setIsLoading(false);
+        })
+            .catch((err) => {
+            if (fetchId !== fetchIdRef.current)
+                return;
+            setError(err instanceof Error ? err : new Error(String(err)));
+            setIsLoading(false);
+        });
+    }, [client, objectKey, enabled]);
+    useEffect(() => {
+        doFetch();
+    }, [doFetch]);
+    return { object, isLoading, error, refetch: doFetch };
+}

package/src/lib/hooks/useFieldTypes.d.ts

@@ -0,0 +1,15 @@
+import type { SfaFieldTypeDescriptor } from '../provider/types';
+interface UseFieldTypesOptions {
+    readonly enabled?: boolean;
+}
+interface UseFieldTypesResult {
+    readonly fieldTypes: readonly SfaFieldTypeDescriptor[];
+    readonly isLoading: boolean;
+    readonly error: Error | null;
+    readonly refetch: () => void;
+}
+/**
+ * @description Fetches the static field-type catalog from Keystone.
+ */
+export declare function useFieldTypes(options?: UseFieldTypesOptions): UseFieldTypesResult;
+export {};

package/src/lib/hooks/useFieldTypes.js

@@ -0,0 +1,39 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { useSfaClient } from '../provider/useSfaClient';
+/**
+ * @description Fetches the static field-type catalog from Keystone.
+ */
+export function useFieldTypes(options) {
+    var _a;
+    const client = useSfaClient();
+    const enabled = (_a = options === null || options === void 0 ? void 0 : options.enabled) !== null && _a !== void 0 ? _a : true;
+    const [fieldTypes, setFieldTypes] = useState([]);
+    const [isLoading, setIsLoading] = useState(enabled);
+    const [error, setError] = useState(null);
+    const fetchIdRef = useRef(0);
+    const doFetch = useCallback(() => {
+        if (!enabled)
+            return;
+        const fetchId = ++fetchIdRef.current;
+        setIsLoading(true);
+        setError(null);
+        client
+            .listFieldTypes()
+            .then(result => {
+            if (fetchId !== fetchIdRef.current)
+                return;
+            setFieldTypes(result.fieldTypes);
+            setIsLoading(false);
+        })
+            .catch((err) => {
+            if (fetchId !== fetchIdRef.current)
+                return;
+            setError(err instanceof Error ? err : new Error(String(err)));
+            setIsLoading(false);
+        });
+    }, [client, enabled]);
+    useEffect(() => {
+        doFetch();
+    }, [doFetch]);
+    return { fieldTypes, isLoading, error, refetch: doFetch };
+}

package/src/lib/hooks/useObjectCatalog.d.ts

@@ -0,0 +1,15 @@
+import type { SfaObjectSummary } from '../provider/types';
+interface UseObjectCatalogOptions {
+    readonly enabled?: boolean;
+}
+interface UseObjectCatalogResult {
+    readonly objects: readonly SfaObjectSummary[];
+    readonly isLoading: boolean;
+    readonly error: Error | null;
+    readonly refetch: () => void;
+}
+/**
+ * @description Fetches the list of all objects available in the org.
+ */
+export declare function useObjectCatalog(options?: UseObjectCatalogOptions): UseObjectCatalogResult;
+export {};

package/src/lib/hooks/useObjectCatalog.js

@@ -0,0 +1,39 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { useSfaClient } from '../provider/useSfaClient';
+/**
+ * @description Fetches the list of all objects available in the org.
+ */
+export function useObjectCatalog(options) {
+    var _a;
+    const client = useSfaClient();
+    const enabled = (_a = options === null || options === void 0 ? void 0 : options.enabled) !== null && _a !== void 0 ? _a : true;
+    const [objects, setObjects] = useState([]);
+    const [isLoading, setIsLoading] = useState(enabled);
+    const [error, setError] = useState(null);
+    const fetchIdRef = useRef(0);
+    const doFetch = useCallback(() => {
+        if (!enabled)
+            return;
+        const fetchId = ++fetchIdRef.current;
+        setIsLoading(true);
+        setError(null);
+        client
+            .listObjects()
+            .then(result => {
+            if (fetchId !== fetchIdRef.current)
+                return;
+            setObjects(result.objects);
+            setIsLoading(false);
+        })
+            .catch((err) => {
+            if (fetchId !== fetchIdRef.current)
+                return;
+            setError(err instanceof Error ? err : new Error(String(err)));
+            setIsLoading(false);
+        });
+    }, [client, enabled]);
+    useEffect(() => {
+        doFetch();
+    }, [doFetch]);
+    return { objects, isLoading, error, refetch: doFetch };
+}

package/src/lib/hooks/useRecord.d.ts

@@ -0,0 +1,15 @@
+import type { SfaRecord } from '../provider/types';
+interface UseRecordOptions {
+    readonly enabled?: boolean;
+}
+interface UseRecordResult {
+    readonly record: SfaRecord | null;
+    readonly isLoading: boolean;
+    readonly error: Error | null;
+    readonly refetch: () => void;
+}
+/**
+ * @description Fetches a single record from the SFA/CRM API.
+ */
+export declare function useRecord(collection: string, recordId: string, options?: UseRecordOptions): UseRecordResult;
+export {};