@sanity-labs/client-fake-for-test 0.11.0 → 0.13.0

package/dist/index.d.cts

@@ -38,7 +38,7 @@ export declare function applyPatchOps(
  */
 export declare function applyPerspective(
   docs: readonly SanityDocument[],
-  perspective: Perspective,
+  requested: Perspective,
 ): SanityDocument[];
 
 /**
@@ -61,6 +61,8 @@ export declare interface CallRecord {
   tag?: string | null;
   projectId: string;
   dataset: string;
+  /** The resource the call targeted, on a `resource`-configured handle. */
+  resource?: TestClientResource;
 }
 
 /** Outcome of a recorded call, reported once a (possibly async) result is known. */
@@ -105,6 +107,27 @@ export declare interface CreateTestClientOptions {
    * pairs. Useful when workflows span multiple datasets.
    */
   datasets?: Record<string, SanityDocumentLike[]>;
+  /**
+   * Optional: seed any resource type. Keys are `"<type>:<id>"`, the
+   * `resource` config's two fields: `"media-library:ml1"`, `"canvas:c1"`,
+   * `"dashboard:d1"`, or `"dataset:<projectId>.<dataset>"` (the same store
+   * as `datasets["<projectId>:<dataset>"]`).
+   */
+  resources?: Record<string, SanityDocumentLike[]>;
+  /**
+   * The resource the root handle points at, named exactly as
+   * `@sanity/client`'s `resource` config names it. While set, it decides
+   * the store (over `projectId` / `dataset`), and each capability the
+   * platform lacks on that resource type answers with the platform's
+   * refusal. `withConfig({ resource })` mints siblings on other resources.
+   */
+  resource?: TestClientResource;
+  /**
+   * The organization every resource of this client belongs to — what
+   * `GET /media-libraries/<id>`, `/canvases/<id>`, `/dashboards/<id>` and
+   * `/projects/<projectId>` answer as `organizationId`.
+   */
+  organizationId?: string;
   /**
    * Opt-in access-control simulation. When set, the client exposes
    * `request({ url })` that serves `/users/me` (host-aware), the
@@ -152,12 +175,12 @@ export declare interface CreateTestClientOptions {
    */
   token?: string;
   /**
-   * Pluggable write interceptor — runs on each write through the document
-   * mutation API (create/patch/delete/transaction; not the release/version
-   * action API) before the store changes, and may throw to reject it. The
-   * client has no opinion about the policy; callers (e.g. a workflow test bench
-   * enforcing lake mutation guards) supply it. Inherited by `withConfig`
-   * siblings. See {@link MutationGuard}.
+   * Pluggable write interceptor — runs once for each document's net change in
+   * a commit. Document publish/unpublish actions expose their underlying
+   * draft/published mutations; release/version actions remain unhooked. Return
+   * denial descriptors to reject atomically with `GuardDeniedError`; a
+   * thrown callback error propagates unchanged. The client owns no policy.
+   * Inherited by `withConfig` siblings. See {@link MutationGuard}.
    */
   mutationGuard?: MutationGuard;
   /**
@@ -246,7 +269,11 @@ export declare interface DocumentBody {
   [field: string]: unknown;
 }
 
-export declare type DocumentValuePermission = "create" | "read" | "update";
+export declare type DocumentValuePermission =
+  | "create"
+  | "manage"
+  | "read"
+  | "update";
 
 /**
  * Error helpers shared across the fake.
@@ -326,11 +353,14 @@ export declare type FakeMutation =
 /**
  * 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.
+ * One `createTestClient()` call creates a registry of stores, one per
+ * resource: a `(projectId, dataset)` pair, or a Media Library, Canvas or
+ * dashboard named by `resource: { type, id }` exactly as `@sanity/client`
+ * names it. The returned client points at one of them.
+ * `withConfig({ projectId, dataset })` or `withConfig({ resource })` 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.
@@ -341,7 +371,7 @@ export declare type FakeMutation =
  *   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.
+ * - `datasets()` / `resources()` — list the stores known in this registry.
  *
  * Methods deliberately omitted:
  *
@@ -397,6 +427,61 @@ export declare interface GuardConfig {
   recorded?: Set<string>;
 }
 
+/** HTTP-shaped guard rejection matching the error exposed by `@sanity/client`. */
+export declare class GuardDeniedError extends Error {
+  readonly statusCode = 403;
+  readonly type = "guardDeniedError";
+  readonly denials: MutationGuardDenial[];
+  readonly details: GuardDeniedResponse["body"]["error"];
+  readonly response: GuardDeniedResponse;
+  constructor(denials: readonly MutationGuardDenial[]);
+}
+
+export declare interface GuardDeniedResponse {
+  body: {
+    error: {
+      type: "guardDeniedError";
+      denials: MutationGuardDenial[];
+    };
+  };
+  url: string;
+  method: "POST";
+  headers: Record<string, string>;
+  statusCode: 403;
+  statusMessage: "Forbidden";
+}
+
+/** An event as `GET <data base>/history/events/documents/<ids>` serves it. */
+export declare interface HistoryEvent {
+  type: "createLiveDocument" | "updateLiveDocument";
+  id: string;
+  documentId: string;
+  revisionId: string;
+  timestamp: string;
+  author?: string;
+}
+
+/** A transaction as `GET <data base>/history/transactions/<ids>` serves it, one per NDJSON line. */
+export declare interface HistoryTransactionRecord {
+  id: string;
+  timestamp: string;
+  author?: string;
+  mutations: (
+    | {
+        create: SanityDocument;
+      }
+    | {
+        createOrReplace: SanityDocument;
+      }
+    | {
+        delete: {
+          id: string;
+        };
+      }
+  )[];
+  documentIDs: string[];
+}
+
 export declare const isDraftId: (id: string) => boolean;
 
 export declare const isReleaseDocId: (id: string) => boolean;
@@ -416,72 +501,53 @@ export declare interface MultipleMutationResult {
 }
 
 /**
- * A pluggable write interceptor, configured via
- * `createTestClient({ mutationGuard })`. It runs on each write through the
- * document mutation API — `create` / `createOrReplace` / `createIfNotExists` /
- * `patch` / `delete` and the equivalent `transaction()` operations — and on the
- * document publish/unpublish actions (`sanity.action.document.publish` /
- * `.unpublish` via `client.action`) — before the store changes; **throw to
- * reject the write** (the throw propagates out of the client call, exactly as
- * a real lake rejection would). The release/version action API
- * (`client.releases.*`, `createVersion`, the `sanity.action.release.*` and
- * `*.version.*` action types) is **not** intercepted.
- *
- * The client itself has no opinion about *what* a guard is — it only provides
- * the seam and the before/after/identity context. Callers (e.g. a workflow test
- * bench) supply the policy: evaluate lake mutation guards, enforce field locks,
- * etc. Keeping the policy in the caller avoids duplicating guard-evaluation
- * logic the client has no business owning.
+ * Evaluates one net document change and returns every denying guard. Returning
+ * `void` allows observe-only hooks. A thrown value is a callback failure and
+ * propagates unchanged; only returned entries become {@link GuardDeniedError}.
  */
 export declare type MutationGuard = (
   context: MutationGuardContext,
-) => void | Promise<void>;
+) =>
+  | readonly MutationGuardDenial[]
+  | void
+  | Promise<readonly MutationGuardDenial[] | void>;
 
