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

package/dist/index.js

@@ -3,6 +3,449 @@ const ERR_PREFIX = "[client-fake-for-test]";
 function fakeError(message) {
   return new Error(`${ERR_PREFIX} ${message}`);
 }
+function createDocumentHistory() {
+  const transactions = [], revisions = /* @__PURE__ */ new Map(), keep = (doc) => revisions.set(`${doc._id} ${doc._rev}`, structuredClone(doc)), deleted = /* @__PURE__ */ new Map();
+  return {
+    commit: ({ transactionId, author, before, after }) => {
+      const afterById = new Map(after.map((doc) => [doc._id, doc])), ids = /* @__PURE__ */ new Set([...before.keys(), ...afterById.keys()]), effects = [];
+      for (const id of ids) {
+        const previous = before.get(id), next = afterById.get(id);
+        previous !== next && (previous !== void 0 && keep(previous), next !== void 0 && keep(next), next === void 0 && previous !== void 0 ? deleted.set(id, structuredClone(previous)) : deleted.delete(id), effects.push({
+          documentId: id,
+          after: next === void 0 ? void 0 : structuredClone(next),
+          existed: previous !== void 0
+        }));
+      }
+      effects.length !== 0 && transactions.push({
+        id: transactionId,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        author,
+        effects
+      });
+    },
+    documentsAt: ({ ids, revision, current }) => ids.flatMap((id) => {
+      const image = revisions.get(`${id} ${revision}`) ?? current.find((doc) => doc._id === id && doc._rev === revision);
+      return image === void 0 ? [] : [structuredClone(image)];
+    }),
+    lastImage: (id) => deleted.get(id),
+    documentIds: () => [
+      ...new Set(transactions.flatMap((txn) => txn.effects.map((effect) => effect.documentId)))
+    ],
+    transactions: (ids, visible) => transactions.filter((txn) => txn.effects.some((effect) => ids.includes(effect.documentId))).map((txn) => ({ ...txn, effects: txn.effects.filter((e) => visible(e.documentId)) })).map((txn) => ({
+      id: txn.id,
+      timestamp: txn.timestamp,
+      ...txn.author !== void 0 ? { author: txn.author } : {},
+      mutations: txn.effects.map((effect) => {
+        if (effect.after === void 0) return { delete: { id: effect.documentId } };
+        const after = structuredClone(effect.after);
+        return effect.existed ? { createOrReplace: after } : { create: after };
+      }),
+      documentIDs: txn.effects.map((effect) => effect.documentId)
+    })),
+    events: (ids) => Object.fromEntries(
+      ids.map((id) => [
+        id,
+        transactions.flatMap(
+          (txn) => txn.effects.filter((effect) => effect.documentId === id && effect.after !== void 0).map(
+            (effect) => ({
+              type: effect.existed ? "updateLiveDocument" : "createLiveDocument",
+              id: txn.id,
+              documentId: id,
+              revisionId: effect.after._rev,
+              timestamp: txn.timestamp,
+              ...txn.author !== void 0 ? { author: txn.author } : {}
+            })
+          )
+        ).toReversed()
+      ])
+    )
+  };
+}
+function historyIds(list) {
+  return list.split(",").map((id) => decodeURIComponent(id));
+}
+class PlatformHttpError extends Error {
+  statusCode;
+  response;
+  responseBody;
+  details;
+  constructor(args) {
+    const { method, path, statusCode, statusMessage, body } = args;
+    super(clientErrorMessage(args)), this.name = "PlatformHttpError", this.statusCode = statusCode, this.response = { body, url: path, method, headers: {}, statusCode, statusMessage }, this.responseBody = typeof body == "string" ? body : JSON.stringify(body, null, 2);
+    const error = isRecord(body) ? body.error : void 0;
+    this.details = isRecord(error) ? error : void 0;
+  }
+}
+function isRecord(value) {
+  return typeof value == "object" && value !== null;
+}
+function clientErrorMessage(args) {
+  const { body } = args;
+  if (isRecord(body)) {
+    const { error, message } = body;
+    if (isRecord(error) && typeof error.description == "string") return error.description;
+    if (typeof message == "string") return message;
+  }
+  const details = typeof body == "string" ? ` (${body.length > 100 ? `${body.slice(0, 100)}\u2026` : body})` : "";
+  return `${args.method}-request to ${args.path} resulted in HTTP ${args.statusCode} ${args.statusMessage}${details}`;
+}
+const notMounted = ({ method, path }) => new PlatformHttpError({
+  method,
+  path,
+  statusCode: 404,
+  statusMessage: "Not Found",
+  body: `Cannot ${method} ${path}`
+});
+function accessApiError(args) {
+  const { request, statusCode, statusMessage, message } = args;
+  return new PlatformHttpError({
+    ...request,
+    statusCode,
+    statusMessage,
+    body: { statusCode, message }
+  });
+}
+const noPermission = (request) => accessApiError({
+  request,
+  statusCode: 403,
+  statusMessage: "Forbidden",
+  message: "You do not have permission to access this resource"
+});
+function invalidAccessType(request, type) {
+  return accessApiError({
+    request,
+    statusCode: 400,
+    statusMessage: "Bad Request",
+    message: `Invalid resource type ${type}`
+  });
+}
+function notFound(name) {
+  return (request) => accessApiError({
+    request,
+    statusCode: 404,
+    statusMessage: "Not Found",
+    message: `${name} not found`
+  });
+}
+const releaseLimitExceeded = ({ method, path }) => new PlatformHttpError({
+  method,
+  path,
+  statusCode: 403,
+  statusMessage: "Forbidden",
+  body: {
+    error: {
+      description: "active release count exceeds the limit of 0",
+      type: "releaseLimitExceededError"
+    }
+  }
+});
+function serveCapability(capability, request, serve) {
+  if (capability !== "served") throw capability(request);
+  return serve();
+}
+const ACCESS_KEY_SEPARATOR = ":";
+function accessKey(type, id) {
+  return `${type}${ACCESS_KEY_SEPARATOR}${id}`;
+}
+function segmentBase(segment) {
+  const pattern = new RegExp(`^/${segment}/([^/]+)(/.*)?$`);
+  return (path) => {
+    const match = path.match(pattern);
+    if (match !== null)
+      return { id: decodeURIComponent(match[1]), rest: match[2] ?? "" };
+  };
+}
+const DATASET_BASE = /^\/projects\/([^/]+)\/datasets\/([^/]+)(\/.*)?$/;
+function datasetParts(id) {
+  const dot = id.indexOf(".");
+  return { projectId: id.slice(0, dot), dataset: id.slice(dot + 1) };
+}
+function accessEntryRoles(type) {
+  return ({ identity, id }) => identity.access?.[accessKey(type, id)]?.roles;
+}
+const RESOURCE_CAPABILITIES = {
+  dataset: {
+    label: (id) => {
+      const { projectId, dataset } = datasetParts(id);
+      return `dataset "${projectId}:${dataset}"`;
+    },
+    dataBase: (id) => {
+      const { projectId, dataset } = datasetParts(id);
+      return `/projects/${projectId}/datasets/${dataset}`;
+    },
+    matchBase: (path) => {
+      const match = path.match(DATASET_BASE);
+      if (match !== null)
+        return { id: `${match[1]}.${match[2]}`, rest: match[3] ?? "" };
+    },
+    // A dataset's organization comes from its project: `GET /projects/<projectId>`.
+    lookupAtBase: !1,
+    identity: "project",
+    acl: "served",
+    history: "served",
+    actions: "served",
+    refusedActions: {},
+    access: {
+      type: "project",
+      id: (id) => datasetParts(id).projectId,
+      roles: "served",
+      users: "served",
+      // Every registered identity is a member of every project, with its project roles.
+      memberRoles: ({ identity, id }) => (identity.usersByProject?.[id] ?? identity.user).roles ?? []
+    }
+  },
+  "media-library": {
+    label: (id) => `media library "${id}"`,
+    dataBase: (id) => `/media-libraries/${id}`,
+    matchBase: segmentBase("media-libraries"),
+    lookupAtBase: !0,
+    identity: "global",
+    acl: "served",
+    history: "served",
+    actions: "served",
+    refusedActions: { "sanity.action.release.create": releaseLimitExceeded },
+    access: {
+      type: "media-library",
+      id: (id) => id,
+      // Unproven on staging (no token held roles read): refused like a missing permission.
+      roles: noPermission,
+      users: "served",
+      unknownId: notFound("Media library"),
+      memberRoles: accessEntryRoles("media-library")
+    }
+  },
+  canvas: {
+    label: (id) => `canvas "${id}"`,
+    dataBase: (id) => `/canvases/${id}`,
+    matchBase: segmentBase("canvases"),
+    lookupAtBase: !0,
+    identity: "global",
+    acl: "served",
+    history: "served",
+    actions: notMounted,
+    refusedActions: {},
+    access: {
+      type: "canvas",
+      id: (id) => id,
+      // Unproven on staging (no canvas roles/members permission exists to grant).
+      roles: noPermission,
+      users: noPermission,
+      unknownId: notFound("Canvas"),
+      memberRoles: accessEntryRoles("canvas")
+    }
+  },
+  dashboard: {
+    label: (id) => `dashboard "${id}"`,
+    dataBase: (id) => `/dashboards/${id}`,
+    matchBase: segmentBase("dashboards"),
+    lookupAtBase: !0,
+    identity: "global",
+    acl: notMounted,
+    history: notMounted,
+    actions: notMounted,
+    refusedActions: {},
+    access: {
+      type: "dashboard",
+      id: (id) => id,
+      // Unproven on staging, as for canvas.
+      roles: noPermission,
+      users: noPermission,
+      unknownId: notFound("Dashboard"),
+      memberRoles: accessEntryRoles("dashboard")
+    }
+  }
+};
+function capabilitiesOf(type) {
+  const row = RESOURCE_CAPABILITIES[type];
+  if (row === void 0)
+    throw fakeError(
+      `Unsupported resource type ${JSON.stringify(type)}. The fake serves ${Object.keys(RESOURCE_CAPABILITIES).map((t) => `"${t}"`).join(", ")}.`
+    );
+  return row;
+}
+function validateResource(resource) {
+  const row = capabilitiesOf(resource.type);
+  if (resource.type === "dataset" && resource.id.split(".").length !== 2)
+    throw fakeError(
+      `Dataset resource ID must be in the format "project.dataset" (got ${JSON.stringify(resource.id)}), the same rule @sanity/client applies to \`resource: { type: 'dataset', id }\`.`
+    );
+  return row;
+}
+function matchResourcePath(path) {
+  for (const [type, row] of Object.entries(RESOURCE_CAPABILITIES)) {
+    const match = row.matchBase(path);
+    if (match !== void 0)
+      return { resource: { type, id: match.id }, rest: match.rest };
+  }
+}
+function capabilitiesForAccessType(type) {
+  for (const [resourceType, row] of Object.entries(RESOURCE_CAPABILITIES))
+    if (row.access.type === type) return { resourceType, row };
+}
+function dataUrl(args) {
+  const { resource, dataset, operation, path } = args;
+  if (resource !== void 0) {
+    const uri2 = path !== void 0 ? `${operation}/${path}` : operation;
+    return `${capabilitiesOf(resource.type).dataBase(resource.id)}/${uri2}`.replace(
+      /\/($|\?)/,
+      "$1"
+    );
+  }
+  const base = `/${operation}/${dataset}`;
+  return `/data${path !== void 0 ? `${base}/${path}` : base}`.replace(/\/($|\?)/, "$1");
+}
+const ACCESS_PATH = /^\/access\/([^/]+)\/([^/]+)(\/.*)?$/, DATA_HISTORY_PATH = /^\/data\/history\/([^/]+)(\/.*)$/;
+function page(data) {
+  return { data, nextCursor: null };
+}
+async function servePlatformRequest(ctx, url) {
+  const queryStart = url.indexOf("?"), path = queryStart === -1 ? url : url.slice(0, queryStart), query = new URLSearchParams(queryStart === -1 ? "" : url.slice(queryStart + 1)), request = { method: "GET", path }, access = path.match(ACCESS_PATH);
+  if (access !== null) {
+    const [, type, id, rest2] = access;
+    return serveAccess({ ctx, request, type, id: decodeURIComponent(id), rest: rest2 ?? "", query });
+  }
+  const dataHistory = path.match(DATA_HISTORY_PATH);
+  if (dataHistory !== null) {
+    const [, dataset, rest2] = dataHistory, resource2 = { type: "dataset", id: `${ctx.projectId}.${dataset}` };
+    return serveHistory({ ctx, request, resource: resource2, rest: rest2, query });
+  }
+  const matched = matchResourcePath(path);
+  if (matched === void 0) return;
+  const { resource, rest } = matched, row = capabilitiesOf(resource.type);
+  if (rest === "") return row.lookupAtBase ? serveLookup(ctx, resource) : void 0;
+  if (rest === "/acl")
+    return serveCapability(row.acl, request, () => {
+      const own = ctx.own(resource);
+      return own === void 0 ? void 0 : { value: own.grants };
+    });
+  if (rest.startsWith("/history/"))
+    return serveHistory({ ctx, request, resource, rest: rest.slice(8), query });
+}
+function serveLookup(ctx, resource) {
+  if (ctx.organizationId === void 0)
+    throw fakeError(
+      `request(): GET ${capabilitiesOf(resource.type).dataBase(resource.id)} answers the resource's organization, but no organization is configured. Pass createTestClient({ organizationId }).`
+    );
+  return { value: { organizationId: ctx.organizationId, id: resource.id, status: "active" } };
+}
+function serveHistory(args) {
+  const { ctx, request, resource, rest, query } = args;
+  return serveCapability(capabilitiesOf(resource.type).history, request, () => {
+    const own = ctx.own(resource);
+    return own === void 0 ? void 0 : readHistory({ own, request, rest, query });
+  });
+}
+async function readHistory(args) {
+  const { own, request, rest, query } = args, current = new Map(own.documents().map((doc) => [doc._id, doc])), hidden = /* @__PURE__ */ new Set();
+  for (const id of /* @__PURE__ */ new Set([...current.keys(), ...own.history.documentIds()])) {
+    const image = current.get(id) ?? own.history.lastImage(id);
+    image !== void 0 && !await own.canRead(image) && hidden.add(id);
+  }
+  const visible = (id) => !hidden.has(id), readable = (list) => historyIds(list).filter(visible), documents = rest.match(/^\/documents\/([^/]+)$/);
+  if (documents !== null) {
+    const revision = query.get("revision");
+    if (revision === null)
+      throw fakeError(
+        `request(): ${request.path} is served for \`?revision=<rev>\` reads only (time-based history reads are not simulated).`
+      );
+    const ids = readable(documents[1]);
+    return {
+      value: { documents: own.history.documentsAt({ ids, revision, current: own.documents() }) }
+    };
+  }
+  const transactions = rest.match(/^\/transactions\/([^/]+)$/);
+  if (transactions !== null)
+    return { value: own.history.transactions(readable(transactions[1]), visible).map((record) => JSON.stringify(record)).join(`
+`) };
+  const events = rest.match(/^\/events\/documents\/([^/]+)$/);
+  if (events !== null)
+    return {
+      value: {
+        events: own.history.events(readable(events[1])),
+        nextCursor: ""
+      }
+    };
+}
+function serveAccess(args) {
+  const { ctx, request, type, id, rest, query } = args, found = capabilitiesForAccessType(type);
+  if (found === void 0) throw invalidAccessType(request, type);
+  const accessType = found.row.access.type, { unknownId } = found.row.access;
+  if (unknownId !== void 0 && rest !== "/user-permissions/me/check" && !ctx.exists({ type: found.resourceType, id }))
+    throw unknownId(request);
+  const permissions = ctx.actorAccess()?.[accessKey(accessType, id)]?.permissions ?? [];
+  switch (rest) {
+    case "/roles":
+      return serveCapability(found.row.access.roles, request, () => ({
+        value: page(rolesOn({ row: found.row, id, identities: ctx.identities() }))
+      }));
+    case "/users":
+      return serveCapability(found.row.access.users, request, () => ({
+        value: page(usersOn({ row: found.row, id, identities: ctx.identities() }))
+      }));
+    case "/user-permissions/me":
+      return {
+        value: page(
+          permissions.map((permission) => {
+            const dot = permission.lastIndexOf(".");
+            return {
+              type: permission.slice(0, dot),
+              resourceType: accessType,
+              resourceId: id,
+              action: permission.slice(dot + 1)
+            };
+          })
+        )
+      };
+    case "/user-permissions/me/check": {
+      const requested = query.getAll("permissions").flatMap((value) => value.split(","));
+      return {
+        value: {
+          data: Object.fromEntries(requested.map((p) => [p, permissions.includes(p)]))
+        }
+      };
+    }
+    default:
+      return;
+  }
+}
+function rolesOn(args) {
+  const byName = /* @__PURE__ */ new Map();
+  for (const identity of args.identities)
+    for (const role of args.row.access.memberRoles({ identity, id: args.id }) ?? [])
+      byName.set(role.name, {
+        name: role.name,
+        ...role.title !== void 0 ? { title: role.title } : {},
+        ...role.description !== void 0 ? { description: role.description } : {}
+      });
+  return [...byName.values()].toSorted((a, b) => a.name.localeCompare(b.name));
+}
+function usersOn(args) {
+  const { row, id, identities } = args, bySanityUserId = /* @__PURE__ */ new Map();
+  for (const identity of identities) {
+    const roles = row.access.memberRoles({ identity, id });
+    if (roles === void 0) continue;
+    const user = identity.globalUser ?? identity.user, record = {
+      sanityUserId: user.id,
+      profile: {
+        displayName: user.name ?? user.id,
+        ...user.email !== void 0 ? { email: user.email } : {}
+      },
+      memberships: [
+        {
+          resourceType: row.access.type,
+          resourceId: id,
+          roleNames: roles.map((role) => role.name).toSorted()
+        }
+      ]
+    }, existing = bySanityUserId.get(record.sanityUserId);
+    if (existing !== void 0 && JSON.stringify(existing) !== JSON.stringify(record))
+      throw fakeError(
+        `request(): two registered identities resolve to user "${record.sanityUserId}" on ${row.access.type} "${id}" with different records. Fix the identity registrations so duplicate ids carry identical records.`
+      );
+    bySanityUserId.set(record.sanityUserId, record);
+  }
+  return [...bySanityUserId.values()];
+}
 class WriteAccessDeniedError extends Error {
   documentId;
   permission;
@@ -59,6 +502,12 @@ async function enforceWriteAccess(args) {
 function defaultAclPath(projectId, dataset) {
   return `/projects/${projectId}/datasets/${dataset}/acl`;
 }
+function refusedAcl(path) {
+  const matched = matchResourcePath(path);
+  if (matched?.rest !== "/acl") return;
+  const { acl } = capabilitiesOf(matched.resource.type);
+  return acl === "served" ? void 0 : acl({ method: "GET", path });
+}
 function projectUserOf(identity, projectId) {
   return identity.usersByProject?.[projectId] ?? identity.user;
 }
@@ -122,16 +571,19 @@ function serveProject(args) {
       ...projectUser.id.startsWith("p-") ? { isRobot: !0 } : {},
       ...projectUser.roles !== void 0 ? { roles: canonicalProjectRoles(projectUser.roles) } : {}
     };
-  });
-  return { members: [...consistentProjectRecords({ projectId: args.pathProjectId, records }).values()] };
+  }), members = consistentProjectRecords({ projectId: args.pathProjectId, records });
+  return {
+    ...args.organizationId !== void 0 ? { organizationId: args.organizationId } : {},
+    members: [...members.values()]
+  };
 }
 function makeRequestImpl(ctx) {
-  const { getAccess, projectId, dataset, useProjectHostname, listIdentities } = ctx;
+  const { getAccess, useProjectHostname, listIdentities, organizationId, platform } = ctx;
   return async (opts) => {
-    const accessControl = getAccess(), aclPath = accessControl.aclPath ?? defaultAclPath(projectId, dataset), path = opts.uri ?? opts.url;
+    const accessControl = getAccess(), path = opts.uri ?? opts.url;
     if (path === "/users/me")
       return useProjectHostname ? accessControl.currentUser : accessControl.globalUser ?? accessControl.currentUser;
-    if (path === aclPath)
+    if (path !== void 0 && path === accessControl.aclPath && refusedAcl(path) === void 0)
       return accessControl.grants;
     const projectUsers = path?.match(PROJECT_USERS_PATH), [, pathProjectId, requestedIds] = projectUsers ?? [];
     if (pathProjectId !== void 0 && requestedIds !== void 0)
@@ -144,10 +596,13 @@ function makeRequestImpl(ctx) {
     if (membersProjectId !== void 0)
       return serveProject({
         pathProjectId: membersProjectId,
-        identities: listIdentities()
+        identities: listIdentities(),
+        organizationId
       });
+    const served = path === void 0 ? void 0 : await servePlatformRequest(platform, path);
+    if (served !== void 0) return served.value;
     throw fakeError(
-      `request(): no handler for path "${path}". With access control configured, the fake serves "/users/me", "${aclPath}", "/projects/<projectId>" (members), and "/projects/<projectId>/users/<ids>". For any other endpoint, register a stub (client.stub("request", fn)) or intercept the HTTP call with a tool like MSW.`
+      `request(): no handler for path "${path}". With access control configured, the fake serves "/users/me", the handle's ACL ("<data base>/acl"), "/projects/<projectId>" (members), "/projects/<projectId>/users/<ids>", the History API (client.getDataUrl("history", \u2026)), resource lookup ("/media-libraries/<id>", "/canvases/<id>", "/dashboards/<id>") and the Access API ("/access/<type>/<id>/roles | users | user-permissions/me[/check]"). For any other endpoint, register a stub (client.stub("request", fn)) or intercept the HTTP call with a tool like MSW.`
     );
   };
 }
@@ -411,7 +866,8 @@ function releaseNameOf(id) {
     return rest.slice(0, dot);
 }
 const isDraftId = (id) => id.startsWith(DRAFTS_PREFIX), isVersionId = (id) => id.startsWith(VERSIONS_PREFIX$1), isSystemId = (id) => id.startsWith("_."), isReleaseDocId = (id) => id.startsWith(RELEASE_DOC_PREFIX$1);
-function applyPerspective(docs, perspective) {
+function applyPerspective(docs, requested) {
+  const perspective = normalizePerspective(requested);
   if (perspective === "raw") return [...docs];
   if (perspective === "published")
     return docs.filter((d) => !isDraftId(d._id) && !isVersionId(d._id) && !isSystemId(d._id));
@@ -423,6 +879,20 @@ function applyPerspective(docs, perspective) {
     entry === "drafts" ? includeDrafts = !0 : stack.push(entry);
   return mergeStack(docs, stack, { includeDrafts, includeReleaseDocs: !0 });
 }
+function normalizePerspective(perspective) {
+  if (Array.isArray(perspective)) return perspective;
+  switch (perspective) {
+    case "raw":
+      return "raw";
+    case "published":
+      return "published";
+    case "drafts":
+    case "previewDrafts":
+      return "drafts";
+    default:
+      return perspective.split(",");
+  }
+}
 function mergeStack(docs, releaseStack, options) {
   const groups = /* @__PURE__ */ new Map(), systemReleases = [];
   for (const doc of docs) {
@@ -856,6 +1326,7 @@ const ISSUES_URL = "https://github.com/sanity-labs/client-fake-for-test/issues",
   "createVersion",
   "unpublishVersion",
   "request (only with accessControl or a bound token)",
+  "getDataUrl",
   "config",
   "withConfig"
 ], UNSUPPORTED_MEMBERS = {
@@ -875,10 +1346,6 @@ const ISSUES_URL = "https://github.com/sanity-labs/client-fake-for-test/issues",
     what: "build an absolute API URL for a path",
     workaround: "Hard-code the expected URL in your test, or stub it."
   },
-  getDataUrl: {
-    what: "build an absolute data-API URL",
-    workaround: "Hard-code the expected URL in your test, or stub it."
-  },
   assets: {
     what: "asset upload / metadata namespace",
     workaround: "Seed asset documents into the store directly with `seed()` / `add()`."
@@ -905,7 +1372,7 @@ const ISSUES_URL = "https://github.com/sanity-labs/client-fake-for-test/issues",
   },
   request: {
     what: "generic HTTP request hook \u2014 only wired up when the handle has an acting identity",
-    workaround: "Create the client with `accessControl`, or bind a registered token (`identities` + `token` / `withConfig({ token })`), to enable request() (it serves /users/me, the ACL path, /projects/<projectId>, and /projects/<projectId>/users/<ids>). Or register a stub."
+    workaround: "Create the client with `accessControl`, or bind a registered token (`identities` + `token` / `withConfig({ token })`), to enable request() (it serves /users/me, the ACL path, /projects/<projectId>, /projects/<projectId>/users/<ids>, the History API, resource lookup and the Access API). Or register a stub."
   },
   dryRun: {
     what: "not a method \u2014 did you mean the `{ dryRun }` mutation option?",
@@ -1063,13 +1530,32 @@ function rejectAmbiguousIdentity(site, config) {
       `${site}: \`token\` and \`accessControl\` are mutually exclusive \u2014 a handle acts either as a registered identity (token) or as an inline accessControl config, not both.`
     );
 }
-const registryKey = (projectId, dataset) => `${projectId}:${dataset}`, parseRegistryKey = (key) => {
+const registryKey = (resource) => `${resource.type}:${resource.id}`, datasetResource = (projectId, dataset) => ({
+  type: "dataset",
+  id: `${projectId}.${dataset}`
+}), parseDatasetKey = (key) => {
   const [projectId, dataset] = key.split(":");
   return { projectId, dataset };
+}, parseResourceKey = (key) => {
+  const separator = key.indexOf(":"), resource = {
+    type: key.slice(0, separator),
+    id: key.slice(separator + 1)
+  };
+  if (separator <= 0 || resource.id.length === 0)
+    throw fakeError(
+      `createTestClient(): \`resources\` keys are "<type>:<id>" (e.g. "media-library:ml1"); got "${key}".`
+    );
+  return validateResource(resource), resource;
 };
+function ensureEntry(registry, resource) {
+  const key = registryKey(resource);
+  let entry = registry.get(key);
+  return entry === void 0 && (entry = { resource, store: createTestStore(), history: createDocumentHistory() }, registry.set(key, entry)), entry;
+}
 function createTestClient(options = {}) {
   const defaultProjectId = options.projectId ?? DEFAULT_PROJECT_ID, defaultDataset = options.dataset ?? DEFAULT_DATASET, backend = {
     registry: /* @__PURE__ */ new Map(),
+    organizationId: options.organizationId,
     log: [],
     stubs: /* @__PURE__ */ new Map(),
     calls: [],
@@ -1077,21 +1563,23 @@ function createTestClient(options = {}) {
     identities: new Map(Object.entries(options.identities ?? {})),
     writeChain: Promise.resolve()
   }, registry = backend.registry;
-  rejectAmbiguousIdentity("createTestClient()", options), options.token !== void 0 && requireIdentity(backend, options.token, "createTestClient()");
-  const ensureStore = (projectId, dataset) => {
-    const key = registryKey(projectId, dataset);
-    let store = registry.get(key);
-    return store === void 0 && (store = createTestStore(), registry.set(key, store)), store;
-  };
-  if (options.documents && ensureStore(defaultProjectId, defaultDataset).seed(options.documents), options.datasets)
+  if (rejectAmbiguousIdentity("createTestClient()", options), options.token !== void 0 && requireIdentity(backend, options.token, "createTestClient()"), options.resource !== void 0 && validateResource(options.resource), options.documents) {
+    const root = options.resource ?? datasetResource(defaultProjectId, defaultDataset);
+    ensureEntry(registry, root).store.seed(options.documents);
+  }
+  if (options.datasets)
     for (const [key, docs] of Object.entries(options.datasets)) {
-      const { projectId, dataset } = parseRegistryKey(key);
-      ensureStore(projectId, dataset).seed(docs);
+      const { projectId, dataset } = parseDatasetKey(key);
+      ensureEntry(registry, datasetResource(projectId, dataset)).store.seed(docs);
     }
+  if (options.resources)
+    for (const [key, docs] of Object.entries(options.resources))
+      ensureEntry(registry, parseResourceKey(key)).store.seed(docs);
   return makeHandle({
     backend,
     projectId: defaultProjectId,
     dataset: defaultDataset,
+    resource: options.resource,
     accessControl: options.accessControl,
     perspective: options.perspective ?? "raw",
     requestTagPrefix: options.requestTagPrefix,
@@ -1153,39 +1641,52 @@ function toTxnMutations(operations) {
 function makeHandle(handleArgs) {
   const {
     backend,
-    projectId,
-    dataset,
+    resource,
     accessControl,
     perspective,
     requestTagPrefix,
     mutationGuard,
     token,
     useProjectHostname
-  } = handleArgs, { registry } = backend, activeAccess = () => {
+  } = handleArgs, { registry } = backend, { projectId, dataset } = resource?.type === "dataset" ? datasetParts(resource.id) : handleArgs, target = resource ?? datasetResource(projectId, dataset), activeAccess = () => {
     if (token === void 0) return accessControl;
     const identity = backend.identities.get(token);
     if (identity === void 0)
       throw fakeError(`no identity is registered for token "${token}" (was it removed?).`);
     return {
-      currentUser: projectUserOf(identity, projectId),
+      // Per-project records apply only where the resource lives in a project.
+      currentUser: capabilitiesOf(target.type).identity === "project" ? projectUserOf(identity, projectId) : identity.user,
       ...identity.globalUser !== void 0 ? { globalUser: identity.globalUser } : {},
-      grants: identity.grants
+      grants: identity.grants,
+      ...identity.access !== void 0 ? { access: identity.access } : {}
     };
   }, requireActiveAccess = () => {
     const access = activeAccess();
     if (access === void 0)
       throw fakeError("this handle has no acting identity (no token or accessControl bound).");
     return access;
-  }, store = (() => {
-    const key = registryKey(projectId, dataset);
-    let s = registry.get(key);
-    return s === void 0 && (s = createTestStore(), registry.set(key, s)), s;
-  })(), concurrentEditKey = (id) => registryKey(projectId, dataset) + " " + id, record = (transactionId, mutations, tag) => {
+  }, capabilities = capabilitiesOf(target.type), targetLabel = capabilities.label(target.id), { store, history } = ensureEntry(registry, target), concurrentEditKey = (id) => registryKey(target) + " " + id, actorId = () => {
+    const access = activeAccess();
+    if (access !== void 0)
+      return capabilities.identity === "global" ? (access.globalUser ?? access.currentUser).id : access.currentUser.id;
+  };
+  let beforeWrite;
+  const write = (run) => serializeWrite(backend, async () => {
+    beforeWrite = new Map(store.all().map((doc) => [doc._id, doc]));
+    try {
+      return await run();
+    } finally {
+      beforeWrite = void 0;
+    }
+  }), commitHistory = (transactionId) => {
+    beforeWrite !== void 0 && history.commit({ transactionId, author: actorId(), before: beforeWrite, after: store.all() });
+  }, record = (transactionId, mutations, tag) => {
     const effectiveTag = effectiveRequestTag(tag);
-    backend.log.push({
+    commitHistory(transactionId), backend.log.push({
       transactionId,
       projectId,
       dataset,
+      ...resource !== void 0 ? { resource } : {},
       mutations,
       ...effectiveTag !== void 0 ? { tag: effectiveTag } : {}
     });
@@ -1235,10 +1736,10 @@ function makeHandle(handleArgs) {
       document,
       grants: access.grants,
       permission: document._id !== void 0 && isSystemId(document._id) ? "manage" : permission,
-      userId: access.currentUser.id
+      userId: actorId()
     });
   }, guardGate = async (contexts) => {
-    const identity = activeAccess()?.currentUser.id;
+    const identity = actorId();
     await enforceMutationGuards(
       mutationGuard,
       contexts.map((context) => ({ ...context, identity }))
@@ -1251,13 +1752,13 @@ function makeHandle(handleArgs) {
       document,
       grants: access.grants,
       permission: "read",
-      userId: access.currentUser.id
+      userId: actorId()
     });
   }, applyPatch = async (documentId, ops, ifRev, options = {}) => {
     const existing = store.get(documentId);
     if (existing === void 0)
       throw fakeError(
-        `Cannot patch document "${documentId}": not found \u2014 no document with that _id exists in dataset "${projectId}:${dataset}". patch() requires the target to already exist; use createOrReplace() / createIfNotExists() to upsert, or seed the document first.`
+        `Cannot patch document "${documentId}": not found \u2014 no document with that _id exists in ${targetLabel}. patch() requires the target to already exist; use createOrReplace() / createIfNotExists() to upsert, or seed the document first.`
       );
     checkRevision(documentId, ifRev), await gate(existing, "update");
     const patched = applyPatchOps(existing, ops), now = (/* @__PURE__ */ new Date()).toISOString(), next = {
@@ -1278,7 +1779,7 @@ function makeHandle(handleArgs) {
             const promoted = promote2(mut.doc);
             if (store.get(promoted._id) !== void 0)
               throw fakeError(
-                `create() failed: a document with _id "${promoted._id}" already exists in dataset "${projectId}:${dataset}". Use createOrReplace() to overwrite it, or createIfNotExists() to leave the existing one untouched.`
+                `create() failed: a document with _id "${promoted._id}" already exists in ${targetLabel}. Use createOrReplace() to overwrite it, or createIfNotExists() to leave the existing one untouched.`
               );
             await gate(promoted, "create"), store.put(promoted), touchedIds.push(promoted._id), operations.push({ id: promoted._id, operation: "create" });
             break;
@@ -1327,7 +1828,21 @@ function makeHandle(handleArgs) {
       txnOptions?.returnDocuments ?? !1,
       txnOptions?.returnFirst ?? !1
     );
-  }, runAction = (actions) => serializeWrite(backend, async () => applyActions(store, actions, { gate, guard: guardGate })), accessVisibleDocs = async () => {
+  }, runAction = async (actions) => {
+    const request = {
+      method: "POST",
+      path: `${capabilities.dataBase(target.id)}/actions`
+    };
+    if (capabilities.actions !== "served") throw capabilities.actions(request);
+    for (const action of Array.isArray(actions) ? actions : [actions]) {
+      const refused = capabilities.refusedActions[action.actionType];
+      if (refused !== void 0) throw refused(request);
+    }
+    return write(async () => {
+      const result = await applyActions(store, actions, { gate, guard: guardGate });
+      return commitHistory(result.transactionId), result;
+    });
+  }, accessVisibleDocs = async () => {
     const all = store.all();
     if (activeAccess() === void 0) return all;
     const out = [];
@@ -1371,10 +1886,11 @@ function makeHandle(handleArgs) {
       const view = await visibleDocs(effective);
       return ids.map((id) => resolveDocument(view, id, effective) ?? null);
     },
-    create: (doc, opts) => serializeWrite(backend, async () => {
+    getDataUrl: (operation, path) => dataUrl({ resource, dataset, operation, path }),
+    create: (doc, opts) => write(async () => {
       if (checkRevision(doc._id, opts?.ifRevisionId), store.get(doc._id) !== void 0)
         throw fakeError(
-          `create() failed: a document with _id "${doc._id}" already exists in dataset "${projectId}:${dataset}". Use createOrReplace() to overwrite it, or createIfNotExists() to leave the existing one untouched.`
+          `create() failed: a document with _id "${doc._id}" already exists in ${targetLabel}. Use createOrReplace() to overwrite it, or createIfNotExists() to leave the existing one untouched.`
         );
       const promoted = promote2(doc);
       await gate(promoted, "create"), await guardOne("create", null, promoted);
@@ -1386,7 +1902,7 @@ function makeHandle(handleArgs) {
         opts
       );
     }),
-    createOrReplace: (doc, opts) => serializeWrite(backend, async () => {
+    createOrReplace: (doc, opts) => write(async () => {
       checkRevision(doc._id, opts?.ifRevisionId);
       const promoted = promote2(doc), existing = store.get(doc._id);
       await gate(existing ?? promoted, existing !== void 0 ? "update" : "create"), await guardOne(existing !== void 0 ? "update" : "create", existing ?? null, promoted);
@@ -1400,7 +1916,7 @@ function makeHandle(handleArgs) {
         opts
       );
     }),
-    createIfNotExists: (doc, opts) => serializeWrite(backend, async () => {
+    createIfNotExists: (doc, opts) => write(async () => {
       checkRevision(doc._id, opts?.ifRevisionId);
       const existing = store.get(doc._id), transactionId = opts?.transactionId ?? cryptoRandomKey();
       if (existing !== void 0)
@@ -1418,7 +1934,7 @@ function makeHandle(handleArgs) {
         opts
       );
     }),
-    delete: (id, opts) => serializeWrite(backend, async () => {
+    delete: (id, opts) => write(async () => {
       checkRevision(id, opts?.ifRevisionId);
       const existing = store.get(id);
       existing !== void 0 && await gate(existing, "update"), existing !== void 0 && await guardOne("delete", existing, null);
@@ -1433,7 +1949,7 @@ function makeHandle(handleArgs) {
       );
     }),
     patch: (documentId) => createPatch(documentId, {
-      apply: (docId, ops, ifRev, options) => serializeWrite(backend, async () => {
+      apply: (docId, ops, ifRev, options) => write(async () => {
         const doc = await applyPatch(docId, ops, ifRev);
         return record(
           cryptoRandomKey(),
@@ -1450,9 +1966,9 @@ function makeHandle(handleArgs) {
       })
     }),
     transaction: () => createTransaction({
-      apply: (mutations, txnOptions) => serializeWrite(backend, () => applyTransaction(mutations, txnOptions))
+      apply: (mutations, txnOptions) => write(() => applyTransaction(mutations, txnOptions))
     }),
-    mutate: (operations, options) => serializeWrite(backend, () => applyTransaction(toTxnMutations(operations), options)),
+    mutate: (operations, options) => write(() => applyTransaction(toTxnMutations(operations), options)),
     // Synchronous writes still take the lock: an action landing while a
     // guarded patch is parked in its gate would otherwise be clobbered
     // when that patch resumes over its pre-action snapshot.
@@ -1501,15 +2017,30 @@ function makeHandle(handleArgs) {
     ...token !== void 0 || accessControl !== void 0 ? {
       request: makeRequestImpl({
         getAccess: requireActiveAccess,
-        projectId,
-        dataset,
-        useProjectHostname,
-        listIdentities: () => [...backend.identities.values()]
+        // `@sanity/client` sends every request of a `resource`-configured
+        // client to the global API host.
+        useProjectHostname: useProjectHostname && resource === void 0,
+        organizationId: backend.organizationId,
+        listIdentities: () => [...backend.identities.values()],
+        platform: {
+          projectId,
+          organizationId: backend.organizationId,
+          own: (asked) => registryKey(asked) === registryKey(target) ? {
+            grants: requireActiveAccess().grants,
+            documents: () => store.all(),
+            history,
+            canRead
+          } : void 0,
+          actorAccess: () => requireActiveAccess().access,
+          identities: () => [...backend.identities.values()],
+          exists: (asked) => registry.has(registryKey(asked))
+        }
       })
     } : {},
     config: () => ({
       projectId,
       dataset,
+      ...resource !== void 0 ? { resource } : {},
       perspective,
       ...requestTagPrefix !== void 0 ? { requestTagPrefix } : {},
       ...token !== void 0 ? { token } : {},
@@ -1517,11 +2048,12 @@ function makeHandle(handleArgs) {
     }),
     withConfig: (config) => {
       rejectAmbiguousIdentity("withConfig()", config), config.token !== void 0 && requireIdentity(backend, config.token, "withConfig()");
-      const rebinds = config.token !== void 0 || config.accessControl !== void 0;
-      return makeHandle({
+      const rebinds = config.token !== void 0 || config.accessControl !== void 0, nextResource = "resource" in config ? config.resource : resource;
+      return nextResource !== void 0 && validateResource(nextResource), makeHandle({
         backend,
         projectId: config.projectId ?? projectId,
         dataset: config.dataset ?? dataset,
+        resource: nextResource,
         accessControl: rebinds ? config.accessControl : accessControl,
         perspective: config.perspective ?? perspective,
         requestTagPrefix: config.requestTagPrefix ?? requestTagPrefix,
@@ -1539,7 +2071,8 @@ function makeHandle(handleArgs) {
       const editKey = concurrentEditKey(id);
       backend.concurrentEdits.set(editKey, (backend.concurrentEdits.get(editKey) ?? 0) + count);
     },
-    datasets: () => [...registry.keys()].map(parseRegistryKey),
+    datasets: () => [...registry.values()].filter((entry) => entry.resource.type === "dataset").map((entry) => datasetParts(entry.resource.id)),
+    resources: () => [...registry.values()].map((entry) => ({ ...entry.resource })),
     stub: (name, handler) => {
       backend.stubs.set(name, handler);
     },
@@ -1562,7 +2095,13 @@ function makeHandle(handleArgs) {
   return wrapWithGuards(client, {
     getStub: (name) => backend.stubs.get(name),
     onCall: (method, args) => {
-      const rec = { method, args, projectId, dataset }, tag = OPTIONS_ARG_POSITION[method] === void 0 ? void 0 : effectiveRequestTag(tagFromArgs(method, args));
+      const rec = {
+        method,
+        args,
+        projectId,
+        dataset,
+        ...resource !== void 0 ? { resource } : {}
+      }, tag = OPTIONS_ARG_POSITION[method] === void 0 ? void 0 : effectiveRequestTag(tagFromArgs(method, args));
       return tag !== void 0 && (rec.tag = tag), backend.calls.push(rec), (outcome) => {
         "error" in outcome ? rec.error = outcome.error : rec.result = outcome.result;
       };
@@ -1573,6 +2112,7 @@ function makeHandle(handleArgs) {
 export {
   ERR_PREFIX,
   GuardDeniedError,
+  PlatformHttpError,
   SUPPORTED_SURFACE,
   UNSUPPORTED_MEMBERS,
   WriteAccessDeniedError,