@geniee-inc/sfa-kit 1.11.0 → 1.12.0

package/GUIDE.md

@@ -263,6 +263,163 @@ Check `status` for **every** hook on the page, not just the first one. Each rela
 
 Returns `{ items, totalCount, hasMore, pageIndex, status, goToPage, isLoading, error, refetch, relationship }`.
 
+### Bulk writes
+
+`useBulkCreateRecords`, `useBulkUpdateRecords` and `useBulkDeleteRecords` write
+many records of one object in a single call — for grid edits and other
+multi-row saves, instead of looping the single-record hooks. They share the
+contract below; the three sections after it cover only what differs.
+
+**A bulk call is best-effort per row.** The API answers `200` and reports every
+row's outcome — there is no all-or-nothing mode, so a batch can be partly
+successful and nothing is rolled back. That is why per-row failures come back
+as data rather than thrown errors: throwing would discard the ids of the rows
+that did land, and those are not recoverable anywhere else.
+
+- `results` — one entry per submitted row, carrying `index` (its position in
+  the request), `status`, `record` and `error`. Each entry is placed by its
+  `index`, never by the order it arrived in, so `results[n]` is the outcome of
+  the row that was sent at position `n`. A response that cannot be paired with
+  the request — fewer entries than rows, an index missing, not a whole
+  position, repeated, or past the end — is refused rather than returned: some
+  submitted row would have no reported outcome, and showing the rest as the
+  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
+- `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
+- `isLoading` — a call is in flight. Starting a second call supersedes the
+  first: whichever was started last owns the state, so a slower earlier batch
+  cannot publish outcomes for rows the caller has moved on from
+- `error` — set only when the whole call was rejected: row count out of range,
+  a response that does not answer for every row, auth, a 4xx/5xx. Individual
+  row failures are never reported here. The call **also rejects**, the same as
+  the single-record write hooks, so catch it to keep the rejection out of the
+  console; what to show the reader comes from `error`
+- `reset` — clears results and error
+
+A `501` inside that error is not a hiccup: the object does not offer bulk
+writes at all. Waiting or retrying will never make it work, so tell the reader
+the operation is unavailable for this object instead of offering a retry. Read
+it from `SfaApiError.status`.
+
+Everything the hook reports describes the object it was written for, on the
+visit it was written on. Pass a different collection, or let the provider
+rebuild its client — a token refresh or an org switch does — and results,
+loading and error read empty again rather than carrying the previous object's
+rows over. Coming back to that object does not bring them back either: they
+belong to the visit that ended. A batch that was already in flight answers into
+nothing, then and later.
+
+Read-only mode is not reported through `error`: the call throws instead,
+because it is a provider setting rather than an outcome of the request.
+
+A call takes 1..`SFA_BULK_MAX_ROWS` (25) rows. The API itself accepts up to
+100; 25 is the kit's own limit, set by how long a call takes — the server
+writes one row at a time, under a budget of its own, and a larger batch would
+outlast it and then the load balancer. A larger selection is refused before a
+request goes out rather than being cut off mid-write. Split bigger selections
+into batches; each batch is its own call.
+
+A bulk write is also given a longer fetch timeout than other calls, so the
+browser waits for the server to finish rather than dropping an answer that
+names the rows already written. Should a call time out anyway, treat the whole
+batch the way you treat `unresolved`: the server may have written some of it
+and the answer is gone, so re-read the records rather than sending them
+again.
+
+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.
+
+Everything else is `unresolved`: `indeterminate`, the server saying it cannot
+tell whether the row applied; a claimed success missing what it should carry —
+no record, an unreadable one, no `version`, an empty id; and any answer the kit
+cannot place, such as a status outside the contract.
+
+Every submitted row is therefore in exactly one of the success list
+(`created` / `updated` / `deletedIds`), `failed`, or `unresolved`.
+
+### useBulkCreateRecords
+
+```tsx
+import { useBulkCreateRecords, SFA_BULK_MAX_ROWS } from '@geniee-inc/sfa-kit';
+
+const { bulkCreate, created, failed, isLoading, error } =
+  useBulkCreateRecords('opportunity');
+
+try {
+  await bulkCreate([
+    { company_id: 'cmp_88', stage: '3', amount: 5300000 },
+    { company_id: 'cmp_90', stage: '1', amount: 120000 },
+  ]);
+} catch {
+  // the whole call was rejected; `error` holds it for rendering
+}
+```
+
+Each row is a field map, like a single create.
+
+- `created` — the records that were written, in submission order
+
+Returns `{ bulkCreate, results, created, failed, unresolved, isLoading, error, reset }`.
+
+### useBulkUpdateRecords
+
+The save action of a grid edit: each row carries its own version.
+
+```tsx
+const { bulkUpdate, updated, conflicts, failed } =
+  useBulkUpdateRecords('opportunity');
+
+await bulkUpdate([
+  { id: 'opp_1', version: 'v1', fields: { stage: '4' } },
+  { id: 'opp_2', version: 'v7', fields: { amount: 90000 } },
+]);
+```
+
+A row whose `version` is stale comes back as `conflict` and is **left
+unchanged**, while the rest of the batch applies. Its result carries the
+server's current `record`, which is what the reader reconciles against — retry
+with the version that record reports, never by re-sending the stale one.
+
+- `updated` — the records as they now stand on the server, in submission order
+- `conflicts` — the rows a concurrent write got to first, each with the current
+  `record`. Also present in `failed`
+
+Returns the same shape, with `updated` and `conflicts` in place of `created`.
+
+### useBulkDeleteRecords
+
+```tsx
+const { bulkDelete, deletedIds, conflicts, failed } =
+  useBulkDeleteRecords('opportunity');
+
+await bulkDelete([
+  { id: 'opp_1', version: 'v1' },
+  { id: 'opp_2', version: 'v7' },
+]);
+```
+
+The same optimistic concurrency: a stale row is reported as `conflict` and
+stays in place. A partly failed batch has already removed records, so reconcile
+from `deletedIds` rather than assume the whole selection is gone.
+
+- `deletedIds` — what was actually removed, in submission order. A delete
+  answers with no record, so the id comes from the row itself
+
+Returns the same shape, with `deletedIds` and `conflicts` in place of
+`created`.
+
 ### useDescribe
 
 Discovers object schema — fields, types, relationships, permissions. Use this to build dynamic UIs that adapt to any object.
@@ -302,6 +459,8 @@ const record = await client.get('companies', 'abc123');
 const list = await client.list('companies', { limit: 10 });
 ```
 
