@sanity/sdk 2.11.0 → 2.12.0

package/src/document/processActions/releaseUtil.ts

@@ -0,0 +1,31 @@
+import {type Action, type ReleaseAction} from '../actions'
+
+/**
+ * Path prefix shared by every release document. Matches studio's
+ * `RELEASE_DOCUMENTS_PATH` constant.
+ */
+const RELEASE_DOCUMENTS_PATH = '_.releases'
+
+/**
+ * Returns the full release document ID for the given release name.
+ * e.g. `getReleaseDocumentId('my-release') === '_.releases.my-release'`
+ * @beta
+ */
+export function getReleaseDocumentId(releaseId: string): string {
+  return `${RELEASE_DOCUMENTS_PATH}.${releaseId}`
+}
+
+const RELEASE_ACTION_TYPES = new Set([
+  'release.create',
+  'release.edit',
+  'release.publish',
+  'release.schedule',
+  'release.unschedule',
+  'release.archive',
+  'release.unarchive',
+  'release.delete',
+])
+
+export function isReleaseAction(action: Action): action is ReleaseAction {
+  return RELEASE_ACTION_TYPES.has(action.type)
+}

package/src/document/processActions/shared.ts

@@ -0,0 +1,139 @@
+import {diffValue} from '@sanity/diff-patch'
+import {type Mutation, type PatchOperations, type SanityDocument} from '@sanity/types'
+import {evaluateSync, type ExprNode} from 'groq-js'
+
+import {type Grant} from '../permissions'
+import {type DocumentSet, processMutations} from '../processMutations'
+import {type HttpAction} from '../reducers'
+
+export interface ActionHandlerContext {
+  base: DocumentSet
+  working: DocumentSet
+  transactionId: string
+  timestamp: string
+  grants: Record<Grant, ExprNode>
+  outgoingActions: HttpAction[]
+  outgoingMutations: Mutation[]
+}
+
+export interface ActionHandlerResult {
+  base: DocumentSet
+  working: DocumentSet
+}
+
+export function checkGrant(grantExpr: ExprNode, document: SanityDocument): boolean {
+  const value = evaluateSync(grantExpr, {params: {document}})
+  return value.type === 'boolean' && value.data
+}
+
+interface ActionErrorOptions {
+  message: string
+  documentId: string
+  transactionId: string
+}
+
+/**
+ * Thrown when a precondition for an action failed.
+ */
+export class ActionError extends Error implements ActionErrorOptions {
+  documentId!: string
+  transactionId!: string
+
+  constructor(options: ActionErrorOptions) {
+    super(options.message)
+    Object.assign(this, options)
+  }
+}
+
+export class PermissionActionError extends ActionError {}
+
+interface ApplySingleDocPatchOptions {
+  base: DocumentSet
+  working: DocumentSet
+  documentId: string
+  patches: PatchOperations[] | undefined
+  transactionId: string
+  timestamp: string
+  grants: Record<Grant, ExprNode>
+  /**
+   * Error message thrown when the target document does not exist in either
+   * the base or working set.
+   */
+  notFoundMessage?: string
+  /**
+   * Error message thrown when the working document fails the `update` grant.
+   */
+  permissionMessage?: string
+}
+
+interface ApplySingleDocPatchResult {
+  base: DocumentSet
+  working: DocumentSet
+  /**
+   * Patch operations representing the minimal diff between base before and
+   * after the user's patches were applied. These are the patches that should
+   * be sent to the server (or applied to the working set as mutations).
+   */
+  diffedPatches: PatchOperations[]
+  /**
+   * Mutation envelopes for `diffedPatches` already keyed to `documentId`.
+   * Useful for callers that want to push them to `outgoingMutations`.
+   */
+  workingMutations: Mutation[]
+}
+
+/**
+ * Shared logic for applying user-provided patches to a single document that
+ * is identified by an exact ID (no draft/published wrapping). Used by the
+ * liveEdit branch of `document.edit` and by `release.edit`.
+ *
+ * Returns the updated base + working sets, plus the diffed patches in both
+ * raw and mutation form so the caller can decide what to send to the server.
+ */
+export function applySingleDocPatch({
+  base: initialBase,
+  working: initialWorking,
+  documentId,
+  patches,
+  transactionId,
+  timestamp,
+  grants,
+  notFoundMessage = 'Cannot edit document because it does not exist.',
+  permissionMessage = `You do not have permission to edit document "${documentId}".`,
+}: ApplySingleDocPatchOptions): ApplySingleDocPatchResult {
+  let base = initialBase
+  let working = initialWorking
+
+  const userPatches = patches?.map((patch) => ({patch: {id: documentId, ...patch}}))
+
+  if (!userPatches?.length) {
+    return {base, working, diffedPatches: [], workingMutations: []}
+  }
+
+  if (!working[documentId] || !base[documentId]) {
+    throw new ActionError({documentId, transactionId, message: notFoundMessage})
+  }
+
+  const baseBefore = base[documentId]
+  base = processMutations({documents: base, transactionId, mutations: userPatches, timestamp})
+  const baseAfter = base[documentId]
+  const diffedPatches = diffValue(baseBefore, baseAfter) as PatchOperations[]
+
+  const workingBefore = working[documentId] as SanityDocument
+  if (!checkGrant(grants.update, workingBefore)) {
+    throw new PermissionActionError({documentId, transactionId, message: permissionMessage})
+  }
+
+  const workingMutations: Mutation[] = diffedPatches.map((patch) => ({
+    patch: {id: documentId, ...patch},
+  }))
+
+  working = processMutations({
+    documents: working,
+    transactionId,
+    mutations: workingMutations,
+    timestamp,
+  })
+
+  return {base, working, diffedPatches, workingMutations}
+}

