@geniee-inc/sfa-kit 1.14.1 → 1.16.0

package/GUIDE.md

@@ -286,9 +286,11 @@ that did land, and those are not recoverable anywhere else.
   whole picture leaves it looking neither written nor retryable. Re-read the
   records to find out what landed
 - `failed` — the rows that did not land **and can be sent again**: `conflict`,
-  `invalid` and `not_attempted`. Retry exactly these. What makes that safe is
-  that they did not apply; there is no server-side de-duplication to fall back
-  on
+  `invalid`, `not_attempted`, `not_found` and `not_permitted`. Retry exactly
+  these. What makes that safe is that they did not apply; there is no
+  server-side de-duplication to fall back on. Read each row's `status` before
+  offering a retry: `not_found` and `not_permitted` are the server's settled
+  answer, and resending alone will not change it
 - `unresolved` — the rows that may already be written but cannot be reported
   either way. They keep whatever `id` arrived. **Re-read these; never retry
   them**: a create that already landed would be written twice
@@ -375,7 +377,9 @@ return (
       <ErrorSnackbar
         error={null}
         message={`${results.length} 件中 ${updated.length} 件を保存しました。${failed.length} 件は保存されていません。`}
-        onRetry={() => void bulkUpdate(rowsFor(failed)).catch(() => undefined)}
+        onRetry={() =>
+          void bulkUpdate(rowsFor(resendable(failed))).catch(() => undefined)
+        }
         onClose={reset}
       />
     )}
