@sanity/client 7.0.1-canary.2 → 7.2.0

package/README.md

@@ -91,6 +91,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 +107,32 @@ 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)
+        - [Example: Using GROQ in instructionParams](#example-using-groq-in-instructionparams)
+        - [Example: Using the async flag](#example-using-the-async-flag)
+      - [Transforming Documents](#transforming-documents)
+        - [Example: Field-based transformation](#example-field-based-transformation)
+      - [Translating Documents](#translating-documents)
+        - [Example: Storing language in a field](#example-storing-language-in-a-field)
+    - [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 +1306,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 +1472,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 +1518,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 +1961,153 @@ 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.
+
+All methods are available in both Promise and Observable forms:
+
+- `client.agent.action.generate`, `client.agent.action.transform`, `client.agent.action.translate` (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.
+
+##### 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.
+
+##### 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',
+  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.
+- **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.
+
+##### Example: Storing language in a field
+
+```ts
+await client.agent.action.translate({
+  schemaId,
+  documentId,
+  toLanguage: {id: 'fr', title: 'French'},
+  languageFieldPath: ['language'],
+  target: {path: ['body']},
+})
+```
+
 ## License
 
 MIT © [Sanity.io](https://www.sanity.io/)

package/dist/_chunks-cjs/config.cjs

@@ -24,6 +24,18 @@ const VALID_ASSET_TYPES = ["image", "file"], VALID_INSERT_LOCATIONS = ["before",
   if (!doc._id)
     throw new Error(`${op}() requires that the document contains an ID ("_id" property)`);
   validateDocumentId(op, doc._id);
+}, validateDocumentType = (op, type) => {
+  if (typeof type != "string")
+    throw new Error(`\`${op}()\`: \`${type}\` is not a valid document type`);
+}, requireDocumentType = (op, doc) => {
+  if (!doc._type)
+    throw new Error(`\`${op}()\` requires that the document contains a type (\`_type\` property)`);
+  validateDocumentType(op, doc._type);
+}, validateVersionIdMatch = (builtVersionId, document) => {
+  if (document._id && document._id !== builtVersionId)
+    throw new Error(
+      `The provided document ID (\`${document._id}\`) does not match the generated version ID (\`${builtVersionId}\`)`
+    );
 }, validateInsert = (at, selector, items) => {
   const signature = "insert(at, selector, items)";
   if (VALID_INSERT_LOCATIONS.indexOf(at) === -1) {
@@ -166,6 +178,7 @@ exports.printNoDefaultExport = printNoDefaultExport;
 exports.printPreviewDraftsDeprecationWarning = printPreviewDraftsDeprecationWarning;
 exports.requestTag = requestTag;
 exports.requireDocumentId = requireDocumentId;
+exports.requireDocumentType = requireDocumentType;
 exports.resourceConfig = resourceConfig;
 exports.resourceGuard = resourceGuard;
 exports.validateApiPerspective = validateApiPerspective;
@@ -173,4 +186,5 @@ exports.validateAssetType = validateAssetType;
 exports.validateDocumentId = validateDocumentId;
 exports.validateInsert = validateInsert;
 exports.validateObject = validateObject;
+exports.validateVersionIdMatch = validateVersionIdMatch;
 //# sourceMappingURL=config.cjs.map