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

package/dist/index.d.cts

@@ -107,8 +107,9 @@ export declare interface CreateTestClientOptions {
   datasets?: Record<string, SanityDocumentLike[]>;
   /**
    * Opt-in access-control simulation. When set, the client exposes
-   * `request({ url })` that serves `/users/me` + the configured ACL
-   * path, AND every mutation is gated through the supplied `grants`
+   * `request({ url })` that serves `/users/me` (host-aware), the
+   * configured ACL path, and `/projects/<projectId>/users/<ids>`,
+   * AND every mutation is gated through the supplied `grants`
    * — writes that the grants don't permit throw a `WriteAccessDeniedError`
    * shaped like Sanity's 403. Lets tests demonstrate the full
    * "engine soft-gate + lake hard-gate" contract end-to-end without
@@ -165,6 +166,16 @@ export declare interface CreateTestClientOptions {
    * tests stay green.
    */
   perspective?: Perspective;
+  /** Prefix composed with request tags and used alone for untagged requests. */
+  requestTagPrefix?: string;
+  /**
+   * Which API host the root handle models: the project host (default
+   * `true`) or the global host (`false`) — same flag as the real
+   * `createClient` config. A global-hosted handle's `/users/me` serves
+   * the identity's account-global record. `withConfig({ useProjectHostname })`
+   * mints siblings on the other host.
+   */
+  useProjectHostname?: boolean;
 }
 
 /**
@@ -583,6 +594,19 @@ export declare type PatchOp =
 
 export declare type Perspective = "raw" | "published" | "drafts" | string[];
 
+/**
+ * A row served by the project-users directory endpoint
+ * (`/projects/<projectId>/users/<id>`), mirroring Sanity's project user
+ * retrieval API: the project-scoped `id` alongside its account-global
+ * `sanityUserId` — the one sanctioned bridge between the two namespaces.
+ */
+export declare interface ProjectUserRecord {
+  id: string;
+  sanityUserId: string;
+  displayName: string;
+  email?: string;
+}
+
 /** Strip `drafts.` / `versions.<name>.` prefix to recover the published id. */
 export declare function publishedIdOf(id: string): string;
 
@@ -843,14 +867,17 @@ export declare interface TestClient {
     publishedId: string;
   }) => Promise<ActionResult>;
   /**
-   * Current `(projectId, dataset)` and active perspective. `token` is
-   * present iff the handle is bound to a registered identity.
+   * Current `(projectId, dataset)`, active perspective, and which API host
+   * the handle models (`useProjectHostname`). `token` is present iff the
+   * handle is bound to a registered identity.
    */
   config: () => {
     projectId: string;
     dataset: string;
     perspective: Perspective;
+    requestTagPrefix?: string;
     token?: string;
+    useProjectHostname: boolean;
   };
   /**
    * Return a new client handle pointing at a different `(projectId, dataset)`
@@ -863,6 +890,16 @@ export declare interface TestClient {
       projectId: string;
       dataset: string;
       perspective: Perspective;
+      /** Prefix composed with request tags and used alone for untagged requests. */
+      requestTagPrefix: string;
+      /**
+       * Model the global API host (`false`) instead of the project host
+       * (default `true`). A global-hosted sibling's `/users/me` serves the
+       * identity's account-global record (`globalUser`, falling back to the
+       * project record) — mirroring `@sanity/client`, where a non-project
+       * config routes requests to `api.sanity.io`.
+       */
+      useProjectHostname: boolean;
       /**
        * Rebind the acting identity (and its grants) on a sibling that shares
        * the same store — the test analogue of a token-scoped client. Lets two
@@ -873,10 +910,11 @@ export declare interface TestClient {
       /**
        * Bind the sibling to a token registered in the family's identity
        * registry (`createTestClient({ identities })` / `addIdentity`): its
-       * `/users/me` serves that identity's user, its ACL path serves that
-       * identity's grants, and reads/writes are gated through them — the
-       * token determines identity, exactly like production. Unknown tokens
-       * throw. Mutually exclusive with `accessControl`.
+       * `/users/me` serves that identity's record for the sibling's project
+       * and host, its ACL path serves that identity's grants, and
+       * reads/writes are gated through them — the token determines
+       * identity, exactly like production. Unknown tokens throw. Mutually
+       * exclusive with `accessControl`.
        */
       token: string;
     }>,