@@ -385,17 +389,42 @@ return (
 
 Counts only: which row failed and why belongs in the grid, where the reader
 acts on it — `results` carries each row's `index` and its per-field errors.
-Offer `onRetry` for `failed` rows; `unresolved` rows are re-read instead, so
-label the action accordingly (`retryLabel`).
+`unresolved` rows are re-read instead, so label the action accordingly
+(`retryLabel`).
+
+Offer `onRetry` for the `failed` rows a resend can still change — that is what
+`resendable` stands for above:
+
+```tsx
+const SETTLED = new Set(['not_found', 'not_permitted']);
+
+const resendable = (rows: readonly SfaBulkRowResult[]) =>
+  rows.filter(row => !SETTLED.has(row.status));
+```
+
+Every row in `failed` is safe to send again, but a `not_found` or
+`not_permitted` one comes back refused however often it is sent. Showing those
+under a retry button gives the reader an action that cannot succeed; report
+what they say instead.
 
 A row counts as written only when it carries what a write produces: the record
 for a create or an update, the id for a delete. Anything short of that is
 `failed` or `unresolved`, and which one is decided by what the answer says,
-not by elimination. Three statuses mean the row did not apply, and only those
-may be sent again: `conflict`, `invalid`, and `not_attempted` — the last for a
-row the call ran out of budget before starting, which is resent exactly as it
-was. A `conflict` carries the server's current record: retry with the
-`version` it reports, or re-read first if none arrived.
+not by elimination. Five statuses mean the row did not apply, and only those
+may be sent again:
+
+| Status          | What it means                                      | What to do                                                                 |
+| --------------- | -------------------------------------------------- | -------------------------------------------------------------------------- |
+| `conflict`      | Another write got there first                      | Retry with the `version` the row reports, or re-read first if none arrived |
+| `invalid`       | The row failed validation                          | Correct the row from its per-field errors, then resend                     |
+| `not_attempted` | The call ran out of budget before starting the row | Resend exactly as it was                                                   |
+| `not_found`     | The record the row named does not exist            | Tell the reader; a resend answers the same                                 |
+| `not_permitted` | The caller may not write that record               | Tell the reader; a resend answers the same                                 |
+
+`not_found` and `not_permitted` are refusals of a row the call did reach, so no
+write happened and resending is safe — it is simply futile until the record or
+the permission changes. Their `error.code` may be an empty string: keystone has
+not minted one for `not_permitted`, so branch on `status` rather than `code`.
 
 Everything else is `unresolved`: `indeterminate`, the server saying it cannot
 tell whether the row applied; a claimed success missing what it should carry —

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geniee-inc/sfa-kit",
-  "version": "1.14.1",
+  "version": "1.16.0",
   "description": "React hooks and components for building pages that connect to GENIEE SFA/CRM data.",
   "type": "module",
   "main": "./src/index.js",

package/src/lib/auth/ObjectKeyGuard.d.ts

@@ -0,0 +1,12 @@
+import { type ReactNode } from 'react';
+interface ObjectKeyGuardProps {
+    readonly objectKey: string;
+    readonly children: ReactNode;
+}
+/**
+ * objectKey が組織のオブジェクトカタログに存在することを検証する。
+ * 不一致の場合はページ本体の代わりにエラーバナーを表示し、
+ * singular / typo のキーがリフレッシュ時に 404 で壊れる前に検出する。
+ */
+export declare function ObjectKeyGuard({ objectKey, children }: ObjectKeyGuardProps): JSX.Element;
+export {};

package/src/lib/auth/ObjectKeyGuard.js

@@ -0,0 +1,61 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useObjectCatalog } from '../hooks/useObjectCatalog';
+import { font, space } from '../theme';
+/**
+ * objectKey が組織のオブジェクトカタログに存在することを検証する。
+ * 不一致の場合はページ本体の代わりにエラーバナーを表示し、
+ * singular / typo のキーがリフレッシュ時に 404 で壊れる前に検出する。
+ */
+export function ObjectKeyGuard({ objectKey, children }) {
+    const { objects, isLoading, error } = useObjectCatalog();
+    // カタログ取得中やエラー時はブロックせずそのまま表示する。
+    // ガードが止めるのは「カタログに無い」と確定した場合のみ。
+    if (isLoading || error || objects.length === 0)
+        return _jsx(_Fragment, { children: children });
+    const knownKeys = objects.map(o => o.key);
+    if (knownKeys.includes(objectKey))
+        return _jsx(_Fragment, { children: children });
+    // 提案のみ大文字小文字を無視する。一致判定は API がキーを厳密比較するため厳密のまま
+    const target = objectKey.toLowerCase();
+    const suggestion = knownKeys.find(knownKey => {
+        const key = knownKey.toLowerCase();
+        return key.startsWith(target) || target.startsWith(key);
+    });
+    return (_jsx("div", { style: {
+            padding: space.lg,
+            fontFamily: font.family,
+            maxWidth: 560,
+            margin: '80px auto',
+        }, children: _jsxs("div", { style: {
+                background: '#FEF2F2',
+                border: '1px solid #FECACA',
+                borderRadius: 8,
+                padding: space.lg,
+            }, children: [_jsx("div", { style: {
+                        fontWeight: 700,
+                        fontSize: 15,
+                        color: '#991B1B',
+                        marginBottom: 8,
+                    }, children: "Invalid object key" }), _jsxs("p", { style: {
+                        margin: 0,
+                        fontSize: 14,
+                        color: '#7F1D1D',
+                        lineHeight: 1.5,
+                    }, children: [_jsx("code", { style: {
+                                background: '#FEE2E2',
+                                padding: '2px 6px',
+                                borderRadius: 4,
+                                fontSize: 13,
+                            }, children: objectKey }), ' ', "does not match any object in this organization.", suggestion && (_jsxs(_Fragment, { children: [' ', "Did you mean", ' ', _jsx("code", { style: {
+                                        background: '#DCFCE7',
+                                        padding: '2px 6px',
+                                        borderRadius: 4,
+                                        fontSize: 13,
+                                        color: '#166534',
+                                    }, children: suggestion }), "?"] }))] }), _jsx("p", { style: {
+                        margin: '12px 0 0',
+                        fontSize: 12,
+                        color: '#9CA3AF',
+                        lineHeight: 1.4,
+                    }, children: "Object keys are the plural collection name from the object catalogue (e.g. \"business_discussions\", not \"business_discussion\"). Check the objectKey prop on SfaLoginGate and the manifest." })] }) }));
+}

package/src/lib/auth/SfaLoginGate.js

@@ -6,6 +6,7 @@ import { color, font, radius, space, baseContainerStyle, baseButtonStyle, } from
 import { SFA_KIT_VERSION } from '../version';
 import { DevToolbar } from './DevToolbar';
 import { authenticate } from './keystone-auth';
+import { ObjectKeyGuard } from './ObjectKeyGuard';
 import { KEYSTONE_PRODUCTION_API_BASE, resolveApiBase, } from './resolve-api-base';
 import { loadSession, saveSession, clearSession, loadLastOrgId, } from './session-store';
 import { StandalonePreviewCtx } from './StandalonePreviewContext';
