@sanity/sdk 2.11.1 → 2.13.0

package/src/document/processActions/unpublish.ts

@@ -16,7 +16,7 @@ export function handleUnpublish(
   action: UnpublishDocumentAction,
   ctx: ActionHandlerContext,
 ): ActionHandlerResult {
-  const {transactionId, timestamp, grants, outgoingActions, outgoingMutations} = ctx
+  const {transactionId, timestamp, grants, identity, outgoingActions, outgoingMutations} = ctx
   let {base, working} = ctx
 
   const documentId = getId(action.documentId)
@@ -48,7 +48,7 @@ export function handleUnpublish(
     {createIfNotExists: newDraftFromPublished},
   ]
 
-  if (!checkGrant(grants.update, sourceDoc)) {
+  if (!checkGrant(grants.update, sourceDoc, identity)) {
     throw new PermissionActionError({
       documentId,
       transactionId,
@@ -56,7 +56,7 @@ export function handleUnpublish(
     })
   }
 
-  if (!working[draftId] && !checkGrant(grants.create, newDraftFromPublished)) {
+  if (!working[draftId] && !checkGrant(grants.create, newDraftFromPublished, identity)) {
     throw new PermissionActionError({
       documentId,
       transactionId,

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,18 +7,19 @@ 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']>> = {}
 
 export type SyncTransactionState = Pick<
   DocumentStoreState,
-  'queued' | 'applied' | 'documentStates' | 'outgoing' | 'grants'
+  'queued' | 'applied' | 'documentStates' | 'outgoing' | 'grants' | 'identity'
 >
 
 type DocumentHandleLike = Pick<DocumentHandle, 'perspective'> & {
@@ -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.
@@ -203,6 +232,7 @@ export function applyFirstQueuedTransaction(prev: SyncTransactionState): SyncTra
     base: working,
     timestamp,
     grants: prev.grants,
+    identity: prev.identity,
   })
   const applied: AppliedTransaction = {
     ...queued,
@@ -272,7 +302,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,
@@ -368,7 +400,7 @@ export function revertOutgoingTransaction(prev: SyncTransactionState): SyncTrans
 
   for (const t of prev.applied) {
     try {
-      const next = processActions({...t, working, grants: prev.grants})
+      const next = processActions({...t, working, grants: prev.grants, identity: prev.identity})
       working = next.working
       nextApplied.push({...t, ...next})
     } catch (error) {
@@ -475,7 +507,7 @@ export function applyRemoteDocument(
   // transaction again through the listener and this same flow will run then
   for (const curr of prev.applied) {
     try {
-      const next = processActions({...curr, working, grants: prev.grants})
+      const next = processActions({...curr, working, grants: prev.grants, identity: prev.identity})
       working = next.working
       // next includes an updated `previous` set and `working` set and updates
       // the `outgoingAction` and `outgoingMutations`. the `base` set from the
@@ -586,9 +618,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) {