@@ -970,8 +1008,18 @@ export declare interface TestClient {
 }
 
 export declare interface TestClientAccessControl {
-  /** What `client.request({ url: "/users/me" })` returns. */
+  /** What `client.request({ url: "/users/me" })` returns on a project-hosted handle. */
   currentUser: CurrentUser;
+  /**
+   * What `/users/me` returns on a global-hosted handle
+   * (`useProjectHostname: false`, at creation or via `withConfig`).
+   * Sanity serves the
+   * account-global user there (`g*` id, no roles) while the project host
+   * serves the project-scoped record (`p*` id, project roles). Omit to
+   * serve `currentUser` from both — the single-id collapse that is also
+   * exactly how robot tokens behave in production.
+   */
+  globalUser?: CurrentUser;
   /** What `client.request({ url: aclPath })` returns. */
   grants: Grant[];
   /**
@@ -984,13 +1032,36 @@ export declare interface TestClientAccessControl {
 /**
  * One entry in the token→identity registry (`createTestClient({ identities })`).
  * A handle bound to the entry's token behaves exactly like one configured
- * with `accessControl: { currentUser: user, grants }` — `/users/me` serves
- * `user`, the default ACL path serves `grants`, and reads/writes are gated
- * through them.
+ * with `accessControl: { currentUser: projectUserOf(identity, projectId),
+ * globalUser, grants }` — `/users/me` serves the record for the handle's
+ * project and host, the default ACL path serves `grants`, and reads/writes
+ * are gated through them.
  */
 export declare interface TestClientIdentity {
-  /** What `/users/me` returns for clients bound to this token. */
+  /**
+   * The project-scoped user record: what `/users/me` returns on a
+   * project-hosted handle, and the id `identity()` resolves to in grant
+   * filters and mutation guards. Per-project variants go in
+   * `usersByProject`; this is the record for any project without one.
+   */
   user: CurrentUser;
+  /**
+   * The account-global user record, served by `/users/me` on a
+   * global-hosted handle (`useProjectHostname: false`, at creation or
+   * via `withConfig`).
+   * The same person carries a different id per project (`p*`) and one
+   * global id (`g*`); registering both lets tests model that split.
+   * Omit for single-id principals (robot tokens resolve to one `p-*` id
+   * on every host).
+   */
+  globalUser?: CurrentUser;
+  /**
+   * Per-project user records, keyed by projectId — the same token
+   * resolves to a different project-scoped id in each project, which is
+   * what these model. A handle's project falls back to `user` when its
+   * projectId has no entry.
+   */
+  usersByProject?: Record<string, CurrentUser>;
   /** Grants served at the ACL path and enforced on reads/writes. */
   grants: Grant[];
 }

package/dist/index.d.ts

@@ -107,8 +107,9 @@ export declare interface CreateTestClientOptions {
   datasets?: Record<string, SanityDocumentLike[]>;
   /**
    * Opt-in access-control simulation. When set, the client exposes
-   * `request({ url })` that serves `/users/me` + the configured ACL
-   * path, AND every mutation is gated through the supplied `grants`
+   * `request({ url })` that serves `/users/me` (host-aware), the
+   * configured ACL path, and `/projects/<projectId>/users/<ids>`,
+   * AND every mutation is gated through the supplied `grants`
    * — writes that the grants don't permit throw a `WriteAccessDeniedError`
    * shaped like Sanity's 403. Lets tests demonstrate the full
    * "engine soft-gate + lake hard-gate" contract end-to-end without
@@ -165,6 +166,16 @@ export declare interface CreateTestClientOptions {
    * tests stay green.
    */
   perspective?: Perspective;
+  /** Prefix composed with request tags and used alone for untagged requests. */
+  requestTagPrefix?: string;
+  /**
+   * Which API host the root handle models: the project host (default
+   * `true`) or the global host (`false`) — same flag as the real
+   * `createClient` config. A global-hosted handle's `/users/me` serves
+   * the identity's account-global record. `withConfig({ useProjectHostname })`
+   * mints siblings on the other host.
+   */
+  useProjectHostname?: boolean;
 }
 
 /**
@@ -583,6 +594,19 @@ export declare type PatchOp =
 
 export declare type Perspective = "raw" | "published" | "drafts" | string[];
 
+/**
+ * A row served by the project-users directory endpoint
+ * (`/projects/<projectId>/users/<id>`), mirroring Sanity's project user
+ * retrieval API: the project-scoped `id` alongside its account-global
+ * `sanityUserId` — the one sanctioned bridge between the two namespaces.
+ */
+export declare interface ProjectUserRecord {
+  id: string;
+  sanityUserId: string;
+  displayName: string;
+  email?: string;
+}
+
 /** Strip `drafts.` / `versions.<name>.` prefix to recover the published id. */
 export declare function publishedIdOf(id: string): string;
 
@@ -843,14 +867,17 @@ export declare interface TestClient {
     publishedId: string;
   }) => Promise<ActionResult>;
   /**
-   * Current `(projectId, dataset)` and active perspective. `token` is
-   * present iff the handle is bound to a registered identity.
+   * Current `(projectId, dataset)`, active perspective, and which API host
+   * the handle models (`useProjectHostname`). `token` is present iff the
+   * handle is bound to a registered identity.
    */
   config: () => {
     projectId: string;
     dataset: string;
     perspective: Perspective;
+    requestTagPrefix?: string;
     token?: string;
+    useProjectHostname: boolean;
   };
   /**
    * Return a new client handle pointing at a different `(projectId, dataset)`
@@ -863,6 +890,16 @@ export declare interface TestClient {
       projectId: string;
       dataset: string;
       perspective: Perspective;
+      /** Prefix composed with request tags and used alone for untagged requests. */
+      requestTagPrefix: string;
+      /**
+       * Model the global API host (`false`) instead of the project host
+       * (default `true`). A global-hosted sibling's `/users/me` serves the
+       * identity's account-global record (`globalUser`, falling back to the
+       * project record) — mirroring `@sanity/client`, where a non-project
+       * config routes requests to `api.sanity.io`.
+       */
+      useProjectHostname: boolean;
       /**
        * Rebind the acting identity (and its grants) on a sibling that shares
        * the same store — the test analogue of a token-scoped client. Lets two
@@ -873,10 +910,11 @@ export declare interface TestClient {
       /**
        * Bind the sibling to a token registered in the family's identity
        * registry (`createTestClient({ identities })` / `addIdentity`): its
-       * `/users/me` serves that identity's user, its ACL path serves that
-       * identity's grants, and reads/writes are gated through them — the
-       * token determines identity, exactly like production. Unknown tokens
-       * throw. Mutually exclusive with `accessControl`.
+       * `/users/me` serves that identity's record for the sibling's project
+       * and host, its ACL path serves that identity's grants, and
+       * reads/writes are gated through them — the token determines
+       * identity, exactly like production. Unknown tokens throw. Mutually
+       * exclusive with `accessControl`.
        */
       token: string;
     }>,
