@sanity-labs/client-fake-for-test 0.8.0 → 0.9.1

package/README.md

@@ -77,10 +77,10 @@ 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? }` |
-| Config | `withConfig({ projectId?, dataset?, perspective?, accessControl?, token? })` | 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 |
+| 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` + the configured ACL path. Calling it without one throws a guidance error. |
+| 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, and `/projects/<projectId>/users/<ids>` (project-user records with `id` + `sanityUserId`). Calling it without one throws a guidance error. |
 
 #### Mutation return shapes
 
@@ -117,6 +117,9 @@ await client.patch("article-1").set({ title: "ok" }).commit(); // allowed
 await expect(client.patch("article-1").set({ body: "no" }).commit()).rejects.toThrow();
 ```
 
+> [!NOTE]
+> Treat `before` / `after` as read-only — they are the live store images, not copies; mutating them corrupts the store.
+
 #### Identity is the token
 
 `identity` is the id of the handle's acting identity. To act as different users against the **same** store (e.g. to exercise `identity()`-based guards), register a token→identity registry and mint token-scoped siblings — the token determines identity, exactly like production:
@@ -137,8 +140,29 @@ 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).
 
-> [!NOTE]
-> Treat `before` / `after` as read-only — they are the live store images, not copies; mutating them corrupts the store.
+#### 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`):
+
+```ts
+const client = createTestClient({
+  projectId: "alpha",
+  token: "t-snorre",
+  identities: {
+    "t-snorre": {
+      user: { id: "pDefault" },
+      globalUser: { id: "gSnorre" },
+      usersByProject: { alpha: { id: "pAlpha" }, beta: { id: "pBeta" } },
+      grants,
+    },
+  },
+});
+await client.request({ uri: "/users/me" }); // { id: "pAlpha", ... }
+await client.withConfig({ useProjectHostname: false }).request({ uri: "/users/me" }); // { id: "gSnorre", ... }
+await client.request({ uri: "/projects/alpha/users/pAlpha" }); // { id: "pAlpha", sanityUserId: "gSnorre", ... } (ProjectUserRecord)
+```
+
+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.
 
 ### Test-only helpers (not on real `SanityClient`)
 

package/dist/index.cjs

@@ -61,15 +61,62 @@ async function enforceWriteAccess(args) {
 function defaultAclPath(projectId, dataset) {
   return `/projects/${projectId}/datasets/${dataset}/acl`;
 }
-function makeRequestImpl(getAccess, projectId, dataset) {
+function projectUserOf(identity, projectId) {
+  return identity.usersByProject?.[projectId] ?? identity.user;
+}
+function serveProjectUsers(args) {
+  const { requestedIds, pathProjectId, identities } = args, toRecord = (identity) => {
+    const projectUser = projectUserOf(identity, pathProjectId);
+    return {
+      id: projectUser.id,
+      sanityUserId: identity.globalUser?.id ?? projectUser.id,
+      displayName: projectUser.name ?? projectUser.id,
+      ...projectUser.email !== void 0 ? { email: projectUser.email } : {}
+    };
+  }, byId = /* @__PURE__ */ new Map();
+  for (const identity of identities) {
+    const resolvedId = projectUserOf(identity, pathProjectId).id, existing = byId.get(resolvedId);
+    if (existing !== void 0 && JSON.stringify(toRecord(existing)) !== JSON.stringify(toRecord(identity)))
+      throw fakeError(
+        `request(): two registered identities resolve to project user "${resolvedId}" in project "${pathProjectId}" with different records. The directory cannot answer unambiguously \u2014 fix the identity registrations so duplicate ids carry identical records.`
+      );
+    byId.set(resolvedId, identity);
+  }
+  const ids = requestedIds.split(","), [firstId] = ids;
+  if (ids.length === 1 && firstId !== void 0) {
+    const identity = byId.get(firstId);
+    if (identity === void 0)
+      throw Object.assign(
+        fakeError(
+          `request(): no registered identity resolves to project user "${firstId}" in project "${pathProjectId}". Register it via createTestClient({ identities }) or addIdentity().`
+        ),
+        { statusCode: 404 }
+      );
+    return toRecord(identity);
+  }
+  return ids.flatMap((id) => {
+    const identity = byId.get(id);
+    return identity === void 0 ? [] : [toRecord(identity)];
+  });
+}
+const PROJECT_USERS_PATH = /^\/projects\/([^/]+)\/users\/([^/]+)$/;
+function makeRequestImpl(ctx) {
+  const { getAccess, projectId, dataset, useProjectHostname, listIdentities } = ctx;
   return async (opts) => {
     const accessControl = getAccess(), aclPath = accessControl.aclPath ?? defaultAclPath(projectId, dataset), path = opts.uri ?? opts.url;
     if (path === "/users/me")
-      return accessControl.currentUser;
+      return useProjectHostname ? accessControl.currentUser : accessControl.globalUser ?? accessControl.currentUser;
     if (path === aclPath)
       return accessControl.grants;
+    const projectUsers = path?.match(PROJECT_USERS_PATH), [, pathProjectId, requestedIds] = projectUsers ?? [];
+    if (pathProjectId !== void 0 && requestedIds !== void 0)
+      return serveProjectUsers({
+        requestedIds,
+        pathProjectId,
+        identities: listIdentities()
+      });
     throw fakeError(
-      `request(): no handler for path "${path}". With access control configured, the fake only serves "/users/me" and "${aclPath}". 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", "${aclPath}", 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.`
     );
   };
 }
@@ -780,7 +827,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). 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, and /projects/<projectId>/users/<ids>). Or register a stub."
   },
   dryRun: {
     what: "not a method \u2014 did you mean the `{ dryRun }` mutation option?",
@@ -963,15 +1010,17 @@ function createTestClient(options = {}) {
       const { projectId, dataset } = parseRegistryKey(key);
       ensureStore(projectId, dataset).seed(docs);
     }
-  return makeHandle(
+  return makeHandle({
     backend,
-    defaultProjectId,
-    defaultDataset,
-    options.accessControl,
-    options.perspective ?? "raw",
-    options.mutationGuard,
-    options.token
-  );
+    projectId: defaultProjectId,
+    dataset: defaultDataset,
+    accessControl: options.accessControl,
+    perspective: options.perspective ?? "raw",
+    requestTagPrefix: options.requestTagPrefix,
+    mutationGuard: options.mutationGuard,
+    token: options.token,
+    useProjectHostname: options.useProjectHostname ?? !0
+  });
 }
 function dedupeIds(results) {
   const seen = /* @__PURE__ */ new Set(), out = [];
@@ -1023,13 +1072,27 @@ function toTxnMutations(operations) {
     }
   ];
 }
