@geniee-inc/sfa-kit 1.14.0 → 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.0",
+  "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

@@ -1,22 +1,17 @@
 import { __awaiter } from "tslib";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useCallback, useMemo, useState } from 'react';
 import { SfaProvider } from '../provider/SfaProvider';
 import { color, font, radius, space, baseContainerStyle, baseButtonStyle, } from '../theme';
 import { SFA_KIT_VERSION } from '../version';
 import { DevToolbar } from './DevToolbar';
-import { parseInboundMessage, sendToHost } from './embed-protocol';
-import { exchangeCode } from './exchange-code';
 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';
 import { EmbedContextValue } from './useEmbedContext';
-const REFRESH_BUFFER_SECONDS = 120;
-/** After this many consecutive exchange failures, stop retrying and show session_expired. */
-const MAX_CONSECUTIVE_FAILURES = 3;
-/** Seconds to wait for the host to send a code before showing a connection error. */
-const CODE_TIMEOUT_SECONDS = 15;
+import { useEmbedSession } from './useEmbedSession';
 /**
  * @description Returns true when the page is running inside an iframe.
  */
@@ -93,103 +88,35 @@ function resolvePageOrigin() {
 export function SfaLoginGate({ apiBase, trustedOrigin, defaultOrganizationId, objectKey, level, children, }) {
     const shouldEmbed = isEmbedded() && (trustedOrigin != null || hasContentToken());
     const resolvedOrigin = resolveTrustedOrigin(trustedOrigin);
-    if (shouldEmbed && resolvedOrigin != null) {
+    if (shouldEmbed) {
+        // ホストオリジンを 1 つに決められない状態。postMessage の宛先も
+        // event.origin の照合相手も決まらないため、埋め込みの手順自体が成立
+        // しない。ここでログインフォームに落とすと、どの frame の中にいるか
+        // 分からないまま資格情報の入力欄を出すことになるので、描画せずに
+        // 理由だけ表示して止める。
+        //
+        // NOTE: resolveTrustedOrigin は trustedOrigin 未指定時に document.referrer
+        // を使う。referrer は埋め込む側が決める値なので、下の EmbedFlow の
+        // 経路は「埋め込み元の自己申告を信じる」ことになる。ホストを実際に
+        // 限定できるのは trustedOrigin を明示した場合だけ。
+        if (resolvedOrigin == null) {
+            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 }));
 }
-function EmbedFlow({ trustedOrigin, apiBase, children, }) {
-    const [phase, setPhase] = useState({ step: 'waiting_for_code' });
-    const refreshTimerRef = useRef(null);
-    const exchangingRef = useRef(false);
-    const failureCountRef = useRef(0);
+// ---------------------------------------------------------------------------
+// Embed flow (iframe + postMessage)
+// ---------------------------------------------------------------------------
+function EmbedFlow({ objectKey, trustedOrigin, apiBase, children, }) {
     const normalizedBase = useMemo(() => apiBase.replace(/\/+$/, ''), [apiBase]);
-    const clearRefreshTimer = useCallback(() => {
-        if (refreshTimerRef.current != null) {
-            clearTimeout(refreshTimerRef.current);
-            refreshTimerRef.current = null;
-        }
-    }, []);
-    const scheduleRefresh = useCallback((expiresInSeconds) => {
-        clearRefreshTimer();
-        const refreshAfterMs = (expiresInSeconds - REFRESH_BUFFER_SECONDS) * 1000;
-        if (refreshAfterMs <= 0) {
-            sendToHost({ type: 'sfa-kit:code-request' }, trustedOrigin);
-            return;
-        }
-        refreshTimerRef.current = setTimeout(() => {
-            sendToHost({ type: 'sfa-kit:code-request' }, trustedOrigin);
-        }, refreshAfterMs);
-    }, [trustedOrigin, clearRefreshTimer]);
-    const handleCodeReceived = useCallback((code, context) => __awaiter(this, void 0, void 0, function* () {
-        if (exchangingRef.current)
-            return;
-        exchangingRef.current = true;
-        setPhase({ step: 'exchanging' });
-        try {
-            const session = yield exchangeCode(normalizedBase, code);
-            failureCountRef.current = 0;
-            setPhase({ step: 'authenticated', session, context });
-            const expiresInSeconds = Math.max(0, Math.floor((session.expiresAt - Date.now()) / 1000));
-            scheduleRefresh(expiresInSeconds);
-        }
-        catch (thrown) {
-            failureCountRef.current += 1;
-            if (failureCountRef.current >= MAX_CONSECUTIVE_FAILURES) {
-                setPhase({ step: 'session_expired' });
-            }
-            else {
-                const message = thrown instanceof Error ? thrown.message : 'Code exchange failed';
-                setPhase({ step: 'error', message });
-            }
-        }
-        finally {
-            exchangingRef.current = false;
-        }
-    }), [normalizedBase, scheduleRefresh]);
-    const handleAuthError = useCallback(() => {
-        clearRefreshTimer();
-        failureCountRef.current += 1;
-        if (failureCountRef.current >= MAX_CONSECUTIVE_FAILURES) {
-            setPhase({ step: 'session_expired' });
-            return;
-        }
-        sendToHost({ type: 'sfa-kit:code-request' }, trustedOrigin);
-        setPhase({ step: 'waiting_for_code' });
-    }, [trustedOrigin, clearRefreshTimer]);
-    useEffect(() => {
-        const handleMessage = (event) => {
-            var _a;
-            const parsed = parseInboundMessage(event, trustedOrigin);
-            if (!parsed)
-                return;
-            if (parsed.type === 'sfa-kit:code') {
-                void handleCodeReceived(parsed.code, (_a = parsed.context) !== null && _a !== void 0 ? _a : null);
-            }
-        };
-        window.addEventListener('message', handleMessage);
-        sendToHost({ type: 'sfa-kit:ready' }, trustedOrigin);
-        // If the host never sends a code (e.g. mintSfaKitExchangeCode is not
-        // implemented or the host page doesn't support the embed protocol),
-        // show an error instead of hanging on "Connecting..." forever.
-        const codeTimeout = setTimeout(() => {
-            setPhase(current => {
-                if (current.step !== 'waiting_for_code')
-                    return current;
-                return {
-                    step: 'error',
-                    message: 'SFA/CRM との接続がタイムアウトしました。ページを再読み込みしてください。',
-                };
-            });
-        }, CODE_TIMEOUT_SECONDS * 1000);
-        return () => {
-            window.removeEventListener('message', handleMessage);
-            clearTimeout(codeTimeout);
-            clearRefreshTimer();
-        };
-    }, [trustedOrigin, handleCodeReceived, clearRefreshTimer]);
+    const { phase, handleAuthError } = useEmbedSession({
+        apiBase: normalizedBase,
+        trustedOrigin,
+    });
     const auth = useMemo(() => {
         if (phase.step !== 'authenticated')
             return null;
@@ -199,20 +126,23 @@ function EmbedFlow({ trustedOrigin, apiBase, children, }) {
         return (_jsx(EmbedStatus, { title: "\u30BB\u30C3\u30B7\u30E7\u30F3\u671F\u9650\u5207\u308C", message: "SFA/CRM \u306E\u30BB\u30C3\u30B7\u30E7\u30F3\u304C\u7D42\u4E86\u3057\u307E\u3057\u305F\u3002\u30DA\u30FC\u30B8\u3092\u518D\u8AAD\u307F\u8FBC\u307F\u3057\u3066\u304F\u3060\u3055\u3044\u3002", showReload: true }));
     }
     if (phase.step === 'error') {
-        return (_jsx(EmbedStatus, { title: "\u63A5\u7D9A\u30A8\u30E9\u30FC", message: phase.message, showReload: true }));
+        return (_jsx(EmbedStatus, { title: "\u63A5\u7D9A\u30A8\u30E9\u30FC", message: phase.message, showReload: phase.canRecoverByReload }));
+    }
+    if (phase.step === 'reconnecting') {
+        return (_jsx(EmbedStatus, { title: "\u518D\u63A5\u7D9A\u4E2D...", message: "SFA/CRM \u3078\u306E\u63A5\u7D9A\u306B\u5931\u6557\u3057\u307E\u3057\u305F\u3002\u81EA\u52D5\u7684\u306B\u518D\u8A66\u884C\u3057\u3066\u3044\u307E\u3059\u3002" }));
     }
     if (phase.step === 'waiting_for_code' || phase.step === 'exchanging') {
         return (_jsx(EmbedStatus, { title: phase.step === 'exchanging' ? '認証中...' : 'SFA/CRM に接続中...', message: "\u30DB\u30B9\u30C8\u30A2\u30D7\u30EA\u30B1\u30FC\u30B7\u30E7\u30F3\u304B\u3089\u306E\u5FDC\u7B54\u3092\u5F85\u3063\u3066\u3044\u307E\u3059\u3002" }));
     }
     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(() => {
         window.location.reload();
     }, []);
-    return (_jsx("div", { style: styles.backdrop, children: _jsxs("div", { style: Object.assign(Object.assign({}, styles.card), { textAlign: 'center' }), children: [_jsxs("div", { style: loginStyles.logoGroup, children: [_jsx(GenieeLogoMark, {}), _jsxs("div", { style: loginStyles.logoText, children: [_jsx("span", { style: loginStyles.logoGeniee, children: "GENIEE" }), _jsx("span", { style: loginStyles.logoProduct, children: "SFA/CRM" })] })] }), _jsx("h2", { style: styles.title, children: title }), _jsx("p", { style: styles.subtitle, children: message }), showReload && (_jsx("button", { type: "button", style: styles.reloadButton, onClick: handleReload, children: "\u30DA\u30FC\u30B8\u3092\u518D\u8AAD\u307F\u8FBC\u307F" })), _jsxs("div", { style: styles.versionFooter, children: ["@geniee-inc/sfa-kit v", SFA_KIT_VERSION] })] }) }));
+    return (_jsx("div", { style: styles.backdrop, children: _jsxs("div", { role: "status", style: Object.assign(Object.assign({}, styles.card), { textAlign: 'center' }), children: [_jsxs("div", { style: loginStyles.logoGroup, children: [_jsx(GenieeLogoMark, {}), _jsxs("div", { style: loginStyles.logoText, children: [_jsx("span", { style: loginStyles.logoGeniee, children: "GENIEE" }), _jsx("span", { style: loginStyles.logoProduct, children: "SFA/CRM" })] })] }), _jsx("h2", { style: styles.title, children: title }), _jsx("p", { style: styles.subtitle, children: message }), showReload && (_jsx("button", { type: "button", style: styles.reloadButton, onClick: handleReload, children: "\u30DA\u30FC\u30B8\u3092\u518D\u8AAD\u307F\u8FBC\u307F" })), _jsxs("div", { style: styles.versionFooter, children: ["@geniee-inc/sfa-kit v", SFA_KIT_VERSION] })] }) }));
 }
 // ---------------------------------------------------------------------------
 // Standalone flow (login form + DevToolbar)
@@ -312,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/auth/useEmbedSession.d.ts

@@ -0,0 +1,49 @@
+import type { EmbedContext } from './embed-protocol';
+import type { SfaSession } from './types';
+export type EmbedPhase = {
+    step: 'waiting_for_code';
+} | {
+    step: 'exchanging';
+} | {
+    step: 'authenticated';
+    session: SfaSession;
+    context: EmbedContext | null;
+}
+/** 交換に失敗したが、まだ試行回数が残っている状態。自力で復帰しうる。 */
+ | {
+    step: 'reconnecting';
+} | {
+    step: 'session_expired';
+}
+/**
+ * 打ち切って画面を差し替えた状態。canRecoverByReload は再読み込みで
+ * 直りうるかどうか。設定の誤りのように直らない失敗で再読み込みを勧めると、
+ * 利用者は同じ操作を繰り返すことになる。
+ */
+ | {
+    step: 'error';
+    message: string;
+    canRecoverByReload: boolean;
+};
+export interface EmbedSessionState {
+    readonly phase: EmbedPhase;
+    /** Passed to SfaProvider so a 401 triggers the code-request fallback. */
+    readonly handleAuthError: () => void;
+}
+/**
+ * @description Keeps an embedded page authenticated over the postMessage
+ * code-exchange protocol: requests a code on mount, swaps the token before it
+ * expires, and falls back to a fresh code on 401.
+ *
+ * トークンを差し替えている間も phase は `authenticated` のまま据え置く。
+ * 状態画面に切り替えると子ツリーがアンマウントされ、埋め込みページの入力内容と
+ * React の状態が失われるため（authentication.md 条件 1）。
+ *
+ * 再要求は毎回 backoff 付きの見張りを伴う。手元のトークンが有効なうちは
+ * 諦めず、失効して規定回数を試し切った時点でセッション切れとして扱う
+ * （同 条件 3）。打ち切った後は isSettledRef で以降の遷移を止める。
+ */
+export declare function useEmbedSession({ apiBase, trustedOrigin, }: {
+    readonly apiBase: string;
+    readonly trustedOrigin: string;
+}): EmbedSessionState;

package/src/lib/auth/useEmbedSession.js

@@ -0,0 +1,404 @@
+import { __awaiter } from "tslib";
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { parseInboundMessage, sendToHost } from './embed-protocol';
+import { exchangeCode, ExchangeError } from './exchange-code';
+/** How many seconds before expiry a fresh code is requested from the host. */
+const REFRESH_BUFFER_SECONDS = 120;
+/**
+ * Fraction of the remaining lifetime used for the refresh timer when a token
+ * lives for less than REFRESH_BUFFER_SECONDS. A flat floor would only set the
+ * period of a permanent re-exchange loop, not stop it.
+ */
+const SHORT_TOKEN_REFRESH_RATIO = 0.5;
+/** Lower bound for the refresh timer. */
+const MIN_REFRESH_DELAY_SECONDS = 5;
+/** First wait before asking the host for a code again. */
+const CODE_RETRY_BASE_SECONDS = 5;
+/** Upper bound for the backoff between code requests. */
+const CODE_RETRY_MAX_SECONDS = 20;
+/** Seconds to wait for the host's first code before showing a connection error. */
+const CODE_TIMEOUT_SECONDS = 15;
+/** Consecutive failed attempts to obtain a usable session before giving up. */
+const MAX_RECOVERY_ATTEMPTS = 4;
+/**
+ * A 401 landing within this window of the previous one belongs to the same
+ * recovery run. Without it, a token Keystone happily mints but the API keeps
+ * rejecting loops forever, because every exchange succeeds and resets counters.
+ */
+const AUTH_ERROR_WINDOW_SECONDS = 30;
+/** 401-triggered recovery cycles allowed inside AUTH_ERROR_WINDOW_SECONDS. */
+const MAX_AUTH_ERROR_CYCLES = 3;
+/** An exchange still unsettled after this long is treated as abandoned. */
+const STALE_EXCHANGE_SECONDS = 20;
+/**
+ * Statuses below 500 that are still worth retrying. Every attempt asks the host
+ * for a fresh code, so a rejected code (401) can succeed on the next one.
+ * Everything else in the 4xx range (wrong apiBase, malformed request) fails
+ * identically however many times it is tried.
+ */
+const RETRYABLE_CLIENT_STATUSES = new Set([401, 408, 425, 429]);
+/**
+ * @description Whether asking for another code could plausibly succeed.
+ * Non-ExchangeError throws are network faults and aborts, which are transient.
+ */
+function isTransientExchangeFailure(thrown) {
+    if (!(thrown instanceof ExchangeError))
+        return true;
+    // 200 なのに本文が欠けていた場合。ゲートウェイが一度だけ返すことがあるので、
+    // 本文が JSON として壊れていた場合（SyntaxError）と同じ扱いにする。
+    if (thrown.httpStatus === 0)
+        return true;
+    if (thrown.httpStatus >= 500)
+        return true;
+    return RETRYABLE_CLIENT_STATUSES.has(thrown.httpStatus);
+}
+const CONNECT_FAILED_MESSAGE = 'SFA/CRM に接続できませんでした。ページを再読み込みしてください。';
+/**
+ * 何度試しても同じ結果になる失敗。再読み込みでは解消しないため、
+ * CONNECT_FAILED_MESSAGE とは別の案内を出す。
+ */
+const PERMANENT_FAILURE_MESSAGE = 'SFA/CRM に接続できませんでした。埋め込み設定を管理者にご確認ください。';
+/**
+ * @description 交換の失敗理由をコンソールに残す。画面には出さない。
+ * ExchangeError の message は応答本文をそのまま含むため、日本語の案内画面に
+ * 流すと利用者に読めない内容が出るうえ、カードの幅を越えて崩れる。
+ */
+function logExchangeFailure(thrown) {
+    // eslint-disable-next-line no-console
+    console.warn('[sfa-kit] code exchange failed:', thrown);
+}
+/**
+ * @description Keeps an embedded page authenticated over the postMessage
+ * code-exchange protocol: requests a code on mount, swaps the token before it
+ * expires, and falls back to a fresh code on 401.
+ *
+ * トークンを差し替えている間も phase は `authenticated` のまま据え置く。
+ * 状態画面に切り替えると子ツリーがアンマウントされ、埋め込みページの入力内容と
+ * React の状態が失われるため（authentication.md 条件 1）。
+ *
+ * 再要求は毎回 backoff 付きの見張りを伴う。手元のトークンが有効なうちは
+ * 諦めず、失効して規定回数を試し切った時点でセッション切れとして扱う
+ * （同 条件 3）。打ち切った後は isSettledRef で以降の遷移を止める。
+ */
+export function useEmbedSession({ apiBase, trustedOrigin, }) {
+    const [phase, setPhase] = useState({ step: 'waiting_for_code' });
+    const refreshTimerRef = useRef(null);
+    const retryTimerRef = useRef(null);
+    const exchangingRef = useRef(false);
+    const exchangeStartedAtRef = useRef(0);
+    /** 追い越された交換の結果で新しいセッションを上書きしないための世代番号。 */
+    const exchangeGenerationRef = useRef(0);
+    /**
+     * 直近に交換できたセッション。トークンがまだ有効かどうかの判定に使う。
+     * 401 を受け取った時点で null に戻す（期限内でもそのトークンは使えない）。
+     */
+    const sessionRef = useRef(null);
+    /** 使えるセッションを得られなかった連続回数。交換成功で 0 に戻す。 */
+    const recoveryAttemptsRef = useRef(0);
+    const authErrorCyclesRef = useRef(0);
+    /** 連鎖の起点。最後の 1 件ではなく最初の 1 件から窓を測る。 */
+    const authErrorRunStartedAtRef = useRef(0);
+    /**
+     * 401 を受けてコードを要求済みかどうか。SfaClient は 401 を返した
+     * リクエストごとに onAuthError を呼ぶため、並行リクエストの分をまとめる。
+     */
+    const isAuthErrorPendingRef = useRef(false);
+    const hasEverAuthenticatedRef = useRef(false);
+    /** 同じ復帰の試行でコンソールに書いたかどうか。交換成功で false に戻す。 */
+    const hasLoggedExchangeFailureRef = useRef(false);
+    /** 打ち切り済み。以降は再要求も画面遷移もしない。 */
+    const isSettledRef = useRef(false);
+    const clearRefreshTimer = useCallback(() => {
+        if (refreshTimerRef.current != null) {
+            clearTimeout(refreshTimerRef.current);
+            refreshTimerRef.current = null;
+        }
+    }, []);
+    const clearRetryTimer = useCallback(() => {
+        if (retryTimerRef.current != null) {
+            clearTimeout(retryTimerRef.current);
+            retryTimerRef.current = null;
+        }
+    }, []);
+    const isTokenUsable = useCallback(() => {
+        const session = sessionRef.current;
+        return session != null && session.expiresAt > Date.now();
+    }, []);
+    /** 打ち切って画面を差し替える。手元に使えるものが何も残っていないとき。 */
+    const settle = useCallback((next) => {
+        isSettledRef.current = true;
+        // 進行中の交換を無効化する。これが無いと、打ち切った後に解決した交換が
+        // authenticated を書き戻し、二度と操作できない画面が残る。
+        exchangeGenerationRef.current += 1;
+        clearRefreshTimer();
+        clearRetryTimer();
+        setPhase(next);
+    }, [clearRefreshTimer, clearRetryTimer]);
+    /**
+     * 状態画面は子ツリーがまだ描画されていないときだけ出す。認証済みの表示中は
+     * phase を動かさず、ページの状態をそのまま残す。打ち切り後も動かさない。
+     */
+    const showStatusIfNotMounted = useCallback((next) => {
+        if (isSettledRef.current)
+            return;
+        setPhase(current => (current.step === 'authenticated' ? current : next));
+    }, []);
+    /**
+     * 交換中であることを示す。すでに再接続中の表示なら据え置く。再試行のたびに
+     * 「認証中...」と「再接続中...」が入れ替わると、見出しが点滅して見えるため。
+     */
+    const showExchangingIfNotMounted = useCallback(() => {
+        if (isSettledRef.current)
+            return;
+        setPhase(current => current.step === 'authenticated' || current.step === 'reconnecting'
+            ? current
+            : { step: 'exchanging' });
+    }, []);
+    const sendCodeRequest = useCallback(() => {
+        sendToHost({ type: 'sfa-kit:code-request' }, trustedOrigin);
+    }, [trustedOrigin]);
+    /** 打ち切り後にトークンが切れた時点で next に落とすためのタイマー。 */
+    const scheduleExpiryCutoff = useCallback((next) => {
+        clearRefreshTimer();
+        const session = sessionRef.current;
+        if (session == null)
+            return;
+        refreshTimerRef.current = setTimeout(() => {
+            refreshTimerRef.current = null;
+            setPhase(next);
+        }, Math.max(0, session.expiresAt - Date.now()));
+    }, [clearRefreshTimer]);
+    /**
+     * 打ち切る。手元のトークンがまだ使えるなら描画済みの子ツリーを残し、
+     * 失効した時点で next に切り替える。使えるものが無ければその場で next を出す。
+     *
+     * next は打ち切った理由をそのまま表す。設定の誤りで再交換が詰んだ場合に
+     * 失効を待って「セッション期限切れ」を出すと、原因の見当がつかなくなる。
+     *
+     * トークンの有無の判定はここに閉じる。呼び出し側で分岐させると、据え置きの
+     * 経路だけを通って失効タイマーの無いまま固まる呼び方ができてしまう。
+     */
+    const stopRetrying = useCallback((next) => {
+        if (!isTokenUsable()) {
+            settle(next);
+            return;
+        }
+        isSettledRef.current = true;
+        exchangeGenerationRef.current += 1;
+        clearRetryTimer();
+        setPhase(current => (current.step === 'authenticated' ? current : next));
+        scheduleExpiryCutoff(next);
+    }, [clearRetryTimer, isTokenUsable, scheduleExpiryCutoff, settle]);
+    // 見張りは自分自身を再武装する。useCallback は自己参照できないため ref 経由。
+    const armCodeRetryRef = useRef(() => undefined);
+    /**
+     * コード要求に応答が無かった場合に備えて次の要求を仕込む。間隔は指数的に
+     * 広げ、揺らぎを加える。複数のタブが同じ間隔で一斉に再要求すると、弱った
+     * ホストと Keystone をそろって叩くことになるため。
+     */
+    const armCodeRetry = useCallback(() => {
+        if (isSettledRef.current)
+            return;
+        clearRetryTimer();
+        const backoffSeconds = Math.min(CODE_RETRY_BASE_SECONDS * Math.pow(2, recoveryAttemptsRef.current), CODE_RETRY_MAX_SECONDS);
+        const delayMs = backoffSeconds * 1000 * (0.75 + Math.random() * 0.5);
+        retryTimerRef.current = setTimeout(() => {
+            retryTimerRef.current = null;
+            if (isSettledRef.current)
+                return;
+            recoveryAttemptsRef.current += 1;
+            // トークンが生きているうちは諦めない。間隔だけ広げる。
+            if (!isTokenUsable() &&
+                recoveryAttemptsRef.current >= MAX_RECOVERY_ATTEMPTS) {
+                settle(hasEverAuthenticatedRef.current
+                    ? { step: 'session_expired' }
+                    : {
+                        step: 'error',
+                        message: CONNECT_FAILED_MESSAGE,
+                        canRecoverByReload: true,
+                    });
+                return;
+            }
+            sendCodeRequest();
+            armCodeRetryRef.current();
+        }, delayMs);
+    }, [clearRetryTimer, isTokenUsable, sendCodeRequest, settle]);
+    armCodeRetryRef.current = armCodeRetry;
+    /** コードを要求し、応答が無かったときのために次の要求を仕込む。 */
+    const requestCode = useCallback(() => {
+        sendCodeRequest();
+        armCodeRetry();
+    }, [sendCodeRequest, armCodeRetry]);
+    const scheduleRefresh = useCallback((expiresInSeconds) => {
+        clearRefreshTimer();
+        const lifetime = Number.isFinite(expiresInSeconds)
+            ? Math.max(0, expiresInSeconds)
+            : 0;
+        // 3 つの下限の最大値をとる。分岐で選ぶと 125 秒付近で不連続になり、
+        // 1 秒長いトークンの交換頻度が 10 倍になっていた。
+        const delaySeconds = Math.max(MIN_REFRESH_DELAY_SECONDS, lifetime - REFRESH_BUFFER_SECONDS, lifetime * SHORT_TOKEN_REFRESH_RATIO);
+        refreshTimerRef.current = setTimeout(() => {
+            refreshTimerRef.current = null;
+            requestCode();
+        }, delaySeconds * 1000);
+    }, [clearRefreshTimer, requestCode]);
+    const handleCodeReceived = useCallback((code, context) => __awaiter(this, void 0, void 0, function* () {
+        if (isSettledRef.current)
+            return;
+        const startedAt = Date.now();
+        // 決着しない交換に居座られてコードを取りこぼし続けないよう、古い交換は
+        // 見捨てる（authTimeoutSignal は AbortSignal.timeout が無い環境で
+        // undefined を返すため、fetch 側で必ず中断されるとは限らない）。
+        if (exchangingRef.current &&
+            startedAt - exchangeStartedAtRef.current < STALE_EXCHANGE_SECONDS * 1000) {
+            return;
+        }
+        exchangingRef.current = true;
+        exchangeStartedAtRef.current = startedAt;
+        const generation = (exchangeGenerationRef.current += 1);
+        // 交換中も見張りを残す。ここでタイマーを消すと、決着しない交換に
+        // 入った時点で armed なタイマーが 1 つも無くなり、復帰できなくなる。
+        armCodeRetry();
+        showExchangingIfNotMounted();
+        try {
+            const session = yield exchangeCode(apiBase, code);
+            if (exchangeGenerationRef.current !== generation)
+                return;
+            recoveryAttemptsRef.current = 0;
+            isAuthErrorPendingRef.current = false;
+            hasLoggedExchangeFailureRef.current = false;
+            hasEverAuthenticatedRef.current = true;
+            sessionRef.current = session;
+            // 交換中に 401 で仕込まれた見張りが生き残ると、成功後も 5 秒ごとに
+            // コードを要求し続けることになる。
+            clearRetryTimer();
+            setPhase(current => ({
+                step: 'authenticated',
+                session,
+                // context を省いた再交換で object_key / record_id を失わない。
+                context: context !== null && context !== void 0 ? context : (current.step === 'authenticated' ? current.context : null),
+            }));
+            scheduleRefresh(Math.max(0, Math.floor((session.expiresAt - Date.now()) / 1000)));
+        }
+        catch (thrown) {
+            if (exchangeGenerationRef.current !== generation)
+                return;
+            // 同じ復帰の試行が続く間は 1 回だけ出す。トークンが生きている間は
+            // 20 秒ごとに再交換を続けるため、毎回書くとホストのコンソールが埋まる。
+            if (!hasLoggedExchangeFailureRef.current) {
+                hasLoggedExchangeFailureRef.current = true;
+                logExchangeFailure(thrown);
+            }
+            // 何度やっても通らない失敗。使い捨てコードを浪費しない。
+            if (!isTransientExchangeFailure(thrown)) {
+                stopRetrying({
+                    step: 'error',
+                    message: PERMANENT_FAILURE_MESSAGE,
+                    canRecoverByReload: false,
+                });
+                return;
+            }
+            // 試行回数は見張りのタイマー側だけで数える。ここでも足すと 1 周で
+            // 2 つ進み、実際にホストへ届く要求が半分になる。
+            if (isTokenUsable()) {
+                armCodeRetry();
+                return;
+            }
+            // ここはまだ打ち切っていない。error を出すと再読み込みボタン付きの
+            // 終了画面になるが、実際には最大 55 秒ほど再試行が続き、そのまま
+            // ログインできることがある。
+            showStatusIfNotMounted({ step: 'reconnecting' });
+            armCodeRetry();
+        }
+        finally {
+            if (exchangeGenerationRef.current === generation) {
+                exchangingRef.current = false;
+            }
+        }
+    }), [
+        apiBase,
+        scheduleRefresh,
+        armCodeRetry,
+        clearRetryTimer,
+        isTokenUsable,
+        stopRetrying,
+        showStatusIfNotMounted,
+        showExchangingIfNotMounted,
+    ]);
+    const handleAuthError = useCallback(() => {
+        if (isSettledRef.current)
+            return;
+        if (isAuthErrorPendingRef.current)
+            return;
+        isAuthErrorPendingRef.current = true;
+        const now = Date.now();
+        // 窓は連鎖の起点から測る。直近の 1 件から測ると、正常に復帰している
+        // 25 秒間隔の 401 でも窓が滑り続けて打ち切りに達してしまう。
+        if (now - authErrorRunStartedAtRef.current >
+            AUTH_ERROR_WINDOW_SECONDS * 1000) {
+            authErrorCyclesRef.current = 0;
+            authErrorRunStartedAtRef.current = now;
+        }
+        authErrorCyclesRef.current += 1;
+        // ここに達した時点で交換自体は通り続けている。その 401 は差し替え前の
+        // トークンで投げられたリクエストの遅れ着信であることが多く、手元では
+        // 見分けられない（onAuthError は拒否されたトークンを渡さない）。
+        // 動いているセッションを巻き添えにしない側を採る。
+        if (authErrorCyclesRef.current > MAX_AUTH_ERROR_CYCLES) {
+            // 手元のトークンが期限内なら表示は保ち、コードの取り直しだけをやめて、
+            // 失効した時点でセッション切れとして扱う。
+            //
+            // 据え置きにする必要がある。ホストは要求を受けてから非同期にコードを
+            // 発行するので、打ち切った後に以前の要求への応答が届く。交換を続けて
+            // しまうと更新タイマーが張り直され、打ち切りが無かったことになる。
+            // stopRetrying が世代を進めて以降のコードを無視させる。
+            stopRetrying({ step: 'session_expired' });
+            return;
+        }
+        clearRefreshTimer();
+        // 401 を返されたトークンは期限内でも使えない。保持判定から外す。
+        //
+        // NOTE: phase.session のトークンは差し替えるまで残る。SfaProvider に渡す
+        // auth は phase.session から作るため、ここで消すと auth が null になり
+        // 子ツリーが落ちる（それを避けるのがこの修正の目的）。復帰までの数秒は
+        // 無効なトークンでリクエストが失敗するが、トークンを外しても同じく
+        // 失敗するため、表示を保つ側を採る。
+        sessionRef.current = null;
+        requestCode();
+        showStatusIfNotMounted({ step: 'waiting_for_code' });
+    }, [requestCode, clearRefreshTimer, stopRetrying, showStatusIfNotMounted]);
+    useEffect(() => {
+        const handleMessage = (event) => {
+            var _a;
+            const parsed = parseInboundMessage(event, trustedOrigin);
+            if (!parsed)
+                return;
+            if (parsed.type === 'sfa-kit:code') {
+                void handleCodeReceived(parsed.code, (_a = parsed.context) !== null && _a !== void 0 ? _a : null);
+            }
+        };
+        window.addEventListener('message', handleMessage);
+        sendToHost({ type: 'sfa-kit:ready' }, trustedOrigin);
+        // If the host never sends a code (e.g. mintSfaKitExchangeCode is not
+        // implemented or the host page doesn't support the embed protocol),
+        // show an error instead of hanging on "Connecting..." forever.
+        const codeTimeout = setTimeout(() => {
+            setPhase(current => {
+                if (current.step !== 'waiting_for_code')
+                    return current;
+                return {
+                    step: 'error',
+                    message: 'SFA/CRM との接続がタイムアウトしました。ページを再読み込みしてください。',
+                    canRecoverByReload: true,
+                };
+            });
+        }, CODE_TIMEOUT_SECONDS * 1000);
+        return () => {
+            window.removeEventListener('message', handleMessage);
+            clearTimeout(codeTimeout);
+            clearRefreshTimer();
+            clearRetryTimer();
+        };
+    }, [trustedOrigin, handleCodeReceived, clearRefreshTimer, clearRetryTimer]);
+    return { phase, handleAuthError };
+}

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.0";
+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.0';
+export const SFA_KIT_VERSION = '1.16.0';