@sanity/client 6.28.3-instruct.0 → 6.28.3-instruct.2

package/dist/stega.d.ts

@@ -110,117 +110,6 @@ export declare class AssetsClient {
   ): Promise<SanityAssetDocument | SanityImageAssetDocument>
 }
 
-/** @beta */
-export declare type AssistAsyncInstruction<T extends Record<string, Any> = Record<string, Any>> = (
-  | ExistingDocumentRequest
-  | CreateDocumentRequest<T>
-) &
-  AssistRequestBase &
-  Async
-
-/** @public */
-declare class AssistClient {
-  #private
-  constructor(client: SanityClient, httpRequest: HttpRequest)
-  instruct(request: AssistAsyncInstruction): Promise<{
-    _id: string
-  }>
-  instruct<DocumentShape extends Record<string, Any>>(
-    request: AssistSyncInstruction<DocumentShape>,
-  ): Promise<IdentifiedSanityDocumentStub & DocumentShape>
-}
-
-/** @beta */
-export declare type AssistInstruction<T extends Record<string, Any> = Record<string, Any>> =
-  | AssistSyncInstruction<T>
-  | AssistAsyncInstruction<T>
-
-declare interface AssistRequestBase {
-  /** schemaId as reported by sanity deploy / sanity schema store */
-  schemaId: string
-  /** string template using $variable – more on this below under "Dynamic instruction" */
-  instruction: string
-  /** param values for the string template, keys are the variable name, ie if the template has "$variable", one key must be "variable" */
-  instructionParams?: InstructionParams
-  /**
-   *  Optional document path output target for the instruction.
-   *  When provided, the instruction will apply to this path in the document and its children.
-   *
-   *  ## Examples
-   *  - `path: 'title'` will output to the title field in the document
-   * - `path: 'array[_key="xx"]'` will output to the item with `_key: 'xx'` in the array field
-   */
-  path?: string
-  /**
-   * Controls sub-paths in the document that can be output to.
-   *
-   * The string-paths are relative to the `path` param
-   *
-   * Note: these path strings are less strictly validated than the `path` param itself:
-   * if an relative-path does not exist or is invalid, it will be silently ignored.
-   *
-   * @see AssistRequestBase#conditionalPaths
-   * @see AssistRequestBase#outputTypes
-   */
-  relativeOutputPaths?:
-    | {
-        include: string[]
-      }
-    | {
-        exclude: string[]
-      }
-  /**
-   * Controls which types the instruction is allowed to output to.
-   *
-   * @see AssistRequestBase#relativeOutputPaths
-   * @see AssistRequestBase#conditionalPaths
-   */
-  outputTypes?:
-    | {
-        include: string[]
-      }
-    | {
-        exclude: string[]
-      }
-  /**
-   * When a type or field in the schema has a function set for `hidden` or `readOnly`, it is conditional.
-   *
-   * By default, AI Assist will not output to conditional `readOnly` and `hidden` fields,
-   * ie, they are considered to resolve to `readOnly: true` / `hidden: true`.
-   *
-   * `conditionalPaths` param allows setting the default conditional value for
-   * `hidden` and `readOnly` to false,
-   * or individually set `hidden` and `readOnly` state for individual document paths.
-   *
-   *
-   * Note: fields and types with explicit readOnly: true or hidden: true in the schema, are not available to AI Assist,
-   * and cannot be changed via conditionalPaths.
-   *
-   * conditionalPaths state only apply to fields and types that have conditional `hidden` or `readOnly` in their schema definition.
-   *
-   * @see AssistRequestBase#relativeOutputPaths
-   * @see AssistRequestBase#outputTypes
-   */
-  conditionalPaths?: {
-    defaultReadOnly?: boolean
-    defaultHidden?: boolean
-    paths?: {
-      /** path here is not a relative path: it must be the full document path, regardless of `path` param on the request itself */
-      path: string
-      readOnly: boolean
-      hidden: boolean
-    }[]
-  }
-}
-
-/** @beta */
-export declare type AssistSyncInstruction<T extends Record<string, Any> = Record<string, Any>> = (
-  | ExistingDocumentRequest
-  | CreateDocumentRequest<T>
-) &
-  AssistRequestBase &
-  Sync
-
 declare interface Async {
   /**
    * When async: true, requests responds with status 201 and {_id} as response body as soon as the request is validated.
@@ -578,12 +467,6 @@ export declare class ConnectionFailedError extends Error {
   readonly name = 'ConnectionFailedError'
 }
 
-/** @beta */
-export declare interface ConstantInstructionParam {
-  type: 'constant'
-  value: string
-}
-
 /** @public */
 export declare interface ContentSourceMap {
   mappings: ContentSourceMapMappings
@@ -1040,23 +923,6 @@ declare interface ExistingDocumentRequest {
   documentId: string
 }
 
-/**
- *
- * Includes a LLM-friendly version of the field value in the instruction
- * @beta
- * */
-export declare interface FieldInstructionParam {
-  type: 'field'
-  /**
-   * Examples: 'title', 'array[_key=="key"].field
-   */
-  path: string
-  /**
-   * If omitted, implicitly uses the documentId of the instruction target
-   */
-  documentId?: string
-}
-
 /** @public */
 export declare type FilterDefault = (props: {
   /**
@@ -1172,13 +1038,6 @@ export declare type FirstDocumentMutationOptions = BaseMutationOptions & {
   returnDocuments?: true
 }
 
-/** @beta */
-export declare interface GroqInstructionParam {
-  type: 'groq'
-  query: string
-  params?: Record<string, string>
-}
-
 /** @public */
 export declare type HttpRequest = {
   (options: RequestOptions, requester: Requester): ReturnType<Requester>
@@ -1250,15 +1109,143 @@ export declare type InsertPatch =
     }
 
 /** @beta */
-export declare type InstructionParam =
+export declare type InstructAsyncInstruction<T extends Record<string, Any> = Record<string, Any>> =
+  (ExistingDocumentRequest | CreateDocumentRequest<T>) & InstructRequestBase & Async
+
+/** @beta */
+export declare interface InstructConstantInstructionParam {
+  type: 'constant'
+  value: string
+}
+
+/**
+ *
+ * Includes a LLM-friendly version of the field value in the instruction
+ * @beta
+ * */
+export declare interface InstructFieldInstructionParam {
+  type: 'field'
+  /**
+   * Examples: 'title', 'array[_key=="key"].field'
+   */
+  path: string
+  /**
+   * If omitted, implicitly uses the documentId of the instruction target
+   */
+  documentId?: string
+}
+
+/**
+ * Includes a LLM-friendly version of GROQ query result in the instruction
+ * @beta
+ * */
+export declare interface InstructGroqInstructionParam {
+  type: 'groq'
+  query: string
+  params?: Record<string, string>
+}
+
+/** @beta */
+export declare type InstructInstruction<T extends Record<string, Any> = Record<string, Any>> =
+  | InstructSyncInstruction<T>
+  | InstructAsyncInstruction<T>
+
+/** @beta */
+export declare type InstructInstructionParam =
   | string
-  | ConstantInstructionParam
-  | FieldInstructionParam
+  | InstructConstantInstructionParam
+  | InstructFieldInstructionParam
   | DocumentInstructionParam
-  | GroqInstructionParam
+  | InstructGroqInstructionParam
 
 /** @beta */
-export declare type InstructionParams = Record<string, InstructionParam>
+export declare type InstructInstructionParams = Record<string, InstructInstructionParam>
+
+declare interface InstructRequestBase {
+  /** schemaId as reported by sanity deploy / sanity schema store */
+  schemaId: string
+  /** string template using $variable – more on this below under "Dynamic instruction" */
+  instruction: string
+  /** param values for the string template, keys are the variable name, ie if the template has "$variable", one key must be "variable" */
+  instructionParams?: InstructInstructionParams
+  /**
+   *  Optional document path output target for the instruction.
+   *  When provided, the instruction will apply to this path in the document and its children.
+   *
+   *  ## Examples
+   *  - `path: 'title'` will output to the title field in the document
+   * - `path: 'array[_key="xx"]'` will output to the item with `_key: 'xx'` in the array field
+   */
+  path?: string
+  /**
+   * Controls sub-paths in the document that can be output to.
+   *
+   * The string-paths are relative to the `path` param
+   *
+   * Note: these path strings are less strictly validated than the `path` param itself:
+   * if an relative-path does not exist or is invalid, it will be silently ignored.
+   *
+   * @see InstructRequestBase#conditionalPaths
+   * @see InstructRequestBase#outputTypes
+   */
+  relativeOutputPaths?:
+    | {
+        include: string[]
+      }
+    | {
+        exclude: string[]
+      }
+  /**
+   * Controls which types the instruction is allowed to output to.
+   *
+   * @see InstructRequestBase#relativeOutputPaths
+   * @see InstructRequestBase#conditionalPaths
+   */
+  outputTypes?:
+    | {
+        include: string[]
+      }
+    | {
+        exclude: string[]
+      }
+  /**
+   * When a type or field in the schema has a function set for `hidden` or `readOnly`, it is conditional.
+   *
+   * By default, AI Instruct will not output to conditional `readOnly` and `hidden` fields,
+   * ie, they are considered to resolve to `readOnly: true` / `hidden: true`.
+   *
+   * `conditionalPaths` param allows setting the default conditional value for
+   * `hidden` and `readOnly` to false,
+   * or individually set `hidden` and `readOnly` state for individual document paths.
+   *
+   *
+   * Note: fields and types with explicit readOnly: true or hidden: true in the schema, are not available to AI Instruct,
+   * and cannot be changed via conditionalPaths.
+   *
+   * conditionalPaths state only apply to fields and types that have conditional `hidden` or `readOnly` in their schema definition.
+   *
+   * @see InstructRequestBase#relativeOutputPaths
+   * @see InstructRequestBase#outputTypes
+   */
+  conditionalPaths?: {
+    defaultReadOnly?: boolean
+    defaultHidden?: boolean
+    paths?: {
+      /** path here is not a relative path: it must be the full document path, regardless of `path` param on the request itself */
+      path: string
+      readOnly: boolean
+      hidden: boolean
+    }[]
+  }
+}
+
+/** @beta */
+export declare type InstructSyncInstruction<T extends Record<string, Any> = Record<string, Any>> = (
+  | ExistingDocumentRequest
+  | CreateDocumentRequest<T>
+) &
+  InstructRequestBase &
+  Sync
 
 /**
  * Set up a listener that will be notified when mutations occur on documents matching the provided query/filter.
@@ -1681,18 +1668,6 @@ export declare class ObservableAssetsClient {
   >
 }
 
-/** @public */
-declare class ObservableAssistClient {
-  #private
-  constructor(client: ObservableSanityClient, httpRequest: HttpRequest)
-  instruct(request: AssistAsyncInstruction): Observable<{
-    _id: string
-  }>
-  instruct<DocumentShape extends Record<string, Any>>(
-    request: AssistSyncInstruction<DocumentShape>,
-  ): Observable<IdentifiedSanityDocumentStub & DocumentShape>
-}
-
 /** @internal */
 export declare class ObservableDatasetsClient {
   #private
@@ -1816,7 +1791,6 @@ export declare class ObservableSanityClient {
   live: LiveClient
   projects: ObservableProjectsClient
   users: ObservableUsersClient
-  assist: ObservableAssistClient
   /**
    * Instance properties
    */
@@ -2311,6 +2285,12 @@ export declare class ObservableSanityClient {
    * @param path - Path to append after the operation
    */
   getDataUrl(operation: string, path?: string): string
+  instruct(request: InstructAsyncInstruction): Observable<{
+    _id: string
+  }>
+  instruct<DocumentShape extends Record<string, Any>>(
+    request: InstructSyncInstruction<DocumentShape>,
+  ): Observable<IdentifiedSanityDocumentStub & DocumentShape>
 }
 
 /**
@@ -2748,7 +2728,6 @@ export declare class SanityClient {
   live: LiveClient
   projects: ProjectsClient
   users: UsersClient
-  assist: AssistClient
   /**
    * Observable version of the Sanity client, with the same configuration as the promise-based one
    */
@@ -3263,6 +3242,12 @@ export declare class SanityClient {
    * @param path - Path to append after the operation
    */
   getDataUrl(operation: string, path?: string): string
+  instruct(request: InstructAsyncInstruction): Promise<{
+    _id: string
+  }>
+  instruct<DocumentShape extends Record<string, Any>>(
+    request: InstructSyncInstruction<DocumentShape>,
+  ): Promise<IdentifiedSanityDocumentStub & DocumentShape>
 }
 
 /** @internal */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/client",
-  "version": "6.28.3-instruct.0",
+  "version": "6.28.3-instruct.2",
   "description": "Client for retrieving, creating and patching data from Sanity.io",
   "keywords": [
     "sanity",
@@ -125,39 +125,39 @@
   "devDependencies": {
     "@edge-runtime/types": "^4.0.0",
     "@edge-runtime/vm": "^5.0.0",
-    "@eslint/eslintrc": "^3.2.0",
-    "@eslint/js": "^9.20.0",
-    "@rollup/plugin-commonjs": "^28.0.2",
-    "@rollup/plugin-node-resolve": "^16.0.0",
+    "@eslint/eslintrc": "^3.3.0",
+    "@eslint/js": "^9.22.0",
+    "@rollup/plugin-commonjs": "^28.0.3",
+    "@rollup/plugin-node-resolve": "^16.0.1",
     "@sanity/client-latest": "npm:@sanity/client@latest",
-    "@sanity/pkg-utils": "^7.0.4",
+    "@sanity/pkg-utils": "^7.1.1",
     "@types/json-diff": "^1.0.3",
     "@types/node": "^22.9.0",
-    "@typescript-eslint/eslint-plugin": "^8.24.0",
-    "@typescript-eslint/parser": "^8.24.0",
+    "@typescript-eslint/eslint-plugin": "^8.26.1",
+    "@typescript-eslint/parser": "^8.26.1",
     "@vercel/stega": "0.1.2",
-    "@vitest/coverage-v8": "3.0.5",
-    "eslint": "^9.20.0",
-    "eslint-config-prettier": "^10.0.1",
+    "@vitest/coverage-v8": "3.0.9",
+    "eslint": "^9.22.0",
+    "eslint-config-prettier": "^10.1.1",
     "eslint-formatter-compact": "^8.40.0",
     "eslint-plugin-prettier": "^5.2.3",
     "eslint-plugin-simple-import-sort": "^12.1.1",
     "faucet": "^0.0.4",
-    "globals": "^15.14.0",
+    "globals": "^15.15.0",
     "happy-dom": "^12.10.3",
     "json-diff": "^1.0.6",
     "ls-engines": "^0.9.3",
-    "msw": "^2.7.0",
-    "next": "^15.1.7",
+    "msw": "^2.7.3",
+    "next": "^15.2.3",
     "nock": "^13.5.6",
-    "prettier": "^3.5.0",
-    "prettier-plugin-packagejson": "^2.5.8",
+    "prettier": "^3.5.3",
+    "prettier-plugin-packagejson": "^2.5.10",
     "rimraf": "^5.0.7",
-    "rollup": "^4.34.6",
+    "rollup": "^4.36.0",
     "sse-channel": "^4.0.0",
-    "terser": "^5.38.2",
-    "typescript": "5.7.3",
-    "vitest": "3.0.5"
+    "terser": "^5.39.0",
+    "typescript": "5.8.2",
+    "vitest": "3.0.9"
   },
   "packageManager": "npm@11.0.0",
   "engines": {

package/src/SanityClient.ts

@@ -1,7 +1,6 @@
 import {lastValueFrom, Observable} from 'rxjs'
 
 import {AssetsClient, ObservableAssetsClient} from './assets/AssetsClient'
-import {AssistClient, ObservableAssistClient} from './assist/AssistClient'
 import {defaultConfig, initConfig} from './config'
 import * as dataMethods from './data/dataMethods'
 import {_listen} from './data/listen'
@@ -9,6 +8,7 @@ import {LiveClient} from './data/live'
 import {ObservablePatch, Patch} from './data/patch'
 import {ObservableTransaction, Transaction} from './data/transaction'
 import {DatasetsClient, ObservableDatasetsClient} from './datasets/DatasetsClient'
+import {_instruct} from './instruct/instruct'
 import {ObservableProjectsClient, ProjectsClient} from './projects/ProjectsClient'
 import type {
   Action,
@@ -25,6 +25,9 @@ import type {
   HttpRequest,
   IdentifiedSanityDocumentStub,
   InitializedClientConfig,
+  InstructAsyncInstruction,
+  InstructInstruction,
+  InstructSyncInstruction,
   MultipleActionResult,
   MultipleMutationResult,
   Mutation,
@@ -66,7 +69,6 @@ export class ObservableSanityClient {
   live: LiveClient
   projects: ObservableProjectsClient
   users: ObservableUsersClient
-  assist: ObservableAssistClient
   /**
    * Private properties
    */
@@ -88,7 +90,6 @@ export class ObservableSanityClient {
     this.live = new LiveClient(this)
     this.projects = new ObservableProjectsClient(this, this.#httpRequest)
     this.users = new ObservableUsersClient(this, this.#httpRequest)
-    this.assist = new ObservableAssistClient(this, this.#httpRequest)
   }
 
   /**
@@ -726,6 +727,27 @@ export class ObservableSanityClient {
   getDataUrl(operation: string, path?: string): string {
     return dataMethods._getDataUrl(this, operation, path)
   }
+
+  instruct(request: InstructAsyncInstruction): Observable<{_id: string}>
+
+  instruct<DocumentShape extends Record<string, Any>>(
+    request: InstructSyncInstruction<DocumentShape>,
+  ): Observable<IdentifiedSanityDocumentStub & DocumentShape>
+
+  /**
+   * Run an ad-hoc instruction for a target document.
+   * @param request instruction request
+   */
+  instruct<
+    DocumentShape extends Record<string, Any>,
+    Req extends InstructInstruction<DocumentShape>,
+  >(
+    request: Req,
+  ): Observable<
+    Req['async'] extends true ? {_id: string} : IdentifiedSanityDocumentStub & DocumentShape
+  > {
+    return _instruct(this, this.#httpRequest, request)
+  }
 }
 
 /** @public */
@@ -735,7 +757,6 @@ export class SanityClient {
   live: LiveClient
   projects: ProjectsClient
   users: UsersClient
-  assist: AssistClient
 
   /**
    * Observable version of the Sanity client, with the same configuration as the promise-based one
@@ -763,7 +784,6 @@ export class SanityClient {
     this.live = new LiveClient(this)
     this.projects = new ProjectsClient(this, this.#httpRequest)
     this.users = new UsersClient(this, this.#httpRequest)
-    this.assist = new AssistClient(this, this.#httpRequest)
 
     this.observable = new ObservableSanityClient(httpRequest, config)
   }
@@ -1432,4 +1452,25 @@ export class SanityClient {
   getDataUrl(operation: string, path?: string): string {
     return dataMethods._getDataUrl(this, operation, path)
   }
+
+  instruct(request: InstructAsyncInstruction): Promise<{_id: string}>
+
+  instruct<DocumentShape extends Record<string, Any>>(
+    request: InstructSyncInstruction<DocumentShape>,
+  ): Promise<IdentifiedSanityDocumentStub & DocumentShape>
+
+  /**
+   * Run an ad-hoc instruction for a target document.
+   * @param request instruction request
+   */
+  instruct<
+    DocumentShape extends Record<string, Any>,
+    Req extends InstructInstruction<DocumentShape>,
+  >(
+    request: Req,
+  ): Promise<
+    Req['async'] extends true ? {_id: string} : IdentifiedSanityDocumentStub & DocumentShape
+  > {
+    return lastValueFrom(_instruct(this, this.#httpRequest, request))
+  }
 }

package/src/config.ts

@@ -28,30 +28,15 @@ function validateApiVersion(apiVersion: string) {
   }
 }
 
-const VALID_PERSPECTIVE = /^[a-z0-9_]+$/i
-
 /**
  * @internal - it may have breaking changes in any release
  */
 export function validateApiPerspective(
   perspective: unknown,
 ): asserts perspective is ClientPerspective {
-  if (Array.isArray(perspective)) {
-    if (perspective.includes('raw')) {
-      throw new TypeError(
-        `Invalid API perspective value: "raw". The raw-perspective can not be combined with other perspectives`,
-      )
-    }
-  }
-
-  const invalid = (Array.isArray(perspective) ? perspective : [perspective]).filter(
-    (perspectiveName) =>
-      typeof perspectiveName !== 'string' || !VALID_PERSPECTIVE.test(perspectiveName),
-  )
-  if (invalid.length > 0) {
-    const formatted = invalid.map((v) => JSON.stringify(v))
+  if (Array.isArray(perspective) && perspective.length > 1 && perspective.includes('raw')) {
     throw new TypeError(
-      `Invalid API perspective value${invalid.length === 1 ? '' : 's'}: ${formatted.join(', ')}, expected \`published\`, \`drafts\`, \`raw\` or a release identifier string`,
+      `Invalid API perspective value: "raw". The raw-perspective can not be combined with other perspectives`,
     )
   }
 }
@@ -122,7 +107,13 @@ export const initConfig = (
   const isBrowser = typeof window !== 'undefined' && window.location && window.location.hostname
   const isLocalhost = isBrowser && isLocal(window.location.hostname)
 
-  if (isBrowser && isLocalhost && newConfig.token && newConfig.ignoreBrowserTokenWarning !== true) {
+  const hasToken = Boolean(newConfig.token)
+  if (newConfig.withCredentials && hasToken) {
+    warnings.printCredentialedTokenWarning()
+    newConfig.withCredentials = false
+  }
+
+  if (isBrowser && isLocalhost && hasToken && newConfig.ignoreBrowserTokenWarning !== true) {
     warnings.printBrowserTokenWarning()
   } else if (typeof newConfig.useCdn === 'undefined') {
     warnings.printCdnWarning()

package/src/data/listen.ts

@@ -84,7 +84,7 @@ export function _listen<R extends Record<string, Any> = Record<string, Any>>(
   const listenFor = options.events ? options.events : ['mutation']
 
   const esOptions: EventSourceInit & {headers?: Record<string, string>} = {}
-  if (token || withCredentials) {
+  if (withCredentials) {
     esOptions.withCredentials = true
   }
 

package/src/http/requestOptions.ts

@@ -18,7 +18,7 @@ export function requestOptions(config: Any, overrides: Any = {}): Omit<RequestOp
 
   const withCredentials = Boolean(
     typeof overrides.withCredentials === 'undefined'
-      ? config.token || config.withCredentials
+      ? config.withCredentials
       : overrides.withCredentials,
   )
 

package/src/instruct/instruct.ts

@@ -0,0 +1,24 @@
+import {type Observable} from 'rxjs'
+
+import {_request} from '../data/dataMethods'
+import type {ObservableSanityClient, SanityClient} from '../SanityClient'
+import type {Any, HttpRequest, IdentifiedSanityDocumentStub, InstructInstruction} from '../types'
+import {hasDataset} from '../validators'
+
+export function _instruct<
+  DocumentShape extends Record<string, Any>,
+  Req extends InstructInstruction<DocumentShape>,
+>(
+  client: SanityClient | ObservableSanityClient,
+  httpRequest: HttpRequest,
+  request: Req,
+): Observable<
+  Req['async'] extends true ? {_id: string} : IdentifiedSanityDocumentStub & DocumentShape
+> {
+  const dataset = hasDataset(client.config())
+  return _request(client, httpRequest, {
+    method: 'POST',
+    uri: `/assist/tasks/instruct/${dataset}`,
+    body: request,
+  })
+}