@sanity-labs/client-fake-for-test 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -1,3 +1,9 @@
+export declare type Action = ReleaseAction | VersionAction;
+
+export declare interface ActionResult {
+  transactionId: string;
+}
+
 /**
  * Apply an ordered list of patch ops to a document, returning the new doc.
  *
@@ -16,6 +22,19 @@ export declare function applyPatchOps(
   ops: PatchOp[],
 ): SanityDocument;
 
+/**
+ * Apply a perspective to a raw set of documents and return the view
+ * groq-js should evaluate against.
+ *
+ * For non-raw perspectives, each output document for a non-system id
+ * gets `_id` projected to its published id and `_originalId` carrying
+ * the source id (matching the wire shape of the real Content Lake).
+ */
+export declare function applyPerspective(
+  docs: readonly SanityDocument[],
+  perspective: Perspective,
+): SanityDocument[];
+
 export declare function createPatch(
   documentId: string,
   executor: PatchExecutor,
@@ -65,6 +84,13 @@ export declare interface CreateTestClientOptions {
    * unconditionally — the legacy behavior.
    */
   accessControl?: TestClientAccessControl;
+  /**
+   * Default perspective applied to reads. Per-fetch `options.perspective`
+   * overrides this. `withConfig({ perspective })` returns a sibling
+   * handle with a different default. Defaults to `"raw"` so existing
+   * tests stay green.
+   */
+  perspective?: Perspective;
 }
 
 /**
@@ -102,6 +128,18 @@ export declare function defaultAclPath(
   dataset: string,
 ): string;
 
+/**
+ * Document body accepted by `version.create` / `createVersion`. The id
+ * is derived from `releaseId + publishedId` so callers may omit `_id`
+ * here. `version.replace` requires `_id` since it identifies the doc
+ * to replace.
+ */
+export declare interface DocumentBody {
+  _id?: string;
+  _type: string;
+  [field: string]: unknown;
+}
+
 export declare type DocumentValuePermission = "create" | "read" | "update";
 
 /**
@@ -125,11 +163,46 @@ export declare function evaluateWriteAccess(args: {
   matchingGrants: number;
 }>;
 
+/**
+ * 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.
+ */
+export declare interface FetchOptions {
+  /** Override the client's configured perspective for this read. */
+  perspective?: Perspective;
+}
+
 export declare interface Grant {
   filter: string;
   permissions: DocumentValuePermission[];
 }
 
+export declare const isDraftId: (id: string) => boolean;
+
+export declare const isReleaseDocId: (id: string) => boolean;
+
+export declare const isSystemId: (id: string) => boolean;
+
+export declare const isVersionId: (id: string) => boolean;
+
 export declare interface MutationOptions {
   ifRevisionId?: string;
 }
@@ -197,6 +270,107 @@ export declare type PatchOp =
       items: unknown[];
     };
 
