@sanity-labs/client-fake-for-test 0.10.0 → 0.12.0

package/dist/index.d.cts

@@ -152,12 +152,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 +246,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.
@@ -397,6 +401,30 @@ 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";
+}
+
 export declare const isDraftId: (id: string) => boolean;
 
 export declare const isReleaseDocId: (id: string) => boolean;
@@ -416,67 +444,46 @@ 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;
@@ -599,6 +606,8 @@ export declare type Perspective = "raw" | "published" | "drafts" | string[];
 export declare interface ProjectMemberRecord {
   id: string;
   isRobot?: boolean;
+  /** Project-scoped roles in canonical order, independent of registration order. */
+  roles?: NonNullable<CurrentUser["roles"]>;
 }
 
 /**
@@ -853,8 +862,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[],

package/dist/index.d.ts

@@ -152,12 +152,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 +246,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.
@@ -397,6 +401,30 @@ 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";
+}
+
 export declare const isDraftId: (id: string) => boolean;
 
 export declare const isReleaseDocId: (id: string) => boolean;
@@ -416,67 +444,46 @@ 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;
@@ -599,6 +606,8 @@ export declare type Perspective = "raw" | "published" | "drafts" | string[];
 export declare interface ProjectMemberRecord {
   id: string;
   isRobot?: boolean;
+  /** Project-scoped roles in canonical order, independent of registration order. */
+  roles?: NonNullable<CurrentUser["roles"]>;
 }
 
 /**
@@ -853,8 +862,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[],