@sanity/client 8.3.0 → 8.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/client",
-  "version": "8.3.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",
@@ -113,6 +115,7 @@
     "format": "oxfmt",
     "format:check": "oxfmt --check",
     "knip": "knip",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "generate:context": "node scripts/prune-context-spec.mjs src/context/openapi.json .tmp/context-openapi.pruned.json && pnpm --package=typescript@5.9.3 --package=openapi-typescript@7.13.0 dlx openapi-typescript .tmp/context-openapi.pruned.json -o src/context/types.gen.ts && oxfmt src/context/openapi.json src/context/types.gen.ts"
   }
 }

package/src/SanityClient.ts

@@ -8,6 +8,7 @@ import {
   ObservableCollaborationCommentsClient,
 } from './collaboration/CollaborationCommentsClient'
 import {defaultConfig, initConfig} from './config'
+import {ContextClient, ObservableContextClient} from './context/ContextClient'
 import * as dataMethods from './data/dataMethods'
 import {_listen} from './data/listen'
 import {LiveClient} from './data/live'
@@ -77,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: {
@@ -93,16 +131,22 @@ export class ObservableSanityClient {
     comments: ObservableCollaborationCommentsClient
   }
   functions: ObservableFunctionsClient
-  releases: ObservableReleasesClient
-
   /**
-   * Private properties
+   * Create and manage content releases and their scheduled publishing
+   *
+   * @category Releases
    */
+  releases: ObservableReleasesClient
+  /** @beta */
+  context: ObservableContextClient
+
   #clientConfig: InitializedClientConfig
   #httpRequest: HttpRequest
 
   /**
-   * Instance properties
+   * Listen to document changes matching a GROQ query, delivered as server-sent events
+   *
+   * @category Real-time
    */
   listen = _listen
 
@@ -127,10 +171,13 @@ export class ObservableSanityClient {
     }
     this.functions = new ObservableFunctionsClient(this, this.#httpRequest)
     this.releases = new ObservableReleasesClient(this, this.#httpRequest)
+    this.context = new ObservableContextClient(this, this.#httpRequest)
   }
 
   /**
    * Clone the client - returns a new instance
+   *
+   * @category Configuration
    */
   clone(): ObservableSanityClient {
     return new ObservableSanityClient(this.#httpRequest, this.config())
@@ -138,6 +185,8 @@ export class ObservableSanityClient {
 
   /**
    * Returns the current client configuration
+   *
+   * @category Configuration
    */
   config(): InitializedClientConfig
   /**
@@ -162,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 {
@@ -181,6 +232,8 @@ export class ObservableSanityClient {
   /**
    * Perform a GROQ-query against the configured dataset.
    *
+   * @category Querying
+   *
    * @param query - GROQ-query to perform
    */
   fetch<
@@ -254,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
    */
@@ -313,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
    */
@@ -327,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
    */
@@ -341,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
    */
@@ -410,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
    */
@@ -479,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
    */
@@ -687,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
    */
@@ -807,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.
@@ -854,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.
@@ -960,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.
@@ -991,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
    */
@@ -1059,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
@@ -1097,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>>(
@@ -1108,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
    */
@@ -1121,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> {
@@ -1130,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
    */
@@ -1140,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
    */
@@ -1150,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: {
@@ -1166,21 +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
 
@@ -1205,12 +1337,15 @@ export class SanityClient {
     }
     this.functions = new FunctionsClient(this, this.#httpRequest)
     this.releases = new ReleasesClient(this, this.#httpRequest)
+    this.context = new ContextClient(this, this.#httpRequest)
 
     this.observable = new ObservableSanityClient(httpRequest, config)
   }
 
   /**
    * Clone the client - returns a new instance
+   *
+   * @category Configuration
    */
   clone(): SanityClient {
     return new SanityClient(this.#httpRequest, this.config())
@@ -1218,6 +1353,8 @@ export class SanityClient {
 
   /**
    * Returns the current client configuration
+   *
+   * @category Configuration
    */
   config(): InitializedClientConfig
   /**
@@ -1246,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 {
@@ -1265,6 +1404,8 @@ export class SanityClient {
   /**
    * Perform a GROQ-query against the configured dataset.
    *
+   * @category Querying
+   *
    * @param query - GROQ-query to perform
    */
   fetch<
@@ -1338,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
    */
@@ -1397,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
    */
@@ -1411,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
    */
@@ -1425,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
    */
@@ -1494,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
    */
@@ -1563,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
    */
@@ -1759,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
    */
@@ -1879,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.
@@ -1920,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.
@@ -1973,7 +2132,6 @@ export class SanityClient {
    * // }
    * ```
    */
-
   replaceVersion<R extends Record<string, Any>>(
     args: {
       document: SanityDocumentStub<R>
@@ -2022,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.
@@ -2047,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
    */
@@ -2115,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
@@ -2153,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>>(
@@ -2165,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
    */
@@ -2179,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
    */
@@ -2203,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
    */
@@ -2213,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
@@ -303,6 +309,11 @@ function buildAssetUploadUrl(config: InitializedClientConfig, assetType: 'image'
       case 'canvas': {
         return `/canvases/${id}/assets/${assetTypeEndpoint}`
       }
+      case 'knowledge-base': {
+        throw new Error(
+          'Assets are not supported for knowledge-base resources. Use `client.context.imports` to add content instead.',
+        )
+      }
       case 'media-library': {
         return `/media-libraries/${id}/upload`
       }

package/src/config.ts

@@ -62,6 +62,7 @@ export const initConfig = (
   const newConfig = {
     ...defaultConfig,
     ...specifiedConfig,
+    apiHost: specifiedConfig.apiHost ?? defaultConfig.apiHost,
   } as InitializedClientConfig
 
   // Normalize resource configuration - prefer `resource` over deprecated `~experimental_resource`