@geniee-inc/sfa-kit 1.10.0 → 1.12.0

package/src/lib/hooks/useBulkUpdateRecords.js

@@ -0,0 +1,37 @@
+import { useMemo } from 'react';
+import { splitBulkRows } from './splitBulkRows';
+import { useBulkWrite } from './useBulkWrite';
+/** Module level so its identity never changes: `run` stays stable. */
+const sendBulkUpdate = (client, collection, rows) => client.bulkUpdate(collection, rows);
+/**
+ * @description Imperative hook for updating many records of one object in a
+ * single call — the save action of a grid edit.
+ *
+ * Best-effort per row: the API answers 200 and reports each row's outcome,
+ * with no all-or-nothing mode. A stale row is reported as `conflict` and left
+ * unchanged while the rest of the batch applies, so per-row outcomes come back
+ * 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
+ * re-read, not retried.
+ */
+export function useBulkUpdateRecords(collection) {
+    const { run, results, isLoading, error, reset } = useBulkWrite(collection, sendBulkUpdate);
+    /**
+     * NOTE: memoised because a grid passes these into effect and callback
+     * dependency lists; fresh arrays every render would re-run that work.
+     */
+    const split = useMemo(() => splitBulkRows(results, 'updated', row => row.record), [results]);
+    return {
+        bulkUpdate: run,
+        results,
+        updated: split.landed,
+        conflicts: split.conflicts,
+        failed: split.failed,
+        unresolved: split.unresolved,
+        isLoading,
+        error,
+        reset,
+    };
+}

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

@@ -0,0 +1,55 @@
+import type { SfaBulkRowResult, SfaClientInterface } from '../provider/types';
+export interface BulkWriteState<TRow> {
+    readonly run: (rows: readonly TRow[]) => Promise<readonly SfaBulkRowResult[]>;
+    readonly results: readonly SfaBulkRowResult[];
+    readonly isLoading: boolean;
+    readonly error: Error | null;
+    readonly reset: () => void;
+}
+/**
+ * @description The state the three bulk write hooks share: one call in flight,
+ * its per-row results, and whether the call as a whole was rejected.
+ *
+ * `send` takes the client and collection as arguments so it can be defined
+ * once per hook at module level. Its identity never changes, which is what
+ * keeps `run` stable across renders.
+ *
+ * A hook instance outlives its arguments: a grid switches object, and the
+ * provider builds a new client on a token refresh or an org switch. Outcomes
+ * must never be reported as the current object's, and this is settled in two
+ * places that answer two different questions.
+ *
+ * NOTE: what to show is settled during render, by clearing the state as the
+ * arguments change. Clearing in an effect instead would leave one render
+ * showing the previous object's rows. React discards a render it does not
+ * commit — an interrupted transition — along with the state set during it, so
+ * a screen that never appears cannot blank the one the user is looking at.
+ *
+ * NOTE: whether an answer may still be published is settled against the
+ * arguments as last **committed**, tracked in a ref written from a commit
+ * effect. Effects run only for renders that commit, so a transition React
+ * starts and abandons cannot orphan the request the visible screen is waiting
+ * for. A ref written during render would: the write survives the abandoned
+ * render, and the committed screen's own answer would be taken for a stale
+ * one.
+ *
+ * NOTE: the number itself is assigned during render and kept in state, so a
+ * callback knows which arguments it was made for without reading the ref, and
+ * the ref is recorded in the insertion phase — before any child's layout
+ * effect can call back into this hook. A callback from an earlier render is
+ * therefore recognised as stale even inside the commit that superseded it,
+ * and the current one is never mistaken for stale.
+ *
+ * The number advances on every committed change, so returning to an object
+ * does not adopt the earlier visit's request: a batch started before the
+ * reader left carries a number the ref has moved past.
+ *
+ * NOTE: read-only is read from that same committed ref, not from the
+ * callback's own value. The ref is current from the insertion phase onwards,
+ * so it answers for the commit that turns the setting on as well as for a
+ * `run` the caller kept from before it — a callback's own copy would be
+ * whatever its render saw. Read-only throws before anything is sent, the same
+ * as the single-record write hooks: it is a provider setting, not an outcome
+ * of the call, so it never reaches `error`.
+ */
+export declare function useBulkWrite<TRow>(collection: string, send: (client: SfaClientInterface, collection: string, rows: readonly TRow[]) => Promise<readonly SfaBulkRowResult[]>): BulkWriteState<TRow>;

