@sanity/sdk 3.0.0-rc.0 → 3.0.0-rc.1

package/src/document/actions.test.ts

@@ -1,32 +1,35 @@
+import {type ReleaseDocument} from '@sanity/client'
 import {at, patch, set, setIfMissing} from '@sanity/mutate'
 import {type PatchOperations} from '@sanity/types'
 import {describe, expect, it} from 'vitest'
 
-import {type DocumentHandle, type DocumentResource} from '../config/sanityConfig'
+import {type DocumentHandle, type ReleaseHandle} from '../config/sanityConfig'
 import {
+  archiveRelease,
   createDocument,
+  createRelease,
   deleteDocument,
+  deleteRelease,
   discardDocument,
   editDocument,
+  editRelease,
   publishDocument,
+  publishRelease,
+  scheduleRelease,
+  unarchiveRelease,
   unpublishDocument,
+  unscheduleRelease,
 } from '../document/actions'
 
 const dummyPatch: PatchOperations = {
   diffMatchPatch: {'dummy.path': 'dummy patch'},
 }
-const dummyDocResource: DocumentResource = {projectId: 'test-project', dataset: 'test-dataset'}
 
-const dummyDocHandle: DocumentHandle = {
-  documentId: 'drafts.abc123',
-  documentType: 'testType',
-  resource: dummyDocResource,
-}
-const dummyDocString: DocumentHandle = {
-  documentId: 'drafts.abc123',
-  documentType: 'testType',
-  resource: dummyDocResource,
-}
+const dummyDocHandle: DocumentHandle = {documentId: 'drafts.abc123', documentType: 'testType'}
+const dummyDocString = {documentId: 'drafts.abc123', documentType: 'testType'}
+
+const dummyReleaseHandle: ReleaseHandle = {releaseId: 'my-release'}
+const dummyReleasePatch: PatchOperations = {set: {'metadata.title': 'Updated title'}}
 
 describe('document actions', () => {
   describe('createDocument', () => {
@@ -37,24 +40,18 @@ describe('document actions', () => {
         // getId returns the input if it does not end with a dot.
         documentId: 'abc123',
         documentType: dummyDocHandle.documentType,
-        resource: dummyDocResource,
       })
     })
 
     it('creates a document action from a document type handle', () => {
       // A document type handle is similar to a document handle,
       // but _id is optional.
-      const typeHandle = {
-        documentId: 'abc456',
-        documentType: 'anotherType',
-        resource: dummyDocResource,
-      }
+      const typeHandle = {documentId: 'abc456', documentType: 'anotherType'}
       const action = createDocument(typeHandle)
       expect(action).toEqual({
         type: 'document.create',
         documentId: 'abc456',
         documentType: typeHandle.documentType,
-        resource: dummyDocResource,
       })
     })
 
@@ -70,7 +67,6 @@ describe('document actions', () => {
         documentId: 'abc123',
         documentType: dummyDocHandle.documentType,
         initialValue,
-        resource: dummyDocResource,
       })
     })
 
@@ -80,7 +76,6 @@ describe('document actions', () => {
         type: 'document.create',
         documentId: 'abc123',
         documentType: dummyDocHandle.documentType,
-        resource: dummyDocResource,
       })
     })
 
@@ -91,7 +86,6 @@ describe('document actions', () => {
         documentId: 'abc123',
         documentType: dummyDocHandle.documentType,
         initialValue: {},
-        resource: dummyDocResource,
       })
     })
   })
@@ -104,7 +98,6 @@ describe('document actions', () => {
         type: 'document.delete',
         documentId: 'abc123',
         documentType: dummyDocString.documentType,
-        resource: dummyDocResource,
       })
     })
 
@@ -114,7 +107,6 @@ describe('document actions', () => {
         type: 'document.delete',
         documentId: 'abc123',
         documentType: dummyDocHandle.documentType,
-        resource: dummyDocResource,
       })
     })
   })