@@ -102,7 +103,7 @@ export function SfaLoginGate({ apiBase, trustedOrigin, defaultOrganizationId, ob
             return (_jsx(EmbedStatus, { title: "\u63A5\u7D9A\u3067\u304D\u307E\u305B\u3093", message: "SFA/CRM \u306E\u30DB\u30B9\u30C8\u30AA\u30EA\u30B8\u30F3\u3092\u78BA\u8A8D\u3067\u304D\u306A\u3044\u305F\u3081\u3001\u3053\u306E\u30DA\u30FC\u30B8\u3092\u8868\u793A\u3067\u304D\u307E\u305B\u3093\u3002\u57CB\u3081\u8FBC\u307F\u8A2D\u5B9A\u3092\u7BA1\u7406\u8005\u306B\u3054\u78BA\u8A8D\u304F\u3060\u3055\u3044\u3002" }));
         }
         // Embedded: the SFA/CRM host that framed us decides the environment.
-        return (_jsx(EmbedFlow, { trustedOrigin: resolvedOrigin, apiBase: apiBase !== null && apiBase !== void 0 ? apiBase : resolveApiBase(resolvedOrigin), children: children }));
+        return (_jsx(EmbedFlow, { objectKey: objectKey, trustedOrigin: resolvedOrigin, apiBase: apiBase !== null && apiBase !== void 0 ? apiBase : resolveApiBase(resolvedOrigin), children: children }));
     }
     // Standalone: there is no host, so the page's own origin decides.
     return (_jsx(StandaloneFlow, { apiBase: apiBase !== null && apiBase !== void 0 ? apiBase : resolveApiBase(resolvePageOrigin()), defaultOrganizationId: defaultOrganizationId, objectKey: objectKey, level: level, children: children }));
