@geniee-inc/sfa-kit 1.10.0 → 1.12.0

package/src/lib/provider/SfaClient.js

@@ -2,13 +2,47 @@ 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 How long a bulk write may take before the browser gives up.
+ *
+ * NOTE: a bulk write is slower than any other call — the server works through
+ * the rows one at a time, with a 45 s budget of its own — so the default 30 s
+ * would abort a full batch part-way. The abort only stops the browser: the
+ * server keeps writing, the response is dropped, and the caller loses the ids
+ * of everything that landed. Waiting longer than the server's own budget is
+ * what makes the answer reachable.
+ *
+ * NOTE: 60 s is the ceiling, not a preference. That is the ALB idle timeout
+ * (AWS default; the API gateway is off in both staging and production), so a
+ * request held open longer is cut by the load balancer instead.
+ */
+const BULK_REQUEST_TIMEOUT_MS = 60000;
+/**
+ * @description The most rows one bulk call sends.
+ *
+ * NOTE: the API's own contract is `minItems: 1, maxItems: 100`. 25 is the
+ * kit's stricter limit, and it comes from how long the call takes rather than
+ * from what the API accepts: Keystone delegates one row at a time, measured at
+ * about 1.4 s per row on staging (2026-09-04). 25 rows fits inside the
+ * server's own 45 s budget for a bulk write, which in turn fits inside the
+ * 60 s ALB idle timeout. Agreed with Kumada and Takeuchi.
+ *
+ * Do not raise this to match `maxItems` — a call of 100 rows would outlast
+ * the server's budget and then the load balancer, and the caller would learn
+ * nothing about which rows had been written. It can go up only once a row
+ * costs less, or those limits change.
+ *
+ * NOTE: public because a caller cannot batch without it, and kept next to the
+ * check that enforces it so the two cannot disagree.
+ */
+export const SFA_BULK_MAX_ROWS = 25;
 /**
  * @description Returns a timeout AbortSignal, or undefined where the runtime
  * doesn't support AbortSignal.timeout (e.g. older jsdom in tests).
  */
-function timeoutSignal() {
+function timeoutSignal(timeoutMs = REQUEST_TIMEOUT_MS) {
     if (typeof AbortSignal.timeout === 'function') {
-        return AbortSignal.timeout(REQUEST_TIMEOUT_MS);
+        return AbortSignal.timeout(timeoutMs);
     }
     return undefined;
 }
@@ -91,6 +125,9 @@ export class SfaClient {
                 if (params === null || params === void 0 ? void 0 : params.filter) {
                     body['filter'] = params.filter;
                 }
+                if (params === null || params === void 0 ? void 0 : params.listId) {
+                    body['list_id'] = params.listId;
+                }
                 const path = `/v1/objects/${enc(collection)}/records/query`;
                 const raw = yield this.postJson(path, body);
                 return normalizeKeystoneListResponse(raw, pageIndex, pageSize);
@@ -165,23 +202,118 @@ export class SfaClient {
         }
     }
     /**
-     * @description Creates a new record. Optionally accepts an idempotency key
-     * to prevent duplicate creates on retries.
+     * @description Creates a new record.
+     *
+     * NOTE: a retried create writes a second record — nothing de-duplicates it.
      */
-    create(collection, fields, options) {
+    create(collection, fields, 
+    // NOTE: kept so the class matches the published interface. Its only member
+    // is inert, so nothing reads it; it goes when the type does
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    options) {
         return __awaiter(this, void 0, void 0, function* () {
             this.assertDirectMode();
             const normalized = yield this.applySchemaAwareNormalization(collection, fields);
             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(normalized) }, extra);
+            const response = yield this.fetchWithBody('POST', path, {
+                fields: normalizeWriteFields(normalized),
+            });
             const raw = yield response.json();
             return normalizeKeystoneRecord(raw);
         });
     }