-function makeHandle(backend, projectId, dataset, accessControl, perspective, mutationGuard, token) {
-  const { registry } = backend, activeAccess = () => {
+function makeHandle(handleArgs) {
+  const {
+    backend,
+    projectId,
+    dataset,
+    accessControl,
+    perspective,
+    requestTagPrefix,
+    mutationGuard,
+    token,
+    useProjectHostname
+  } = handleArgs, { registry } = backend, 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: identity.user, grants: identity.grants };
+    return {
+      currentUser: projectUserOf(identity, projectId),
+      ...identity.globalUser !== void 0 ? { globalUser: identity.globalUser } : {},
+      grants: identity.grants
+    };
   }, requireActiveAccess = () => {
     const access = activeAccess();
     if (access === void 0)
@@ -1040,14 +1103,15 @@ function makeHandle(backend, projectId, dataset, accessControl, perspective, mut
     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) => {
+    const effectiveTag = effectiveRequestTag(tag);
     backend.log.push({
       transactionId,
       projectId,
       dataset,
       mutations,
-      ...tag !== void 0 ? { tag } : {}
+      ...effectiveTag !== void 0 ? { tag: effectiveTag } : {}
     });
-  }, writeResult = (documents, results, transactionId, opts) => formatMutationResult(
+  }, effectiveRequestTag = (tag) => requestTagPrefix === void 0 ? tag : tag ? `${requestTagPrefix}.${tag}` : requestTagPrefix, writeResult = (documents, results, transactionId, opts) => formatMutationResult(
     documents,
     results,
     transactionId,
@@ -1350,20 +1414,37 @@ function makeHandle(backend, projectId, dataset, accessControl, perspective, mut
       versionId: `versions.${releaseId}.${publishedId}`,
       publishedId
     }),
-    ...token !== void 0 || accessControl !== void 0 ? { request: makeRequestImpl(requireActiveAccess, projectId, dataset) } : {},
-    config: () => ({ projectId, dataset, perspective, ...token !== void 0 ? { token } : {} }),
+    ...token !== void 0 || accessControl !== void 0 ? {
+      request: makeRequestImpl({
+        getAccess: requireActiveAccess,
+        projectId,
+        dataset,
+        useProjectHostname,
+        listIdentities: () => [...backend.identities.values()]
+      })
+    } : {},
+    config: () => ({
+      projectId,
+      dataset,
+      perspective,
+      ...requestTagPrefix !== void 0 ? { requestTagPrefix } : {},
+      ...token !== void 0 ? { token } : {},
+      useProjectHostname
+    }),
     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(
+      return makeHandle({
         backend,
-        config.projectId ?? projectId,
-        config.dataset ?? dataset,
-        rebinds ? config.accessControl : accessControl,
-        config.perspective ?? perspective,
+        projectId: config.projectId ?? projectId,
+        dataset: config.dataset ?? dataset,
+        accessControl: rebinds ? config.accessControl : accessControl,
+        perspective: config.perspective ?? perspective,
+        requestTagPrefix: config.requestTagPrefix ?? requestTagPrefix,
         mutationGuard,
-        rebinds ? config.token : token
-      );
+        token: rebinds ? config.token : token,
+        useProjectHostname: config.useProjectHostname ?? useProjectHostname
+      });
     },
     seed: (documents) => store.seed(documents),
     add: (documents) => store.add(documents),
@@ -1397,7 +1478,7 @@ function makeHandle(backend, projectId, dataset, accessControl, perspective, mut
   return wrapWithGuards(client, {
     getStub: (name) => backend.stubs.get(name),
     onCall: (method, args) => {
-      const rec = { method, args, projectId, dataset }, tag = tagFromArgs(method, args);
+      const rec = { method, args, projectId, dataset }, 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;
       };