@sanity/client 6.18.3 → 6.19.0

package/package.json

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

package/src/SanityClient.ts

@@ -10,9 +10,11 @@ import {ObservableTransaction, Transaction} from './data/transaction'
 import {DatasetsClient, ObservableDatasetsClient} from './datasets/DatasetsClient'
 import {ObservableProjectsClient, ProjectsClient} from './projects/ProjectsClient'
 import type {
+  Action,
   AllDocumentIdsMutationOptions,
   AllDocumentsMutationOptions,
   Any,
+  BaseActionOptions,
   BaseMutationOptions,
   ClientConfig,
   FilteredResponseQueryOptions,
@@ -21,6 +23,7 @@ import type {
   HttpRequest,
   IdentifiedSanityDocumentStub,
   InitializedClientConfig,
+  MultipleActionResult,
   MultipleMutationResult,
   Mutation,
   MutationSelection,
@@ -34,6 +37,7 @@ import type {
   RawRequestOptions,
   SanityDocument,
   SanityDocumentStub,
+  SingleActionResult,
   SingleMutationResult,
   UnfilteredResponseQueryOptions,
   UnfilteredResponseWithoutQuery,
@@ -665,6 +669,19 @@ export class ObservableSanityClient {
     return new ObservableTransaction(operations, this)
   }
 
+  /**
+   * Perform action operations against the configured dataset
+   *
+   * @param operations - Action operation(s) to execute
+   * @param options - Action options
+   */
+  action(
+    operations: Action | Action[],
+    options?: BaseActionOptions,
+  ): Observable<SingleActionResult | MultipleActionResult> {
+    return dataMethods._action(this, this.#httpRequest, operations, options)
+  }
+
   /**
    * Perform an HTTP request against the Sanity API
    *
@@ -1322,6 +1339,20 @@ export class SanityClient {
     return new Transaction(operations, this)
   }
 
+  /**
+   * Perform action operations against the configured dataset
+   * Returns a promise that resolves to the transaction result
+   *
+   * @param operations - Action operation(s) to execute
+   * @param options - Action options
+   */
+  action(
+    operations: Action | Action[],
+    options?: BaseActionOptions,
+  ): Promise<SingleActionResult | MultipleActionResult> {
+    return lastValueFrom(dataMethods._action(this, this.#httpRequest, operations, options))
+  }
+
   /**
    * Perform a request against the Sanity API
    * NOTE: Only use this for Sanity API endpoints, not for your own APIs!

package/src/data/dataMethods.ts

@@ -6,9 +6,11 @@ import {requestOptions} from '../http/requestOptions'
 import type {ObservableSanityClient, SanityClient} from '../SanityClient'
 import {stegaClean} from '../stega/stegaClean'
 import type {
+  Action,
   AllDocumentIdsMutationOptions,
   AllDocumentsMutationOptions,
   Any,
+  BaseActionOptions,
   BaseMutationOptions,
   FirstDocumentIdMutationOptions,
   FirstDocumentMutationOptions,
@@ -16,6 +18,7 @@ import type {
   HttpRequestEvent,
   IdentifiedSanityDocumentStub,
   InitializedStegaConfig,
+  MultipleActionResult,
   MultipleMutationResult,
   Mutation,
   MutationSelection,
@@ -24,6 +27,7 @@ import type {
   RequestObservableOptions,
   RequestOptions,
   SanityDocument,
+  SingleActionResult,
   SingleMutationResult,
 } from '../types'
 import {getSelection} from '../util/getSelection'
@@ -238,6 +242,30 @@ export function _mutate<R extends Record<string, Any>>(
   return _dataRequest(client, httpRequest, 'mutate', {mutations: muts, transactionId}, options)
 }
 
+/**
+ * @internal
+ */
+export function _action(
+  client: SanityClient | ObservableSanityClient,
+  httpRequest: HttpRequest,
+  actions: Action | Action[],
+  options?: BaseActionOptions,
+): Observable<SingleActionResult | MultipleActionResult> {
+  const acts = Array.isArray(actions) ? actions : [actions]
+  const transactionId = (options && options.transactionId) || undefined
+  const skipCrossDatasetReferenceValidation =
+    (options && options.skipCrossDatasetReferenceValidation) || undefined
+  const dryRun = (options && options.dryRun) || undefined
+
+  return _dataRequest(
+    client,
+    httpRequest,
+    'actions',
+    {actions: acts, transactionId, skipCrossDatasetReferenceValidation, dryRun},
+    options,
+  )
+}
+
 /**
  * @internal
  */
@@ -249,12 +277,13 @@ export function _dataRequest(
   options: Any = {},
 ): Any {
   const isMutation = endpoint === 'mutate'
+  const isAction = endpoint === 'actions'
   const isQuery = endpoint === 'query'
 
   // Check if the query string is within a configured threshold,
   // in which case we can use GET. Otherwise, use POST.
-  const strQuery = isMutation ? '' : encodeQueryString(body)
-  const useGet = !isMutation && strQuery.length < getQuerySizeLimit
+  const strQuery = isMutation || isAction ? '' : encodeQueryString(body)
+  const useGet = !isMutation && !isAction && strQuery.length < getQuerySizeLimit
   const stringQuery = useGet ? strQuery : ''
   const returnFirst = options.returnFirst
   const {timeout, token, tag, headers, returnQuery, lastLiveEventId} = options

package/src/http/errors.ts

@@ -1,4 +1,4 @@
-import type {Any, ErrorProps, MutationError} from '../types'
+import type {ActionError, Any, ErrorProps, MutationError} from '../types'
 
 const MAX_ITEMS_IN_ERROR_MESSAGE = 5
 
@@ -47,7 +47,7 @@ function extractErrorProps(res: Any): ErrorProps {
   }
 
   // Mutation errors (specifically)
-  if (isMutationError(body)) {
+  if (isMutationError(body) || isActionError(body)) {
     const allItems = body.error.items || []
     const items = allItems
       .slice(0, MAX_ITEMS_IN_ERROR_MESSAGE)
@@ -83,6 +83,15 @@ function isMutationError(body: Any): body is MutationError {
   )
 }
 
+function isActionError(body: Any): body is ActionError {
+  return (
+    isPlainObject(body) &&
+    isPlainObject(body.error) &&
+    body.error.type === 'actionError' &&
+    typeof body.error.description === 'string'
+  )
+}
+
 function isPlainObject(obj: Any): obj is Record<string, unknown> {
   return typeof obj === 'object' && obj !== null && !Array.isArray(obj)
 }

package/src/types.ts

@@ -511,6 +511,193 @@ export type Mutation<R extends Record<string, Any> = Record<string, Any>> =
   | {delete: MutationSelection}
   | {patch: PatchMutationOperation}
 
+/** @public */
+export type Action =
+  | CreateAction
+  | ReplaceDraftAction
+  | EditAction
+  | DeleteAction
+  | DiscardAction
+  | PublishAction
+  | UnpublishAction
+
+/**
+ * Creates a new draft document. The published version of the document must not already exist.
+ * If the draft version of the document already exists the action will fail by default, but
+ * this can be adjusted to instead leave the existing document in place.
+ *
+ * @public
+ */
+export type CreateAction = {
+  actionType: 'sanity.action.document.create'
+
+  /**
+   * ID of the published document to create a draft for.
+   */
+  publishedId: string
+
+  /**
+   * Document to create. Requires a `_type` property.
+   */
+  attributes: IdentifiedSanityDocumentStub
+
+  /**
+   * ifExists controls what to do if the draft already exists
+   */
+  ifExists: 'fail' | 'ignore'
+}
+
+/**
+ * Replaces an existing draft document.
+ * At least one of the draft or published versions of the document must exist.
+ *
+ * @public
+ */
+export type ReplaceDraftAction = {
+  actionType: 'sanity.action.document.replaceDraft'
+
+  /**
+   * Draft document ID to replace, if it exists.
+   */
+  draftId: string
+
+  /**
+   * Published document ID to create draft from, if draft does not exist
+   */
+  publishedId: string
+
+  /**
+   * Document to create if it does not already exist. Requires `_id` and `_type` properties.
+   */
+  attributes: IdentifiedSanityDocumentStub
+}
+
+/**
+ * Modifies an existing draft document.
+ * It applies the given patch to the document referenced by draftId.
+ * If there is no such document then one is created using the current state of the published version and then that is updated accordingly.
+ *
+ * @public
+ */
+export type EditAction = {
+  actionType: 'sanity.action.document.edit'
+
+  /**
+   * Draft document ID to edit
+   */
+  draftId: string
+
+  /**
+   * Published document ID to create draft from, if draft does not exist
+   */
+  publishedId: string
+
+  /**
+   * Patch operations to apply
+   */
+  patch: PatchOperations
+}
+
+/**
+ * Deletes the published version of a document and optionally some (likely all known) draft versions.
+ * If any draft version exists that is not specified for deletion this is an error.
+ * If the purge flag is set then the document history is also deleted.
+ *
+ * @public
+ */
+export type DeleteAction = {
+  actionType: 'sanity.action.document.delete'
+
+  /**
+   * Published document ID to delete
+   */
+  publishedId: string
+
+  /**
+   * Draft document ID to delete
+   */
+  includeDrafts: string[]
+
+  /**
+   * Delete document history
+   */
+  purge: boolean
+}
+
+/**
+ * Delete the draft version of a document.
+ * It is an error if it does not exist. If the purge flag is set, the document history is also deleted.
+ *
+ * @public
+ */
+export type DiscardAction = {
+  actionType: 'sanity.action.document.discard'
+
+  /**
+   * Draft document ID to delete
+   */
+  draftId: string
+
+  /**
+   * Delete document history
+   */
+  purge: boolean
+}
+
+/**
+ * Publishes a draft document.
+ * If a published version of the document already exists this is replaced by the current draft document.
+ * In either case the draft document is deleted.
+ * The optional revision id parameters can be used for optimistic locking to ensure
+ * that the draft and/or published versions of the document have not been changed by another client.
+ *
+ * @public
+ */
+export type PublishAction = {
+  actionType: 'sanity.action.document.publish'
+
+  /**
+   * Draft document ID to publish
+   */
+  draftId: string
+
+  /**
+   * Draft revision ID to match
+   */
+  ifDraftRevisionId: string
+
+  /**
+   * Published document ID to replace
+   */
+  publishedId: string
+
+  /**
+   * Published revision ID to match
+   */
+  ifPublishedRevisionId: string
+}
+
+/**
+ * Retract a published document.
+ * If there is no draft version then this is created from the published version.
+ * In either case the published version is deleted.
+ *
+ * @public
+ */
+export type UnpublishAction = {
+  actionType: 'sanity.action.document.unpublish'
+
+  /**
+   * Draft document ID to replace the published document with
+   */
+  draftId: string
+
+  /**
+   * Published document ID to delete
+   */
+  publishedId: string
+}
+
 /**
  * A mutation was performed. Note that when updating multiple documents in a transaction,
  * each document affected will get a separate mutation event.
@@ -884,6 +1071,23 @@ export type TransactionMutationOptions =
   | TransactionAllDocumentsMutationOptions
   | TransactionAllDocumentIdsMutationOptions
 
+/** @internal */
+export type BaseActionOptions = RequestOptions & {
+  transactionId?: string
+  skipCrossDatasetReferenceValidation?: boolean
+  dryRun?: boolean
+}
+
+/** @internal */
+export interface SingleActionResult {
+  transactionId: string
+}
+
+/** @internal */
+export interface MultipleActionResult {
+  transactionId: string
+}
+
 /** @internal */
 export interface RawRequestOptions {
   url?: string
@@ -927,6 +1131,25 @@ export interface MutationErrorItem {
   }
 }
 
+/** @internal */
+export interface ActionError {
+  error: {
+    type: 'actionError'
+    description: string
+    items?: ActionErrorItem[]
+  }
+}
+
+/** @internal */
+export interface ActionErrorItem {
+  error: {
+    type: string
+    description: string
+    value?: unknown
+  }
+  index: number
+}
+
 /**
  * DocumentValueSource is a path to a value within a document
  * @public

package/umd/sanityClient.js

@@ -1839,7 +1839,7 @@
     };
     if (body.error && body.message)
       return props.message = `${body.error} - ${body.message}`, props;
-    if (isMutationError(body)) {
+    if (isMutationError(body) || isActionError(body)) {
       const allItems = body.error.items || [], items = allItems.slice(0, 5).map((item) => {
         var _a;
         return (_a = item.error) == null ? void 0 : _a.description;
@@ -1855,6 +1855,9 @@
   function isMutationError(body) {
     return isPlainObject(body) && isPlainObject(body.error) && body.error.type === "mutationError" && typeof body.error.description == "string";
   }
+  function isActionError(body) {
+    return isPlainObject(body) && isPlainObject(body.error) && body.error.type === "actionError" && typeof body.error.description == "string";
+  }
   function isPlainObject(obj) {
     return typeof obj == "object" && obj !== null && !Array.isArray(obj);
   }
@@ -2486,8 +2489,18 @@ ${selectionOpts}`);
     const muts = Array.isArray(mut) ? mut : [mut], transactionId = options && options.transactionId || void 0;
     return _dataRequest(client, httpRequest, "mutate", { mutations: muts, transactionId }, options);
   }
+  function _action(client, httpRequest, actions, options) {
+    const acts = Array.isArray(actions) ? actions : [actions], transactionId = options && options.transactionId || void 0, skipCrossDatasetReferenceValidation = options && options.skipCrossDatasetReferenceValidation || void 0, dryRun = options && options.dryRun || void 0;
+    return _dataRequest(
+      client,
+      httpRequest,
+      "actions",
+      { actions: acts, transactionId, skipCrossDatasetReferenceValidation, dryRun },
+      options
+    );
+  }
   function _dataRequest(client, httpRequest, endpoint, body, options = {}) {
-    const isMutation = endpoint === "mutate", isQuery = endpoint === "query", strQuery = isMutation ? "" : encodeQueryString(body), useGet = !isMutation && strQuery.length < getQuerySizeLimit, stringQuery = useGet ? strQuery : "", returnFirst = options.returnFirst, { timeout, token, tag, headers, returnQuery, lastLiveEventId } = options, uri = _getDataUrl(client, endpoint, stringQuery), reqOptions = {
+    const isMutation = endpoint === "mutate", isAction = endpoint === "actions", isQuery = endpoint === "query", strQuery = isMutation || isAction ? "" : encodeQueryString(body), useGet = !isMutation && !isAction && strQuery.length < getQuerySizeLimit, stringQuery = useGet ? strQuery : "", returnFirst = options.returnFirst, { timeout, token, tag, headers, returnQuery, lastLiveEventId } = options, uri = _getDataUrl(client, endpoint, stringQuery), reqOptions = {
       method: useGet ? "GET" : "POST",
       uri,
       json: !0,
@@ -3099,6 +3112,15 @@ ${selectionOpts}`);
     transaction(operations) {
       return new ObservableTransaction(operations, this);
     }
+    /**
+     * Perform action operations against the configured dataset
+     *
+     * @param operations - Action operation(s) to execute
+     * @param options - Action options
+     */
+    action(operations, options) {
+      return _action(this, __privateGet(this, _httpRequest), operations, options);
+    }
     /**
      * Perform an HTTP request against the Sanity API
      *
@@ -3236,6 +3258,16 @@ ${selectionOpts}`);
     transaction(operations) {
       return new Transaction(operations, this);
     }
+    /**
+     * Perform action operations against the configured dataset
+     * Returns a promise that resolves to the transaction result
+     *
+     * @param operations - Action operation(s) to execute
+     * @param options - Action options
+     */
+    action(operations, options) {
+      return lastValueFrom(_action(this, __privateGet(this, _httpRequest2), operations, options));
+    }
     /**
      * Perform a request against the Sanity API
      * NOTE: Only use this for Sanity API endpoints, not for your own APIs!