@geniee-inc/sfa-kit 1.14.1 → 1.17.0

package/src/lib/bundle/build-static-bundle.js

@@ -0,0 +1,263 @@
+import { __awaiter } from "tslib";
+import { mkdir, readFile, readdir, rm, stat, writeFile, } from 'node:fs/promises';
+import { join, posix, relative } from 'node:path';
+import { computeContentHash } from '../signing/compute-content-hash.js';
+import { readBundleFiles } from '../signing/read-bundle-files.js';
+import { loadEsbuild } from './esbuild-loader.js';
+import { requestSignature } from './request-signature.js';
+/** Where the bundled script lands inside the output directory. */
+const BUNDLE_PATH = 'assets/bundle.js';
+/** esbuild writes this beside the script when the entry imports any CSS. */
+const STYLES_PATH = 'assets/bundle.css';
+/**
+ * Every path this builder writes, relative to `outDir` with forward slashes.
+ *
+ * NOTE: full paths, not top-level names. Matching on names would accept any
+ * directory shaped like a static site — an `index.html` beside an `assets/`
+ * folder — and clear it.
+ */
+const OWN_OUTPUT = new Set([
+    'index.html',
+    'manifest.json',
+    BUNDLE_PATH,
+    STYLES_PATH,
+]);
+/** How many unexpected paths an error names before it stops listing them. */
+const UNEXPECTED_SHOWN = 5;
+/**
+ * Removed rather than refused. Opening the output directory in Finder to zip
+ * it — which GUIDE.md tells the reader to do — leaves a `.DS_Store` behind,
+ * and refusing it would wedge the build → zip → rebuild loop on a hidden file.
+ */
+const JUNK_FILES = new Set(['.DS_Store', 'Thumbs.db']);
+/**
+ * @description Builds the framework-free static bundle a page is uploaded as
+ * to become a custom tab, and signs it.
+ *
+ * Produces `index.html`, `assets/bundle.js` and a signed `manifest.json` in
+ * `outDir`. The caller zips that directory's contents — the files have to sit
+ * at the zip root. Zipping is left out because Node ships no zip writer, and a
+ * dependency for it would reach a package whose runtime needs only `tslib`.
+ *
+ * Signing is not optional, and a failure removes the output: an unsigned bundle
+ * uploads successfully while Keystone's verifier runs in `disabled` mode and
+ * only starts failing at `enforced`, so a half-built directory left behind is
+ * something a caller can still zip and upload by mistake.
+ *
+ * **Node.js only**, and needs `esbuild` installed alongside the kit.
+ *
+ * @returns The manifest that was written.
+ */
+export function buildStaticBundle(_a) {
+    return __awaiter(this, arguments, void 0, function* ({ entry, outDir, studioVersion, apiBase, accessToken, title = 'SFA/CRM', manifestExtras = {}, }) {
+        for (const [name, value] of [
+            ['entry', entry],
+            ['outDir', outDir],
+            ['studioVersion', studioVersion],
+            ['apiBase', apiBase],
+            ['accessToken', accessToken],
+        ]) {
+            // NOTE: checked before esbuild runs. An empty apiBase otherwise surfaces as
+            // "Failed to parse URL from /v1/pages/sign" after a full build.
+            // NOTE: `== null` as well as empty. The subpath is published, and a JS
+            // caller omitting a field would otherwise pay for a full build to reach
+            // `Authorization: Bearer undefined`.
+            if (value == null || value === '') {
+                throw new Error(`${name} is required and must not be empty`);
+            }
+        }
+        // Serialised now so a value that cannot be JSON — cyclic, a BigInt — fails
+        // before anything is written, rather than after Keystone has signed.
+        assertSerialisable(manifestExtras);
+        const esbuild = yield loadEsbuild();
+        yield prepareOutDir(outDir);
+        yield mkdir(join(outDir, 'assets'), { recursive: true });
+        try {
+            yield esbuild.build({
+                entryPoints: [entry],
+                outfile: join(outDir, BUNDLE_PATH),
+                bundle: true,
+                minify: true,
+                format: 'esm',
+                jsx: 'automatic',
+                target: 'es2020',
+            });
+            // entry が CSS を import していると esbuild が bundle.css も書き出す。
+            // index.html から参照しないと、署名も検証も通ったうえで無スタイルの画面が
+            // 出る — どこにも失敗が現れない
+            const hasStyles = yield stat(join(outDir, STYLES_PATH)).then(() => true, () => false);
+            yield writeFile(join(outDir, 'index.html'), renderIndexHtml(title, hasStyles), 'utf-8');
+            // manifest.json is written last: the hash covers every other file, so the
+            // directory has to be complete before it is computed.
+            const contentHash = computeContentHash(yield readBundleFiles(outDir));
+            const manifest = {
+                studio_version: studioVersion,
+                content_hash: contentHash,
+                signature: yield requestSignature({
+                    apiBase,
+                    accessToken,
+                    studioVersion,
+                    contentHash,
+                }),
+            };
+            yield writeFile(join(outDir, 'manifest.json'), 
+            // NOTE: the decorative fields go first so the three signed ones cannot be
+            // overwritten by a caller's extras.
+            `${JSON.stringify(Object.assign(Object.assign({}, manifestExtras), manifest), null, 2)}\n`, 'utf-8');
+            return manifest;
+        }
+        catch (thrown) {
+            // Whatever was written is a bundle in every respect but the manifest, and
+            // a caller can still zip and upload it.
+            yield removeOwnOutput(outDir).catch(() => {
+                throw new Error(`${thrown instanceof Error ? thrown.message : String(thrown)} ` +
+                    `Additionally, ${outDir} could not be cleaned up — delete it by ` +
+                    'hand rather than uploading it; it carries no signature.');
+            });
+            throw thrown;
+        }
+    });
+}
+/** Fails now on a value `JSON.stringify` would reject after the bundle is signed. */
+function assertSerialisable(extras) {
+    try {
+        JSON.stringify(extras);
+    }
+    catch (thrown) {
+        throw new Error('manifestExtras must be JSON-serialisable ' +
+            `(${thrown instanceof Error ? thrown.message : String(thrown)})`);
+    }
+}
+/**
+ * @description Empties the output directory of previous build output, and
+ * refuses to touch anything else.
+ *
+ * NOTE: `outDir` comes from a caller's flag, so nothing is deleted recursively
+ * — `--out src` would take the source tree with it. Only the exact files this
+ * builder writes are removed, and any other file at any depth stops the build:
+ * a leftover lands in `content_hash` and then has to be in the zip for the
+ * signature to match, which quietly makes it part of the bundle.
+ *
+ * NOTE: matching those names is not enough to claim the directory. `index.html`
+ * beside `assets/bundle.js` is also what a hand-written static site looks like,
+ * and deleting one would be unrecoverable. A `manifest.json` carrying the three
+ * signed fields is the proof, because only this builder writes one.
+ */
+function prepareOutDir(outDir) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        // NOTE: names only. Reading contents here — as readBundleFiles does — would
+        // pull the whole directory into memory to decide it is the wrong directory,
+        // so `--out .` in a repository would run out of memory instead of refusing.
+        const entries = yield readdir(outDir, {
+            recursive: true,
+            withFileTypes: true,
+        }).catch((thrown) => {
+            // Only "it is not there yet" means there is nothing to check. Swallowing
+            // every error would turn a permission problem into a silent build over
+            // whatever the directory held.
+            if (thrown.code === 'ENOENT')
+                return null;
+            throw thrown;
+        });
+        if (entries == null)
+            return;
+        const unexpected = [];
+        const junk = [];
+        const own = [];
+        for (const entry of entries) {
+            if (!entry.isFile())
+                continue;
+            const parent = (_a = entry.parentPath) !== null && _a !== void 0 ? _a : entry.path;
+            const path = relative(outDir, join(parent, entry.name))
+                .split(/[\\/]/)
+                .join(posix.sep);
+            if (OWN_OUTPUT.has(path)) {
+                own.push(path);
+                continue;
+            }
+            // NOTE: collected, not deleted yet. Removing junk from a directory the
+            // next few lines may refuse to touch would contradict the promise above.
+            if (JUNK_FILES.has(entry.name)) {
+                junk.push(join(parent, entry.name));
+                continue;
+            }
+            unexpected.push(path);
+            if (unexpected.length > UNEXPECTED_SHOWN)
+                break;
+        }
+        if (unexpected.length > 0) {
+            const shown = unexpected.slice(0, UNEXPECTED_SHOWN).sort().join(', ');
+            const more = unexpected.length > UNEXPECTED_SHOWN ? ', and more' : '';
+            throw new Error(`${outDir} holds files this build did not produce ` +
+                `(${shown}${more}). They would be hashed into the bundle. ` +
+                'Point --out at an empty directory, or clear it first.');
+        }
+        if (own.length > 0 && !(yield hasOwnManifest(outDir))) {
+            throw new Error(`${outDir} holds ${own.sort().join(', ')} but no manifest.json this ` +
+                'builder wrote, so it is not a previous build of this bundle and will ' +
+                'not be overwritten. Point --out at an empty directory, or clear it ' +
+                'first.');
+        }
+        for (const path of junk) {
+            yield rm(path, { force: true });
+        }
+        yield removeOwnOutput(outDir);
+    });
+}
+/** Whether the directory carries a manifest only this builder could have written. */
+function hasOwnManifest(outDir) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const raw = yield readFile(join(outDir, 'manifest.json'), 'utf-8').catch(() => null);
+        if (raw == null)
+            return false;
+        try {
+            const parsed = JSON.parse(raw);
+            return ['studio_version', 'content_hash', 'signature'].every(field => typeof parsed[field] === 'string' && parsed[field] !== '');
+        }
+        catch (_a) {
+            return false;
+        }
+    });
+}
+/**
+ * @description Deletes the files this builder writes, and nothing else.
+ *
+ * NOTE: separate from {@link prepareOutDir} because the failure path needs the
+ * removal without the validation. Reusing the checking function there would
+ * throw on any stray file and leave the unsigned bundle exactly where the
+ * contract promises it will not be.
+ */
+function removeOwnOutput(outDir) {
+    return __awaiter(this, void 0, void 0, function* () {
+        for (const path of OWN_OUTPUT) {
+            yield rm(join(outDir, path), { force: true });
+        }
+    });
+}
+/** The host page for the bundle: the script, and the stylesheet if there is one. */
+function renderIndexHtml(title, hasStyles) {
+    const stylesheet = hasStyles
+        ? `\n    <link rel="stylesheet" href="./${STYLES_PATH}" />`
+        : '';
+    return `<!doctype html>
+<html lang="ja">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${escapeHtml(title)}</title>${stylesheet}
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="./${BUNDLE_PATH}"></script>
+  </body>
+</html>
+`;
+}
+function escapeHtml(value) {
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}