@@ -127,7 +119,6 @@ describe('document actions', () => {
         documentId: 'abc123',
         documentType: dummyDocString.documentType,
         patches: [dummyPatch],
-        resource: dummyDocResource,
       })
     })
 
@@ -138,7 +129,6 @@ describe('document actions', () => {
         documentId: 'abc123',
         documentType: dummyDocHandle.documentType,
         patches: [dummyPatch],
-        resource: dummyDocResource,
       })
     })
 
@@ -165,7 +155,6 @@ describe('document actions', () => {
           {ifRevisionID: 'txn0', set: {'address.city': 'Oslo'}},
         ],
         type: 'document.edit',
-        resource: dummyDocResource,
       })
     })
   })
@@ -177,7 +166,6 @@ describe('document actions', () => {
         type: 'document.publish',
         documentId: 'abc123',
         documentType: dummyDocString.documentType,
-        resource: dummyDocResource,
       })
     })
 
@@ -187,7 +175,6 @@ describe('document actions', () => {
         type: 'document.publish',
         documentId: 'abc123',
         documentType: dummyDocHandle.documentType,
-        resource: dummyDocResource,
       })
     })
   })
@@ -199,7 +186,6 @@ describe('document actions', () => {
         type: 'document.unpublish',
         documentId: 'abc123',
         documentType: dummyDocString.documentType,
-        resource: dummyDocResource,
       })
     })
 
@@ -209,7 +195,6 @@ describe('document actions', () => {
         type: 'document.unpublish',
         documentId: 'abc123',
         documentType: dummyDocHandle.documentType,
-        resource: dummyDocResource,
       })
     })
   })
@@ -221,7 +206,6 @@ describe('document actions', () => {
         type: 'document.discard',
         documentId: 'abc123',
         documentType: dummyDocString.documentType,
-        resource: dummyDocResource,
       })
     })
 
@@ -231,8 +215,106 @@ describe('document actions', () => {
         type: 'document.discard',
         documentId: 'abc123',
         documentType: dummyDocHandle.documentType,
-        resource: dummyDocResource,
       })
     })
   })
 })
+
+describe('release actions', () => {
+  describe('createRelease', () => {
+    it('creates a release action from a release handle', () => {
+      const action = createRelease(dummyReleaseHandle)
+      expect(action).toEqual({
+        type: 'release.create',
+        releaseId: 'my-release',
+        metadata: {releaseType: 'undecided'},
+      })
+    })
+
+    it('creates a release action with metadata', () => {
+      const metadata: ReleaseDocument['metadata'] = {
+        title: 'My release',
+        description: 'Some description',
+        releaseType: 'scheduled',
+        intendedPublishAt: '2026-01-01T00:00:00.000Z',
+      }
+      const action = createRelease(dummyReleaseHandle, metadata)
+      expect(action).toEqual({
+        type: 'release.create',
+        releaseId: 'my-release',
+        metadata,
+      })
+    })
+
+    it('preserves resource fields from the handle', () => {
+      const action = createRelease({
+        releaseId: 'my-release',
+        resource: {dataset: 'production', projectId: 'abc123'},
+      })
+      expect(action).toEqual({
+        type: 'release.create',
+        releaseId: 'my-release',
+        resource: {dataset: 'production', projectId: 'abc123'},
+        metadata: {releaseType: 'undecided'},
+      })
+    })
+  })
+
+  describe('editRelease', () => {
+    it('creates a release.edit action with a patch', () => {
+      const action = editRelease(dummyReleaseHandle, dummyReleasePatch)
+      expect(action).toEqual({
+        type: 'release.edit',
+        releaseId: 'my-release',
+        patch: dummyReleasePatch,
+      })
+    })
+  })
+
+  describe('publishRelease', () => {
+    it('creates a release.publish action from a release handle', () => {
+      const action = publishRelease(dummyReleaseHandle)
+      expect(action).toEqual({type: 'release.publish', releaseId: 'my-release'})
+    })
+  })
+
+  describe('scheduleRelease', () => {
+    it('creates a release.schedule action with publishAt', () => {
+      const publishAt = '2026-01-01T00:00:00.000Z'
+      const action = scheduleRelease(dummyReleaseHandle, publishAt)
+      expect(action).toEqual({
+        type: 'release.schedule',
+        releaseId: 'my-release',
+        publishAt,
+      })
+    })
+  })
+
+  describe('unscheduleRelease', () => {
+    it('creates a release.unschedule action from a release handle', () => {
+      const action = unscheduleRelease(dummyReleaseHandle)
+      expect(action).toEqual({type: 'release.unschedule', releaseId: 'my-release'})
+    })
+  })
+
+  describe('archiveRelease', () => {
+    it('creates a release.archive action from a release handle', () => {
+      const action = archiveRelease(dummyReleaseHandle)
+      expect(action).toEqual({type: 'release.archive', releaseId: 'my-release'})
+    })
+  })
+
+  describe('unarchiveRelease', () => {
+    it('creates a release.unarchive action from a release handle', () => {
+      const action = unarchiveRelease(dummyReleaseHandle)
+      expect(action).toEqual({type: 'release.unarchive', releaseId: 'my-release'})
+    })
+  })
+
+  describe('deleteRelease', () => {
+    it('creates a release.delete action from a release handle', () => {
+      const action = deleteRelease(dummyReleaseHandle)
+      expect(action).toEqual({type: 'release.delete', releaseId: 'my-release'})
+    })
+  })
+})

