@sanity/client 6.29.0-generate.2 → 6.29.0-generate.5

package/dist/index.d.cts

@@ -1,10 +1,10 @@
-import type {AgentActionAsync} from '@sanity/client/agent/actions/commonTypes'
+import type {AgentActionAsync as AgentActionAsync_2} from '@sanity/client/agent/actions/commonTypes'
 import type {AgentActionPath as AgentActionPath_2} from '@sanity/client/agent/actions/commonTypes'
 import type {AgentActionPathSegment as AgentActionPathSegment_2} from '@sanity/client/agent/actions/commonTypes'
-import type {AgentActionRequestBase} from '@sanity/client/agent/actions/commonTypes'
-import type {AgentActionSync} from '@sanity/client/agent/actions/commonTypes'
+import type {AgentActionRequestBase as AgentActionRequestBase_2} from '@sanity/client/agent/actions/commonTypes'
+import type {AgentActionSync as AgentActionSync_2} from '@sanity/client/agent/actions/commonTypes'
 import type {AgentActionTarget as AgentActionTarget_2} from '@sanity/client/agent/actions/commonTypes'
-import type {AgentActionTargetInclude} from '@sanity/client/agent/actions/commonTypes'
+import type {AgentActionTargetInclude as AgentActionTargetInclude_2} from '@sanity/client/agent/actions/commonTypes'
 import type {ContentSourceMapDocuments as ContentSourceMapDocuments_2} from '@sanity/client/csm'
 import {ContentSourceMapParsedPath} from '@sanity/client/csm'
 import {ContentSourceMapParsedPathKeyedSegment} from '@sanity/client/csm'
@@ -46,6 +46,19 @@ export declare interface ActionErrorItem {
   index: number
 }
 
+/** @beta */
+export declare interface AgentActionAsync {
+  /**
+   * 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 noWrite, as async: true does not return the resulting document
+   */
+  async: true
+}
+
 /** @beta */
 export declare type AgentActionParam =
   | string
@@ -67,28 +80,147 @@ export declare type AgentActionPathSegment =
       _key: string
     }
 
+/** @beta */
+export declare interface AgentActionRequestBase {
+  /** schemaId as reported by sanity deploy / sanity schema store */
+  schemaId: string
+  /**
+   * When a type or field in the schema has a function set for `hidden` or `readOnly`, it is conditional.
+   *
+   * By default, Generate 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 Generate,
+   * and cannot be changed via conditionalPaths
+   *
+   * conditionalPaths state only apply to fields and types that have conditional `hidden` or `readOnly` in their schema definition.
+   *
+   * Consider using `hidden: () => true` in schema config, if a field should be writeable only by Generate and never
+   * visible in the studio – then make the field visible to the Generate using `conditionalPaths`.
+   *
+   * @see GenerateRequestBase#target
+   */
+  conditionalPaths?: {
+    defaultReadOnly?: boolean
+    defaultHidden?: boolean
+    paths?: {
+      /** path here is not a relative path: it must be the full document path, regardless of `path` param used in targets */
+      path: AgentActionPath
+      readOnly: boolean
+      hidden: boolean
+    }[]
+  }
+  /**
+   * When localeSettings is provided on the request, instruct can write to date and datetime fields.
+   * Otherwise, such fields will be ignored.
+   */
+  localeSettings?: {
+    /**
+     * A valid Unicode BCP 47 locale identifier used to interpret and format
+     * natural language inputs and date output. Examples include "en-US", "fr-FR", or "ja-JP".
+     *
+     * This affects how phrases like "next Friday" or "in two weeks" are parsed,
+     * and how resulting dates are presented (e.g., 12-hour vs 24-hour format).
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#getcanonicalocales
+     */
+    locale: string
+    /**
+     * A valid IANA time zone identifier used to resolve relative and absolute
+     * date expressions to a specific point in time. Examples include
+     * "America/New_York", "Europe/Paris", or "Asia/Tokyo".
+     *
+     * This ensures phrases like "tomorrow at 9am" are interpreted correctly
+     * based on the user's local time.
+     *
+     * @see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+     */
+    timeZone: string
+  }
+  /**
+   * Controls how much variance the instructions will run with.
+   *
+   * Value must be in the range [0, 1] (inclusive).
+   *
+   * Defaults:
+   * - generate: 0.3
+   * - translate: 0
+   * - transform: 0
+   */
+  temperature?: number
+}
+
 /** @public */
 declare class AgentActionsClient {
   #private
   constructor(client: SanityClient, httpRequest: HttpRequest)
-  generate(request: GenerateAsyncInstruction): Promise<{
-    _id: string
-  }>
+  /**
+   * Run an instruction to generate content in a target document.
+   * @param request instruction request
+   */
   generate<DocumentShape extends Record<string, Any>>(
-    request: GenerateSyncInstruction<DocumentShape>,
-  ): Promise<IdentifiedSanityDocumentStub & DocumentShape>
-  transform(request: TransformDocumentAsync): Promise<{
-    _id: string
-  }>
+    request: GenerateInstruction<DocumentShape>,
+  ): Promise<
+    (typeof request)['async'] extends true
+      ? {
+          _id: string
+        }
+      : IdentifiedSanityDocumentStub & DocumentShape
+  >
+  /**
+   * Transform a target document based on a source.
+   * @param request translation request
+   */
   transform<DocumentShape extends Record<string, Any>>(
-    request: TransformDocumentSync,
-  ): Promise<IdentifiedSanityDocumentStub & DocumentShape>
-  translate(request: TranslateDocumentAsync): Promise<{
-    _id: string
-  }>
+    request: TransformDocument<DocumentShape>,
+  ): Promise<
+    (typeof request)['async'] extends true
+      ? {
+          _id: string
+        }
+      : IdentifiedSanityDocumentStub & DocumentShape
+  >
+  /**
+   * Translate a target document based on a source.
+   * @param request translation request
+   */
   translate<DocumentShape extends Record<string, Any>>(
-    request: TranslateDocumentSync,
-  ): Promise<IdentifiedSanityDocumentStub & DocumentShape>
+    request: TranslateDocument<DocumentShape>,
+  ): Promise<
+    (typeof request)['async'] extends true
+      ? {
+          _id: string
+        }
+      : IdentifiedSanityDocumentStub & DocumentShape
+  >
+}
+
+/** @beta */
+export declare interface AgentActionSync {
+  /**
+   * By default, noWrite: false.
+   * Write enabled operations will mutate the target document, and emit AI presence in the studio.
+   *
+   * When noWrite: true, the api will not mutate any documents nor emit presence.
+   * Ie, when true, no changes will be made to content-lake
+   *
+   * noWrite: true is incompatible with async: true,
+   * as noWrite implies that you will use the return value of the operation
+   */
+  noWrite?: 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 noWrite: true, as async: true does not return the resulting document
+   */
+  async?: false
 }
 
 /**
@@ -143,7 +275,24 @@ export declare interface AgentActionTarget {
 }
 
 /**  @beta */
