@geniee-inc/sfa-kit 1.6.0

package/src/lib/hooks/useRecord.js

@@ -0,0 +1,49 @@
+import { __awaiter } from "tslib";
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { ERR_EMPTY_RECORD_ID } from '../errors';
+import { useSfaClient } from '../provider/useSfaClient';
+/**
+ * @description Fetches a single record from the SFA/CRM API.
+ */
+export function useRecord(collection, recordId, 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 [record, setRecord] = useState(null);
+    const [isLoading, setIsLoading] = useState(enabled && !!collection && !!recordId);
+    const [error, setError] = useState(null);
+    const fetchId = useRef(0);
+    const doFetch = useCallback(() => __awaiter(this, void 0, void 0, function* () {
+        if (!enabled || !collection)
+            return;
+        if (!recordId) {
+            fetchId.current += 1;
+            setRecord(null);
+            setIsLoading(false);
+            setError(new Error(ERR_EMPTY_RECORD_ID));
+            return;
+        }
+        fetchId.current += 1;
+        const currentFetchId = fetchId.current;
+        setIsLoading(true);
+        setError(null);
+        try {
+            const result = yield client.get(collection, recordId);
+            if (currentFetchId === fetchId.current) {
+                setRecord(result);
+                setIsLoading(false);
+            }
+        }
+        catch (e) {
+            if (currentFetchId === fetchId.current) {
+                setError(e instanceof Error ? e : new Error(String(e)));
+                setRecord(null);
+                setIsLoading(false);
+            }
+        }
+    }), [client, collection, recordId, enabled]);
+    useEffect(() => {
+        doFetch();
+    }, [doFetch]);
+    return { record, isLoading, error, refetch: doFetch };
+}

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

@@ -0,0 +1,19 @@
+import type { SfaListParams, SfaRecord } from '../provider/types';
+interface UseRecordListOptions {
+    readonly enabled?: boolean;
+}
+interface UseRecordListResult {
+    readonly items: readonly SfaRecord[];
+    readonly totalCount: number;
+    readonly hasMore: boolean;
+    readonly pageIndex: number;
+    readonly isLoading: boolean;
+    readonly error: Error | null;
+    readonly refetch: () => void;
+    readonly goToPage: (page: number) => void;
+}
+/**
+ * @description Fetches a paginated list of records from the SFA/CRM API.
+ */
+export declare function useRecordList(collection: string, params?: SfaListParams, options?: UseRecordListOptions): UseRecordListResult;
+export {};

package/src/lib/hooks/useRecordList.js

