@sanity/client 7.2.2 → 7.4.0

package/dist/index.d.cts

@@ -1,6 +1,7 @@
 import type {ContentSourceMapDocuments as ContentSourceMapDocuments_2} from '@sanity/client/csm'
 import {ContentSourceMapParsedPath} from '@sanity/client/csm'
 import {ContentSourceMapParsedPathKeyedSegment} from '@sanity/client/csm'
+import type {HttpContext} from 'get-it'
 import {Observable} from 'rxjs'
 import {Requester} from 'get-it'
 import type {ResolveStudioUrl} from '@sanity/client/csm'
@@ -24,11 +25,9 @@ export declare type Action =
 
 /** @internal */
 export declare interface ActionError {
-  error: {
-    type: 'actionError'
-    description: string
-    items?: ActionErrorItem[]
-  }
+  type: 'actionError'
+  description: string
+  items?: ActionErrorItem[]
 }
 
 /** @internal */
@@ -55,15 +54,27 @@ declare interface AgentActionAsync {
 }
 
 /** @beta */
-export declare type AgentActionParam =
+export declare type AgentActionParam<
+  TParamConfig extends {
+    docIdRequired: boolean
+  } = {
+    docIdRequired: false
+  },
+> =
   | string
   | ConstantAgentActionParam
-  | FieldAgentActionParam
-  | DocumentAgentActionParam
+  | FieldAgentActionParam<TParamConfig>
+  | DocumentAgentActionParam<TParamConfig>
   | GroqAgentActionParam
 
 /** @beta */
-export declare type AgentActionParams = Record<string, AgentActionParam>
+export declare type AgentActionParams<
+  TParamConfig extends {
+    docIdRequired: boolean
+  } = {
+    docIdRequired: false
+  },
+> = Record<string, AgentActionParam<TParamConfig>>
 
 /**  @beta */
 export declare type AgentActionPath = AgentActionPathSegment[]
@@ -76,39 +87,7 @@ export declare type AgentActionPathSegment =
     }
 
 /** @beta */
