@sanity/sdk 2.11.0 → 2.12.0

package/src/document/documentStore.ts

@@ -59,7 +59,8 @@ import {
   type DocumentPermissionsResult,
   type Grant,
 } from './permissions'
-import {ActionError} from './processActions'
+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,
+      }),
     ),
   )
 }

package/src/document/permissions.ts

@@ -7,7 +7,7 @@ import {isReleasePerspective} from '../releases/utils/isReleasePerspective'
 import {type SelectorContext} from '../store/createStateSourceAction'
 import {MultiKeyWeakMap} from '../utils/MultiKeyWeakMap'
 import {type DocumentAction} from './actions'
-import {ActionError, PermissionActionError, processActions} from './processActions'
+import {ActionError, PermissionActionError, processActions} from './processActions/processActions'
 import {type DocumentSet} from './processMutations'
 import {type SyncTransactionState} from './reducers'
 

package/src/document/processActions/create.ts

@@ -0,0 +1,135 @@
+import {DocumentId, getDraftId, getPublishedId, getVersionId} from '@sanity/id-utils'
+import {type Mutation, type SanityDocument} from '@sanity/types'
+
+import {isReleasePerspective} from '../../releases/utils/isReleasePerspective'
+import {type CreateDocumentAction} from '../actions'
+import {getId, processMutations} from '../processMutations'
+import {
+  ActionError,
+  type ActionHandlerContext,
+  type ActionHandlerResult,
+  checkGrant,
+  PermissionActionError,
+} from './shared'
+
+export function handleCreate(
+  action: CreateDocumentAction,
+  ctx: ActionHandlerContext,
+): ActionHandlerResult {
+  const {transactionId, timestamp, grants, outgoingActions, outgoingMutations} = ctx
+  let {base, working} = ctx
+
+  const documentId = getId(action.documentId)
+
+  if (action.liveEdit) {
+    if (working[documentId]) {
+      throw new ActionError({
+        documentId,
+        transactionId,
+        message: `This document already exists.`,
+      })
+    }
+
+    const newDocBase = {_type: action.documentType, _id: documentId, ...action.initialValue}
+    const newDocWorking = {
+      _type: action.documentType,
+      _id: documentId,
+      ...action.initialValue,
+    }
+    const mutations: Mutation[] = [{create: newDocWorking}]
+
+    base = processMutations({
+      documents: base,
+      transactionId,
+      mutations: [{create: newDocBase}],
+      timestamp,
+    })
+    working = processMutations({
+      documents: working,
+      transactionId,
+      mutations,
+      timestamp,
+    })
+
+    if (!checkGrant(grants.create, working[documentId] as SanityDocument)) {
+      throw new PermissionActionError({
+        documentId,
+        transactionId,
+        message: `You do not have permission to create document "${documentId}".`,
+      })
+    }
+
+    // liveEdit documents use the mutation endpoint directly -- we don't send actions
+    outgoingMutations.push(...mutations)
+    return {base, working}
+  }
+
+  // Standard draft/published/version logic
+  const versionId = isReleasePerspective(action.perspective)
+    ? getVersionId(DocumentId(documentId), action.perspective.releaseName)
+    : undefined
+  const draftId = getDraftId(DocumentId(documentId))
+  const publishedId = getPublishedId(DocumentId(documentId))
+
+  const alreadyHasVersion = versionId ? working[versionId] : working[draftId]
+
+  if (alreadyHasVersion) {
+    const errorDocType = versionId ? 'release version' : 'draft'
+    throw new ActionError({
+      documentId,
+      transactionId,
+      message: `A ${errorDocType} of this document already exists. Please use or discard the existing ${errorDocType} before creating a new one.`,
+    })
+  }
+
+  // Spread the (possibly undefined) draft or published version directly.
+  // (studio uses the draft version as a base if you are in a release perspective)
+  const newDocBase = {
+    ...(base[draftId] ?? base[publishedId]),
+    _type: action.documentType,
+    _id: versionId ?? draftId,
+    ...action.initialValue,
+  }
+  const newDocWorking = {
+    ...(working[draftId] ?? working[publishedId]),
+    _type: action.documentType,
+    _id: versionId ?? draftId,
+    ...action.initialValue,
+  }
+  const mutations: Mutation[] = [{create: newDocWorking}]
+
+  base = processMutations({
+    documents: base,
+    transactionId,
+    mutations: [{create: newDocBase}],
+    timestamp,
+  })
+  working = processMutations({
+    documents: working,
+    transactionId,
+    mutations,
+    timestamp,
+  })
+
+  if (versionId && !checkGrant(grants.create, working[versionId] as SanityDocument)) {
+    throw new PermissionActionError({
+      documentId,
+      transactionId,
+      message: `You do not have permission to create a release version for document "${documentId}".`,
+    })
+  } else if (!versionId && !checkGrant(grants.create, working[draftId] as SanityDocument)) {
+    throw new PermissionActionError({
+      documentId,
+      transactionId,
+      message: `You do not have permission to create a draft for document "${documentId}".`,
+    })
+  }
+
+  outgoingMutations.push(...mutations)
+  outgoingActions.push({
+    actionType: 'sanity.action.document.version.create',
+    publishedId,
+    attributes: newDocWorking,
+  })
+  return {base, working}
+}

