@sanity/sdk 2.11.1 → 2.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/sdk",
-  "version": "2.11.1",
+  "version": "2.12.0",
   "private": false,
   "description": "Sanity SDK",
   "keywords": [
@@ -59,7 +59,7 @@
     "@sanity/message-protocol": "^0.23.0",
     "@sanity/mutate": "^0.16.1",
     "@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",
     "reselect": "^5.1.1",
@@ -70,19 +70,19 @@
     "@sanity/browserslist-config": "^1.0.5",
     "@sanity/pkg-utils": "^8.1.29",
     "@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.6",
     "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",
+    "vitest": "^4.1.6",
     "@repo/package.bundle": "3.82.0",
-    "@repo/config-test": "0.0.1",
     "@repo/package.config": "0.0.1",
-    "@repo/tsconfig": "0.0.1"
+    "@repo/tsconfig": "0.0.1",
+    "@repo/config-test": "0.0.1",
+    "@repo/config-eslint": "0.0.0"
   },
   "publishConfig": {
     "access": "public"

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.ts

@@ -5,7 +5,7 @@ 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'
@@ -26,9 +26,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.

package/src/document/documentStore.ts

@@ -60,6 +60,7 @@ import {
   type Grant,
 } from './permissions'
 import {ActionError} from './processActions/processActions'
+import {isReleaseAction} from './processActions/releaseUtil'
 import {
   type AppliedTransaction,
   applyFirstQueuedTransaction,
@@ -414,10 +415,11 @@ const subscribeToAppliedAndSubmitNextTransaction = ({
           outgoing,
         }))
 
-        // Any liveEdit action in the batch routes to the mutations API. For mixed batches
-        // non-liveEdit operations (e.g. publish) lose atomicity, but that is acceptable
-        // given how rare mixed batches are.
-        if (outgoing.actions.some((action) => action.liveEdit)) {
+        // liveEdit transactions route to the mutations API; everything else routes
+        // to the actions API. processActions rejects transactions that mix the two,
+        // and reducers won't batch across that boundary, so a batch is always
+        // entirely liveEdit or entirely not.
+        if (outgoing.actions.some((action) => !isReleaseAction(action) && action.liveEdit)) {
           return client.observable
             .mutate(outgoing.outgoingMutations as Mutation[], {
               transactionId: outgoing.transactionId,
@@ -430,7 +432,6 @@ const subscribeToAppliedAndSubmitNextTransaction = ({
             .pipe(revertOnError, toResult)
         }
 
-        // Pure non-liveEdit transactions use the actions API.
         return client.observable
           .action(outgoing.outgoingActions as Action[], {
             transactionId: outgoing.transactionId,

package/src/document/events.test.ts

@@ -1,6 +1,6 @@
 import {describe, expect, it} from 'vitest'
 
-import {type DocumentAction} from '../document/actions'
+import {type Action, type DocumentAction} from '../document/actions'
 import {type DocumentEvent, getDocumentEvents} from '../document/events'
 import {type OutgoingTransaction} from '../document/reducers'
 
@@ -41,11 +41,66 @@ describe('getDocumentEvents', () => {
     expect(events).toHaveLength(outgoing.actions.length)
     events.forEach((event) => {
       const action = outgoing.actions.find(
-        (a) => 'documentId' in event && event.documentId === a.documentId,
+        (a) => 'documentId' in a && 'documentId' in event && event.documentId === a.documentId,
       )
       expect(action).toBeDefined()
       expect(event.type).toEqual(expectedMap[action!.type])
       expect((event as Extract<DocumentEvent, {outgoing: unknown}>).outgoing).toBe(outgoing)
     })
   })
+
+  it('emits created/edited/deleted events for release.create/edit/delete with release doc IDs', () => {
+    const outgoing: OutgoingTransaction = {
+      transactionId: 'txn-release',
+      actions: [
+        {type: 'release.create', releaseId: 'r1'} as Action,
+        {type: 'release.edit', releaseId: 'r2', patch: {set: {}}} as Action,
+        {type: 'release.delete', releaseId: 'r3'} as Action,
+      ],
+      disableBatching: false,
+      batchedTransactionIds: [],
+      outgoingActions: [],
+      outgoingMutations: [],
+      base: {},
+      working: {},
+      previous: {},
+      previousRevs: {},
+      timestamp: '2025-02-06T00:00:00.000Z',
+    }
+
+    const events = getDocumentEvents(outgoing)
+    expect(events).toEqual([
+      {type: 'created', documentId: '_.releases.r1', outgoing},
+      {type: 'edited', documentId: '_.releases.r2', outgoing},
+      {type: 'deleted', documentId: '_.releases.r3', outgoing},
+    ])
+  })
+
+  it('skips release actions that have no local mutation (publish/schedule/archive/etc.)', () => {
+    const outgoing: OutgoingTransaction = {
+      transactionId: 'txn-release-noop',
+      actions: [
+        {type: 'release.publish', releaseId: 'r1'} as Action,
+        {
+          type: 'release.schedule',
+          releaseId: 'r2',
+          publishAt: '2026-01-01T00:00:00.000Z',
+        } as Action,
+        {type: 'release.unschedule', releaseId: 'r3'} as Action,
+        {type: 'release.archive', releaseId: 'r4'} as Action,
+        {type: 'release.unarchive', releaseId: 'r5'} as Action,
+      ],
+      disableBatching: false,
+      batchedTransactionIds: [],
+      outgoingActions: [],
+      outgoingMutations: [],
+      base: {},
+      working: {},
+      previous: {},
+      previousRevs: {},
+      timestamp: '2025-02-06T00:00:00.000Z',
+    }
+
+    expect(getDocumentEvents(outgoing)).toEqual([])
+  })
 })

package/src/document/events.ts

@@ -1,6 +1,7 @@
 import {type MultipleMutationResult, type SanityClient} from '@sanity/client'
 
-import {type DocumentAction} from './actions'
+import {type DocumentAction, type ReleaseAction} from './actions'
+import {getReleaseDocumentId, isReleaseAction} from './processActions/releaseUtil'
 import {type OutgoingTransaction} from './reducers'
 
 /** @beta Response body from submitting an outgoing transaction (actions or mutations API). */
@@ -118,31 +119,49 @@ export interface DocumentDiscardedEvent {
   outgoing: OutgoingTransaction
 }
 
-export function getDocumentEvents(outgoing: OutgoingTransaction): DocumentEvent[] {
-  const documentIdsByAction = Object.entries(
-    outgoing.actions.reduce(
-      (acc, {type, documentId}) => {
-        const ids = acc[type] || new Set()
-        if (documentId) ids.add(documentId)
-        acc[type] = ids
-        return acc
-      },
-      {} as Record<DocumentAction['type'], Set<string>>,
-    ),
-  ) as [DocumentAction['type'], Set<string>][]
+// Release actions that write a mutation to the local release doc map onto
+// the regular per-document events with `documentId = '_.releases.<releaseId>'`.
+// The other release actions (publish/schedule/unschedule/archive/unarchive)
+// don't mutate local state, so they aren't in the map and get skipped — they
+// surface through the transaction-level `accepted`/`reverted` events instead.
+const actionMap = {
+  'document.create': 'created',
+  'document.delete': 'deleted',
+  'document.discard': 'discarded',
+  'document.edit': 'edited',
+  'document.publish': 'published',
+  'document.unpublish': 'unpublished',
+  'release.create': 'created',
+  'release.edit': 'edited',
+  'release.delete': 'deleted',
+} satisfies Partial<Record<DocumentAction['type'] | ReleaseAction['type'], DocumentEvent['type']>>
+
+type MappedActionType = keyof typeof actionMap
 
-  const actionMap = {
-    'document.create': 'created',
-    'document.delete': 'deleted',
-    'document.discard': 'discarded',
-    'document.edit': 'edited',
-    'document.publish': 'published',
-    'document.unpublish': 'unpublished',
-  } satisfies Record<DocumentAction['type'], DocumentEvent['type']>
+export function getDocumentEvents(outgoing: OutgoingTransaction): DocumentEvent[] {
+  const documentIdsByAction = outgoing.actions.reduce(
+    (acc, action) => {
+      if (!(action.type in actionMap)) return acc
+      const documentId = isReleaseAction(action)
+        ? getReleaseDocumentId(action.releaseId)
+        : action.documentId
+      if (!documentId) return acc
+      const type = action.type as MappedActionType
+      const ids = acc[type] ?? new Set<string>()
+      ids.add(documentId)
+      acc[type] = ids
+      return acc
+    },
+    {} as Partial<Record<MappedActionType, Set<string>>>,
+  )
 
-  return documentIdsByAction.flatMap(([actionType, documentIds]) =>
-    Array.from(documentIds).map(
-      (documentId): DocumentEvent => ({type: actionMap[actionType], documentId, outgoing}),
+  return Object.entries(documentIdsByAction).flatMap(([actionType, documentIds]) =>
+    Array.from(documentIds ?? []).map(
+      (documentId): DocumentEvent => ({
+        type: actionMap[actionType as MappedActionType],
+        documentId,
+        outgoing,
+      }),
     ),
   )
 }