package/src/lib/bundle/esbuild-loader.d.ts

@@ -0,0 +1,25 @@
+/** The slice of esbuild's API the bundler uses. */
+export interface EsbuildModule {
+    build(options: {
+        entryPoints: string[];
+        outfile: string;
+        bundle: boolean;
+        minify: boolean;
+        format: 'esm';
+        jsx: 'automatic';
+        target: string;
+    }): Promise<unknown>;
+}
+/**
+ * @description Loads esbuild at call time.
+ *
+ * esbuild is an optional peer: it is a build-time tool for the one caller that
+ * packages a static bundle, and adding it to `dependencies` would put a
+ * platform-specific binary into every install of a package whose runtime needs
+ * nothing but `tslib`.
+ *
+ * NOTE: the specifier goes through a variable so TypeScript does not resolve
+ * `esbuild` at compile time. Naming it directly would make the kit fail to
+ * build wherever esbuild is absent — which is everywhere it is not being used.
+ */
+export declare function loadEsbuild(): Promise<EsbuildModule>;

package/src/lib/bundle/esbuild-loader.js

@@ -0,0 +1,27 @@
+import { __awaiter } from "tslib";
+/**
+ * @description Loads esbuild at call time.
+ *
+ * esbuild is an optional peer: it is a build-time tool for the one caller that
+ * packages a static bundle, and adding it to `dependencies` would put a
+ * platform-specific binary into every install of a package whose runtime needs
+ * nothing but `tslib`.
+ *
+ * NOTE: the specifier goes through a variable so TypeScript does not resolve
+ * `esbuild` at compile time. Naming it directly would make the kit fail to
+ * build wherever esbuild is absent — which is everywhere it is not being used.
+ */
+export function loadEsbuild() {
+    return __awaiter(this, void 0, void 0, function* () {
+        const specifier = 'esbuild';
+        try {
+            return (yield import(specifier));
+        }
+        catch (thrown) {
+            const reason = thrown instanceof Error ? thrown.message : String(thrown);
+            throw new Error('esbuild is required to build a static bundle but could not be loaded ' +
+                `(${reason}). Install it alongside @geniee-inc/sfa-kit ` +
+                '(npm install --save-dev esbuild).');
+        }
+    });
+}