+export declare type Perspective = "raw" | "published" | "drafts" | string[];
+
+/** Strip `drafts.` / `versions.<name>.` prefix to recover the published id. */
+export declare function publishedIdOf(id: string): string;
+
+export declare type ReleaseAction =
+  | {
+      actionType: "sanity.action.release.create";
+      releaseId: string;
+      metadata?: Partial<ReleaseMetadata>;
+    }
+  | {
+      actionType: "sanity.action.release.edit";
+      releaseId: string;
+      patch: {
+        set?: Record<string, unknown>;
+        unset?: string[];
+      };
+    }
+  | {
+      actionType: "sanity.action.release.schedule";
+      releaseId: string;
+      publishAt: string;
+    }
+  | {
+      actionType: "sanity.action.release.unschedule";
+      releaseId: string;
+    }
+  | {
+      actionType: "sanity.action.release.publish";
+      releaseId: string;
+    }
+  | {
+      actionType: "sanity.action.release.archive";
+      releaseId: string;
+    }
+  | {
+      actionType: "sanity.action.release.unarchive";
+      releaseId: string;
+    }
+  | {
+      actionType: "sanity.action.release.delete";
+      releaseId: string;
+    };
+
+export declare interface ReleaseDocument extends SanityDocument {
+  _type: "system.release";
+  name: string;
+  state: ReleaseState;
+  metadata: ReleaseMetadata;
+  publishAt?: string;
+}
+
+export declare interface ReleaseMetadata {
+  title?: string;
+  description?: string;
+  releaseType?: ReleaseType;
+  intendedPublishAt?: string;
+}
+
+/** Extract the release name from a `versions.<name>.<id>` id, else undefined. */
+export declare function releaseNameOf(id: string): string | undefined;
+
+export declare interface ReleasesHandle {
+  create: (params: {
+    releaseId: string;
+    metadata?: Partial<ReleaseMetadata>;
+  }) => Promise<
+    ActionResult & {
+      releaseId: string;
+      metadata: ReleaseMetadata;
+    }
+  >;
+  edit: (params: {
+    releaseId: string;
+    patch: {
+      set?: Record<string, unknown>;
+      unset?: string[];
+    };
+  }) => Promise<ActionResult>;
+  get: (params: { releaseId: string }) => Promise<ReleaseDocument | undefined>;
+  fetchDocuments: (params: { releaseId: string }) => Promise<SanityDocument[]>;
+  schedule: (params: {
+    releaseId: string;
+    publishAt: string;
+  }) => Promise<ActionResult>;
+  unschedule: (params: { releaseId: string }) => Promise<ActionResult>;
+  publish: (params: { releaseId: string }) => Promise<ActionResult>;
+  archive: (params: { releaseId: string }) => Promise<ActionResult>;
+  unarchive: (params: { releaseId: string }) => Promise<ActionResult>;
+  delete: (params: { releaseId: string }) => Promise<ActionResult>;
+}
+
+export declare type ReleaseState =
+  | "active"
+  | "scheduled"
+  | "published"
+  | "archived";
+
+export declare type ReleaseType = "asap" | "scheduled" | "undecided";
+
 /** @public */
 declare interface SanityDocument {
   _id: string;
@@ -232,36 +406,20 @@ export declare interface SystemFields {
   _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>,
+    options?: FetchOptions,
   ) => Promise<T>;
-  getDocument: <T = SanityDocument>(id: string) => Promise<T | null>;
-  getDocuments: <T = SanityDocument>(ids: string[]) => Promise<(T | null)[]>;
+  getDocument: <T = SanityDocument>(
+    id: string,
+    options?: FetchOptions,
+  ) => Promise<T | null>;
+  getDocuments: <T = SanityDocument>(
+    ids: string[],
+    options?: FetchOptions,
+  ) => Promise<(T | null)[]>;
   /**
    * Sanity-style HTTP request hook. Present iff the client was
    * created with `accessControl`. The engine's access resolver pokes
@@ -300,10 +458,30 @@ export declare interface TestClient {
   } | null>;
   patch: (documentId: string) => PatchHandle;
   transaction: () => TransactionHandle;
-  /** Current `(projectId, dataset)`. */
+  /**
+   * Dispatch one or more release / version actions against the store.
+   * Returns a synthetic `transactionId`. Multi-action arrays are applied
+   * atomically — any failure rolls back the batch.
+   */
+  action: (action: Action | Action[]) => Promise<ActionResult>;
+  /** Helpers mirroring `@sanity/client`'s `client.releases.*` surface. */
+  releases: ReleasesHandle;
+  /** Helper for `sanity.action.document.version.create`. */
+  createVersion: (params: {
+    releaseId: string;
+    publishedId: string;
+    document: DocumentBody;
+  }) => Promise<ActionResult>;
+  /** Helper for `sanity.action.document.version.unpublish`. */
+  unpublishVersion: (params: {
+    releaseId: string;
+    publishedId: string;
+  }) => Promise<ActionResult>;
+  /** Current `(projectId, dataset)` and active perspective. */
   config: () => {
     projectId: string;
     dataset: string;
+    perspective: Perspective;
   };
   /**
    * Return a new client handle pointing at a different `(projectId, dataset)`
@@ -315,6 +493,7 @@ export declare interface TestClient {
     config: Partial<{
       projectId: string;
       dataset: string;
+      perspective: Perspective;
     }>,
   ) => TestClient;
   /** Replace the current dataset with the given documents. */
@@ -445,6 +624,27 @@ export declare type TxnMutation =
       ifRev?: string;
     };
 