@@ -110,7 +111,7 @@ export function SfaLoginGate({ apiBase, trustedOrigin, defaultOrganizationId, ob
 // ---------------------------------------------------------------------------
 // Embed flow (iframe + postMessage)
 // ---------------------------------------------------------------------------
-function EmbedFlow({ trustedOrigin, apiBase, children, }) {
+function EmbedFlow({ objectKey, trustedOrigin, apiBase, children, }) {
     const normalizedBase = useMemo(() => apiBase.replace(/\/+$/, ''), [apiBase]);
     const { phase, handleAuthError } = useEmbedSession({
         apiBase: normalizedBase,
@@ -135,7 +136,7 @@ function EmbedFlow({ trustedOrigin, apiBase, children, }) {
     }
     if (!auth)
         return null;
-    return (_jsx(EmbedContextValue.Provider, { value: phase.context, children: _jsx(SfaProvider, { apiBase: normalizedBase, auth: auth, mode: "direct", organizationId: phase.session.organizationId, onAuthError: handleAuthError, children: children }) }));
+    return (_jsx(EmbedContextValue.Provider, { value: phase.context, children: _jsx(SfaProvider, { apiBase: normalizedBase, auth: auth, mode: "direct", organizationId: phase.session.organizationId, onAuthError: handleAuthError, children: objectKey ? (_jsx(ObjectKeyGuard, { objectKey: objectKey, children: children })) : (children) }) }));
 }
 function EmbedStatus({ title, message, showReload, }) {
     const handleReload = useCallback(() => {
@@ -241,7 +242,7 @@ function StandaloneFlow({ apiBase, defaultOrganizationId, objectKey, level, chil
     if (!session || !auth) {
         return (_jsx(LoginForm, { defaultApiBase: apiBase, defaultOrganizationId: defaultOrganizationId, onSubmit: handleLogin, status: status, error: error }));
     }
-    return (_jsx(SfaProvider, { apiBase: activeBase, auth: auth, mode: "direct", organizationId: session.organizationId, onAuthError: handleLogout, children: _jsxs(StandalonePreviewCtx.Provider, { value: previewControls, children: [_jsx(DevToolbar, { organizationId: session.organizationId, preview: previewControls, objectKey: objectKey, level: resolvedLevel, onLogout: handleLogout }), children] }) }));
+    return (_jsx(SfaProvider, { apiBase: activeBase, auth: auth, mode: "direct", organizationId: session.organizationId, onAuthError: handleLogout, children: _jsxs(StandalonePreviewCtx.Provider, { value: previewControls, children: [_jsx(DevToolbar, { organizationId: session.organizationId, preview: previewControls, objectKey: objectKey, level: resolvedLevel, onLogout: handleLogout }), objectKey ? (_jsx(ObjectKeyGuard, { objectKey: objectKey, children: children })) : (children)] }) }));
 }
 // ---------------------------------------------------------------------------
 // GENIEE SFA/CRM-branded login form

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

@@ -8,7 +8,9 @@ export interface BulkRowSplit<T> {
     readonly conflicts: readonly SfaBulkRowResult[];
     /**
      * The rows that did not land and can be sent again. A `conflict` is one of
-     * them, and also appears in `conflicts`.
+     * them, and also appears in `conflicts`. Read each row's `status` to say why
+     * it failed: `not_found` and `not_permitted` are settled refusals that a
+     * resend alone will not clear.
      */
     readonly failed: readonly SfaBulkRowResult[];
 }
@@ -16,9 +18,11 @@ export interface BulkRowSplit<T> {
  * @description Splits per-row outcomes by what the caller may do with them.
  *
  * NOTE: `failed` is decided by what the answer says, never by exclusion.
- * `conflict`, `invalid` and `not_attempted` all mean the row did not apply, so
- * those are the ones safe to send again — a row the call never started is as
- * unwritten as one the server rejected. Anything else the kit cannot place —
+ * `conflict`, `invalid`, `not_attempted`, `not_found` and `not_permitted` all
+ * mean the row did not apply, so those are the ones safe to send again — a row
+ * the call never started is as unwritten as one the server refused. Each keeps
+ * its own `status`, so a caller can tell "no permission" from "failed
+ * validation" without a bucket per reason. Anything else the kit cannot place —
  * `indeterminate`, no record, no version, a status outside the contract or
  * belonging to another operation — may already be written, and a retry would
  * write it twice.

package/src/lib/hooks/splitBulkRows.js

@@ -1,16 +1,29 @@
-/** The outcomes that mean the row did not apply, so sending it again is safe. */
+/**
+ * The outcomes that mean the row did not apply, so sending it again is safe.
+ *
+ * NOTE: safe to send again, not sure to succeed. `invalid` needs the row
+ * corrected first, `conflict` a fresh `version`, and `not_found` /
+ * `not_permitted` answer the same until the record or the permission changes.
+ * What the set decides is that no write happened, so the caller may resend
+ * without writing a second record — which is the question `unresolved` exists
+ * to answer, and the reason these belong in `failed` instead.
+ */
 const RETRYABLE_STATUSES = new Set([
     'conflict',
     'invalid',
     'not_attempted',
+    'not_found',
+    'not_permitted',
 ]);
 /**
  * @description Splits per-row outcomes by what the caller may do with them.
  *
  * NOTE: `failed` is decided by what the answer says, never by exclusion.
- * `conflict`, `invalid` and `not_attempted` all mean the row did not apply, so
- * those are the ones safe to send again — a row the call never started is as
- * unwritten as one the server rejected. Anything else the kit cannot place —
+ * `conflict`, `invalid`, `not_attempted`, `not_found` and `not_permitted` all
+ * mean the row did not apply, so those are the ones safe to send again — a row
+ * the call never started is as unwritten as one the server refused. Each keeps
+ * its own `status`, so a caller can tell "no permission" from "failed
+ * validation" without a bucket per reason. Anything else the kit cannot place —
  * `indeterminate`, no record, no version, a status outside the contract or
  * belonging to another operation — may already be written, and a retry would
  * write it twice.

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

@@ -18,7 +18,9 @@ export interface UseBulkCreateRecordsResult {
     /**
      * The rows that did not land and can be sent again, with their `index` and
      * `error`. A batch can be partly successful, so this being non-empty does
-     * not mean nothing was written — retry exactly these rows.
+     * not mean nothing was written. Read each row's `status` before retrying:
+     * `not_found` and `not_permitted` are settled refusals that come back the
+     * same however often they are resent.
      */
     readonly failed: readonly SfaBulkRowResult[];
     /**
@@ -50,7 +52,10 @@ export interface UseBulkCreateRecordsResult {
  * the call as a whole.
  *
  * Retry only the rows in `failed`: those did not apply, which is what makes
- * resending them safe. Re-read the rows in `unresolved` instead — nothing
- * protects against writing them twice.
+ * resending them safe — safe, not sure to succeed. A `not_found` or
+ * `not_permitted` row is refused again until the record or the permission
+ * changes, so branch on `status` rather than offering one retry for the whole
+ * bucket. Re-read the rows in `unresolved` instead — nothing protects against
+ * writing them twice.
  */
 export declare function useBulkCreateRecords(collection: string): UseBulkCreateRecordsResult;

package/src/lib/hooks/useBulkCreateRecords.js

@@ -14,8 +14,11 @@ const sendBulkCreate = (client, collection, rows) => client.bulkCreate(collectio
  * the call as a whole.
  *
  * Retry only the rows in `failed`: those did not apply, which is what makes
- * resending them safe. Re-read the rows in `unresolved` instead — nothing
- * protects against writing them twice.
+ * resending them safe — safe, not sure to succeed. A `not_found` or
+ * `not_permitted` row is refused again until the record or the permission
+ * changes, so branch on `status` rather than offering one retry for the whole
+ * bucket. Re-read the rows in `unresolved` instead — nothing protects against
+ * writing them twice.
  */
 export function useBulkCreateRecords(collection) {
     const { run, results, isLoading, error, reset } = useBulkWrite(collection, sendBulkCreate);

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

@@ -20,7 +20,16 @@ export interface UseBulkDeleteRecordsResult {
      * whether it still wants the record gone.
      */
     readonly conflicts: readonly SfaBulkRowResult[];
-    /** The rows still in place that can be sent again, conflicts included. */
+    /**
+     * The rows that were not removed by this call, conflicts included.
+     *
+     * NOTE: not all of them are still in place. A `not_found` row says the
+     * record was not there to delete — already gone, or never existing. It is
+     * reported here rather than in `deletedIds` because this call removed
+     * nothing, and the kit will not claim a deletion the server did not make.
+     * A caller whose grid wants the row cleared checks for that `status`;
+     * `not_permitted` is the one that leaves the record in place.
+     */
     readonly failed: readonly SfaBulkRowResult[];
     /**
      * The rows that may already be removed but cannot be reported either way.
@@ -46,5 +55,9 @@ export interface UseBulkDeleteRecordsResult {
  * place while the rest of the batch applies. There is no rollback, so a
  * partly failed batch has already removed records — which is why per-row
  * outcomes are returned as data rather than thrown.
+ *
+ * Retry only the rows in `failed`, and read each row's `status` first: a
+ * `not_found` row was not there to delete and a `not_permitted` one may not be
+ * deleted, so neither clears on a resend. Rows in `unresolved` are re-read.
  */
 export declare function useBulkDeleteRecords(collection: string): UseBulkDeleteRecordsResult;

package/src/lib/hooks/useBulkDeleteRecords.js

@@ -11,6 +11,10 @@ const sendBulkDelete = (client, collection, rows) => client.bulkDelete(collectio
  * place while the rest of the batch applies. There is no rollback, so a
  * partly failed batch has already removed records — which is why per-row
  * outcomes are returned as data rather than thrown.
+ *
+ * Retry only the rows in `failed`, and read each row's `status` first: a
+ * `not_found` row was not there to delete and a `not_permitted` one may not be
+ * deleted, so neither clears on a resend. Rows in `unresolved` are re-read.
  */
 export function useBulkDeleteRecords(collection) {
     const { run, results, isLoading, error, reset } = useBulkWrite(collection, sendBulkDelete);

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

@@ -21,7 +21,11 @@ export interface UseBulkUpdateRecordsResult {
      * without a `version`, re-read it first — there is nothing to lock against.
      */
     readonly conflicts: readonly SfaBulkRowResult[];
-    /** The rows that did not land and can be sent again, conflicts included. */
+    /**
+     * The rows that did not land and can be sent again, conflicts included.
+     * Read each row's `status`: `not_found` and `not_permitted` are settled
+     * refusals, and a resend alone will not clear them.
+     */
     readonly failed: readonly SfaBulkRowResult[];
     /**
      * The rows that may already be applied but cannot be reported either way.
@@ -49,7 +53,9 @@ export interface UseBulkUpdateRecordsResult {
  * as data rather than thrown errors.
  *
  * Retry only the rows in `failed`. A conflict is retried with the version from
- * its `record`, never by re-sending the stale one. Rows in `unresolved` are
+ * its `record`, never by re-sending the stale one. A `not_found` or
+ * `not_permitted` row is refused again until the record or the permission
+ * changes — report it rather than offering a retry. Rows in `unresolved` are
  * re-read, not retried.
  */
 export declare function useBulkUpdateRecords(collection: string): UseBulkUpdateRecordsResult;

package/src/lib/hooks/useBulkUpdateRecords.js

@@ -13,7 +13,9 @@ const sendBulkUpdate = (client, collection, rows) => client.bulkUpdate(collectio
  * as data rather than thrown errors.
  *
  * Retry only the rows in `failed`. A conflict is retried with the version from
- * its `record`, never by re-sending the stale one. Rows in `unresolved` are
+ * its `record`, never by re-sending the stale one. A `not_found` or
+ * `not_permitted` row is refused again until the record or the permission
+ * changes — report it rather than offering a retry. Rows in `unresolved` are
  * re-read, not retried.
  */
 export function useBulkUpdateRecords(collection) {

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

@@ -35,6 +35,7 @@ export declare class SfaClient implements SfaClientInterface {
     /** In-memory cache for describe results, keyed by objectKey. Stores Promises
      *  so concurrent callers share a single in-flight request. */
     private readonly describeCache;
+    private listObjectsCache;
     constructor(config: SfaClientConfig);
     private resolveBase;
     get(collection: string, recordId: string): Promise<SfaRecord>;

package/src/lib/provider/SfaClient.js

@@ -59,6 +59,7 @@ export class SfaClient {
         /** In-memory cache for describe results, keyed by objectKey. Stores Promises
          *  so concurrent callers share a single in-flight request. */
         this.describeCache = new Map();
+        this.listObjectsCache = null;
         this.apiBase = this.resolveBase(config.apiBase.replace(/\/+$/, ''), config.mode);
         this.auth = config.auth;
         this.mode = config.mode;
@@ -174,11 +175,21 @@ export class SfaClient {
     }
     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 };
+            if (this.listObjectsCache)
+                return this.listObjectsCache;
+            const promise = this.fetchGet(this.objectsPath())
+                .then(raw => {
+                var _a;
+                const data = raw;
+                const objects = ((_a = data.objects) !== null && _a !== void 0 ? _a : []).map(o => normalizeObjectSummary(o));
+                return { objects };
+            })
+                .catch((err) => {
+                this.listObjectsCache = null;
+                throw err;
+            });
+            this.listObjectsCache = promise;
+            return promise;
         });
     }
     listFieldTypes() {
@@ -1040,6 +1051,8 @@ function readBulkRowStatus(raw) {
         conflict: 'conflict',
         invalid: 'invalid',
         not_attempted: 'not_attempted',
+        not_found: 'not_found',
+        not_permitted: 'not_permitted',
         indeterminate: 'indeterminate',
     };
     return typeof raw === 'string' ? (_a = known[raw]) !== null && _a !== void 0 ? _a : 'unknown' : 'unknown';

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

@@ -103,13 +103,19 @@ export interface SfaFieldError {
  * All are reported per row with HTTP 200 — a bulk call is best-effort and has
  * no all-or-nothing mode.
  *
+ * `not_found` and `not_permitted` are refusals of a row the call did reach:
+ * the record it named does not exist, or the caller may not write it. No write
+ * happened either way, so both are settled failures and reach the caller in
+ * `failed`. Sending them again is safe, but returns the same answer until the
+ * record or the permission changes — the decision belongs to the server.
+ *
  * `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';
+export type SfaBulkRowStatus = 'created' | 'updated' | 'deleted' | 'conflict' | 'invalid' | 'not_attempted' | 'not_found' | 'not_permitted' | 'indeterminate' | 'unknown';
 /** @description One row of a bulk update: what to change and from which version. */
 export interface SfaBulkUpdateRow {
     readonly id: string;
@@ -146,12 +152,22 @@ export interface SfaBulkRowResult {
      * against.
      */
     readonly record: SfaRecord | null;
-    /** Set on `conflict` and `invalid`: the problem detail for this row. */
+    /**
+     * The problem detail for this row. Set on the statuses that report one:
+     * `conflict`, `invalid`, `not_found` and `not_permitted`.
+     */
     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`. */
+    /**
+     * Machine-readable problem code, e.g. `version_mismatch`.
+     *
+     * NOTE: empty when the response carried none. Keystone has not minted a code
+     * for `not_permitted` and widened that field of its contract to any string,
+     * so a caller that branches on `code` has to treat `''` as "not stated" and
+     * fall back to `status`, rather than assume every failure names itself.
+     */
     readonly code: string;
     readonly message: string;
     /** Per-field errors when the row failed validation. */

package/src/lib/version.d.ts

@@ -1 +1 @@
-export declare const SFA_KIT_VERSION = "1.14.1";
+export declare const SFA_KIT_VERSION = "1.16.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.14.1';
+export const SFA_KIT_VERSION = '1.16.0';