package/src/document/processActions/delete.ts

@@ -0,0 +1,100 @@
+import {DocumentId, getDraftId, getPublishedId} from '@sanity/id-utils'
+import {type Mutation} from '@sanity/types'
+
+import {isReleasePerspective} from '../../releases/utils/isReleasePerspective'
+import {type DeleteDocumentAction} from '../actions'
+import {processMutations} from '../processMutations'
+import {
+  ActionError,
+  type ActionHandlerContext,
+  type ActionHandlerResult,
+  checkGrant,
+  PermissionActionError,
+} from './shared'
+
+export function handleDelete(
+  action: DeleteDocumentAction,
+  ctx: ActionHandlerContext,
+): ActionHandlerResult {
+  const {transactionId, timestamp, grants, outgoingActions, outgoingMutations} = ctx
+  let {base, working} = ctx
+
+  const documentId = action.documentId
+
+  if (isReleasePerspective(action.perspective)) {
+    throw new ActionError({
+      documentId,
+      transactionId,
+      message: `Cannot delete a version document. You may want to use the "unpublish" or "discard" actions instead.`,
+    })
+  }
+
+  if (action.liveEdit) {
+    if (!working[documentId]) {
+      throw new ActionError({
+        documentId,
+        transactionId,
+        message: 'The document you are trying to delete does not exist.',
+      })
+    }
+
+    if (!checkGrant(grants.update, working[documentId])) {
+      throw new PermissionActionError({
+        documentId,
+        transactionId,
+        message: `You do not have permission to delete this document.`,
+      })
+    }
+
+    const mutations: Mutation[] = [{delete: {id: documentId}}]
+
+    base = processMutations({documents: base, transactionId, mutations, timestamp})
+    working = processMutations({documents: working, transactionId, mutations, timestamp})
+
+    // although liveEdit documents can use the actions API for deletion,
+    // having this be an action while other operations are mutations creates an inconsistency
+    // (and a possible race condition in document store where mutations might get skipped)
+    outgoingMutations.push(...mutations)
+    return {base, working}
+  }
+
+  // Standard draft/published logic
+  const draftId = getDraftId(DocumentId(documentId))
+  const publishedId = getPublishedId(DocumentId(documentId))
+
+  if (!working[publishedId]) {
+    throw new ActionError({
+      documentId,
+      transactionId,
+      message: working[draftId]
+        ? 'Cannot delete a document without a published version.'
+        : 'The document you are trying to delete does not exist.',
+    })
+  }
+
+  const cantDeleteDraft = working[draftId] && !checkGrant(grants.update, working[draftId])
+  const cantDeletePublished =
+    working[publishedId] && !checkGrant(grants.update, working[publishedId])
+
+  if (cantDeleteDraft || cantDeletePublished) {
+    throw new PermissionActionError({
+      documentId,
+      transactionId,
+      message: `You do not have permission to delete this document.`,
+    })
+  }
+
+  const mutations: Mutation[] = [{delete: {id: publishedId}}, {delete: {id: draftId}}]
+  const includeDrafts = working[draftId] ? [draftId] : undefined
+
+  base = processMutations({documents: base, transactionId, mutations, timestamp})
+  working = processMutations({documents: working, transactionId, mutations, timestamp})
+
+  outgoingMutations.push(...mutations)
+  outgoingActions.push({
+    actionType: 'sanity.action.document.delete',
+    publishedId,
+    ...(includeDrafts ? {includeDrafts} : {}),
+  })
+  return {base, working}
+}

