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

package/dist/index.cjs

@@ -5,6 +5,516 @@ 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, error: statusMessage, 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 }
+  },
+  "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 }
+  },
+  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 }
+  },
+  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 }
+  }
+};
+function capabilitiesOf(type) {
+  const row = Object.hasOwn(RESOURCE_CAPABILITIES, type) ? RESOURCE_CAPABILITIES[type] : void 0;
+  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 accessResourceOf(resource) {
+  const { access } = capabilitiesOf(resource.type);
+  return { type: access.type, id: access.id(resource.id) };
+}
+function holdsResource(type) {
+  return (registry, id) => registry.resources().some((resource) => {
+    const access = accessResourceOf(resource);
+    return access.type === type && access.id === id;
+  });
+}
+const ACCESS_CAPABILITIES = {
+  organization: {
+    // Proven on staging, but outside what the fake serves: refused like a missing permission.
+    roles: noPermission,
+    users: "served",
+    user: "served",
+    // Granted by the built-in organization `member` role.
+    usersPermission: "sanity.organization.members.read",
+    unknown: {
+      holds: (registry, id) => id === registry.organizationId,
+      refusal: notFound("Organization")
+    },
+    memberRoles: accessEntryRoles("organization"),
+    // Every resource of the family belongs to its organization (see `organizationId`).
+    owns: (registry) => {
+      const byKey = /* @__PURE__ */ new Map();
+      for (const resource of registry.resources()) {
+        const access = accessResourceOf(resource);
+        byKey.set(accessKey(access.type, access.id), access);
+      }
+      return [...byKey.values()];
+    }
+  },
+  project: {
+    roles: "served",
+    users: "served",
+    // Single-user reads are served only where the fake checks members read (the
+    // organization); elsewhere they refuse rather than answer unchecked.
+    user: noPermission,
+    // Every registered identity is a member of every project, with its project roles.
+    memberRoles: ({ identity, id }) => (identity.usersByProject?.[id] ?? identity.user).roles ?? []
+  },
+  "media-library": {
+    // Unproven on staging (no token held roles read): refused like a missing permission.
+    roles: noPermission,
+    users: "served",
+    // Unproven on staging (only the listing was probed); refused as on `project`.
+    user: noPermission,
+    unknown: { holds: holdsResource("media-library"), refusal: notFound("Media library") },
+    memberRoles: accessEntryRoles("media-library")
+  },
+  canvas: {
+    // Unproven on staging (no canvas roles/members permission exists to grant).
+    roles: noPermission,
+    users: noPermission,
+    user: noPermission,
+    unknown: { holds: holdsResource("canvas"), refusal: notFound("Canvas") },
+    memberRoles: accessEntryRoles("canvas")
+  },
+  dashboard: {
+    // Unproven on staging, as for canvas.
+    roles: noPermission,
+    users: noPermission,
+    user: noPermission,
+    unknown: { holds: holdsResource("dashboard"), refusal: notFound("Dashboard") },
+    memberRoles: accessEntryRoles("dashboard")
+  }
+};
+function accessCapabilitiesOf(type) {
+  return Object.hasOwn(ACCESS_CAPABILITIES, type) ? ACCESS_CAPABILITIES[type] : void 0;
+}
+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\/([^/]+)\/([^/]+)(\/.*)?$/, ACCESS_USER_PATH = /^\/users\/([^/]+)$/, DATA_HISTORY_PATH = /^\/data\/history\/([^/]+)(\/.*)$/;
+function page(data) {
+  return { data, nextCursor: null };
+}
+function usersPage(data) {
+  return { ...page(data), totalCount: data.length };
+}
+const UNMODELLED_PROFILE = { provider: "sanity", createdAt: (/* @__PURE__ */ new Date(0)).toISOString() };
+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, row = accessCapabilitiesOf(type);
+  if (row === void 0) throw invalidAccessType(request, type);
+  const resource = { type, id }, registry = {
+    organizationId: ctx.organizationId,
+    resources: ctx.resources
+  }, permissions = ctx.actorAccess()?.[accessKey(resource.type, id)]?.permissions ?? [];
+  if (rest === "/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)])) }
+    };
+  }
+  if (row.unknown !== void 0 && !row.unknown.holds(registry, id))
+    throw row.unknown.refusal(request);
+  const users = (capability, serve) => serveCapability(capability, request, () => {
+    if (row.usersPermission !== void 0 && !permissions.includes(row.usersPermission))
+      throw noPermission(request);
+    return serve();
+  }), user = rest.match(ACCESS_USER_PATH);
+  if (user !== null)
+    return users(row.user, () => {
+      const sanityUserId = decodeURIComponent(user[1]), record = usersOn({ resource, registry, identities: ctx.identities() }).find(
+        (candidate) => candidate.sanityUserId === sanityUserId
+      );
+      if (record === void 0) throw notFound("User")(request);
+      return { value: record };
+    });
+  switch (rest) {
+    case "/roles":
+      return serveCapability(row.roles, request, () => ({
+        value: page(rolesOn({ resource, identities: ctx.identities() }))
+      }));
+    case "/users":
+      return users(row.users, () => ({
+        value: usersPage(usersOn({ resource, registry, identities: ctx.identities() }))
+      }));
+    case "/user-permissions/me":
+      return {
+        value: page(
+          permissions.map((permission) => {
+            const dot = permission.lastIndexOf(".");
+            return {
+              type: permission.slice(0, dot),
+              resourceType: resource.type,
+              resourceId: id,
+              action: permission.slice(dot + 1)
+            };
+          })
+        )
+      };
+    default:
+      return;
+  }
+}
+function rolesOn(args) {
+  const { resource } = args, byName = /* @__PURE__ */ new Map();
+  for (const identity of args.identities) {
+    const roles = ACCESS_CAPABILITIES[resource.type].memberRoles({ identity, id: resource.id });
+    for (const role of roles ?? [])
+      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 membershipOn(identity, resource) {
+  const roles = ACCESS_CAPABILITIES[resource.type].memberRoles({ identity, id: resource.id });
+  if (roles !== void 0)
+    return {
+      resourceType: resource.type,
+      resourceId: resource.id,
+      roleNames: roles.map((role) => role.name).toSorted()
+    };
+}
+function usersOn(args) {
+  const { resource, registry, identities } = args, owned = ACCESS_CAPABILITIES[resource.type].owns?.(registry) ?? [], bySanityUserId = /* @__PURE__ */ new Map();
+  for (const identity of identities) {
+    const own = membershipOn(identity, resource);
+    if (own === void 0) continue;
+    const user = identity.globalUser ?? identity.user, record = {
+      sanityUserId: user.id,
+      profile: {
+        id: user.id,
+        displayName: user.name ?? user.id,
+        email: user.email ?? "",
+        ...UNMODELLED_PROFILE
+      },
+      memberships: [
+        own,
+        // A user is part of a resource only through a role on it.
+        ...owned.flatMap((child) => {
+          const membership = membershipOn(identity, child);
+          return membership === void 0 || membership.roleNames.length === 0 ? [] : [membership];
+        })
+      ]
+    }, 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 ${resource.type} "${resource.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;
@@ -61,6 +571,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;
 }
@@ -124,16 +640,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)
@@ -146,10 +665,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[/<id>] | 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.`
     );
   };
 }
@@ -413,7 +935,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));
@@ -425,6 +948,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) {
@@ -858,6 +1395,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 = {
@@ -877,10 +1415,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()`."
@@ -907,7 +1441,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?",
@@ -1065,13 +1599,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: [],
@@ -1079,21 +1632,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,
@@ -1155,39 +1710,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 } : {}
     });