@@ -0,0 +1,82 @@
+import { __awaiter } from "tslib";
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useSfaClient } from '../provider/useSfaClient';
+/**
+ * @description Fetches a paginated list of records from the SFA/CRM API.
+ */
+export function useRecordList(collection, params, options) {
+    var _a, _b;
+    const client = useSfaClient();
+    const limit = (_a = params === null || params === void 0 ? void 0 : params.limit) !== null && _a !== void 0 ? _a : 20;
+    const [items, setItems] = useState([]);
+    const [totalCount, setTotalCount] = useState(0);
+    const [hasMore, setHasMore] = useState(false);
+    // offset is a record offset, not a page number: pageIndex = floor(offset / limit)
+    const [pageIndex, setPageIndex] = useState((params === null || params === void 0 ? void 0 : params.offset) != null && limit > 0 ? Math.floor(params.offset / limit) : 0);
+    const enabled = (_b = options === null || options === void 0 ? void 0 : options.enabled) !== null && _b !== void 0 ? _b : true;
+    const [isLoading, setIsLoading] = useState(enabled && !!collection);
+    const [error, setError] = useState(null);
+    const fetchId = useRef(0);
+    const sortBy = params === null || params === void 0 ? void 0 : params.sortBy;
+    const sortOrder = params === null || params === void 0 ? void 0 : params.sortOrder;
+    const filterKey = useMemo(() => ((params === null || params === void 0 ? void 0 : params.filter) ? JSON.stringify(params.filter) : ''), [params === null || params === void 0 ? void 0 : params.filter]);
+    const filterRef = useRef(params === null || params === void 0 ? void 0 : params.filter);
+    filterRef.current = params === null || params === void 0 ? void 0 : params.filter;
+    // Track cursors for each page so goToPage can navigate backwards.
+    const cursorMapRef = useRef(new Map());
+    const doFetch = useCallback((page) => __awaiter(this, void 0, void 0, function* () {
+        if (!collection || !enabled)
+            return;
+        fetchId.current += 1;
+        const currentFetchId = fetchId.current;
+        setIsLoading(true);
+        setError(null);
+        try {
+            const cursor = cursorMapRef.current.get(page);
+            const result = yield client.list(collection, Object.assign({ limit, offset: page, sortBy,
+                sortOrder, filter: filterRef.current }, (cursor ? { cursor } : {})));
+            if (currentFetchId === fetchId.current) {
+                setItems(result.items);
+                setTotalCount(result.totalCount);
+                setHasMore(result.hasMore);
+                setPageIndex(result.pageIndex);
+                setIsLoading(false);
+                // Store cursor for the next page so goToPage can use it.
+                if (result.nextCursor) {
+                    cursorMapRef.current.set(page + 1, result.nextCursor);
+                }
+            }
+        }
+        catch (e) {
+            if (currentFetchId === fetchId.current) {
+                setError(e instanceof Error ? e : new Error(String(e)));
+                setItems([]);
+                setIsLoading(false);
+            }
+        }
+    }), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- filterKey triggers re-fetch when filter object changes
+    [client, collection, enabled, limit, sortBy, sortOrder, filterKey]);
+    useEffect(() => {
+        cursorMapRef.current.clear();
+        setPageIndex(0);
+        doFetch(0);
+    }, [doFetch]);
+    const goToPage = useCallback((page) => {
+        setPageIndex(page);
+        doFetch(page);
+    }, [doFetch]);
+    const refetch = useCallback(() => {
+        doFetch(pageIndex);
+    }, [doFetch, pageIndex]);
+    return {
+        items,
+        totalCount,
+        hasMore,
+        pageIndex,
+        isLoading,
+        error,
+        refetch,
+        goToPage,
+    };
+}

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

@@ -0,0 +1,65 @@
+import type { SfaRecord, SfaRelationDescriptor } from '../provider/types';
+/** @description Parameters for narrowing, sorting, and filtering related records. */
+export interface UseRelatedRecordsParams {
+    readonly limit?: number;
+    readonly sortBy?: string;
+    readonly sortOrder?: 'asc' | 'desc';
+    /**
+     * @description Extra filter constraints merged alongside the auto-built
+     * relationship filter. Accepts any react-querybuilder-shaped group or rule.
+     */
+    readonly additionalFilter?: Record<string, unknown>;
+}
+/** @description Options controlling whether the hook fetches. */
+export interface UseRelatedRecordsOptions {
+    readonly enabled?: boolean;
+}
+/** @description Return value of useRelatedRecords: paginated items, loading/error state, and the resolved relationship descriptor. */
+export interface UseRelatedRecordsResult {
+    readonly items: readonly SfaRecord[];
+    readonly totalCount: number;
+    readonly hasMore: boolean;
+    readonly pageIndex: number;
+    readonly isLoading: boolean;
+    readonly error: Error | null;
+    readonly refetch: () => void;
+    readonly goToPage: (page: number) => void;
+    readonly relationship: SfaRelationDescriptor | null;
+}
+/**
+ * @description Thrown when the describe metadata for parentCollection
+ * contains no relationship pointing at the requested relationTarget.
+ */
+export declare class RelationNotFoundError extends Error {
+    readonly parentCollection: string;
+    readonly relationTarget: string;
+    readonly availableTargets: readonly string[];
+    constructor(parentCollection: string, relationTarget: string, availableTargets: readonly string[]);
+}
+/**
+ * @description Finds the first relationship descriptor whose `target`
+ * matches relationTarget, falling back to a match on `name`.
+ */
+export declare function resolveRelation(relationships: readonly SfaRelationDescriptor[], relationTarget: string): SfaRelationDescriptor | undefined;
+/**
+ * @description Builds a react-querybuilder-shaped filter that constrains
+ * `viaField` to the given parent id(s). A single string uses `eq`;
+ * an array uses `in` (batch fetch for the grandchild pattern).
+ */
+export declare function buildRelationFilter(viaField: string, parentId: string | readonly string[], additionalFilter?: Record<string, unknown>): Record<string, unknown>;
+/**
+ * @description Fetches child records scoped to a parent by automatically
+ * resolving the join from describe metadata. The AI agent never needs to
+ * hand-wire foreign keys: pass the parent collection, a parent id (or array
+ * of ids for the grandchild batch pattern), and the target collection.
+ *
+ * Resolution is direction-agnostic: the hook first checks the parent's
+ * describe for a forward relationship to the target; if none is found it
+ * falls back to describing the target and looking for a reverse
+ * relationship back to the parent.  This handles org schemas that only
+ * declare the FK on the "many" (child) side.
+ *
+ * Composes useDescribe (relationship lookup) and useRecordList (fetch +
+ * cursor pagination) internally.
+ */
+export declare function useRelatedRecords(parentCollection: string, parentId: string | readonly string[], relationTarget: string, params?: UseRelatedRecordsParams, options?: UseRelatedRecordsOptions): UseRelatedRecordsResult;