+    /**
+     * @description Creates many records of one object in a single call.
+     *
+     * The call is best-effort per row: the API answers 200 and reports every
+     * row's outcome, so a failed row does not undo the ones that worked. Per-row
+     * failures come back as results, not as thrown errors — throwing would
+     * discard the ids of the rows that succeeded, which are not recoverable
+     * anywhere else. SfaValidationError and the rest still surface when the
+     * whole call is rejected.
+     *
+     * Retry only the failed rows. What makes that safe is that those rows did
+     * not apply: nothing on the server de-duplicates a repeated write.
+     */
+    bulkCreate(collection, rows) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.assertDirectMode();
+            assertBulkRowCount(rows.length);
+            const normalizedRows = yield Promise.all(rows.map((fields) => __awaiter(this, void 0, void 0, function* () {
+                return ({
+                    fields: yield this.normalizeRowFields(collection, fields),
+                });
+            })));
+            return this.postBulk(collection, 'bulk-create', normalizedRows);
+        });
+    }
+    /**
+     * @description Updates many records of one object in a single call.
+     *
+     * Each row carries its own `version`, so a stale row comes back as
+     * `conflict` with the server's current record to reconcile from — the rest
+     * of the batch still applies, and nothing is rolled back. Per-row outcomes
+     * are results, not thrown errors: a throw would hide which rows landed.
+     */
+    bulkUpdate(collection, rows) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.assertDirectMode();
+            assertBulkRowCount(rows.length);
+            for (const row of rows)
+                this.assertRecordId(row.id);
+            const normalizedRows = yield Promise.all(rows.map((row) => __awaiter(this, void 0, void 0, function* () {
+                return ({
+                    id: row.id,
+                    version: row.version,
+                    fields: yield this.normalizeRowFields(collection, row.fields),
+                });
+            })));
+            return this.postBulk(collection, 'bulk-update', normalizedRows);
+        });
+    }
+    /**
+     * @description Deletes many records of one object in a single call.
+     *
+     * Each row carries the `version` last read for it; a stale row comes back as
+     * `conflict` and is left in place while the rest of the batch applies.
+     */
+    bulkDelete(collection, rows) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.assertDirectMode();
+            assertBulkRowCount(rows.length);
+            for (const row of rows)
+                this.assertRecordId(row.id);
+            return this.postBulk(collection, 'bulk-delete', rows.map(row => ({ id: row.id, version: row.version })));
+        });
+    }
+    /**
+     * @description Prepares one row's fields for a bulk write.
+     *
+     * NOTE: shared by bulk-create and bulk-update so the two steps stay in this
+     * order for both. Schema-aware normalisation reads the object's field types
+     * — a select written by label, a date written loosely — and the write
+     * normalisation that follows only shapes what it produced.
+     */
+    normalizeRowFields(collection, fields) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return normalizeWriteFields(yield this.applySchemaAwareNormalization(collection, fields));
+        });
+    }
+    /**
+     * @description Sends one bulk request and reads its per-row outcomes.
+     *
+     * NOTE: shared by the three bulk methods so the envelope and the result
+     * parsing cannot drift apart between them.
+     */
+    postBulk(collection, operation, records) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const path = `/v1/objects/${enc(collection)}/records/${operation}`;
+            const response = yield this.fetchWithBody('POST', path, { records }, {
+                timeoutMs: BULK_REQUEST_TIMEOUT_MS,
+            });
+            return normalizeBulkResults(yield response.json(), records.length);
+        });
+    }
     /**
      * @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
@@ -193,7 +325,7 @@ export class SfaClient {
             this.assertRecordId(recordId);
             const normalized = yield this.applySchemaAwareNormalization(collection, fields);
             const path = `/v1/objects/${enc(collection)}/records/${enc(recordId)}`;
-            const response = yield this.fetchWithBody('PATCH', path, { fields: normalizeWriteFields(normalized) }, { 'If-Match': version });
+            const response = yield this.fetchWithBody('PATCH', path, { fields: normalizeWriteFields(normalized) }, { headers: { 'If-Match': version } });
             const raw = yield response.json();
             return normalizeKeystoneRecord(raw);
         });
@@ -228,7 +360,7 @@ export class SfaClient {
             this.assertRecordId(recordId);
             const path = `/v1/objects/${enc(collection)}/records/${enc(recordId)}`;
             yield this.fetchWithBody('DELETE', path, undefined, {
-                'If-Match': version,
+                headers: { 'If-Match': version },
             });
         });
     }
@@ -310,17 +442,17 @@ export class SfaClient {
      * body / extra headers. Returns the raw Response so callers can inspect
      * status codes, headers, or handle empty bodies (204).
      */
