@geniee-inc/sfa-kit 1.17.0 → 1.19.0

package/src/lib/bundle/request-signature.js

@@ -6,6 +6,15 @@ import { __awaiter } from "tslib";
 const HEX_DIGEST_PATTERN = /^[0-9a-f]{64}$/;
 /** Matches the timeout the documented Python flow uses for the same call. */
 const SIGN_TIMEOUT_MS = 30000;
+/**
+ * Whether `value` has the shape Keystone gives `content_hash` and `signature`.
+ *
+ * NOTE: shared with the builder's previous-build check, so the shape the
+ * signer accepts and the shape a rebuild recognises cannot drift apart.
+ */
+export function isHexDigest(value) {
+    return typeof value === 'string' && HEX_DIGEST_PATTERN.test(value);
+}
 /**
  * @description Asks Keystone to sign a bundle, returning the signature.
  *
@@ -14,6 +23,11 @@ const SIGN_TIMEOUT_MS = 30000;
  * per project while the key must be identical across all of them (SFAJAI-186).
  * The caller computes `contentHash` locally and Keystone signs it.
  *
+ * Without `studioVersion`, Keystone signs `contentHash` alone. With it, Keystone
+ * returns the legacy signature over `"{studio_version}:{content_hash}"`, and the
+ * caller must write the same `studio_version` into the manifest for it to
+ * verify.
+ *
  * NOTE: every failure throws. An unsigned bundle uploads successfully while
  * Keystone's verifier runs in `disabled` mode, so returning "no signature" here
  * would produce an artifact that looks fine and starts being rejected the day
@@ -24,7 +38,7 @@ const SIGN_TIMEOUT_MS = 30000;
  */
 export function requestSignature(_a) {
     return __awaiter(this, arguments, void 0, function* ({ apiBase, accessToken, studioVersion, contentHash, }) {
-        if (!HEX_DIGEST_PATTERN.test(contentHash)) {
+        if (!isHexDigest(contentHash)) {
             throw new Error(`content_hash must be a 64-character hex digest, got ${JSON.stringify(contentHash)}`);
         }
         // 末尾のスラッシュを落とす。付いたままだと //v1/pages/sign になり、多くの
@@ -44,10 +58,11 @@ export function requestSignature(_a) {
                 'Content-Type': 'application/json',
                 Authorization: `Bearer ${accessToken}`,
             },
-            body: JSON.stringify({
-                studio_version: studioVersion,
-                content_hash: contentHash,
-            }),
+            // NOTE: the field is left out, not sent empty. Keystone picks the format
+            // by whether studio_version is present, as it does for the manifest.
+            body: JSON.stringify(studioVersion == null
+                ? { content_hash: contentHash }
+                : { studio_version: studioVersion, content_hash: contentHash }),
         })
             .catch((thrown) => {
             throw new Error(`POST ${url} could not be reached ` +
@@ -72,7 +87,7 @@ export function requestSignature(_a) {
         // error page echoed into this field would otherwise be written into
         // manifest.json, upload fine while the verifier is `disabled`, and fail only
         // once it is switched to `enforced`.
-        if (!HEX_DIGEST_PATTERN.test(payload.signature)) {
+        if (!isHexDigest(payload.signature)) {
             throw new Error(`POST ${url} returned ${JSON.stringify(payload.signature)}, which is ` +
                 'not an HMAC-SHA-256 hex digest. The bundle was not signed.');
         }

package/src/lib/components/FieldRenderer.d.ts

@@ -5,7 +5,8 @@ interface FieldRendererProps {
 }
 /**
  * @description Renders a single field value based on its normalized kind.
- * Uses `label` for display (pre-formatted by the API), falls back to `value`.
+ * Uses `label` for display (pre-formatted by the API), falls back to a plain
+ * readable `value` — never a code or an id.
  */
 export declare function FieldRenderer({ fieldValue, fieldName }: FieldRendererProps): JSX.Element;
 export {};

package/src/lib/components/FieldRenderer.js

@@ -1,36 +1,28 @@
 import { jsx as _jsx } from "react/jsx-runtime";
+import { toFieldDisplayText } from './fieldDisplayText';
 /**
  * @description Renders a single field value based on its normalized kind.
- * Uses `label` for display (pre-formatted by the API), falls back to `value`.
+ * Uses `label` for display (pre-formatted by the API), falls back to a plain
+ * readable `value` — never a code or an id.
  */
 export function FieldRenderer({ fieldValue, fieldName }) {
-    var _a;
-    const display = (_a = fieldValue.label) !== null && _a !== void 0 ? _a : formatFallback(fieldValue);
+    const display = toFieldDisplayText(fieldValue);
+    // NOTE: every branch carries `data-field`, so a page can find a field by name
+    // whatever its value looks like — empty, multi-line or a link
     if (display == null || display === '') {
-        return _jsx("span", { style: styles.empty, children: "\u2014" });
+        return (_jsx("span", { "data-field": fieldName, style: styles.empty, children: "\u2014" }));
     }
     if (fieldValue.kind === 'text' && typeof fieldValue.value === 'string') {
         if (isMultiline(fieldValue.value)) {
-            return _jsx("span", { style: styles.preWrap, children: display });
+            return (_jsx("span", { "data-field": fieldName, style: styles.preWrap, children: display }));
         }
         const link = detectLink(fieldValue.value);
         if (link) {
-            return (_jsx("a", { href: link.href, style: styles.link, target: "_blank", rel: "noopener noreferrer", children: display }));
+            return (_jsx("a", { "data-field": fieldName, href: link.href, style: styles.link, target: "_blank", rel: "noopener noreferrer", children: display }));
         }
     }
     return _jsx("span", { "data-field": fieldName, children: display });
 }
-function formatFallback(field) {
-    if (field.value == null)
-        return null;
-    if (typeof field.value === 'number')
-        return field.value.toLocaleString('ja-JP');
-    if (typeof field.value === 'string')
-        return field.value;
-    if (Array.isArray(field.value))
-        return field.value.join(', ');
-    return String(field.value);
-}
 function isMultiline(value) {
     return value.includes('\n');
 }
@@ -39,10 +31,31 @@ function detectLink(value) {
         return { href: value };
     if (/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value))
         return { href: `mailto:${value}` };
-    if (/^[\d+][\d\-().+\s]{7,}$/.test(value))
-        return { href: `tel:${value.replace(/[\s()-]/g, '')}` };
+    const phoneNumber = toPhoneNumber(value);
+    if (phoneNumber)
+        return { href: `tel:${phoneNumber}` };
     return null;
 }
+/**
+ * The number to dial when `value` reads as a phone number, or null.
+ *
+ * NOTE: digits and dashes alone also make up postal codes (100-0001) and dates
+ * (2026-09-28). A Japanese number starts with a single 0 and has 10 or 11
+ * digits; an international one starts with + and has 8 to 15 (E.164 caps it at
+ * 15). A leading 00 is a zero-padded code, not a number to dial
+ */
+function toPhoneNumber(value) {
+    if (!/^(?:\+|\(?0)[\d\s().-]+$/.test(value))
+        return null;
+    const digits = value.replace(/\D/g, '');
+    if (value.startsWith('+')) {
+        return digits.length >= 8 && digits.length <= 15 ? `+${digits}` : null;
+    }
+    // NOTE: checked on the digits, so separators cannot hide the second 0
+    if (digits.startsWith('00'))
+        return null;
+    return digits.length === 10 || digits.length === 11 ? digits : null;
+}
 const styles = {
     empty: {
         color: '#94a3b8',

package/src/lib/components/RecordList.js

@@ -3,6 +3,7 @@ import { useEffect, useMemo, useRef } from 'react';
 import { useRecordList } from '../hooks/useRecordList';
 import { color, font, radius, space, baseContainerStyle, baseButtonStyle, } from '../theme';
 import { SFA_KIT_VERSION } from '../version';
+import { EmptyState } from './EmptyState';
 import { FetchErrorState } from './FetchErrorState';
 import { FieldRenderer } from './FieldRenderer';
 const MAX_AUTO_COLUMNS = 8;
@@ -26,6 +27,15 @@ export function RecordList({ collection, columns, params, pageSize = 20, showPag
     if (status === 'error') {
         return (_jsxs("div", { style: styles.container, children: [_jsx(FetchErrorState, { message: errorMessage, onRetry: refetch }), _jsxs("div", { style: styles.versionFooter, children: ["@geniee-inc/sfa-kit v", SFA_KIT_VERSION] })] }));
     }
+    // NOTE: on 'idle' nothing was asked — this component never disables the hook,
+    // so it only happens while `collection` is empty. "0 records" and "No records
+    // found" would state something the server never answered, and an empty table
+    // would look broken. Say what is missing instead — the input, not the data —
+    // as RecordView does for a missing record. From here on the status is
+    // 'loading' or 'success', so `!isLoading` means the items came from the server
+    if (status === 'idle') {
+        return (_jsxs("div", { style: styles.container, children: [_jsx(EmptyState, { message: "\u30AA\u30D6\u30B8\u30A7\u30AF\u30C8\u304C\u6307\u5B9A\u3055\u308C\u3066\u3044\u307E\u305B\u3093" }), _jsxs("div", { style: styles.versionFooter, children: ["@geniee-inc/sfa-kit v", SFA_KIT_VERSION] })] }));
+    }
     const resolvedColumns = columns !== null && columns !== void 0 ? columns : autoDetectColumns(items);
     const totalPages = Math.max(1, Math.ceil(totalCount / pageSize));
     const rangeStart = pageIndex * pageSize + 1;

package/src/lib/components/RecordView.js

@@ -3,7 +3,9 @@ import { useEffect, useRef } from 'react';
 import { useRecord } from '../hooks/useRecord';
 import { color, font, radius, space, baseContainerStyle } from '../theme';
 import { SFA_KIT_VERSION } from '../version';
+import { EmptyState } from './EmptyState';
 import { FetchErrorState } from './FetchErrorState';
+import { toFieldDisplayText } from './fieldDisplayText';
 import { FieldRenderer } from './FieldRenderer';
 /**
  * @description Fetches and displays a single SFA/CRM record in a label-value grid.
@@ -11,26 +13,41 @@ import { FieldRenderer } from './FieldRenderer';
 export function RecordView({ collection, recordId, title, fields, fieldGroups, onError, errorMessage, }) {
     var _a;
     const { record, isLoading, error, refetch } = useRecord(collection, recordId);
+    // NOTE: useRecord reports an empty record id as an error so a page using the
+    // hook alone can say so, but to this component it is "no record specified",
+    // not a failed fetch: nothing was sent, and a retry would only repeat it.
+    // The screen and onError both read this, so a page never toasts a failure
+    // next to the "not specified" state
+    const fetchError = recordId === '' ? null : error;
     // Use a ref so inline onError callbacks don't re-fire the effect on
     // every parent render when error is present.
     const onErrorRef = useRef(onError);
     onErrorRef.current = onError;
     useEffect(() => {
         var _a;
-        if (error)
-            (_a = onErrorRef.current) === null || _a === void 0 ? void 0 : _a.call(onErrorRef, error);
-    }, [error]);
-    if (error) {
+        if (fetchError)
+            (_a = onErrorRef.current) === null || _a === void 0 ? void 0 : _a.call(onErrorRef, fetchError);
+    }, [fetchError]);
+    if (fetchError) {
         // NOTE: `title` is the label the page already shows as the heading, so it
         // names the record without exposing `collection` — the object key the API
         // is addressed with. The derived heading is unavailable here: it reads the
         // record, and on a failure there is none.
         return (_jsxs("div", { style: styles.container, children: [_jsx(FetchErrorState, { message: errorMessage !== null && errorMessage !== void 0 ? errorMessage : (title ? `${title}の取得に失敗` : undefined), onRetry: refetch }), _jsxs("div", { style: styles.versionFooter, children: ["@geniee-inc/sfa-kit v", SFA_KIT_VERSION] })] }));
     }
-    if (isLoading || !record) {
+    if (isLoading) {
         return (_jsxs("div", { style: styles.container, children: [_jsx("div", { style: styles.loading, children: "Loading..." }), _jsxs("div", { style: styles.versionFooter, children: ["@geniee-inc/sfa-kit v", SFA_KIT_VERSION] })] }));
     }
-    const displayTitle = (_a = title !== null && title !== void 0 ? title : record.title) !== null && _a !== void 0 ? _a : buildTitle(record.fields, record.titleFields);
+    // NOTE: nothing is loading and no fetch failed, yet there is no record. A
+    // fetch that finds none throws, so this means no record was specified — no
+    // collection or no record id yet. "Loading..." would never go away
+    if (!record) {
+        return (_jsxs("div", { style: styles.container, children: [_jsx(EmptyState, { message: "\u30EC\u30B3\u30FC\u30C9\u304C\u6307\u5B9A\u3055\u308C\u3066\u3044\u307E\u305B\u3093" }), _jsxs("div", { style: styles.versionFooter, children: ["@geniee-inc/sfa-kit v", SFA_KIT_VERSION] })] }));
+    }
+    // NOTE: an empty title from the API names nothing, so build one from
+    // `titleFields` as if it were missing
+    const recordTitle = record.title === '' ? null : record.title;
+    const displayTitle = (_a = title !== null && title !== void 0 ? title : recordTitle) !== null && _a !== void 0 ? _a : buildTitle(record.fields, record.titleFields);
     const hasGroups = fieldGroups && fieldGroups.length > 0;
     return (_jsxs("div", { style: styles.container, children: [displayTitle && _jsx("h2", { style: styles.title, children: displayTitle }), _jsxs("div", { style: styles.meta, children: [collection, " / ", record.record_id] }), hasGroups
                 ? renderFieldGroups(record.fields, fieldGroups)
@@ -65,7 +82,10 @@ function renderFieldGroups(mapping, groups) {
 }
 function buildTitle(mapping, titleFields) {
     return titleFields
-        .map(name => { var _a; return (_a = mapping[name]) === null || _a === void 0 ? void 0 : _a.label; })
+        .map(name => {
+        const field = mapping[name];
+        return field ? toFieldDisplayText(field) : null;
+    })
         .filter(Boolean)
         .join(' ');
 }

package/src/lib/components/fieldDisplayText.d.ts

@@ -0,0 +1,11 @@
+import type { SfaFieldValue } from '../provider/types';
+/**
+ * @description The text a field shows to a reader — its label, or a plain
+ * readable value when the label is empty or missing — or null.
+ *
+ * NOTE: never a code or an id. FieldRenderer and the heading RecordView builds
+ * from `titleFields` both use this, so a field shows the same thing in its row
+ * and in the heading, and a reference whose label is missing puts its raw id
+ * in neither
+ */
+export declare function toFieldDisplayText(field: SfaFieldValue): string | null;

package/src/lib/components/fieldDisplayText.js

@@ -0,0 +1,51 @@
+/**
+ * Kinds whose `value` reads as it is. The others hold a code or an id, and
+ * only `label` names it
+ */
+const READABLE_VALUE_KINDS = new Set([
+    'text',
+    'number',
+    'date',
+    'datetime',
+    'computed',
+]);
+/**
+ * Whether `value` can be shown to a reader as it is: a number, a boolean, or a
+ * string that is not markup
+ *
+ * NOTE: Chikyu also sends kinds it has no mapping for as 'text' — an image
+ * field holds HTML, others may hold an object — so the kind alone does not
+ * promise readable text
+ */
+function isPlainValue(value) {
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return true;
+    return typeof value === 'string' && !/<[a-z!/][^>]*>/i.test(value);
+}
+/**
+ * @description The text a field shows to a reader — its label, or a plain
+ * readable value when the label is empty or missing — or null.
+ *
+ * NOTE: never a code or an id. FieldRenderer and the heading RecordView builds
+ * from `titleFields` both use this, so a field shows the same thing in its row
+ * and in the heading, and a reference whose label is missing puts its raw id
+ * in neither
+ */
+export function toFieldDisplayText(field) {
+    if (field.label != null && field.label !== '')
+        return field.label;
+    // NOTE: an empty or missing label carries no formatting, so a plain readable
+    // value shows instead. Anything else stays empty: a choice or a reference
+    // holds a code or an id (Chikyu leaves the caption out of fields it does not
+    // display, and a master-backed select holds an id), and markup or an object
+    // means nothing to a reader
+    return READABLE_VALUE_KINDS.has(field.kind) && isPlainValue(field.value)
+        ? formatPlainValue(field.value)
+        : null;
+}
+/** A plain value as text: a number formatted for ja-JP, the rest as it is */
+function formatPlainValue(value) {
+    return typeof value === 'number'
+        ? value.toLocaleString('ja-JP')
+        : String(value);
+}

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

@@ -10,6 +10,11 @@ interface UseFieldTypesResult {
 }
 /**
  * @description Fetches the static field-type catalog from Keystone.
+ *
+ * NOTE: a failed refetch keeps the field types already shown and sets `error`
+ * beside them. The catalog almost never changes, so a transient failure must
+ * not empty the pickers built from it. useRecord drops its record instead: a
+ * record does change, and a stale one would pass for the current one.
  */
 export declare function useFieldTypes(options?: UseFieldTypesOptions): UseFieldTypesResult;
 export {};

package/src/lib/hooks/useFieldTypes.js

@@ -2,6 +2,11 @@ import { useCallback, useEffect, useRef, useState } from 'react';
 import { useSfaClient } from '../provider/useSfaClient';
 /**
  * @description Fetches the static field-type catalog from Keystone.
+ *
+ * NOTE: a failed refetch keeps the field types already shown and sets `error`
+ * beside them. The catalog almost never changes, so a transient failure must
+ * not empty the pickers built from it. useRecord drops its record instead: a
+ * record does change, and a stale one would pass for the current one.
  */
 export function useFieldTypes(options) {
     var _a;

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

@@ -10,6 +10,12 @@ interface UseObjectCatalogResult {
 }
 /**
  * @description Fetches the list of all objects available in the org.
+ *
+ * NOTE: a failed refetch keeps the objects already shown and sets `error`
+ * beside them. The catalog almost never changes, so a transient failure must
+ * not empty the object picker built from it. useRecord drops its record
+ * instead: a record does change, and a stale one would pass for the current
+ * one.
  */
 export declare function useObjectCatalog(options?: UseObjectCatalogOptions): UseObjectCatalogResult;
 export {};

package/src/lib/hooks/useObjectCatalog.js

@@ -2,6 +2,12 @@ import { useCallback, useEffect, useRef, useState } from 'react';
 import { useSfaClient } from '../provider/useSfaClient';
 /**
  * @description Fetches the list of all objects available in the org.
+ *
+ * NOTE: a failed refetch keeps the objects already shown and sets `error`
+ * beside them. The catalog almost never changes, so a transient failure must
+ * not empty the object picker built from it. useRecord drops its record
+ * instead: a record does change, and a stale one would pass for the current
+ * one.
  */
 export function useObjectCatalog(options) {
     var _a;

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

@@ -10,6 +10,26 @@ interface UseRecordResult {
 }
 /**
  * @description Fetches a single record from the SFA/CRM API.
+ *
+ * NOTE: a failed refetch drops the record already shown. A record changes, so
+ * an earlier copy next to the error would pass for the current one and could
+ * be edited from. The catalog hooks keep their data on a failure instead,
+ * because what they hold almost never changes.
+ *
+ * NOTE: an empty `collection` means there is nothing to ask yet — the embed
+ * context has not arrived, say — and is treated like `enabled: false`: no
+ * request and no error. An error would flash on every page that is still
+ * waiting, and useRecordList and useDescribe stay idle the same way. An empty
+ * `recordId` with a collection given is different, and does set `error`: the
+ * object is known but no record is picked, which the message asks the reader to
+ * fix, and an empty id that reached the API was answered with a 503.
+ *
+ * NOTE: the result always describes the `collection` / `recordId` / client
+ * passed right now. When they change, the state still answers the old ones
+ * until the fetch for the new ones starts, so it reports no record and no
+ * error — with `isLoading` when a fetch is due — instead of the old answer,
+ * the way useRecordList reports 'loading' before its fetch settles. Disabling
+ * without changing them keeps the record already fetched.
  */
 export declare function useRecord(collection: string, recordId: string, options?: UseRecordOptions): UseRecordResult;
 export {};

package/src/lib/hooks/useRecord.js

@@ -4,6 +4,26 @@ import { ERR_EMPTY_RECORD_ID } from '../errors';
 import { useSfaClient } from '../provider/useSfaClient';
 /**
  * @description Fetches a single record from the SFA/CRM API.
+ *
+ * NOTE: a failed refetch drops the record already shown. A record changes, so
+ * an earlier copy next to the error would pass for the current one and could
+ * be edited from. The catalog hooks keep their data on a failure instead,
+ * because what they hold almost never changes.
+ *
+ * NOTE: an empty `collection` means there is nothing to ask yet — the embed
+ * context has not arrived, say — and is treated like `enabled: false`: no
+ * request and no error. An error would flash on every page that is still
+ * waiting, and useRecordList and useDescribe stay idle the same way. An empty
+ * `recordId` with a collection given is different, and does set `error`: the
+ * object is known but no record is picked, which the message asks the reader to
+ * fix, and an empty id that reached the API was answered with a 503.
+ *
+ * NOTE: the result always describes the `collection` / `recordId` / client
+ * passed right now. When they change, the state still answers the old ones
+ * until the fetch for the new ones starts, so it reports no record and no
+ * error — with `isLoading` when a fetch is due — instead of the old answer,
+ * the way useRecordList reports 'loading' before its fetch settles. Disabling
+ * without changing them keeps the record already fetched.
  */
 export function useRecord(collection, recordId, options) {
     var _a;
@@ -13,9 +33,19 @@ export function useRecord(collection, recordId, options) {
     const [isLoading, setIsLoading] = useState(enabled && !!collection && !!recordId);
     const [error, setError] = useState(null);
     const fetchId = useRef(0);
+    // NOTE: which inputs the state above answers. Set whenever doFetch starts
+    // answering a new question, so a render can tell the state is about inputs
+    // that are no longer passed
+    const answeredRef = useRef(null);
     const doFetch = useCallback(() => __awaiter(this, void 0, void 0, function* () {
         if (!enabled || !collection)
             return;
+        const answered = answeredRef.current;
+        const isNewQuestion = answered == null ||
+            answered.client !== client ||
+            answered.collection !== collection ||
+            answered.recordId !== recordId;
+        answeredRef.current = { client, collection, recordId };
         if (!recordId) {
             fetchId.current += 1;
             setRecord(null);
@@ -25,6 +55,10 @@ export function useRecord(collection, recordId, options) {
         }
         fetchId.current += 1;
         const currentFetchId = fetchId.current;
+        // NOTE: a refetch of the same record keeps it on screen while it loads; a
+        // record answering other inputs must not stand in for the new one
+        if (isNewQuestion)
+            setRecord(null);
         setIsLoading(true);
         setError(null);
         try {
@@ -45,5 +79,24 @@ export function useRecord(collection, recordId, options) {
     useEffect(() => {
         doFetch();
     }, [doFetch]);
+    const answered = answeredRef.current;
+    const answersCurrentInputs = answered != null &&
+        answered.client === client &&
+        answered.collection === collection &&
+        answered.recordId === recordId;
+    // NOTE: the state answers other inputs — the fetch for these has not started
+    // yet, or nothing will be asked (no collection, or disabled after the inputs
+    // changed). Either way the old record and error answer something else. It
+    // is loading only when a fetch is due; an empty record id gets its error from
+    // the effect. Disabling without changing the inputs keeps what was fetched,
+    // as useRecordList does
+    if (!answersCurrentInputs) {
+        return {
+            record: null,
+            isLoading: enabled && !!collection && !!recordId,
+            error: null,
+            refetch: doFetch,
+        };
+    }
     return { record, isLoading, error, refetch: doFetch };
 }

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

@@ -124,6 +124,19 @@ export declare class SfaClient implements SfaClientInterface {
     private objectsPath;
     /** @description Returns the field-types catalog path for the current mode. */
     private fieldTypesPath;
+    /**
+     * @description Sets the auth headers, returning the token it used.
+     *
+     * NOTE: the caller keeps that token so a 401 can name it. Reading `this.auth`
+     * at the 401 would give the same value today — `auth` is readonly and
+     * `SfaProvider` builds a new client per token — but returning it from here
+     * keeps the answer true by construction.
+     *
+     * NOTE: this owns the `Authorization` header. It runs after any caller
+     * headers are spread in, so a caller-supplied one is overwritten — and if
+     * the client has no auth, the returned `undefined` would not describe it.
+     * Callers pass `If-Match` and the like, never `Authorization`.
+     */
     private applyAuth;
     /**
      * @description GET request with auth headers. Works for all read-only

package/src/lib/provider/SfaClient.js

@@ -388,14 +388,31 @@ export class SfaClient {
         return this.mode === 'direct' ? '/v1/field-types' : '/field-types';
     }
     // ── Private transport ──
+    /**
+     * @description Sets the auth headers, returning the token it used.
+     *
+     * NOTE: the caller keeps that token so a 401 can name it. Reading `this.auth`
+     * at the 401 would give the same value today — `auth` is readonly and
+     * `SfaProvider` builds a new client per token — but returning it from here
+     * keeps the answer true by construction.
+     *
+     * NOTE: this owns the `Authorization` header. It runs after any caller
+     * headers are spread in, so a caller-supplied one is overwritten — and if
+     * the client has no auth, the returned `undefined` would not describe it.
+     * Callers pass `If-Match` and the like, never `Authorization`.
+     */
     applyAuth(headers) {
         var _a;
-        if ((_a = this.auth) === null || _a === void 0 ? void 0 : _a.accessToken) {
-            headers['Authorization'] = `Bearer ${this.auth.accessToken}`;
+        const accessToken = (_a = this.auth) === null || _a === void 0 ? void 0 : _a.accessToken;
+        if (accessToken) {
+            headers['Authorization'] = `Bearer ${accessToken}`;
         }
         if (this.organizationId) {
             headers['organization-id'] = this.organizationId;
         }
+        // NOTE: 空文字は「トークンを送っていない」。値として返すと、受け手は
+        // 差し替え済みの遅れ着信と区別できず、認証なしの 401 を握り潰す
+        return accessToken || undefined;
     }
     /**
      * @description GET request with auth headers. Works for all read-only
@@ -408,7 +425,7 @@ export class SfaClient {
             const headers = {
                 'Content-Type': 'application/json',
             };
-            this.applyAuth(headers);
+            const sentToken = this.applyAuth(headers);
             const response = yield globalThis.fetch(url, {
                 method: 'GET',
                 headers,
@@ -416,7 +433,7 @@ export class SfaClient {
             });
             if (!response.ok) {
                 if (response.status === 401)
-                    (_a = this.onAuthError) === null || _a === void 0 ? void 0 : _a.call(this);
+                    (_a = this.onAuthError) === null || _a === void 0 ? void 0 : _a.call(this, sentToken);
                 const text = yield response.text().catch(() => '');
                 throw new SfaApiError(response.status, response.statusText, text, url);
             }
@@ -434,7 +451,7 @@ export class SfaClient {
             const headers = {
                 'Content-Type': 'application/json',
             };
-            this.applyAuth(headers);
+            const sentToken = this.applyAuth(headers);
             const response = yield globalThis.fetch(url, {
                 method: 'POST',
                 headers,
@@ -443,7 +460,7 @@ export class SfaClient {
             });
             if (!response.ok) {
                 if (response.status === 401)
-                    (_a = this.onAuthError) === null || _a === void 0 ? void 0 : _a.call(this);
+                    (_a = this.onAuthError) === null || _a === void 0 ? void 0 : _a.call(this, sentToken);
                 const text = yield response.text().catch(() => '');
                 throw new SfaApiError(response.status, response.statusText, text, url);
             }
@@ -460,7 +477,7 @@ export class SfaClient {
             var _a;
             const url = `${this.apiBase}${path}`;
             const headers = Object.assign({ 'Content-Type': 'application/json' }, options === null || options === void 0 ? void 0 : options.headers);
-            this.applyAuth(headers);
+            const sentToken = this.applyAuth(headers);
             const response = yield globalThis.fetch(url, {
                 method,
                 headers,
@@ -469,7 +486,7 @@ export class SfaClient {
             });
             if (!response.ok) {
                 if (response.status === 401)
-                    (_a = this.onAuthError) === null || _a === void 0 ? void 0 : _a.call(this);
+                    (_a = this.onAuthError) === null || _a === void 0 ? void 0 : _a.call(this, sentToken);
                 const text = yield response.text().catch(() => '');
                 if (response.status === 412) {
                     throw SfaConflictError.fromBody(response.status, response.statusText, text, url);

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

@@ -1,5 +1,5 @@
 import type { ReactNode } from 'react';
-import type { SfaApiMode, SfaAuth, SfaClientInterface } from './types';
+import type { SfaApiMode, SfaAuth, SfaAuthErrorHandler, SfaClientInterface } from './types';
 export interface SfaContextValue {
     readonly client: SfaClientInterface;
     readonly auth: SfaAuth | undefined;
@@ -14,7 +14,7 @@ interface SfaProviderProps {
     readonly auth?: SfaAuth;
     readonly mode?: SfaApiMode;
     readonly organizationId?: string;
-    readonly onAuthError?: () => void;
+    readonly onAuthError?: SfaAuthErrorHandler;
     /**
      * Disable mutation hooks (create/update/delete). Defaults to false.
      *

package/src/lib/provider/SfaProvider.js

@@ -38,7 +38,7 @@ export function SfaProvider({ apiBase, auth, mode, organizationId, onAuthError,
         auth: stableAuth,
         mode: resolvedMode,
         organizationId: resolvedOrgId,
-        onAuthError: () => { var _a; return (_a = onAuthErrorRef.current) === null || _a === void 0 ? void 0 : _a.call(onAuthErrorRef); },
+        onAuthError: rejectedToken => { var _a; return (_a = onAuthErrorRef.current) === null || _a === void 0 ? void 0 : _a.call(onAuthErrorRef, rejectedToken); },
     }), [apiBase, stableAuth, resolvedMode, resolvedOrgId]);
     const value = useMemo(() => ({
         client,

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

@@ -2,12 +2,23 @@ export interface SfaAuth {
     readonly accessToken: string;
 }
 export type SfaApiMode = 'direct' | 'proxy';
+/**
+ * @description Called when a request came back 401, naming the token it was
+ * sent with.
+ *
+ * `rejectedToken` is the access token that request carried, or `undefined`
+ * when it went out unauthenticated. A caller that swaps tokens needs it to
+ * tell a late reply about a token it has already replaced from a rejection of
+ * the one it holds now: the first is nothing to act on, the second means the
+ * session has to be re-established.
+ */
+export type SfaAuthErrorHandler = (rejectedToken: string | undefined) => void;
 export interface SfaClientConfig {
     readonly apiBase: string;
     readonly auth?: SfaAuth;
     readonly mode: SfaApiMode;
     readonly organizationId?: string;
-    readonly onAuthError?: () => void;
+    readonly onAuthError?: SfaAuthErrorHandler;
 }
 /**
  * @description Normalized field kinds aligned with keystone's 10-type model.