@sanity/workflow-engine-test 0.1.0 → 0.2.1

package/dist/index.d.ts

@@ -13,13 +13,17 @@ import type { OperationArgs } from "@sanity/workflow-engine";
 import { PendingEffect } from "@sanity/workflow-engine";
 import type { StartInstanceArgs } from "@sanity/workflow-engine";
 import { TaskStatus } from "@sanity/workflow-engine";
-import type { TestClient } from "@sanity-labs/client-fake-for-test";
-import type { TestClientAccessControl } from "@sanity-labs/client-fake-for-test";
 import type { WorkflowAccess } from "@sanity/workflow-engine";
 import { WorkflowEvaluation } from "@sanity/workflow-engine";
 import { WorkflowInstance } from "@sanity/workflow-engine";
 import type { WorkflowResource } from "@sanity/workflow-engine";
 
+declare type Action = ReleaseAction | VersionAction;
+
+declare interface ActionResult {
+  transactionId: string;
+}
+
 /**
  * The bench's default access state — wildcard user + wildcard
  * grants. The bench injects this as the `access` override on every
@@ -102,6 +106,26 @@ declare interface BenchState {
   grants: Grant[];
   /** Add documents to the store after construction. */
   seedDocuments: (documents: StoreDocument[]) => void;
+  /**
+   * Current bench clock reading (ISO). Wall-clock until {@link Bench.setNow}
+   * or {@link Bench.advance} freezes it. Handy for computing deadlines
+   * relative to frozen time in a test.
+   */
+  now: () => string;
+  /**
+   * Freeze the bench clock at an explicit ISO instant. Every subsequent
+   * engine call (`startInstance` / `fireAction` / `tick` / `completeEffect`
+   * / `evaluate`) sees this as `$now` and stamps it on history, so
+   * time-based `completeWhen` / `failWhen` / SLA predicates are
+   * deterministic.
+   */
+  setNow: (iso: string) => void;
+  /**
+   * Move the bench clock forward by `ms`, freezing it at
+   * `current + ms`. Re-evaluate by calling {@link Bench.tick} — `advance`
+   * itself never writes, so the timeline only progresses when you tick.
+   */
+  advance: (ms: number) => void;
 }
 
 declare type BenchTickArgs = Omit<
@@ -113,6 +137,26 @@ declare type BenchTickArgs = Omit<
   actor?: Actor;
 };
 
+/**
+ * One recorded invocation of a client method — the spy layer behind
+ * `client.calls()` / `client.callCount()`. `result` holds the resolved
+ * value (awaited, for async methods); `error` holds the thrown/rejected
+ * value. Builder-returning methods (`patch`, `transaction`) record the
+ * builder as `result`; their eventual writes show up in the mutation log.
+ */
+declare interface CallRecord {
+  /** Method name; namespace methods are dotted, e.g. `releases.create`. */
+  method: string;
+  /** Arguments as passed (stored by reference, like `vi.fn`). */
+  args: unknown[];
+  /** Resolved/returned value, set once the call settles successfully. */
+  result?: unknown;
+  /** Thrown or rejected value, set if the call failed. */
+  error?: unknown;
+  projectId: string;
+  dataset: string;
+}
+
 /**
  * Create a fresh bench. By default the bench is fully isolated — two
  * `createBench()` calls have no shared state. Pass `client` + `tags`
@@ -181,11 +225,45 @@ export declare interface CreateBenchOptions {
    * URIs read as `dataset:test:test:<docId>`.
    */
   workflowResource?: WorkflowResource;
+  /**
+   * Freeze the bench clock at this ISO instant from construction, so
+   * `$now` and every engine timestamp are deterministic. Equivalent to
+   * calling {@link Bench.setNow} immediately after `createBench`. Omit to
+   * start on the wall clock (`advance` / `setNow` can freeze it later).
+   */
+  now?: string;
+}
+
+declare interface CurrentUser {
+  id: string;
+  name?: string;
+  email?: string;
+  /** @deprecated singular `role` on legacy responses */
+  role?: string;
+  roles?: {
+    name: string;
+    title?: string;
+    description?: string;
+  }[];
 }
 
 /** Default workflow resource for benches that don't pass one. */
 export declare const DEFAULT_WORKFLOW_RESOURCE: WorkflowResource;
 