-    fetchWithBody(method, path, body, extraHeaders) {
+    fetchWithBody(method, path, body, options) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a;
             const url = `${this.apiBase}${path}`;
-            const headers = Object.assign({ 'Content-Type': 'application/json' }, extraHeaders);
+            const headers = Object.assign({ 'Content-Type': 'application/json' }, options === null || options === void 0 ? void 0 : options.headers);
             this.applyAuth(headers);
             const response = yield globalThis.fetch(url, {
                 method,
                 headers,
                 body: body ? JSON.stringify(body) : undefined,
-                signal: timeoutSignal(),
+                signal: timeoutSignal(options === null || options === void 0 ? void 0 : options.timeoutMs),
             });
             if (!response.ok) {
                 if (response.status === 401)
@@ -725,27 +857,243 @@ function parseConflictRecord(body) {
     }
     return null;
 }
+/**
+ * @description Guards the row count before a request goes out.
+ *
+ * NOTE: the API rejects the whole call with 422 when the array is empty or
+ * longer than the limit, so a caller that over-sends loses every row. Saying
+ * so here names the limit instead of surfacing a generic validation failure.
+ */
+function assertBulkRowCount(count) {
+    if (count === 0) {
+        throw new Error('A bulk write needs at least one row.');
+    }
+    if (count > SFA_BULK_MAX_ROWS) {
+        throw new Error(`A bulk write accepts at most ${SFA_BULK_MAX_ROWS} rows, got ${count}. ` +
+            'Split the selection into batches.');
+    }
+}
+/**
+ * @description Reads the per-row outcomes out of a bulk response body.
+ *
+ * NOTE: results are ordered by `index`, not by their position in the array.
+ * That field exists to align them with the request, and a caller writing ids
+ * back into a grid needs submission order to be true.
+ *
+ * NOTE: a count that does not match the request is refused rather than
+ * returned. Unlike a row that failed — an expected outcome the caller must see
+ * — a short response leaves some submitted rows with no reported fate, and
+ * showing the rest as the whole picture makes those rows look neither written
+ * nor retryable. The caller has to re-read to learn the truth.
+ */
+function normalizeBulkResults(raw, submittedRowCount) {
+    const data = raw;
+    const rawResults = Array.isArray(data['results']) ? data['results'] : [];
+    const rows = rawResults
+        .filter((row) => row != null && typeof row === 'object')
+        .map(row => downgradeUnusableSuccess({
+        index: readRowIndex(row['index']),
+        id: readIdentifier(row['id']),
+        status: readBulkRowStatus(row['status']),
+        record: readBulkRecord(row['record']),
+        error: normalizeBulkRowError(row['error']),
+    }));
+    return alignedToTheRequest(rows, submittedRowCount);
+}
+/**
+ * @description The position in the request a result answers for, or null when
+ * the response does not say.
+ *
+ * NOTE: `index` is a required field, and the order the rows arrive in is not
+ * part of the contract. Filling a missing one from the array position would
+ * turn that order into a guarantee the API never gave, and a caller pairing
+ * results with its own rows would silently act on the wrong ones. A value that
+ * is not a whole position — fractional, negative, NaN, Infinity — says just as
+ * little.
+ */
+function readRowIndex(raw) {
+    const isWholePosition = typeof raw === 'number' && Number.isInteger(raw) && raw >= 0;
+    return isWholePosition ? raw : null;
+}
+/**
+ * @description Puts the results in request order, refusing a response that
+ * cannot be paired with the request.
+ *
+ * NOTE: the outcome for each submitted position is looked up by `index`, so
+ * the order the rows arrived in is never relied on. A position no row answers
+ * for — an index missing, invalid, repeated, or past the end — is refused for
+ * the whole call: that submitted row would have no reported outcome, and
+ * handing back the rest would show it as neither written nor retryable.
+ *
+ * NOTE: the count is checked after parsing, not on the raw array. An entry
+ * that is not an object is dropped on the way in, so counting the raw array
+ * would pass a response of the right length that answers for fewer rows than
+ * it appears to.
+ */
+function alignedToTheRequest(rows, submittedRowCount) {
+    if (rows.length !== submittedRowCount) {
+        throw new Error(`A bulk write answered with ${rows.length} results for ` +
+            `${submittedRowCount} submitted rows. Re-read the records to find ` +
+            'out which ones landed.');
+    }
+    const byPosition = new Map(rows.flatMap(row => (row.index == null ? [] : [[row.index, row]])));
+    return Array.from({ length: submittedRowCount }, (_row, position) => {
+        const answered = byPosition.get(position);
+        if ((answered === null || answered === void 0 ? void 0 : answered.index) == null) {
+            throw new Error(`A bulk write answered for rows [${rows
+                .map(row => { var _a; return (_a = row.index) !== null && _a !== void 0 ? _a : '?'; })
+                .join(', ')}] of ${submittedRowCount} submitted, so a result ` +
+                'cannot be paired with the row that produced it. Re-read the ' +
+                'records to find out which ones landed.');
+        }
+        return Object.assign(Object.assign({}, answered), { index: answered.index });
+    });
+}
+/**
+ * @description An identifier, or null when the row does not carry a usable one.
+ *
+ * NOTE: an empty string is not an id. Reported as one it would reach a caller
+ * as a row it believes was written — a delete would list `''` among the ids it
+ * removed — so the row counts as not landed instead.
+ */
+function readIdentifier(raw) {
+    return typeof raw === 'string' && raw !== '' ? raw : null;
+}
+/**
+ * @description The record a row produced, or null when there is none to use.
+ *
+ * NOTE: normalisation answers with an empty shell for a body it cannot read,
+ * and a shell is not what a written row produces: it has no id and no version.
+ * Passing it on would let the row count as written and hand a grid a blank row
+ * with nothing to save against, so the row is reported as not landed. The same
+ * applies to a conflict, whose record exists only to reconcile against.
+ */
+function readBulkRecord(raw) {
+    if (raw == null || typeof raw !== 'object')
+        return null;
+    const record = normalizeKeystoneRecord(raw);
+    return record.record_id === '' ? null : record;
+}
+/**
+ * @description Refuses to report a write that nothing can be built on.
+ *
+ * NOTE: a created or updated row answers with the record it produced, and the
+ * contract has that record carry a `version` — the token the next update or
+ * delete locks against. Reported as written, such a row would be handed to a
+ * grid as the saved state of that row, and the next save would have nothing to
+ * address it by. A row answering with no record at all is the same problem one
+ * step earlier, and each says so in its own code: a reader of the log should
+ * not have to guess which of the two the server sent.
+ *
+ * NOTE: it is not reported as failed either. The row did land, and `failed`
+ * asks the caller to retry it — for a create that would write a second record.
+ * `unknown` says what a retry cannot fix while keeping the id: re-read the
+ * record.
+ *
+ * NOTE: a conflict is left as it is. Its record exists to reconcile against,
+ * it already counts as not landed, and calling it `unknown` would throw away
+ * the one thing the caller needs to know about it.
+ */
+function downgradeUnusableSuccess(row) {
+    const wroteARecord = row.status === 'created' || row.status === 'updated';
+    if (!wroteARecord)
+        return row;
+    if (row.record == null) {
+        return unresolved(row, 'missing_record', 'The write reported success but answered with no record, so there is ' +
+            'nothing to write back. Re-read the record to find out what landed.');
+    }
+    if (!isUsableVersion(row.record.version)) {
+        return unresolved(row, 'missing_version', 'The written record carried no version to save against. Re-read it ' +
+            'before writing to it again.');
+    }
+    return row;
+}
+/**
+ * @description Marks a row as one the kit cannot report either way, keeping
+ * whatever the server did say about it.
+ */
+function unresolved(row, code, message) {
+    var _a;
+    return Object.assign(Object.assign({}, row), { status: 'unknown', error: (_a = row.error) !== null && _a !== void 0 ? _a : { code, message, fieldErrors: [] } });
+}
+function isUsableVersion(version) {
+    return typeof version === 'string' && version !== '';
+}
+/**
+ * @description Reads a row's outcome, keeping unrecognised ones distinguishable.
+ *
+ * NOTE: a status outside the contract becomes `unknown` rather than being
+ * passed through under the union's type. The row still comes back — a create
+ * that landed carries an id recoverable nowhere else — but no caller can
+ * mistake it for a written row.
+ */
+function readBulkRowStatus(raw) {
+    var _a;
+    const known = {
+        created: 'created',
+        updated: 'updated',
+        deleted: 'deleted',
+        conflict: 'conflict',
+        invalid: 'invalid',
+        not_attempted: 'not_attempted',
+        indeterminate: 'indeterminate',
+    };
+    return typeof raw === 'string' ? (_a = known[raw]) !== null && _a !== void 0 ? _a : 'unknown' : 'unknown';
+}
+function normalizeBulkRowError(raw) {
+    // NOTE: a plain string is not the Problem shape the contract promises, but
+    // it is still the server's own account of the failure — kept as the message
+    // rather than dropped, or the row would fail with nothing said about why
+    if (typeof raw === 'string') {
+        return { code: '', message: raw, fieldErrors: [] };
+    }
+    if (raw == null || typeof raw !== 'object')
+        return null;
+    const problem = raw;
+    return {
+        code: typeof problem['code'] === 'string' ? problem['code'] : '',
+        // NOTE: Problem carries the human-readable text in `detail`, with `title`
+        // as the fallback when the server sent only a summary
+        message: readProblemText(problem['detail'], problem['title']),
+        fieldErrors: readFieldErrors(problem['errors']),
+    };
+}
+/** @description Problem's human-readable text, `detail` first, `title` after. */
+function readProblemText(detail, title) {
+    if (typeof detail === 'string')
+        return detail;
+    return typeof title === 'string' ? title : '';
+}
 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 : '',
-                });
-            });
-        }
+        return readFieldErrors(parsed['errors']);
     }
     catch (_a) {
         // Body may not be parseable
+        return [];
     }
