@sanity/client 7.3.0 → 7.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/client",
-  "version": "7.3.0",
+  "version": "7.4.0",
   "description": "Client for retrieving, creating and patching data from Sanity.io",
   "keywords": [
     "sanity",

package/src/agent/actions/AgentActionsClient.ts

@@ -1,10 +1,12 @@
 import {lastValueFrom, type Observable} from 'rxjs'
 
 import type {ObservableSanityClient, SanityClient} from '../../SanityClient'
-import type {Any, HttpRequest, IdentifiedSanityDocumentStub, TranslateDocument} from '../../types'
+import type {Any, HttpRequest, IdentifiedSanityDocumentStub} from '../../types'
 import {_generate, type GenerateInstruction} from './generate'
+import {_patch, type PatchDocument} from './patch'
+import {_prompt, type PromptRequest} from './prompt'
 import {_transform, type TransformDocument} from './transform'
-import {_translate} from './translate'
+import {_translate, type TranslateDocument} from './translate'
 
 /** @public */
 export class ObservableAgentsActionClient {
@@ -108,4 +110,29 @@ export class AgentActionsClient {
   > {
     return lastValueFrom(_translate(this.#client, this.#httpRequest, request))
   }
+
+  /**
+   * 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> {
+    return lastValueFrom(_prompt(this.#client, this.#httpRequest, request))
+  }
+
+  /**
+   * 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
+  > {
+    return lastValueFrom(_patch(this.#client, this.#httpRequest, request))
+  }
 }

package/src/agent/actions/commonTypes.ts

@@ -35,6 +35,16 @@ export interface ConstantAgentActionParam {
   value: string
 }
 
+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
+      }
+
 /**
  *
  *
@@ -58,17 +68,15 @@ export interface ConstantAgentActionParam {
  *
  * @beta
  * */
-export interface FieldAgentActionParam {
+export 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>
 
 /**
  *
@@ -90,13 +98,11 @@ export interface FieldAgentActionParam {
  *
  * @beta
  * */
-export interface DocumentAgentActionParam {
+export type DocumentAgentActionParam<
+  TParamConfig extends {docIdRequired: boolean} = {docIdRequired: false},
+> = {
   type: 'document'
-  /**
-   * If omitted, implicitly uses the documentId of the instruction target
-   */
-  documentId?: string
-}
+} & DocIdParam<TParamConfig>
 
 /**
  * Includes a LLM-friendly version of GROQ query result in the instruction
@@ -209,21 +215,52 @@ export interface AgentActionTarget {
 }
 
 /** @beta */
-export type AgentActionParam =
+export type AgentActionParam<
+  TParamConfig extends {docIdRequired: boolean} = {docIdRequired: false},
+> =
   | string
   | ConstantAgentActionParam
-  | FieldAgentActionParam
-  | DocumentAgentActionParam
+  | FieldAgentActionParam<TParamConfig>
+  | DocumentAgentActionParam<TParamConfig>
   | GroqAgentActionParam
 
 /** @beta */
-export type AgentActionParams = Record<string, AgentActionParam>
+export type AgentActionParams<
+  TParamConfig extends {docIdRequired: boolean} = {docIdRequired: false},
+> = Record<string, AgentActionParam<TParamConfig>>
 
 /** @beta */
-export interface AgentActionRequestBase {
+export 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.
    *
@@ -254,7 +291,10 @@ export interface AgentActionRequestBase {
       hidden: boolean
     }[]
   }
+}
 
+/** @beta */
+export 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.

package/src/agent/actions/generate.ts

@@ -25,7 +25,7 @@ export 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
   /**
@@ -121,6 +121,21 @@ export 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[]
@@ -179,6 +194,7 @@ export interface GenerateTarget extends AgentActionTarget {
    * @see #AgentActionTargetInclude.operation
    * @see #include
    * @see #AgentActionTargetInclude.include
+   * @see #AgentActionSchema.forcePublishedWrite
    */
   operation?: GenerateOperation
 
@@ -196,22 +212,34 @@ export interface GenerateTarget extends AgentActionTarget {
 export 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
@@ -222,8 +250,11 @@ export type GenerateTargetDocument<T extends Record<string, Any> = Record<string
  * @beta
  */
 interface GenerateExistingDocumentRequest {
+  /**
+   * @see #AgentActionSchema.forcePublishedWrite
+   */
   documentId: string
-  createDocument?: never
+  targetDocument?: never
 }
 
 /**
@@ -231,6 +262,9 @@ interface GenerateExistingDocumentRequest {
  * @beta
  */
 interface GenerateTargetDocumentRequest<T extends Record<string, Any> = Record<string, Any>> {
+  /**
+   * @see #AgentActionSchema.forcePublishedWrite
+   */
   targetDocument: GenerateTargetDocument<T>
   documentId?: never
 }

package/src/agent/actions/patch.ts

@@ -0,0 +1,136 @@
+import {type Observable} from 'rxjs'
+
+import {_request} from '../../data/dataMethods'
+import type {ObservableSanityClient, SanityClient} from '../../SanityClient'
+import type {
+  AgentActionPath,
+  AgentActionPathSegment,
+  Any,
+  GenerateTargetDocument,
+  HttpRequest,
+  IdentifiedSanityDocumentStub,
+} from '../../types'
+import {hasDataset} from '../../validators'
+import type {AgentActionAsync, AgentActionSchema, AgentActionSync} from './commonTypes'
+
+/**  @beta */
+export type PatchOperation = 'set' | 'append' | 'mixed' | 'unset'
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyNonNullable = Exclude<any, null | undefined>
+
+/**  @beta */
+export 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[]
+}
+
+/**  @beta */
+export 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}
+)
+
+/**
+ * Patches an existing document
+ * @beta
+ */
+interface PatchExistingDocumentRequest {
+  /**
+   * @see #AgentActionSchema.forcePublishedWrite
+   */
+  documentId: string
+  targetDocument?: never
+}
+
+/**
+ * Create a new document, then patch it
+ * @beta
+ */
+interface PatchTargetDocumentRequest<T extends Record<string, Any> = Record<string, Any>> {
+  /**
+   * @see #AgentActionSchema.forcePublishedWrite
+   */
+  targetDocument: GenerateTargetDocument<T>
+  documentId?: never
+}
+
+/** @beta */
+export type PatchDocumentSync<T extends Record<string, Any> = Record<string, Any>> = (
+  | PatchExistingDocumentRequest
+  | PatchTargetDocumentRequest<T>
+) &
+  PatchRequestBase &
+  AgentActionSync
+
+/** @beta */
+export type PatchDocumentAsync<T extends Record<string, Any> = Record<string, Any>> = (
+  | PatchExistingDocumentRequest
+  | PatchTargetDocumentRequest<T>
+) &
+  PatchRequestBase &
+  AgentActionAsync
+
+/** @beta */
+export type PatchDocument<T extends Record<string, Any> = Record<string, Any>> =
+  | PatchDocumentSync<T>
+  | PatchDocumentAsync<T>
+
+export function _patch<DocumentShape extends Record<string, Any>>(
+  client: SanityClient | ObservableSanityClient,
+  httpRequest: HttpRequest,
+  request: PatchDocument<DocumentShape>,
+): Observable<
+  (typeof request)['async'] extends true
+    ? {_id: string}
+    : IdentifiedSanityDocumentStub & DocumentShape
+> {
+  const dataset = hasDataset(client.config())
+  return _request(client, httpRequest, {
+    method: 'POST',
+    uri: `/agent/action/patch/${dataset}`,
+    body: request,
+  })
+}

package/src/agent/actions/prompt.ts

@@ -0,0 +1,145 @@
+import {type Observable} from 'rxjs'
+
+import {_request} from '../../data/dataMethods'
+import type {ObservableSanityClient, SanityClient} from '../../SanityClient'
+import type {AgentActionParams, Any, HttpRequest} from '../../types'
+import {hasDataset} from '../../validators'
+
+/**  @beta */
+export 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
+}
+
+/**
+ * @beta
+ */
+// need the unused generic here to allow for optional callsite casting
+// eslint-disable-next-line unused-imports/no-unused-vars
+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'
+}
+
+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'
+}
+
+/** @beta */
+export type PromptRequest<T extends Record<string, Any> = Record<string, Any>> = (
+  | PromptTextResponse
+  | PromptJsonResponse<T>
+) &
+  PromptRequestBase
+
+export function _prompt<const DocumentShape extends Record<string, Any>>(
+  client: SanityClient | ObservableSanityClient,
+  httpRequest: HttpRequest,
+  request: PromptRequest<DocumentShape>,
+): Observable<(typeof request)['format'] extends 'json' ? DocumentShape : string> {
+  const dataset = hasDataset(client.config())
+  return _request(client, httpRequest, {
+    method: 'POST',
+    uri: `/agent/action/prompt/${dataset}`,
+    body: request,
+  })
+}

