@sanity/sdk 2.11.1 → 2.12.0

package/src/document/processActions/edit.ts

@@ -9,6 +9,7 @@ import {
   ActionError,
   type ActionHandlerContext,
   type ActionHandlerResult,
+  applySingleDocPatch,
   checkGrant,
   PermissionActionError,
 } from './shared'
@@ -23,54 +24,18 @@ export function handleEdit(
   const documentId = getId(action.documentId)
 
   if (action.liveEdit) {
-    // Single-document mode (liveEdit or release perspective): edit directly without draft logic
-    const userPatches = action.patches?.map((patch) => ({patch: {id: documentId, ...patch}}))
-
-    // skip this action if there are no associated patches
-    if (!userPatches?.length) return {base, working}
-
-    if (!working[documentId] || !base[documentId]) {
-      throw new ActionError({
-        documentId,
-        transactionId,
-        message: `Cannot edit document because it does not exist.`,
-      })
-    }
-
-    const baseBefore = base[documentId] as SanityDocument
-    if (userPatches) {
-      base = processMutations({
-        documents: base,
-        transactionId,
-        mutations: userPatches,
-        timestamp,
-      })
-    }
-
-    const baseAfter = base[documentId] as SanityDocument
-    const patches = diffValue(baseBefore, baseAfter)
-
-    const workingBefore = working[documentId] as SanityDocument
-    if (!checkGrant(grants.update, workingBefore)) {
-      throw new PermissionActionError({
-        documentId,
-        transactionId,
-        message: `You do not have permission to edit document "${documentId}".`,
-      })
-    }
-
-    const workingMutations = patches.map((patch) => ({patch: {id: documentId, ...patch}}))
-
-    working = processMutations({
-      documents: working,
+    const result = applySingleDocPatch({
+      base,
+      working,
+      documentId,
+      patches: action.patches,
       transactionId,
-      mutations: workingMutations,
       timestamp,
+      grants,
     })
-
     // liveEdit documents use the mutation endpoint directly -- we don't send actions
-    outgoingMutations.push(...workingMutations)
-    return {base, working}
+    outgoingMutations.push(...result.workingMutations)
+    return {base: result.base, working: result.working}
   }
 
   const versionId = isReleasePerspective(action.perspective)

package/src/document/processActions/processActions.ts

@@ -1,7 +1,7 @@
 import {type Mutation} from '@sanity/types'
 import {type ExprNode} from 'groq-js'
 
-import {type DocumentAction} from '../actions'
+import {type Action, type DocumentAction} from '../actions'
 import {type Grant} from '../permissions'
 import {type DocumentSet} from '../processMutations'
 import {type HttpAction} from '../reducers'
@@ -10,6 +10,13 @@ import {handleDelete} from './delete'
 import {handleDiscard} from './discard'
 import {handleEdit} from './edit'
 import {handlePublish} from './publish'
+import {handleReleaseArchive, handleReleaseUnarchive} from './releaseArchive'
+import {handleReleaseCreate} from './releaseCreate'
+import {handleReleaseDelete} from './releaseDelete'
+import {handleReleaseEdit} from './releaseEdit'
+import {handleReleasePublish} from './releasePublish'
+import {handleReleaseSchedule, handleReleaseUnschedule} from './releaseSchedule'
+import {isReleaseAction} from './releaseUtil'
 import {
   ActionError,
   type ActionHandlerContext,
@@ -30,7 +37,7 @@ interface ProcessActionsOptions {
   /**
    * The actions to apply to the given documents
    */
-  actions: DocumentAction[]
+  actions: Action[]
 
   /**
    * The set of documents these actions were intended to be applied to. These
@@ -116,6 +123,24 @@ export function processActions({
   const outgoingActions: HttpAction[] = []
   const outgoingMutations: Mutation[] = []
 
+  // liveEdit document actions go to the mutations API, since the actions API
+  // requires a draft+published pair. Mixing them with anything else in the same
+  // transaction would silently lose atomicity for the non-liveEdit operations,
+  // so require users to split the transaction.
+  // (Note that the reducers already does this for us -- you'd have to try hard to mix them.)
+  const liveEditAction = actions.find((action) => !isReleaseAction(action) && action.liveEdit) as
+    | DocumentAction
+    | undefined
+  const otherAction = actions.find((action) => isReleaseAction(action) || !action.liveEdit)
+  if (liveEditAction && otherAction) {
+    throw new ActionError({
+      documentId: liveEditAction.documentId!,
+      transactionId,
+      message:
+        'Cannot combine liveEdit document actions with other actions in the same transaction. Submit them as separate transactions.',
+    })
+  }
+
   for (const action of actions) {
     const result = dispatch(action, {
       base,
@@ -143,7 +168,7 @@ export function processActions({
   }
 }
 
-function dispatch(action: DocumentAction, ctx: ActionHandlerContext): ActionHandlerResult {
+function dispatch(action: Action, ctx: ActionHandlerContext): ActionHandlerResult {
   switch (action.type) {
     case 'document.create':
       return handleCreate(action, ctx)
@@ -157,6 +182,22 @@ function dispatch(action: DocumentAction, ctx: ActionHandlerContext): ActionHand
       return handlePublish(action, ctx)
     case 'document.unpublish':
       return handleUnpublish(action, ctx)
+    case 'release.create':
+      return handleReleaseCreate(action, ctx)
+    case 'release.edit':
+      return handleReleaseEdit(action, ctx)
+    case 'release.publish':
+      return handleReleasePublish(action, ctx)
+    case 'release.schedule':
+      return handleReleaseSchedule(action, ctx)
+    case 'release.unschedule':
+      return handleReleaseUnschedule(action, ctx)
+    case 'release.archive':
+      return handleReleaseArchive(action, ctx)
+    case 'release.unarchive':
+      return handleReleaseUnarchive(action, ctx)
+    case 'release.delete':
+      return handleReleaseDelete(action, ctx)
     default:
       throw new Error(
         `Unknown action type: "${

package/src/document/processActions/releaseArchive.ts

@@ -0,0 +1,77 @@
+import {type ArchiveReleaseAction, type UnarchiveReleaseAction} from '../actions'
+import {getReleaseDocumentId} from './releaseUtil'
+import {
+  ActionError,
+  type ActionHandlerContext,
+  type ActionHandlerResult,
+  checkGrant,
+  PermissionActionError,
+} from './shared'
+
+export function handleReleaseArchive(
+  action: ArchiveReleaseAction,
+  ctx: ActionHandlerContext,
+): ActionHandlerResult {
+  const {base, working, grants, outgoingActions, transactionId} = ctx
+
+  const releaseDocumentId = getReleaseDocumentId(action.releaseId)
+  const existing = working[releaseDocumentId] ?? base[releaseDocumentId]
+  if (!existing) {
+    throw new ActionError({
+      documentId: releaseDocumentId,
+      transactionId,
+      message: `Cannot archive release "${action.releaseId}" because it does not exist.`,
+    })
+  }
+
+  if (!checkGrant(grants.update, existing)) {
+    throw new PermissionActionError({
+      documentId: releaseDocumentId,
+      transactionId,
+      message: `You do not have permission to archive release "${action.releaseId}".`,
+    })
+  }
+
+  // Archiving deletes every version document in the release server-side.
+  // Although technically we could search through the document store for all related
+  // version documents, for now it's simpler to just let the server handle it.
+  // (Those local documents will be eventually updated by the listener.)
+  outgoingActions.push({
+    actionType: 'sanity.action.release.archive',
+    releaseId: action.releaseId,
+  })
+
+  return {base, working}
+}
+
+export function handleReleaseUnarchive(
+  action: UnarchiveReleaseAction,
+  ctx: ActionHandlerContext,
+): ActionHandlerResult {
+  const {base, working, grants, outgoingActions, transactionId} = ctx
+
+  const releaseDocumentId = getReleaseDocumentId(action.releaseId)
+  const existing = working[releaseDocumentId] ?? base[releaseDocumentId]
+  if (!existing) {
+    throw new ActionError({
+      documentId: releaseDocumentId,
+      transactionId,
+      message: `Cannot unarchive release "${action.releaseId}" because it does not exist.`,
+    })
+  }
+
+  if (!checkGrant(grants.update, existing)) {
+    throw new PermissionActionError({
+      documentId: releaseDocumentId,
+      transactionId,
+      message: `You do not have permission to unarchive release "${action.releaseId}".`,
+    })
+  }
+
+  outgoingActions.push({
+    actionType: 'sanity.action.release.unarchive',
+    releaseId: action.releaseId,
+  })
+
+  return {base, working}
+}

package/src/document/processActions/releaseCreate.ts

@@ -0,0 +1,59 @@
+import {type Mutation, type SanityDocument} from '@sanity/types'
+
+import {type CreateReleaseAction} from '../actions'
+import {processMutations} from '../processMutations'
+import {getReleaseDocumentId} from './releaseUtil'
+import {
+  ActionError,
+  type ActionHandlerContext,
+  type ActionHandlerResult,
+  checkGrant,
+  PermissionActionError,
+} from './shared'
+
+export function handleReleaseCreate(
+  action: CreateReleaseAction,
+  ctx: ActionHandlerContext,
+): ActionHandlerResult {
+  const {transactionId, timestamp, grants, outgoingActions, outgoingMutations} = ctx
+  let {base, working} = ctx
+
+  const releaseDocumentId = getReleaseDocumentId(action.releaseId)
+
+  if (working[releaseDocumentId] || base[releaseDocumentId]) {
+    throw new ActionError({
+      documentId: releaseDocumentId,
+      transactionId,
+      message: `A release with id "${action.releaseId}" already exists.`,
+    })
+  }
+  // Optimistic local release doc
+  const releaseDoc = {
+    _id: releaseDocumentId,
+    _type: 'system.release',
+    name: action.releaseId,
+    state: 'active',
+    metadata: action.metadata,
+  }
+  const mutations: Mutation[] = [{create: releaseDoc}]
+
+  base = processMutations({documents: base, transactionId, mutations, timestamp})
+  working = processMutations({documents: working, transactionId, mutations, timestamp})
+
+  if (!checkGrant(grants.create, working[releaseDocumentId] as SanityDocument)) {
+    throw new PermissionActionError({
+      documentId: releaseDocumentId,
+      transactionId,
+      message: `You do not have permission to create release "${action.releaseId}".`,
+    })
+  }
+
+  outgoingMutations.push(...mutations)
+  outgoingActions.push({
+    actionType: 'sanity.action.release.create',
+    releaseId: action.releaseId,
+    metadata: action.metadata,
+  })
+
+  return {base, working}
+}

package/src/document/processActions/releaseDelete.ts

@@ -0,0 +1,65 @@
+import {type Mutation} from '@sanity/types'
+
+import {type DeleteReleaseAction} from '../actions'
+import {processMutations} from '../processMutations'
+import {getReleaseDocumentId} from './releaseUtil'
+import {
+  ActionError,
+  type ActionHandlerContext,
+  type ActionHandlerResult,
+  checkGrant,
+  PermissionActionError,
+} from './shared'
+
+// you can only delete archived or published releases
+// https://www.sanity.io/docs/content-lake/dispatch-actions#k22ab37420f3c
+const DELETABLE_STATES = new Set(['archived', 'published'])
+
+export function handleReleaseDelete(
+  action: DeleteReleaseAction,
+  ctx: ActionHandlerContext,
+): ActionHandlerResult {
+  const {transactionId, timestamp, grants, outgoingActions, outgoingMutations} = ctx
+  let {base, working} = ctx
+
+  const releaseDocumentId = getReleaseDocumentId(action.releaseId)
+  const existing = working[releaseDocumentId] ?? base[releaseDocumentId]
+
+  if (!existing) {
+    throw new ActionError({
+      documentId: releaseDocumentId,
+      transactionId,
+      message: `Cannot delete release "${action.releaseId}" because it does not exist.`,
+    })
+  }
+
+  const state = existing['state']
+  if (state && typeof state === 'string' && !DELETABLE_STATES.has(state)) {
+    throw new ActionError({
+      documentId: releaseDocumentId,
+      transactionId,
+      message: `Cannot delete release "${action.releaseId}" while it is "${state}". Archive it first.`,
+    })
+  }
+
+  if (!checkGrant(grants.update, existing)) {
+    throw new PermissionActionError({
+      documentId: releaseDocumentId,
+      transactionId,
+      message: `You do not have permission to delete release "${action.releaseId}".`,
+    })
+  }
+
+  const mutations: Mutation[] = [{delete: {id: releaseDocumentId}}]
+
+  base = processMutations({documents: base, transactionId, mutations, timestamp})
+  working = processMutations({documents: working, transactionId, mutations, timestamp})
+
+  outgoingMutations.push(...mutations)
+  outgoingActions.push({
+    actionType: 'sanity.action.release.delete',
+    releaseId: action.releaseId,
+  })
+
+  return {base, working}
+}

package/src/document/processActions/releaseEdit.ts

@@ -0,0 +1,36 @@
+import {type EditReleaseAction} from '../actions'
+import {getReleaseDocumentId} from './releaseUtil'
+import {type ActionHandlerContext, type ActionHandlerResult, applySingleDocPatch} from './shared'
+
+export function handleReleaseEdit(
+  action: EditReleaseAction,
+  ctx: ActionHandlerContext,
+): ActionHandlerResult {
+  const {transactionId, timestamp, grants, outgoingActions, outgoingMutations} = ctx
+  const {base, working} = ctx
+
+  const releaseDocumentId = getReleaseDocumentId(action.releaseId)
+
+  const result = applySingleDocPatch({
+    base,
+    working,
+    documentId: releaseDocumentId,
+    patches: [action.patch],
+    transactionId,
+    timestamp,
+    grants,
+    notFoundMessage: `Cannot edit release "${action.releaseId}" because it does not exist.`,
+    permissionMessage: `You do not have permission to edit release "${action.releaseId}".`,
+  })
+
+  outgoingMutations.push(...result.workingMutations)
+  outgoingActions.push(
+    ...result.diffedPatches.map((patch) => ({
+      actionType: 'sanity.action.release.edit' as const,
+      releaseId: action.releaseId,
+      patch,
+    })),
+  )
+
+  return {base: result.base, working: result.working}
+}

package/src/document/processActions/releasePublish.ts

@@ -0,0 +1,45 @@
+import {type PublishReleaseAction} from '../actions'
+import {getReleaseDocumentId} from './releaseUtil'
+import {
+  ActionError,
+  type ActionHandlerContext,
+  type ActionHandlerResult,
+  checkGrant,
+  PermissionActionError,
+} from './shared'
+
+export function handleReleasePublish(
+  action: PublishReleaseAction,
+  ctx: ActionHandlerContext,
+): ActionHandlerResult {
+  const {base, working, grants, outgoingActions, transactionId} = ctx
+
+  const releaseDocumentId = getReleaseDocumentId(action.releaseId)
+  const existing = working[releaseDocumentId] ?? base[releaseDocumentId]
+  if (!existing) {
+    throw new ActionError({
+      documentId: releaseDocumentId,
+      transactionId,
+      message: `Cannot publish release "${action.releaseId}" because it does not exist.`,
+    })
+  }
+
+  if (!checkGrant(grants.update, existing)) {
+    throw new PermissionActionError({
+      documentId: releaseDocumentId,
+      transactionId,
+      message: `You do not have permission to publish release "${action.releaseId}".`,
+    })
+  }
+
+  // a release publish cascades to every version document in the release
+  // although technically we could search through the document store for all related
+  // version documents, for now it's simpler to just let the server handle it.
+  // (Those local documents will be eventually updated by the listener.)
+  outgoingActions.push({
+    actionType: 'sanity.action.release.publish',
+    releaseId: action.releaseId,
+  })
+
+  return {base, working}
+}

package/src/document/processActions/releaseSchedule.ts

@@ -0,0 +1,87 @@
+import {type ScheduleReleaseAction, type UnscheduleReleaseAction} from '../actions'
+import {getReleaseDocumentId} from './releaseUtil'
+import {
+  ActionError,
+  type ActionHandlerContext,
+  type ActionHandlerResult,
+  checkGrant,
+  PermissionActionError,
+} from './shared'
+
+export function handleReleaseSchedule(
+  action: ScheduleReleaseAction,
+  ctx: ActionHandlerContext,
+): ActionHandlerResult {
+  const {base, working, grants, outgoingActions, transactionId} = ctx
+
+  const releaseDocumentId = getReleaseDocumentId(action.releaseId)
+
+  if (Number.isNaN(Date.parse(action.publishAt))) {
+    throw new ActionError({
+      documentId: releaseDocumentId,
+      transactionId,
+      message: `Cannot schedule release "${action.releaseId}": "publishAt" must be a valid ISO 8601 timestamp (received "${action.publishAt}").`,
+    })
+  }
+
+  const existing = working[releaseDocumentId] ?? base[releaseDocumentId]
+  if (!existing) {
+    throw new ActionError({
+      documentId: releaseDocumentId,
+      transactionId,
+      message: `Cannot schedule release "${action.releaseId}" because it does not exist.`,
+    })
+  }
+
+  if (!checkGrant(grants.update, existing)) {
+    throw new PermissionActionError({
+      documentId: releaseDocumentId,
+      transactionId,
+      message: `You do not have permission to schedule release "${action.releaseId}".`,
+    })
+  }
+
+  // Scheduling flips `state` to 'scheduled' and locks version documents
+  // server-side. We don't model the lock locally yet — local edits to those
+  // version docs will be rejected at submit time. The listener will sync the
+  // updated release state.
+  outgoingActions.push({
+    actionType: 'sanity.action.release.schedule',
+    releaseId: action.releaseId,
+    publishAt: action.publishAt,
+  })
+
+  return {base, working}
+}
+
+export function handleReleaseUnschedule(
+  action: UnscheduleReleaseAction,
+  ctx: ActionHandlerContext,
+): ActionHandlerResult {
+  const {base, working, grants, outgoingActions, transactionId} = ctx
+
+  const releaseDocumentId = getReleaseDocumentId(action.releaseId)
+  const existing = working[releaseDocumentId] ?? base[releaseDocumentId]
+  if (!existing) {
+    throw new ActionError({
+      documentId: releaseDocumentId,
+      transactionId,
+      message: `Cannot unschedule release "${action.releaseId}" because it does not exist.`,
+    })
+  }
+
+  if (!checkGrant(grants.update, existing)) {
+    throw new PermissionActionError({
+      documentId: releaseDocumentId,
+      transactionId,
+      message: `You do not have permission to unschedule release "${action.releaseId}".`,
+    })
+  }
+
+  outgoingActions.push({
+    actionType: 'sanity.action.release.unschedule',
+    releaseId: action.releaseId,
+  })
+
+  return {base, working}
+}

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

@@ -1,8 +1,9 @@
-import {type Mutation, type SanityDocument} from '@sanity/types'
+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} from '../processMutations'
+import {type DocumentSet, processMutations} from '../processMutations'
 import {type HttpAction} from '../reducers'
 
 export interface ActionHandlerContext {
@@ -45,3 +46,94 @@ export class ActionError extends Error implements ActionErrorOptions {
 }
 
 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}
+}