@sanity-labs/client-fake-for-test 0.7.1 → 0.9.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-export declare type Action = ReleaseAction | VersionAction;
+export declare type Action = ReleaseAction | VersionAction | DocumentAction;
 
 /** Options for `action()`. Only `tag` is meaningful to the fake. */
 export declare interface ActionOptions {
@@ -107,8 +107,9 @@ export declare interface CreateTestClientOptions {
   datasets?: Record<string, SanityDocumentLike[]>;
   /**
    * Opt-in access-control simulation. When set, the client exposes
-   * `request({ url })` that serves `/users/me` + the configured ACL
-   * path, AND every mutation is gated through the supplied `grants`
+   * `request({ url })` that serves `/users/me` (host-aware), the
+   * configured ACL path, and `/projects/<projectId>/users/<ids>`,
+   * AND every mutation is gated through the supplied `grants`
    * — writes that the grants don't permit throw a `WriteAccessDeniedError`
    * shaped like Sanity's 403. Lets tests demonstrate the full
    * "engine soft-gate + lake hard-gate" contract end-to-end without
@@ -165,6 +166,14 @@ export declare interface CreateTestClientOptions {
    * tests stay green.
    */
   perspective?: Perspective;
+  /**
+   * Which API host the root handle models: the project host (default
+   * `true`) or the global host (`false`) — same flag as the real
+   * `createClient` config. A global-hosted handle's `/users/me` serves
+   * the identity's account-global record. `withConfig({ useProjectHostname })`
+   * mints siblings on the other host.
+   */
+  useProjectHostname?: boolean;
 }
 
 /**
@@ -202,6 +211,26 @@ export declare function defaultAclPath(
   dataset: string,
 ): string;
 
+/**
+ * Draft↔published document actions — `sanity.action.document.publish`
+ * promotes the draft onto the published id (and deletes the draft);
+ * `sanity.action.document.unpublish` retracts the published document into a
+ * draft (keeping an existing draft untouched) and deletes the published one.
+ */
+export declare type DocumentAction =
+  | {
+      actionType: "sanity.action.document.publish";
+      draftId: string;
+      publishedId: string;
+      ifDraftRevisionId?: string;
+      ifPublishedRevisionId?: string;
+    }
+  | {
+      actionType: "sanity.action.document.unpublish";
+      draftId: string;
+      publishedId: string;
+    };
+
 /**
  * Document body accepted by `version.create` / `createVersion`. The id
  * is derived from `releaseId + publishedId` so callers may omit `_id`
@@ -387,11 +416,13 @@ 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 — 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.action`, `client.releases.*`, `createVersion`) is **not**
- * intercepted.
+ * `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
@@ -404,13 +435,21 @@ export declare type MutationGuard = (
 ) => void | Promise<void>;
 
 /** The kind of write a {@link MutationGuard} is asked to vet. */
-export declare type MutationGuardAction = "create" | "update" | "delete";
+export declare type MutationGuardAction =
+  | "create"
+  | "update"
+  | "delete"
+  | "publish"
+  | "unpublish";
 
 /**
  * The before/after image of a single document write, handed to a
  * {@link MutationGuard} before it is applied.
  *
- * - `before` is null on create; `after` is null on delete.
+ * - `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.
@@ -553,6 +592,19 @@ export declare type PatchOp =
 
 export declare type Perspective = "raw" | "published" | "drafts" | string[];
 
+/**
+ * A row served by the project-users directory endpoint
+ * (`/projects/<projectId>/users/<id>`), mirroring Sanity's project user
+ * retrieval API: the project-scoped `id` alongside its account-global
+ * `sanityUserId` — the one sanctioned bridge between the two namespaces.
+ */
+export declare interface ProjectUserRecord {
+  id: string;
+  sanityUserId: string;
+  displayName: string;
+  email?: string;
+}
+
 /** Strip `drafts.` / `versions.<name>.` prefix to recover the published id. */
 export declare function publishedIdOf(id: string): string;
 
@@ -789,9 +841,11 @@ export declare interface TestClient {
     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.
+   * 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.
    */
   action: (
     action: Action | Action[],
@@ -811,14 +865,16 @@ export declare interface TestClient {
     publishedId: string;
   }) => Promise<ActionResult>;
   /**
-   * Current `(projectId, dataset)` and active perspective. `token` is
-   * present iff the handle is bound to a registered identity.
+   * Current `(projectId, dataset)`, 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;
     perspective: Perspective;
     token?: string;
+    useProjectHostname: boolean;
   };
   /**
    * Return a new client handle pointing at a different `(projectId, dataset)`
@@ -831,6 +887,14 @@ export declare interface TestClient {
       projectId: string;
       dataset: string;
       perspective: Perspective;
+      /**
+       * Model the global API host (`false`) instead of the project host
+       * (default `true`). A global-hosted sibling's `/users/me` serves the
+       * identity's account-global record (`globalUser`, falling back to the
+       * project record) — mirroring `@sanity/client`, where a non-project
+       * config routes requests to `api.sanity.io`.
+       */
+      useProjectHostname: boolean;
       /**
        * 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
@@ -841,10 +905,11 @@ export declare interface TestClient {
       /**
        * Bind the sibling to a token registered in the family's identity
        * registry (`createTestClient({ identities })` / `addIdentity`): its
-       * `/users/me` serves that identity's user, its ACL path serves that
-       * identity's grants, and reads/writes are gated through them — the
-       * token determines identity, exactly like production. Unknown tokens
-       * throw. Mutually exclusive with `accessControl`.
+       * `/users/me` serves that identity's record for the sibling's project
+       * and host, its ACL path serves that identity's grants, and
+       * reads/writes are gated through them — the token determines
+       * identity, exactly like production. Unknown tokens throw. Mutually
+       * exclusive with `accessControl`.
        */
       token: string;
     }>,
@@ -938,8 +1003,18 @@ export declare interface TestClient {
 }
 
 export declare interface TestClientAccessControl {
-  /** What `client.request({ url: "/users/me" })` returns. */
+  /** What `client.request({ url: "/users/me" })` returns on a project-hosted handle. */
   currentUser: CurrentUser;
+  /**
+   * What `/users/me` returns on a global-hosted handle
+   * (`useProjectHostname: false`, at creation or via `withConfig`).
+   * Sanity serves the
+   * account-global user there (`g*` id, no roles) while the project host
+   * serves the project-scoped record (`p*` id, project roles). Omit to
+   * serve `currentUser` from both — the single-id collapse that is also
+   * exactly how robot tokens behave in production.
+   */
+  globalUser?: CurrentUser;
   /** What `client.request({ url: aclPath })` returns. */
   grants: Grant[];
   /**
@@ -952,13 +1027,36 @@ export declare interface TestClientAccessControl {
 /**
  * One entry in the token→identity registry (`createTestClient({ identities })`).
  * A handle bound to the entry's token behaves exactly like one configured
- * with `accessControl: { currentUser: user, grants }` — `/users/me` serves
- * `user`, the default ACL path serves `grants`, and reads/writes are gated
- * through them.
+ * with `accessControl: { currentUser: projectUserOf(identity, projectId),
+ * globalUser, grants }` — `/users/me` serves the record for the handle's
+ * project and host, the default ACL path serves `grants`, and reads/writes
+ * are gated through them.
  */
 export declare interface TestClientIdentity {
-  /** What `/users/me` returns for clients bound to this token. */
+  /**
+   * The project-scoped user record: what `/users/me` returns on a
+   * project-hosted handle, and the id `identity()` resolves to in grant
+   * filters and mutation guards. Per-project variants go in
+   * `usersByProject`; this is the record for any project without one.
+   */
   user: CurrentUser;
+  /**
+   * The account-global user record, served by `/users/me` on a
+   * global-hosted handle (`useProjectHostname: false`, at creation or
+   * via `withConfig`).
+   * The same person carries a different id per project (`p*`) and one
+   * global id (`g*`); registering both lets tests model that split.
+   * Omit for single-id principals (robot tokens resolve to one `p-*` id
+   * on every host).
+   */
+  globalUser?: CurrentUser;
+  /**
+   * Per-project user records, keyed by projectId — the same token
+   * resolves to a different project-scoped id in each project, which is
+   * what these model. A handle's project falls back to `user` when its
+   * projectId has no entry.
+   */
+  usersByProject?: Record<string, CurrentUser>;
   /** Grants served at the ACL path and enforced on reads/writes. */
   grants: Grant[];
 }

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare type Action = ReleaseAction | VersionAction;
+export declare type Action = ReleaseAction | VersionAction | DocumentAction;
 
 /** Options for `action()`. Only `tag` is meaningful to the fake. */
 export declare interface ActionOptions {
@@ -107,8 +107,9 @@ export declare interface CreateTestClientOptions {
   datasets?: Record<string, SanityDocumentLike[]>;
   /**
    * Opt-in access-control simulation. When set, the client exposes
-   * `request({ url })` that serves `/users/me` + the configured ACL
-   * path, AND every mutation is gated through the supplied `grants`
+   * `request({ url })` that serves `/users/me` (host-aware), the
+   * configured ACL path, and `/projects/<projectId>/users/<ids>`,
+   * AND every mutation is gated through the supplied `grants`
    * — writes that the grants don't permit throw a `WriteAccessDeniedError`
    * shaped like Sanity's 403. Lets tests demonstrate the full
    * "engine soft-gate + lake hard-gate" contract end-to-end without
@@ -165,6 +166,14 @@ export declare interface CreateTestClientOptions {
    * tests stay green.
    */
   perspective?: Perspective;
+  /**
+   * Which API host the root handle models: the project host (default
+   * `true`) or the global host (`false`) — same flag as the real
+   * `createClient` config. A global-hosted handle's `/users/me` serves
+   * the identity's account-global record. `withConfig({ useProjectHostname })`
+   * mints siblings on the other host.
+   */
+  useProjectHostname?: boolean;
 }
 
 /**
@@ -202,6 +211,26 @@ export declare function defaultAclPath(
   dataset: string,
 ): string;
 
+/**
+ * Draft↔published document actions — `sanity.action.document.publish`
+ * promotes the draft onto the published id (and deletes the draft);
+ * `sanity.action.document.unpublish` retracts the published document into a
+ * draft (keeping an existing draft untouched) and deletes the published one.
+ */
+export declare type DocumentAction =
+  | {
+      actionType: "sanity.action.document.publish";
+      draftId: string;
+      publishedId: string;
+      ifDraftRevisionId?: string;
+      ifPublishedRevisionId?: string;
+    }
+  | {
+      actionType: "sanity.action.document.unpublish";
+      draftId: string;
+      publishedId: string;
+    };
+
 /**
  * Document body accepted by `version.create` / `createVersion`. The id
  * is derived from `releaseId + publishedId` so callers may omit `_id`
@@ -387,11 +416,13 @@ 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 — 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.action`, `client.releases.*`, `createVersion`) is **not**
- * intercepted.
+ * `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
@@ -404,13 +435,21 @@ export declare type MutationGuard = (
 ) => void | Promise<void>;
 
 /** The kind of write a {@link MutationGuard} is asked to vet. */
-export declare type MutationGuardAction = "create" | "update" | "delete";
+export declare type MutationGuardAction =
+  | "create"
+  | "update"
+  | "delete"
+  | "publish"
+  | "unpublish";
 
 /**
  * The before/after image of a single document write, handed to a
  * {@link MutationGuard} before it is applied.
  *
- * - `before` is null on create; `after` is null on delete.
+ * - `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.
@@ -553,6 +592,19 @@ export declare type PatchOp =
 
 export declare type Perspective = "raw" | "published" | "drafts" | string[];
 
+/**
+ * A row served by the project-users directory endpoint
+ * (`/projects/<projectId>/users/<id>`), mirroring Sanity's project user
+ * retrieval API: the project-scoped `id` alongside its account-global
+ * `sanityUserId` — the one sanctioned bridge between the two namespaces.
+ */
+export declare interface ProjectUserRecord {
+  id: string;
+  sanityUserId: string;
+  displayName: string;
+  email?: string;
+}
+
 /** Strip `drafts.` / `versions.<name>.` prefix to recover the published id. */
 export declare function publishedIdOf(id: string): string;
 
@@ -789,9 +841,11 @@ export declare interface TestClient {
     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.
+   * 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.
    */
   action: (
     action: Action | Action[],
@@ -811,14 +865,16 @@ export declare interface TestClient {
     publishedId: string;
   }) => Promise<ActionResult>;
   /**
-   * Current `(projectId, dataset)` and active perspective. `token` is
-   * present iff the handle is bound to a registered identity.
+   * Current `(projectId, dataset)`, 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;
     perspective: Perspective;
     token?: string;
+    useProjectHostname: boolean;
   };
   /**
    * Return a new client handle pointing at a different `(projectId, dataset)`
@@ -831,6 +887,14 @@ export declare interface TestClient {
       projectId: string;
       dataset: string;
       perspective: Perspective;
+      /**
+       * Model the global API host (`false`) instead of the project host
+       * (default `true`). A global-hosted sibling's `/users/me` serves the
+       * identity's account-global record (`globalUser`, falling back to the
+       * project record) — mirroring `@sanity/client`, where a non-project
+       * config routes requests to `api.sanity.io`.
+       */
+      useProjectHostname: boolean;
       /**
        * 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
@@ -841,10 +905,11 @@ export declare interface TestClient {
       /**
        * Bind the sibling to a token registered in the family's identity
        * registry (`createTestClient({ identities })` / `addIdentity`): its
-       * `/users/me` serves that identity's user, its ACL path serves that
-       * identity's grants, and reads/writes are gated through them — the
-       * token determines identity, exactly like production. Unknown tokens
-       * throw. Mutually exclusive with `accessControl`.
+       * `/users/me` serves that identity's record for the sibling's project
+       * and host, its ACL path serves that identity's grants, and
+       * reads/writes are gated through them — the token determines
+       * identity, exactly like production. Unknown tokens throw. Mutually
+       * exclusive with `accessControl`.
        */
       token: string;
     }>,
@@ -938,8 +1003,18 @@ export declare interface TestClient {
 }
 
 export declare interface TestClientAccessControl {
-  /** What `client.request({ url: "/users/me" })` returns. */
+  /** What `client.request({ url: "/users/me" })` returns on a project-hosted handle. */
   currentUser: CurrentUser;
+  /**
+   * What `/users/me` returns on a global-hosted handle
+   * (`useProjectHostname: false`, at creation or via `withConfig`).
+   * Sanity serves the
+   * account-global user there (`g*` id, no roles) while the project host
+   * serves the project-scoped record (`p*` id, project roles). Omit to
+   * serve `currentUser` from both — the single-id collapse that is also
+   * exactly how robot tokens behave in production.
+   */
+  globalUser?: CurrentUser;
   /** What `client.request({ url: aclPath })` returns. */
   grants: Grant[];
   /**
@@ -952,13 +1027,36 @@ export declare interface TestClientAccessControl {
 /**
  * One entry in the token→identity registry (`createTestClient({ identities })`).
  * A handle bound to the entry's token behaves exactly like one configured
- * with `accessControl: { currentUser: user, grants }` — `/users/me` serves
- * `user`, the default ACL path serves `grants`, and reads/writes are gated
- * through them.
+ * with `accessControl: { currentUser: projectUserOf(identity, projectId),
+ * globalUser, grants }` — `/users/me` serves the record for the handle's
+ * project and host, the default ACL path serves `grants`, and reads/writes
+ * are gated through them.
  */
 export declare interface TestClientIdentity {
-  /** What `/users/me` returns for clients bound to this token. */
+  /**
+   * The project-scoped user record: what `/users/me` returns on a
+   * project-hosted handle, and the id `identity()` resolves to in grant
+   * filters and mutation guards. Per-project variants go in
+   * `usersByProject`; this is the record for any project without one.
+   */
   user: CurrentUser;
+  /**
+   * The account-global user record, served by `/users/me` on a
+   * global-hosted handle (`useProjectHostname: false`, at creation or
+   * via `withConfig`).
+   * The same person carries a different id per project (`p*`) and one
+   * global id (`g*`); registering both lets tests model that split.
+   * Omit for single-id principals (robot tokens resolve to one `p-*` id
+   * on every host).
+   */
+  globalUser?: CurrentUser;
+  /**
+   * Per-project user records, keyed by projectId — the same token
+   * resolves to a different project-scoped id in each project, which is
+   * what these model. A handle's project falls back to `user` when its
+   * projectId has no entry.
+   */
+  usersByProject?: Record<string, CurrentUser>;
   /** Grants served at the ACL path and enforced on reads/writes. */
   grants: Grant[];
 }