package/src/agent/actions/transform.ts

@@ -20,6 +20,8 @@ export interface TransformRequestBase extends AgentActionRequestBase {
 
   /**
    * The source document the transformation will use as input.
+   *
+   * @see #AgentActionSchema.forcePublishedWrite
    */
   documentId: string
 
@@ -28,13 +30,15 @@ export 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.
    * */
@@ -134,12 +138,31 @@ export 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[]
 }
 
-/**  @beta */
+/**
+ * @see #AgentActionSchema.forcePublishedWrite
+ *
+ * @beta
+ */
 export type TransformTargetDocument =
   | {operation: 'edit'; _id: string}
   | {operation: 'create'; _id?: string}
@@ -151,7 +174,7 @@ export 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
 
   /**
@@ -169,7 +192,7 @@ export 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
 

package/src/agent/actions/translate.ts

@@ -27,6 +27,7 @@ export interface TranslateRequestBase extends AgentActionRequestBase {
 
   /**
    * The source document the transformation will use as input.
+   * @see #AgentActionSchema.forcePublishedWrite
    */
   documentId: string
 
@@ -35,6 +36,8 @@ export 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
 
@@ -105,7 +108,7 @@ export interface TranslateLanguage {
 
 /**  @beta */
 export interface TranslateTargetInclude extends AgentActionTargetInclude {
-  /** string template using $variable from instructionParams  */
+  /** String template using $variable from styleGuideParams.  */
   styleGuide?: string
 
   /**
@@ -120,7 +123,7 @@ export interface TranslateTargetInclude extends AgentActionTargetInclude {
 
 /**  @beta */
 export interface TranslateTarget extends AgentActionTarget {
-  /** string template using $variable from instructionParams  */
+  /** String template using $variable from styleGuideParams.  */
   styleGuide?: string
 
   /**

package/src/csm/walkMap.ts

@@ -1,5 +1,5 @@
+import {isRecord} from '../util/isRecord'
 import {isArray} from './isArray'
-import {isRecord} from './isRecord'
 import type {ContentSourceMapParsedPath, WalkMapFn} from './types'
 
 /**