@sanity-labs/client-fake-for-test 0.0.0

package/dist/index.d.ts

@@ -0,0 +1,465 @@
+/**
+ * Apply an ordered list of patch ops to a document, returning the new doc.
+ *
+ * The path semantics are deliberately a small subset:
+ *
+ * - **Dotted paths** (`a.b.c`) for nested object fields.
+ * - **Array index** (`a.b[0]`) for positional access into arrays.
+ * - **Keyed lookup** (`a.b[_key=="x"]`) for finding an array entry by `_key`.
+ *
+ * Anything more exotic (recursive `..`, GROQ filter expressions, multi-match)
+ * is intentionally out of scope and will throw — the workflow engine only
+ * needs the three forms above.
+ */
+export declare function applyPatchOps(
+  doc: SanityDocument,
+  ops: PatchOp[],
+): SanityDocument;
+
+export declare function createPatch(
+  documentId: string,
+  executor: PatchExecutor,
+): PatchHandle;
+
+/**
+ * Create a fresh, isolated test client backed by a private multi-dataset
+ * registry. `withConfig` returns a sibling handle into the same registry.
+ *
+ * ```
+ * const client = createTestClient({
+ *   datasets: {
+ *     "test:definitions": [...],
+ *     "test:instances": [...],
+ *   },
+ * });
+ * const defs = client.withConfig({ dataset: "definitions" });
+ * const inst = client.withConfig({ dataset: "instances" });
+ * ```
+ */
+export declare function createTestClient(
+  options?: CreateTestClientOptions,
+): TestClient;
+
+export declare interface CreateTestClientOptions {
+  /** Default project id. Defaults to `"test"`. */
+  projectId?: string;
+  /** Default dataset name. Defaults to `"test"`. */
+  dataset?: string;
+  /** Documents to seed into the default `(projectId, dataset)` store. */
+  documents?: SanityDocumentLike[];
+  /**
+   * Optional: seed multiple datasets at once. Keys are `"projectId:dataset"`
+   * pairs. Useful when workflows span multiple datasets.
+   */
+  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`
+   * — 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
+   * a real HTTP round-trip.
+   *
+   * When omitted, `request` is undefined and all writes proceed
+   * unconditionally — the legacy behavior.
+   */
+  accessControl?: TestClientAccessControl;
+}
+
+/**
+ * Create a fresh, isolated store. The returned object closes over a private
+ * Map; two stores created from two calls do not see each other.
+ */
+export declare function createTestStore(
+  initial?: SanityDocumentLike[],
+): TestStore;
+
+export declare function createTransaction(
+  executor: TxnExecutor,
+): TransactionHandle;
+
+export declare interface CurrentUser {
+  id: string;
+  name?: string;
+  email?: string;
+  /** @deprecated singular `role` on legacy responses */
+  role?: string;
+  roles?: {
+    name: string;
+    title?: string;
+    description?: string;
+  }[];
+}
+
+/**
+ * Default ACL path the engine pulls grants from. Mirrors Sanity's
+ * project/dataset ACL endpoint. Callers can override via
+ * `accessControl.aclPath`.
+ */
+export declare function defaultAclPath(
+  projectId: string,
+  dataset: string,
+): string;
+
+export declare type DocumentValuePermission = "create" | "read" | "update";
+
+/**
+ * Resolve whether `grants` allow `permission` on `document` for the
+ * given user. Same logic the engine uses in `permissions.grantsPermissionOn`
+ * (most-permissive wins; multiple grants compose).
+ *
+ * Returns `{ allowed: boolean, matchingGrants: number }` so callers
+ * can build the structured error without re-counting.
+ */
+export declare function evaluateWriteAccess(args: {
+  document: SanityDocumentLike & {
+    _id?: string;
+    _type?: string;
+  };
+  grants: Grant[];
+  permission: DocumentValuePermission;
+  userId: string;
+}): Promise<{
+  allowed: boolean;
+  matchingGrants: number;
+}>;
+
+export declare interface Grant {
+  filter: string;
+  permissions: DocumentValuePermission[];
+}
+
+export declare interface MutationOptions {
+  ifRevisionId?: string;
+}
+
+export declare interface PatchExecutor {
+  apply: (
+    documentId: string,
+    ops: PatchOp[],
+    ifRev: string | undefined,
+  ) => Promise<SanityDocument>;
+}
+
+export declare interface PatchHandle {
+  set: (props: Record<string, unknown>) => PatchHandle;
+  setIfMissing: (props: Record<string, unknown>) => PatchHandle;
+  unset: (paths: string[]) => PatchHandle;
+  inc: (props: Record<string, number>) => PatchHandle;
+  dec: (props: Record<string, number>) => PatchHandle;
+  insert: (
+    position: "before" | "after" | "replace",
+    anchor: string,
+    items: unknown[],
+  ) => PatchHandle;
+  ifRevisionId: (rev: string) => PatchHandle;
+  commit: () => Promise<SanityDocument>;
+  /** Test-only introspection — not on real Patch */
+  toJSON: () => {
+    id: string;
+    ops: PatchOp[];
+    ifRev?: string;
+  };
+}
+
+/**
+ * Patch operations the test client supports.
+ *
+ * Subset of `@sanity/client`'s PatchOperations. Each entry is one
+ * mutation step applied in order at commit time.
+ */
+export declare type PatchOp =
+  | {
+      kind: "set";
+      props: Record<string, unknown>;
+    }
+  | {
+      kind: "setIfMissing";
+      props: Record<string, unknown>;
+    }
+  | {
+      kind: "unset";
+      paths: string[];
+    }
+  | {
+      kind: "inc";
+      props: Record<string, number>;
+    }
+  | {
+      kind: "dec";
+      props: Record<string, number>;
+    }
+  | {
+      kind: "insert";
+      position: "before" | "after" | "replace";
+      anchor: string;
+      items: unknown[];
+    };
+
+/** @public */
+declare interface SanityDocument {
+  _id: string;
+  _type: string;
+  _createdAt: string;
+  _updatedAt: string;
+  _rev: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Similar to `SanityDocument` but only requires the `_id` and `_type`
+ *
+ * @see SanityDocument
+ *
+ * @public
+ */
+declare interface SanityDocumentLike {
+  _id: string;
+  _type: string;
+  _createdAt?: string;
+  _updatedAt?: string;
+  _rev?: string;
+  _system?: {
+    delete?: boolean;
+  };
+  [key: string]: unknown;
+}
+
+export declare interface SystemFields {
+  _rev: string;
+  _createdAt: string;
+  _updatedAt: string;
+}
+
+/**
+ * Data-plane subset of `@sanity/client`'s surface, with multi-dataset support.
+ *
+ * One `createTestClient()` call creates a registry of stores keyed by
+ * `(projectId, dataset)`. The returned client points at one of them.
+ * `withConfig({ projectId, dataset })` returns a new handle into the same
+ * registry but pointing at a different store — useful for workflows where
+ * definitions live in one dataset and instances live in another.
+ *
+ * Two separate `createTestClient()` calls have separate registries, so
+ * tests stay isolated from each other.
+ *
+ * Methods not on the real client:
+ *
+ * - `seed`, `add`, `reset`, `snapshot`, `store` — bulk-load helpers,
+ *   scoped to the current dataset.
+ * - `datasets()` — lists known dataset keys in this registry.
+ *
+ * Methods deliberately omitted:
+ *
+ * - Project / agent / asset / live / listen APIs.
+ * - Perspective handling.
+ */
+export declare interface TestClient {
+  fetch: <T = unknown>(
+    query: string,
+    params?: Record<string, unknown>,
+  ) => Promise<T>;
+  getDocument: <T = SanityDocument>(id: string) => Promise<T | null>;
+  getDocuments: <T = SanityDocument>(ids: string[]) => Promise<(T | null)[]>;
+  /**
+   * Sanity-style HTTP request hook. Present iff the client was
+   * created with `accessControl`. The engine's access resolver pokes
+   * `/users/me` and the configured ACL path through this — without it
+   * the engine throws on any verb that needs an actor (which is the
+   * cue for the bench to supply an `access` override).
+   *
+   * Test cases that want to exercise the engine's token-resolution
+   * path should configure `accessControl`; cases that want bench-style
+   * always-allow should leave it off and pass `access` through the
+   * bench.
+   */
+  request?: <T>(opts: {
+    url?: string;
+    uri?: string;
+    signal?: AbortSignal;
+    tag?: string;
+  }) => Promise<T>;
+  create: <T extends SanityDocumentLike>(
+    doc: T,
+    options?: MutationOptions,
+  ) => Promise<T & SystemFields>;
+  createOrReplace: <T extends SanityDocumentLike>(
+    doc: T,
+    options?: MutationOptions,
+  ) => Promise<T & SystemFields>;
+  createIfNotExists: <T extends SanityDocumentLike>(
+    doc: T,
+    options?: MutationOptions,
+  ) => Promise<T & SystemFields>;
+  delete: (
+    id: string,
+    options?: MutationOptions,
+  ) => Promise<{
+    _id: string;
+  } | null>;
+  patch: (documentId: string) => PatchHandle;
+  transaction: () => TransactionHandle;
+  /** Current `(projectId, dataset)`. */
+  config: () => {
+    projectId: string;
+    dataset: string;
+  };
+  /**
+   * Return a new client handle pointing at a different `(projectId, dataset)`
+   * within the SAME backing registry. Either field can be omitted to keep
+   * the current value. Two clients produced by `withConfig` see each
+   * other's writes if they point at the same `(projectId, dataset)`.
+   */
+  withConfig: (
+    config: Partial<{
+      projectId: string;
+      dataset: string;
+    }>,
+  ) => TestClient;
+  /** Replace the current dataset with the given documents. */
+  seed: (documents: SanityDocumentLike[]) => void;
+  /** Add documents to the current dataset without dropping existing ones. */
+  add: (documents: SanityDocumentLike[]) => void;
+  /** Drop all documents in the current dataset. */
+  reset: () => void;
+  /** Read-only snapshot of all documents in the current dataset. */
+  snapshot: () => readonly SanityDocument[];
+  /** Direct store access for the current dataset. */
+  store: () => TestStore;
+  /** List `(projectId, dataset)` pairs known in this registry. */
+  datasets: () => {
+    projectId: string;
+    dataset: string;
+  }[];
+}
+
+export declare interface TestClientAccessControl {
+  /** What `client.request({ url: "/users/me" })` returns. */
+  currentUser: CurrentUser;
+  /** What `client.request({ url: aclPath })` returns. */
+  grants: Grant[];
+  /**
+   * URL path the engine's access resolver hits to fetch grants.
+   * Defaults to `/projects/<projectId>/datasets/<dataset>/acl`.
+   */
+  aclPath?: string;
+}
+
+/**
+ * In-memory document store backing a TestClient. Closure-scoped — created
+ * fresh per test, no global state.
+ *
+ * The shape mirrors what `groq-js` evaluates against: an array of
+ * documents. Internally we keep a Map by `_id` for O(1) lookup, and
+ * project to an array on each query.
+ */
+export declare interface TestStore {
+  /** Replace the entire dataset with the given documents. Existing docs are dropped. */
+  seed: (documents: SanityDocumentLike[]) => void;
+  /** Add documents without dropping existing ones. Conflicts (same _id) overwrite. */
+  add: (documents: SanityDocumentLike[]) => void;
+  /** Remove all documents. */
+  reset: () => void;
+  /** All documents as an array, in insertion order. */
+  all: () => SanityDocument[];
+  /** Get one document by _id, or undefined. */
+  get: (id: string) => SanityDocument | undefined;
+  /** Insert a fully-formed document by _id. Replaces if it already exists. */
+  put: (doc: SanityDocument) => void;
+  /** Remove a document by _id. Returns the removed doc or undefined. */
+  remove: (id: string) => SanityDocument | undefined;
+  /** Snapshot of all docs, useful for assertions. */
+  snapshot: () => readonly SanityDocument[];
+}
+
+export declare interface TransactionHandle {
+  create: (doc: SanityDocumentLike) => TransactionHandle;
+  createOrReplace: (doc: SanityDocumentLike) => TransactionHandle;
+  createIfNotExists: (doc: SanityDocumentLike) => TransactionHandle;
+  delete: (id: string) => TransactionHandle;
+  /** Accept either a Patch builder (drained at commit) or an inline doc id + ops. */
+  patch: (
+    documentIdOrPatch: string | PatchHandle,
+    ops?: PatchOp[],
+    ifRev?: string,
+  ) => TransactionHandle;
+  commit: (options?: TxnCommitOptions) => Promise<TxnCommitResult>;
+  /** Test-only introspection — not on real Transaction. */
+  toJSON: () => TxnMutation[];
+}
+
+export declare interface TxnCommitOptions {
+  /** If true, returns the resulting documents instead of just ids. */
+  returnDocuments?: boolean;
+  /** With `returnDocuments`, return only the first updated doc. */
+  returnFirst?: boolean;
+}
+
+export declare type TxnCommitResult =
+  | {
+      transactionId: string;
+      results: {
+        id: string;
+        operation: "create" | "update" | "delete";
+      }[];
+    }
+  | SanityDocument
+  | SanityDocument[];
+
+export declare interface TxnExecutor {
+  apply: (
+    mutations: TxnMutation[],
+    options?: TxnCommitOptions,
+  ) => Promise<TxnCommitResult>;
+}
+
+/**
+ * A transaction collects mutations and applies them atomically at commit
+ * time. Mutations are applied in declaration order; if any one fails, the
+ * whole transaction throws and no writes land in the store.
+ *
+ * Subset of `@sanity/client`'s Transaction. Same shape, narrower surface.
+ */
+export declare type TxnMutation =
+  | {
+      kind: "create";
+      doc: SanityDocumentLike;
+    }
+  | {
+      kind: "createOrReplace";
+      doc: SanityDocumentLike;
+    }
+  | {
+      kind: "createIfNotExists";
+      doc: SanityDocumentLike;
+    }
+  | {
+      kind: "delete";
+      id: string;
+    }
+  | {
+      kind: "patch";
+      documentId: string;
+      ops: PatchOp[];
+      ifRev?: string;
+    };
+
+/**
+ * Sanity-style 403 raised when a configured-grants check rejects a
+ * write. The thrown object carries the doc id, the attempted
+ * permission, and the count of matching grants (for parity with the
+ * engine's `permission-denied` disabled-reason).
+ */
+export declare class WriteAccessDeniedError extends Error {
+  readonly documentId: string;
+  readonly permission: DocumentValuePermission;
+  readonly matchingGrants: number;
+  constructor(args: {
+    documentId: string;
+    permission: DocumentValuePermission;
+    matchingGrants: number;
+  });
+}
+
+export {};