-/** The kind of write a {@link MutationGuard} is asked to vet. */
-export declare type MutationGuardAction =
-  | "create"
-  | "update"
-  | "delete"
-  | "publish"
-  | "unpublish";
+/** The Content Lake mutation actions that a {@link MutationGuard} can match. */
+export declare type MutationGuardAction = "create" | "update" | "delete";
 
-/**
- * The before/after image of a single document write, handed to a
- * {@link MutationGuard} before it is applied.
- *
- * - `before` is null on create and on a publish with no live published
- *   document; `after` is null on delete and unpublish.
- * - On publish/unpublish both images are of the *published* document —
- *   `after` on publish is the draft's content promoted onto the published id.
- * - `identity` is the acting user — the id bound to the client's token
- *   (its `accessControl.currentUser`), or undefined when the client has no
- *   identity configured.
- *
- * Treat `before`/`after` as read-only — they are the live store images, not
- * copies; a guard that mutates them corrupts the store.
- */
+/** The before/final-after image of one net document change in a commit. */
 export declare interface MutationGuardContext {
   action: MutationGuardAction;
-  before:
-    | (SanityDocumentLike & {
-        _id: string;
-        _type: string;
-      })
-    | null;
-  after:
-    | (SanityDocumentLike & {
-        _id: string;
-        _type: string;
-      })
-    | null;
+  /** Original live store image. Treat it as read-only; it is not a copy. */
+  before: Readonly<
+    SanityDocumentLike & {
+      _id: string;
+      _type: string;
+    }
+  > | null;
+  /** Final live store image. Treat it as read-only; it is not a copy. */
+  after: Readonly<
+    SanityDocumentLike & {
+      _id: string;
+      _type: string;
+    }
+  > | null;
+  /** Acting project identity, or `undefined` on an identity-free client. */
   identity: string | undefined;
 }
 