@@ -970,8 +1008,18 @@ export declare interface TestClient {
 }
 
 export declare interface TestClientAccessControl {
-  /** What `client.request({ url: "/users/me" })` returns. */
+  /** What `client.request({ url: "/users/me" })` returns on a project-hosted handle. */
   currentUser: CurrentUser;
+  /**
+   * What `/users/me` returns on a global-hosted handle
+   * (`useProjectHostname: false`, at creation or via `withConfig`).
+   * Sanity serves the
+   * account-global user there (`g*` id, no roles) while the project host
+   * serves the project-scoped record (`p*` id, project roles). Omit to
+   * serve `currentUser` from both — the single-id collapse that is also
+   * exactly how robot tokens behave in production.
+   */
+  globalUser?: CurrentUser;
   /** What `client.request({ url: aclPath })` returns. */
   grants: Grant[];
   /**
@@ -984,13 +1032,36 @@ export declare interface TestClientAccessControl {
 /**
  * One entry in the token→identity registry (`createTestClient({ identities })`).
  * A handle bound to the entry's token behaves exactly like one configured
- * with `accessControl: { currentUser: user, grants }` — `/users/me` serves
- * `user`, the default ACL path serves `grants`, and reads/writes are gated
- * through them.
+ * with `accessControl: { currentUser: projectUserOf(identity, projectId),
+ * globalUser, grants }` — `/users/me` serves the record for the handle's
+ * project and host, the default ACL path serves `grants`, and reads/writes
+ * are gated through them.
  */
 export declare interface TestClientIdentity {
-  /** What `/users/me` returns for clients bound to this token. */
+  /**
+   * The project-scoped user record: what `/users/me` returns on a
+   * project-hosted handle, and the id `identity()` resolves to in grant
+   * filters and mutation guards. Per-project variants go in
+   * `usersByProject`; this is the record for any project without one.
+   */
   user: CurrentUser;
+  /**
+   * The account-global user record, served by `/users/me` on a
+   * global-hosted handle (`useProjectHostname: false`, at creation or
+   * via `withConfig`).
+   * The same person carries a different id per project (`p*`) and one
+   * global id (`g*`); registering both lets tests model that split.
+   * Omit for single-id principals (robot tokens resolve to one `p-*` id
+   * on every host).
+   */
+  globalUser?: CurrentUser;
+  /**
+   * Per-project user records, keyed by projectId — the same token
+   * resolves to a different project-scoped id in each project, which is
+   * what these model. A handle's project falls back to `user` when its
+   * projectId has no entry.
+   */
+  usersByProject?: Record<string, CurrentUser>;
   /** Grants served at the ACL path and enforced on reads/writes. */
   grants: Grant[];
 }

package/dist/index.js

@@ -59,15 +59,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.`
     );
   };
 }
@@ -778,7 +825,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?",
@@ -961,15 +1008,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 = [];
@@ -1021,13 +1070,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)
@@ -1038,14 +1101,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,
@@ -1348,20 +1412,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),
@@ -1395,7 +1476,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;
       };