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

package/README.md

@@ -77,10 +77,11 @@ More patterns — passing the fake to code typed against `SanityClient`, asserti
 | Transaction | `transaction()` chain → `.commit()` | Mutations: `.create`, `.createOrReplace`, `.createIfNotExists`, `.delete`, `.patch(id, recipe)`. Atomic — any throw rolls back the whole batch. Default result is a `MultipleMutationResult` (`{ transactionId, documentIds, results }`) |
 | Actions | `action(action \| action[])` | Content Lake release / version actions, applied atomically |
 | Releases | `releases.*`, `createVersion`, `unpublishVersion` | Content Releases lifecycle — create / edit / schedule / publish / archive / delete, plus version create / replace / discard / unpublish |
-| Config | `config()` | Returns `{ projectId, dataset, perspective, token?, useProjectHostname }` |
-| Config | `withConfig({ projectId?, dataset?, perspective?, accessControl?, token?, useProjectHostname? })` | Sibling handle into the same multi-dataset registry; `token` binds a registered identity (see the token→identity registry below), `accessControl` rebinds it inline — the two are mutually exclusive; `useProjectHostname: false` mints a global-hosted sibling |
-| Perspectives | `raw` / `published` / `drafts` / release stacks | Per-client default or per-`fetch` override; draft/version layering with `_originalId` projection |
-| HTTP | `request({ url? \| uri? })` | Present **only** when the handle has an acting identity (`accessControl`, or a bound `token`). Serves `/users/me` (host-aware: project-scoped record on the project host, `globalUser` on a global-hosted handle), the configured ACL path, `/projects/<projectId>` (the project's members: `{ id, isRobot?, roles? }` rows, one per distinct resolved project user), and `/projects/<projectId>/users/<ids>` (project-user records with `id` + `sanityUserId`). Calling it without one throws a guidance error. |
+| Config | `config()` | Returns `{ projectId, dataset, resource?, perspective, token?, useProjectHostname }` |
+| Config | `getDataUrl(operation, path?)` | The same URL `@sanity/client` builds: `<resource base>/<operation>/<path>` on a `resource` handle, `/data/<operation>/<dataset>/<path>` otherwise |
+| Config | `withConfig({ projectId?, dataset?, resource?, perspective?, accessControl?, token?, useProjectHostname? })` | Sibling handle into the same multi-resource registry; `resource` points it at a Media Library, Canvas, dashboard or dataset (see [Resource types](#resource-types-media-library-canvas-dashboard)); `token` binds a registered identity (see the token→identity registry below), `accessControl` rebinds it inline — the two are mutually exclusive; `useProjectHostname: false` mints a global-hosted sibling |
+| Perspectives | `raw` / `published` / `drafts` / release stacks / a single release name or comma-joined stack (`"rA"`, `"drafts,rA"`), as `@sanity/client` sends them | Per-client default or per-`fetch` override; draft/version layering with `_originalId` projection |
+| HTTP | `request({ url? \| uri? })` | Present **only** when the handle has an acting identity (`accessControl`, or a bound `token`). Serves `/users/me` (host-aware: project-scoped record on the project host, `globalUser` on a global-hosted or `resource` handle), the handle's ACL (`<data base>/acl`, or an explicit `aclPath`), `/projects/<projectId>` (the project's members: `{ id, isRobot?, roles? }` rows, one per distinct resolved project user, plus `organizationId` when configured), `/projects/<projectId>/users/<ids>` (project-user records with `id` + `sanityUserId`), the History API, resource lookup and the Access API (see [Resource types](#resource-types-media-library-canvas-dashboard)). Calling it without one throws a guidance error. |
 
 #### Mutation return shapes
 
@@ -98,9 +99,9 @@ More patterns — passing the fake to code typed against `SanityClient`, asserti
 
 ### Gating writes — `mutationGuard`
 
-`createTestClient({ mutationGuard })` installs a pluggable write interceptor. It runs on every write through the document mutation API — `create` / `createOrReplace` / `createIfNotExists` / `patch` / `delete` and the equivalent `transaction()` / `mutate()` operations — _before_ the store changes, and **throws to reject** the write (the throw propagates out of the client call, like a real lake rejection). The release/version action API (`action`, `releases.*`, `createVersion`) is **not** intercepted.
+`createTestClient({ mutationGuard })` installs a pluggable write interceptor. It runs once for each document's net change in a commit through the document mutation API — `create` / `createOrReplace` / `createIfNotExists` / `patch` / `delete` and the equivalent `transaction()` / `mutate()` operations. Document publish and unpublish actions are expanded into their published and draft mutations. Release and version actions (`releases.*`, `createVersion`, and `unpublishVersion`) are not intercepted.
 
-The client owns the _seam_; the caller owns the _policy_. This is the hook a workflow test bench uses to enforce Content Lake **mutation guards** at the write path without re-implementing guard evaluation. Each call receives the before/after image (`before` is `null` on create, `after` is `null` on delete), the `action`, and the acting `identity`.
+The client owns the _seam_; the caller owns the _policy_. This is the hook a workflow test bench uses to enforce Content Lake **mutation guards** at the write path without re-implementing guard evaluation. Each call receives the original/final image (`before` is `null` on create, `after` is `null` on delete), the `action`, and the acting `identity`. Return every denying guard as `{ guardID, name? }`; the fake evaluates every net document mutation, aggregates the returned denials, deduplicates them by `guardID` in first-observed order, rolls back the commit, and throws a 403-shaped `GuardDeniedError` with `type: "guardDeniedError"` and `denials`. Other thrown callback errors propagate unchanged.
 
 ```ts
 const client = createTestClient({
@@ -108,13 +109,16 @@ const client = createTestClient({
   mutationGuard: ({ action, before, after }) => {
     // Freeze `body` once an article is locked.
     if (action === "update" && before?.locked && before.body !== after?.body) {
-      throw new Error("body is locked");
+      return [{ guardID: "_.guards.article-body", name: "Locked article body" }];
     }
   },
 });
 
 await client.patch("article-1").set({ title: "ok" }).commit(); // allowed
-await expect(client.patch("article-1").set({ body: "no" }).commit()).rejects.toThrow();
+await expect(client.patch("article-1").set({ body: "no" }).commit()).rejects.toMatchObject({
+  statusCode: 403,
+  type: "guardDeniedError",
+});
 ```
 
 > [!NOTE]
@@ -140,6 +144,10 @@ const bob = alice.withConfig({ token: "t-bob" });
 
 Register more identities after creation with `client.addIdentity(token, { user, grants })` — an upsert into the family-shared registry; already-bound siblings resolve lazily and pick the change up immediately. For a one-off identity without a registry, `withConfig({ accessControl })` still works (mutually exclusive with `token` in the same call).
 
+#### System-document grants
+
+User-issued writes to system document IDs beginning with `_.` require the `manage` permission. Ordinary `create` and `update` grants do not authorize these writes; add `manage` to identities whose tests intentionally create, replace, patch, delete, transact, mutate, publish, or unpublish system documents. The fake's internal release/version bookkeeping remains outside access-control interception.
+
 #### Dual-namespace identities: global vs project user ids
 
 In production the same token resolves to a **different project-scoped user id in every project** (what lake `identity()` returns) and **one account-global id** (what the global API host's `/users/me` returns); robot tokens carry a single id on every host. An identity can model that split with `globalUser` (served by `/users/me` on a `useProjectHostname: false` handle) and `usersByProject` (per-project records; the handle's project falls back to `user`):
@@ -164,7 +172,39 @@ await client.request({ uri: "/projects/alpha/users/pAlpha" }); // { id: "pAlpha"
 
 The project directory endpoint (`/projects/<projectId>`) returns each resolved project member's `id`, project-specific `roles`, and robot marker. Roles are served in canonical order, and duplicate-token agreement ignores role and property order. Registering two tokens with the same project user id is supported when their served member records agree; conflicting roles fail the request instead of making the result depend on registration order.
 
-Grant-filter and mutation-guard `identity()` stay bound to the **project-scoped** record, matching the lake. Identities without `globalUser` serve one record everywhere — the production robot-token shape.
+Grant-filter and mutation-guard `identity()` stay bound to the **project-scoped** record on a dataset, matching the lake. On a Media Library, Canvas or dashboard there is no project, so they see the account-global record (`globalUser`, falling back to `user`). Identities without `globalUser` serve one record everywhere — the production robot-token shape.
+
+### Resource types: Media Library, Canvas, dashboard
+
+A handle configured with `resource: { type, id }` — the same config `@sanity/client` takes — reads and writes that resource's own store, and answers each capability the way the platform does on that resource type (staging probe, 2026-11-06). Where the platform says no, the fake throws the platform's status and body, shaped like `@sanity/client`'s `ClientError` (`statusCode`, `message`, `response.body`, `details`).
+
+```ts
+const client = createTestClient({
+  resource: { type: "media-library", id: "ml1" },
+  organizationId: "org1",
+  identities: { "t-robot": robot },
+  token: "t-robot",
+});
+const canvas = client.withConfig({ resource: { type: "canvas", id: "c1" } });
+await client.request({ url: client.getDataUrl("history", `documents/a?revision=${rev}`) });
+await canvas.releases.create({ releaseId: "r1" }); // 404 Cannot POST /canvases/c1/actions
+```
+
+| Capability | dataset | media-library | canvas | dashboard |
+| --- | --- | --- | --- | --- |
+| `drafts.` / `versions.` ids, perspectives | ✅ | ✅ | ✅ | ✅ |
+| `/actions` (releases, version and document actions) | ✅ | ✅, except `release.create` → 403 `releaseLimitExceededError` | 404 `Cannot POST …/actions` | 404 `Cannot POST …/actions` |
+| History: `documents/<ids>?revision=`, `transactions/<ids>` (NDJSON), `events/documents/<ids>` | ✅ | ✅ | ✅ | 404 `Cannot GET …` |
+| ACL `<data base>/acl` | ✅ | ✅ | ✅ | 404 `Cannot GET …` |
+| Access API `…/user-permissions/me`, `…/me/check` | ✅ | ✅ | ✅ | ✅ |
+| Access API `…/users` | ✅ | ✅ | 403 | 403 |
+| Access API `…/roles` | ✅ | 403 | 403 | 403 |
+| Org lookup | `/projects/<projectId>` | `GET /media-libraries/<id>` | `GET /canvases/<id>` | `GET /dashboards/<id>` |
+
+- **Access API.** Paths are `/access/<type>/<id>/…` with type `project`, `media-library`, `canvas` or `dashboard`. An identity's `access` entries, keyed `"<type>:<id>"`, hold its `roles` there (non-dataset membership) and the `permissions` the `user-permissions` endpoints report. Every identity is a project member with its project roles. Listings come back on one page (`nextCursor: null`). An unknown type answers 400 `Invalid resource type <type>`. An id the registry does not hold (never seeded, written or addressed) answers 404 `Media library not found` / `Canvas not found` / `Dashboard not found`, except `…/me/check`, which answers `false` as staging does. The 403 cells were not proven on staging (no token could list them), so they answer the way the platform refuses a missing permission: `{ statusCode: 403, message: "You do not have permission to access this resource" }`.
+- **History.** Every committed write since the client was created is recorded per resource, authored by the acting identity; seeded documents can be read at their seeded `_rev`. A handle answers for its own resource, and hides documents its grants cannot read, as reads do (a transaction that also touched such a document is served without it). Events model `createLiveDocument` / `updateLiveDocument` only.
+- **Org lookup.** `createTestClient({ organizationId })` names the organization every resource of the client belongs to.
+- **Identity.** `@sanity/client` sends a `resource` client's requests to the global host, so `/users/me` answers `globalUser`.
 
 ### Test-only helpers (not on real `SanityClient`)
 
@@ -178,6 +218,7 @@ Useful in test bodies, but a giveaway that the code under test isn't using the r
 | `client.reset()` | Drop everything in the current dataset |
 | `client.store()` | Direct access to the underlying `TestStore` |
 | `client.datasets()` | `{ projectId, dataset }[]` known to the registry |
+| `client.resources()` | Every resource known to the registry, `{ type, id }[]` (datasets as `id: "<projectId>.<dataset>"`) |
 | `client.mutations()` | Every committed mutation, flattened and in order — assert exactly what writes your code submitted |
 | `client.transactions()` | Every committed transaction (a direct mutation is a one-mutation transaction), each tagged with `transactionId` + `(projectId, dataset)` |
 | `client.clearLog()` | Reset the mutation / transaction log |
@@ -189,6 +230,7 @@ Useful in test bodies, but a giveaway that the code under test isn't using the r
 | `client.addIdentity(token, identity)` | Register (upsert) a token→identity entry in the family-shared registry |
 | `client.identities()` | Snapshot of the registered token→identity entries |
 | `createTestClient({ datasets: { "p:d": [...] } })` | Seed multiple `(projectId, dataset)` stores up front |
+| `createTestClient({ resources: { "media-library:ml1": [...] } })` | Seed any resource type up front; keys are `"<type>:<id>"` |
 
 #### Two layers of observability
 
@@ -245,7 +287,7 @@ Nested access reports the full path (`client.assets.upload(...)` → `client.ass
 | --- | --- | --- |
 | `listen(...)` — real-time | ❌ Guarded | Test subscription logic separately, or `client.stub("listen", fn)` |
 | `clone()` | ❌ Guarded | `withConfig({})` returns a sibling handle |
-| `getUrl(uri)` / `getDataUrl(...)` — URL builders | ❌ Guarded | Hard-code in tests, or stub |
+| `getUrl(uri)` — URL builder | ❌ Guarded | Hard-code in tests, or stub |
 | `request(...)` — generic HTTP | ⚠️ Only with an acting identity | Configure `accessControl` or bind a registered `token`, stub it, or use [MSW](https://mswjs.io) |
 | `agent.*` / `assets.*` / `projects.*` / `users.*` / `live.*` / `mediaLibrary.*` | ❌ Guarded | Seed docs directly, or `client.stub(name, fn)` |
 | `observable.*` — RxJS API | ❌ Guarded | Wrap the Promise API with `from()` if needed |