@sanity/client 6.28.2 → 6.28.3-instruct.1

package/dist/stega.d.cts

@@ -33,6 +33,18 @@ export declare interface ActionErrorItem {
   index: number
 }
 
+/** @public */
+declare class AiClient {
+  #private
+  constructor(client: SanityClient, httpRequest: HttpRequest)
+  instruct(request: InstructAsyncInstruction): Promise<{
+    _id: string
+  }>
+  instruct<DocumentShape extends Record<string, Any>>(
+    request: InstructSyncInstruction<DocumentShape>,
+  ): Promise<IdentifiedSanityDocumentStub & DocumentShape>
+}
+
 /** @internal */
 export declare type AllDocumentIdsMutationOptions = BaseMutationOptions & {
   returnFirst: false
@@ -110,6 +122,18 @@ export declare class AssetsClient {
   ): Promise<SanityAssetDocument | SanityImageAssetDocument>
 }
 
+declare interface Async {
+  /**
+   * When async: true, requests responds with status 201 and {_id} as response body as soon as the request is validated.
+   * The instruction operation will carry on in the background.
+   *
+   * When async: false (default), requests respond with status 200 and the document value after instruction has been applied.
+   *
+   * async: true is incompatible with skipWrite, as async: true does not return the resulting document
+   */
+  async: true
+}
+
 /** @internal */
 export declare type AttributeSet = {
   [key: string]: Any
@@ -336,14 +360,14 @@ export declare interface ClientConfig {
   /**
    * What perspective to use for the client. See {@link https://www.sanity.io/docs/perspectives|perspective documentation}
    * @remarks
-   * As of API version `v2025-02-19`, the default perspective has changed from `raw` to `published`. {@link https://www.sanity.io/changelog/e93a2d5a-9cee-4801-829e-8d3394bfed85|Changelog}
+   * As of API version `v2025-02-19`, the default perspective has changed from `raw` to `published`. {@link https://www.sanity.io/changelog/676aaa9d-2da6-44fb-abe5-580f28047c10|Changelog}
    * @defaultValue 'published'
    */
   perspective?: ClientPerspective
   apiHost?: string
   /**
      @remarks
-     * As of API version `v2025-02-19`, the default perspective has changed from `raw` to `published`. {@link https://www.sanity.io/changelog/e93a2d5a-9cee-4801-829e-8d3394bfed85|Changelog}
+     * As of API version `v2025-02-19`, the default perspective has changed from `raw` to `published`. {@link https://www.sanity.io/changelog/676aaa9d-2da6-44fb-abe5-580f28047c10|Changelog}
      */
   apiVersion?: string
   proxy?: string
@@ -673,6 +697,18 @@ export declare type CreateAction = {
  */
 export declare const createClient: (config: ClientConfig_2) => SanityClient
 
+/**
+ * Instruction to create a new document
+ * @beta
+ */
+declare interface CreateDocumentRequest<T extends Record<string, Any> = Record<string, Any>> {
+  createDocument: {
+    /** if no _id is provided, one will be generated. _id is always returned when the requests succeed */
+    _id?: string
+    _type: string
+  } & SanityDocumentStub<T>
+}
+
 /** @public */
 export declare interface CurrentSanityUser {
   id: string
@@ -817,6 +853,19 @@ export declare type DisconnectEvent = {
   reason: string
 }
 
+/**
+ *
+ * Includes a LLM-friendly version of the document in the instruction
+ * @beta
+ * */
+declare interface DocumentInstructionParam {
+  type: 'document'
+  /**
+   * If omitted, implicitly uses the documentId of the instruction target
+   */
+  documentId?: string
+}
+
 /**
  * Modifies an existing draft document.
  * It applies the given patch to the document referenced by draftId.
@@ -878,6 +927,14 @@ export declare type EventSourceEvent<Name extends string> = ServerSentEvent<Name
  */
 export declare type EventSourceInstance = InstanceType<typeof globalThis.EventSource>
 
+/**
+ * Instruction for an existing document.
+ * @beta
+ */
+declare interface ExistingDocumentRequest {
+  documentId: string
+}
+
 /** @public */
 export declare type FilterDefault = (props: {
   /**
@@ -1063,6 +1120,145 @@ export declare type InsertPatch =
       items: Any[]
     }
 
+/** @beta */
+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
+  | InstructConstantInstructionParam
+  | InstructFieldInstructionParam
+  | DocumentInstructionParam
+  | InstructGroqInstructionParam
+
+/** @beta */
+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.
  *
@@ -1134,7 +1330,7 @@ export declare interface ListenOptions {
   includePreviousRevision?: boolean
   /**
    * Whether to include events for drafts and versions. As of API Version >= v2025-02-19, only events
-   * for published documents will be included by default (see {@link https://www.sanity.io/changelog/e93a2d5a-9cee-4801-829e-8d3394bfed85|Changelog})
+   * for published documents will be included by default (see {@link https://www.sanity.io/changelog/676aaa9d-2da6-44fb-abe5-580f28047c10|Changelog})
    * If you need events from drafts and versions, set this to `true`.
    * Note: Keep in mind that additional document variants may be introduced in the future, so it's
    * recommended to respond to events in a way that's tolerant of potential future variants, e.g. by
@@ -1430,6 +1626,18 @@ export declare type MutationSelectionQueryParams = {
   [key: string]: Any
 }
 
+/** @public */
+declare class ObservableAiClient {
+  #private
+  constructor(client: ObservableSanityClient, httpRequest: HttpRequest)
+  instruct(request: InstructAsyncInstruction): Observable<{
+    _id: string
+  }>
+  instruct<DocumentShape extends Record<string, Any>>(
+    request: InstructSyncInstruction<DocumentShape>,
+  ): Observable<IdentifiedSanityDocumentStub & DocumentShape>
+}
+
 /** @internal */
 export declare class ObservableAssetsClient {
   #private
@@ -1607,6 +1815,7 @@ export declare class ObservableSanityClient {
   live: LiveClient
   projects: ObservableProjectsClient
   users: ObservableUsersClient
+  ai: ObservableAiClient
   /**
    * Instance properties
    */
@@ -2538,6 +2747,7 @@ export declare class SanityClient {
   live: LiveClient
   projects: ProjectsClient
   users: UsersClient
+  ai: AiClient
   /**
    * Observable version of the Sanity client, with the same configuration as the promise-based one
    */
@@ -3321,6 +3531,29 @@ export declare type StudioBaseUrl =
 /** @alpha */
 export declare type StudioUrl = StudioBaseUrl | StudioBaseRoute
 
+declare interface Sync {
+  /**
+   * By default, skipWrite: false.
+   * Write enabled operations will mutate the target document, and emit AI presence in the studio.
+   *
+   * When skipWrite: true, the api will not mutate any documents nor emit presence.
+   * Ie, when true, no changes will be made to content-lake
+   *
+   * skipWrite: true is incompatible with async: true,
+   * as skipWrite implies that you will use the return value of the operation
+   */
+  skipWrite?: boolean
+  /**
+   * When async: true, requests responds with status 201 and {_id} as response body as soon as the request is validated.
+   * The instruction operation will carry on in the background.
+   *
+   * When async: false (default), requests respond with status 200 and the document value after instruction has been applied.
+   *
+   * async: true is incompatible with skipWrite: true, as async: true does not return the resulting document
+   */
+  async?: false
+}
+
 /** @public */
 export declare type SyncTag = `s1:${string}`
 

package/dist/stega.d.ts

@@ -33,6 +33,18 @@ export declare interface ActionErrorItem {
   index: number
 }
 
+/** @public */
+declare class AiClient {
+  #private
+  constructor(client: SanityClient, httpRequest: HttpRequest)
+  instruct(request: InstructAsyncInstruction): Promise<{
+    _id: string
+  }>
+  instruct<DocumentShape extends Record<string, Any>>(
+    request: InstructSyncInstruction<DocumentShape>,
+  ): Promise<IdentifiedSanityDocumentStub & DocumentShape>
+}
+
 /** @internal */
 export declare type AllDocumentIdsMutationOptions = BaseMutationOptions & {
   returnFirst: false
@@ -110,6 +122,18 @@ export declare class AssetsClient {
   ): Promise<SanityAssetDocument | SanityImageAssetDocument>
 }
 
+declare interface Async {
+  /**
+   * When async: true, requests responds with status 201 and {_id} as response body as soon as the request is validated.
+   * The instruction operation will carry on in the background.
+   *
+   * When async: false (default), requests respond with status 200 and the document value after instruction has been applied.
+   *
+   * async: true is incompatible with skipWrite, as async: true does not return the resulting document
+   */
+  async: true
+}
+
 /** @internal */
 export declare type AttributeSet = {
   [key: string]: Any
@@ -336,14 +360,14 @@ export declare interface ClientConfig {
   /**
    * What perspective to use for the client. See {@link https://www.sanity.io/docs/perspectives|perspective documentation}
    * @remarks
-   * As of API version `v2025-02-19`, the default perspective has changed from `raw` to `published`. {@link https://www.sanity.io/changelog/e93a2d5a-9cee-4801-829e-8d3394bfed85|Changelog}
+   * As of API version `v2025-02-19`, the default perspective has changed from `raw` to `published`. {@link https://www.sanity.io/changelog/676aaa9d-2da6-44fb-abe5-580f28047c10|Changelog}
    * @defaultValue 'published'
    */
   perspective?: ClientPerspective
   apiHost?: string
   /**
      @remarks
-     * As of API version `v2025-02-19`, the default perspective has changed from `raw` to `published`. {@link https://www.sanity.io/changelog/e93a2d5a-9cee-4801-829e-8d3394bfed85|Changelog}
+     * As of API version `v2025-02-19`, the default perspective has changed from `raw` to `published`. {@link https://www.sanity.io/changelog/676aaa9d-2da6-44fb-abe5-580f28047c10|Changelog}
      */
   apiVersion?: string
   proxy?: string
@@ -673,6 +697,18 @@ export declare type CreateAction = {
  */
 export declare const createClient: (config: ClientConfig_2) => SanityClient
 
+/**
+ * Instruction to create a new document
+ * @beta
+ */
+declare interface CreateDocumentRequest<T extends Record<string, Any> = Record<string, Any>> {
+  createDocument: {
+    /** if no _id is provided, one will be generated. _id is always returned when the requests succeed */
+    _id?: string
+    _type: string
+  } & SanityDocumentStub<T>
+}
+
 /** @public */
 export declare interface CurrentSanityUser {
   id: string
@@ -817,6 +853,19 @@ export declare type DisconnectEvent = {
   reason: string
 }
 
+/**
+ *
+ * Includes a LLM-friendly version of the document in the instruction
+ * @beta
+ * */
+declare interface DocumentInstructionParam {
+  type: 'document'
+  /**
+   * If omitted, implicitly uses the documentId of the instruction target
+   */
+  documentId?: string
+}
+
 /**
  * Modifies an existing draft document.
  * It applies the given patch to the document referenced by draftId.
@@ -878,6 +927,14 @@ export declare type EventSourceEvent<Name extends string> = ServerSentEvent<Name
  */
 export declare type EventSourceInstance = InstanceType<typeof globalThis.EventSource>
 
+/**
+ * Instruction for an existing document.
+ * @beta
+ */
+declare interface ExistingDocumentRequest {
+  documentId: string
+}
+
 /** @public */
 export declare type FilterDefault = (props: {
   /**
@@ -1063,6 +1120,145 @@ export declare type InsertPatch =
       items: Any[]
     }
 
+/** @beta */
+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
+  | InstructConstantInstructionParam
+  | InstructFieldInstructionParam
+  | DocumentInstructionParam
+  | InstructGroqInstructionParam
+
+/** @beta */
+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.
  *
@@ -1134,7 +1330,7 @@ export declare interface ListenOptions {
   includePreviousRevision?: boolean
   /**
    * Whether to include events for drafts and versions. As of API Version >= v2025-02-19, only events
-   * for published documents will be included by default (see {@link https://www.sanity.io/changelog/e93a2d5a-9cee-4801-829e-8d3394bfed85|Changelog})
+   * for published documents will be included by default (see {@link https://www.sanity.io/changelog/676aaa9d-2da6-44fb-abe5-580f28047c10|Changelog})
    * If you need events from drafts and versions, set this to `true`.
    * Note: Keep in mind that additional document variants may be introduced in the future, so it's
    * recommended to respond to events in a way that's tolerant of potential future variants, e.g. by
@@ -1430,6 +1626,18 @@ export declare type MutationSelectionQueryParams = {
   [key: string]: Any
 }
 
+/** @public */
+declare class ObservableAiClient {
+  #private
+  constructor(client: ObservableSanityClient, httpRequest: HttpRequest)
+  instruct(request: InstructAsyncInstruction): Observable<{
+    _id: string
+  }>
+  instruct<DocumentShape extends Record<string, Any>>(
+    request: InstructSyncInstruction<DocumentShape>,
+  ): Observable<IdentifiedSanityDocumentStub & DocumentShape>
+}
+
 /** @internal */
 export declare class ObservableAssetsClient {
   #private
@@ -1607,6 +1815,7 @@ export declare class ObservableSanityClient {
   live: LiveClient
   projects: ObservableProjectsClient
   users: ObservableUsersClient
+  ai: ObservableAiClient
   /**
    * Instance properties
    */
@@ -2538,6 +2747,7 @@ export declare class SanityClient {
   live: LiveClient
   projects: ProjectsClient
   users: UsersClient
+  ai: AiClient
   /**
    * Observable version of the Sanity client, with the same configuration as the promise-based one
    */
@@ -3321,6 +3531,29 @@ export declare type StudioBaseUrl =
 /** @alpha */
 export declare type StudioUrl = StudioBaseUrl | StudioBaseRoute
 
+declare interface Sync {
+  /**
+   * By default, skipWrite: false.
+   * Write enabled operations will mutate the target document, and emit AI presence in the studio.
+   *
+   * When skipWrite: true, the api will not mutate any documents nor emit presence.
+   * Ie, when true, no changes will be made to content-lake
+   *
+   * skipWrite: true is incompatible with async: true,
+   * as skipWrite implies that you will use the return value of the operation
+   */
+  skipWrite?: boolean
+  /**
+   * When async: true, requests responds with status 201 and {_id} as response body as soon as the request is validated.
+   * The instruction operation will carry on in the background.
+   *
+   * When async: false (default), requests respond with status 200 and the document value after instruction has been applied.
+   *
+   * async: true is incompatible with skipWrite: true, as async: true does not return the resulting document
+   */
+  async?: false
+}
+
 /** @public */
 export declare type SyncTag = `s1:${string}`