+export declare type VersionAction =
+  | {
+      actionType: "sanity.action.document.version.create";
+      publishedId: string;
+      document: DocumentBody;
+      releaseId?: string;
+    }
+  | {
+      actionType: "sanity.action.document.version.replace";
+      document: SanityDocumentLike;
+    }
+  | {
+      actionType: "sanity.action.document.version.discard";
+      versionId: string;
+    }
+  | {
+      actionType: "sanity.action.document.version.unpublish";
+      versionId: string;
+      publishedId: string;
+    };
+
 /**
  * Sanity-style 403 raised when a configured-grants check rejects a
  * write. The thrown object carries the doc id, the attempted

package/dist/index.d.ts

@@ -1,3 +1,9 @@
+export declare type Action = ReleaseAction | VersionAction;
+
+export declare interface ActionResult {
+  transactionId: string;
+}
+
 /**
  * Apply an ordered list of patch ops to a document, returning the new doc.
  *
@@ -16,6 +22,19 @@ export declare function applyPatchOps(
   ops: PatchOp[],
 ): SanityDocument;
 
+/**
+ * Apply a perspective to a raw set of documents and return the view
+ * groq-js should evaluate against.
+ *
+ * For non-raw perspectives, each output document for a non-system id
+ * gets `_id` projected to its published id and `_originalId` carrying
+ * the source id (matching the wire shape of the real Content Lake).
+ */
+export declare function applyPerspective(
+  docs: readonly SanityDocument[],
+  perspective: Perspective,
+): SanityDocument[];
+
 export declare function createPatch(
   documentId: string,
   executor: PatchExecutor,
@@ -65,6 +84,13 @@ export declare interface CreateTestClientOptions {
    * unconditionally — the legacy behavior.
    */
   accessControl?: TestClientAccessControl;
+  /**
+   * Default perspective applied to reads. Per-fetch `options.perspective`
+   * overrides this. `withConfig({ perspective })` returns a sibling
+   * handle with a different default. Defaults to `"raw"` so existing
+   * tests stay green.
+   */
+  perspective?: Perspective;
 }
 
 /**
@@ -102,6 +128,18 @@ export declare function defaultAclPath(
   dataset: string,
 ): string;
 
+/**
+ * Document body accepted by `version.create` / `createVersion`. The id
+ * is derived from `releaseId + publishedId` so callers may omit `_id`
+ * here. `version.replace` requires `_id` since it identifies the doc
+ * to replace.
+ */
+export declare interface DocumentBody {
+  _id?: string;
+  _type: string;
+  [field: string]: unknown;
+}
+
 export declare type DocumentValuePermission = "create" | "read" | "update";
 
 /**
@@ -125,11 +163,46 @@ export declare function evaluateWriteAccess(args: {
   matchingGrants: number;
 }>;
 
+/**
+ * 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.
+ */
+export declare interface FetchOptions {
+  /** Override the client's configured perspective for this read. */
+  perspective?: Perspective;
+}
+
 export declare interface Grant {
   filter: string;
   permissions: DocumentValuePermission[];
 }
 
+export declare const isDraftId: (id: string) => boolean;
+
+export declare const isReleaseDocId: (id: string) => boolean;
+
+export declare const isSystemId: (id: string) => boolean;
+
+export declare const isVersionId: (id: string) => boolean;
+
 export declare interface MutationOptions {
   ifRevisionId?: string;
 }
@@ -197,6 +270,107 @@ export declare type PatchOp =
       items: unknown[];
     };
 