@@ -1237,10 +1805,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 }))
@@ -1253,13 +1821,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 = {
@@ -1280,7 +1848,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;
@@ -1329,7 +1897,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 = [];
@@ -1373,10 +1955,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);
@@ -1388,7 +1971,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);
@@ -1402,7 +1985,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)
@@ -1420,7 +2003,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);
@@ -1435,7 +2018,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(),
@@ -1452,9 +2035,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.
@@ -1503,15 +2086,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()],
+          resources: () => [...registry.values()].map((entry) => entry.resource)
+        }
       })
     } : {},
     config: () => ({
       projectId,
       dataset,
+      ...resource !== void 0 ? { resource } : {},
       perspective,
       ...requestTagPrefix !== void 0 ? { requestTagPrefix } : {},
       ...token !== void 0 ? { token } : {},
@@ -1519,11 +2117,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,
@@ -1541,7 +2140,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);
     },
@@ -1564,7 +2164,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;
       };
@@ -1574,6 +2180,7 @@ function makeHandle(handleArgs) {
 }
 exports.ERR_PREFIX = ERR_PREFIX;
 exports.GuardDeniedError = GuardDeniedError;
+exports.PlatformHttpError = PlatformHttpError;
 exports.SUPPORTED_SURFACE = SUPPORTED_SURFACE;
 exports.UNSUPPORTED_MEMBERS = UNSUPPORTED_MEMBERS;
 exports.WriteAccessDeniedError = WriteAccessDeniedError;