package/src/lib/hooks/useRelatedRecords.js

@@ -0,0 +1,227 @@
+import { useMemo, useRef } from 'react';
+import { useDescribe } from './useDescribe';
+import { useRecordList } from './useRecordList';
+// ── Error ──
+/**
+ * @description Thrown when the describe metadata for parentCollection
+ * contains no relationship pointing at the requested relationTarget.
+ */
+export class RelationNotFoundError extends Error {
+    constructor(parentCollection, relationTarget, availableTargets) {
+        const available = availableTargets.length > 0 ? availableTargets.join(', ') : 'none';
+        super(`No relationship from "${parentCollection}" to "${relationTarget}". ` +
+            `Available targets: ${available}.`);
+        this.name = 'RelationNotFoundError';
+        this.parentCollection = parentCollection;
+        this.relationTarget = relationTarget;
+        this.availableTargets = availableTargets;
+    }
+}
+// ── Helpers ──
+/**
+ * @description Finds the first relationship descriptor whose `target`
+ * matches relationTarget, falling back to a match on `name`.
+ */
+export function resolveRelation(relationships, relationTarget) {
+    var _a;
+    return ((_a = relationships.find(r => r.target === relationTarget)) !== null && _a !== void 0 ? _a : relationships.find(r => r.name === relationTarget));
+}
+/**
+ * @description Builds a react-querybuilder-shaped filter that constrains
+ * `viaField` to the given parent id(s). A single string uses `eq`;
+ * an array uses `in` (batch fetch for the grandchild pattern).
+ */
+export function buildRelationFilter(viaField, parentId, additionalFilter) {
+    const isArray = Array.isArray(parentId);
+    const relationRule = {
+        field: viaField,
+        operator: isArray ? 'in' : 'eq',
+        value: parentId,
+    };
+    const rules = [relationRule];
+    if (additionalFilter) {
+        rules.push(additionalFilter);
+    }
+    return { combinator: 'and', rules };
+}
+// ── Hook ──
+/**
+ * @description Fetches child records scoped to a parent by automatically
+ * resolving the join from describe metadata. The AI agent never needs to
+ * hand-wire foreign keys: pass the parent collection, a parent id (or array
+ * of ids for the grandchild batch pattern), and the target collection.
+ *
+ * Resolution is direction-agnostic: the hook first checks the parent's
+ * describe for a forward relationship to the target; if none is found it
+ * falls back to describing the target and looking for a reverse
+ * relationship back to the parent.  This handles org schemas that only
+ * declare the FK on the "many" (child) side.
+ *
+ * Composes useDescribe (relationship lookup) and useRecordList (fetch +
+ * cursor pagination) internally.
+ */
+export function useRelatedRecords(parentCollection, parentId, relationTarget, params, options) {
+    var _a, _b, _c;
+    const enabled = (_a = options === null || options === void 0 ? void 0 : options.enabled) !== null && _a !== void 0 ? _a : true;
+    const hasParentId = Array.isArray(parentId)
+        ? parentId.length > 0
+        : !!parentId;
+    // ── Step 1: Describe the parent to discover relationships ──
+    // Describe is decoupled from hasParentId so it prefetches eagerly.
+    // In the grandchild pattern the second hook's parentId starts as []
+    // while the first hook fetches; starting describe early lets both
+    // metadata calls overlap instead of running in sequence.
+    const { object: parentObject, isLoading: isParentDescribeLoading, error: parentDescribeError, } = useDescribe(parentCollection, {
+        enabled,
+    });
+    // Only trust parentObject while it matches the current collection;
+    // useDescribe keeps the previous object around while a new key is loading.
+    const parentObjectMatches = (parentObject === null || parentObject === void 0 ? void 0 : parentObject.key) === parentCollection;
+    // ── Step 2: Resolve the relationship ──
+    // Try the parent's describe first (forward: parent declares a
+    // relationship to the child).  If that misses, fall back to the
+    // child's describe and look for a reverse relationship back to the
+    // parent.  Some org schemas only declare the FK on the "many" side;
+    // this two-pass lookup keeps callers direction-agnostic.
+    const forwardRelationship = useMemo(() => {
+        var _a;
+        return parentObject && parentObjectMatches
+            ? (_a = resolveRelation(parentObject.relationships, relationTarget)) !== null && _a !== void 0 ? _a : null
+            : null;
+    }, [parentObject, parentObjectMatches, relationTarget]);
+    // ── Step 2b: Reverse-lookup fallback via the child's describe ──
+    const needsReverseLookup = enabled &&
+        parentObjectMatches &&
+        !isParentDescribeLoading &&
+        !forwardRelationship;
+    const { object: childObject, isLoading: isChildDescribeLoading, error: childDescribeError, } = useDescribe(relationTarget, {
+        enabled: needsReverseLookup,
+    });
+    const childObjectMatches = (childObject === null || childObject === void 0 ? void 0 : childObject.key) === relationTarget;
+    const reverseRelationship = useMemo(() => {
+        var _a;
+        return needsReverseLookup && childObject && childObjectMatches
+            ? (_a = resolveRelation(childObject.relationships, parentCollection)) !== null && _a !== void 0 ? _a : null
+            : null;
+    }, [needsReverseLookup, childObject, childObjectMatches, parentCollection]);
+    const relationship = forwardRelationship !== null && forwardRelationship !== void 0 ? forwardRelationship : reverseRelationship;
+    // ── Step 3: Surface a clear error when the relation is absent ──
+    // Only error once both forward and reverse lookups have definitively failed.
+    const relationError = useMemo(() => {
+        if (relationship)
+            return null;
+        if (!parentObjectMatches)
+            return null;
+        if (isParentDescribeLoading)
+            return null;
+        if (needsReverseLookup && (isChildDescribeLoading || !childObjectMatches))
+            return null;
+        return new RelationNotFoundError(parentCollection, relationTarget, parentObject.relationships.map(r => r.target));
+    }, [
+        relationship,
+        parentObjectMatches,
+        isParentDescribeLoading,
+        needsReverseLookup,
+        isChildDescribeLoading,
+        childObjectMatches,
+        parentCollection,
+        relationTarget,
+        parentObject,
+    ]);
+    // ── Step 4: Build the relationship filter ──
+    // Stabilize array/object identity via serialized keys so downstream
+    // useRecordList only re-fetches when the actual values change.
+    const parentIdRef = useRef(parentId);
+    parentIdRef.current = parentId;
+    const parentIdKey = Array.isArray(parentId)
+        ? JSON.stringify(parentId)
+        : parentId;
+    const additionalFilterRef = useRef(params === null || params === void 0 ? void 0 : params.additionalFilter);
+    additionalFilterRef.current = params === null || params === void 0 ? void 0 : params.additionalFilter;
+    const additionalFilterKey = (params === null || params === void 0 ? void 0 : params.additionalFilter)
+        ? JSON.stringify(params.additionalFilter)
+        : '';
+    const filter = useMemo(() => relationship
+        ? buildRelationFilter(relationship.viaField, parentIdRef.current, additionalFilterRef.current)
+        : undefined, 
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- parentIdKey and additionalFilterKey are stable serialized proxies for ref values
+    [relationship, parentIdKey, additionalFilterKey]);
+    // ── Step 5: Delegate to useRecordList ──
+    const listParams = useMemo(() => {
+        var _a;
+        return filter
+            ? {
+                limit: (_a = params === null || params === void 0 ? void 0 : params.limit) !== null && _a !== void 0 ? _a : 20,
+                sortBy: params === null || params === void 0 ? void 0 : params.sortBy,
+                sortOrder: params === null || params === void 0 ? void 0 : params.sortOrder,
+                filter,
+            }
+            : undefined;
+    }, [filter, params === null || params === void 0 ? void 0 : params.limit, params === null || params === void 0 ? void 0 : params.sortBy, params === null || params === void 0 ? void 0 : params.sortOrder]);
+    // When using a reverse relationship, relationship.target points back at
+    // the *parent* — not the child we want to query.  Always prefer the
+    // forward relationship's target (which IS the child); otherwise fall
+    // back to the caller-supplied relationTarget.
+    const targetCollection = (_b = forwardRelationship === null || forwardRelationship === void 0 ? void 0 : forwardRelationship.target) !== null && _b !== void 0 ? _b : relationTarget;
+    const recordList = useRecordList(targetCollection, listParams, {
+        enabled: enabled &&
+            hasParentId &&
+            parentObjectMatches &&
+            !!relationship &&
+            !relationError,
+    });
+    // Detect any change to the list query identifiers so we can reset the
+    // "fetch has started" marker before useRecordList's effect flips isLoading
+    // back on. This prevents one render frame where isLoading is false while
+    // the previous fetch's items are still on display.
+    const listQueryKey = useMemo(() => JSON.stringify({
+        collection: targetCollection,
+        params: listParams,
+        relationTarget,
+    }), [targetCollection, listParams, relationTarget]);
+    // ── Step 6: Merge state ──
+    // listShouldBeActive covers the one-frame gap where useRecordList's
+    // enabled just flipped to true but its internal isLoading hasn't been
+    // set yet (useState initial value is only evaluated at mount).
+    // listQueryKey resets the marker whenever the query identity changes
+    // (parentId / filter / limit / sort / relationTarget) so we never return
+    // stale items with isLoading: false while a new fetch is about to start.
+    const listShouldBeActive = enabled &&
+        hasParentId &&
+        parentObjectMatches &&
+        !!relationship &&
+        !relationError;
+    const listHasStartedRef = useRef(false);
+    const prevListShouldBeActiveRef = useRef(listShouldBeActive);
+    const prevListQueryKeyRef = useRef(listQueryKey);
+    if (listShouldBeActive &&
+        (!prevListShouldBeActiveRef.current ||
+            prevListQueryKeyRef.current !== listQueryKey)) {
+        listHasStartedRef.current = false;
+    }
+    prevListShouldBeActiveRef.current = listShouldBeActive;
+    prevListQueryKeyRef.current = listQueryKey;
+    if (listShouldBeActive && recordList.isLoading) {
+        listHasStartedRef.current = true;
+    }
+    const isDescribeLoading = isParentDescribeLoading ||
+        (needsReverseLookup &&
+            !childDescribeError &&
+            (!childObjectMatches || isChildDescribeLoading));
+    const isLoading = isDescribeLoading ||
+        (listShouldBeActive &&
+            (recordList.isLoading || !listHasStartedRef.current));
+    const describeError = parentDescribeError !== null && parentDescribeError !== void 0 ? parentDescribeError : (needsReverseLookup ? childDescribeError : null);
+    const error = (_c = describeError !== null && describeError !== void 0 ? describeError : relationError) !== null && _c !== void 0 ? _c : recordList.error;
+    return {
+        items: recordList.items,
+        totalCount: recordList.totalCount,
+        hasMore: recordList.hasMore,
+        pageIndex: recordList.pageIndex,
+        isLoading,
+        error,
+        refetch: recordList.refetch,
+        goToPage: recordList.goToPage,
+        relationship,
+    };
+}

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