package/src/document/processActions/discard.ts

@@ -0,0 +1,63 @@
+import {DocumentId, getDraftId, getVersionId} from '@sanity/id-utils'
+import {type Mutation} from '@sanity/types'
+
+import {isReleasePerspective} from '../../releases/utils/isReleasePerspective'
+import {type DiscardDocumentAction} from '../actions'
+import {getId, processMutations} from '../processMutations'
+import {
+  ActionError,
+  type ActionHandlerContext,
+  type ActionHandlerResult,
+  checkGrant,
+  PermissionActionError,
+} from './shared'
+
+export function handleDiscard(
+  action: DiscardDocumentAction,
+  ctx: ActionHandlerContext,
+): ActionHandlerResult {
+  const {transactionId, timestamp, grants, outgoingActions, outgoingMutations} = ctx
+  let {base, working} = ctx
+
+  const documentId = getId(action.documentId)
+
+  if (action.liveEdit) {
+    throw new ActionError({
+      documentId,
+      transactionId,
+      message: `Cannot discard changes for liveEdit document "${documentId}". LiveEdit documents do not support drafts.`,
+    })
+  }
+
+  // draft/published or version logic
+  const versionId = isReleasePerspective(action.perspective)
+    ? getVersionId(DocumentId(documentId), action.perspective.releaseName)
+    : getDraftId(DocumentId(documentId))
+  const mutations: Mutation[] = [{delete: {id: versionId}}]
+
+  if (!working[versionId]) {
+    throw new ActionError({
+      documentId,
+      transactionId,
+      message: `There is no draft or version available to discard for document "${documentId}".`,
+    })
+  }
+
+  if (!checkGrant(grants.update, working[versionId])) {
+    throw new PermissionActionError({
+      documentId,
+      transactionId,
+      message: `You do not have permission to discard changes for document "${documentId}".`,
+    })
+  }
+
+  base = processMutations({documents: base, transactionId, mutations, timestamp})
+  working = processMutations({documents: working, transactionId, mutations, timestamp})
+
+  outgoingMutations.push(...mutations)
+  outgoingActions.push({
+    actionType: 'sanity.action.document.version.discard',
+    versionId,
+  })
+  return {base, working}
+}

package/src/document/processActions/edit.ts

