@sanity/sdk 2.11.1 → 2.12.0

package/src/document/processActions.test.ts

@@ -2,7 +2,7 @@ import {type CreateMutation, type Reference, type SanityDocument} from '@sanity/
 import {parse} from 'groq-js'
 import {describe, expect, it} from 'vitest'
 
-import {type DocumentAction} from './actions'
+import {type Action, type DocumentAction} from './actions'
 import {ActionError, processActions} from './processActions/processActions'
 import {type DocumentSet} from './processMutations'
 
@@ -1420,4 +1420,426 @@ describe('processActions', () => {
       })
     })
   })
+
+  describe('release actions', () => {
+    const releaseName = 'my-release'
+    const releaseDocId = `_.releases.${releaseName}`
+
+    const createReleaseDoc = (overrides: Partial<SanityDocument> = {}): SanityDocument => ({
+      _id: releaseDocId,
+      _type: 'system.release',
+      _createdAt: '2025-01-01T00:00:00.000Z',
+      _updatedAt: '2025-01-01T00:00:00.000Z',
+      _rev: 'initial',
+      name: releaseName,
+      state: 'active',
+      metadata: {releaseType: 'undecided'},
+      ...overrides,
+    })
+
+    describe('release.create', () => {
+      it('inserts an optimistic release doc and emits a release.create action', () => {
+        const base: DocumentSet = {}
+        const working: DocumentSet = {}
+        const actions: Action[] = [
+          {
+            type: 'release.create',
+            releaseId: releaseName,
+            metadata: {title: 'My release', releaseType: 'asap'},
+          },
+        ]
+
+        const result = processActions({
+          actions,
+          transactionId,
+          base,
+          working,
+          timestamp,
+          grants: defaultGrants,
+        })
+
+        const doc = result.working[releaseDocId]
+        expect(doc).toBeDefined()
+        expect(doc?._type).toBe('system.release')
+        expect(doc?.['name']).toBe(releaseName)
+        expect(doc?.['state']).toBe('active')
+        expect(doc?.['metadata']).toEqual({title: 'My release', releaseType: 'asap'})
+
+        expect(result.outgoingActions).toEqual([
+          {
+            actionType: 'sanity.action.release.create',
+            releaseId: releaseName,
+            metadata: {title: 'My release', releaseType: 'asap'},
+          },
+        ])
+      })
+
+      it('throws if the release already exists in base or working', () => {
+        const existing = createReleaseDoc()
+        expect(() =>
+          processActions({
+            actions: [
+              {
+                type: 'release.create',
+                releaseId: releaseName,
+                metadata: {releaseType: 'undecided'},
+              },
+            ],
+            transactionId,
+            base: {[releaseDocId]: existing},
+            working: {[releaseDocId]: existing},
+            timestamp,
+            grants: defaultGrants,
+          }),
+        ).toThrow(/already exists/)
+      })
+
+      it('throws PermissionActionError when the create grant is denied', () => {
+        expect(() =>
+          processActions({
+            actions: [
+              {
+                type: 'release.create',
+                releaseId: releaseName,
+                metadata: {releaseType: 'undecided'},
+              },
+            ],
+            transactionId,
+            base: {},
+            working: {},
+            timestamp,
+            grants: {...defaultGrants, create: alwaysDeny},
+          }),
+        ).toThrow(/permission to create release/)
+      })
+    })
+
+    describe('release.edit', () => {
+      it('applies the patch optimistically and forwards the original patch to the outgoing action', () => {
+        const existing = createReleaseDoc({
+          metadata: {releaseType: 'undecided'},
+        } as Partial<SanityDocument>)
+        const patch = {set: {'metadata.title': 'Updated title'}}
+
+        const result = processActions({
+          actions: [{type: 'release.edit', releaseId: releaseName, patch}],
+          transactionId,
+          base: {[releaseDocId]: existing},
+          working: {[releaseDocId]: existing},
+          timestamp,
+          grants: defaultGrants,
+        })
+
+        const updated = result.working[releaseDocId] as SanityDocument & {
+          metadata: {title?: string; releaseType: string}
+        }
+        expect(updated.metadata.title).toBe('Updated title')
+        // releaseType wasn't unset
+        expect(updated.metadata.releaseType).toBe('undecided')
+
+        expect(result.outgoingActions).toEqual([
+          {
+            actionType: 'sanity.action.release.edit',
+            releaseId: releaseName,
+            patch,
+          },
+        ])
+      })
+
+      it('throws when editing a release that does not exist', () => {
+        expect(() =>
+          processActions({
+            actions: [
+              {
+                type: 'release.edit',
+                releaseId: releaseName,
+                patch: {set: {'metadata.title': 'x'}},
+              },
+            ],
+            transactionId,
+            base: {},
+            working: {},
+            timestamp,
+            grants: defaultGrants,
+          }),
+        ).toThrow(/does not exist/)
+      })
+
+      it('throws PermissionActionError when the working release fails the update grant', () => {
+        const existing = createReleaseDoc()
+        expect(() =>
+          processActions({
+            actions: [
+              {
+                type: 'release.edit',
+                releaseId: releaseName,
+                patch: {set: {'metadata.title': 'x'}},
+              },
+            ],
+            transactionId,
+            base: {[releaseDocId]: existing},
+            working: {[releaseDocId]: existing},
+            timestamp,
+            grants: {...defaultGrants, update: alwaysDeny},
+          }),
+        ).toThrow(/permission to edit release/)
+      })
+    })
+
+    describe('fire-and-forget actions', () => {
+      const existing = createReleaseDoc()
+      const cases: Array<{
+        name: string
+        action: Action
+        expectedOutgoing: Record<string, unknown>
+      }> = [
+        {
+          name: 'release.publish',
+          action: {type: 'release.publish', releaseId: releaseName},
+          expectedOutgoing: {actionType: 'sanity.action.release.publish', releaseId: releaseName},
+        },
+        {
+          name: 'release.schedule',
+          action: {
+            type: 'release.schedule',
+            releaseId: releaseName,
+            publishAt: '2026-01-01T00:00:00.000Z',
+          },
+          expectedOutgoing: {
+            actionType: 'sanity.action.release.schedule',
+            releaseId: releaseName,
+            publishAt: '2026-01-01T00:00:00.000Z',
+          },
+        },
+        {
+          name: 'release.unschedule',
+          action: {type: 'release.unschedule', releaseId: releaseName},
+          expectedOutgoing: {
+            actionType: 'sanity.action.release.unschedule',
+            releaseId: releaseName,
+          },
+        },
+        {
+          name: 'release.archive',
+          action: {type: 'release.archive', releaseId: releaseName},
+          expectedOutgoing: {actionType: 'sanity.action.release.archive', releaseId: releaseName},
+        },
+        {
+          name: 'release.unarchive',
+          action: {type: 'release.unarchive', releaseId: releaseName},
+          expectedOutgoing: {actionType: 'sanity.action.release.unarchive', releaseId: releaseName},
+        },
+      ]
+
+      it.each(cases)(
+        '$name does not mutate local state and emits the matching outgoing action',
+        ({action, expectedOutgoing}) => {
+          const base: DocumentSet = {[releaseDocId]: existing}
+          const working: DocumentSet = {[releaseDocId]: existing}
+
+          const result = processActions({
+            actions: [action],
+            transactionId,
+            base,
+            working,
+            timestamp,
+            grants: defaultGrants,
+          })
+
+          // working and base reference the same doc instance — no optimistic
+          // mutation was applied
+          expect(result.working[releaseDocId]).toBe(existing)
+          expect(result.outgoingActions).toEqual([expectedOutgoing])
+          expect(result.outgoingMutations).toEqual([])
+        },
+      )
+
+      it.each(cases)('$name throws if the release does not exist', ({action}) => {
+        expect(() =>
+          processActions({
+            actions: [action],
+            transactionId,
+            base: {},
+            working: {},
+            timestamp,
+            grants: defaultGrants,
+          }),
+        ).toThrow(ActionError)
+      })
+
+      it.each(cases)(
+        '$name throws PermissionActionError when update grant is denied',
+        ({action}) => {
+          const base: DocumentSet = {[releaseDocId]: existing}
+          const working: DocumentSet = {[releaseDocId]: existing}
+          expect(() =>
+            processActions({
+              actions: [action],
+              transactionId,
+              base,
+              working,
+              timestamp,
+              grants: {...defaultGrants, update: alwaysDeny},
+            }),
+          ).toThrow(/permission to/)
+        },
+      )
+    })
+
+    describe('release.schedule publishAt validation', () => {
+      const existing = createReleaseDoc()
+
+      it.each(['not-a-date', '', '2026-13-40T99:99:99Z'])(
+        'throws ActionError when publishAt is not a valid timestamp (%s)',
+        (publishAt) => {
+          expect(() =>
+            processActions({
+              actions: [{type: 'release.schedule', releaseId: releaseName, publishAt}],
+              transactionId,
+              base: {[releaseDocId]: existing},
+              working: {[releaseDocId]: existing},
+              timestamp,
+              grants: defaultGrants,
+            }),
+          ).toThrow(/must be a valid ISO 8601 timestamp/)
+        },
+      )
+    })
+
+    describe('release.delete', () => {
+      it.each(['archived', 'published'] as const)(
+        'optimistically removes the local release when state is %s',
+        (state) => {
+          const existing = createReleaseDoc({state} as Partial<SanityDocument>)
+          const result = processActions({
+            actions: [{type: 'release.delete', releaseId: releaseName}],
+            transactionId,
+            base: {[releaseDocId]: existing},
+            working: {[releaseDocId]: existing},
+            timestamp,
+            grants: defaultGrants,
+          })
+
+          // processMutations sets deleted entries to null
+          expect(result.working[releaseDocId]).toBeNull()
+          expect(result.outgoingMutations).toEqual([{delete: {id: releaseDocId}}])
+          expect(result.outgoingActions).toEqual([
+            {actionType: 'sanity.action.release.delete', releaseId: releaseName},
+          ])
+        },
+      )
+
+      it.each(['active', 'scheduled', 'archiving', 'publishing'] as const)(
+        'throws when state is %s (server only accepts archived/published)',
+        (state) => {
+          const existing = createReleaseDoc({state} as Partial<SanityDocument>)
+          expect(() =>
+            processActions({
+              actions: [{type: 'release.delete', releaseId: releaseName}],
+              transactionId,
+              base: {[releaseDocId]: existing},
+              working: {[releaseDocId]: existing},
+              timestamp,
+              grants: defaultGrants,
+            }),
+          ).toThrow(/Archive it first/)
+        },
+      )
+
+      it('throws if the release does not exist', () => {
+        expect(() =>
+          processActions({
+            actions: [{type: 'release.delete', releaseId: releaseName}],
+            transactionId,
+            base: {},
+            working: {},
+            timestamp,
+            grants: defaultGrants,
+          }),
+        ).toThrow(/does not exist/)
+      })
+
+      it('throws PermissionActionError when the update grant is denied', () => {
+        const existing = createReleaseDoc({state: 'archived'} as Partial<SanityDocument>)
+        expect(() =>
+          processActions({
+            actions: [{type: 'release.delete', releaseId: releaseName}],
+            transactionId,
+            base: {[releaseDocId]: existing},
+            working: {[releaseDocId]: existing},
+            timestamp,
+            grants: {...defaultGrants, update: alwaysDeny},
+          }),
+        ).toThrow(/permission to delete release/)
+      })
+    })
+
+    describe('mixed with liveEdit document actions', () => {
+      const liveEditDocId = 'live-edit-doc'
+      const liveEditDoc = {
+        _id: liveEditDocId,
+        _type: 'liveEditType',
+        _createdAt: '2025-01-01T00:00:00.000Z',
+        _updatedAt: '2025-01-01T00:00:00.000Z',
+        _rev: 'initial',
+      }
+      const liveEditAction = {
+        type: 'document.edit',
+        documentId: liveEditDocId,
+        documentType: 'liveEditType',
+        liveEdit: true,
+        patches: [{set: {title: 'x'}}],
+      } as const
+
+      it('throws ActionError when a transaction mixes a release action with a liveEdit document action', () => {
+        expect(() =>
+          processActions({
+            actions: [
+              {
+                type: 'release.create',
+                releaseId: releaseName,
+                metadata: {releaseType: 'undecided'},
+              },
+              liveEditAction as unknown as Action,
+            ],
+            transactionId,
+            base: {[liveEditDocId]: liveEditDoc},
+            working: {[liveEditDocId]: liveEditDoc},
+            timestamp,
+            grants: defaultGrants,
+          }),
+        ).toThrow(/Cannot combine liveEdit document actions with other actions/)
+      })
+
+      it('throws ActionError when a transaction mixes a non-liveEdit document action with a liveEdit document action', () => {
+        const otherDocId = 'other-doc'
+        const otherDoc = {
+          _id: otherDocId,
+          _type: 'someType',
+          _createdAt: '2025-01-01T00:00:00.000Z',
+          _updatedAt: '2025-01-01T00:00:00.000Z',
+          _rev: 'initial',
+        } as SanityDocument
+
+        expect(() =>
+          processActions({
+            actions: [
+              {
+                type: 'document.edit',
+                documentId: otherDocId,
+                documentType: 'someType',
+                patches: [{set: {title: 'y'}}],
+              },
+              liveEditAction as unknown as Action,
+            ],
+            transactionId,
+            base: {[liveEditDocId]: liveEditDoc, [otherDocId]: otherDoc},
+            working: {[liveEditDocId]: liveEditDoc, [otherDocId]: otherDoc},
+            timestamp,
+            grants: defaultGrants,
+          }),
+        ).toThrow(/Cannot combine liveEdit document actions with other actions/)
+      })
+    })
+  })
 })