package/src/lib/hooks/useBulkWrite.js

@@ -0,0 +1,160 @@
+import { __awaiter } from "tslib";
+import { useCallback, useEffect, useInsertionEffect, useRef, useState, } from 'react';
+import { ERR_READ_ONLY } from '../errors';
+import { useSfaContext } from '../provider/useSfaClient';
+/** Stable identity so an unfinished batch never re-renders on a fresh array. */
+const NO_RESULTS = [];
+/**
+ * Runs in the insertion phase of the commit, which React finishes for the
+ * whole tree before any layout effect runs. A child's layout effect can
+ * therefore call this hook during the very commit that changed its arguments
+ * and still see them recorded — the ordering is child-insertion,
+ * parent-insertion, child-layout, parent-layout. A layout effect here would
+ * be too late, since the child's runs first.
+ *
+ * Insertion effects run only for renders that commit, so an abandoned
+ * transition still leaves nothing behind. There is no commit to observe on
+ * the server, where it would only warn, so the plain effect stands in.
+ */
+const useCommitEffect = typeof window === 'undefined' ? useEffect : useInsertionEffect;
+const NOTHING_WRITTEN = {
+    results: NO_RESULTS,
+    isLoading: false,
+    error: null,
+};
+/**
+ * @description The state the three bulk write hooks share: one call in flight,
+ * its per-row results, and whether the call as a whole was rejected.
+ *
+ * `send` takes the client and collection as arguments so it can be defined
+ * once per hook at module level. Its identity never changes, which is what
+ * keeps `run` stable across renders.
+ *
+ * A hook instance outlives its arguments: a grid switches object, and the
+ * provider builds a new client on a token refresh or an org switch. Outcomes
+ * must never be reported as the current object's, and this is settled in two
+ * places that answer two different questions.
+ *
+ * NOTE: what to show is settled during render, by clearing the state as the
+ * arguments change. Clearing in an effect instead would leave one render
+ * showing the previous object's rows. React discards a render it does not
+ * commit — an interrupted transition — along with the state set during it, so
+ * a screen that never appears cannot blank the one the user is looking at.
+ *
+ * NOTE: whether an answer may still be published is settled against the
+ * arguments as last **committed**, tracked in a ref written from a commit
+ * effect. Effects run only for renders that commit, so a transition React
+ * starts and abandons cannot orphan the request the visible screen is waiting
+ * for. A ref written during render would: the write survives the abandoned
+ * render, and the committed screen's own answer would be taken for a stale
+ * one.
+ *
+ * NOTE: the number itself is assigned during render and kept in state, so a
+ * callback knows which arguments it was made for without reading the ref, and
+ * the ref is recorded in the insertion phase — before any child's layout
+ * effect can call back into this hook. A callback from an earlier render is
+ * therefore recognised as stale even inside the commit that superseded it,
+ * and the current one is never mistaken for stale.
+ *
+ * The number advances on every committed change, so returning to an object
+ * does not adopt the earlier visit's request: a batch started before the
+ * reader left carries a number the ref has moved past.
+ *
+ * NOTE: read-only is read from that same committed ref, not from the
+ * callback's own value. The ref is current from the insertion phase onwards,
+ * so it answers for the commit that turns the setting on as well as for a
+ * `run` the caller kept from before it — a callback's own copy would be
+ * whatever its render saw. Read-only throws before anything is sent, the same
+ * as the single-record write hooks: it is a provider setting, not an outcome
+ * of the call, so it never reaches `error`.
+ */
+export function useBulkWrite(collection, send) {
+    const { client, readOnly } = useSfaContext();
+    const [state, setState] = useState(NOTHING_WRITTEN);
+    const [numbered, setNumbered] = useState({
+        client,
+        collection,
+        sequence: 0,
+    });
+    const callId = useRef(0);
+    const committed = useRef({
+        readOnly,
+        sequence: numbered.sequence,
+    });
+    // NOTE: the state adjustment React documents for props changes — set during
+    // render, so this render already reports nothing, and thrown away with the
+    // render if it never commits
+    if (numbered.client !== client || numbered.collection !== collection) {
+        setNumbered({ client, collection, sequence: numbered.sequence + 1 });
+        setState(NOTHING_WRITTEN);
+    }
+    const sequence = numbered.sequence;
+    useCommitEffect(() => {
+        committed.current = { readOnly, sequence };
+    }, [readOnly, sequence]);
+    const run = useCallback((rows) => __awaiter(this, void 0, void 0, function* () {
+        // NOTE: both refusals come before anything is claimed. Bumping the call
+        // id first would let a refusal disown a batch that is still running, and
+        // its answer — the only record of the ids that landed — would be dropped
+        if (committed.current.readOnly) {
+            throw new Error(ERR_READ_ONLY);
+        }
+        // NOTE: this callback sends to the client and collection it was made
+        // with. Once a later set of arguments has been committed it would write
+        // to an object the reader has left, so it refuses. Sending to wherever
+        // the hook now points would be worse: the rows were meant for the object
+        // the caller asked for.
+        //
+        // NOTE: strictly later, not merely different. Only a callback the
+        // commit record has moved past is stale; one carrying a number the
+        // record has not reached could only come from a render that never
+        // committed, and no such callback can be invoked.
+        if (committed.current.sequence > sequence) {
+            throw new Error(`This bulk write was prepared for ${collection} under arguments ` +
+                'the hook has moved past — a different object, or a client the ' +
+                'provider has replaced. Use the callback it returns now.');
+        }
+        callId.current += 1;
+        const currentCallId = callId.current;
+        const stillOwnsTheState = () => currentCallId === callId.current &&
+            committed.current.sequence === sequence;
+        // NOTE: the previous results stay visible while the next batch runs, so
+        // a grid does not blank the outcomes the reader is still acting on
+        setState(previous => ({
+            results: previous.results,
+            isLoading: true,
+            error: null,
+        }));
+        try {
+            const rowResults = yield send(client, collection, rows);
+            if (stillOwnsTheState()) {
+                setState({ results: rowResults, isLoading: false, error: null });
+            }
+            return rowResults;
+        }
+        catch (e) {
+            // NOTE: the results of the previous call are kept. They are still true
+            // about the rows that landed then, and a rejected retry must not be
+            // what makes those ids disappear — nothing else records them
+            if (stillOwnsTheState()) {
+                setState(previous => ({
+                    results: previous.results,
+                    isLoading: false,
+                    error: e instanceof Error ? e : new Error(String(e)),
+                }));
+            }
+            throw e;
+        }
+    }), [client, collection, send, sequence]);
+    const reset = useCallback(() => {
+        callId.current += 1;
+        setState(NOTHING_WRITTEN);
+    }, []);
+    return {
+        run,
+        results: state.results,
+        isLoading: state.isLoading,
+        error: state.error,
+        reset,
+    };
+}