-declare type AgentActionTypeConfig =
+export declare interface AgentActionTargetInclude {
+  path: AgentActionPathSegment | AgentActionPath
+  /**
+   * By default, all children up to `target.maxPathDepth` are included.
+   * Fields or array items not on the exclude list, are implicitly included.
+   */
+  exclude?: AgentActionPathSegment[]
+  /**
+   * Types can be used to exclude array item types or all fields directly under the target path of a certain type.
+   * If you do exclude: ['string'] all string fields under the target will be excluded, for instance.
+   *
+   * `types.include` and `types.exclude` are mutually exclusive.
+   */
+  types?: AgentActionTypeConfig
+}
+
+/**  @beta */
+export declare type AgentActionTypeConfig =
   | {
       include: string[]
       exclude?: never
@@ -1008,12 +1157,10 @@ export declare type FirstDocumentMutationOptions = BaseMutationOptions & {
 }
 
 /** @beta */
-declare type GenerateAsyncInstruction<T extends Record<string, Any> = Record<string, Any>> = (
-  | GenerateExistingDocumentRequest
-  | GenerateCreateDocumentRequest<T>
-) &
-  GenerateRequestBase &
-  AgentActionAsync
+export declare type GenerateAsyncInstruction<T extends Record<string, Any> = Record<string, Any>> =
+  (GenerateExistingDocumentRequest | GenerateCreateDocumentRequest<T>) &
+    GenerateRequestBase &
+    AgentActionAsync_2
 
 /**
  * Instruction to create a new document
@@ -1048,7 +1195,7 @@ export declare type GenerateInstruction<T extends Record<string, Any> = Record<s
 export declare type GenerateOperation = 'set' | 'append' | 'mixed'
 
 /**  @beta */
-declare interface GenerateRequestBase extends AgentActionRequestBase {
+export declare interface GenerateRequestBase extends AgentActionRequestBase_2 {
   /** schemaId as reported by sanity deploy / sanity schema store */
   schemaId: string
   /** string template using $variable  */
@@ -1072,12 +1219,12 @@ declare interface GenerateRequestBase extends AgentActionRequestBase {
 }
 
 /** @beta */
-declare type GenerateSyncInstruction<T extends Record<string, Any> = Record<string, Any>> = (
+export declare type GenerateSyncInstruction<T extends Record<string, Any> = Record<string, Any>> = (
   | GenerateExistingDocumentRequest
   | GenerateCreateDocumentRequest<T>
 ) &
   GenerateRequestBase &
-  AgentActionSync
+  AgentActionSync_2
 
 /**  @beta */
 export declare interface GenerateTarget extends AgentActionTarget_2 {
@@ -1125,7 +1272,7 @@ export declare interface GenerateTarget extends AgentActionTarget_2 {
 }
 
 /**  @beta */
-export declare interface GenerateTargetInclude extends AgentActionTargetInclude {
+export declare interface GenerateTargetInclude extends AgentActionTargetInclude_2 {
   /**
    * Sets the operation for this path, and all its children.
    * This overrides any operation set parents or the root target.
@@ -1589,24 +1736,45 @@ export declare type MutationSelectionQueryParams = {
 declare class ObservableAgentsActionClient {
   #private
   constructor(client: ObservableSanityClient, httpRequest: HttpRequest)
-  generate(request: GenerateAsyncInstruction): Observable<{
-    _id: string
-  }>
+  /**
+   * Run an instruction to generate content in a target document.
+   * @param request instruction request
+   */
   generate<DocumentShape extends Record<string, Any>>(
-    request: GenerateSyncInstruction<DocumentShape>,
-  ): Observable<IdentifiedSanityDocumentStub & DocumentShape>
-  transform(request: TransformDocumentAsync): Observable<{
-    _id: string
-  }>
+    request: GenerateInstruction<DocumentShape>,
+  ): Observable<
+    (typeof request)['async'] extends true
+      ? {
+          _id: string
+        }
+      : IdentifiedSanityDocumentStub & DocumentShape
+  >
+  /**
+   * Transform a target document based on a source.
+   * @param request translation request
+   */
   transform<DocumentShape extends Record<string, Any>>(
-    request: TransformDocumentSync,
-  ): Observable<IdentifiedSanityDocumentStub & DocumentShape>
-  translate(request: TranslateDocumentAsync): Observable<{
-    _id: string
-  }>
+    request: TransformDocument<DocumentShape>,
+  ): Observable<
+    (typeof request)['async'] extends true
+      ? {
+          _id: string
+        }
+      : IdentifiedSanityDocumentStub & DocumentShape
+  >
+  /**
+   * Translate a target document based on a source.
+   * @param request translation request
+   */
   translate<DocumentShape extends Record<string, Any>>(
-    request: TranslateDocumentSync,
-  ): Observable<IdentifiedSanityDocumentStub & DocumentShape>
+    request: TranslateDocument<DocumentShape>,
+  ): Observable<
+    (typeof request)['async'] extends true
+      ? {
+          _id: string
+        }
+      : IdentifiedSanityDocumentStub & DocumentShape
+  >
 }
 
 /** @internal */
@@ -3526,16 +3694,19 @@ export declare type TransactionMutationOptions =
   | TransactionAllDocumentIdsMutationOptions
 
 /** @beta */
-export declare type TransformDocument = TransformDocumentSync | TransformDocumentAsync
+export declare type TransformDocument<T extends Record<string, Any> = Record<string, Any>> =
+  | TransformDocumentSync<T>
+  | TransformDocumentAsync
 
 /** @beta */
-declare type TransformDocumentAsync = TransformRequestBase & AgentActionAsync
+export declare type TransformDocumentAsync = TransformRequestBase & AgentActionAsync_2
 
 /** @beta */
-declare type TransformDocumentSync = TransformRequestBase & AgentActionSync
+export declare type TransformDocumentSync<T extends Record<string, Any> = Record<string, Any>> =
+  TransformRequestBase & AgentActionSync_2
 
 /**  @beta */
-declare interface TransformRequestBase extends AgentActionRequestBase {
+export declare interface TransformRequestBase extends AgentActionRequestBase_2 {
   /** schemaId as reported by sanity deploy / sanity schema store */
   schemaId: string
   documentId: string
@@ -3594,7 +3765,7 @@ export declare type TransformTargetDocument =
     }
 
 /**  @beta */
-export declare interface TransformTargetInclude extends AgentActionTargetInclude {
+export declare interface TransformTargetInclude extends AgentActionTargetInclude_2 {
   /** string template using $variable from instructionParams  */
   transformation?: string
   /**
@@ -3608,22 +3779,25 @@ export declare interface TransformTargetInclude extends AgentActionTargetInclude
 }
 
 /** @beta */
-export declare type TranslateDocument = TranslateDocumentSync | TranslateDocumentAsync
+export declare type TranslateDocument<T extends Record<string, Any> = Record<string, Any>> =
+  | TranslateDocumentSync<T>
+  | TranslateDocumentAsync
 
 /** @beta */
-declare type TranslateDocumentAsync = TranslateRequestBase & AgentActionAsync
+export declare type TranslateDocumentAsync = TranslateRequestBase & AgentActionAsync_2
 
 /** @beta */
-declare type TranslateDocumentSync = TranslateRequestBase & AgentActionSync
+export declare type TranslateDocumentSync<T extends Record<string, Any> = Record<string, Any>> =
+  TranslateRequestBase & AgentActionSync_2
 
 /**  @beta */
-declare interface TranslateLanguage {
+export declare interface TranslateLanguage {
   id: string
   title?: string
 }
 
 /**  @beta */
-declare interface TranslateRequestBase extends AgentActionRequestBase {
+export declare interface TranslateRequestBase extends AgentActionRequestBase_2 {
   /** schemaId as reported by sanity deploy / sanity schema store */
   schemaId: string
   documentId: string
@@ -3667,7 +3841,7 @@ export declare interface TranslateTarget extends AgentActionTarget {
 }
 
 /**  @beta */
-export declare interface TranslateTargetInclude extends AgentActionTargetInclude {
+export declare interface TranslateTargetInclude extends AgentActionTargetInclude_2 {
   /** string template using $variable from instructionParams  */
   styleGuide?: string
   /**