-    return [];
+}
+/**
+ * @description Reads Problem's `errors` extension member.
+ *
+ * NOTE: separate from parseFieldErrors so a caller that already has the parsed
+ * Problem — a bulk row, which arrives inside a 200 body — does not serialize it
+ * back to a string just to read it again.
+ */
+function readFieldErrors(rawErrors) {
+    if (!Array.isArray(rawErrors))
+        return [];
+    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 : '',
+        });
+    });
 }
 // ── Mutation error classes ──
 /**

package/src/lib/provider/SfaProvider.js

@@ -23,22 +23,29 @@ export function SfaProvider({ apiBase, auth, mode, organizationId, onAuthError,
     // Use a ref for onAuthError so updates don't trigger client re-creation.
     const onAuthErrorRef = useRef(onAuthError);
     onAuthErrorRef.current = onAuthError;
-    const value = useMemo(() => {
-        const stableAuth = accessToken ? { accessToken } : undefined;
-        const client = new SfaClient({
-            apiBase,
-            auth: stableAuth,
-            mode: resolvedMode,
-            organizationId: resolvedOrgId,
-            onAuthError: () => { var _a; return (_a = onAuthErrorRef.current) === null || _a === void 0 ? void 0 : _a.call(onAuthErrorRef); },
-        });
-        return {
-            client,
-            auth: stableAuth,
-            mode: resolvedMode,
-            organizationId: resolvedOrgId,
-            readOnly,
-        };
-    }, [apiBase, accessToken, resolvedMode, resolvedOrgId, readOnly]);
+    const stableAuth = useMemo(() => (accessToken ? { accessToken } : undefined), [accessToken]);
+    /**
+     * NOTE: `readOnly` is deliberately not a dependency here. The client does
+     * not read it — it is a context flag the hooks check before writing — and
+     * rebuilding the client would change its identity. Consumers treat a new
+     * client as a different session: a bulk write in flight would be judged to
+     * belong to the previous one and its per-row report dropped, while the
+     * request itself carries on and the server applies the rows. The describe
+     * cache would go with it.
+     */
+    const client = useMemo(() => new SfaClient({
+        apiBase,
+        auth: stableAuth,
+        mode: resolvedMode,
+        organizationId: resolvedOrgId,
+        onAuthError: () => { var _a; return (_a = onAuthErrorRef.current) === null || _a === void 0 ? void 0 : _a.call(onAuthErrorRef); },
+    }), [apiBase, stableAuth, resolvedMode, resolvedOrgId]);
+    const value = useMemo(() => ({
+        client,
+        auth: stableAuth,
+        mode: resolvedMode,
+        organizationId: resolvedOrgId,
+        readOnly,
+    }), [client, stableAuth, resolvedMode, resolvedOrgId, readOnly]);
     return _jsx(SfaContext.Provider, { value: value, children: children });
 }

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