package/src/lib/hooks/useRecordList.js

@@ -1,5 +1,6 @@
 import { __awaiter } from "tslib";
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useEmbedContext } from '../auth/useEmbedContext';
 import { useSfaClient } from '../provider/useSfaClient';
 /** Stable identity so an unanswered query never re-renders on a fresh array. */
 const NO_ITEMS = [];
@@ -7,9 +8,11 @@ const NO_ITEMS = [];
  * @description Fetches a paginated list of records from the SFA/CRM API.
  */
 export function useRecordList(collection, params, options) {
-    var _a, _b, _c;
+    var _a, _b, _c, _d;
     const client = useSfaClient();
-    const limit = (_a = params === null || params === void 0 ? void 0 : params.limit) !== null && _a !== void 0 ? _a : 20;
+    const embedCtx = useEmbedContext();
+    const listId = (_a = params === null || params === void 0 ? void 0 : params.listId) !== null && _a !== void 0 ? _a : embedCtx === null || embedCtx === void 0 ? void 0 : embedCtx.list_id;
+    const limit = (_b = params === null || params === void 0 ? void 0 : params.limit) !== null && _b !== void 0 ? _b : 20;
     const [items, setItems] = useState([]);
     const [totalCount, setTotalCount] = useState(0);
     const [hasMore, setHasMore] = useState(false);
@@ -22,11 +25,11 @@ export function useRecordList(collection, params, options) {
      * about the *first* page: from there the hook pages on its own, computing
      * offsets from the page number and reusing cursors the server handed back.
      */
-    const initialOffset = (_b = params === null || params === void 0 ? void 0 : params.offset) !== null && _b !== void 0 ? _b : 0;
+    const initialOffset = (_c = params === null || params === void 0 ? void 0 : params.offset) !== null && _c !== void 0 ? _c : 0;
     const initialCursor = params === null || params === void 0 ? void 0 : params.cursor;
     const initialPage = limit > 0 ? Math.floor(initialOffset / limit) : 0;
     const [pageIndex, setPageIndex] = useState(initialPage);
-    const enabled = (_c = options === null || options === void 0 ? void 0 : options.enabled) !== null && _c !== void 0 ? _c : true;
+    const enabled = (_d = options === null || options === void 0 ? void 0 : options.enabled) !== null && _d !== void 0 ? _d : true;
     // NOTE: the seed is never published. Until a fetch settles for the current
     // query the reported status is derived below, so this only matters after the
     // first settle — by which time a fetch has set it.
@@ -50,6 +53,7 @@ export function useRecordList(collection, params, options) {
         filterKey,
         initialOffset,
         initialCursor,
+        listId,
     }), [
         collection,
         limit,
@@ -58,6 +62,7 @@ export function useRecordList(collection, params, options) {
         filterKey,
         initialOffset,
         initialCursor,
+        listId,
     ]);
     /**
      * Which client, query and page the records in state came from, so a failure
@@ -95,14 +100,14 @@ export function useRecordList(collection, params, options) {
             // Every other page is reached with what the server handed back, or with
             // an offset computed from the page number.
             const cursor = (_a = cursorMapRef.current.get(page)) !== null && _a !== void 0 ? _a : (page === initialPage ? initialCursor : undefined);
-            const result = yield client.list(collection, Object.assign({ limit, 
+            const result = yield client.list(collection, Object.assign(Object.assign({ limit, 
                 // NOTE: offset is a record position, not a page number. Sending the
                 // page number asks for records 1..limit for page 1: it overlaps
                 // page 0 and comes back reporting pageIndex 0, so the list never
                 // advances. SfaClient derives pageIndex from this offset even when
                 // the server paginates by cursor, so the two have to agree.
                 offset: page === initialPage ? initialOffset : page * limit, sortBy,
-                sortOrder, filter: filterRef.current }, (cursor ? { cursor } : {})));
+                sortOrder, filter: filterRef.current }, (cursor ? { cursor } : {})), (listId ? { listId } : {})));
             if (currentFetchId === fetchId.current) {
                 // NOTE: the refs are written before the setState calls. Outside an
                 // event handler React 18 in legacy mode re-renders on every setState
@@ -179,6 +184,7 @@ export function useRecordList(collection, params, options) {
         initialOffset,
         initialCursor,
         initialPage,
+        listId,
     ]);
     useEffect(() => {
         // Invalidate anything still in flight before deciding what to do next.

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

@@ -1,4 +1,23 @@
-import type { SfaApiMode, SfaClientConfig, SfaClientInterface, SfaCreateOptions, SfaDescribeResult, SfaFieldError, SfaFieldTypeCatalog, SfaListParams, SfaListResponse, SfaObjectCatalog, SfaRecord } from './types';
+import type { SfaApiMode, SfaBulkDeleteRow, SfaBulkRowResult, SfaBulkUpdateRow, SfaClientConfig, SfaClientInterface, SfaCreateOptions, SfaDescribeResult, SfaFieldError, SfaFieldTypeCatalog, SfaListParams, SfaListResponse, SfaObjectCatalog, SfaRecord } from './types';
+/**
+ * @description The most rows one bulk call sends.
+ *
+ * NOTE: the API's own contract is `minItems: 1, maxItems: 100`. 25 is the
+ * kit's stricter limit, and it comes from how long the call takes rather than
+ * from what the API accepts: Keystone delegates one row at a time, measured at
+ * about 1.4 s per row on staging (2026-09-04). 25 rows fits inside the
+ * server's own 45 s budget for a bulk write, which in turn fits inside the
+ * 60 s ALB idle timeout. Agreed with Kumada and Takeuchi.
+ *
+ * Do not raise this to match `maxItems` — a call of 100 rows would outlast
+ * the server's budget and then the load balancer, and the caller would learn
+ * nothing about which rows had been written. It can go up only once a row
+ * costs less, or those limits change.
+ *
+ * NOTE: public because a caller cannot batch without it, and kept next to the
+ * check that enforces it so the two cannot disagree.
+ */
+export declare const SFA_BULK_MAX_ROWS = 25;
 /**
  * @description API client for SFA/CRM data operations via keystone.
  * Authenticates with a JWT Bearer token.
@@ -30,10 +49,57 @@ export declare class SfaClient implements SfaClientInterface {
     /** @description Throws if recordId is empty to prevent malformed API requests. */
     private assertRecordId;
     /**
-     * @description Creates a new record. Optionally accepts an idempotency key
-     * to prevent duplicate creates on retries.
+     * @description Creates a new record.
+     *
+     * NOTE: a retried create writes a second record — nothing de-duplicates it.
      */
     create(collection: string, fields: Record<string, unknown>, options?: SfaCreateOptions): Promise<SfaRecord>;
+    /**
+     * @description Creates many records of one object in a single call.
+     *
+     * The call is best-effort per row: the API answers 200 and reports every
+     * row's outcome, so a failed row does not undo the ones that worked. Per-row
+     * failures come back as results, not as thrown errors — throwing would
+     * discard the ids of the rows that succeeded, which are not recoverable
+     * anywhere else. SfaValidationError and the rest still surface when the
+     * whole call is rejected.
+     *
+     * Retry only the failed rows. What makes that safe is that those rows did
+     * not apply: nothing on the server de-duplicates a repeated write.
+     */
+    bulkCreate(collection: string, rows: readonly Record<string, unknown>[]): Promise<readonly SfaBulkRowResult[]>;
+    /**
+     * @description Updates many records of one object in a single call.
+     *
+     * Each row carries its own `version`, so a stale row comes back as
+     * `conflict` with the server's current record to reconcile from — the rest
+     * of the batch still applies, and nothing is rolled back. Per-row outcomes
+     * are results, not thrown errors: a throw would hide which rows landed.
+     */
+    bulkUpdate(collection: string, rows: readonly SfaBulkUpdateRow[]): Promise<readonly SfaBulkRowResult[]>;
+    /**
+     * @description Deletes many records of one object in a single call.
+     *
+     * Each row carries the `version` last read for it; a stale row comes back as
+     * `conflict` and is left in place while the rest of the batch applies.
+     */
+    bulkDelete(collection: string, rows: readonly SfaBulkDeleteRow[]): Promise<readonly SfaBulkRowResult[]>;
+    /**
+     * @description Prepares one row's fields for a bulk write.
+     *
+     * NOTE: shared by bulk-create and bulk-update so the two steps stay in this
+     * order for both. Schema-aware normalisation reads the object's field types
+     * — a select written by label, a date written loosely — and the write
+     * normalisation that follows only shapes what it produced.
+     */
+    private normalizeRowFields;
+    /**
+     * @description Sends one bulk request and reads its per-row outcomes.
+     *
+     * NOTE: shared by the three bulk methods so the envelope and the result
+     * parsing cannot drift apart between them.
+     */
+    private postBulk;
     /**
      * @description Updates a record with optimistic locking. The version token
      * (from a prior GET) is sent as the If-Match header; a 412 response means