@@ -0,0 +1,141 @@
+import {diffValue} from '@sanity/diff-patch'
+import {DocumentId, getDraftId, getPublishedId, getVersionId} from '@sanity/id-utils'
+import {type Mutation, type PatchOperations, type SanityDocument} from '@sanity/types'
+
+import {isReleasePerspective} from '../../releases/utils/isReleasePerspective'
+import {type EditDocumentAction} from '../actions'
+import {getId, processMutations} from '../processMutations'
+import {
+  ActionError,
+  type ActionHandlerContext,
+  type ActionHandlerResult,
+  applySingleDocPatch,
+  checkGrant,
+  PermissionActionError,
+} from './shared'
+
+export function handleEdit(
+  action: EditDocumentAction,
+  ctx: ActionHandlerContext,
+): ActionHandlerResult {
+  const {transactionId, timestamp, grants, outgoingActions, outgoingMutations} = ctx
+  let {base, working} = ctx
+
+  const documentId = getId(action.documentId)
+
+  if (action.liveEdit) {
+    const result = applySingleDocPatch({
+      base,
+      working,
+      documentId,
+      patches: action.patches,
+      transactionId,
+      timestamp,
+      grants,
+    })
+    // liveEdit documents use the mutation endpoint directly -- we don't send actions
+    outgoingMutations.push(...result.workingMutations)
+    return {base: result.base, working: result.working}
+  }
+
+  const versionId = isReleasePerspective(action.perspective)
+    ? getVersionId(DocumentId(documentId), action.perspective.releaseName)
+    : undefined
+  const draftId = getDraftId(DocumentId(documentId))
+  const publishedId = getPublishedId(DocumentId(documentId))
+  const patchDocumentId = isReleasePerspective(action.perspective) ? versionId! : draftId
+  const userPatches = action.patches?.map((patch) => ({
+    patch: {id: patchDocumentId, ...patch},
+  }))
+
+  // skip this action if there are no associated patches
+  if (!userPatches?.length) return {base, working}
+
+  if (isReleasePerspective(action.perspective)) {
+    if (!working[versionId!] && !base[versionId!]) {
+      throw new ActionError({
+        documentId,
+        transactionId,
+        message: `This document does not exist in the release. Please create it or add it to the release first.`,
+      })
+    }
+  } else if (
+    (!working[draftId] && !working[publishedId]) ||
+    (!base[draftId] && !base[publishedId])
+  ) {
+    throw new ActionError({
+      documentId,
+      transactionId,
+      message: `Cannot edit document because it does not exist in draft or published form.`,
+    })
+  }
+
+  const baseMutations: Mutation[] = []
+  // don't create a draft from the published version in a release perspective
+  if (!isReleasePerspective(action.perspective) && !base[draftId] && base[publishedId]) {
+    // otherwise make a draft from the published version
+    baseMutations.push({create: {...base[publishedId], _id: draftId}})
+  }
+
+  // the above statement and guards should make this never be null or undefined
+  const baseBefore = base[patchDocumentId] ?? base[publishedId]
+  if (userPatches) {
+    baseMutations.push(...userPatches)
+  }
+
+  base = processMutations({
+    documents: base,
+    transactionId,
+    mutations: baseMutations,
+    timestamp,
+  })
+  // this one will always be defined because a patch mutation will never
+  // delete an input document
+  const baseAfter = base[patchDocumentId] as SanityDocument
+  const patches = diffValue(baseBefore, baseAfter)
+
+  const workingMutations: Mutation[] = []
+  if (!isReleasePerspective(action.perspective) && !working[draftId] && working[publishedId]) {
+    const newDraftFromPublished = {...working[publishedId], _id: draftId}
+
+    if (!checkGrant(grants.create, newDraftFromPublished)) {
+      throw new PermissionActionError({
+        documentId,
+        transactionId,
+        message: `You do not have permission to create a draft for editing this document.`,
+      })
+    }
+
+    workingMutations.push({create: newDraftFromPublished})
+  }
+
+  // the first if statement should make this never be null or undefined
+  const workingBefore = working[patchDocumentId] ?? working[publishedId]
+  if (!checkGrant(grants.update, workingBefore!)) {
+    throw new PermissionActionError({
+      documentId,
+      transactionId,
+      message: `You do not have permission to edit document "${documentId}".`,
+    })
+  }
+  workingMutations.push(...patches.map((patch) => ({patch: {id: patchDocumentId, ...patch}})))
+
+  working = processMutations({
+    documents: working,
+    transactionId,
+    mutations: workingMutations,
+    timestamp,
+  })
+
+  outgoingMutations.push(...workingMutations)
+  outgoingActions.push(
+    ...patches.map((patch) => ({
+      actionType: 'sanity.action.document.edit' as const,
+      draftId: patchDocumentId,
+      publishedId,
+      patch: patch as PatchOperations,
+    })),
+  )
+
+  return {base, working}
+}