@sanity/client 7.1.0-views.0 → 7.1.0-views.1

package/README.md

@@ -27,6 +27,10 @@ export const client = createClient({
   projectId: 'your-project-id',
   dataset: 'your-dataset-name',
   useCdn: true, // set to `false` to bypass the edge cache
+  // Set default headers to be included with all requests
+  headers: {
+    'X-Custom-Header': 'custom-value'
+  },
   apiVersion: '2025-02-06', // use current date (YYYY-MM-DD) to target the latest API version. Note: this should always be hard coded. Setting API version based on a dynamic value (e.g. new Date()) may break your application at a random point in the future.
   // token: process.env.SANITY_SECRET_TOKEN // Needed for certain operations like updating content, accessing drafts or using draft perspectives
 })
@@ -91,6 +95,7 @@ export async function updateDocumentTitle(_id, title) {
   - [Delete documents](#delete-documents)
   - [Multiple mutations in a transaction](#multiple-mutations-in-a-transaction)
   - [Clientless patches \& transactions](#clientless-patches--transactions)
+  - [Release and version operations](#release-and-version-operations)
   - [Uploading assets](#uploading-assets)
     - [Examples: Uploading assets from Node.js](#examples-uploading-assets-from-nodejs)
     - [Examples: Uploading assets from the Browser](#examples-uploading-assets-from-the-browser)
@@ -106,11 +111,37 @@ export async function updateDocumentTitle(_id, title) {
     - [Action options](#action-options)
     - [Create Action](#create-action)
     - [Delete Action](#delete-action)
-    - [Discard Action](#discard-action)
     - [Edit Action](#edit-action)
     - [Publish Action](#publish-action)
-    - [ReplaceDraft Action](#replacedraft-action)
     - [Unpublish Action](#unpublish-action)
+    - [Agent Actions API](#agent-actions-api)
+      - [Overview](#overview)
+      - [Generating Content](#generating-content)
+        - [Generating images](#generating-images)
+        - [Example: Using GROQ in instructionParams](#example-using-groq-in-instructionparams)
+        - [Example: Using the async flag](#example-using-the-async-flag)
+      - [Transforming Documents](#transforming-documents)
+        - [Transforming images](#transforming-images)
+        - [Image descriptions](#image-descriptions)
+        - [Example: Field-based transformation](#example-field-based-transformation)
+      - [Translating Documents](#translating-documents)
+        - [Example: Storing language in a field](#example-storing-language-in-a-field)
+      - [Prompt the LLM](#prompt-the-llm)
+      - [Patch with a schema-aware API](#patch-with-a-schema-aware-api)
+    - [Version actions](#version-actions)
+      - [Create Version Action](#create-version)
+      - [Discard Version Action](#discard-version)
+      - [Replace Version Action](#replace-version)
+      - [Unpublish Version Action](#unpublish-action)
+    - [Release Actions](#release-actions)
+      - [Create Release Action](#create-release)
+      - [Edit Release Action](#edit-release)
+      - [Published Release Action](#publish-release)
+      - [Schedule Release Action](#schedule-release)
+      - [Unschedule Release Action](#unarchive-release)
+      - [Archive Release Action](#archive-release)
+      - [Unarchive Release Action](#unarchive-release)
+      - [Delete Release Action](#delete-release)
 - [License](#license)
 - [From `v5`](#from-v5)
   - [The default `useCdn` is changed to `true`](#the-default-usecdn-is-changed-to-true)
@@ -1284,6 +1315,113 @@ client.mutate(transaction)
 
 An important note on this approach is that you cannot call `commit()` on transactions or patches instantiated this way, instead you have to pass them to `client.mutate()`
 
+### Release and version operations
+
+Release and version actions can be taken directly using the client's [actions API](#version-actions). Additionally, helper methods are provided which abstract some esoteric nomenclature with the release and version processing.
+
+0. Setup the client
+
+```js
+import {createClient} from '@sanity/client'
+
+const client = createClient({
+  projectId: 'your-project-id',
+  dataset: 'bikeshop',
+})
+```
+
+1. Create a new release
+
+```js
+const {releaseId} = await client.release.create({
+  metadata: {
+    title: 'New bike drop'
+    releaseType: 'scheduled'
+  }
+})
+```
+
+2. Create a new document into the release
+
+```js
+client.createVersion({
+  document: {
+    _type: 'bike',
+    name: 'Upgraded black bike',
+  },
+  releaseId,
+  publishedId: 'bike-123',
+})
+```
+
+3. Mark a document to be unpublished when the release is run
+
+```js
+client.unpublishVersion({
+  publishedId: 'old-red-bike',
+  releaseId,
+})
+```
+
+4. List the release and all the documents within the release
+
+```js
+const newBikesRelease = await client.releases.get({releaseId})
+/**
+ * {
+ *   _type: 'system.release',
+ *   _id: '_.releases.releaseId',
+ *   name: 'releaseId',
+ *   state: 'active',
+ *   metadata: {
+ *     name: 'New bike drop',
+ *     releaseType: 'scheduled'
+ *   }
+ * }
+ */
+
+const releaseDocuments = await client.releases.getDocuments({
+  releaseId,
+})
+
+/**
+ * Returns a list of documents eg.
+ *
+ * [{
+ *   _type: 'bike',
+ *   _id: 'versions.releaseId.bike-123',
+ *   name: 'Upgraded black bike',
+ *   ...
+ * },
+ * {
+ *   _type: 'bike',
+ *   _id: 'versions.releaseId.old-red-bike',
+ *   _system: {
+ *     delete: true
+ * }
+ * }]
+ */
+```
+
+5. Schedule the release (to run in 1 hours time)
+
+```js
+client.release.schedule({
+  releaseId,
+  publishAt: new Date(Date.now() + 3600000).toISOString(),
+})
+```
+
+6. After the release has run, check and delete the release
+
+```js
+const runRelease = await client.releases.get({releaseId})
+
+if (runRelease.state === 'published' && !runRelease.error) {
+  client.releases.delete({releaseId})
+}
+```
+
 ### Actions
 
 The Actions API provides a new interface for creating, updating and publishing documents. It is a wrapper around the [Actions API](https://www.sanity.io/docs/http-actions).
@@ -1343,27 +1481,6 @@ client
   })
 ```
 
-#### Discard Action
-
-A draft document can be deleted by specifying a discard action type:
-
-```js
-client
-  .action(
-    {
-      actionType: 'sanity.action.document.discard',
-      draftId: 'draft.bike-123',
-    },
-    actionOptions,
-  )
-  .then(() => {
-    console.log('Bike draft deleted')
-  })
-  .catch((err) => {
-    console.error('Discard failed: ', err.message)
-  })
-```
-
 #### Edit Action
 
 A patch can be applied to an existing document draft or create a new one by specifying an edit action type:
@@ -1410,47 +1527,268 @@ client
   })
 ```
 
-#### ReplaceDraft Action
+#### Unpublish Action
 
-An existing document draft can be deleted and replaced by a new one by specifying a replaceDraft action type:
+A published document can be retracted by specifying an unpublish action type:
 
 ```js
 client
   .action(
     {
-      actionType: 'sanity.action.document.replaceDraft',
+      actionType: 'sanity.action.document.unpublish',
+      draftId: 'draft.bike-123',
       publishedId: 'bike-123',
-      attributes: {name: 'Sanity Tandem Extraordinaire', _type: 'bike', seats: 1},
     },
     actionOptions,
   )
   .then(() => {
-    console.log('Bike draft replaced')
+    console.log('Bike draft unpublished')
   })
   .catch((err) => {
-    console.error('Replace draft failed: ', err.message)
+    console.error('Unpublish draft failed: ', err.message)
   })
 ```
 
-#### Unpublish Action
+## Version actions
 
-A published document can be retracted by specifying an unpublish action type:
+### Create version
+
+Create a draft or release version of a published document.
+
+```js
+client.action(
+  {
+    actionType: 'sanity.action.document.version.create',
+    publishedId: 'bike-123',
+    document: {
+      _id: 'versions.new-bike-release.bike-123'
+      _type: 'bike'
+    }
+  }
+).then(() => {
+  console.log('Copy of published `bike-123` created in release `new-bike-release`')
+}).catch((err) => {
+  console.error('Create version failed: ', err.message)
+})
+```
+
+> [!NOTE]
+> Replacing `versions.<releaseId>` with `drafts` will create a new draft version from the published document.
+
+### Discard version
+
+Discard a draft or release version.
 
 ```js
 client
-  .action(
-    {
-      actionType: 'sanity.action.document.unpublish',
-      draftId: 'draft.bike-123',
-      publishedId: 'bike-123',
+  .action({
+    actionType: 'sanity.action.document.version.discard',
+    versionId: 'versions.new-bike-release.bike-123',
+  })
+  .then(() => {
+    console.log('Discarded the version of `bike-123` within the `new-bike-release` release')
+  })
+  .catch((err) => {
+    console.error('Discard version failed: ', err.message)
+  })
+```
+
+### Replace version
+
+Replaces the contents of an existing draft or release version document.
+
+```js
+client
+  .action({
+    actionType: 'sanity.action.document.version.replace',
+    document: {
+      _id: 'versions.new-bike-release.bike-123',
+      color: 'red',
+      _type: 'bike',
     },
-    actionOptions,
-  )
+  })
   .then(() => {
-    console.log('Bike draft unpublished')
+    console.log('Replaced the existing `bike-123` document within the `new-bike-release` release')
   })
   .catch((err) => {
-    console.error('Unpublish draft failed: ', err.message)
+    console.error('Replace version failed: ', err.message)
+  })
+```
+
+### Unpublish version
+
+Marks a document to be unpublished when the release it is part of is run.
+
+```js
+client
+  .action({
+    actionType: 'sanity.action.document.version.unpublish',
+    publishedId: 'bike-123',
+    versionId: 'versions.new-bike-release.bike-123',
+  })
+  .then(() => {
+    console.log('`bike-123` will be unpublished when `new-bike-release` release is run')
+  })
+  .catch((err) => {
+    console.error('Unpublish version failed: ', err.message)
+  })
+```
+
+## Release Actions
+
+### Create release
+
+Create a new release.
+
+```js
+client
+  .action({
+    actionType: 'sanity.action.release.create',
+    releaseId: 'new-bikes-release',
+    metadata: {
+      title: 'New bikes',
+      releaseType: 'undecided',
+    },
+  })
+  .then(() => {
+    console.log('`new-bikes-release` created')
+  })
+  .catch((err) => {
+    console.error('Create release failed: ', err.message)
+  })
+```
+
+### Edit release
+
+Edit the metadata on an existing release.
+
+```js
+client
+  .action({
+    actionType: 'sanity.action.release.edit',
+    releaseId: 'new-bikes-release',
+    patch: {
+      set: {
+        metadata: {
+          releaseType: 'asap',
+        },
+      },
+    },
+  })
+  .then(() => {
+    console.log('`new-bikes-release` changed to `asap` release type')
+  })
+  .catch((err) => {
+    console.error('Edit release failed: ', err.message)
+  })
+```
+
+### Publish release
+
+Publish all document versions within a release.
+
+```js
+client
+  .action({
+    actionType: 'sanity.action.release.publish',
+    releaseId: 'new-bikes-release',
+  })
+  .then(() => {
+    console.log('`new-bikes-release` published')
+  })
+  .catch((err) => {
+    console.error('Publish release failed: ', err.message)
+  })
+```
+
+### Schedule release
+
+Schedule a release to be run now or in the future
+
+```js
+client
+  .action({
+    actionType: 'sanity.action.release.schedule',
+    releaseId: 'new-bikes-release',
+    publishAt: '2025-01-01T00:00:00.000Z',
+  })
+  .then(() => {
+    console.log('`new-bikes-release` scheduled')
+  })
+  .catch((err) => {
+    console.error('Schedule release failed: ', err.message)
+  })
+```
+
+### Unschedule release
+
+Unschedule a currently scheduled release, to stop the release being run.
+
+```js
+client
+  .action({
+    actionType: 'sanity.action.release.unschedule',
+    releaseId: 'new-bikes-release',
+  })
+  .then(() => {
+    console.log('`new-bikes-release` unscheduled')
+  })
+  .catch((err) => {
+    console.error('Unschedule release failed: ', err.message)
+  })
+```
+
+### Archive release
+
+Mark an active (not published) release as archived.
+
+```js
+client
+  .action({
+    actionType: 'sanity.action.release.archive',
+    releaseId: 'new-bikes-release',
+  })
+  .then(() => {
+    console.log('`new-bikes-release` archived')
+  })
+  .catch((err) => {
+    console.error('Archive release failed: ', err.message)
+  })
+```
+
+### Unarchive release
+
+Once a release has been archived, the archive process may be undone by unarchiving the release.
+
+```js
+client
+  .action({
+    actionType: 'sanity.action.release.unarchive',
+    releaseId: 'new-bikes-release',
+  })
+  .then(() => {
+    console.log('`new-bikes-release` unarchived')
+  })
+  .catch((err) => {
+    console.error('Unarchive release failed: ', err.message)
+  })
+```
+
+### Delete release
+
+An archived release can be deleted, which will remove the system release document permanently from the dataset.
+
+```js
+client
+  .action({
+    actionType: 'sanity.action.release.delete',
+    releaseId: 'new-bikes-release',
+  })
+  .then(() => {
+    console.log('`new-bikes-release` deleted')
+  })
+  .catch((err) => {
+    console.error('Delete release failed: ', err.message)
   })
 ```
 
@@ -1632,6 +1970,296 @@ client.config({dataset: 'newDataset'})
 
 Set client configuration. Required options are `projectId` and `dataset`.
 
+### Agent Actions API
+
+The Agent Actions API provides programmatic access to AI-powered content generation, transformation, and translation for your Sanity documents. These APIs are available on the `client.agent.action` namespace.
+
+> **Note:** These APIs are currently in beta and may change in future releases.
+
+#### Overview
+
+Agent Actions allow you to:
+
+- **Generate** new content for a document or specific fields using LLM instructions.
+- **Transform** a document based on instructions, optionally copying from a source document.
+- **Translate** a document or fields from one language to another, with support for style guides and protected phrases.
+- **Prompt** the LLM using the same instruction template format as the other actions, but returns text or json instead of acting on a document.
+- **Patch** documents using a schema-aware API; validates that provided paths and values are schema compliant and handles `setIfMissing` semantics for deep value operations
+
+All methods are available in both Promise and Observable forms:
+
+- `client.agent.action.generate`, `client.agent.action.transform`, `client.agent.action.translate`, `client.agent.action.prompt`, `client.agent.action.patch` (Promise-based)
+- `client.observable.agent.action.generate`, etc. (Observable-based, for streaming or RxJS use)
+
+---
+
+#### Generating Content
+
+```ts
+const result = await client.agent.action.generate({
+  schemaId: 'your-schema-id',
+  documentId: 'your-document-id',
+  instruction: 'Write a summary for the following topic: $topic',
+  instructionParams: {
+    topic: 'Grapefruit',
+  },
+  target: {path: ['body']},
+})
+```
+
+- **schemaId**: The schema identifier for the document type.
+- **documentId**: The ID of the document to generate content for.
+- **instruction**: A string template describing what to generate. Use `$variable` for dynamic values.
+- **instructionParams**: Values for variables in the instruction. Supports constants, fields, documents, or GROQ queries.
+- **target**: (Optional) Specifies which fields or paths to generate content for.
+- **temperature**: (Optional) Controls variance, 0-1 – defaults to 0.3
+- **async**: (Optional) when true, the request will respond with the document id; the LLM request and mutations will continue on the server.
+- **noWrite**: (Optional) when true, the document will not be changed. The response will contain the document value with the changes.
+- **conditionalPaths**: (Optional) control how conditionally readOnly and hidden fields and types will be treated
+
+##### 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.
+
+##### Example: Using GROQ in instructionParams
+
+```ts
+await client.agent.action.generate({
+  schemaId,
+  documentId,
+  instruction: 'Generate a title based on these: $list',
+  instructionParams: {
+    list: {
+      type: 'groq',
+      query: '*[_type==$type].title',
+      params: {type: 'article'},
+    },
+  },
+  target: {path: ['body']},
+})
+```
+
+#### Example: Using the async flag
+
+The `async` parameter allows you to fire and forget and will not wait for a response from the LLMj, this works also in the Transform and Translate APIs.
+
+```ts
+const result = await client.agent.action.generate({
+  schemaId: 'article',
+  documentId: 'article-123',
+  instruction: 'Write a comprehensive article about $topic',
+  instructionParams: {
+    topic: 'Climate Change',
+  },
+  target: {path: ['body']},
+  async: true, // Enable async mode for long-running tasks or where you don't want to wait for the result
+})
+
+// result will return back the document id
+console.log('Generation task started:', result._id)
+```
+
+#### Transforming Documents
+
+```ts
+const result = await client.agent.action.transform({
+  schemaId: 'your-schema-id',
+  documentId: 'source-document-id',
+  instruction: 'Transform the content to a more formal tone.',
+  targetDocument: {operation: 'edit', _id: 'target-document-id'},
+  target: {path: ['body']},
+})
+```
+
+- **schemaId**: The schema identifier for the document type.
+- **documentId**: The source document ID.
+- **instruction**: A string template describing the transformation.
+- **targetDocument**: (Optional) Specify a different document to write the result to, or create a new one.
+- **target**: (Optional) Specifies which fields or paths to transform.
+- **temperature**: (Optional) Controls variance, 0-1 – defaults to 0
+- **async**: (Optional) when true, the request will respond with the document id; the LLM request and mutations will continue on the server.
+- **noWrite**: (Optional) when true, the document will not be changed. The response will contain the document value with the changes.
+- **conditionalPaths**: (Optional) control how conditionally readOnly and hidden fields and types will be treated
+
+##### 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' }`
+
+##### Image descriptions
+
+## Image description
+
+Images can be transformed to a textual description by targeting a `string`, `text` or Portable Text field (`array` with `block`)
+with `operation: {type: 'image-description'}`.
+
+Custom instructions for image description targets will be used to generate the description.
+
+###### Targeting image fields
+If a target is a descendant field of an image object, no `sourcePath` is required in the operation:
+
+For example:
+- `target: {path: ['image', 'description'], operation: {type: 'image-description'} }`
+- `target: {path: ['array', {_key: 'abc'}, 'alt'], operation: {type: 'image-description'} } //assuming the item in the array on the key-ed path is an image`
+- `target: {path: ['image'], include: ['portableTextField'], operation: {type: 'image-description'}, instruction: 'Use formatting and headings to describe the image in great detail' }`
+
+###### Targeting non-image fields
+If the target image description lives outside an image object, use the `sourcePath` option to specify the path to the image field.
+`sourcePath` must be an image or image asset field.
+
+For example:
+- `target: {path: ['description'], operation: {type: 'image-description', sourcePath: ['image', 'asset'] }`
+- `target: {path: ['wrapper', 'title'], operation: {type: 'image-description', sourcePath: ['array', {_key: 'abc'}, 'image'] }`
+- `target: {path: ['wrapper'], include: ['portableTextField'], operation: {type: 'image-description', sourcePath: ['image', 'asset'] }, instruction: 'Use formatting and headings to describe the image in great detail' }`
+
+##### Example: Field-based transformation
+
+```ts
+await client.agent.action.transform({
+  schemaId,
+  documentId,
+  instruction: 'Summarize the following field: $content',
+  instructionParams: {
+    content: {type: 'field', path: ['body']},
+  },
+  target: {path: ['body']},
+})
+```
+
+---
+
+#### Translating Documents
+
+```ts
+const result = await client.agent.action.translate({
+  schemaId: 'your-schema-id',
+  documentId: 'source-document-id',
+  targetDocument: {operation: 'create'},
+  fromLanguage: {id: 'en', title: 'English'},
+  toLanguage: {id: 'es', title: 'Spanish'},
+  styleGuide: 'Use a friendly tone.',
+  protectedPhrases: ['Sanity', 'Grapefruit'],
+  target: {path: ['body']},
+})
+```
+
+- **schemaId**: The schema identifier for the document type.
+- **documentId**: The source document ID.
+- **targetDocument**: (Optional) Specify a different document to write the result to, or create a new one.
+- **fromLanguage**: (Optional) The source language code and title.
+- **toLanguage**: The target language code and title.
+- **styleGuide**: (Optional) Instructions for translation style.
+- **protectedPhrases**: (Optional) Array of phrases to leave untranslated.
+- **target**: (Optional) Specifies which fields or paths to translate.
+- **temperature**: (Optional) Controls variance, 0-1 – defaults to 0
+- **async**: (Optional) when true, the request will respond with the document id; the LLM request and mutations will continue on the server.
+- **noWrite**: (Optional) when true, the document will not be changed. The response will contain the document value with the changes.
+- **conditionalPaths**: (Optional) control how conditionally readOnly and hidden fields and types will be treated
+
+##### Example: Storing language in a field
+
+```ts
+await client.agent.action.translate({
+  schemaId,
+  documentId,
+  toLanguage: {id: 'fr', title: 'French'},
+  languageFieldPath: ['language'],
+  target: {path: ['body']},
+})
+```
+
+#### Prompt the LLM
+
+```ts
+const result = await client.agent.action.prompt({
+  instruction: 'Say: Oh, hi $name!',
+  instructionParams: {
+    name: 'Mark',
+  },
+  temperature: 0.5,
+  format: 'text',
+})
+```
+
+- **instruction**: A string template describing what the LLM should do. Use `$variable` for dynamic values.
+- **instructionParams**: Values for variables in the instruction. Supports constants, fields, documents, or GROQ queries.
+- **format**: (Optional) 'text' or 'json'. Defaults to 'text'. Note that when specifying 'json', the instruction MUST include the word "json" (ignoring case) in some form.
+- **temperature**: (Optional) Controls variance, 0-1 – defaults to 0
+
+#### Patch with a schema-aware API
+
+The `client.patch` and `client.transaction` API are not schema aware. This allows patching documents any way you want, but the operations will not fail if they deviate from the document schema.
+
+To ensure schema-compliant operation, `client.agent.action.patch` is available. It will ensure that provided paths and values adhere to the document schema,
+ensure no duplicate keys are inserted, and merge object values so `set` operations dont accidentally remove existing values.
+
+```ts
+const result = await client.agent.action.patch({
+  schemaId,
+  documentId,
+  target: [
+    {path: 'title', operation: 'set', value: 'New title'},
+    {
+      path: ['wrapper', 'array'],
+      operation: 'append',
+      value: [{_type: 'item', title: 'Item title'}],
+    },
+  ],
+})
+```
+
+- **schemaId**: The schema identifier for the document type.
+- **documentId**: The source document ID OR use `targetDocument`
+- **targetDocument**: (Optional) Specify a different document to write the result to, or create a new one. Incompatible with `documentId`
+- **target**: Specify patch operations and values for paths in the document.
+- **async**: (Optional) when true, the request will respond with the document id; the LLM request and mutations will continue on the server.
+- **noWrite**: (Optional) when true, the document will not be changed. The response will contain the document value with the changes.
+- **conditionalPaths**: (Optional) control how conditionally readOnly and hidden fields and types will be treated
+
+#### Appending into array after a key
+
+When appending to arrays, providing a `_key` is optional.
+When a path targets a key in an array, the values provided will be appended after that key'ed item in the array.
+Note that when appending to arrays, `value` must be an array itself, even when only a single item should be appended.
+
+```ts
+const result = await client.agent.action.patch({
+  schemaId,
+  documentId,
+  target: {
+    path: ['array', {_key: 'existingKey'}],
+    operation: 'append',
+    value: [{_type: 'item', title: 'Item title', _key: 'isOptionalAndWillBeGeneratedIfMissing'}],
+  },
+})
+```
+
 ## License
 
 MIT © [Sanity.io](https://www.sanity.io/)