package/src/document/actions.ts

@@ -1,9 +1,15 @@
+import {type ReleaseDocument} from '@sanity/client'
 import {SanityEncoder} from '@sanity/mutate'
 import {type PatchMutation as SanityMutatePatchMutation} from '@sanity/mutate/_unstable_store'
-import {type PatchMutation, type PatchOperations, type SanityDocument} from '@sanity/types'
+import {type PatchMutation, type PatchOperations} from '@sanity/types'
+import {type SanityDocument} from 'groq'
 
-import {type DocumentHandle, type DocumentTypeHandle} from '../config/sanityConfig'
-import {getPublishedId} from '../utils/ids'
+import {
+  type DocumentHandle,
+  type DocumentTypeHandle,
+  type ReleaseHandle,
+} from '../config/sanityConfig'
+import {getEffectiveDocumentId} from './util'
 
 const isSanityMutatePatch = (value: unknown): value is SanityMutatePatchMutation => {
   if (typeof value !== 'object' || !value) return false
@@ -30,7 +36,10 @@ export interface CreateDocumentAction<
    * System fields (_id, _type, _rev, _createdAt, _updatedAt) are omitted as they are set automatically.
    */
   initialValue?: Partial<
-    Omit<SanityDocument, '_id' | '_type' | '_rev' | '_createdAt' | '_updatedAt'>
+    Omit<
+      SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`>,
+      '_id' | '_type' | '_rev' | '_createdAt' | '_updatedAt'
+    >
   >
 }
 
@@ -59,6 +68,21 @@ export interface EditDocumentAction<
 > extends DocumentHandle<TDocumentType, TDataset, TProjectId> {
   type: 'document.edit'
   patches?: PatchOperations[]
+  /**
+   * When `true`, the given `patches` are forwarded verbatim to the server and
+   * applied as-is locally, instead of being re-derived by diffing document
+   * snapshots. This preserves the operational intent of the patches (e.g.
+   * keyed array inserts/unsets), which lets concurrent edits from other
+   * clients interleave coherently instead of being overwritten by
+   * position-based patches computed from a stale snapshot.
+   *
+   * Use this when the patches were produced by an editor that tracks its own
+   * operations (e.g. a collaborative text editor). During a rebase onto a
+   * changed remote document, preserved patches are re-applied operationally;
+   * if a patch can no longer apply, the transaction is skipped and reported
+   * as a `rebase-error` document event.
+   */
+  preserveOperations?: boolean
 }
 
 /**
@@ -116,6 +140,17 @@ export type DocumentAction<
   | UnpublishDocumentAction<TDocumentType, TDataset, TProjectId>
   | DiscardDocumentAction<TDocumentType, TDataset, TProjectId>
 
+/**
+ * Union of every action accepted by `applyDocumentActions` — both document-
+ * level actions and release-lifecycle actions.
+ * @beta
+ */
+export type Action<
+  TDocumentType extends string = string,
+  TDataset extends string = string,
+  TProjectId extends string = string,
+> = DocumentAction<TDocumentType, TDataset, TProjectId> | ReleaseAction
+
 /**
  * Creates a `CreateDocumentAction` object.
  * @param doc - A handle identifying the document type, dataset, and project. An optional `documentId` can be provided.
@@ -130,15 +165,21 @@ export function createDocument<
 >(
   doc: DocumentTypeHandle<TDocumentType, TDataset, TProjectId>,
   initialValue?: Partial<
-    Omit<SanityDocument, '_id' | '_type' | '_rev' | '_createdAt' | '_updatedAt'>
+    Omit<
+      SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`>,
+      '_id' | '_type' | '_rev' | '_createdAt' | '_updatedAt'
+    >
   >,
 ): CreateDocumentAction<TDocumentType, TDataset, TProjectId> {
+  // users may pass in an explicit documentId -- make sure we format it correctly for the action
+  let effectiveDocumentId
+  if (typeof doc.documentId === 'string') {
+    effectiveDocumentId = getEffectiveDocumentId({...doc, documentId: doc.documentId})
+  }
   return {
     type: 'document.create',
     ...doc,
-    ...(doc.documentId && {
-      documentId: doc.liveEdit ? doc.documentId : getPublishedId(doc.documentId),
-    }),
+    ...(effectiveDocumentId && {documentId: effectiveDocumentId}),
     ...(initialValue && {initialValue}),
   }
 }
