@geniee-inc/sfa-kit 1.6.0

package/src/lib/provider/SfaClient.js

@@ -0,0 +1,688 @@
+import { __awaiter } from "tslib";
+import { ERR_DIRECT_MODE_REQUIRED, ERR_EMPTY_RECORD_ID } from '../errors';
+/** Abort in-flight requests after this many milliseconds. */
+const REQUEST_TIMEOUT_MS = 30000;
+/**
+ * @description Returns a timeout AbortSignal, or undefined where the runtime
+ * doesn't support AbortSignal.timeout (e.g. older jsdom in tests).
+ */
+function timeoutSignal() {
+    if (typeof AbortSignal.timeout === 'function') {
+        return AbortSignal.timeout(REQUEST_TIMEOUT_MS);
+    }
+    return undefined;
+}
+/**
+ * @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 class SfaClient {
+    constructor(config) {
+        this.apiBase = this.resolveBase(config.apiBase.replace(/\/+$/, ''), config.mode);
+        this.auth = config.auth;
+        this.mode = config.mode;
+        this.organizationId = config.organizationId;
+        this.onAuthError = config.onAuthError;
+    }
+    resolveBase(base, mode) {
+        var _a;
+        if (mode !== 'proxy' || base.startsWith('http'))
+            return base;
+        const nextData = typeof globalThis.document !== 'undefined'
+            ? globalThis['__NEXT_DATA__']
+            : undefined;
+        const basePath = (_a = nextData === null || nextData === void 0 ? void 0 : nextData.basePath) !== null && _a !== void 0 ? _a : '';
+        if (basePath && !base.startsWith(basePath)) {
+            return basePath + base;
+        }
+        return base;
+    }
+    // ── Public API ──
+    get(collection, recordId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.assertRecordId(recordId);
+            if (this.mode === 'direct') {
+                const path = `/v1/objects/${enc(collection)}/records/${enc(recordId)}`;
+                const raw = yield this.fetchGet(path);
+                return normalizeKeystoneRecord(raw);
+            }
+            const raw = yield this.fetchGet(`/${collection}/${recordId}`);
+            return normalizeRecord(raw);
+        });
+    }
+    list(collection, params) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c;
+            const pageSize = (_a = params === null || params === void 0 ? void 0 : params.limit) !== null && _a !== void 0 ? _a : 20;
+            const offset = (_b = params === null || params === void 0 ? void 0 : params.offset) !== null && _b !== void 0 ? _b : 0;
+            // offset is a record offset, not a page number: pageIndex = floor(offset / pageSize)
+            const pageIndex = pageSize > 0 ? Math.floor(offset / pageSize) : 0;
+            if (this.mode === 'direct') {
+                const body = {
+                    limit: pageSize,
+                };
+                if (params === null || params === void 0 ? void 0 : params.cursor) {
+                    body['cursor'] = params.cursor;
+                }
+                if (params === null || params === void 0 ? void 0 : params.sortBy) {
+                    body['sort'] = [
+                        {
+                            field: params.sortBy,
+                            direction: (_c = params.sortOrder) !== null && _c !== void 0 ? _c : 'asc',
+                        },
+                    ];
+                }
+                if (params === null || params === void 0 ? void 0 : params.filter) {
+                    body['filter'] = params.filter;
+                }
+                const path = `/v1/objects/${enc(collection)}/records/query`;
+                const raw = yield this.postJson(path, body);
+                return normalizeKeystoneListResponse(raw, pageIndex, pageSize);
+            }
+            const query = new URLSearchParams();
+            if ((params === null || params === void 0 ? void 0 : params.limit) != null)
+                query.set('limit', String(params.limit));
+            if ((params === null || params === void 0 ? void 0 : params.offset) != null)
+                query.set('offset', String(params.offset));
+            if (params === null || params === void 0 ? void 0 : params.sortBy)
+                query.set('sort_by', params.sortBy);
+            if (params === null || params === void 0 ? void 0 : params.sortOrder)
+                query.set('sort_order', params.sortOrder);
+            const queryString = query.toString();
+            const path = queryString
+                ? `/${collection}?${queryString}`
+                : `/${collection}`;
+            const raw = yield this.fetchGet(path);
+            return normalizeListResponse(raw, pageIndex, pageSize);
+        });
+    }
+    describe(objectKey) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const raw = yield this.fetchGet(this.objectsPath(`/${enc(objectKey)}`));
+            return { object: normalizeObjectDetail(raw) };
+        });
+    }
+    listObjects() {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const raw = yield this.fetchGet(this.objectsPath());
+            const data = raw;
+            const objects = ((_a = data.objects) !== null && _a !== void 0 ? _a : []).map(o => normalizeObjectSummary(o));
+            return { objects };
+        });
+    }
+    listFieldTypes() {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const raw = yield this.fetchGet(this.fieldTypesPath());
+            const data = raw;
+            const fieldTypes = ((_a = data.field_types) !== null && _a !== void 0 ? _a : []).map(ft => normalizeFieldTypeDescriptor(ft));
+            return { fieldTypes };
+        });
+    }
+    // ── Mutations (direct mode only) ──
+    assertDirectMode() {
+        if (this.mode !== 'direct') {
+            throw new Error(ERR_DIRECT_MODE_REQUIRED);
+        }
+    }
+    /** @description Throws if recordId is empty to prevent malformed API requests. */
+    assertRecordId(recordId) {
+        if (!recordId) {
+            throw new Error(ERR_EMPTY_RECORD_ID);
+        }
+    }
+    /**
+     * @description Creates a new record. Optionally accepts an idempotency key
+     * to prevent duplicate creates on retries.
+     */
+    create(collection, fields, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.assertDirectMode();
+            const path = `/v1/objects/${enc(collection)}/records`;
+            const extra = {};
+            if (options === null || options === void 0 ? void 0 : options.idempotencyKey) {
+                extra['Idempotency-Key'] = options.idempotencyKey;
+            }
+            const response = yield this.fetchWithBody('POST', path, { fields: normalizeWriteFields(fields) }, extra);
+            const raw = yield response.json();
+            return normalizeKeystoneRecord(raw);
+        });
+    }
+    /**
+     * @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, recordId, fields, version) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.assertDirectMode();
+            this.assertRecordId(recordId);
+            const path = `/v1/objects/${enc(collection)}/records/${enc(recordId)}`;
+            const response = yield this.fetchWithBody('PATCH', path, { fields: normalizeWriteFields(fields) }, { 'If-Match': version });
+            const raw = yield response.json();
+            return normalizeKeystoneRecord(raw);
+        });
+    }
+    /**
+     * @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, recordId, version) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.assertDirectMode();
+            this.assertRecordId(recordId);
+            const path = `/v1/objects/${enc(collection)}/records/${enc(recordId)}`;
+            yield this.fetchWithBody('DELETE', path, undefined, {
+                'If-Match': version,
+            });
+        });
+    }
+    // ── Path resolution ──
+    /** @description Returns the objects metadata path for the current mode. */
+    objectsPath(suffix = '') {
+        const prefix = this.mode === 'direct' ? '/v1/objects' : '/objects';
+        return `${prefix}${suffix}`;
+    }
+    /** @description Returns the field-types catalog path for the current mode. */
+    fieldTypesPath() {
+        return this.mode === 'direct' ? '/v1/field-types' : '/field-types';
+    }
+    // ── Private transport ──
+    applyAuth(headers) {
+        var _a;
+        if ((_a = this.auth) === null || _a === void 0 ? void 0 : _a.accessToken) {
+            headers['Authorization'] = `Bearer ${this.auth.accessToken}`;
+        }
+        if (this.organizationId) {
+            headers['organization-id'] = this.organizationId;
+        }
+    }
+    /**
+     * @description GET request with auth headers. Works for all read-only
+     * endpoints in both direct and proxy modes.
+     */
+    fetchGet(path) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const url = `${this.apiBase}${path}`;
+            const headers = {
+                'Content-Type': 'application/json',
+            };
+            this.applyAuth(headers);
+            const response = yield globalThis.fetch(url, {
+                method: 'GET',
+                headers,
+                signal: timeoutSignal(),
+            });
+            if (!response.ok) {
+                if (response.status === 401)
+                    (_a = this.onAuthError) === null || _a === void 0 ? void 0 : _a.call(this);
+                const text = yield response.text().catch(() => '');
+                throw new SfaApiError(response.status, response.statusText, text, url);
+            }
+            return response.json();
+        });
+    }
+    /**
+     * @description POST request with auth headers and a JSON body.
+     * Body is sent directly (not wrapped in { data: ... }).
+     */
+    postJson(path, body) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const url = `${this.apiBase}${path}`;
+            const headers = {
+                'Content-Type': 'application/json',
+            };
+            this.applyAuth(headers);
+            const response = yield globalThis.fetch(url, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(body),
+                signal: timeoutSignal(),
+            });
+            if (!response.ok) {
+                if (response.status === 401)
+                    (_a = this.onAuthError) === null || _a === void 0 ? void 0 : _a.call(this);
+                const text = yield response.text().catch(() => '');
+                throw new SfaApiError(response.status, response.statusText, text, url);
+            }
+            return response.json();
+        });
+    }
+    /**
+     * @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).
+     */
+    fetchWithBody(method, path, body, extraHeaders) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const url = `${this.apiBase}${path}`;
+            const headers = Object.assign({ 'Content-Type': 'application/json' }, extraHeaders);
+            this.applyAuth(headers);
+            const response = yield globalThis.fetch(url, {
+                method,
+                headers,
+                body: body ? JSON.stringify(body) : undefined,
+                signal: timeoutSignal(),
+            });
+            if (!response.ok) {
+                if (response.status === 401)
+                    (_a = this.onAuthError) === null || _a === void 0 ? void 0 : _a.call(this);
+                const text = yield response.text().catch(() => '');
+                if (response.status === 412) {
+                    throw SfaConflictError.fromBody(response.status, response.statusText, text, url);
+                }
+                if (response.status === 422) {
+                    throw SfaValidationError.fromBody(response.status, response.statusText, text, url);
+                }
+                throw new SfaApiError(response.status, response.statusText, text, url);
+            }
+            return response;
+        });
+    }
+}
+/** @description URI-encode a path segment. */
+function enc(segment) {
+    return encodeURIComponent(segment);
+}
+// ── Keystone record normalization (direct mode) ──
+/**
+ * @description Converts a caller-supplied fields map into the raw values
+ * expected by Keystone's RecordWrite body. If a value is already a raw value
+ * it is preserved; if it is an SfaFieldValue object (with kind/value/label)
+ * only the stored value is sent, so labels are never written back.
+ */
+function normalizeWriteFields(fields) {
+    var _a;
+    const result = {};
+    for (const [key, raw] of Object.entries(fields)) {
+        result[key] = isSfaFieldValue(raw) ? (_a = raw.value) !== null && _a !== void 0 ? _a : null : raw;
+    }
+    return result;
+}
+function isSfaFieldValue(value) {
+    return (typeof value === 'object' &&
+        value != null &&
+        'kind' in value &&
+        'value' in value &&
+        typeof value.kind === 'string');
+}
+/**
+ * @description Normalizes a CrmRecord from keystone v1 API into the
+ * internal SfaRecord shape used by all sfa-kit components.
+ */
+function normalizeKeystoneRecord(raw) {
+    var _a, _b, _c, _d, _e, _f, _g, _h;
+    const data = raw;
+    const perms = (_a = data['permissions']) !== null && _a !== void 0 ? _a : {};
+    return {
+        record_id: (_b = data['id']) !== null && _b !== void 0 ? _b : '',
+        collection_name: (_c = data['object_key']) !== null && _c !== void 0 ? _c : '',
+        fields: normalizeKeystoneFields(data['fields']),
+        titleFields: [],
+        title: (_d = data['title']) !== null && _d !== void 0 ? _d : null,
+        version: (_e = data['version']) !== null && _e !== void 0 ? _e : null,
+        permissions: {
+            canEdit: (_g = (_f = perms['editable']) !== null && _f !== void 0 ? _f : perms['updatable']) !== null && _g !== void 0 ? _g : false,
+            canDelete: (_h = perms['deletable']) !== null && _h !== void 0 ? _h : false,
+        },
+    };
+}
+function normalizeKeystoneFields(rawFields) {
+    if (!rawFields || typeof rawFields !== 'object')
+        return {};
+    const result = {};
+    for (const [key, raw] of Object.entries(rawFields)) {
+        if (raw && typeof raw === 'object') {
+            result[key] = normalizeKeystoneCell(raw);
+        }
+        else {
+            // Bare scalar or null: preserve the field instead of silently dropping it
+            result[key] = {
+                kind: inferScalarKind(raw),
+                value: raw !== null && raw !== void 0 ? raw : null,
+                label: raw != null ? String(raw) : null,
+            };
+        }
+    }
+    return result;
+}
+function normalizeKeystoneCell(cell) {
+    var _a, _b, _c, _d, _e;
+    const shape = cell['shape'];
+    switch (shape) {
+        case 'coded':
+            return {
+                kind: 'single_choice',
+                value: (_a = cell['value']) !== null && _a !== void 0 ? _a : null,
+                label: (_b = cell['label']) !== null && _b !== void 0 ? _b : null,
+            };
+        case 'coded_list': {
+            const labels = cell['label'];
+            return {
+                kind: 'multi_choice',
+                value: (_c = cell['value']) !== null && _c !== void 0 ? _c : [],
+                label: Array.isArray(labels)
+                    ? labels.filter(Boolean).join(', ')
+                    : null,
+            };
+        }
+        case 'scalar':
+            return {
+                kind: inferScalarKind(cell['value']),
+                value: (_d = cell['value']) !== null && _d !== void 0 ? _d : null,
+                label: cell['value'] != null ? String(cell['value']) : null,
+            };
+        case 'unresolved':
+        default:
+            return {
+                kind: 'text',
+                value: (_e = cell['value']) !== null && _e !== void 0 ? _e : null,
+                label: cell['value'] != null ? String(cell['value']) : null,
+            };
+    }
+}
+function inferScalarKind(value) {
+    if (typeof value === 'number')
+        return 'number';
+    if (typeof value === 'string') {
+        if (/^\d{4}-\d{2}-\d{2}T/.test(value))
+            return 'datetime';
+        if (/^\d{4}-\d{2}-\d{2}$/.test(value))
+            return 'date';
+    }
+    return 'text';
+}
+function normalizeKeystoneListResponse(raw, pageIndex, pageSize) {
+    var _a, _b, _c;
+    const data = raw;
+    const rawRecords = (_a = data['records']) !== null && _a !== void 0 ? _a : [];
+    const items = rawRecords.map(r => normalizeKeystoneRecord(r));
+    const nextCursor = (_b = data['next_cursor']) !== null && _b !== void 0 ? _b : null;
+    const prevCursor = (_c = data['prev_cursor']) !== null && _c !== void 0 ? _c : null;
+    const hasMore = nextCursor != null;
+    // Keystone uses cursor pagination without a total count.
+    // Estimate a totalCount that keeps the hasMore logic correct.
+    const totalCount = hasMore
+        ? (pageIndex + 1) * pageSize + 1
+        : pageIndex * pageSize + items.length;
+    return { items, totalCount, hasMore, pageIndex, nextCursor, prevCursor };
+}
+// ── Legacy Chikyu normalization (proxy mode) ──
+const CHIKYU_KIND_MAP = {
+    CHIKYU_STRING: 'text',
+    CHIKYU_TEXT: 'text',
+    CHIKYU_NUMBER: 'number',
+    CHIKYU_DATE: 'date',
+    CHIKYU_DATE_TIME: 'datetime',
+    CHIKYU_SELECT: 'single_choice',
+    CHIKYU_MULTIPLE_SELECT: 'multi_choice',
+    CHIKYU_USER_SELECT: 'user_reference',
+    CHIKYU_MULTIPLE_USER_SELECT: 'user_reference',
+    CHIKYU_COLLECTION: 'reference',
+    CHIKYU_SUB_COLLECTION: 'reference',
+    CHIKYU_ID_LIST: 'reference',
+    CHIKYU_DATE_DIFF: 'computed',
+    CHIKYU_AUTO_NUMBERING: 'computed',
+    CHIKYU_FORMULA: 'computed',
+    CHIKYU_LOOKUP: 'computed',
+    CHIKYU_HEAP_AGGREGATE: 'computed',
+    CHIKYU_ROLE: 'user_reference',
+    CHIKYU_LAYOUT_TYPE: 'record_type',
+    CHIKYU_IMAGE_HTML: 'text',
+};
+function normalizeFieldValue(raw) {
+    var _a, _b, _c, _d;
+    const chikyuType = (_a = raw['type']) !== null && _a !== void 0 ? _a : '';
+    return {
+        kind: (_b = CHIKYU_KIND_MAP[chikyuType]) !== null && _b !== void 0 ? _b : 'text',
+        value: (_c = raw['value']) !== null && _c !== void 0 ? _c : null,
+        label: (_d = raw['caption']) !== null && _d !== void 0 ? _d : null,
+    };
+}
+function normalizeFields(rawMapping) {
+    if (!rawMapping || typeof rawMapping !== 'object')
+        return {};
+    const result = {};
+    for (const [key, raw] of Object.entries(rawMapping)) {
+        if (raw && typeof raw === 'object') {
+            result[key] = normalizeFieldValue(raw);
+        }
+    }
+    return result;
+}
+function normalizeRecord(raw) {
+    var _a, _b, _c, _d, _e, _f;
+    const data = raw;
+    return {
+        record_id: (_b = (_a = data['record_id']) !== null && _a !== void 0 ? _a : data['_id']) !== null && _b !== void 0 ? _b : '',
+        collection_name: (_c = data['collection_name']) !== null && _c !== void 0 ? _c : '',
+        fields: normalizeFields(data['field_value_mapping']),
+        titleFields: (_d = data['title_field_name_list']) !== null && _d !== void 0 ? _d : [],
+        permissions: {
+            canEdit: (_e = data['is_editable']) !== null && _e !== void 0 ? _e : false,
+            canDelete: (_f = data['is_deletable']) !== null && _f !== void 0 ? _f : false,
+        },
+    };
+}
+function normalizeListResponse(raw, pageIndex, pageSize) {
+    var _a, _b, _c, _d;
+    const data = raw;
+    const rawItems = (_b = (_a = data['item_list']) !== null && _a !== void 0 ? _a : data['items']) !== null && _b !== void 0 ? _b : [];
+    const items = rawItems.map(item => normalizeRecord(item));
+    const totalCount = (_d = (_c = data['total_count']) !== null && _c !== void 0 ? _c : data['totalCount']) !== null && _d !== void 0 ? _d : items.length;
+    return {
+        items,
+        totalCount,
+        hasMore: (pageIndex + 1) * pageSize < totalCount,
+        pageIndex,
+    };
+}
+const VALID_KINDS = new Set([
+    'text',
+    'number',
+    'date',
+    'datetime',
+    'single_choice',
+    'multi_choice',
+    'reference',
+    'user_reference',
+    'computed',
+    'record_type',
+]);
+const VALID_CARDINALITIES = new Set([
+    'one',
+    'many',
+]);
+const VALID_REL_KINDS = new Set([
+    'association',
+    'master_detail',
+]);
+function normalizeRelationship(raw) {
+    var _a, _b, _c, _d, _e;
+    return {
+        name: (_a = raw.name) !== null && _a !== void 0 ? _a : '',
+        target: (_b = raw.target) !== null && _b !== void 0 ? _b : '',
+        cardinality: VALID_CARDINALITIES.has((_c = raw.cardinality) !== null && _c !== void 0 ? _c : '')
+            ? raw.cardinality
+            : 'one',
+        kind: VALID_REL_KINDS.has((_d = raw.kind) !== null && _d !== void 0 ? _d : '')
+            ? raw.kind
+            : 'association',
+        viaField: (_e = raw.via_field) !== null && _e !== void 0 ? _e : '',
+    };
+}
+function normalizeFieldDescriptor(raw) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
+    const kind = VALID_KINDS.has((_a = raw.kind) !== null && _a !== void 0 ? _a : '')
+        ? raw.kind
+        : 'text';
+    const descriptor = Object.assign(Object.assign(Object.assign(Object.assign({ key: (_b = raw.key) !== null && _b !== void 0 ? _b : '', label: (_d = (_c = raw.label) !== null && _c !== void 0 ? _c : raw.key) !== null && _d !== void 0 ? _d : '', kind, description: (_e = raw.description) !== null && _e !== void 0 ? _e : null, required: (_f = raw.required) !== null && _f !== void 0 ? _f : false, readOnly: (_g = raw.read_only) !== null && _g !== void 0 ? _g : false, order: (_h = raw.order) !== null && _h !== void 0 ? _h : 0, section: (_j = raw.section) !== null && _j !== void 0 ? _j : null, filterable: (_k = raw.filterable) !== null && _k !== void 0 ? _k : false, sortable: (_l = raw.sortable) !== null && _l !== void 0 ? _l : false }, (raw.options ? { options: raw.options } : {})), (raw.target_object ? { targetObject: raw.target_object } : {})), (raw.cardinality && VALID_CARDINALITIES.has(raw.cardinality)
+        ? { cardinality: raw.cardinality }
+        : {})), (raw.display_field ? { displayField: raw.display_field } : {}));
+    return descriptor;
+}
+function normalizePermissions(raw) {
+    var _a, _b, _c, _d;
+    return {
+        readable: (_a = raw === null || raw === void 0 ? void 0 : raw.readable) !== null && _a !== void 0 ? _a : false,
+        creatable: (_b = raw === null || raw === void 0 ? void 0 : raw.creatable) !== null && _b !== void 0 ? _b : false,
+        updatable: (_c = raw === null || raw === void 0 ? void 0 : raw.updatable) !== null && _c !== void 0 ? _c : false,
+        deletable: (_d = raw === null || raw === void 0 ? void 0 : raw.deletable) !== null && _d !== void 0 ? _d : false,
+    };
+}
+function normalizeObjectSummary(raw) {
+    var _a, _b, _c, _d, _e;
+    return {
+        key: (_a = raw.key) !== null && _a !== void 0 ? _a : '',
+        label: (_c = (_b = raw.label) !== null && _b !== void 0 ? _b : raw.key) !== null && _c !== void 0 ? _c : '',
+        origin: raw.origin === 'custom' ? 'custom' : 'standard',
+        primaryDisplayField: (_d = raw.primary_display_field) !== null && _d !== void 0 ? _d : null,
+        relationships: ((_e = raw.relationships) !== null && _e !== void 0 ? _e : []).map(normalizeRelationship),
+    };
+}
+function normalizeObjectDetail(raw) {
+    var _a, _b, _c, _d, _e, _f;
+    return {
+        key: (_a = raw.key) !== null && _a !== void 0 ? _a : '',
+        label: (_c = (_b = raw.label) !== null && _b !== void 0 ? _b : raw.key) !== null && _c !== void 0 ? _c : '',
+        origin: raw.origin === 'custom' ? 'custom' : 'standard',
+        primaryDisplayField: (_d = raw.primary_display_field) !== null && _d !== void 0 ? _d : null,
+        fields: ((_e = raw.fields) !== null && _e !== void 0 ? _e : []).map(normalizeFieldDescriptor),
+        relationships: ((_f = raw.relationships) !== null && _f !== void 0 ? _f : []).map(normalizeRelationship),
+        permissions: normalizePermissions(raw.permissions),
+    };
+}
+function normalizeFieldTypeDescriptor(raw) {
+    var _a, _b, _c, _d, _e, _f, _g, _h;
+    return {
+        kind: VALID_KINDS.has((_a = raw.kind) !== null && _a !== void 0 ? _a : '') ? raw.kind : 'text',
+        summary: (_b = raw.summary) !== null && _b !== void 0 ? _b : '',
+        valueShape: (_c = raw.value_shape) !== null && _c !== void 0 ? _c : '',
+        multiValued: (_d = raw.multi_valued) !== null && _d !== void 0 ? _d : false,
+        editableByDefault: (_e = raw.editable_by_default) !== null && _e !== void 0 ? _e : true,
+        hasOptions: (_f = raw.has_options) !== null && _f !== void 0 ? _f : false,
+        referencesObject: (_g = raw.references_object) !== null && _g !== void 0 ? _g : false,
+        operators: ((_h = raw.operators) !== null && _h !== void 0 ? _h : []),
+    };
+}
+/** Max characters of the response body retained on SfaApiError. Bodies can
+ * contain record data, so keep only enough for debugging. */
+const ERROR_BODY_MAX_LENGTH = 500;
+/**
+ * @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 class SfaApiError extends Error {
+    constructor(status, statusText, body, url) {
+        var _a, _b, _c;
+        const parsed = parseKeystoneError(body);
+        const displayMessage = (_a = parsed === null || parsed === void 0 ? void 0 : parsed.detail) !== null && _a !== void 0 ? _a : (statusText || `HTTP ${status} error`);
+        super(`SFA API ${status}\u{FF1A}${displayMessage}`);
+        this.status = status;
+        this.statusText = statusText;
+        this.url = url;
+        this.name = 'SfaApiError';
+        this.detail = (_b = parsed === null || parsed === void 0 ? void 0 : parsed.detail) !== null && _b !== void 0 ? _b : null;
+        this.code = (_c = parsed === null || parsed === void 0 ? void 0 : parsed.code) !== null && _c !== void 0 ? _c : null;
+        this.body = body.slice(0, ERROR_BODY_MAX_LENGTH);
+    }
+}
+function parseKeystoneError(body) {
+    var _a, _b;
+    if (!body)
+        return null;
+    try {
+        const parsed = JSON.parse(body);
+        if (typeof parsed['detail'] === 'string') {
+            return {
+                detail: parsed['detail'],
+                code: (_a = parsed['code']) !== null && _a !== void 0 ? _a : '',
+                title: (_b = parsed['title']) !== null && _b !== void 0 ? _b : undefined,
+            };
+        }
+    }
+    catch (_c) {
+        // Not JSON or missing detail field
+    }
+    return null;
+}
+// ── Mutation error helpers ──
+function parseConflictRecord(body) {
+    var _a, _b;
+    try {
+        const parsed = JSON.parse(body);
+        const recordData = (_b = (_a = parsed['current_record']) !== null && _a !== void 0 ? _a : parsed['record']) !== null && _b !== void 0 ? _b : parsed['current'];
+        if (recordData && typeof recordData === 'object') {
+            return normalizeKeystoneRecord(recordData);
+        }
+    }
+    catch (_c) {
+        // Body may not contain the current record
+    }
+    return null;
+}
+function parseFieldErrors(body) {
+    try {
+        const parsed = JSON.parse(body);
+        const rawErrors = parsed['errors'];
+        if (Array.isArray(rawErrors)) {
+            return rawErrors
+                .filter((e) => e != null && typeof e === 'object')
+                .map(e => {
+                var _a, _b, _c;
+                return ({
+                    field: (_a = e['field']) !== null && _a !== void 0 ? _a : '',
+                    code: (_b = e['code']) !== null && _b !== void 0 ? _b : '',
+                    message: (_c = e['message']) !== null && _c !== void 0 ? _c : '',
+                });
+            });
+        }
+    }
+    catch (_a) {
+        // Body may not be parseable
+    }
+    return [];
+}
+// ── Mutation error classes ──
+/**
+ * @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 class SfaConflictError extends SfaApiError {
+    constructor(status, statusText, body, url, currentRecord) {
+        super(status, statusText, body, url);
+        this.name = 'SfaConflictError';
+        this.currentRecord = currentRecord;
+    }
+    static fromBody(status, statusText, body, url) {
+        const currentRecord = parseConflictRecord(body);
+        return new SfaConflictError(status, statusText, body, url, currentRecord);
+    }
+}
+/**
+ * @description Thrown on 422 with code VALIDATION_FAILED. Exposes per-field
+ * errors so the UI can highlight which fields need correction.
+ */
+export class SfaValidationError extends SfaApiError {
+    constructor(status, statusText, body, url, fieldErrors) {
+        super(status, statusText, body, url);
+        this.name = 'SfaValidationError';
+        this.fieldErrors = fieldErrors;
+    }
+    static fromBody(status, statusText, body, url) {
+        const fieldErrors = parseFieldErrors(body);
+        return new SfaValidationError(status, statusText, body, url, fieldErrors);
+    }
+}