@@ -0,0 +1,23 @@
+import type { SfaRecord } from '../provider/types';
+export interface SfaConflictDetail {
+    /** The current version of the record on the server. */
+    readonly currentRecord: SfaRecord;
+}
+export interface UseUpdateRecordResult {
+    /** Call to update a record. Requires the record's current version for optimistic locking. */
+    readonly update: (recordId: string, fields: Record<string, unknown>, version: string) => Promise<SfaRecord>;
+    /** The most recently updated record, or null before the first update. */
+    readonly data: SfaRecord | null;
+    readonly isLoading: boolean;
+    readonly error: Error | null;
+    /** Non-null when the last update failed with a 412 conflict. Contains the server's current record. */
+    readonly conflict: SfaConflictDetail | null;
+    /** Reset data, error, and conflict state to initial values. */
+    readonly reset: () => void;
+}
+/**
+ * @description Imperative hook for updating a single record with optimistic
+ * locking. Surfaces 412 conflicts as a dedicated `conflict` state so
+ * components can show "someone else updated this" with the current record.
+ */
+export declare function useUpdateRecord(collection: string): UseUpdateRecordResult;

package/src/lib/hooks/useUpdateRecord.js

@@ -0,0 +1,55 @@
+import { __awaiter } from "tslib";
+import { useCallback, useRef, useState } from 'react';
+import { ERR_READ_ONLY } from '../errors';
+import { SfaConflictError } from '../provider/SfaClient';
+import { useSfaContext } from '../provider/useSfaClient';
+/**
+ * @description Imperative hook for updating a single record with optimistic
+ * locking. Surfaces 412 conflicts as a dedicated `conflict` state so
+ * components can show "someone else updated this" with the current record.
+ */
+export function useUpdateRecord(collection) {
+    const { client, readOnly } = useSfaContext();
+    const [data, setData] = useState(null);
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const [conflict, setConflict] = useState(null);
+    const callId = useRef(0);
+    const update = useCallback((recordId, fields, 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);
+        setConflict(null);
+        try {
+            const record = yield client.update(collection, recordId, fields, version);
+            if (currentCallId === callId.current) {
+                setData(record);
+                setIsLoading(false);
+            }
+            return record;
+        }
+        catch (e) {
+            if (currentCallId === callId.current) {
+                if (e instanceof SfaConflictError && e.currentRecord) {
+                    setConflict({ currentRecord: e.currentRecord });
+                }
+                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);
+        setConflict(null);
+        setIsLoading(false);
+    }, []);
+    return { update, data, isLoading, error, conflict, reset };
+}