+export declare interface MutationGuardDenial {
+  guardID: string;
+  name?: string;
+}
+
 /** Append-only record of one committed transaction (a single mutation is a 1-entry transaction). */
 export declare interface MutationLogEntry {
   transactionId: string;
   projectId: string;
   dataset: string;
+  /** The resource the transaction targeted, on a `resource`-configured handle. */
+  resource?: TestClientResource;
   mutations: TxnMutation[];
   /** Request tag the commit carried, when one was passed (`null` = explicit suppression). */
   tag?: string | null;
@@ -593,7 +659,46 @@ export declare type PatchOp =
       items: unknown[];
     };
 
-export declare type Perspective = "raw" | "published" | "drafts" | string[];
+/**
+ * `raw`, `published`, `drafts`, a release stack, or a single release name
+ * (`"rSpring"`) — which the Content Lake reads as a one-release stack.
+ */
+export declare type Perspective =
+  | "raw"
+  | "published"
+  | "drafts"
+  | (string & {})
+  | string[];
+
+/** The `response` of an HTTP error, shaped like `@sanity/client`'s `HttpError["response"]`. */
+declare interface PlatformErrorResponse {
+  body: unknown;
+  url: string;
+  method: string;
+  headers: Record<string, string>;
+  statusCode: number;
+  statusMessage: string;
+}
+
+/**
+ * The platform's refusal, shaped like the `ClientError` `@sanity/client`
+ * throws for the same response: `statusCode`, `response`, `responseBody`,
+ * `details`, and a `message` derived from the body the way the client
+ * derives it.
+ */
+export declare class PlatformHttpError extends Error {
+  readonly statusCode: number;
+  readonly response: PlatformErrorResponse;
+  readonly responseBody: string;
+  readonly details: unknown;
+  constructor(args: {
+    method: string;
+    path: string;
+    statusCode: number;
+    statusMessage: string;
+    body: unknown;
+  });
+}
 
 /** One row of the `/projects/<projectId>` members response. */
 export declare interface ProjectMemberRecord {
@@ -726,6 +831,25 @@ export declare type ReleaseState =
 
 export declare type ReleaseType = "asap" | "scheduled" | "undecided";
 
+/**
+ * What the Access API (`/access/<type>/<id>/…`) answers about one actor on
+ * one resource: the roles it holds there (served by `…/users` and collected
+ * into `…/roles`) and the permissions `…/user-permissions/me` and
+ * `…/user-permissions/me/check` report, as `"<type>.<action>"` names such
+ * as `"sanity.media-library.read"`.
+ */
+export declare interface ResourceAccess {
+  roles?: NonNullable<CurrentUser["roles"]>;
+  permissions?: string[];
+}
+
+/** Resource types `@sanity/client`'s `resource` config can name (the ones staging probed). */
+export declare type ResourceType =
+  | "dataset"
+  | "media-library"
+  | "canvas"
+  | "dashboard";
+
 /** @public */
 declare interface SanityDocument {
   _id: string;
@@ -782,6 +906,7 @@ export declare const SUPPORTED_SURFACE: readonly [
   "createVersion",
   "unpublishVersion",
   "request (only with accessControl or a bound token)",
+  "getDataUrl",
   "config",
   "withConfig",
 ];
@@ -812,7 +937,8 @@ export declare interface TestClient {
    * registered token (`identities` + `token`). 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.
+   * actor. Also serves the resource's history, ACL, lookup and Access API
+   * endpoints, or the platform's refusal where the resource has none.
    */
   request?: <T>(opts: {
     url?: string;
@@ -820,6 +946,13 @@ export declare interface TestClient {
     signal?: AbortSignal;
     tag?: string | null;
   }) => Promise<T>;
+  /**
+   * `@sanity/client`'s `getDataUrl(operation, path)`: `<resource
+   * base>/<operation>/<path>` on a `resource`-configured handle,
+   * `/data/<operation>/<dataset>/<path>` otherwise. Pass the result to
+   * `request()` to reach e.g. the History API.
+   */
+  getDataUrl: (operation: string, path?: string) => string;
   create: <T extends SanityDocumentLike>(
     doc: T,
     options?: MutationOptions,
@@ -855,8 +988,9 @@ export declare interface TestClient {
    * Dispatch one or more release / version / document actions against the
    * store. Returns a synthetic `transactionId`. Multi-action arrays are
    * applied atomically — any failure rolls back the batch. The document
-   * publish/unpublish actions run through the access gate and the
-   * `mutationGuard` seam; release/version actions apply unhooked.
+   * publish/unpublish actions run through the access gate and expose their
+   * net draft/published mutations to `mutationGuard`; release/version actions
+   * apply unhooked.
    */
   action: (
     action: Action | Action[],
@@ -876,13 +1010,15 @@ export declare interface TestClient {
     publishedId: string;
   }) => Promise<ActionResult>;
   /**
-   * Current `(projectId, dataset)`, active perspective, and which API host
+   * Current `(projectId, dataset)` or `resource`, active perspective, and which API host
    * the handle models (`useProjectHostname`). `token` is present iff the
    * handle is bound to a registered identity.
    */
   config: () => {
     projectId: string;
     dataset: string;
+    /** Present iff the handle is `resource`-configured. */
+    resource?: TestClientResource;
     perspective: Perspective;
     requestTagPrefix?: string;
     token?: string;
@@ -898,6 +1034,13 @@ export declare interface TestClient {
     config: Partial<{
       projectId: string;
       dataset: string;
+      /**
+       * Point the sibling at a resource, named as `@sanity/client`'s
+       * `resource` config names it. While set, it decides the store (over
+       * `projectId` / `dataset`), as in `@sanity/client`. Pass `undefined`
+       * to drop it and address `(projectId, dataset)` again.
+       */
+      resource: TestClientResource | undefined;
       perspective: Perspective;
       /** Prefix composed with request tags and used alone for untagged requests. */
       requestTagPrefix: string;
@@ -964,6 +1107,8 @@ export declare interface TestClient {
     projectId: string;
     dataset: string;
   }[];
+  /** List every resource known in this registry — datasets as `{ type: "dataset", id: "<projectId>.<dataset>" }`. */
+  resources: () => TestClientResource[];
   /**
    * Register a handler for a `@sanity/client` member the fake doesn't
    * implement (e.g. `listen`, `assets`). Accessing that member on the
@@ -1033,9 +1178,15 @@ export declare interface TestClientAccessControl {
   grants: Grant[];
   /**
    * URL path the engine's access resolver hits to fetch grants.
-   * Defaults to `/projects/<projectId>/datasets/<dataset>/acl`.
+   * Defaults to the handle's resource ACL: `/projects/<projectId>/datasets/<dataset>/acl`,
+   * or `<resource base>/acl` on a `resource`-configured handle.
    */
   aclPath?: string;
+  /**
+   * Access API entries, keyed `"<access type>:<id>"` — `"project:<projectId>"`,
+   * `"media-library:<id>"`, `"canvas:<id>"`, `"dashboard:<id>"`. See {@link ResourceAccess}.
+   */
+  access?: Record<string, ResourceAccess>;
 }
 
 /**
@@ -1073,6 +1224,24 @@ export declare interface TestClientIdentity {
   usersByProject?: Record<string, CurrentUser>;
   /** Grants served at the ACL path and enforced on reads/writes. */
   grants: Grant[];
+  /**
+   * Access API entries, keyed `"<access type>:<id>"` (`"media-library:<id>"`,
+   * `"canvas:<id>"`, `"dashboard:<id>"`, `"project:<projectId>"`). On a
+   * non-dataset resource, an entry with `roles` makes the identity a member
+   * there. Project membership needs no entry: every identity is a member of
+   * every project with its project-scoped roles.
+   */
+  access?: Record<string, ResourceAccess>;
+}
+
+/**
+ * A resource, named exactly as `@sanity/client`'s `resource` config names
+ * it: `{ type: "media-library", id: "ml…" }`, or `{ type: "dataset", id:
+ * "<projectId>.<dataset>" }`.
+ */
+export declare interface TestClientResource {
+  type: ResourceType;
+  id: string;
 }
 
 /**