+`SfaClientInterface` describes the shape of the client the provider hands out — it is not an extension point. Methods are added to it as the API grows, so implementing it yourself would break on any release that covers a new endpoint. Take the client from `useSfaClient()`; to stand one in for a test, mock the hook rather than the interface.
+
 ## Record shape
 
 All hooks return records in a normalized shape:
@@ -728,6 +887,7 @@ Returns `null` for unsupported collections (e.g. `schedules`).
 - Do NOT hardcode `defaultOrganizationId` as a number literal in JSX. Use `Number(process.env.NEXT_PUBLIC_DEFAULT_ORG_ID)` and set the value in `.env`.
 - Do NOT embed service account credentials in generated page source. Discovery credentials (used to query the schema at build time) must never appear in deployed code.
 - Do NOT call the API directly with fetch. Use the provided hooks or `useSfaClient()`.
+- Do NOT loop single writes to save many rows. Use the bulk hooks: a loop sends one request per row, and a failure part-way through leaves the caller with no report of what landed.
 - Do NOT add Route Handlers (app/api/) for SFA data. The kit calls the API from the browser.
 - Do NOT hardcode API base URLs, API keys, or credentials anywhere.
 - Do NOT add record detail links automatically. They are opt-in: generate them only when the user asks (e.g. "make the names clickable", "add links to records"), or ask the user for confirmation before adding them. In standalone preview mode, links are unavailable (`useRecordDetailUrl` returns `null`). The `schedules` collection does not have a standard record detail page; if asked, tell the user that schedule links are not yet supported.

package/package.json

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

package/src/index.d.ts

@@ -15,6 +15,12 @@ export { useObjectCatalog } from './lib/hooks/useObjectCatalog';
 export { useFieldTypes } from './lib/hooks/useFieldTypes';
 export { useCreateRecord } from './lib/hooks/useCreateRecord';
 export type { UseCreateRecordResult } from './lib/hooks/useCreateRecord';