package/src/document/reducers.ts

@@ -7,11 +7,12 @@ import {type StoreContext} from '../store/defineStore'
 import {insecureRandomId} from '../utils/ids'
 import {omitProperty} from '../utils/object'
 import {setCleanupTimeout} from '../utils/setCleanupTimeout'
-import {type DocumentAction} from './actions'
+import {type Action} from './actions'
 import {DOCUMENT_STATE_CLEAR_DELAY} from './documentConstants'
 import {type DocumentState, type DocumentStoreState} from './documentStore'
 import {type RemoteDocument} from './listen'
 import {ActionError, processActions} from './processActions/processActions'
+import {getReleaseDocumentId, isReleaseAction} from './processActions/releaseUtil'
 import {type DocumentSet} from './processMutations'
 
 const EMPTY_REVISIONS: NonNullable<Required<DocumentState['unverifiedRevisions']>> = {}
@@ -33,6 +34,14 @@ type ActionMap = {
   delete: 'sanity.action.document.delete'
   edit: 'sanity.action.document.edit'
   publish: 'sanity.action.document.publish'
+  releaseCreate: 'sanity.action.release.create'
+  releaseEdit: 'sanity.action.release.edit'
+  releasePublish: 'sanity.action.release.publish'
+  releaseSchedule: 'sanity.action.release.schedule'
+  releaseUnschedule: 'sanity.action.release.unschedule'
+  releaseArchive: 'sanity.action.release.archive'
+  releaseUnarchive: 'sanity.action.release.unarchive'
+  releaseDelete: 'sanity.action.release.delete'
 }
 
 type OptimisticLock = {
@@ -40,6 +49,14 @@ type OptimisticLock = {
   ifPublishedRevisionId?: string
 }
 
+interface ReleaseMetadataPayload {
+  title?: string
+  description?: string
+  intendedPublishAt?: string
+  releaseType?: 'asap' | 'scheduled' | 'undecided'
+  cardinality?: 'one' | 'many'
+}
+
 export type HttpAction =
   | {actionType: ActionMap['create']; publishedId: string; attributes: SanityDocumentLike}
   | {actionType: ActionMap['discard']; versionId: string; purge?: boolean}
@@ -47,6 +64,18 @@ export type HttpAction =
   | {actionType: ActionMap['delete']; publishedId: string; includeDrafts?: string[]}
   | {actionType: ActionMap['edit']; draftId: string; publishedId: string; patch: PatchOperations}
   | ({actionType: ActionMap['publish']; draftId: string; publishedId: string} & OptimisticLock)
+  | {
+      actionType: ActionMap['releaseCreate']
+      releaseId: string
+      metadata?: ReleaseMetadataPayload
+    }
+  | {actionType: ActionMap['releaseEdit']; releaseId: string; patch: PatchOperations}
+  | {actionType: ActionMap['releasePublish']; releaseId: string}
+  | {actionType: ActionMap['releaseSchedule']; releaseId: string; publishAt: string}
+  | {actionType: ActionMap['releaseUnschedule']; releaseId: string}
+  | {actionType: ActionMap['releaseArchive']; releaseId: string}
+  | {actionType: ActionMap['releaseUnarchive']; releaseId: string}
+  | {actionType: ActionMap['releaseDelete']; releaseId: string}
 
 /**
  * Represents a transaction that is queued to be applied but has not yet been
@@ -63,7 +92,7 @@ export interface QueuedTransaction {
    * actions don't mention draft IDs and is meant to abstract away the draft
    * model from users.
    */
-  actions: DocumentAction[]
+  actions: Action[]
   /**
    * An optional flag set to disable this transaction from being batched with
    * other transactions.
@@ -272,7 +301,9 @@ export function batchAppliedTransactions([curr, ...rest]: AppliedTransaction[]):
   if (next.disableBatching) return editAction
 
   // Don't batch a liveEdit edit with a non-liveEdit edit — they route to different APIs
-  if (!!action.liveEdit !== !!next.actions[0]?.liveEdit) return editAction
+  const nextFirst = next.actions[0]
+  const nextLiveEdit = nextFirst && 'liveEdit' in nextFirst ? nextFirst.liveEdit : false
+  if (!!action.liveEdit !== !!nextLiveEdit) return editAction
 
   return {
     disableBatching: false,
@@ -586,9 +617,13 @@ export function manageSubscriberIds(
 
 // document handles are passed in via the public facing API, but we also need to
 // pull the correct document ids from action bodies, which have similar but not
-// identical shapes to the document handles.
-function getDocumentIdsFromHandleLikes(handles: DocumentHandleLike[]): string[] {
+// identical shapes to the document handles. release actions also flow through
+// here, and resolve to the underlying release document id.
+function getDocumentIdsFromHandleLikes(handles: (DocumentHandleLike | Action)[]): string[] {
   return handles.flatMap((handle) => {
+    if ('type' in handle && isReleaseAction(handle)) {
+      return [getReleaseDocumentId(handle.releaseId)]
+    }
     const idsForDocument = []
     if (!handle.documentId) return []
     if (handle.liveEdit) {

package/src/releases/getPerspectiveState.test.ts

@@ -1,3 +1,4 @@
+import {type ReleaseDocument} from '@sanity/client'
 import {filter, firstValueFrom, of, Subject, take} from 'rxjs'
 import {describe, expect, it, vi} from 'vitest'
 
@@ -6,7 +7,6 @@ import {getQueryState} from '../query/queryStore'
 import {createSanityInstance, type SanityInstance} from '../store/createSanityInstance'
 import {type StateSource} from '../store/createStateSourceAction'
 import {getPerspectiveState} from './getPerspectiveState'
-import {type ReleaseDocument} from './releasesStore'
 
 vi.mock('../query/queryStore')
 

package/src/releases/releasesStore.test.ts

@@ -1,10 +1,11 @@
+import {type ReleaseDocument} from '@sanity/client'
 import {NEVER, Observable, type Observer, of, Subject} from 'rxjs'
 import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
 
 import {getQueryState, resolveQuery} from '../query/queryStore'
 import {createSanityInstance, type SanityInstance} from '../store/createSanityInstance'
 import {type StateSource} from '../store/createStateSourceAction'
-import {getActiveReleasesState, type ReleaseDocument} from './releasesStore'
+import {getActiveReleasesState, getAllReleasesState} from './releasesStore'
 
 // Mock dependencies
 vi.mock('../query/queryStore')
@@ -167,6 +168,54 @@ describe('releasesStore', () => {
     expect(state.getCurrent()).toEqual([])
   })
 
+  it('exposes archived/published releases through getAllReleasesState but filters them out of getActiveReleasesState', async () => {
+    const subject = new Subject<ReleaseDocument[]>()
+    vi.mocked(getQueryState).mockReturnValue({
+      subscribe: () => () => {},
+      getCurrent: () => undefined,
+      observable: subject.asObservable(),
+    } as StateSource<ReleaseDocument[] | undefined>)
+
+    const active = getActiveReleasesState(instance, {
+      resource: {projectId: 'test', dataset: 'test'},
+    })
+    const all = getAllReleasesState(instance, {resource: {projectId: 'test', dataset: 'test'}})
+
+    const releases: ReleaseDocument[] = [
+      {
+        _id: 'r-active',
+        _type: 'system.release',
+        name: 'r-active',
+        state: 'active',
+        metadata: {releaseType: 'asap'},
+      } as ReleaseDocument,
+      {
+        _id: 'r-archived',
+        _type: 'system.release',
+        name: 'r-archived',
+        state: 'archived',
+        metadata: {releaseType: 'asap'},
+      } as ReleaseDocument,
+      {
+        _id: 'r-published',
+        _type: 'system.release',
+        name: 'r-published',
+        state: 'published',
+        metadata: {releaseType: 'asap'},
+      } as ReleaseDocument,
+    ]
+
+    subject.next(releases)
+    await new Promise((resolve) => setTimeout(resolve, 0))
+
+    const activeNames = active.getCurrent()?.map((r) => r.name) ?? []
+    const allNames = all.getCurrent()?.map((r) => r.name) ?? []
+
+    expect(activeNames).toEqual(['r-active'])
+    expect(allNames).toEqual(expect.arrayContaining(['r-active', 'r-archived', 'r-published']))
+    expect(allNames).toHaveLength(3)
+  })
+
   it('should not crash when the releases query errors', async () => {
     const subject = new Subject<ReleaseDocument[]>()
     vi.mocked(getQueryState).mockReturnValue({