@@ -50,6 +50,15 @@ export interface SfaListResponse {
     /** Cursor for fetching the previous page (keystone cursor-based pagination). */
     readonly prevCursor?: string | null;
 }
+/**
+ * @description The shape of the client SfaProvider hands out — not an
+ * extension point.
+ *
+ * NOTE: methods are added here as the API surface grows, so this interface is
+ * not treated as a breaking change when it gains one. Consumers take the
+ * client from `useSfaClient()`; a test that needs a stand-in mocks that hook
+ * rather than implementing this.
+ */
 export interface SfaClientInterface {
     get(collection: string, recordId: string): Promise<SfaRecord>;
     list(collection: string, params?: SfaListParams): Promise<SfaListResponse>;
@@ -59,12 +68,21 @@ export interface SfaClientInterface {
     create(collection: string, fields: Record<string, unknown>, options?: SfaCreateOptions): Promise<SfaRecord>;
     update(collection: string, recordId: string, fields: Record<string, unknown>, version: string): Promise<SfaRecord>;
     delete(collection: string, recordId: string, version: string): Promise<void>;
+    bulkCreate(collection: string, rows: readonly Record<string, unknown>[]): Promise<readonly SfaBulkRowResult[]>;
+    bulkUpdate(collection: string, rows: readonly SfaBulkUpdateRow[]): Promise<readonly SfaBulkRowResult[]>;
+    bulkDelete(collection: string, rows: readonly SfaBulkDeleteRow[]): Promise<readonly SfaBulkRowResult[]>;
 }
 /**
- * @description Options for creating a record. The idempotency key prevents
- * duplicate creates if the same request is retried.
+ * @description Options for creating one record. Its only member is
+ * deprecated, so the type itself goes at the next breaking release.
  */
 export interface SfaCreateOptions {
+    /**
+     * @deprecated Accepted and ignored. Keystone never de-duplicated on
+     * `Idempotency-Key`, and SFAJAI-294 drops the header from the contract, so
+     * the kit no longer sends it. Kept only because removing it would fail the
+     * build of callers that pass it; drop it at the next breaking release.
+     */
     readonly idempotencyKey?: string;
 }
 /**
@@ -75,6 +93,70 @@ export interface SfaFieldError {
     readonly code: string;
     readonly message: string;
 }
+/**
+ * @description How one row of a bulk write ended.
+ *
+ * `conflict` means the row's `version` no longer matched, `invalid` that it
+ * failed validation. `not_attempted` means the call ran out of budget before
+ * this row started, so nothing was written and it can be sent again exactly as
+ * it was. `indeterminate` means the server cannot say whether the row applied.
+ * All are reported per row with HTTP 200 — a bulk call is best-effort and has
+ * no all-or-nothing mode.
+ *
+ * `unknown` is not sent by the API: it is what the kit reads an unrecognised
+ * status as, and what a claimed success it cannot make sense of becomes — no
+ * record, or no `version` for the next write to lock against. The row keeps
+ * its `id`, and reaches the caller in `unresolved`, never in `failed`:
+ * retrying a create that already landed writes a second record.
+ */
+export type SfaBulkRowStatus = 'created' | 'updated' | 'deleted' | 'conflict' | 'invalid' | 'not_attempted' | 'indeterminate' | 'unknown';
+/** @description One row of a bulk update: what to change and from which version. */
+export interface SfaBulkUpdateRow {
+    readonly id: string;
+    /**
+     * The version last read for this record. A mismatch makes this row a
+     * `conflict` and leaves it unchanged; the rest of the batch still applies.
+     */
+    readonly version: string;
+    /** Only the keys present are changed. */
+    readonly fields: Record<string, unknown>;
+}
+/** @description One row of a bulk delete: what to remove and from which version. */
+export interface SfaBulkDeleteRow {
+    readonly id: string;
+    /** As in an update — a stale version makes this row a `conflict`. */
+    readonly version: string;
+}
+/** @description The outcome of one submitted row, positioned by `index`. */
+export interface SfaBulkRowResult {
+    /** Zero-based position in the request, for mapping the result back to input. */
+    readonly index: number;
+    /**
+     * The record's identifier. Always present for update and delete; on create
+     * only once the row succeeded. Null when the response carried none the
+     * caller could use, which makes the row count as not landed.
+     */
+    readonly id: string | null;
+    readonly status: SfaBulkRowStatus;
+    /**
+     * On a successful create or update, the resulting record. On a conflict, the
+     * server's current state, so the caller can show what it lost to. Otherwise
+     * null — including when the response carried a record that could not be
+     * read, since an unusable record is nothing to write back or reconcile
+     * against.
+     */
+    readonly record: SfaRecord | null;
+    /** Set on `conflict` and `invalid`: the problem detail for this row. */
+    readonly error: SfaBulkRowError | null;
+}
+/** @description Why one row failed, in the same shape single writes report. */
+export interface SfaBulkRowError {
+    /** Machine-readable problem code, e.g. `version_mismatch`. */
+    readonly code: string;
+    readonly message: string;
+    /** Per-field errors when the row failed validation. */
+    readonly fieldErrors: readonly SfaFieldError[];
+}
 export interface SfaListParams {
     readonly limit?: number;
     readonly offset?: number;
@@ -83,6 +165,8 @@ export interface SfaListParams {
     readonly filter?: Record<string, unknown>;
     /** Opaque cursor for keystone cursor-based pagination. Takes precedence over offset. */
     readonly cursor?: string;
+    /** List tab pre-filter. Sent as `list_id` in the keystone query body. */
+    readonly listId?: string;
 }
 export type SfaObjectOrigin = 'standard' | 'custom';
 export type SfaRelationshipKind = 'association' | 'master_detail';

package/src/lib/version.d.ts

@@ -1 +1 @@
-export declare const SFA_KIT_VERSION = "1.10.0";
+export declare const SFA_KIT_VERSION = "1.12.0";

package/src/lib/version.js

@@ -1,3 +1,3 @@
 // このファイルは libs/sfa-kit/scripts/sync-version.cjs が生成する。
 // 手で編集しないこと。バージョンを上げるときは libs/sfa-kit/package.json を変更する。
-export const SFA_KIT_VERSION = '1.10.0';
+export const SFA_KIT_VERSION = '1.12.0';