@sanity/sdk 3.0.0-rc.0 → 3.0.0-rc.2

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, identity} = 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, identity)) {
+    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,37 @@
+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, identity} = ctx
+  const {base, working} = ctx
+
+  const releaseDocumentId = getReleaseDocumentId(action.releaseId)
+
+  const result = applySingleDocPatch({
+    base,
+    working,
+    documentId: releaseDocumentId,
+    patches: [action.patch],
+    transactionId,
+    timestamp,
+    grants,
+    identity,
+    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, identity} = 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, identity)) {
+    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, identity} = 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, identity)) {
+    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, identity} = 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, identity)) {
+    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

@@ -0,0 +1,308 @@
+import {diffValue} from '@sanity/diff-patch'
+import {jsonMatch, stringifyPath} from '@sanity/json-match'
+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>
+  /**
+   * The current user's ID, used by GROQ's `identity()` when evaluating ACL
+   * filters. May be `undefined` before the user has loaded; in that case
+   * `identity()` evaluates to null.
+   */
+  identity: string | undefined
+  outgoingActions: HttpAction[]
+  outgoingMutations: Mutation[]
+}
+
+export interface ActionHandlerResult {
+  base: DocumentSet
+  working: DocumentSet
+}
+
+export function checkGrant(
+  grantExpr: ExprNode,
+  document: SanityDocument,
+  identity: string | undefined,
+): boolean {
+  const value = evaluateSync(grantExpr, {params: {document}, identity})
+  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 {}
+
+/**
+ * Creates a `processMutations` wrapper that surfaces application failures as
+ * `ActionError`s when the caller asked to preserve their patch operations.
+ * With preserved operations, patches can legitimately fail to apply (e.g.
+ * re-applied onto a diverged document during a rebase), so wrapping lets a
+ * rebase skip the transaction instead of failing the store. Without
+ * `preserveOperations`, errors are rethrown untouched.
+ */
+export function createMutationApplier(options: {
+  documentId: string
+  transactionId: string
+  timestamp: string
+  preserveOperations: boolean | undefined
+}): (
+  documents: DocumentSet,
+  mutations: Mutation[],
+  documentSetName: 'base' | 'working',
+) => DocumentSet {
+  const {documentId, transactionId, timestamp, preserveOperations} = options
+  return (documents, mutations, documentSetName) => {
+    try {
+      return processMutations({documents, transactionId, mutations, timestamp})
+    } catch (error) {
+      if (!preserveOperations) throw error
+      throw new ActionError({
+        documentId,
+        transactionId,
+        message: `Failed to apply patches to the ${documentSetName} document: ${
+          error instanceof Error ? error.message : 'Unknown error'
+        }`,
+      })
+    }
+  }
+}
+
+/**
+ * Re-applies the operational intent of user-supplied `inc`/`dec` patches to a
+ * set of snapshot-diffed patches.
+ *
+ * The outgoing patches sent to Content Lake are re-derived by diffing the
+ * base document before and after the user's patches were applied. That diff
+ * collapses an `inc` into a `set` of the resulting number, which turns
+ * concurrent increments from different clients into last-write-wins. This
+ * helper finds diffed `set` operations that are exactly explained by the
+ * user's `inc`/`dec` operations and swaps them back, so the server applies
+ * the increment against whatever value is current at commit time.
+ *
+ * A `set` is only swapped when its value equals the base value plus the
+ * accumulated user deltas for that exact path; anything else (e.g. an `inc`
+ * combined with a `set` of the same field) keeps the diffed `set`.
+ *
+ * Content Lake fails the whole transaction when `inc`/`dec` targets a missing
+ * path (unlike `set`, which always succeeds). To avoid turning a concurrent
+ * field removal into a transaction revert, the emitted patch seeds the target
+ * with a `setIfMissing` of the base value; the server executes `setIfMissing`
+ * before `inc`/`dec` within a single patch, so a concurrently removed field
+ * degrades to the same result the diffed `set` would have produced. A path
+ * into a concurrently removed keyed array item can still fail the
+ * transaction (`setIfMissing` cannot create array items); the transaction is
+ * then reverted and reported, which is preferable to silently resurrecting
+ * the item.
+ */
+export function preserveNumericOperations(
+  baseBefore: SanityDocument | null | undefined,
+  userPatches: PatchOperations[] | undefined,
+  diffedPatches: PatchOperations[],
+): PatchOperations[] {
+  if (!baseBefore || !userPatches?.length) return diffedPatches
+
+  // accumulate the user's inc/dec deltas per concrete (stringified) path,
+  // tracking the expected final value by replaying the additions in order
+  const targets = new Map<string, {baseValue: number; expectedValue: number; delta: number}>()
+  for (const patch of userPatches) {
+    for (const [op, sign] of [
+      ['inc', 1],
+      ['dec', -1],
+    ] as const) {
+      const record = patch[op]
+      if (!record) continue
+      for (const [pathExpression, amount] of Object.entries(record)) {
+        if (typeof amount !== 'number') continue
+        for (const match of jsonMatch(baseBefore, pathExpression)) {
+          const path = stringifyPath(match.path)
+          const existing = targets.get(path)
+          if (existing) {
+            existing.expectedValue += sign * amount
+            existing.delta += sign * amount
+          } else if (typeof match.value === 'number') {
+            targets.set(path, {
+              baseValue: match.value,
+              expectedValue: match.value + sign * amount,
+              delta: sign * amount,
+            })
+          }
+        }
+      }
+    }
+  }
+  if (!targets.size) return diffedPatches
+
+  const preserved = new Map<string, {delta: number; baseValue: number}>()
+  const next = diffedPatches.flatMap((patch) => {
+    if (!patch.set) return [patch]
+
+    const keptSet: Record<string, unknown> = {}
+    for (const [path, value] of Object.entries(patch.set)) {
+      const target = targets.get(path)
+      if (target && typeof value === 'number' && value === target.expectedValue) {
+        preserved.set(path, {delta: target.delta, baseValue: target.baseValue})
+      } else {
+        keptSet[path] = value
+      }
+    }
+
+    if (Object.keys(keptSet).length === Object.keys(patch.set).length) return [patch]
+    const {set: _set, ...rest} = patch
+    const withKept = Object.keys(keptSet).length ? {...rest, set: keptSet} : rest
+    return Object.keys(withKept).length ? [withKept] : []
+  })
+
+  if (!preserved.size) return next
+
+  const setIfMissing: Record<string, unknown> = {}
+  const inc: Record<string, number> = {}
+  const dec: Record<string, number> = {}
+  for (const [path, {delta, baseValue}] of preserved) {
+    setIfMissing[path] = baseValue
+    if (delta >= 0) inc[path] = delta
+    else dec[path] = -delta
+  }
+  return [
+    ...next,
+    {
+      setIfMissing,
+      ...(Object.keys(inc).length && {inc}),
+      ...(Object.keys(dec).length && {dec}),
+    },
+  ]
+}
+
+interface ApplySingleDocPatchOptions {
+  base: DocumentSet
+  working: DocumentSet
+  documentId: string
+  patches: PatchOperations[] | undefined
+  transactionId: string
+  timestamp: string
+  grants: Record<Grant, ExprNode>
+  identity: string | undefined
+  /**
+   * 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
+  /**
+   * When `true`, the given patches are used verbatim instead of being
+   * re-derived by diffing the base document before and after application.
+   * Patch application failures are surfaced as `ActionError`s so a rebase
+   * can skip the transaction instead of failing the store.
+   */
+  preserveOperations?: boolean
+}
+
+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,
+  identity,
+  notFoundMessage = 'Cannot edit document because it does not exist.',
+  permissionMessage = `You do not have permission to edit document "${documentId}".`,
+  preserveOperations,
+}: 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 applyMutations = createMutationApplier({
+    documentId,
+    transactionId,
+    timestamp,
+    preserveOperations,
+  })
+
+  const baseBefore = base[documentId]
+  base = applyMutations(base, userPatches, 'base')
+  const baseAfter = base[documentId]
+  const diffedPatches = preserveOperations
+    ? (patches as PatchOperations[])
+    : preserveNumericOperations(
+        baseBefore,
+        patches,
+        diffValue(baseBefore, baseAfter) as PatchOperations[],
+      )
+
+  const workingBefore = working[documentId] as SanityDocument
+  if (!checkGrant(grants.update, workingBefore, identity)) {
+    throw new PermissionActionError({documentId, transactionId, message: permissionMessage})
+  }
+
+  const workingMutations: Mutation[] = diffedPatches.map((patch) => ({
+    patch: {id: documentId, ...patch},
+  }))
+
+  working = applyMutations(working, workingMutations, 'working')
+
+  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, identity, 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, identity)) {
+    throw new PermissionActionError({
+      documentId,
+      transactionId,
+      message: `You do not have permission to unpublish the document "${documentId}".`,
+    })
+  }
+
+  if (!working[draftId] && !checkGrant(grants.create, newDraftFromPublished, identity)) {
+    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}
+}