@sanity-labs/client-fake-for-test 0.12.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
@@ -330,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.
@@ -345,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:
  *
@@ -425,6 +451,37 @@ export declare interface GuardDeniedResponse {
   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;
@@ -489,6 +546,8 @@ 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;
@@ -600,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 {
@@ -733,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;
@@ -789,6 +906,7 @@ export declare const SUPPORTED_SURFACE: readonly [
   "createVersion",
   "unpublishVersion",
   "request (only with accessControl or a bound token)",
+  "getDataUrl",
   "config",
   "withConfig",
 ];
@@ -819,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;
@@ -827,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,
@@ -884,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;
@@ -906,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;
@@ -972,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
@@ -1041,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>;
 }
 
 /**
@@ -1081,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;
 }
 
 /**

package/dist/index.d.ts

@@ -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
@@ -330,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.
@@ -345,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:
  *
@@ -425,6 +451,37 @@ export declare interface GuardDeniedResponse {
   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;
@@ -489,6 +546,8 @@ 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;
@@ -600,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 {
@@ -733,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;
@@ -789,6 +906,7 @@ export declare const SUPPORTED_SURFACE: readonly [
   "createVersion",
   "unpublishVersion",
   "request (only with accessControl or a bound token)",
+  "getDataUrl",
   "config",
   "withConfig",
 ];
@@ -819,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;
@@ -827,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,
@@ -884,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;
@@ -906,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;
@@ -972,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
@@ -1041,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>;
 }
 
 /**
@@ -1081,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;
 }
 
 /**