+export { useBulkCreateRecords } from './lib/hooks/useBulkCreateRecords';
+export type { UseBulkCreateRecordsResult } from './lib/hooks/useBulkCreateRecords';
+export { useBulkUpdateRecords } from './lib/hooks/useBulkUpdateRecords';
+export type { UseBulkUpdateRecordsResult } from './lib/hooks/useBulkUpdateRecords';
+export { useBulkDeleteRecords } from './lib/hooks/useBulkDeleteRecords';
+export type { UseBulkDeleteRecordsResult } from './lib/hooks/useBulkDeleteRecords';
 export { useUpdateRecord } from './lib/hooks/useUpdateRecord';
 export type { UseUpdateRecordResult, SfaConflictDetail, } from './lib/hooks/useUpdateRecord';
 export { useDeleteRecord } from './lib/hooks/useDeleteRecord';
@@ -27,7 +33,8 @@ export { RecordList } from './lib/components/RecordList';
 export { ErrorBoundary } from './lib/components/ErrorBoundary';
 export { EmptyState } from './lib/components/EmptyState';
 export { FetchErrorState } from './lib/components/FetchErrorState';
-export type { SfaAuth, SfaApiMode, SfaClientConfig, SfaRecord, SfaListResponse, SfaListParams, SfaFieldValue, SfaFieldKind, SfaFieldValueMapping, FieldGroupSpec, FieldGroupLayout, SfaFieldDescriptor, SfaFieldOption, SfaRelationDescriptor, SfaObjectDetail, SfaObjectSummary, SfaObjectCatalog, SfaObjectPermissions, SfaObjectOrigin, SfaRelationshipKind, SfaCardinality, SfaDescribeResult, SfaFieldTypeDescriptor, SfaFieldTypeCatalog, SfaFilterOperator, SfaCreateOptions, SfaFieldError, } from './lib/provider/types';
+export type { SfaAuth, SfaApiMode, SfaClientConfig, SfaRecord, SfaListResponse, SfaListParams, SfaFieldValue, SfaFieldKind, SfaFieldValueMapping, FieldGroupSpec, FieldGroupLayout, SfaFieldDescriptor, SfaFieldOption, SfaRelationDescriptor, SfaObjectDetail, SfaObjectSummary, SfaObjectCatalog, SfaObjectPermissions, SfaObjectOrigin, SfaRelationshipKind, SfaCardinality, SfaDescribeResult, SfaFieldTypeDescriptor, SfaFieldTypeCatalog, SfaFilterOperator, SfaCreateOptions, SfaFieldError, SfaBulkRowStatus, SfaBulkRowResult, SfaBulkRowError, SfaBulkUpdateRow, SfaBulkDeleteRow, } from './lib/provider/types';
+export { SFA_BULK_MAX_ROWS } from './lib/provider/SfaClient';
 export type { SfaSession, AuthResult, OrganizationChoice, } from './lib/auth/types';
 export { buildRecordDetailUrl, resolveHostOrigin, } from './lib/navigation/record-detail-url';
 export type { RecordDetailUrlParams, RecordDetailLink, } from './lib/navigation/record-detail-url';

package/src/index.js

@@ -11,6 +11,9 @@ export { useDescribe } from './lib/hooks/useDescribe';
 export { useObjectCatalog } from './lib/hooks/useObjectCatalog';
 export { useFieldTypes } from './lib/hooks/useFieldTypes';
 export { useCreateRecord } from './lib/hooks/useCreateRecord';
+export { useBulkCreateRecords } from './lib/hooks/useBulkCreateRecords';
+export { useBulkUpdateRecords } from './lib/hooks/useBulkUpdateRecords';
+export { useBulkDeleteRecords } from './lib/hooks/useBulkDeleteRecords';
 export { useUpdateRecord } from './lib/hooks/useUpdateRecord';
 export { useDeleteRecord } from './lib/hooks/useDeleteRecord';
 export { useRelatedRecords, RelationNotFoundError, resolveRelation, buildRelationFilter, } from './lib/hooks/useRelatedRecords';
@@ -20,5 +23,6 @@ export { RecordList } from './lib/components/RecordList';
 export { ErrorBoundary } from './lib/components/ErrorBoundary';
 export { EmptyState } from './lib/components/EmptyState';
 export { FetchErrorState } from './lib/components/FetchErrorState';
