@sanity/client 7.1.0 → 7.2.1-agent-actions.0

package/src/agent/actions/AgentActionsClient.ts

@@ -3,6 +3,7 @@ import {lastValueFrom, type Observable} from 'rxjs'
 import type {ObservableSanityClient, SanityClient} from '../../SanityClient'
 import type {Any, HttpRequest, IdentifiedSanityDocumentStub, TranslateDocument} from '../../types'
 import {_generate, type GenerateInstruction} from './generate'
+import {_prompt, type PromptRequest} from './prompt'
 import {_transform, type TransformDocument} from './transform'
 import {_translate} from './translate'
 
@@ -108,4 +109,14 @@ 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<DocumentShape extends Record<string, Any>>(
+    request: PromptRequest<DocumentShape>,
+  ): Promise<(typeof request)['json'] extends true ? DocumentShape : string> {
+    return lastValueFrom(_prompt(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,15 +215,19 @@ 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 {

package/src/agent/actions/prompt.ts

@@ -0,0 +1,150 @@
+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 using $variable
+   * */
+  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.generate({
+   *   schemaId,
+   *   documentId,
+   *   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).
+   *
+   * Defaults:
+   * - generate: 0.3
+   * - translate: 0
+   * - transform: 0
+   */
+  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.
+   */
+  json: true
+}
+
+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.
+   */
+  json?: false
+}
+
+/** @beta */
+export type PromptRequest<T extends Record<string, Any> = Record<string, Any>> = (
+  | PromptTextResponse
+  | PromptJsonResponse<T>
+) &
+  PromptRequestBase
+
+export function _prompt<DocumentShape extends Record<string, Any>>(
+  client: SanityClient | ObservableSanityClient,
+  httpRequest: HttpRequest,
+  request: PromptRequest<DocumentShape>,
+): Observable<(typeof request)['json'] extends true ? DocumentShape : string> {
+  const dataset = hasDataset(client.config())
+  return _request(client, httpRequest, {
+    method: 'POST',
+    uri: `/agent/action/prompt/${dataset}`,
+    body: request,
+  })
+}

package/src/data/dataMethods.ts

@@ -1,3 +1,4 @@
+import {getVersionFromId, getVersionId, isDraftId} from '@sanity/client/csm'
 import {from, type MonoTypeOperatorFunction, Observable} from 'rxjs'
 import {combineLatestWith, filter, map} from 'rxjs/operators'
 
@@ -12,6 +13,8 @@ import type {
   Any,
   BaseActionOptions,
   BaseMutationOptions,
+  CreateVersionAction,
+  DiscardVersionAction,
   FirstDocumentIdMutationOptions,
   FirstDocumentMutationOptions,
   HttpRequest,
@@ -25,11 +28,13 @@ import type {
   MutationSelection,
   QueryOptions,
   RawQueryResponse,
+  ReplaceVersionAction,
   RequestObservableOptions,
   RequestOptions,
   SanityDocument,
   SingleActionResult,
   SingleMutationResult,
+  UnpublishVersionAction,
 } from '../types'
 import {getSelection} from '../util/getSelection'
 import * as validate from '../validators'
@@ -132,10 +137,36 @@ export function _getDocument<R extends Record<string, Any>>(
   client: Client,
   httpRequest: HttpRequest,
   id: string,
-  opts: {signal?: AbortSignal; tag?: string} = {},
+  opts: {signal?: AbortSignal; tag?: string; releaseId?: string} = {},
 ): Observable<SanityDocument<R> | undefined> {
+  const getDocId = () => {
+    if (!opts.releaseId) {
+      return id
+    }
+
+    const versionId = getVersionFromId(id)
+    if (!versionId) {
+      if (isDraftId(id)) {
+        throw new Error(
+          `The document ID (\`${id}\`) is a draft, but \`options.releaseId\` is set as \`${opts.releaseId}\``,
+        )
+      }
+
+      return getVersionId(id, opts.releaseId)
+    }
+
+    if (versionId !== opts.releaseId) {
+      throw new Error(
+        `The document ID (\`${id}\`) is already a version of \`${versionId}\` release, but this does not match the provided \`options.releaseId\` (\`${opts.releaseId}\`)`,
+      )
+    }
+
+    return id
+  }
+  const docId = getDocId()
+
   const options = {
-    uri: _getDataUrl(client, 'doc', id),
+    uri: _getDataUrl(client, 'doc', docId),
     json: true,
     tag: opts.tag,
     signal: opts.signal,
@@ -168,6 +199,27 @@ export function _getDocuments<R extends Record<string, Any>>(
   )
 }
 
+/** @internal */
+export function _getReleaseDocuments<R extends Record<string, Any>>(
+  client: ObservableSanityClient | SanityClient,
+  httpRequest: HttpRequest,
+  releaseId: string,
+  opts: BaseMutationOptions = {},
+): Observable<RawQueryResponse<SanityDocument<R>[]>> {
+  return _dataRequest(
+    client,
+    httpRequest,
+    'query',
+    {
+      query: '*[sanity::partOfRelease($releaseId)]',
+      params: {
+        releaseId,
+      },
+    },
+    opts,
+  )
+}
+
 /** @internal */
 export function _createIfNotExists<R extends Record<string, Any>>(
   client: Client,
@@ -204,6 +256,26 @@ export function _createOrReplace<R extends Record<string, Any>>(
   return _create<R>(client, httpRequest, doc, 'createOrReplace', options)
 }
 
+/** @internal */
+export function _createVersion<R extends Record<string, Any>>(
+  client: ObservableSanityClient | SanityClient,
+  httpRequest: HttpRequest,
+  doc: IdentifiedSanityDocumentStub<R>,
+  publishedId: string,
+  options?: BaseActionOptions,
+): Observable<SingleActionResult> {
+  validators.requireDocumentId('createVersion', doc)
+  validators.requireDocumentType('createVersion', doc)
+
+  const createVersionAction: CreateVersionAction = {
+    actionType: 'sanity.action.document.version.create',
+    publishedId,
+    document: doc,
+  }
+
+  return _action(client, httpRequest, createVersionAction, options)
+}
+
 /** @internal */
 export function _delete<R extends Record<string, Any>>(
   client: Client,
@@ -227,6 +299,58 @@ export function _delete<R extends Record<string, Any>>(
   )
 }
 
+/** @internal */
+export function _discardVersion(
+  client: ObservableSanityClient | SanityClient,
+  httpRequest: HttpRequest,
+  versionId: string,
+  purge: boolean = false,
+  options?: BaseActionOptions,
+): Observable<SingleActionResult> {
+  const discardVersionAction: DiscardVersionAction = {
+    actionType: 'sanity.action.document.version.discard',
+    versionId,
+    purge,
+  }
+
+  return _action(client, httpRequest, discardVersionAction, options)
+}
+
+/** @internal */
+export function _replaceVersion<R extends Record<string, Any>>(
+  client: ObservableSanityClient | SanityClient,
+  httpRequest: HttpRequest,
+  doc: IdentifiedSanityDocumentStub<R>,
+  options?: BaseActionOptions,
+): Observable<SingleActionResult> {
+  validators.requireDocumentId('replaceVersion', doc)
+  validators.requireDocumentType('replaceVersion', doc)
+
+  const replaceVersionAction: ReplaceVersionAction = {
+    actionType: 'sanity.action.document.version.replace',
+    document: doc,
+  }
+
+  return _action(client, httpRequest, replaceVersionAction, options)
+}
+
+/** @internal */
+export function _unpublishVersion(
+  client: ObservableSanityClient | SanityClient,
+  httpRequest: HttpRequest,
+  versionId: string,
+  publishedId: string,
+  options?: BaseActionOptions,
+): Observable<SingleActionResult> {
+  const unpublishVersionAction: UnpublishVersionAction = {
+    actionType: 'sanity.action.document.version.unpublish',
+    versionId,
+    publishedId,
+  }
+
+  return _action(client, httpRequest, unpublishVersionAction, options)
+}
+
 /** @internal */
 export function _mutate<R extends Record<string, Any>>(
   client: Client,