@sanity/client 8.4.0 → 8.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/client",
-  "version": "8.4.0",
+  "version": "8.5.0",
   "description": "Client for retrieving, creating and patching data from Sanity.io",
   "keywords": [
     "api",
@@ -49,38 +49,39 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "eventsource": "^5.1.0",
-    "get-it": "^9.5.0",
+    "eventsource": "^5.1.1",
+    "get-it": "^9.5.2",
     "obug": "^2.1.4",
     "rxjs": "^7.8.2"
   },
   "devDependencies": {
     "@changesets/cli": "^2.31.1",
-    "@cloudflare/vitest-pool-workers": "^0.21.3",
+    "@cloudflare/vitest-pool-workers": "^0.22.0",
     "@edge-runtime/types": "^4.0.0",
     "@edge-runtime/vm": "^5.0.0",
-    "@sanity/pkg-utils": "^12.1.2",
+    "@sanity/pkg-utils": "^12.3.3",
     "@types/json-diff": "^1.0.3",
     "@types/node": "^22.20.1",
     "@types/react": "^19.2.18",
     "@vercel/stega": "1.1.0",
-    "@vitest/browser": "^4.1.10",
-    "@vitest/browser-playwright": "^4.1.10",
-    "@vitest/coverage-v8": "^4.1.10",
+    "@vitest/browser": "^4.1.11",
+    "@vitest/browser-playwright": "^4.1.11",
+    "@vitest/coverage-v8": "^4.1.11",
     "eventsource-encoder": "^1.0.2",
-    "happy-dom": "^20.11.2",
+    "happy-dom": "^20.11.12",
     "json-diff": "^1.0.6",
-    "knip": "^6.32.2",
+    "knip": "^6.32.3",
     "ls-engines": "^0.10.1",
-    "next": "^16.3.1",
-    "oxfmt": "^0.63.0",
-    "oxlint": "^1.78.0",
+    "next": "^16.3.3",
+    "oxfmt": "^0.65.0",
+    "oxlint": "^1.80.0",
     "oxlint-tsgolint": "^7.0.2001",
     "pkg-pr-new": "^0.0.88",
     "playwright": "^1.62.1",
+    "rolldown": "^1.2.6",
     "typescript": "7.0.2",
     "undici": "^7.29.0",
-    "vitest": "^4.1.10"
+    "vitest": "^4.1.11"
   },
   "browserslist": "extends @sanity/browserslist-config",
   "engines": {
@@ -92,6 +93,7 @@
   "scripts": {
     "build": "pkg build --strict && pkg --strict",
     "coverage": "vitest run --coverage",
+    "docs:build": "pnpm --filter @sanity/client-docs exec typedoc --options ../../typedoc.json",
     "lint": "oxlint",
     "release": "changeset publish",
     "test": "vitest",

package/src/SanityClient.ts

@@ -78,15 +78,52 @@ export type {
 
 /** @public */
 export class ObservableSanityClient {
+  /**
+   * Upload, fetch and delete assets (images and files) in the configured dataset
+   *
+   * @category Assets
+   */
   assets: ObservableAssetsClient
+  /**
+   * Create, list, edit and delete datasets in the configured project
+   *
+   * @category Projects & Datasets
+   */
   datasets: ObservableDatasetsClient
+  /**
+   * Subscribe to live content updates through the Live Content API
+   *
+   * @category Real-time
+   */
   live: LiveClient
+  /**
+   * Interact with Media Library assets
+   *
+   * @category Assets
+   */
   mediaLibrary: {
+    /** Upload and manage Media Library video assets */
     video: ObservableMediaLibraryVideoClient
   }
+  /**
+   * Fetch information about the projects the authenticated user has access to
+   *
+   * @category Projects & Datasets
+   */
   projects: ObservableProjectsClient
+  /**
+   * Fetch information about users in the configured project
+   *
+   * @category Projects & Datasets
+   */
   users: ObservableUsersClient
+  /**
+   * Run Agent Actions - AI-powered operations to generate, transform, translate, prompt and patch documents
+   *
+   * @category Agent Actions
+   */
   agent: {
+    /** Run individual Agent Action operations */
     action: ObservableAgentsActionClient
   }
   collaboration: {
@@ -94,18 +131,22 @@ export class ObservableSanityClient {
     comments: ObservableCollaborationCommentsClient
   }
   functions: ObservableFunctionsClient
+  /**
+   * Create and manage content releases and their scheduled publishing
+   *
+   * @category Releases
+   */
   releases: ObservableReleasesClient
   /** @beta */
   context: ObservableContextClient
 
-  /**
-   * Private properties
-   */
   #clientConfig: InitializedClientConfig
   #httpRequest: HttpRequest
 
   /**
-   * Instance properties
+   * Listen to document changes matching a GROQ query, delivered as server-sent events
+   *
+   * @category Real-time
    */
   listen = _listen
 
@@ -135,6 +176,8 @@ export class ObservableSanityClient {
 
   /**
    * Clone the client - returns a new instance
+   *
+   * @category Configuration
    */
   clone(): ObservableSanityClient {
     return new ObservableSanityClient(this.#httpRequest, this.config())
@@ -142,6 +185,8 @@ export class ObservableSanityClient {
 
   /**
    * Returns the current client configuration
+   *
+   * @category Configuration
    */
   config(): InitializedClientConfig
   /**
@@ -166,6 +211,8 @@ export class ObservableSanityClient {
   /**
    * Clone the client with a new (partial) configuration.
    *
+   * @category Configuration
+   *
    * @param newConfig - New client configuration properties, shallowly merged with existing configuration
    */
   withConfig(newConfig?: Partial<ClientConfig>): ObservableSanityClient {
@@ -185,6 +232,8 @@ export class ObservableSanityClient {
   /**
    * Perform a GROQ-query against the configured dataset.
    *
+   * @category Querying
+   *
    * @param query - GROQ-query to perform
    */
   fetch<
@@ -258,6 +307,8 @@ export class ObservableSanityClient {
   /**
    * Fetch a single document with the given ID.
    *
+   * @category Querying
+   *
    * @param id - Document ID to fetch
    * @param options - Request options
    */
@@ -317,6 +368,8 @@ export class ObservableSanityClient {
    * The order/position of documents is preserved based on the original array of IDs.
    * If any of the documents are missing, they will be replaced by a `null` entry in the returned array
    *
+   * @category Querying
+   *
    * @param ids - Document IDs to fetch
    * @param options - Request options
    */
@@ -331,6 +384,8 @@ export class ObservableSanityClient {
    * Convenient and bandwidth efficient method of checking wether a set of document IDs exists.
    * Returns a set of the IDs that exist.
    *
+   * @category Querying
+   *
    * @param ids - Document IDs to check
    * @param options - Request options
    */
@@ -345,6 +400,8 @@ export class ObservableSanityClient {
    * Create a document. Requires a `_type` property. If no `_id` is provided, it will be generated by the database.
    * Returns an observable that resolves to the created document.
    *
+   * @category Mutations
+   *
    * @param document - Document to create
    * @param options - Mutation options
    */
@@ -414,6 +471,8 @@ export class ObservableSanityClient {
    * Create a document if no document with the same ID already exists.
    * Returns an observable that resolves to the created document.
    *
+   * @category Mutations
+   *
    * @param document - Document to create
    * @param options - Mutation options
    */
@@ -483,6 +542,8 @@ export class ObservableSanityClient {
    * Create a document if it does not exist, or replace a document with the same document ID
    * Returns an observable that resolves to the created document.
    *
+   * @category Mutations
+   *
    * @param document - Document to either create or replace
    * @param options - Mutation options
    */
@@ -691,6 +752,8 @@ export class ObservableSanityClient {
    * Deletes a document with the given document ID.
    * Returns an observable that resolves to the deleted document.
    *
+   * @category Mutations
+   *
    * @param id - Document ID to delete
    * @param options - Options for the mutation
    */
@@ -811,6 +874,8 @@ export class ObservableSanityClient {
    * * Discarding a version with no `releaseId` will discard the draft version of the published document.
    * * If the draft or release version does not exist, any error will throw.
    *
+   * @category Versions
+   *
    * @param params - Version action parameters:
    *   - `releaseId` - The ID of the release to discard the document from.
    *   - `publishedId` - The published ID of the document to discard.
@@ -858,6 +923,8 @@ export class ObservableSanityClient {
    * * Replacing a version with no `releaseId` will replace the draft version of the published document.
    * * At least one of the **version** or **published** documents must exist.
    *
+   * @category Versions
+   *
    * @param params - Version action parameters:
    *   - `document` - The new document to replace the version with.
    *   - `releaseId` - The ID of the release where the document version is replaced.
@@ -964,6 +1031,8 @@ export class ObservableSanityClient {
    * @remarks
    * * If the published document does not exist, an error will be thrown.
    *
+   * @category Versions
+   *
    * @param params - Version action parameters:
    *   - `releaseId` - The ID of the release to unpublish the document from.
    *   - `publishedId` - The published ID of the document to unpublish.
@@ -995,6 +1064,8 @@ export class ObservableSanityClient {
    * Perform mutation operations against the configured dataset
    * Returns an observable that resolves to the first mutated document.
    *
+   * @category Mutations
+   *
    * @param operations - Mutation operations to execute
    * @param options - Mutation options
    */
@@ -1063,6 +1134,8 @@ export class ObservableSanityClient {
   /**
    * Create a new buildable patch of operations to perform
    *
+   * @category Mutations
+   *
    * @param documentId - Document ID to patch
    * @param operations - Optional object of patch operations to initialize the patch instance with
    * @returns Patch instance - call `.commit()` to perform the operations defined
@@ -1101,6 +1174,8 @@ export class ObservableSanityClient {
   /**
    * Create a new transaction of mutations
    *
+   * @category Mutations
+   *
    * @param operations - Optional array of mutation operations to initialize the transaction instance with
    */
   transaction<R extends Record<string, Any> = Record<string, Any>>(
@@ -1112,6 +1187,8 @@ export class ObservableSanityClient {
   /**
    * Perform action operations against the configured dataset
    *
+   * @category Mutations
+   *
    * @param operations - Action operation(s) to execute
    * @param options - Action options
    */
@@ -1125,6 +1202,8 @@ export class ObservableSanityClient {
   /**
    * Perform an HTTP request against the Sanity API
    *
+   * @category HTTP
+   *
    * @param options - Request options
    */
   request<R = Any>(options: RawRequestOptions): Observable<R> {
@@ -1134,6 +1213,8 @@ export class ObservableSanityClient {
   /**
    * Get a Sanity API URL for the URI provided
    *
+   * @category HTTP
+   *
    * @param uri - URI/path to build URL for
    * @param canUseCdn - Whether or not to allow using the API CDN for this route
    */
@@ -1144,6 +1225,8 @@ export class ObservableSanityClient {
   /**
    * Get a Sanity API URL for the data operation and path provided
    *
+   * @category HTTP
+   *
    * @param operation - Data operation (eg `query`, `mutate`, `listen` or similar)
    * @param path - Path to append after the operation
    */
@@ -1154,15 +1237,52 @@ export class ObservableSanityClient {
 
 /** @public */
 export class SanityClient {
+  /**
+   * Upload, fetch and delete assets (images and files) in the configured dataset
+   *
+   * @category Assets
+   */
   assets: AssetsClient
+  /**
+   * Create, list, edit and delete datasets in the configured project
+   *
+   * @category Projects & Datasets
+   */
   datasets: DatasetsClient
+  /**
+   * Subscribe to live content updates through the Live Content API
+   *
+   * @category Real-time
+   */
   live: LiveClient
+  /**
+   * Interact with Media Library assets
+   *
+   * @category Assets
+   */
   mediaLibrary: {
+    /** Upload and manage Media Library video assets */
     video: MediaLibraryVideoClient
   }
+  /**
+   * Fetch information about the projects the authenticated user has access to
+   *
+   * @category Projects & Datasets
+   */
   projects: ProjectsClient
+  /**
+   * Fetch information about users in the configured project
+   *
+   * @category Projects & Datasets
+   */
   users: UsersClient
+  /**
+   * Run Agent Actions - AI-powered operations to generate, transform, translate, prompt and patch documents
+   *
+   * @category Agent Actions
+   */
   agent: {
+    /** Run individual Agent Action operations */
     action: AgentActionsClient
   }
   collaboration: {
@@ -1170,23 +1290,29 @@ export class SanityClient {
     comments: CollaborationCommentsClient
   }
   functions: FunctionsClient
+  /**
+   * Create and manage content releases and their scheduled publishing
+   *
+   * @category Releases
+   */
   releases: ReleasesClient
   /** @beta */
   context: ContextClient
 
   /**
    * Observable version of the Sanity client, with the same configuration as the promise-based one
+   *
+   * @category Configuration
    */
   observable: ObservableSanityClient
 
-  /**
-   * Private properties
-   */
   #clientConfig: InitializedClientConfig
   #httpRequest: HttpRequest
 
   /**
-   * Instance properties
+   * Listen to document changes matching a GROQ query, delivered as server-sent events
+   *
+   * @category Real-time
    */
   listen = _listen
 
@@ -1218,6 +1344,8 @@ export class SanityClient {
 
   /**
    * Clone the client - returns a new instance
+   *
+   * @category Configuration
    */
   clone(): SanityClient {
     return new SanityClient(this.#httpRequest, this.config())
@@ -1225,6 +1353,8 @@ export class SanityClient {
 
   /**
    * Returns the current client configuration
+   *
+   * @category Configuration
    */
   config(): InitializedClientConfig
   /**
@@ -1253,6 +1383,8 @@ export class SanityClient {
   /**
    * Clone the client with a new (partial) configuration.
    *
+   * @category Configuration
+   *
    * @param newConfig - New client configuration properties, shallowly merged with existing configuration
    */
   withConfig(newConfig?: Partial<ClientConfig>): SanityClient {
@@ -1272,6 +1404,8 @@ export class SanityClient {
   /**
    * Perform a GROQ-query against the configured dataset.
    *
+   * @category Querying
+   *
    * @param query - GROQ-query to perform
    */
   fetch<
@@ -1345,6 +1479,8 @@ export class SanityClient {
   /**
    * Fetch a single document with the given ID.
    *
+   * @category Querying
+   *
    * @param id - Document ID to fetch
    * @param options - Request options
    */
@@ -1404,6 +1540,8 @@ export class SanityClient {
    * The order/position of documents is preserved based on the original array of IDs.
    * If any of the documents are missing, they will be replaced by a `null` entry in the returned array
    *
+   * @category Querying
+   *
    * @param ids - Document IDs to fetch
    * @param options - Request options
    */
@@ -1418,6 +1556,8 @@ export class SanityClient {
    * Convenient and bandwidth efficient method of checking wether a set of document IDs exists.
    * Returns a set of the IDs that exist.
    *
+   * @category Querying
+   *
    * @param ids - Document IDs to check
    * @param options - Request options
    */
@@ -1432,6 +1572,8 @@ export class SanityClient {
    * Create a document. Requires a `_type` property. If no `_id` is provided, it will be generated by the database.
    * Returns a promise that resolves to the created document.
    *
+   * @category Mutations
+   *
    * @param document - Document to create
    * @param options - Mutation options
    */
@@ -1501,6 +1643,8 @@ export class SanityClient {
    * Create a document if no document with the same ID already exists.
    * Returns a promise that resolves to the created document.
    *
+   * @category Mutations
+   *
    * @param document - Document to create
    * @param options - Mutation options
    */
@@ -1570,6 +1714,8 @@ export class SanityClient {
    * Create a document if it does not exist, or replace a document with the same document ID
    * Returns a promise that resolves to the created document.
    *
+   * @category Mutations
+   *
    * @param document - Document to either create or replace
    * @param options - Mutation options
    */
@@ -1766,6 +1912,8 @@ export class SanityClient {
    * Deletes a document with the given document ID.
    * Returns a promise that resolves to the deleted document.
    *
+   * @category Mutations
+   *
    * @param id - Document ID to delete
    * @param options - Options for the mutation
    */
@@ -1886,6 +2034,8 @@ export class SanityClient {
    * * Discarding a version with no `releaseId` will discard the draft version of the published document.
    * * If the draft or release version does not exist, any error will throw.
    *
+   * @category Versions
+   *
    * @param params - Version action parameters:
    *   - `releaseId` - The ID of the release to discard the document from.
    *   - `publishedId` - The published ID of the document to discard.
@@ -1927,6 +2077,8 @@ export class SanityClient {
    * * Replacing a version with no `releaseId` will replace the draft version of the published document.
    * * At least one of the **version** or **published** documents must exist.
    *
+   * @category Versions
+   *
    * @param params - Version action parameters:
    *   - `document` - The new document to replace the version with.
    *   - `releaseId` - The ID of the release where the document version is replaced.
@@ -1980,7 +2132,6 @@ export class SanityClient {
    * // }
    * ```
    */
-
   replaceVersion<R extends Record<string, Any>>(
     args: {
       document: SanityDocumentStub<R>
@@ -2029,6 +2180,8 @@ export class SanityClient {
    * @remarks
    * * If the published document does not exist, an error will be thrown.
    *
+   * @category Versions
+   *
    * @param params - Version action parameters:
    *   - `releaseId` - The ID of the release to unpublish the document from.
    *   - `publishedId` - The published ID of the document to unpublish.
@@ -2054,6 +2207,8 @@ export class SanityClient {
    * Perform mutation operations against the configured dataset
    * Returns a promise that resolves to the first mutated document.
    *
+   * @category Mutations
+   *
    * @param operations - Mutation operations to execute
    * @param options - Mutation options
    */
@@ -2122,6 +2277,8 @@ export class SanityClient {
   /**
    * Create a new buildable patch of operations to perform
    *
+   * @category Mutations
+   *
    * @param documentId - Document ID to patch
    * @param operations - Optional object of patch operations to initialize the patch instance with
    * @returns Patch instance - call `.commit()` to perform the operations defined
@@ -2160,6 +2317,8 @@ export class SanityClient {
   /**
    * Create a new transaction of mutations
    *
+   * @category Mutations
+   *
    * @param operations - Optional array of mutation operations to initialize the transaction instance with
    */
   transaction<R extends Record<string, Any> = Record<string, Any>>(
@@ -2172,6 +2331,8 @@ export class SanityClient {
    * Perform action operations against the configured dataset
    * Returns a promise that resolves to the transaction result
    *
+   * @category Mutations
+   *
    * @param operations - Action operation(s) to execute
    * @param options - Action options
    */
@@ -2186,6 +2347,8 @@ export class SanityClient {
    * Perform a request against the Sanity API
    * NOTE: Only use this for Sanity API endpoints, not for your own APIs!
    *
+   * @category HTTP
+   *
    * @param options - Request options
    * @returns Promise resolving to the response body
    */
@@ -2210,6 +2373,8 @@ export class SanityClient {
   /**
    * Get a Sanity API URL for the URI provided
    *
+   * @category HTTP
+   *
    * @param uri - URI/path to build URL for
    * @param canUseCdn - Whether or not to allow using the API CDN for this route
    */
@@ -2220,6 +2385,8 @@ export class SanityClient {
   /**
    * Get a Sanity API URL for the data operation and path provided
    *
+   * @category HTTP
+   *
    * @param operation - Data operation (eg `query`, `mutate`, `listen` or similar)
    * @param path - Path to append after the operation
    */

package/src/agent/actions/AgentActionsClient.ts

@@ -8,7 +8,10 @@ import {_prompt, type PromptRequest} from './prompt'
 import {_transform, _transformObservable, type TransformDocument} from './transform'
 import {_translate, _translateObservable, type TranslateDocument} from './translate'
 
-/** @public */
+/**
+ * @public
+ * @inline
+ */
 export class ObservableAgentsActionClient {
   #client: ObservableSanityClient
   #httpRequest: HttpRequest
@@ -60,7 +63,10 @@ export class ObservableAgentsActionClient {
   }
 }
 
-/** @public */
+/**
+ * @public
+ * @inline
+ */
 export class AgentActionsClient {
   #client: SanityClient
   #httpRequest: HttpRequest

package/src/assets/AssetsClient.ts

@@ -18,7 +18,10 @@ import type {
 } from '../types'
 import * as validators from '../validators'
 
-/** @internal */
+/**
+ * @internal
+ * @inline
+ */
 export class ObservableAssetsClient {
   #client: ObservableSanityClient
   #httpRequest: HttpRequest
@@ -78,7 +81,10 @@ export class ObservableAssetsClient {
   }
 }
 
-/** @internal */
+/**
+ * @internal
+ * @inline
+ */
 export class AssetsClient {
   #client: SanityClient
   #httpRequest: HttpRequest

package/src/data/live.ts

@@ -26,6 +26,7 @@ const requiredApiVersion = '2021-03-25'
 
 /**
  * @public
+ * @inline
  */
 export class LiveClient {
   #client: SanityClient | ObservableSanityClient

package/src/datasets/DatasetsClient.ts

@@ -13,7 +13,10 @@ import type {
 } from '../types'
 import * as validate from '../validators'
 
-/** @internal */
+/**
+ * @internal
+ * @inline
+ */
 export class ObservableDatasetsClient {
   #client: ObservableSanityClient
   #httpRequest: HttpRequest
@@ -107,7 +110,10 @@ export class ObservableDatasetsClient {
   }
 }
 
-/** @internal */
+/**
+ * @internal
+ * @inline
+ */
 export class DatasetsClient {
   #client: SanityClient
   #httpRequest: HttpRequest