@sanity/client 6.28.3-instruct.5 → 6.28.3-instruct.6

package/dist/stega.browser.d.cts

@@ -695,6 +695,7 @@ declare interface CreateDocumentRequest<T extends Record<string, Any> = Record<s
     _id?: string
     _type: string
   } & SanityDocumentStub<T>
+  documentId?: never
 }
 
 /** @public */
@@ -921,6 +922,7 @@ export declare type EventSourceInstance = InstanceType<typeof globalThis.EventSo
  */
 declare interface ExistingDocumentRequest {
   documentId: string
+  createDocument?: never
 }
 
 /** @public */
@@ -1161,6 +1163,16 @@ export declare type InstructInstructionParam =
 /** @beta */
 export declare type InstructInstructionParams = Record<string, InstructInstructionParam>
 
+declare type InstructOperation = 'set' | 'append' | 'mixed'
+
+declare type InstructPath = InstructPathSegment[]
+
+declare type InstructPathSegment =
+  | string
+  | {
+      _key: string
+    }
+
 declare interface InstructRequestBase {
   /** schemaId as reported by sanity deploy / sanity schema store */
   schemaId: string
@@ -1169,45 +1181,17 @@ declare interface InstructRequestBase {
   /** 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.
+   * 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.
    *
-   * @see InstructRequestBase#conditionalPaths
-   * @see InstructRequestBase#outputTypes
-   */
-  relativeOutputPaths?:
-    | {
-        include: string[]
-      }
-    | {
-        exclude: string[]
-      }
-  /**
-   * Controls which types the instruction is allowed to output to.
+   * Omitting target implies that the document itself is the root.
    *
-   * @see InstructRequestBase#relativeOutputPaths
-   * @see InstructRequestBase#conditionalPaths
+   * 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 therefor an error to provide conflicting include/exclude across targets (ie, include title in one, and exclude it in another)
    */
-  outputTypes?:
-    | {
-        include: string[]
-      }
-    | {
-        exclude: string[]
-      }
+  target?: InstructTarget | InstructTarget[]
   /**
    * When a type or field in the schema has a function set for `hidden` or `readOnly`, it is conditional.
    *
@@ -1231,15 +1215,15 @@ declare interface InstructRequestBase {
     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
+      /** path here is not a relative path: it must be the full document path, regardless of `path` param used in targets */
+      path: InstructPath
       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.
+   * Otherwise, such fields will be ignored.
    */
   localeSettings?: {
     /**
@@ -1265,18 +1249,13 @@ declare interface InstructRequestBase {
     timeZone: string
   }
   /**
-   * The max depth for document paths instruction can write to.
-   *
-   * Depth is based on field path segments:
-   * - `title` has depth 1
-   * - `array[_key="no"].title` has depth 3
+   * Controls how much variance the instructions will run with.
    *
-   * Be careful not to set this too high in studios with recursive document schemas, as it could have
-   * negative impact on performance; both runtime and quality of responses.
+   * Value must be in the range [0, 1] (inclusive).
    *
-   * Default: 4
+   * Default: 0.3
    */
-  maxPathDepth?: number
+  temperature?: number
 }
 
 /** @beta */
@@ -1287,6 +1266,139 @@ export declare type InstructSyncInstruction<T extends Record<string, Any> = Reco
   InstructRequestBase &
   Sync
 
+/**
+ * @beta
+ */
+declare interface InstructTarget {
+  /**
+   * Root target path.
+   *
+   * Use this to have the instruction only affect a part of the document.
+   *
+   * To further control the behavior of individual paths under the root, use `include`, `exclude`, `types.include`
+   * and `types.exclude`.
+   *
+   * Example:
+   *
+   * `target: ['body', {_key: 'someKey'}, 'nestedObject']`
+   *
+   * Here, the instruction will only write to fields under the nestedObject.
+   *
+   * Default: [] = the document itself
+   *
+   * @see #InstructPathSegment
+   * @see #InstructPath
+   * */
+  path?: InstructPathSegment | InstructPath
+  /**
+   * Sets the default operation for all paths in the target.
+   * Instruct runs in `'mixed'` operation mode by default:
+   * Changes are set in all non-array fields, and append to all array fields.
+   *
+   * ### Operation types
+   * - `'set'` – an *overwriting* operation, and replaces the full field value.
+   * - `'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'` – (default) sets non-array fields, and appends to array fields
+   *
+   * The default operation can be overridden on a per-path basis using `include`.
+   *
+   * Nested fields inherit the operation specified by their parent and falls back to the
+   * top level target operation if not otherwise specified.
+   *
+   * Use `include` to change the `operation` of individual fields or items.
+   *
+   * #### Appending in the middle of arrays
+   * `target: {path: ['array'], operation: 'append'}` will append the output of the instruction to the end of the array.
+   *
+   * To insert in the middle of the array, use `target: {path: ['array', {_key: 'appendAfterKey'}], operation: 'append'}`.
+   * Here, the output of the instruction will be appended after the array item with key `'appendAfterKey'`.
+   *
+   * @see #InstructTargetInclude.operation
+   * @see #include
+   * @see #InstructTargetInclude.include
+   */
+  operation?: InstructOperation
+  /**
+   * maxPathDepth controls how deep into the schema from the target root the instruction will affect.
+   *
+   * Depth is based on path segments:
+   * - `title` has depth 1
+   * - `array[_key="no"].title` has depth 3
+   *
+   * Be careful not to set this too high in studios with recursive document schemas, as it could have
+   * negative impact on performance; both for runtime and quality of responses.
+   *
+   * Default: 4
+   */
+  maxPathDepth?: number
+  /**
+   * By default, all children up to `target.maxPathDepth` are included.
+   *
+   * When `include` is specified, only segments explicitly listed will be included.
+   *
+   * Fields or array items not on the include list, are implicitly excluded.
+   */
+  include?: (InstructPathSegment | InstructTargetInclude)[]
+  /**
+   * By default, all children up to `target.maxPathDepth` are included.
+   * Fields or array items not on the exclude list, are implicitly included.
+   */
+  exclude?: InstructPathSegment[]
+  /**
+   * 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?: InstructTypeConfig
+}
+
+declare interface InstructTargetInclude {
+  path: InstructPathSegment | InstructPath
+  /**
+   * Sets the operation for this path, and all its children.
+   * This overrides any operation set parents or the root target.
+   * @see #InstructTarget.operation
+   * @see #include
+   */
+  operation?: InstructOperation
+  /**
+   * By default, all children up to `target.maxPathDepth` are included.
+   *
+   * When `include` is specified, only segments explicitly listed will be included.
+   *
+   * Fields or array items not on the include list, are implicitly excluded.
+   */
+  include?: (InstructPathSegment | InstructTargetInclude)[]
+  /**
+   * By default, all children up to `target.maxPathDepth` are included.
+   * Fields or array items not on the exclude list, are implicitly included.
+   */
+  exclude?: InstructPathSegment[]
+  /**
+   * 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?: InstructTypeConfig
+}
+
+declare type InstructTypeConfig =
+  | {
+      include: string[]
+      exclude?: never
+    }
+  | {
+      exclude: string[]
+      include?: never
+    }
+
 /**
  * Set up a listener that will be notified when mutations occur on documents matching the provided query/filter.
  *

package/dist/stega.browser.d.ts

@@ -695,6 +695,7 @@ declare interface CreateDocumentRequest<T extends Record<string, Any> = Record<s
     _id?: string
     _type: string
   } & SanityDocumentStub<T>
+  documentId?: never
 }
 
 /** @public */
@@ -921,6 +922,7 @@ export declare type EventSourceInstance = InstanceType<typeof globalThis.EventSo
  */
 declare interface ExistingDocumentRequest {
   documentId: string
+  createDocument?: never
 }
 
 /** @public */
@@ -1161,6 +1163,16 @@ export declare type InstructInstructionParam =
 /** @beta */
 export declare type InstructInstructionParams = Record<string, InstructInstructionParam>
 
+declare type InstructOperation = 'set' | 'append' | 'mixed'
+
+declare type InstructPath = InstructPathSegment[]
+
+declare type InstructPathSegment =
+  | string
+  | {
+      _key: string
+    }
+
 declare interface InstructRequestBase {
   /** schemaId as reported by sanity deploy / sanity schema store */
   schemaId: string
@@ -1169,45 +1181,17 @@ declare interface InstructRequestBase {
   /** 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.
+   * 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.
    *
-   * @see InstructRequestBase#conditionalPaths
-   * @see InstructRequestBase#outputTypes
-   */
-  relativeOutputPaths?:
-    | {
-        include: string[]
-      }
-    | {
-        exclude: string[]
-      }
-  /**
-   * Controls which types the instruction is allowed to output to.
+   * Omitting target implies that the document itself is the root.
    *
-   * @see InstructRequestBase#relativeOutputPaths
-   * @see InstructRequestBase#conditionalPaths
+   * 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 therefor an error to provide conflicting include/exclude across targets (ie, include title in one, and exclude it in another)
    */
-  outputTypes?:
-    | {
-        include: string[]
-      }
-    | {
-        exclude: string[]
-      }
+  target?: InstructTarget | InstructTarget[]
   /**
    * When a type or field in the schema has a function set for `hidden` or `readOnly`, it is conditional.
    *
@@ -1231,15 +1215,15 @@ declare interface InstructRequestBase {
     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
+      /** path here is not a relative path: it must be the full document path, regardless of `path` param used in targets */
+      path: InstructPath
       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.
+   * Otherwise, such fields will be ignored.
    */
   localeSettings?: {
     /**
@@ -1265,18 +1249,13 @@ declare interface InstructRequestBase {
     timeZone: string
   }
   /**
-   * The max depth for document paths instruction can write to.
-   *
-   * Depth is based on field path segments:
-   * - `title` has depth 1
-   * - `array[_key="no"].title` has depth 3
+   * Controls how much variance the instructions will run with.
    *
-   * Be careful not to set this too high in studios with recursive document schemas, as it could have
-   * negative impact on performance; both runtime and quality of responses.
+   * Value must be in the range [0, 1] (inclusive).
    *
-   * Default: 4
+   * Default: 0.3
    */
-  maxPathDepth?: number
+  temperature?: number
 }
 
 /** @beta */
@@ -1287,6 +1266,139 @@ export declare type InstructSyncInstruction<T extends Record<string, Any> = Reco
   InstructRequestBase &
   Sync
 
+/**
+ * @beta
+ */
+declare interface InstructTarget {
+  /**
+   * Root target path.
+   *
+   * Use this to have the instruction only affect a part of the document.
+   *
+   * To further control the behavior of individual paths under the root, use `include`, `exclude`, `types.include`
+   * and `types.exclude`.
+   *
+   * Example:
+   *
+   * `target: ['body', {_key: 'someKey'}, 'nestedObject']`
+   *
+   * Here, the instruction will only write to fields under the nestedObject.
+   *
+   * Default: [] = the document itself
+   *
+   * @see #InstructPathSegment
+   * @see #InstructPath
+   * */
+  path?: InstructPathSegment | InstructPath
+  /**
+   * Sets the default operation for all paths in the target.
+   * Instruct runs in `'mixed'` operation mode by default:
+   * Changes are set in all non-array fields, and append to all array fields.
+   *
+   * ### Operation types
+   * - `'set'` – an *overwriting* operation, and replaces the full field value.
+   * - `'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'` – (default) sets non-array fields, and appends to array fields
+   *
+   * The default operation can be overridden on a per-path basis using `include`.
+   *
+   * Nested fields inherit the operation specified by their parent and falls back to the
+   * top level target operation if not otherwise specified.
+   *
+   * Use `include` to change the `operation` of individual fields or items.
+   *
+   * #### Appending in the middle of arrays
+   * `target: {path: ['array'], operation: 'append'}` will append the output of the instruction to the end of the array.
+   *
+   * To insert in the middle of the array, use `target: {path: ['array', {_key: 'appendAfterKey'}], operation: 'append'}`.
+   * Here, the output of the instruction will be appended after the array item with key `'appendAfterKey'`.
+   *
+   * @see #InstructTargetInclude.operation
+   * @see #include
+   * @see #InstructTargetInclude.include
+   */
+  operation?: InstructOperation
+  /**
+   * maxPathDepth controls how deep into the schema from the target root the instruction will affect.
+   *
+   * Depth is based on path segments:
+   * - `title` has depth 1
+   * - `array[_key="no"].title` has depth 3
+   *
+   * Be careful not to set this too high in studios with recursive document schemas, as it could have
+   * negative impact on performance; both for runtime and quality of responses.
+   *
+   * Default: 4
+   */
+  maxPathDepth?: number
+  /**
+   * By default, all children up to `target.maxPathDepth` are included.
+   *
+   * When `include` is specified, only segments explicitly listed will be included.
+   *
+   * Fields or array items not on the include list, are implicitly excluded.
+   */
+  include?: (InstructPathSegment | InstructTargetInclude)[]
+  /**
+   * By default, all children up to `target.maxPathDepth` are included.
+   * Fields or array items not on the exclude list, are implicitly included.
+   */
+  exclude?: InstructPathSegment[]
+  /**
+   * 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?: InstructTypeConfig
+}
+
+declare interface InstructTargetInclude {
+  path: InstructPathSegment | InstructPath
+  /**
+   * Sets the operation for this path, and all its children.
+   * This overrides any operation set parents or the root target.
+   * @see #InstructTarget.operation
+   * @see #include
+   */
+  operation?: InstructOperation
+  /**
+   * By default, all children up to `target.maxPathDepth` are included.
+   *
+   * When `include` is specified, only segments explicitly listed will be included.
+   *
+   * Fields or array items not on the include list, are implicitly excluded.
+   */
+  include?: (InstructPathSegment | InstructTargetInclude)[]
+  /**
+   * By default, all children up to `target.maxPathDepth` are included.
+   * Fields or array items not on the exclude list, are implicitly included.
+   */
+  exclude?: InstructPathSegment[]
+  /**
+   * 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?: InstructTypeConfig
+}
+
+declare type InstructTypeConfig =
+  | {
+      include: string[]
+      exclude?: never
+    }
+  | {
+      exclude: string[]
+      include?: never
+    }
+
 /**
  * Set up a listener that will be notified when mutations occur on documents matching the provided query/filter.
  *