@@ -156,10 +197,11 @@ export function deleteDocument<
 >(
   doc: DocumentHandle<TDocumentType, TDataset, TProjectId>,
 ): DeleteDocumentAction<TDocumentType, TDataset, TProjectId> {
+  const effectiveDocumentId = getEffectiveDocumentId(doc)
   return {
     type: 'document.delete',
     ...doc,
-    documentId: doc.liveEdit ? doc.documentId : getPublishedId(doc.documentId),
+    documentId: effectiveDocumentId,
   }
 }
 
@@ -174,12 +216,25 @@ function convertSanityMutatePatch(
   })
 }
 
+/**
+ * Options for creating an `EditDocumentAction`.
+ * @beta
+ */
+export interface EditDocumentOptions {
+  /**
+   * Forward the given patches verbatim instead of re-deriving them by
+   * diffing document snapshots. See {@link EditDocumentAction.preserveOperations}.
+   */
+  preserveOperations?: boolean
+}
+
 /**
  * Creates an `EditDocumentAction` object with patches for modifying a document.
  * Accepts patches in either the standard `PatchOperations` format or as a `SanityMutatePatchMutation` from `@sanity/mutate`.
  *
  * @param doc - A handle uniquely identifying the document to be edited.
  * @param sanityMutatePatch - A patch mutation object from `@sanity/mutate`.
+ * @param options - Options controlling how the patches are processed.
  * @returns An `EditDocumentAction` object ready for dispatch.
  * @beta
  */
@@ -190,12 +245,14 @@ export function editDocument<
 >(
   doc: DocumentHandle<TDocumentType, TDataset, TProjectId>,
   sanityMutatePatch: SanityMutatePatchMutation,
+  options?: EditDocumentOptions,
 ): EditDocumentAction<TDocumentType, TDataset, TProjectId>
 /**
  * Creates an `EditDocumentAction` object with patches for modifying a document.
  *
  * @param doc - A handle uniquely identifying the document to be edited.
  * @param patches - A single patch operation or an array of patch operations.
+ * @param options - Options controlling how the patches are processed.
  * @returns An `EditDocumentAction` object ready for dispatch.
  * @beta
  */