+export declare type Perspective = "raw" | "published" | "drafts" | string[];
+
+/** Strip `drafts.` / `versions.<name>.` prefix to recover the published id. */
+export declare function publishedIdOf(id: string): string;
+
+export declare type ReleaseAction =
+  | {
+      actionType: "sanity.action.release.create";
+      releaseId: string;
+      metadata?: Partial<ReleaseMetadata>;
+    }
+  | {
+      actionType: "sanity.action.release.edit";
+      releaseId: string;
+      patch: {
+        set?: Record<string, unknown>;
+        unset?: string[];
+      };
+    }
+  | {
+      actionType: "sanity.action.release.schedule";
+      releaseId: string;
+      publishAt: string;
+    }
+  | {
+      actionType: "sanity.action.release.unschedule";
+      releaseId: string;
+    }
+  | {
+      actionType: "sanity.action.release.publish";
+      releaseId: string;
+    }
+  | {
+      actionType: "sanity.action.release.archive";
+      releaseId: string;
+    }
+  | {
+      actionType: "sanity.action.release.unarchive";
+      releaseId: string;
+    }
+  | {
+      actionType: "sanity.action.release.delete";
+      releaseId: string;
+    };
+
+export declare interface ReleaseDocument extends SanityDocument {
+  _type: "system.release";
+  name: string;
+  state: ReleaseState;
+  metadata: ReleaseMetadata;
+  publishAt?: string;
+}
+
+export declare interface ReleaseMetadata {
+  title?: string;
+  description?: string;
+  releaseType?: ReleaseType;
+  intendedPublishAt?: string;
+}
+
+/** Extract the release name from a `versions.<name>.<id>` id, else undefined. */
+export declare function releaseNameOf(id: string): string | undefined;
+
+export declare interface ReleasesHandle {
+  create: (params: {
+    releaseId: string;
+    metadata?: Partial<ReleaseMetadata>;
+  }) => Promise<
+    ActionResult & {
+      releaseId: string;
+      metadata: ReleaseMetadata;
+    }
+  >;
+  edit: (params: {
+    releaseId: string;
+    patch: {
+      set?: Record<string, unknown>;
+      unset?: string[];
+    };
+  }) => Promise<ActionResult>;
+  get: (params: { releaseId: string }) => Promise<ReleaseDocument | undefined>;
+  fetchDocuments: (params: { releaseId: string }) => Promise<SanityDocument[]>;
+  schedule: (params: {
+    releaseId: string;
+    publishAt: string;
+  }) => Promise<ActionResult>;
+  unschedule: (params: { releaseId: string }) => Promise<ActionResult>;
+  publish: (params: { releaseId: string }) => Promise<ActionResult>;
+  archive: (params: { releaseId: string }) => Promise<ActionResult>;
+  unarchive: (params: { releaseId: string }) => Promise<ActionResult>;
+  delete: (params: { releaseId: string }) => Promise<ActionResult>;
+}
+
+export declare type ReleaseState =
+  | "active"
+  | "scheduled"
+  | "published"
+  | "archived";
+
+export declare type ReleaseType = "asap" | "scheduled" | "undecided";
+
 /** @public */
 declare interface SanityDocument {
   _id: string;
@@ -232,36 +406,20 @@ export declare interface SystemFields {
   _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>,
+    options?: FetchOptions,
   ) => Promise<T>;
-  getDocument: <T = SanityDocument>(id: string) => Promise<T | null>;
-  getDocuments: <T = SanityDocument>(ids: string[]) => Promise<(T | null)[]>;
+  getDocument: <T = SanityDocument>(
+    id: string,
+    options?: FetchOptions,
+  ) => Promise<T | null>;
+  getDocuments: <T = SanityDocument>(
+    ids: string[],
+    options?: FetchOptions,
+  ) => Promise<(T | null)[]>;
   /**
    * Sanity-style HTTP request hook. Present iff the client was
    * created with `accessControl`. The engine's access resolver pokes
@@ -300,10 +458,30 @@ export declare interface TestClient {
   } | null>;
   patch: (documentId: string) => PatchHandle;
   transaction: () => TransactionHandle;
-  /** Current `(projectId, dataset)`. */
+  /**
+   * Dispatch one or more release / version actions against the store.
+   * Returns a synthetic `transactionId`. Multi-action arrays are applied
+   * atomically — any failure rolls back the batch.
+   */
+  action: (action: Action | Action[]) => Promise<ActionResult>;
+  /** Helpers mirroring `@sanity/client`'s `client.releases.*` surface. */
+  releases: ReleasesHandle;
+  /** Helper for `sanity.action.document.version.create`. */
+  createVersion: (params: {
+    releaseId: string;
+    publishedId: string;
+    document: DocumentBody;
+  }) => Promise<ActionResult>;
+  /** Helper for `sanity.action.document.version.unpublish`. */
+  unpublishVersion: (params: {
+    releaseId: string;
+    publishedId: string;
+  }) => Promise<ActionResult>;
+  /** Current `(projectId, dataset)` and active perspective. */
   config: () => {
     projectId: string;
     dataset: string;
+    perspective: Perspective;
   };
   /**
    * Return a new client handle pointing at a different `(projectId, dataset)`
@@ -315,6 +493,7 @@ export declare interface TestClient {
     config: Partial<{
       projectId: string;
       dataset: string;
+      perspective: Perspective;
     }>,
   ) => TestClient;
   /** Replace the current dataset with the given documents. */
@@ -445,6 +624,27 @@ export declare type TxnMutation =
       ifRev?: string;
     };
 
+export declare type VersionAction =
+  | {
+      actionType: "sanity.action.document.version.create";
+      publishedId: string;
+      document: DocumentBody;
+      releaseId?: string;
+    }
+  | {
+      actionType: "sanity.action.document.version.replace";
+      document: SanityDocumentLike;
+    }
+  | {
+      actionType: "sanity.action.document.version.discard";
+      versionId: string;
+    }
+  | {
+      actionType: "sanity.action.document.version.unpublish";
+      versionId: string;
+      publishedId: string;
+    };
+
 /**
  * Sanity-style 403 raised when a configured-grants check rejects a
  * write. The thrown object carries the doc id, the attempted