-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
-    }[]
-  }
+declare interface AgentActionRequestBase extends AgentActionSchema {
   /**
    * When localeSettings is provided on the request, instruct can write to date and datetime fields.
    * Otherwise, such fields will be ignored.
@@ -149,6 +128,68 @@ declare interface AgentActionRequestBase {
   temperature?: number
 }
 
+/** @beta */
+declare interface AgentActionSchema {
+  /** schemaId as reported by sanity deploy / sanity schema store */
+  schemaId: string
+  /**
+   * ### forcePublishedWrite: false (default)
+   * By default, agent actions will never write to a published document.
+   *
+   * Instead, they will force the use of a draft ID ("drafts.some-id") instead of the published ID ("some-id"),
+   * even when a published ID is provided.
+   *
+   * Actions will use state from an existing draft if it exists,
+   * or use the published document to create a draft, if no draft exists.
+   *
+   * Successful responses contains the _id that was mutated by the action.
+   *
+   *
+   * ### forcePublishedWrite: true
+   *
+   * When forcePublishedWrite: true an agent action will write to the exact id provided.
+   * The action will also not fallback to published state for draft ids.
+   *
+   *
+   * ### Versioned ids (releases)
+   *
+   * When an ID on the form "versions.<release>.some-id" is provided, agent actions will
+   * always behave as if `forcePublishedWrite: true`.
+   * That is, only the exact document state of the id provided is considered and mutated.
+   * */
+  forcePublishedWrite?: boolean
+  /**
+   * 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
+    }[]
+  }
+}
+
 /** @public */
 declare class AgentActionsClient {
   #private
@@ -192,6 +233,27 @@ declare class AgentActionsClient {
         }
       : IdentifiedSanityDocumentStub & DocumentShape
   >
+  /**
+   * Run a raw instruction and return the result either as text or json
+   * @param request - prompt request
+   */
+  prompt<const DocumentShape extends Record<string, Any>>(
+    request: PromptRequest<DocumentShape>,
+  ): Promise<(typeof request)['format'] extends 'json' ? DocumentShape : string>
+  /**
+   * Patch a document using a schema aware API.
+   * Does not use an LLM, but uses the schema to ensure paths and values matches the schema.
+   * @param request - instruction request
+   */
+  patch<DocumentShape extends Record<string, Any>>(
+    request: PatchDocument<DocumentShape>,
+  ): Promise<
+    (typeof request)['async'] extends true
+      ? {
+          _id: string
+        }
+      : IdentifiedSanityDocumentStub & DocumentShape
+  >
 }
 
 /** @beta */
@@ -315,6 +377,8 @@ export declare type AllDocumentsMutationOptions = BaseMutationOptions & {
  */
 export declare type Any = any
 
+declare type AnyNonNullable = Exclude<any, null | undefined>
+
 /** @internal */
 export declare interface ApiError {
   error: string
@@ -627,6 +691,12 @@ export declare interface ClientConfig {
    * Optional request tag prefix for all request tags
    */
   requestTagPrefix?: string
+  /**
+   * Optional default headers to include with all requests
+   *
+   * @remarks request-specific headers will override any default headers with the same name.
+   */
+  headers?: Record<string, string>
   ignoreBrowserTokenWarning?: boolean
   withCredentials?: boolean
   allowReconfigure?: boolean
@@ -693,7 +763,7 @@ export declare class ClientError extends Error {
   statusCode: ErrorProps['statusCode']
   responseBody: ErrorProps['responseBody']
   details: ErrorProps['details']
-  constructor(res: Any)
+  constructor(res: Any, context?: HttpContext)
 }
 
 /** @public */
@@ -1099,6 +1169,23 @@ export declare type DisconnectEvent = {
   reason: string
 }
 
+declare type DocIdParam<
+  TParamConfig extends {
+    docIdRequired: boolean
+  } = {
+    docIdRequired: false
+  },
+> = TParamConfig['docIdRequired'] extends true
+  ? {
+      documentId: string
+    }
+  : {
+      /**
+       * If omitted, implicitly uses the documentId of the instruction target
+       */
+      documentId?: string
+    }
+
 /**
  *
  * Includes a LLM-friendly version of the document in the instruction
@@ -1119,13 +1206,15 @@ export declare type DisconnectEvent = {
  *
  * @beta
  * */
-export declare interface DocumentAgentActionParam {
+export declare type DocumentAgentActionParam<
+  TParamConfig extends {
+    docIdRequired: boolean
+  } = {
+    docIdRequired: false
+  },
+> = {
   type: 'document'
-  /**
-   * If omitted, implicitly uses the documentId of the instruction target
-   */
-  documentId?: string
-}
+} & DocIdParam<TParamConfig>
 
 /** @internal */
 export declare type EditableReleaseDocument = Omit<
@@ -1212,17 +1301,19 @@ export declare type EventSourceInstance = InstanceType<typeof globalThis.EventSo
  *
  * @beta
  * */
-export declare interface FieldAgentActionParam {
+export declare type FieldAgentActionParam<
+  TParamConfig extends {
+    docIdRequired: boolean
+  } = {
+    docIdRequired: false
+  },
+> = {
   type: 'field'
   /**
    * Examples: 'title', ['array', \{_key: 'arrayItemKey'\}, 'field']
    */
   path: AgentActionPathSegment | AgentActionPath
-  /**
-   * If omitted, implicitly uses the documentId of the instruction target
-   */
-  documentId?: string
-}
+} & DocIdParam<TParamConfig>
 
 /** @public */
 export declare type FilterDefault = (props: {
@@ -1290,6 +1381,16 @@ export declare type FirstDocumentMutationOptions = BaseMutationOptions & {
   returnDocuments?: true
 }
 
+/**
+ * Formats a GROQ query parse error into a human-readable string.
+ *
+ * @param error - The error object containing details about the parse error.
+ * @param tag - An optional tag to include in the error message.
+ * @returns A formatted error message string.
+ * @public
+ */
+export declare function formatQueryParseError(error: QueryParseError, tag?: string | null): string
+
 /** @beta */
 declare type GenerateAsyncInstruction<T extends Record<string, Any> = Record<string, Any>> = (
   | GenerateExistingDocumentRequest
@@ -1303,8 +1404,11 @@ declare type GenerateAsyncInstruction<T extends Record<string, Any> = Record<str
  * @beta
  */
 declare interface GenerateExistingDocumentRequest {
+  /**
+   * @see #AgentActionSchema.forcePublishedWrite
+   */
   documentId: string
-  createDocument?: never
+  targetDocument?: never
 }
 
 /** @beta */
@@ -1324,7 +1428,7 @@ declare interface GenerateRequestBase extends AgentActionRequestBase {
    *
    * The LLM only has access to information in the instruction, plus the target schema.
    *
-   * string template using $variable
+   * String template with support for $variable from `instructionParams`.
    * */
   instruction: string
   /**
@@ -1419,6 +1523,21 @@ declare interface GenerateRequestBase extends AgentActionRequestBase {
    * - when multiple targets are provided, they will be coalesced into a single target sharing a common target root.
    * It is therefor an error to provide conflicting include/exclude across targets (ie, include title in one, and exclude it in another)
    *
+   * ## Generating images
+   *
+   * Generate will generate images the same was as AI Assist, for images that have been configured using
+   * [AI Assist schema options](https://github.com/sanity-io/assist/tree/main/plugin#image-generation).
+   *
+   * To generate images _without_ changing the schema, directly target an image asset path.
+   *
+   * For example, all the following will generate an image into the provided asset:
+   * * `target: {path: ['image', 'asset'] }`
+   * * `target: {path: 'image', include: ['asset'] }`
+   *
+   * Image generation can be combined with regular content targets:
+   * * `target: [{path: ['image', 'asset'] }, {include: ['title', 'description']}]`
+   *
+   * Since Generate happens in a single LLM pass, the image will be contextually related to other generated content.
    * @see AgentActionRequestBase#conditionalPaths
    */
   target?: GenerateTarget | GenerateTarget[]
@@ -1465,6 +1584,7 @@ export declare interface GenerateTarget extends AgentActionTarget {
    * @see #AgentActionTargetInclude.operation
    * @see #include
    * @see #AgentActionTargetInclude.include
+   * @see #AgentActionSchema.forcePublishedWrite
    */
   operation?: GenerateOperation
   /**
@@ -1481,22 +1601,34 @@ export declare interface GenerateTarget extends AgentActionTarget {
 export declare type GenerateTargetDocument<T extends Record<string, Any> = Record<string, Any>> =
   | {
       operation: 'edit'
+      /**
+       * @see #AgentActionSchema.forcePublishedWrite
+       */
       _id: string
     }
   | {
       operation: 'create'
+      /**
+       * @see #AgentActionSchema.forcePublishedWrite
+       */
       _id?: string
       _type: string
       initialValues?: T
     }
   | {
       operation: 'createIfNotExists'
+      /**
+       * @see #AgentActionSchema.forcePublishedWrite
+       */
       _id: string
       _type: string
       initialValues?: T
     }
   | {
       operation: 'createOrReplace'
+      /**
+       * @see #AgentActionSchema.forcePublishedWrite
+       */
       _id: string
       _type: string
       initialValues?: T
@@ -1509,6 +1641,9 @@ export declare type GenerateTargetDocument<T extends Record<string, Any> = Recor
 declare interface GenerateTargetDocumentRequest<
   T extends Record<string, Any> = Record<string, Any>,
 > {
+  /**
+   * @see #AgentActionSchema.forcePublishedWrite
+   */
   targetDocument: GenerateTargetDocument<T>
   documentId?: never
 }
@@ -1597,6 +1732,12 @@ export declare interface InitializedClientConfig extends ClientConfig {
    * The fully initialized stega config, can be used to check if stega is enabled
    */
   stega: InitializedStegaConfig
+  /**
+   * Default headers to include with all requests
+   *
+   * @remarks request-specific headers will override any default headers with the same name.
+   */
+  headers?: Record<string, string>
 }
 
 /** @public */
@@ -1618,6 +1759,9 @@ export declare type InsertPatch =
       items: Any[]
     }
 
+/** @internal */
+export declare function isQueryParseError(error: object): error is QueryParseError
+
 /**
  * Set up a listener that will be notified when mutations occur on documents matching the provided query/filter.
  *
@@ -1851,11 +1995,9 @@ export declare type Mutation<R extends Record<string, Any> = Record<string, Any>
 
 /** @internal */
 export declare interface MutationError {
-  error: {
-    type: 'mutationError'
-    description: string
-    items?: MutationErrorItem[]
-  }
+  type: 'mutationError'
+  description: string
+  items?: MutationErrorItem[]
 }
 
 /** @internal */
@@ -3374,9 +3516,45 @@ export declare class Patch extends BasePatch {
 /** @public */
 export declare type PatchBuilder = (patch: Patch) => Patch
 
+/** @beta */
+export declare type PatchDocument<T extends Record<string, Any> = Record<string, Any>> =
+  | PatchDocumentSync<T>
+  | PatchDocumentAsync<T>
+
+/** @beta */
+declare type PatchDocumentAsync<T extends Record<string, Any> = Record<string, Any>> = (
+  | PatchExistingDocumentRequest
+  | PatchTargetDocumentRequest<T>
+) &
+  PatchRequestBase &
+  AgentActionAsync
+
+/** @beta */
+declare type PatchDocumentSync<T extends Record<string, Any> = Record<string, Any>> = (
+  | PatchExistingDocumentRequest
+  | PatchTargetDocumentRequest<T>
+) &
+  PatchRequestBase &
+  AgentActionSync
+
+/**
+ * Patches an existing document
+ * @beta
+ */
+declare interface PatchExistingDocumentRequest {
+  /**
+   * @see #AgentActionSchema.forcePublishedWrite
+   */
+  documentId: string
+  targetDocument?: never
+}
+
 /** @internal */
 export declare type PatchMutationOperation = PatchOperations & MutationSelection
 
+/**  @beta */
+export declare type PatchOperation = 'set' | 'append' | 'mixed' | 'unset'
+
 /** @internal */
 export declare interface PatchOperations {
   set?: {
@@ -3399,9 +3577,80 @@ export declare interface PatchOperations {
   ifRevisionID?: string
 }
 
+/**  @beta */
+declare interface PatchRequestBase extends AgentActionSchema {
+  /**
+   * Target defines which parts of the document will be affected by the instruction.
+   * It can be an array, so multiple parts of the document can be separately configured in detail.
+   *
+   * Omitting target implies that the document itself is the root.
+   *
+   * Notes:
+   * - instruction can only affect fields up to `maxPathDepth`
+   * - when multiple targets are provided, they will be coalesced into a single target sharing a common target root.
+   * It is therefore an error to provide conflicting include/exclude across targets (ie, include title in one, and exclude it in another)
+   *
+   * @see AgentActionRequestBase#conditionalPaths
+   */
+  target: PatchTarget | PatchTarget[]
+}
+
 /** @internal */
 export declare type PatchSelection = string | string[] | MutationSelection
 
+/**  @beta */
+export declare type PatchTarget = {
+  /**
+   * Determines how the target path will be patched.
+   *
+   * ### Operation types
+   * - `'set'` – an *overwriting* operation: sets the full field value for primitive targets, and merges the provided value with existing values for objects
+   * - `'append'`:
+   *    – array fields: appends new items to the end of the array,
+   *    - string fields: '"existing content" "new content"'
+   *    - text fields: '"existing content"\\n"new content"'
+   *    - number fields: existing + new
+   *    - other field types not mentioned will set instead (dates, url)
+   * - `'mixed'` –  sets non-array fields, and appends to array fields
+   * - `'unset'` – removes whatever value is on the target path
+   *
+   * All operations except unset requires a `value`.
+   *
+   * #### Appending in the middle of arrays
+   * To append to an array, use the 'append' operation, and provide an array value with one or more array items.
+   *
+   * `target: {path: ['array'], operation: 'append', value: [{_type: 'item' _key: 'a'}]}` will append the items in the value to the existing array.
+   *
+   * To insert in the middle of the array, use `target: {path: ['array', {_key: 'appendAfterKey'}], operation: 'append', value: [{_type: 'item' _key: 'a'}]}`.
+   * Here, `{_type: 'item' _key: 'a'}` will be appended after the array item with key `'appendAfterKey'`
+   *
+   * It is optional to provide a _key for inserted array items; if one isn't provided, it will be generated.
+   */
+  operation: PatchOperation
+  path: AgentActionPathSegment | AgentActionPath
+} & (
+  | {
+      operation: 'unset'
+      value?: never
+    }
+  | {
+      operation: Exclude<PatchOperation, 'unset'>
+      value: AnyNonNullable
+    }
+)
+
+/**
+ * Create a new document, then patch it
+ * @beta
+ */
+declare interface PatchTargetDocumentRequest<T extends Record<string, Any> = Record<string, Any>> {
+  /**
+   * @see #AgentActionSchema.forcePublishedWrite
+   */
+  targetDocument: GenerateTargetDocument<T>
+  documentId?: never
+}
+
 /** @public */
 declare interface ProgressEvent_2 {
   type: 'progress'
@@ -3433,6 +3682,131 @@ export declare class ProjectsClient {
   getById(projectId: string): Promise<SanityProject>
 }
 
+/**
+ * @beta
+ */
+declare interface PromptJsonResponse<T extends Record<string, Any> = Record<string, Any>> {
+  /**
+   *
+   * When true, the response body will be json according to the instruction.
+   * When false, the response is the raw text response to the instruction.
+   *
+   * Note: In addition to setting this to true,  `instruction` MUST include the word 'JSON', or 'json' for this to work.
+   */
+  format: 'json'
+}
+
+/** @beta */
+export declare type PromptRequest<T extends Record<string, Any> = Record<string, Any>> = (
+  | PromptTextResponse
+  | PromptJsonResponse<T>
+) &
+  PromptRequestBase
+
+/**  @beta */
+declare interface PromptRequestBase {
+  /**
+   * Instruct the LLM how it should generate content. Be as specific and detailed as needed.
+   *
+   * The LLM only has access to information in the instruction, plus the target schema.
+   *
+   * String template with support for $variable from `instructionParams`.
+   * */
+  instruction: string
+  /**
+   * param values for the string template, keys are the variable name, ie if the template has "$variable", one key must be "variable"
+   *
+   * ### Examples
+   *
+   * #### Constant
+   *
+   * ##### Shorthand
+   * ```ts
+   * client.agent.action.prompt({
+   *   instruction: 'Give the following topic:\n $topic \n ---\nReturns some facts about it',
+   *   instructionParams: {
+   *     topic: 'Grapefruit'
+   *   },
+   * })
+   * ```
+   * ##### Object-form
+   *
+   * ```ts
+   * client.agent.action.prompt({
+   *   instruction: 'Give the following topic:\n $topic \n ---\nReturns some facts about it.',
+   *   instructionParams: {
+   *     topic: {
+   *       type: 'constant',
+   *       value: 'Grapefruit'
+   *     },
+   *   },
+   * })
+   * ```
+   * #### Field
+   * ```ts
+   * client.agent.action.prompt({
+   *   instruction: 'Give the following field value:\n $pte \n ---\nGenerate keywords.',
+   *   instructionParams: {
+   *     pte: {
+   *       type: 'field',
+   *       path: ['pteField'],
+   *       documentId: 'someSanityDocId'
+   *     },
+   *   },
+   * })
+   * ```
+   * #### Document
+   * ```ts
+   * client.agent.action.prompt({
+   *   json: true,
+   *   instruction: 'Given the following document:$document\nCreate a JSON string[] array with keywords describing it.',
+   *   instructionParams: {
+   *     document: {
+   *       type: 'document',
+   *       documentId: 'someSanityDocId'
+   *     },
+   *   },
+   * })
+   * ```
+   *
+   * #### GROQ
+   * ```ts
+   * client.agent.action.prompt({
+   *   instruction: 'Return the best title amongst these: $titles.',
+   *   instructionParams: {
+   *     titles: {
+   *       type: 'groq',
+   *       query: '* [_type==$type].title',
+   *       params: {type: 'article'}
+   *     },
+   *   },
+   * })
+   * ```
+   * */
+  instructionParams?: AgentActionParams<{
+    docIdRequired: true
+  }>
+  /**
+   * Controls how much variance the instructions will run with.
+   *
+   * Value must be in the range [0, 1] (inclusive).
+   *
+   * Default: 0.3
+   */
+  temperature?: number
+}
+
+declare interface PromptTextResponse {
+  /**
+   *
+   * When true, the response body will be json according to the instruction.
+   * When false, the response is the raw text response to the instruction.
+   *
+   * Note: In addition to setting this to true,  `instruction` MUST include the word 'JSON', or 'json' for this to work.
+   */
+  format?: 'text'
+}
+
 /**
  * Publishes a draft document.
  * If a published version of the document already exists this is replaced by the current draft document.
@@ -3519,6 +3893,23 @@ export declare interface QueryParams {
   cacheMode?: never
 }
 
+/**
+ * Returned from the Content Lake API when a query is malformed, usually with a start
+ * and end column to indicate where the error occurred, but not always. Can we used to
+ * provide a more structured error message to the user.
+ *
+ * This will be located under the response `error` property.
+ *
+ * @public
+ */
+export declare interface QueryParseError {
+  type: 'queryParseError'
+  description: string
+  start?: number
+  end?: number
+  query?: string
+}
+
 /**
  * This type can be used with `client.fetch` to indicate that the query has no GROQ parameters.
  * @public
@@ -5125,6 +5516,8 @@ declare interface TransformRequestBase extends AgentActionRequestBase {
   schemaId: string
   /**
    * The source document the transformation will use as input.
+   *
+   * @see #AgentActionSchema.forcePublishedWrite
    */
   documentId: string
   /**
@@ -5132,12 +5525,14 @@ declare interface TransformRequestBase extends AgentActionRequestBase {
    * then it is transformed according to the instruction.
    *
    * When omitted, the source document (documentId) is also the target document.
+   *
+   *  @see #AgentActionSchema.forcePublishedWrite
    */
   targetDocument?: TransformTargetDocument
   /**
    * Instruct the LLM how to transform the input to th output.
    *
-   * String template using $variable from instructionParams.
+   * String template with support for $variable from `instructionParams`.
    *
    * Capped to 2000 characters, after variables has been injected.
    * */
@@ -5236,6 +5631,21 @@ declare interface TransformRequestBase extends AgentActionRequestBase {
    * It is therefor an error to provide conflicting include/exclude across targets (ie, include title in one, and exclude it in another)
    *
    * Default max depth for transform: 12
+   *
+   * ## Transforming images
+   *
+   * To transform an existing image, directly target an image asset path.
+   *
+   * For example, all the following will transform the image into the provided asset:
+   * * `target: {path: ['image', 'asset'] }`
+   * * `target: {path: 'image', include: ['asset'] }`
+   *
+   * Image transform can be combined with regular content targets:
+   * * `target: [{path: ['image', 'asset'] }, {include: ['title', 'description']}]`
+   *
+   * Image transform can have per-path instructions, just like any other target paths:
+   * * `target: [{path: ['image', 'asset'], instruction: 'Make the sky blue' }`
+   *
    * @see AgentActionRequestBase#conditionalPaths
    */
   target?: TransformTarget | TransformTarget[]
@@ -5246,7 +5656,7 @@ export declare interface TransformTarget extends AgentActionTarget {
   /**
    * Specifies a tailored instruction of this target.
    *
-   * string template using $variable from instructionParams.
+   * String template with support for $variable from `instructionParams`.
    * */
   instruction?: string
   /**
@@ -5259,7 +5669,11 @@ export declare interface TransformTarget extends AgentActionTarget {
   include?: (AgentActionPathSegment | TransformTargetInclude)[]
 }
 
-/**  @beta */
+/**
+ * @see #AgentActionSchema.forcePublishedWrite
+ *
+ * @beta
+ */
 export declare type TransformTargetDocument =
   | {
       operation: 'edit'
@@ -5283,7 +5697,7 @@ export declare interface TransformTargetInclude extends AgentActionTargetInclude
   /**
    * Specifies a tailored instruction of this target.
    *
-   * string template using $variable from instructionParams  */
+   * String template with support for $variable from `instructionParams`.  */
   instruction?: string
   /**
    * By default, all children up to `target.maxPathDepth` are included.
@@ -5325,6 +5739,7 @@ declare interface TranslateRequestBase extends AgentActionRequestBase {
   schemaId: string
   /**
    * The source document the transformation will use as input.
+   * @see #AgentActionSchema.forcePublishedWrite
    */
   documentId: string
   /**
@@ -5332,6 +5747,8 @@ declare interface TranslateRequestBase extends AgentActionRequestBase {
    * then it is translated according to the instruction.
    *
    * When omitted, the source document (documentId) is also the target document.
+   *
+   * @see #AgentActionSchema.forcePublishedWrite
    */
   targetDocument?: TransformTargetDocument
   /**
@@ -5384,7 +5801,7 @@ declare interface TranslateRequestBase extends AgentActionRequestBase {
 
 /**  @beta */
 export declare interface TranslateTarget extends AgentActionTarget {
-  /** string template using $variable from instructionParams  */
+  /** String template using $variable from styleGuideParams.  */
   styleGuide?: string
   /**
    * By default, all children up to `target.maxPathDepth` are included.
@@ -5398,7 +5815,7 @@ export declare interface TranslateTarget extends AgentActionTarget {
 
 /**  @beta */
 export declare interface TranslateTargetInclude extends AgentActionTargetInclude {
-  /** string template using $variable from instructionParams  */
+  /** String template using $variable from styleGuideParams.  */
   styleGuide?: string
   /**
    * By default, all children up to `target.maxPathDepth` are included.