@@ -206,6 +263,7 @@ export function editDocument<
 >(
   doc: DocumentHandle<TDocumentType, TDataset, TProjectId>,
   patches?: PatchOperations | PatchOperations[],
+  options?: EditDocumentOptions,
 ): EditDocumentAction<TDocumentType, TDataset, TProjectId>
 /**
  * Creates an `EditDocumentAction` object with patches for modifying a document.
@@ -213,6 +271,7 @@ export function editDocument<
  *
  * @param doc - A handle uniquely identifying the document to be edited.
  * @param patches - Patches in various formats (`PatchOperations`, `PatchOperations[]`, or `SanityMutatePatchMutation`).
+ * @param options - Options controlling how the patches are processed.
  * @returns An `EditDocumentAction` object ready for dispatch.
  */
 export function editDocument<
@@ -222,24 +281,28 @@ export function editDocument<
 >(
   doc: DocumentHandle<TDocumentType, TDataset, TProjectId>,
   patches?: PatchOperations | PatchOperations[] | SanityMutatePatchMutation,
+  options?: EditDocumentOptions,
 ): EditDocumentAction<TDocumentType, TDataset, TProjectId> {
-  const documentId = doc.liveEdit ? doc.documentId : getPublishedId(doc.documentId)
+  const effectiveDocumentId = getEffectiveDocumentId(doc)
+  const preserveOperations = options?.preserveOperations && {preserveOperations: true as const}
 
   if (isSanityMutatePatch(patches)) {
     const converted = convertSanityMutatePatch(patches) ?? []
     return {
       ...doc,
       type: 'document.edit',
-      documentId,
+      documentId: effectiveDocumentId,
       patches: converted,
+      ...preserveOperations,
     }
   }
 
   return {
     ...doc,
     type: 'document.edit',
-    documentId,
+    documentId: effectiveDocumentId,
     ...(patches && {patches: Array.isArray(patches) ? patches : [patches]}),
+    ...preserveOperations,
   }
 }
 
@@ -256,10 +319,11 @@ export function publishDocument<
 >(
   doc: DocumentHandle<TDocumentType, TDataset, TProjectId>,
 ): PublishDocumentAction<TDocumentType, TDataset, TProjectId> {
+  const effectiveDocumentId = getEffectiveDocumentId(doc)
   return {
     type: 'document.publish',
     ...doc,
-    documentId: doc.liveEdit ? doc.documentId : getPublishedId(doc.documentId),
+    documentId: effectiveDocumentId,
   }
 }
 
@@ -276,10 +340,11 @@ export function unpublishDocument<
 >(
   doc: DocumentHandle<TDocumentType, TDataset, TProjectId>,
 ): UnpublishDocumentAction<TDocumentType, TDataset, TProjectId> {
+  const effectiveDocumentId = getEffectiveDocumentId(doc)
   return {
     type: 'document.unpublish',
     ...doc,
-    documentId: doc.liveEdit ? doc.documentId : getPublishedId(doc.documentId),
+    documentId: effectiveDocumentId,
   }
 }
 
@@ -296,9 +361,141 @@ export function discardDocument<
 >(
   doc: DocumentHandle<TDocumentType, TDataset, TProjectId>,
 ): DiscardDocumentAction<TDocumentType, TDataset, TProjectId> {
+  const effectiveDocumentId = getEffectiveDocumentId(doc)
   return {
     type: 'document.discard',
     ...doc,
-    documentId: doc.liveEdit ? doc.documentId : getPublishedId(doc.documentId),
+    documentId: effectiveDocumentId,
   }
 }