package/src/lib/bundle/index.d.ts

@@ -0,0 +1,2 @@
+export type { BuildStaticBundleOptions } from './build-static-bundle.js';
+export { buildStaticBundle } from './build-static-bundle.js';

package/src/lib/bundle/index.js

@@ -0,0 +1 @@
+export { buildStaticBundle } from './build-static-bundle.js';

package/src/lib/bundle/request-signature.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @description Asks Keystone to sign a bundle, returning the signature.
+ *
+ * The signing key never leaves Keystone: deploying it to the page builder as
+ * well was the original design and was dropped because Studio's secret store is
+ * per project while the key must be identical across all of them (SFAJAI-186).
+ * The caller computes `contentHash` locally and Keystone signs it.
+ *
+ * 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
+ * the mode is switched to `enforced` — with nothing on this side to explain it.
+ *
+ * @param apiBase - Keystone API base. A trailing slash is trimmed.
+ * @param accessToken - The same Bearer token the rest of the API is called with.
+ */
+export declare function requestSignature({ apiBase, accessToken, studioVersion, contentHash, }: {
+    readonly apiBase: string;
+    readonly accessToken: string;
+    readonly studioVersion: string;
+    readonly contentHash: string;
+}): Promise<string>;

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

@@ -0,0 +1,81 @@
+import { __awaiter } from "tslib";
+/**
+ * Both the hash sent and the signature returned are hex SHA-256 / HMAC-SHA-256
+ * digests, so the same shape applies in each direction.
+ */
+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;
+/**
+ * @description Asks Keystone to sign a bundle, returning the signature.
+ *
+ * The signing key never leaves Keystone: deploying it to the page builder as
+ * well was the original design and was dropped because Studio's secret store is
+ * per project while the key must be identical across all of them (SFAJAI-186).
+ * The caller computes `contentHash` locally and Keystone signs it.
+ *
+ * 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
+ * the mode is switched to `enforced` — with nothing on this side to explain it.
+ *
+ * @param apiBase - Keystone API base. A trailing slash is trimmed.
+ * @param accessToken - The same Bearer token the rest of the API is called with.
+ */
+export function requestSignature(_a) {
+    return __awaiter(this, arguments, void 0, function* ({ apiBase, accessToken, studioVersion, contentHash, }) {
+        if (!HEX_DIGEST_PATTERN.test(contentHash)) {
+            throw new Error(`content_hash must be a 64-character hex digest, got ${JSON.stringify(contentHash)}`);
+        }
+        // 末尾のスラッシュを落とす。付いたままだと //v1/pages/sign になり、多くの
+        // ゲートウェイが 404 を返すため、設定ミスが認証の問題に見える
+        const base = apiBase.replace(/\/+$/, '');
+        const url = `${base}/v1/pages/sign`;
+        // NOTE: a bad host gives "fetch failed" and an empty apiBase "Failed to parse
+        // URL from /v1/pages/sign" — neither names the endpoint, the base, or the
+        // fact that the bundle is now unsigned.
+        const response = yield globalThis
+            .fetch(url, {
+            // NOTE: without a deadline a server that accepts the connection and never
+            // answers hangs the build, leaving an unsigned output directory behind.
+            signal: AbortSignal.timeout(SIGN_TIMEOUT_MS),
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${accessToken}`,
+            },
+            body: JSON.stringify({
+                studio_version: studioVersion,
+                content_hash: contentHash,
+            }),
+        })
+            .catch((thrown) => {
+            throw new Error(`POST ${url} could not be reached ` +
+                `(${thrown instanceof Error ? thrown.message : String(thrown)}). ` +
+                'The bundle was not signed; check the API base and network access.');
+        });
+        if (!response.ok) {
+            const detail = yield response.text().catch(() => '');
+            // NOTE: the endpoint exists (SFAJAI-186), so a 404 is a wrong apiBase and a
+            // 401 a token from another org — not a reason to ship the bundle unsigned.
+            throw new Error(`POST /v1/pages/sign failed: ${response.status} ${response.statusText}` +
+                `${detail ? ` — ${detail}` : ''}. The bundle was not signed and must ` +
+                'not be uploaded; check the API base and the access token.');
+        }
+        // NOTE: a proxy answering 200 with an HTML page would throw a bare
+        // SyntaxError here, escaping the messages built for every other failure.
+        const payload = (yield response.json().catch(() => null));
+        if (payload == null || typeof payload.signature !== 'string') {
+            throw new Error(`POST ${url} returned no signature. The bundle was not signed.`);
+        }
+        // NOTE: the hash sent is validated, so the signature coming back is too. An
+        // 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)) {
+            throw new Error(`POST ${url} returned ${JSON.stringify(payload.signature)}, which is ` +
+                'not an HMAC-SHA-256 hex digest. The bundle was not signed.');
+        }
+        return payload.signature;
+    });
+}

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