@sanity/sdk 2.11.1 → 2.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/sdk",
-  "version": "2.11.1",
+  "version": "2.13.0",
   "private": false,
   "description": "Sanity SDK",
   "keywords": [
@@ -57,31 +57,31 @@
     "@sanity/image-url": "^2.1.1",
     "@sanity/json-match": "^1.0.5",
     "@sanity/message-protocol": "^0.23.0",
-    "@sanity/mutate": "^0.16.1",
+    "@sanity/mutate": "^0.18.0",
     "@sanity/telemetry": "^1.1.0",
-    "@sanity/types": "^5.24.0",
+    "@sanity/types": "^5.26.0",
     "groq": "3.88.1-typegen-experimental.0",
-    "groq-js": "^1.30.1",
+    "groq-js": "^1.30.2",
     "reselect": "^5.1.1",
     "rxjs": "^7.8.2",
     "zustand": "^5.0.13"
   },
   "devDependencies": {
     "@sanity/browserslist-config": "^1.0.5",
-    "@sanity/pkg-utils": "^8.1.29",
+    "@sanity/pkg-utils": "^9.2.3",
     "@sanity/prettier-config": "^1.0.6",
-    "@types/node": "^24.12.3",
-    "@vitest/coverage-v8": "4.1.5",
+    "@types/node": "^24.12.4",
+    "@vitest/coverage-v8": "^4.1.8",
     "eslint": "^9.39.4",
     "prettier": "^3.8.3",
     "rollup-plugin-visualizer": "^5.14.0",
     "typescript": "^5.9.3",
-    "vite": "^7.3.3",
-    "vitest": "^4.1.5",
-    "@repo/config-eslint": "0.0.0",
-    "@repo/package.bundle": "3.82.0",
+    "vite": "^7.3.5",
+    "vitest": "^4.1.8",
     "@repo/config-test": "0.0.1",
     "@repo/package.config": "0.0.1",
+    "@repo/config-eslint": "0.0.0",
+    "@repo/package.bundle": "3.82.0",
     "@repo/tsconfig": "0.0.1"
   },
   "publishConfig": {

package/src/_exports/index.ts

@@ -105,6 +105,7 @@ export {
   type MediaLibrarySource,
   type PerspectiveHandle,
   type ProjectHandle,
+  type ReleaseHandle,
   type ReleasePerspective,
   type SanityConfig,
   type StudioConfig,
@@ -112,19 +113,37 @@ export {
 } from '../config/sanityConfig'
 export {getDatasetsState, resolveDatasets} from '../datasets/datasets'
 export {
+  type Action,
+  archiveRelease,
+  type ArchiveReleaseAction,
   createDocument,
   type CreateDocumentAction,
+  createRelease,
+  type CreateReleaseAction,
   deleteDocument,
   type DeleteDocumentAction,
+  deleteRelease,
+  type DeleteReleaseAction,
   discardDocument,
   type DiscardDocumentAction,
   type DocumentAction,
   editDocument,
   type EditDocumentAction,
+  editRelease,
+  type EditReleaseAction,
   publishDocument,
   type PublishDocumentAction,
+  publishRelease,
+  type PublishReleaseAction,
+  type ReleaseAction,
+  scheduleRelease,
+  type ScheduleReleaseAction,
+  unarchiveRelease,
+  type UnarchiveReleaseAction,
   unpublishDocument,
   type UnpublishDocumentAction,
+  unscheduleRelease,
+  type UnscheduleReleaseAction,
 } from '../document/actions'
 export {
   type ActionsResult,
@@ -155,6 +174,7 @@ export {
 } from '../document/events'
 export {type JsonMatch} from '../document/patchOperations'
 export {type DocumentPermissionsResult, type PermissionDeniedReason} from '../document/permissions'
+export {getReleaseDocumentId} from '../document/processActions/releaseUtil'
 export type {FavoriteStatusResponse} from '../favorites/favorites'
 export {getFavoritesState, resolveFavoritesState} from '../favorites/favorites'
 export {
@@ -214,8 +234,8 @@ export {
   resolveQuery,
 } from '../query/queryStore'
 export {getPerspectiveState} from '../releases/getPerspectiveState'
-export type {ReleaseDocument} from '../releases/releasesStore'
-export {getActiveReleasesState} from '../releases/releasesStore'
+export type {ReleaseState} from '../releases/releasesStore'
+export {getActiveReleasesState, getAllReleasesState} from '../releases/releasesStore'
 export {createSanityInstance, type SanityInstance} from '../store/createSanityInstance'
 export {type Selector, type StateSource} from '../store/createStateSourceAction'
 export {getUsersKey, parseUsersKey} from '../users/reducers'
@@ -244,6 +264,7 @@ export {defineIntent, type Intent, type IntentFilter} from '../utils/defineInten
 export {getCorsErrorProjectId} from '../utils/getCorsErrorProjectId'
 export {isImportError} from '../utils/isImportError'
 export {CORE_SDK_VERSION} from '../version'
+export type {ReleaseDocument} from '@sanity/client'
 export {
   getIndexForKey,
   getPathDepth,

package/src/config/sanityConfig.ts

@@ -118,6 +118,18 @@ export interface DocumentHandle<
   documentId: string
 }
 
+/**
+ * Identifies a release within a Sanity dataset and project. `releaseId` is the
+ * `name` parameter on the release document (e.g. `{name: 'r41035a4'}`).
+ * The underlying release document ID is `_.releases.<releaseId>`.
+ * It's also the `id` parameter sent to the Actions API.
+ * (This type doesn't need to have ProjectId / Dataset generics since it's always the same shape)
+ * @beta
+ */
+export interface ReleaseHandle extends DatasetHandle {
+  releaseId: string
+}
+
 /**
  * Represents the complete configuration for a Sanity SDK instance
  * @public

package/src/document/actions.test.ts

@@ -1,15 +1,24 @@
+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} 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 = {
@@ -19,6 +28,9 @@ const dummyPatch: PatchOperations = {
 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', () => {
     it('creates a document action from a document handle', () => {
@@ -207,3 +219,102 @@ describe('document actions', () => {
     })
   })
 })
+
+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,14 @@
+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} from '@sanity/types'
 import {type SanityDocument} from 'groq'
 
-import {type DocumentHandle, type DocumentTypeHandle} from '../config/sanityConfig'
+import {
+  type DocumentHandle,
+  type DocumentTypeHandle,
+  type ReleaseHandle,
+} from '../config/sanityConfig'
 import {getEffectiveDocumentId} from './util'
 
 const isSanityMutatePatch = (value: unknown): value is SanityMutatePatchMutation => {
@@ -120,6 +125,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.
@@ -316,3 +332,134 @@ export function discardDocument<
     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}
+}

package/src/document/applyDocumentActions.test.ts

@@ -202,4 +202,28 @@ describe('applyDocumentActions', () => {
     childInstance.dispose()
     parentInstance.dispose()
   })
+
+  it('normalizes actions for the bound resource before queueing', async () => {
+    // A plain edit action with no `liveEdit` flag. Canvas forces liveEdit, so
+    // the queued action should come back with `liveEdit: true` — proving that
+    // `applyDocumentActions` runs `normalizeActionsForResource`.
+    const action: DocumentAction = {
+      type: 'document.edit',
+      documentId: 'doc1',
+      documentType: 'sanity.canvas.document',
+      patches: [{set: {foo: 'bar'}}],
+    }
+
+    // Don't await — we only need to inspect the synchronously-queued transaction.
+    applyDocumentActions(instance, {
+      actions: [action],
+      transactionId: 'txn-normalize',
+      resource: {canvasId: 'c'},
+    })
+
+    const queued = state.get().queued.find((t) => t.transactionId === 'txn-normalize')
+    expect(queued).toBeDefined()
+    const [queuedAction] = queued!.actions
+    expect(queuedAction).toMatchObject({type: 'document.edit', liveEdit: true})
+  })
 })

package/src/document/applyDocumentActions.ts

@@ -5,11 +5,12 @@ import {type DocumentResource} from '../config/sanityConfig'
 import {bindActionByResource} from '../store/createActionBinder'
 import {type SanityInstance} from '../store/createSanityInstance'
 import {type StoreContext} from '../store/defineStore'
-import {type DocumentAction} from './actions'
+import {type Action} from './actions'
 import {documentStore, type DocumentStoreState} from './documentStore'
 import {type DocumentTransactionSubmissionResult} from './events'
 import {type DocumentSet} from './processMutations'
 import {type AppliedTransaction, type QueuedTransaction, queueTransaction} from './reducers'
+import {normalizeActionsForResource} from './resourceRules'
 
 /** @beta */
 export interface ActionsResult<TDocument extends SanityDocument = SanityDocument> {
@@ -26,9 +27,10 @@ export interface ActionsResult<TDocument extends SanityDocument = SanityDocument
 /** @beta */
 export interface ApplyDocumentActionsOptions {
   /**
-   * List of actions to apply.
+   * List of actions to apply. Accepts both document actions and release
+   * lifecycle actions because they share the same transaction pipeline.
    */
-  actions: DocumentAction[]
+  actions: Action[]
 
   /**
    * The resource to which the documents being acted on belong.
@@ -72,13 +74,23 @@ const boundApplyDocumentActions = bindActionByResource(documentStore, _applyDocu
 /** @internal */
 async function _applyDocumentActions(
   {state}: StoreContext<DocumentStoreState>,
-  {actions, transactionId = crypto.randomUUID(), disableBatching}: ApplyDocumentActionsOptions,
+  {
+    actions,
+    resource,
+    transactionId = crypto.randomUUID(),
+    disableBatching,
+  }: ApplyDocumentActionsOptions,
 ): Promise<ActionsResult> {
   const {events} = state.get()
 
+  // Rewrite edit actions to match the bound resource's editing model (e.g.
+  // forcing liveEdit for Canvas, stripping unsupported release perspectives).
+  // Non-edit and release actions pass through unchanged.
+  const normalizedActions = normalizeActionsForResource(actions, resource)
+
   const transaction: QueuedTransaction = {
     transactionId,
-    actions,
+    actions: normalizedActions,
     ...(disableBatching && {disableBatching}),
   }
 

package/src/document/documentConstants.ts

@@ -8,3 +8,10 @@
 export const DOCUMENT_STATE_CLEAR_DELAY = 1000
 export const INITIAL_OUTGOING_THROTTLE_TIME = 1000
 export const API_VERSION = 'v2025-05-06'
+
+/**
+ * Base delay (ms) before retrying a document listener after an `OutOfSyncError`.
+ * Backoff doubles on each successive retry, capped at {@link OUT_OF_SYNC_RETRY_MAX_DELAY}.
+ */
+export const OUT_OF_SYNC_RETRY_BASE_DELAY = 500
+export const OUT_OF_SYNC_RETRY_MAX_DELAY = 10_000

package/src/document/documentStore.test.ts

@@ -42,6 +42,7 @@ import {
   subscribeDocumentEvents,
 } from './documentStore'
 import {type ActionErrorEvent, type TransactionRevertedEvent} from './events'
+import {DEFAULT_MAX_BUFFER_SIZE} from './listen'
 import {type DatasetAcl} from './permissions'
 import {type DocumentSet, processMutations} from './processMutations'
 import {type HttpAction} from './reducers'
@@ -1006,6 +1007,72 @@ it('version edits are isolated from draft state', async () => {
   unsubscribeDraft()
 })
 
+it('subscribeToSubscriptionsAndListenToDocuments recovers from an OutOfSyncError instead of failing the document store', async () => {
+  const documentId = DocumentId('doc-out-of-sync-recovery')
+  const doc = createDocumentHandle({documentId, documentType: 'article'})
+  const documentState = getDocumentState<TestDocument>(instance, doc)
+  const unsubscribe = documentState.subscribe()
+  const draftId = getDraftId(documentId)
+
+  // Establish a synced document so the listener has a base revision.
+  const created = await applyDocumentActions(instance, {
+    actions: [createDocument(doc), editDocument(doc, {set: {title: 'initial'}})],
+  })
+  await created.submitted()
+  expect(documentState.getCurrent()?.title).toBe('initial')
+
+  // Capture the fetchDocument spy so we can detect when the listener
+  // re-subscribes. (every frest subscription re-runs fetchDocument)
+  const fetchDocumentSpy = vi.mocked(createFetchDocument).mock.results.at(-1)?.value as ReturnType<
+    typeof vi.fn
+  >
+  const fetchCallsBefore = fetchDocumentSpy.mock.calls.filter(([id]) => id === draftId).length
+
+  // Inject DEFAULT_MAX_BUFFER_SIZE mutations whose previousRev doesn't chain
+  // to the base revision (basically forcing the error)
+  const sharedListener = (
+    createSharedListener as unknown as () => {events: Subject<ListenEvent<SanityDocument>>}
+  )()
+  for (let i = 0; i < DEFAULT_MAX_BUFFER_SIZE; i++) {
+    sharedListener.events.next({
+      type: 'mutation',
+      documentId: draftId,
+      eventId: `bad-${i}`,
+      identity: 'user',
+      mutations: [],
+      timestamp: new Date().toISOString(),
+      transactionId: `bad-tx-${i}`,
+      transactionCurrentEvent: 0,
+      transactionTotalEvents: 1,
+      previousRev: `dangling-rev-${i}`,
+      resultRev: `bad-rev-${i}`,
+      transition: 'update',
+      visibility: 'query',
+    })
+  }
+
+  // The above should have triggered a retry and re-subscribed to the listener
+  await vi.waitFor(() => {
+    expect(fetchDocumentSpy.mock.calls.filter(([id]) => id === draftId).length).toBeGreaterThan(
+      fetchCallsBefore,
+    )
+  })
+
+  // The store stayed healthy through the OutOfSyncError.
+  expect(() => documentState.getCurrent()).not.toThrow()
+  expect(() => getDocumentSyncStatus(instance, doc).getCurrent()).not.toThrow()
+
+  // A follow-up edit still propagates through the recovered listener.
+  const edited = await applyDocumentActions(instance, {
+    actions: [editDocument(doc, {set: {title: 'after-recovery'}})],
+    resource,
+  })
+  await edited.submitted()
+  expect(documentState.getCurrent()?.title).toBe('after-recovery')
+
+  unsubscribe()
+})
+
 vi.mock('../client/clientStore.ts', () => ({
   getClientState: vi.fn().mockReturnValue({observable: new ReplaySubject(1)}),
 }))
@@ -1039,6 +1106,8 @@ vi.mock('./documentConstants.ts', async (importOriginal) => {
     ...original,
     INITIAL_OUTGOING_THROTTLE_TIME: 0,
     DOCUMENT_STATE_CLEAR_DELAY: 25,
+    OUT_OF_SYNC_RETRY_BASE_DELAY: 0,
+    OUT_OF_SYNC_RETRY_MAX_DELAY: 0,
   }
 })