+
+/**
+ * Creates a new release. The `releaseId` must be unique within the current
+ * retention period.
+ * @beta
+ */
+export interface CreateReleaseAction extends ReleaseHandle {
+  type: 'release.create'
+  metadata: ReleaseDocument['metadata']
+}
+
+/**
+ * Patches the metadata of an existing release.
+ * @beta
+ */
+export interface EditReleaseAction extends ReleaseHandle {
+  type: 'release.edit'
+  patch: PatchOperations
+}
+
+/**
+ * Publishes all version documents in a release.
+ * @beta
+ */
+export interface PublishReleaseAction extends ReleaseHandle {
+  type: 'release.publish'
+}
+
+/**
+ * Schedules a release to be published at the given UTC time. Locks the
+ * version documents server-side until the release is unscheduled or published.
+ * @beta
+ */
+export interface ScheduleReleaseAction extends ReleaseHandle {
+  type: 'release.schedule'
+  publishAt: string
+}
+
+/**
+ * Unschedules a release that was previously scheduled, returning it to the
+ * active editable state.
+ * @beta
+ */
+export interface UnscheduleReleaseAction extends ReleaseHandle {
+  type: 'release.unschedule'
+}
+
+/**
+ * Archives an active release. Version documents within the release are
+ * removed and no longer queryable, though still recoverable through history
+ * during the retention period.
+ * @beta
+ */
+export interface ArchiveReleaseAction extends ReleaseHandle {
+  type: 'release.archive'
+}
+
+/**
+ * Restores an archived release. Only possible during the retention period.
+ * @beta
+ */
+export interface UnarchiveReleaseAction extends ReleaseHandle {
+  type: 'release.unarchive'
+}
+
+/**
+ * Permanently deletes an archived or published release. To remove an active
+ * release, use the archive action first.
+ * @beta
+ */
+export interface DeleteReleaseAction extends ReleaseHandle {
+  type: 'release.delete'
+}
+
+/**
+ * Union of all release actions that can be dispatched alongside document
+ * actions through `applyDocumentActions`.
+ * @beta
+ */
+export type ReleaseAction =
+  | CreateReleaseAction
+  | EditReleaseAction
+  | PublishReleaseAction
+  | ScheduleReleaseAction
+  | UnscheduleReleaseAction
+  | ArchiveReleaseAction
+  | UnarchiveReleaseAction
+  | DeleteReleaseAction
+
+/** @beta */
+export function createRelease(
+  handle: ReleaseHandle,
+  metadata: ReleaseDocument['metadata'] = {releaseType: 'undecided'},
+): CreateReleaseAction {
+  return {type: 'release.create', ...handle, metadata}
+}
+
+/** @beta */
+export function editRelease(handle: ReleaseHandle, patch: PatchOperations): EditReleaseAction {
+  return {type: 'release.edit', ...handle, patch}
+}
+
+/** @beta */
+export function publishRelease(handle: ReleaseHandle): PublishReleaseAction {
+  return {type: 'release.publish', ...handle}
+}
+
+/** @beta */
+export function scheduleRelease(handle: ReleaseHandle, publishAt: string): ScheduleReleaseAction {
+  return {type: 'release.schedule', ...handle, publishAt}
+}
+
+/** @beta */
+export function unscheduleRelease(handle: ReleaseHandle): UnscheduleReleaseAction {
+  return {type: 'release.unschedule', ...handle}
+}
+
+/** @beta */
+export function archiveRelease(handle: ReleaseHandle): ArchiveReleaseAction {
+  return {type: 'release.archive', ...handle}
+}
+
+/** @beta */
+export function unarchiveRelease(handle: ReleaseHandle): UnarchiveReleaseAction {
+  return {type: 'release.unarchive', ...handle}
+}
+
+/** @beta */
+export function deleteRelease(handle: ReleaseHandle): DeleteReleaseAction {
+  return {type: 'release.delete', ...handle}
+}