@geniee-inc/sfa-kit 1.11.0 → 1.13.0

package/src/lib/provider/SfaClient.js

@@ -2,13 +2,48 @@ 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 size its batches or its own warning
+ * 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 +126,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 +203,119 @@ 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,
+                bulkUnsupportedOn501: true,
+            });
+            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 +327,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 +362,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 +444,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)
@@ -332,6 +466,11 @@ export class SfaClient {
                 if (response.status === 422) {
                     throw SfaValidationError.fromBody(response.status, response.statusText, text, url);
                 }
+                // NOTE: only the bulk endpoints answer 501, and only they can say what
+                // it means to the reader. A 501 elsewhere stays a plain SfaApiError
+                if (response.status === 501 && (options === null || options === void 0 ? void 0 : options.bulkUnsupportedOn501)) {
+                    throw new SfaBulkUnsupportedError(response.status, response.statusText, text, url);
+                }
                 throw new SfaApiError(response.status, response.statusText, text, url);
             }
             return response;
@@ -725,27 +864,240 @@ function parseConflictRecord(body) {
     }
     return null;
 }
+/**
+ * @description Guards the row count before a request goes out.
+ *
+ * NOTE: an empty array is rejected by the API with 422 for the whole call, and
+ * a selection over the kit's limit is refused before it can be sent at all.
+ * Either way the caller loses every row, so this names the limit and the count
+ * instead of leaving a generic validation failure to explain it.
+ */
+function assertBulkRowCount(count) {
+    if (count === 0 || count > SFA_BULK_MAX_ROWS) {
+        throw new SfaBulkRowCountError(count);
+    }
+}
+/**
+ * @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 ──
 /**
@@ -764,6 +1116,65 @@ export class SfaConflictError extends SfaApiError {
         return new SfaConflictError(status, statusText, body, url, currentRecord);
     }
 }
+/**
+ * @description A bulk write refused before a request went out: nothing was
+ * selected, or more rows than the kit sends in one call.
+ *
+ * NOTE: `message` is for the log, like the rest of the kit's errors, and
+ * `userMessage` is what a page shows the reader — the same split the kit
+ * already makes between an error and the text in `FetchErrorState`. The page
+ * decides where to show it; the kit has no UI of its own.
+ *
+ * NOTE: a distinct class so a page recognises this without matching on the
+ * message. It is the one write failure a reader causes and can fix.
+ */
+export class SfaBulkRowCountError extends Error {
+    /** @param submitted how many rows the caller tried to send */
+    constructor(submitted) {
+        super(rowCountLogText(submitted));
+        this.submitted = submitted;
+        /** The most rows one call sends, so a page can say it without importing it. */
+        this.limit = SFA_BULK_MAX_ROWS;
+        this.name = 'SfaBulkRowCountError';
+        this.userMessage = rowCountReaderText(submitted);
+    }
+}
+/**
+ * @description Thrown when the object offers no bulk writes at all: the
+ * endpoint answers 501.
+ *
+ * NOTE: told apart from other failures because waiting changes nothing. A
+ * page with no wording of its own says to try again later, which is the one
+ * thing that cannot work here — the operation is not implemented for this
+ * object, today or in an hour.
+ */
+export class SfaBulkUnsupportedError extends SfaApiError {
+    /**
+     * NOTE: takes the response as it arrived, like every other error here, so
+     * the server's `detail` and `code` are read from the whole body. Building
+     * it from an `SfaApiError` instead would re-read a body already cut to
+     * `ERROR_BODY_MAX_LENGTH`, and a cut inside the JSON leaves nothing to read.
+     */
+    constructor(status, statusText, body, url) {
+        super(status, statusText, body, url);
+        /** What a page shows the reader. `message` is the English text for the log. */
+        this.userMessage = 'このオブジェクトでは一括操作を利用できません。';
+        this.name = 'SfaBulkUnsupportedError';
+    }
+}
+function rowCountLogText(submitted) {
+    if (submitted === 0)
+        return 'A bulk write needs at least one row.';
+    return (`A bulk write accepts at most ${SFA_BULK_MAX_ROWS} rows, ` +
+        `got ${submitted}. Split the selection into batches.`);
+}
+function rowCountReaderText(submitted) {
+    if (submitted === 0)
+        return '保存する行が選択されていません。';
+    return (`一度に保存できるのは ${SFA_BULK_MAX_ROWS} 件までです。` +
+        `選択されているのは ${submitted} 件です。` +
+        `選択を ${SFA_BULK_MAX_ROWS} 件以下に減らしてから保存してください。`);
+}
 /**
  * @description Thrown on 422 with code VALIDATION_FAILED. Exposes per-field
  * errors so the UI can highlight which fields need correction.

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 });
 }