@geniee-inc/sfa-kit 1.11.0 → 1.13.0

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

@@ -50,6 +50,15 @@ export interface SfaListResponse {
     /** Cursor for fetching the previous page (keystone cursor-based pagination). */
     readonly prevCursor?: string | null;
 }
+/**
+ * @description The shape of the client SfaProvider hands out — not an
+ * extension point.
+ *
+ * NOTE: methods are added here as the API surface grows, so this interface is
+ * not treated as a breaking change when it gains one. Consumers take the
+ * client from `useSfaClient()`; a test that needs a stand-in mocks that hook
+ * rather than implementing this.
+ */
 export interface SfaClientInterface {
     get(collection: string, recordId: string): Promise<SfaRecord>;
     list(collection: string, params?: SfaListParams): Promise<SfaListResponse>;
@@ -59,12 +68,21 @@ export interface SfaClientInterface {
     create(collection: string, fields: Record<string, unknown>, options?: SfaCreateOptions): Promise<SfaRecord>;
     update(collection: string, recordId: string, fields: Record<string, unknown>, version: string): Promise<SfaRecord>;
     delete(collection: string, recordId: string, version: string): Promise<void>;
+    bulkCreate(collection: string, rows: readonly Record<string, unknown>[]): Promise<readonly SfaBulkRowResult[]>;
+    bulkUpdate(collection: string, rows: readonly SfaBulkUpdateRow[]): Promise<readonly SfaBulkRowResult[]>;
+    bulkDelete(collection: string, rows: readonly SfaBulkDeleteRow[]): Promise<readonly SfaBulkRowResult[]>;
 }
 /**
- * @description Options for creating a record. The idempotency key prevents
- * duplicate creates if the same request is retried.
+ * @description Options for creating one record. Its only member is
+ * deprecated, so the type itself goes at the next breaking release.
  */
 export interface SfaCreateOptions {
+    /**
+     * @deprecated Accepted and ignored. Keystone never de-duplicated on
+     * `Idempotency-Key`, and SFAJAI-294 drops the header from the contract, so
+     * the kit no longer sends it. Kept only because removing it would fail the
+     * build of callers that pass it; drop it at the next breaking release.
+     */
     readonly idempotencyKey?: string;
 }
 /**
@@ -75,6 +93,70 @@ export interface SfaFieldError {
     readonly code: string;
     readonly message: string;
 }
+/**
+ * @description How one row of a bulk write ended.
+ *
+ * `conflict` means the row's `version` no longer matched, `invalid` that it
+ * failed validation. `not_attempted` means the call ran out of budget before
+ * this row started, so nothing was written and it can be sent again exactly as
+ * it was. `indeterminate` means the server cannot say whether the row applied.
+ * All are reported per row with HTTP 200 — a bulk call is best-effort and has
+ * no all-or-nothing mode.
+ *
+ * `unknown` is not sent by the API: it is what the kit reads an unrecognised
+ * status as, and what a claimed success it cannot make sense of becomes — no
+ * record, or no `version` for the next write to lock against. The row keeps
+ * its `id`, and reaches the caller in `unresolved`, never in `failed`:
+ * retrying a create that already landed writes a second record.
+ */
+export type SfaBulkRowStatus = 'created' | 'updated' | 'deleted' | 'conflict' | 'invalid' | 'not_attempted' | 'indeterminate' | 'unknown';
+/** @description One row of a bulk update: what to change and from which version. */
+export interface SfaBulkUpdateRow {
+    readonly id: string;
+    /**
+     * The version last read for this record. A mismatch makes this row a
+     * `conflict` and leaves it unchanged; the rest of the batch still applies.
+     */
+    readonly version: string;
+    /** Only the keys present are changed. */
+    readonly fields: Record<string, unknown>;
+}
+/** @description One row of a bulk delete: what to remove and from which version. */
+export interface SfaBulkDeleteRow {
+    readonly id: string;
+    /** As in an update — a stale version makes this row a `conflict`. */
+    readonly version: string;
+}
+/** @description The outcome of one submitted row, positioned by `index`. */
+export interface SfaBulkRowResult {
+    /** Zero-based position in the request, for mapping the result back to input. */
+    readonly index: number;
+    /**
+     * The record's identifier. Always present for update and delete; on create
+     * only once the row succeeded. Null when the response carried none the
+     * caller could use, which makes the row count as not landed.
+     */
+    readonly id: string | null;
+    readonly status: SfaBulkRowStatus;
+    /**
+     * On a successful create or update, the resulting record. On a conflict, the
+     * server's current state, so the caller can show what it lost to. Otherwise
+     * null — including when the response carried a record that could not be
+     * read, since an unusable record is nothing to write back or reconcile
+     * against.
+     */
+    readonly record: SfaRecord | null;
+    /** Set on `conflict` and `invalid`: the problem detail for this row. */
+    readonly error: SfaBulkRowError | null;
+}
+/** @description Why one row failed, in the same shape single writes report. */
+export interface SfaBulkRowError {
+    /** Machine-readable problem code, e.g. `version_mismatch`. */
+    readonly code: string;
+    readonly message: string;
+    /** Per-field errors when the row failed validation. */
+    readonly fieldErrors: readonly SfaFieldError[];
+}
 export interface SfaListParams {
     readonly limit?: number;
     readonly offset?: number;
@@ -83,6 +165,8 @@ export interface SfaListParams {
     readonly filter?: Record<string, unknown>;
     /** Opaque cursor for keystone cursor-based pagination. Takes precedence over offset. */
     readonly cursor?: string;
+    /** List tab pre-filter. Sent as `list_id` in the keystone query body. */
+    readonly listId?: string;
 }
 export type SfaObjectOrigin = 'standard' | 'custom';
 export type SfaRelationshipKind = 'association' | 'master_detail';

package/src/lib/version.d.ts

@@ -1 +1 @@
-export declare const SFA_KIT_VERSION = "1.11.0";
+export declare const SFA_KIT_VERSION = "1.13.0";

package/src/lib/version.js

@@ -1,3 +1,3 @@
 // このファイルは libs/sfa-kit/scripts/sync-version.cjs が生成する。
 // 手で編集しないこと。バージョンを上げるときは libs/sfa-kit/package.json を変更する。
-export const SFA_KIT_VERSION = '1.11.0';
+export const SFA_KIT_VERSION = '1.13.0';