+/**
+ * Document body accepted by `version.create` / `createVersion`. The id
+ * is derived from `releaseId + publishedId` so callers may omit `_id`
+ * here. `version.replace` requires `_id` since it identifies the doc
+ * to replace.
+ */
+declare interface DocumentBody {
+  _id?: string;
+  _type: string;
+  [field: string]: unknown;
+}
+
+declare type DocumentValuePermission = "create" | "read" | "update";
+
 /** Engine-call wrappers that inject the bench-owned client + tags + access. */
 declare type EngineWrappers = {
   deployDefinitions: (
@@ -196,8 +274,96 @@ declare type EngineWrappers = {
   completeEffect: (args: BenchCompleteEffectArgs) => Promise<DispatchResult>;
   tick: (args: BenchTickArgs) => Promise<DispatchResult>;
   evaluate: (args: BenchEvaluateArgs) => Promise<WorkflowEvaluation>;
+  guardsForInstance: (instanceId: string) => Promise<MutationGuardDoc[]>;
 };
 
+/**
+ * A single mutation in the raw array form accepted by `mutate()` — the
+ * same shape `@sanity/client` accepts. The inline `patch` form mirrors
+ * the real client's keyed patch object.
+ */
+declare type FakeMutation =
+  | {
+      create: SanityDocumentLike;
+    }
+  | {
+      createOrReplace: SanityDocumentLike;
+    }
+  | {
+      createIfNotExists: SanityDocumentLike;
+    }
+  | {
+      delete: {
+        id: string;
+      };
+    }
+  | {
+      patch: {
+        id: string;
+        ifRevisionID?: string;
+        set?: Record<string, unknown>;
+        setIfMissing?: Record<string, unknown>;
+        unset?: string[];
+        inc?: Record<string, number>;
+        dec?: Record<string, number>;
+        insert?: {
+          before?: string;
+          after?: string;
+          replace?: string;
+          items: unknown[];
+        };
+      };
+    };
+
+/**
+ * Data-plane subset of `@sanity/client`'s surface, with multi-dataset support.
+ *
+ * One `createTestClient()` call creates a registry of stores keyed by
+ * `(projectId, dataset)`. The returned client points at one of them.
+ * `withConfig({ projectId, dataset })` returns a new handle into the same
+ * registry but pointing at a different store — useful for workflows where
+ * definitions live in one dataset and instances live in another.
+ *
+ * Two separate `createTestClient()` calls have separate registries, so
+ * tests stay isolated from each other.
+ *
+ * Methods not on the real client:
+ *
+ * - `seed`, `add`, `reset`, `snapshot`, `store` — bulk-load helpers,
+ *   scoped to the current dataset.
+ * - `simulateConcurrentEdit()` — force the next N revision-guarded writes
+ *   to a document to 409, for optimistic-locking retry tests.
+ * - `datasets()` — lists known dataset keys in this registry.
+ *
+ * Methods deliberately omitted:
+ *
+ * - Project / agent / asset / live / listen APIs.
+ */
+declare interface FetchOptions {
+  /** Override the client's configured perspective for this read. */
+  perspective?: Perspective;
+  /**
+   * When `false`, resolve to a {@link RawQueryResponse} (`{ query, ms,
+   * result }`) instead of the bare result — mirrors `@sanity/client`.
+   * Defaults to `true`.
+   */
+  filterResponse?: boolean;
+  /**
+   * With `filterResponse: false`, set to `false` to omit `query` from the
+   * raw response. Ignored when `filterResponse` is not `false`.
+   */
+  returnQuery?: boolean;
+  /** Accepted for signature parity; not simulated. */
+  tag?: string;
+  /** Accepted for signature parity; not simulated. */
+  signal?: AbortSignal;
+}
+
+declare interface Grant_2 {
+  filter: string;
+  permissions: DocumentValuePermission[];
+}
+
 declare type GuardHelpers = {
   /** All deployed `temp.system.guard` docs in the store. */
   listGuards: () => Promise<MutationGuardDoc[]>;
@@ -211,10 +377,11 @@ declare type GuardHelpers = {
     as?: Actor,
   ) => Promise<MutationGuardDoc[]>;
   /**
-   * Attempt a guarded write to a document — the bench's stand-in for the lake's
-   * mutation path. Evaluates deployed guards (incl. `identity()` = the actor)
-   * against the before/after image and throws `MutationGuardDeniedError` if any
-   * deny; otherwise applies the patch. OPTIMISTIC — not the lake enforcing.
+   * Write to a document through the client's enforced write seam — the bench
+   * client gates the write against deployed guards (incl. `identity()`) and
+   * throws `MutationGuardDeniedError` on denial, exactly as the lake would.
+   * `as` routes the write through a token-scoped sibling so `identity()`
+   * resolves to that actor.
    */
   editDocument: (
     documentId: string,
@@ -226,6 +393,110 @@ declare type GuardHelpers = {
   ) => Promise<StoreDocument>;
 };
 
+/** Result of a mutation when ids are requested for all affected documents. */
+declare interface MultipleMutationResult {
+  transactionId: string;
+  documentIds: string[];
+  results: {
+    id: string;
+    operation: MutationOperation;
+  }[];
+}
+
+/** Append-only record of one committed transaction (a single mutation is a 1-entry transaction). */
+declare interface MutationLogEntry {
+  transactionId: string;
+  projectId: string;
+  dataset: string;
+  mutations: TxnMutation[];
+}
+
+/** The operation recorded per affected document, matching `@sanity/client`. */
+declare type MutationOperation = "create" | "update" | "delete" | "none";
+
+declare interface MutationOptions {
+  ifRevisionId?: string;
+  /**
+   * Shape the resolved value, mirroring `@sanity/client`:
+   * - default → the mutated document
+   * - `returnDocuments: false` → an id-shaped mutation result
+   *   ({@link SingleMutationResult} / {@link MultipleMutationResult})
+   * - `returnFirst: false` with documents → an array
+   *
+   * The static return type reflects the default (the document); pass a
+   * type argument or cast when requesting an id-shaped result.
+   */
+  returnDocuments?: boolean;
+  returnFirst?: boolean;
+  /** Override the synthetic transaction id used in the result and log. */
+  transactionId?: string;
+  /** When `true`, validate + shape the result but don't persist. */
+  dryRun?: boolean;
+  /** Accepted for signature parity; not simulated. */
+  visibility?: "sync" | "async" | "deferred";
+  /** Accepted for signature parity; not simulated. */
+  autoGenerateArrayKeys?: boolean;
+  /** Accepted for signature parity; not simulated. */
+  tag?: string;
+}
+
+declare interface PatchHandle {
+  set: (props: Record<string, unknown>) => PatchHandle;
+  setIfMissing: (props: Record<string, unknown>) => PatchHandle;
+  unset: (paths: string[]) => PatchHandle;
+  inc: (props: Record<string, number>) => PatchHandle;
+  dec: (props: Record<string, number>) => PatchHandle;
+  insert: (
+    position: "before" | "after" | "replace",
+    anchor: string,
+    items: unknown[],
+  ) => PatchHandle;
+  ifRevisionId: (rev: string) => PatchHandle;
+  commit: () => Promise<SanityDocument>;
+  /** Test-only introspection — not on real Patch */
+  toJSON: () => {
+    id: string;
+    ops: PatchOp[];
+    ifRev?: string;
+  };
+}
+
+/**
+ * Patch operations the test client supports.
+ *
+ * Subset of `@sanity/client`'s PatchOperations. Each entry is one
+ * mutation step applied in order at commit time.
+ */
+declare type PatchOp =
+  | {
+      kind: "set";
+      props: Record<string, unknown>;
+    }
+  | {
+      kind: "setIfMissing";
+      props: Record<string, unknown>;
+    }
+  | {
+      kind: "unset";
+      paths: string[];
+    }
+  | {
+      kind: "inc";
+      props: Record<string, number>;
+    }
+  | {
+      kind: "dec";
+      props: Record<string, number>;
+    }
+  | {
+      kind: "insert";
+      position: "before" | "after" | "replace";
+      anchor: string;
+      items: unknown[];
+    };
+
+declare type Perspective = "raw" | "published" | "drafts" | string[];
+
 declare type QueryHelpers = {
   /**
    * Run an arbitrary GROQ query through `workflow.query`. The query MUST
@@ -310,6 +581,134 @@ declare type ReadHelpers = {
   snapshot: () => readonly StoreDocument[];
 };
 
+declare type ReleaseAction =
+  | {
+      actionType: "sanity.action.release.create";
+      releaseId: string;
+      metadata?: Partial<ReleaseMetadata>;
+    }
+  | {
+      actionType: "sanity.action.release.edit";
+      releaseId: string;
+      patch: {
+        set?: Record<string, unknown>;
+        unset?: string[];
+      };
+    }
+  | {
+      actionType: "sanity.action.release.schedule";
+      releaseId: string;
+      publishAt: string;
+    }
+  | {
+      actionType: "sanity.action.release.unschedule";
+      releaseId: string;
+    }
+  | {
+      actionType: "sanity.action.release.publish";
+      releaseId: string;
+    }
+  | {
+      actionType: "sanity.action.release.archive";
+      releaseId: string;
+    }
+  | {
+      actionType: "sanity.action.release.unarchive";
+      releaseId: string;
+    }
+  | {
+      actionType: "sanity.action.release.delete";
+      releaseId: string;
+    };
+
+declare interface ReleaseDocument extends SanityDocument {
+  _type: "system.release";
+  name: string;
+  state: ReleaseState;
+  metadata: ReleaseMetadata;
+  publishAt?: string;
+}
+
+declare interface ReleaseMetadata {
+  title?: string;
+  description?: string;
+  releaseType?: ReleaseType;
+  intendedPublishAt?: string;
+}
+
+declare interface ReleasesHandle {
+  create: (params: {
+    releaseId: string;
+    metadata?: Partial<ReleaseMetadata>;
+  }) => Promise<
+    ActionResult & {
+      releaseId: string;
+      metadata: ReleaseMetadata;
+    }
+  >;
+  edit: (params: {
+    releaseId: string;
+    patch: {
+      set?: Record<string, unknown>;
+      unset?: string[];
+    };
+  }) => Promise<ActionResult>;
+  get: (params: { releaseId: string }) => Promise<ReleaseDocument | undefined>;
+  fetchDocuments: (params: { releaseId: string }) => Promise<SanityDocument[]>;
+  schedule: (params: {
+    releaseId: string;
+    publishAt: string;
+  }) => Promise<ActionResult>;
+  unschedule: (params: { releaseId: string }) => Promise<ActionResult>;
+  publish: (params: { releaseId: string }) => Promise<ActionResult>;
+  archive: (params: { releaseId: string }) => Promise<ActionResult>;
+  unarchive: (params: { releaseId: string }) => Promise<ActionResult>;
+  delete: (params: { releaseId: string }) => Promise<ActionResult>;
+}
+
+declare type ReleaseState = "active" | "scheduled" | "published" | "archived";
+
+declare type ReleaseType = "asap" | "scheduled" | "undecided";
+
+/** @public */
+declare interface SanityDocument {
+  _id: string;
+  _type: string;
+  _createdAt: string;
+  _updatedAt: string;
+  _rev: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Similar to `SanityDocument` but only requires the `_id` and `_type`
+ *
+ * @see SanityDocument
+ *
+ * @public
+ */
+declare interface SanityDocumentLike {
+  _id: string;
+  _type: string;
+  _createdAt?: string;
+  _updatedAt?: string;
+  _rev?: string;
+  _system?: {
+    delete?: boolean;
+  };
+  [key: string]: unknown;
+}
+
+/** Result of a mutation when `returnFirst` resolves true and ids are requested. */
+declare interface SingleMutationResult {
+  transactionId: string;
+  documentId: string;
+  results: {
+    id: string;
+    operation: MutationOperation;
+  }[];
+}
+
 /** A document as stored in the bench's fake lake. */
 declare type StoreDocument = {
   _id: string;
@@ -317,6 +716,312 @@ declare type StoreDocument = {
   [key: string]: unknown;
 };
 
+declare interface SystemFields {
+  _rev: string;
+  _createdAt: string;
+  _updatedAt: string;
+}
+
+declare interface TestClient {
+  fetch: <T = unknown>(
+    query: string,
+    params?: Record<string, unknown>,
+    options?: FetchOptions,
+  ) => Promise<T>;
+  getDocument: <T = SanityDocument>(
+    id: string,
+    options?: FetchOptions,
+  ) => Promise<T | undefined>;
+  getDocuments: <T = SanityDocument>(
+    ids: string[],
+    options?: FetchOptions,
+  ) => Promise<(T | null)[]>;
+  /**
+   * Sanity-style HTTP request hook. Present iff the client was
+   * created with `accessControl`. The engine's access resolver pokes
+   * `/users/me` and the configured ACL path through this — without it
+   * the engine throws on any verb that needs an actor (which is the
+   * cue for the bench to supply an `access` override).
+   *
+   * Test cases that want to exercise the engine's token-resolution
+   * path should configure `accessControl`; cases that want bench-style
+   * always-allow should leave it off and pass `access` through the
+   * bench.
+   */
+  request?: <T>(opts: {
+    url?: string;
+    uri?: string;
+    signal?: AbortSignal;
+    tag?: string;
+  }) => Promise<T>;
+  create: <T extends SanityDocumentLike>(
+    doc: T,
+    options?: MutationOptions,
+  ) => Promise<T & SystemFields>;
+  createOrReplace: <T extends SanityDocumentLike>(
+    doc: T,
+    options?: MutationOptions,
+  ) => Promise<T & SystemFields>;
+  createIfNotExists: <T extends SanityDocumentLike>(
+    doc: T,
+    options?: MutationOptions,
+  ) => Promise<T & SystemFields>;
+  delete: (
+    id: string,
+    options?: MutationOptions,
+  ) => Promise<{
+    _id: string;
+  } | null>;
+  patch: (documentId: string) => PatchHandle;
+  transaction: () => TransactionHandle;
+  /**
+   * Apply a batch of mutations in the raw array form (or a `patch()` /
+   * `transaction()` builder) — mirrors `@sanity/client`'s `mutate()`.
+   * Atomic: any failure rolls the whole batch back. The resolved shape
+   * follows `options.returnDocuments` / `returnFirst` exactly like the
+   * real client (default → {@link MultipleMutationResult}).
+   */
+  mutate: (
+    operations: FakeMutation[] | PatchHandle | TransactionHandle,
+    options?: TxnCommitOptions,
+  ) => Promise<TxnCommitResult>;
+  /**
+   * Dispatch one or more release / version actions against the store.
+   * Returns a synthetic `transactionId`. Multi-action arrays are applied
+   * atomically — any failure rolls back the batch.
+   */
+  action: (action: Action | Action[]) => Promise<ActionResult>;
+  /** Helpers mirroring `@sanity/client`'s `client.releases.*` surface. */
+  releases: ReleasesHandle;
+  /** Helper for `sanity.action.document.version.create`. */
+  createVersion: (params: {
+    releaseId: string;
+    publishedId: string;
+    document: DocumentBody;
+  }) => Promise<ActionResult>;
+  /** Helper for `sanity.action.document.version.unpublish`. */
+  unpublishVersion: (params: {
+    releaseId: string;
+    publishedId: string;
+  }) => Promise<ActionResult>;
+  /** Current `(projectId, dataset)` and active perspective. */
+  config: () => {
+    projectId: string;
+    dataset: string;
+    perspective: Perspective;
+  };
+  /**
+   * Return a new client handle pointing at a different `(projectId, dataset)`
+   * within the SAME backing registry. Either field can be omitted to keep
+   * the current value. Two clients produced by `withConfig` see each
+   * other's writes if they point at the same `(projectId, dataset)`.
+   */
+  withConfig: (
+    config: Partial<{
+      projectId: string;
+      dataset: string;
+      perspective: Perspective;
+      /**
+       * Rebind the acting identity (and its grants) on a sibling that shares
+       * the same store — the test analogue of a token-scoped client. Lets two
+       * actors write the same dataset, e.g. for `identity()`-based guards.
+       */
+      accessControl: TestClientAccessControl;
+    }>,
+  ) => TestClient;
+  /** Replace the current dataset with the given documents. */
+  seed: (documents: SanityDocumentLike[]) => void;
+  /** Add documents to the current dataset without dropping existing ones. */
+  add: (documents: SanityDocumentLike[]) => void;
+  /** Drop all documents in the current dataset. */
+  reset: () => void;
+  /** Read-only snapshot of all documents in the current dataset. */
+  snapshot: () => readonly SanityDocument[];
+  /** Direct store access for the current dataset. */
+  store: () => TestStore;
+  /**
+   * Simulate `count` concurrent edits to `id` in the current dataset: the
+   * next `count` revision-guarded mutations (those passing `ifRevisionId`)
+   * to that document throw a 409-shaped conflict, as if another client
+   * committed between the caller's read and write. Lets a test exercise
+   * optimistic-locking retry paths deterministically, without timing or
+   * interleaving. Mutations that don't pass `ifRevisionId` are unaffected.
+   */
+  simulateConcurrentEdit: (id: string, count?: number) => void;
+  /** List `(projectId, dataset)` pairs known in this registry. */
+  datasets: () => {
+    projectId: string;
+    dataset: string;
+  }[];
+  /**
+   * Register a handler for a `@sanity/client` member the fake doesn't
+   * implement (e.g. `listen`, `assets`). Accessing that member on the
+   * client then returns the handler instead of throwing the
+   * "not implemented" guard error. Shared across sibling `withConfig`
+   * handles. Stubs fill gaps only — they don't shadow implemented methods.
+   */
+  stub: (name: string, handler: unknown) => void;
+  /** The currently-registered stubs, keyed by member name. */
+  stubs: () => Record<string, unknown>;
+  /**
+   * Every mutation committed through this client's registry, flattened
+   * and in order — `create` / `createOrReplace` / `createIfNotExists` /
+   * `delete` / `patch`, whether issued directly, via `transaction()`, or
+   * via `mutate()`. The spy hook for "assert exactly what writes my code
+   * submitted".
+   */
+  mutations: () => TxnMutation[];
+  /**
+   * Every committed transaction, in order. A direct mutation is recorded
+   * as a one-mutation transaction. Each entry carries its synthetic
+   * `transactionId` and the `(projectId, dataset)` it targeted.
+   */
+  transactions: () => MutationLogEntry[];
+  /** Clear the recorded mutation / transaction log. */
+  clearLog: () => void;
+  /**
+   * Every recorded method call, in order — the spy layer for "was `fetch`
+   * called, how many times, and with what params". Records the
+   * `@sanity/client`-surface methods (`fetch`, `getDocument`, `create`,
+   * `patch`, `mutate`, `releases.*`, …), not the test-only helpers.
+   * Pass a method name to filter (e.g. `calls("fetch")`); namespace
+   * methods are dotted (`calls("releases.create")`). Shared across
+   * `withConfig` siblings.
+   */
+  calls: (method?: string) => CallRecord[];
+  /** Number of recorded calls, optionally filtered by method name. */
+  callCount: (method?: string) => number;
+  /** Clear the recorded call log. */
+  clearCalls: () => void;
+}
+
+declare interface TestClientAccessControl {
+  /** What `client.request({ url: "/users/me" })` returns. */
+  currentUser: CurrentUser;
+  /** What `client.request({ url: aclPath })` returns. */
+  grants: Grant_2[];
+  /**
+   * URL path the engine's access resolver hits to fetch grants.
+   * Defaults to `/projects/<projectId>/datasets/<dataset>/acl`.
+   */
+  aclPath?: string;
+}
+
+/**
+ * In-memory document store backing a TestClient. Closure-scoped — created
+ * fresh per test, no global state.
+ *
+ * The shape mirrors what `groq-js` evaluates against: an array of
+ * documents. Internally we keep a Map by `_id` for O(1) lookup, and
+ * project to an array on each query.
+ */
+declare interface TestStore {
+  /** Replace the entire dataset with the given documents. Existing docs are dropped. */
+  seed: (documents: SanityDocumentLike[]) => void;
+  /** Add documents without dropping existing ones. Conflicts (same _id) overwrite. */
+  add: (documents: SanityDocumentLike[]) => void;
+  /** Remove all documents. */
+  reset: () => void;
+  /** All documents as an array, in insertion order. */
+  all: () => SanityDocument[];
+  /** Get one document by _id, or undefined. */
+  get: (id: string) => SanityDocument | undefined;
+  /** Insert a fully-formed document by _id. Replaces if it already exists. */
+  put: (doc: SanityDocument) => void;
+  /** Remove a document by _id. Returns the removed doc or undefined. */
+  remove: (id: string) => SanityDocument | undefined;
+  /** Snapshot of all docs, useful for assertions. */
+  snapshot: () => readonly SanityDocument[];
+}
+
+declare interface TransactionHandle {
+  create: (doc: SanityDocumentLike) => TransactionHandle;
+  createOrReplace: (doc: SanityDocumentLike) => TransactionHandle;
+  createIfNotExists: (doc: SanityDocumentLike) => TransactionHandle;
+  delete: (id: string) => TransactionHandle;
+  /** Accept either a Patch builder (drained at commit) or an inline doc id + ops. */
+  patch: (
+    documentIdOrPatch: string | PatchHandle,
+    ops?: PatchOp[],
+    ifRev?: string,
+  ) => TransactionHandle;
+  commit: (options?: TxnCommitOptions) => Promise<TxnCommitResult>;
+  /** Test-only introspection — not on real Transaction. */
+  toJSON: () => TxnMutation[];
+}
+
+declare interface TxnCommitOptions {
+  /**
+   * Shape the resolved value (mirrors `@sanity/client`):
+   * - default (both unset) → {@link MultipleMutationResult}
+   * - `returnDocuments: true` → the resulting document(s)
+   * - `returnFirst: true` with `returnDocuments` → a single document
+   * - `returnDocuments: false` → an id-shaped mutation result
+   */
+  returnDocuments?: boolean;
+  returnFirst?: boolean;
+  /** Override the synthetic transaction id (mirrors `client.transaction(undefined, { transactionId })`). */
+  transactionId?: string;
+}
+
+declare type TxnCommitResult =
+  | MultipleMutationResult
+  | SingleMutationResult
+  | SanityDocument
+  | SanityDocument[];
+
+/**
+ * A transaction collects mutations and applies them atomically at commit
+ * time. Mutations are applied in declaration order; if any one fails, the
+ * whole transaction throws and no writes land in the store.
+ *
+ * Subset of `@sanity/client`'s Transaction. Same shape, narrower surface.
+ */
+declare type TxnMutation =
+  | {
+      kind: "create";
+      doc: SanityDocumentLike;
+    }
+  | {
+      kind: "createOrReplace";
+      doc: SanityDocumentLike;
+    }
+  | {
+      kind: "createIfNotExists";
+      doc: SanityDocumentLike;
+    }
+  | {
+      kind: "delete";
+      id: string;
+    }
+  | {
+      kind: "patch";
+      documentId: string;
+      ops: PatchOp[];
+      ifRev?: string;
+    };
+
+declare type VersionAction =
+  | {
+      actionType: "sanity.action.document.version.create";
+      publishedId: string;
+      document: DocumentBody;
+      releaseId?: string;
+    }
+  | {
+      actionType: "sanity.action.document.version.replace";
+      document: SanityDocumentLike;
+    }
+  | {
+      actionType: "sanity.action.document.version.discard";
+      versionId: string;
+    }
+  | {
+      actionType: "sanity.action.document.version.unpublish";
+      versionId: string;
+      publishedId: string;
+    };
+
 /**
  * The default grants used when tests don't specify any. A single
  * permissive grant matches every document and confers all permissions.