@sanity/client 6.27.3-canary.2 → 6.28.0-instruct.0

package/src/assist/AssistClient.ts

@@ -0,0 +1,87 @@
+import {lastValueFrom, type Observable} from 'rxjs'
+
+import {_request} from '../data/dataMethods'
+import type {ObservableSanityClient, SanityClient} from '../SanityClient'
+import type {
+  Any,
+  AssistAsyncInstruction,
+  AssistInstruction,
+  AssistSyncInstruction,
+  HttpRequest,
+  IdentifiedSanityDocumentStub,
+} from '../types'
+import {hasDataset} from '../validators'
+
+function _instruct<
+  DocumentShape extends Record<string, Any>,
+  Req extends AssistInstruction<DocumentShape>,
+>(
+  client: SanityClient | ObservableSanityClient,
+  httpRequest: HttpRequest,
+  request: Req,
+): Observable<
+  Req['async'] extends true ? {_id: string} : IdentifiedSanityDocumentStub & DocumentShape
+> {
+  const dataset = hasDataset(client.config())
+  return _request(client, httpRequest, {
+    method: 'POST',
+    uri: `/assist/tasks/instruct/${dataset}`,
+    body: request,
+  })
+}
+
+/** @public */
+export class ObservableAssistClient {
+  #client: ObservableSanityClient
+  #httpRequest: HttpRequest
+  constructor(client: ObservableSanityClient, httpRequest: HttpRequest) {
+    this.#client = client
+    this.#httpRequest = httpRequest
+  }
+
+  instruct(request: AssistAsyncInstruction): Observable<{_id: string}>
+
+  instruct<DocumentShape extends Record<string, Any>>(
+    request: AssistSyncInstruction<DocumentShape>,
+  ): Observable<IdentifiedSanityDocumentStub & DocumentShape>
+
+  /**
+   * Run an ad-hoc instruction for a target document.
+   * @param request instruction request
+   */
+  instruct<DocumentShape extends Record<string, Any>, Req extends AssistInstruction<DocumentShape>>(
+    request: Req,
+  ): Observable<
+    Req['async'] extends true ? {_id: string} : IdentifiedSanityDocumentStub & DocumentShape
+  > {
+    return _instruct(this.#client, this.#httpRequest, request)
+  }
+}
+
+/** @public */
+export class AssistClient {
+  #client: SanityClient
+  #httpRequest: HttpRequest
+  constructor(client: SanityClient, httpRequest: HttpRequest) {
+    this.#client = client
+    this.#httpRequest = httpRequest
+  }
+
+  instruct(request: AssistAsyncInstruction): Promise<{_id: string}>
+
+  instruct<DocumentShape extends Record<string, Any>>(
+    request: AssistSyncInstruction<DocumentShape>,
+  ): Promise<IdentifiedSanityDocumentStub & DocumentShape>
+
+  /**
+   * Run an ad-hoc instruction for a target document.
+   * @param request instruction request
+   */
+  instruct<DocumentShape extends Record<string, Any>, Req extends AssistInstruction<DocumentShape>>(
+    request: Req,
+  ): Promise<
+    Req['async'] extends true ? {_id: string} : IdentifiedSanityDocumentStub & DocumentShape
+  > {
+    return lastValueFrom(_instruct(this.#client, this.#httpRequest, request))
+  }
+}

package/src/assist/types.ts

@@ -0,0 +1,178 @@
+//Request shape
+
+import type {Any, SanityDocumentStub} from '@sanity/client'
+
+/** @beta */
+export interface ConstantInstructionParam {
+  type: 'constant'
+  value: string
+}
+
+/** @beta */
+export interface FieldInstructionParam {
+  type: 'field'
+  path: string
+}
+
+/** @beta */
+export interface GroqInstructionParam {
+  type: 'groq'
+  query: string
+  params?: Record<string, string>
+}
+
+/** @beta */
+export type InstructionParam =
+  | string
+  | ConstantInstructionParam
+  | FieldInstructionParam
+  | GroqInstructionParam
+
+/** @beta */
+export type InstructionParams = Record<string, InstructionParam>
+
+interface AssistRequestBase {
+  /** schemaId as reported by sanity deploy / sanity schema store */
+  schemaId: string
+  /** string template using $variable – more on this below under "Dynamic instruction" */
+  instruction: string
+  /** param values for the string template, keys are the variable name, ie if the template has "$variable", one key must be "variable" */
+  instructionParams?: InstructionParams
+  /**
+   *  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.
+   *
+   * @see AssistRequestBase#conditionalPaths
+   * @see AssistRequestBase#outputTypes
+   */
+  relativeOutputPaths?: {include: string[]} | {exclude: string[]}
+
+  /**
+   * Controls which types the instruction is allowed to output to.
+   *
+   * @see AssistRequestBase#relativeOutputPaths
+   * @see AssistRequestBase#conditionalPaths
+   */
+  outputTypes?: {include: string[]} | {exclude: string[]}
+
+  /**
+   * When a type or field in the schema has a function set for `hidden` or `readOnly`, it is conditional.
+   *
+   * By default, AI Assist 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 AI Assist,
+   * and cannot be changed via conditionalPaths.
+   *
+   * conditionalPaths state only apply to fields and types that have conditional `hidden` or `readOnly` in their schema definition.
+   *
+   * @see AssistRequestBase#relativeOutputPaths
+   * @see AssistRequestBase#outputTypes
+   */
+  conditionalPaths?: {
+    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
+      readOnly: boolean
+      hidden: boolean
+    }[]
+  }
+}
+
+interface Sync {
+  /**
+   * By default, skipWrite: false.
+   * Write enabled operations will mutate the target document, and emit AI presence in the studio.
+   *
+   * When skipWrite: true, the api will not mutate any documents nor emit presence.
+   * Ie, when true, no changes will be made to content-lake
+   *
+   * skipWrite: true is incompatible with async: true,
+   * as skipWrite implies that you will use the return value of the operation
+   */
+  skipWrite?: 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 skipWrite: true, as async: true does not return the resulting document
+   */
+  async?: false
+}
+
+interface Async {
+  /**
+   * 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 skipWrite, as async: true does not return the resulting document
+   */
+  async: true
+}
+
+/**
+ * Instruction for an existing document.
+ * @beta
+ */
+interface ExistingDocumentRequest {
+  documentId: string
+}
+
+/**
+ * Instruction to create a new document
+ * @beta
+ */
+interface CreateDocumentRequest<T extends Record<string, Any> = Record<string, Any>> {
+  createDocument: {
+    /** if no _id is provided, one will be generated. _id is always returned when the requests succeed */
+    _id?: string
+    _type: string
+  } & SanityDocumentStub<T>
+}
+
+/** @beta */
+export type AssistSyncInstruction<T extends Record<string, Any> = Record<string, Any>> = (
+  | ExistingDocumentRequest
+  | CreateDocumentRequest<T>
+) &
+  AssistRequestBase &
+  Sync
+
+/** @beta */
+export type AssistAsyncInstruction<T extends Record<string, Any> = Record<string, Any>> = (
+  | ExistingDocumentRequest
+  | CreateDocumentRequest<T>
+) &
+  AssistRequestBase &
+  Async
+
+/** @beta */
+export type AssistInstruction<T extends Record<string, Any> = Record<string, Any>> =
+  | AssistSyncInstruction<T>
+  | AssistAsyncInstruction<T>

package/src/data/dataMethods.ts

@@ -33,7 +33,7 @@ import type {
 import {getSelection} from '../util/getSelection'
 import * as validate from '../validators'
 import * as validators from '../validators'
-import {printCdnPreviewDraftsWarning} from '../warnings'
+import {printCdnPreviewDraftsWarning, printPreviewDraftsDeprecationWarning} from '../warnings'
 import {encodeQueryString} from './encodeQueryString'
 import {ObservablePatch, Patch} from './patch'
 import {ObservableTransaction, Transaction} from './transaction'
@@ -407,6 +407,9 @@ export function _requestObservable<R>(
     }
     const perspectiveOption = options.perspective || config.perspective
     if (typeof perspectiveOption !== 'undefined') {
+      if (perspectiveOption === 'previewDrafts') {
+        printPreviewDraftsDeprecationWarning()
+      }
       validateApiPerspective(perspectiveOption)
       options.query = {
         perspective: Array.isArray(perspectiveOption)
@@ -414,8 +417,14 @@ export function _requestObservable<R>(
           : perspectiveOption,
         ...options.query,
       }
-      // If the perspective is set to `previewDrafts` we can't use the CDN, the API will throw
-      if (perspectiveOption === 'previewDrafts' && useCdn) {
+      // If the perspective is set to `drafts` or multiple perspectives we can't use the CDN, the API will throw
+      if (
+        ((Array.isArray(perspectiveOption) && perspectiveOption.length > 0) ||
+          // previewDrafts was renamed to drafts, but keep for backwards compat
+          perspectiveOption === 'previewDrafts' ||
+          perspectiveOption === 'drafts') &&
+        useCdn
+      ) {
         useCdn = false
         printCdnPreviewDraftsWarning()
       }

package/src/types.ts

@@ -37,12 +37,17 @@ export interface RequestOptions {
  */
 export type ReleaseId = `r${string}`
 
+/**
+ * @deprecated use 'drafts' instead
+ */
+type DeprecatedPreviewDrafts = 'previewDrafts'
+
 /** @public */
 export type StackablePerspective = ('published' | 'drafts' | string) & {}
 
 /** @public */
 export type ClientPerspective =
-  | 'previewDrafts'
+  | DeprecatedPreviewDrafts
   | 'published'
   | 'drafts'
   | 'raw'
@@ -1315,6 +1320,16 @@ export type ClientReturn<
   Fallback = Any,
 > = GroqString extends keyof SanityQueries ? SanityQueries[GroqString] : Fallback
 
+export type {
+  AssistAsyncInstruction,
+  AssistInstruction,
+  AssistSyncInstruction,
+  ConstantInstructionParam,
+  FieldInstructionParam,
+  GroqInstructionParam,
+  InstructionParam,
+  InstructionParams,
+} from './assist/types'
 export type {
   ContentSourceMapParsedPath,
   ContentSourceMapParsedPathKeyedSegment,

package/src/warnings.ts

@@ -18,10 +18,14 @@ export const printCdnWarning = createWarningPrinter([
 ])
 
 export const printCdnPreviewDraftsWarning = createWarningPrinter([
-  `The Sanity client is configured with the \`perspective\` set to \`previewDrafts\`, which doesn't support the API-CDN.`,
+  `The Sanity client is configured with the \`perspective\` set to \`drafts\` or \`previewDrafts\`, which doesn't support the API-CDN.`,
   `The Live API will be used instead. Set \`useCdn: false\` in your configuration to hide this warning.`,
 ])
 
+export const printPreviewDraftsDeprecationWarning = createWarningPrinter([
+  `The \`previewDrafts\` perspective has been renamed to  \`drafts\` and will be removed in a future API version`,
+])
+
 export const printBrowserTokenWarning = createWarningPrinter([
   'You have configured Sanity client to use a token in the browser. This may cause unintentional security issues.',
   `See ${generateHelpUrl(