+export { SFA_BULK_MAX_ROWS } from './lib/provider/SfaClient';
 export { buildRecordDetailUrl, resolveHostOrigin, } from './lib/navigation/record-detail-url';
 export { useRecordDetailUrl } from './lib/hooks/useRecordDetailUrl';

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

@@ -5,6 +5,7 @@
 export interface StandalonePreviewState {
     readonly object_key: string;
     readonly record_id?: string;
+    readonly list_id?: string;
 }
 export interface StandalonePreviewControls {
     readonly state: StandalonePreviewState | null;

package/src/lib/auth/embed-protocol.d.ts

@@ -15,6 +15,7 @@ export interface EmbedReadyMessage {
 export interface EmbedContext {
     readonly object_key: string;
     readonly record_id?: string;
+    readonly list_id?: string;
 }
 /** Sent by the host to deliver a single-use exchange code. */
 export interface EmbedCodeMessage {

package/src/lib/auth/embed-protocol.js

@@ -33,7 +33,8 @@ export function parseInboundMessage(event, trustedOrigin) {
             const ctx = rawContext;
             if (typeof ctx['object_key'] === 'string' &&
                 ctx['object_key'].length > 0) {
-                const context = { object_key: ctx['object_key'] };
+                const context = Object.assign({ object_key: ctx['object_key'] }, (typeof ctx['list_id'] === 'string' &&
+                    ctx['list_id'].length > 0 && { list_id: ctx['list_id'] }));
                 if (typeof ctx['record_id'] === 'string' &&
                     ctx['record_id'].length > 0) {
                     return Object.assign(Object.assign({}, result), { context: Object.assign(Object.assign({}, context), { record_id: ctx['record_id'] }) });

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

@@ -0,0 +1,30 @@
+import type { SfaBulkRowResult, SfaBulkRowStatus } from '../provider/types';
+export interface BulkRowSplit<T> {
+    /** What each row that landed produced, in submission order. */
+    readonly landed: readonly T[];
+    /** May already be applied. Re-read; retrying is what writes a duplicate. */
+    readonly unresolved: readonly SfaBulkRowResult[];
+    /** The rows a concurrent write got to first. Also present in `failed`. */
+    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`.
+     */
+    readonly failed: readonly SfaBulkRowResult[];
+}
+/**
+ * @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 —
+ * `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.
+ *
+ * NOTE: one pass, so a row that claims success without carrying it falls into
+ * `unresolved` rather than out of every list. Order follows `results`, which
+ * the client has already aligned with the request.
+ */
+export declare function splitBulkRows<T>(results: readonly SfaBulkRowResult[], landedStatus: SfaBulkRowStatus, read: (row: SfaBulkRowResult) => T | null): BulkRowSplit<T>;

package/src/lib/hooks/splitBulkRows.js

@@ -0,0 +1,42 @@
+/** The outcomes that mean the row did not apply, so sending it again is safe. */
+const RETRYABLE_STATUSES = new Set([
+    'conflict',
+    'invalid',
+    'not_attempted',
+]);
+/**
+ * @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 —
+ * `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.
+ *
+ * NOTE: one pass, so a row that claims success without carrying it falls into
+ * `unresolved` rather than out of every list. Order follows `results`, which
+ * the client has already aligned with the request.
+ */
+export function splitBulkRows(results, landedStatus, read) {
+    const landed = [];
+    const unresolved = [];
+    const conflicts = [];
+    const failed = [];
+    for (const row of results) {
+        const value = row.status === landedStatus ? read(row) : null;
+        if (value != null) {
+            landed.push(value);
+            continue;
+        }
+        if (RETRYABLE_STATUSES.has(row.status)) {
+            failed.push(row);
+            if (row.status === 'conflict')
+                conflicts.push(row);
+            continue;
+        }
+        unresolved.push(row);
+    }
+    return { landed, unresolved, conflicts, failed };
+}

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

@@ -0,0 +1,56 @@
+import type { SfaBulkRowResult, SfaRecord } from '../provider/types';
+export interface UseBulkCreateRecordsResult {
+    /**
+     * Call to create many records at once. Each entry is a field map, like a
+     * single create. Resolves with one result per submitted row.
+     */
+    readonly bulkCreate: (rows: readonly Record<string, unknown>[]) => Promise<readonly SfaBulkRowResult[]>;
+    /**
+     * Every row's outcome from the last call, aligned to the submitted rows by
+     * `index`. Empty before the first call, and empty again once `collection`
+     * or the provider's client changes — and it stays that way if they change
+     * back: these outcomes describe the object they were written for, on the
+     * visit they were written on.
+     */
+    readonly results: readonly SfaBulkRowResult[];
+    /** The records that were created, in submission order. */
+    readonly created: readonly SfaRecord[];
+    /**
+     * 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.
+     */
+    readonly failed: readonly SfaBulkRowResult[];
+    /**
+     * The rows that may already be created but cannot be reported either way.
+     * They keep whatever `id` arrived. Re-read these; retrying one that landed
+     * writes a second record.
+     */
+    readonly unresolved: readonly SfaBulkRowResult[];
+    readonly isLoading: boolean;
+    /**
+     * Set when the whole call was rejected — row count out of range, a response
+     * that does not answer for every row, auth, or a 4xx/5xx from the API. Rows
+     * that failed individually are reported in `failed`, not here, and read-only
+     * mode throws synchronously instead: it is a provider setting, not an
+     * outcome of this call.
+     */
+    readonly error: Error | null;
+    /** Reset results and error state to initial values. */
+    readonly reset: () => void;
+}
+/**
+ * @description Imperative hook for creating many records of one object in a
+ * single call. Like the single-record hooks it does not fetch on mount.
+ *
+ * A bulk call is best-effort per row: the API answers 200 and reports each
+ * row's outcome, with no all-or-nothing mode. So a partly failed batch still
+ * created records, and their ids are only available here — which is why
+ * per-row failures are returned as data rather than thrown. `error` is for
+ * 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.
+ */
+export declare function useBulkCreateRecords(collection: string): UseBulkCreateRecordsResult;

package/src/lib/hooks/useBulkCreateRecords.js

@@ -0,0 +1,41 @@
+import { useMemo } from 'react';
+import { splitBulkRows } from './splitBulkRows';
+import { useBulkWrite } from './useBulkWrite';
+/** Module level so its identity never changes: `run` stays stable. */
+const sendBulkCreate = (client, collection, rows) => client.bulkCreate(collection, rows);
+/**
+ * @description Imperative hook for creating many records of one object in a
+ * single call. Like the single-record hooks it does not fetch on mount.
+ *
+ * A bulk call is best-effort per row: the API answers 200 and reports each
+ * row's outcome, with no all-or-nothing mode. So a partly failed batch still
+ * created records, and their ids are only available here — which is why
+ * per-row failures are returned as data rather than thrown. `error` is for
+ * 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.
+ */
+export function useBulkCreateRecords(collection) {
+    const { run, results, isLoading, error, reset } = useBulkWrite(collection, sendBulkCreate);
+    /**
+     * Split here rather than in the caller so a grid does not have to know which
+     * statuses count as failure. A create cannot come back as `conflict`, so
+     * only the two lists are exposed.
+     *
+     * 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, 'created', row => row.record), [results]);
+    return {
+        bulkCreate: run,
+        results,
+        created: split.landed,
+        failed: split.failed,
+        unresolved: split.unresolved,
+        isLoading,
+        error,
+        reset,
+    };
+}

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

@@ -0,0 +1,50 @@
+import type { SfaBulkDeleteRow, SfaBulkRowResult } from '../provider/types';
+export interface UseBulkDeleteRecordsResult {
+    /**
+     * Call to delete many records at once. Each row carries the `version` last
+     * read for it. Resolves with one result per submitted row.
+     */
+    readonly bulkDelete: (rows: readonly SfaBulkDeleteRow[]) => Promise<readonly SfaBulkRowResult[]>;
+    /**
+     * Every row's outcome from the last call, aligned to input by `index`. Empty
+     * again once `collection` or the provider's client changes, and it stays
+     * that way if they change back: these outcomes describe the object they were
+     * written for, on the visit they were written on.
+     */
+    readonly results: readonly SfaBulkRowResult[];
+    /** The ids that were removed, in submission order. */
+    readonly deletedIds: readonly string[];
+    /**
+     * The rows a concurrent write got to first. Each carries the server's
+     * current `record`, so the reader can see what changed before deciding
+     * whether it still wants the record gone.
+     */
+    readonly conflicts: readonly SfaBulkRowResult[];
+    /** The rows still in place that can be sent again, conflicts included. */
+    readonly failed: readonly SfaBulkRowResult[];
+    /**
+     * The rows that may already be removed but cannot be reported either way.
+     * Re-read these rather than sending them again.
+     */
+    readonly unresolved: readonly SfaBulkRowResult[];
+    readonly isLoading: boolean;
+    /**
+     * Set when the whole call was rejected — row count out of range, a response
+     * that does not answer for every row, auth, a 4xx/5xx. Rows that failed
+     * individually are in `failed`, and read-only mode throws synchronously
+     * instead: it is a provider setting, not an outcome of this call.
+     */
+    readonly error: Error | null;
+    /** Reset results and error state to initial values. */
+    readonly reset: () => void;
+}
+/**
+ * @description Imperative hook for deleting many records of one object in a
+ * single call.
+ *
+ * Best-effort per row: a stale row comes back as `conflict` and is left in
+ * 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.
+ */
+export declare function useBulkDeleteRecords(collection: string): UseBulkDeleteRecordsResult;

package/src/lib/hooks/useBulkDeleteRecords.js

@@ -0,0 +1,36 @@
+import { useMemo } from 'react';
+import { splitBulkRows } from './splitBulkRows';
+import { useBulkWrite } from './useBulkWrite';
+/** Module level so its identity never changes: `run` stays stable. */
+const sendBulkDelete = (client, collection, rows) => client.bulkDelete(collection, rows);
+/**
+ * @description Imperative hook for deleting many records of one object in a
+ * single call.
+ *
+ * Best-effort per row: a stale row comes back as `conflict` and is left in
+ * 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.
+ */
+export function useBulkDeleteRecords(collection) {
+    const { run, results, isLoading, error, reset } = useBulkWrite(collection, sendBulkDelete);
+    /**
+     * NOTE: a delete answers with no record, so the id comes from the row
+     * itself — the contract guarantees `id` is present for delete.
+     *
+     * 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, 'deleted', row => row.id), [results]);
+    return {
+        bulkDelete: run,
+        results,
+        deletedIds: split.landed,
+        conflicts: split.conflicts,
+        failed: split.failed,
+        unresolved: split.unresolved,
+        isLoading,
+        error,
+        reset,
+    };
+}

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

@@ -0,0 +1,55 @@
+import type { SfaBulkRowResult, SfaBulkUpdateRow, SfaRecord } from '../provider/types';
+export interface UseBulkUpdateRecordsResult {
+    /**
+     * Call to update many records at once. Each row carries its own `version`
+     * for optimistic concurrency. Resolves with one result per submitted row.
+     */
+    readonly bulkUpdate: (rows: readonly SfaBulkUpdateRow[]) => Promise<readonly SfaBulkRowResult[]>;
+    /**
+     * Every row's outcome from the last call, aligned to input by `index`. Empty
+     * again once `collection` or the provider's client changes, and it stays
+     * that way if they change back: these outcomes describe the object they were
+     * written for, on the visit they were written on.
+     */
+    readonly results: readonly SfaBulkRowResult[];
+    /** The records as they now stand on the server, in submission order. */
+    readonly updated: readonly SfaRecord[];
+    /**
+     * The rows a concurrent write got to first. Each carries the server's
+     * current `record`, which is what the reader has to reconcile against
+     * before retrying with the version it reports. If that record arrives
+     * 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. */
+    readonly failed: readonly SfaBulkRowResult[];
+    /**
+     * The rows that may already be applied but cannot be reported either way.
+     * Re-read these rather than sending them again.
+     */
+    readonly unresolved: readonly SfaBulkRowResult[];
+    readonly isLoading: boolean;
+    /**
+     * Set when the whole call was rejected — row count out of range, a response
+     * that does not answer for every row, auth, a 4xx/5xx. Rows that failed
+     * individually are in `failed`, and read-only mode throws synchronously
+     * instead: it is a provider setting, not an outcome of this call.
+     */
+    readonly error: Error | null;
+    /** Reset results and error state to initial values. */
+    readonly reset: () => void;
+}
+/**
+ * @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 declare function useBulkUpdateRecords(collection: string): UseBulkUpdateRecordsResult;

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,
+    };
+}