package/src/lib/provider/SfaClient.d.ts

@@ -0,0 +1,98 @@
+import type { SfaApiMode, SfaClientConfig, SfaClientInterface, SfaCreateOptions, SfaDescribeResult, SfaFieldError, SfaFieldTypeCatalog, SfaListParams, SfaListResponse, SfaObjectCatalog, SfaRecord } from './types';
+/**
+ * @description API client for SFA/CRM data operations via keystone.
+ * Authenticates with a JWT Bearer token.
+ *
+ * In direct mode the client talks to keystone's v1 REST API.
+ * In proxy mode the client relays through a local Next.js API route.
+ */
+export declare class SfaClient implements SfaClientInterface {
+    private readonly apiBase;
+    private readonly auth;
+    private readonly organizationId;
+    private readonly onAuthError;
+    readonly mode: SfaApiMode;
+    constructor(config: SfaClientConfig);
+    private resolveBase;
+    get(collection: string, recordId: string): Promise<SfaRecord>;
+    list(collection: string, params?: SfaListParams): Promise<SfaListResponse>;
+    describe(objectKey: string): Promise<SfaDescribeResult>;
+    listObjects(): Promise<SfaObjectCatalog>;
+    listFieldTypes(): Promise<SfaFieldTypeCatalog>;
+    private assertDirectMode;
+    /** @description Throws if recordId is empty to prevent malformed API requests. */
+    private assertRecordId;
+    /**
+     * @description Creates a new record. Optionally accepts an idempotency key
+     * to prevent duplicate creates on retries.
+     */
+    create(collection: string, fields: Record<string, unknown>, options?: SfaCreateOptions): Promise<SfaRecord>;
+    /**
+     * @description Updates a record with optimistic locking. The version token
+     * (from a prior GET) is sent as the If-Match header; a 412 response means
+     * another write landed first.
+     */
+    update(collection: string, recordId: string, fields: Record<string, unknown>, version: string): Promise<SfaRecord>;
+    /**
+     * @description Deletes a record with optimistic locking. Returns void on
+     * success (204). Throws SfaConflictError on 412 if the record was modified
+     * since the version was obtained.
+     */
+    delete(collection: string, recordId: string, version: string): Promise<void>;
+    /** @description Returns the objects metadata path for the current mode. */
+    private objectsPath;
+    /** @description Returns the field-types catalog path for the current mode. */
+    private fieldTypesPath;
+    private applyAuth;
+    /**
+     * @description GET request with auth headers. Works for all read-only
+     * endpoints in both direct and proxy modes.
+     */
+    private fetchGet;
+    /**
+     * @description POST request with auth headers and a JSON body.
+     * Body is sent directly (not wrapped in { data: ... }).
+     */
+    private postJson;
+    /**
+     * @description Generic fetch with a configurable HTTP method and optional
+     * body / extra headers. Returns the raw Response so callers can inspect
+     * status codes, headers, or handle empty bodies (204).
+     */
+    private fetchWithBody;
+}
+/**
+ * @description Error from the SFA API with parsed Keystone error details.
+ * Keystone returns structured errors with `detail`, `code`, and `title` fields.
+ * The message prefers the human-readable `detail` over the raw status text.
+ * The raw body is truncated to limit exposure of record data via error
+ * monitoring services.
+ */
+export declare class SfaApiError extends Error {
+    readonly status: number;
+    readonly statusText: string;
+    readonly url: string;
+    readonly detail: string | null;
+    readonly code: string | null;
+    readonly body: string;
+    constructor(status: number, statusText: string, body: string, url: string);
+}
+/**
+ * @description Thrown on 412 Precondition Failed. The record was modified by
+ * another writer since the caller's version was obtained. The response body
+ * contains the current record so the UI can show what changed.
+ */
+export declare class SfaConflictError extends SfaApiError {
+    readonly currentRecord: SfaRecord | null;
+    constructor(status: number, statusText: string, body: string, url: string, currentRecord: SfaRecord | null);
+    static fromBody(status: number, statusText: string, body: string, url: string): SfaConflictError;
+}
+/**
+ * @description Thrown on 422 with code VALIDATION_FAILED. Exposes per-field
+ * errors so the UI can highlight which fields need correction.
+ */
+export declare class SfaValidationError extends SfaApiError {
+    readonly fieldErrors: readonly SfaFieldError[];
+    constructor(status: number, statusText: string, body: string, url: string, fieldErrors: readonly SfaFieldError[]);
+    static fromBody(status: number, statusText: string, body: string, url: string): SfaValidationError;
+}