package/src/document/processActions/unpublish.ts

@@ -0,0 +1,85 @@
+import {DocumentId, getDraftId, getPublishedId} from '@sanity/id-utils'
+import {type Mutation, type SanityDocument} from '@sanity/types'
+
+import {isReleasePerspective} from '../../releases/utils/isReleasePerspective'
+import {type UnpublishDocumentAction} from '../actions'
+import {getId, processMutations} from '../processMutations'
+import {
+  ActionError,
+  type ActionHandlerContext,
+  type ActionHandlerResult,
+  checkGrant,
+  PermissionActionError,
+} from './shared'
+
+export function handleUnpublish(
+  action: UnpublishDocumentAction,
+  ctx: ActionHandlerContext,
+): ActionHandlerResult {
+  const {transactionId, timestamp, grants, outgoingActions, outgoingMutations} = ctx
+  let {base, working} = ctx
+
+  const documentId = getId(action.documentId)
+
+  if (action.liveEdit || isReleasePerspective(action.perspective)) {
+    throw new ActionError({
+      documentId,
+      transactionId,
+      message: `Cannot unpublish this document. Unpublishing is not supported for liveEdit or version (release) documents.`,
+    })
+  }
+
+  // Standard draft/published or version logic
+  const draftId = getDraftId(DocumentId(documentId))
+  const publishedId = getPublishedId(DocumentId(documentId))
+
+  if (!working[publishedId] && !base[publishedId]) {
+    throw new ActionError({
+      documentId,
+      transactionId,
+      message: `Cannot unpublish because the document "${documentId}" is not currently published.`,
+    })
+  }
+
+  const sourceDoc = working[publishedId] ?? (base[publishedId] as SanityDocument)
+  const newDraftFromPublished = {...sourceDoc, _id: draftId}
+  const mutations: Mutation[] = [
+    {delete: {id: publishedId}},
+    {createIfNotExists: newDraftFromPublished},
+  ]
+
+  if (!checkGrant(grants.update, sourceDoc)) {
+    throw new PermissionActionError({
+      documentId,
+      transactionId,
+      message: `You do not have permission to unpublish the document "${documentId}".`,
+    })
+  }
+
+  if (!working[draftId] && !checkGrant(grants.create, newDraftFromPublished)) {
+    throw new PermissionActionError({
+      documentId,
+      transactionId,
+      message: `You do not have permission to create a draft from the published version of "${documentId}".`,
+    })
+  }
+
+  base = processMutations({
+    documents: base,
+    transactionId,
+    mutations: [
+      {delete: {id: publishedId}},
+      {createIfNotExists: {...(base[publishedId] ?? sourceDoc), _id: draftId}},
+    ],
+    timestamp,
+  })
+  working = processMutations({documents: working, transactionId, mutations, timestamp})
+
+  outgoingMutations.push(...mutations)
+  outgoingActions.push({
+    actionType: 'sanity.action.document.unpublish',
+    draftId,
+    publishedId,
+  })
+  return {base, working}
+}

package/src/document/processActions.test.ts

@@ -2,8 +2,8 @@ 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 {ActionError, processActions} from './processActions'
+import {type Action, type DocumentAction} from './actions'
+import {ActionError, processActions} from './processActions/processActions'
 import {type DocumentSet} from './processMutations'
 
 // Helper: Create a sample document that conforms to SanityDocument.
@@ -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/)
+      })
+    })
+  })
 })