@sanity/sdk 2.11.0 → 2.12.0

package/src/document/processActions/processActions.ts

@@ -0,0 +1,209 @@
+import {type Mutation} from '@sanity/types'
+import {type ExprNode} from 'groq-js'
+
+import {type Action, type DocumentAction} from '../actions'
+import {type Grant} from '../permissions'
+import {type DocumentSet} from '../processMutations'
+import {type HttpAction} from '../reducers'
+import {handleCreate} from './create'
+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,
+  type ActionHandlerResult,
+  PermissionActionError,
+} from './shared'
+import {handleUnpublish} from './unpublish'
+
+export {ActionError, PermissionActionError}
+
+interface ProcessActionsOptions {
+  /**
+   * The ID of this transaction. This will become the resulting `_rev` for all
+   * documents affected by changes derived from the current set of actions.
+   */
+  transactionId: string
+
+  /**
+   * The actions to apply to the given documents
+   */
+  actions: Action[]
+
+  /**
+   * The set of documents these actions were intended to be applied to. These
+   * set of documents should be captured right before a queued action is
+   * applied.
+   */
+  base: DocumentSet
+
+  /**
+   * The current "working" set of documents. A patch will be created by applying
+   * the actions to the base. This patch will then be applied to the working
+   * set for conflict resolution. Initially, this value should match the base
+   * set.
+   */
+  working: DocumentSet
+
+  /**
+   * The timestamp to use for `_updateAt` and other similar timestamps for this
+   * transaction
+   */
+  timestamp: string
+
+  /**
+   * the lookup with pre-parsed GROQ expressions
+   */
+  grants: Record<Grant, ExprNode>
+
+  // // TODO: implement initial values from the schema?
+  // initialValues?: {[TDocumentType in string]?: {_type: string}}
+}
+
+interface ProcessActionsResult {
+  /**
+   * The resulting document set after the actions have been applied. This is
+   * derived from the working documents.
+   */
+  working: DocumentSet
+  /**
+   * The document set before the actions have been applied. This is simply the
+   * input of the `working` document set.
+   */
+  previous: DocumentSet
+  /**
+   * The outgoing action that were collected when applying the actions. These
+   * are sent to the Actions HTTP API
+   */
+  outgoingActions: HttpAction[]
+  /**
+   * The outgoing mutations that were collected when applying the actions. These
+   * are here for debugging purposes.
+   */
+  outgoingMutations: Mutation[]
+  /**
+   * The previous revisions of the given documents before the actions were applied.
+   */
+  previousRevs: {[TDocumentId in string]?: string}
+}
+
+/**
+ * Applies the given set of actions to the working set of documents and converts
+ * high-level actions into lower-level outgoing mutations/actions that respect
+ * the current state of the working documents.
+ *
+ * Supports a "base" and "working" set of documents to allow actions to be
+ * applied on top of a different working set of documents in a 3-way merge
+ *
+ * Actions are applied to the base set of documents first. The difference
+ * between the base before and after is used to create a patch. This patch is
+ * then applied to the working set of documents and is set as the outgoing patch
+ * sent to the server.
+ */
+export function processActions({
+  actions,
+  transactionId,
+  working: initialWorking,
+  base: initialBase,
+  timestamp,
+  grants,
+}: ProcessActionsOptions): ProcessActionsResult {
+  let base: DocumentSet = {...initialBase}
+  let working: DocumentSet = {...initialWorking}
+
+  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,
+      working,
+      transactionId,
+      timestamp,
+      grants,
+      outgoingActions,
+      outgoingMutations,
+    })
+    base = result.base
+    working = result.working
+  }
+
+  const previousRevs = Object.fromEntries(
+    Object.entries(initialWorking).map(([id, doc]) => [id, doc?._rev]),
+  )
+
+  return {
+    working,
+    outgoingActions,
+    outgoingMutations,
+    previous: initialWorking,
+    previousRevs,
+  }
+}
+
+function dispatch(action: Action, ctx: ActionHandlerContext): ActionHandlerResult {
+  switch (action.type) {
+    case 'document.create':
+      return handleCreate(action, ctx)
+    case 'document.delete':
+      return handleDelete(action, ctx)
+    case 'document.discard':
+      return handleDiscard(action, ctx)
+    case 'document.edit':
+      return handleEdit(action, ctx)
+    case 'document.publish':
+      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: "${
+          // @ts-expect-error invalid input
+          action.type
+        }". Please contact support if this issue persists.`,
+      )
+  }
+}

package/src/document/processActions/publish.ts

@@ -0,0 +1,120 @@
+import {DocumentId, getDraftId, getPublishedId} from '@sanity/id-utils'
+import {type Mutation, type Reference, type SanityDocument} from '@sanity/types'
+
+import {isReleasePerspective} from '../../releases/utils/isReleasePerspective'
+import {isDeepEqual} from '../../utils/object'
+import {type PublishDocumentAction} from '../actions'
+import {getId, processMutations} from '../processMutations'
+import {
+  ActionError,
+  type ActionHandlerContext,
+  type ActionHandlerResult,
+  checkGrant,
+  PermissionActionError,
+} from './shared'
+
+export function handlePublish(
+  action: PublishDocumentAction,
+  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 publish this document. Publishing is not supported for liveEdit or version (release) documents.`,
+    })
+  }
+
+  // Standard draft/published logic
+  const draftId = getDraftId(DocumentId(documentId))
+  const publishedId = getPublishedId(DocumentId(documentId))
+
+  const workingDraft = working[draftId]
+  const baseDraft = base[draftId]
+  if (!workingDraft || !baseDraft) {
+    throw new ActionError({
+      documentId,
+      transactionId,
+      message: `Cannot publish because no draft version was found for document "${documentId}".`,
+    })
+  }
+
+  // Before proceeding, verify that the working draft is identical to the base draft.
+  // TODO: is it enough just to check for the _rev or nah?
+  if (!isDeepEqual(workingDraft, baseDraft)) {
+    throw new ActionError({
+      documentId,
+      transactionId,
+      message: `Publish aborted: The document has changed elsewhere. Please try again.`,
+    })
+  }
+
+  const newPublishedFromDraft = {...strengthenOnPublish(workingDraft), _id: publishedId}
+
+  const mutations: Mutation[] = [{delete: {id: draftId}}, {createOrReplace: newPublishedFromDraft}]
+
+  if (working[draftId] && !checkGrant(grants.update, working[draftId])) {
+    throw new PermissionActionError({
+      documentId,
+      transactionId,
+      message: `Publish failed: You do not have permission to update the draft for "${documentId}".`,
+    })
+  }
+
+  if (working[publishedId] && !checkGrant(grants.update, newPublishedFromDraft)) {
+    throw new PermissionActionError({
+      documentId,
+      transactionId,
+      message: `Publish failed: You do not have permission to update the published version of "${documentId}".`,
+    })
+  } else if (!working[publishedId] && !checkGrant(grants.create, newPublishedFromDraft)) {
+    throw new PermissionActionError({
+      documentId,
+      transactionId,
+      message: `Publish failed: You do not have permission to publish a new version of "${documentId}".`,
+    })
+  }
+
+  base = processMutations({documents: base, transactionId, mutations, timestamp})
+  working = processMutations({documents: working, transactionId, mutations, timestamp})
+
+  outgoingMutations.push(...mutations)
+  outgoingActions.push({
+    actionType: 'sanity.action.document.publish',
+    draftId,
+    publishedId,
+  })
+  return {base, working}
+}
+
+function strengthenOnPublish(draft: SanityDocument): SanityDocument {
+  const isStrengthenReference = (
+    value: object,
+  ): value is Reference & Required<Pick<Reference, '_strengthenOnPublish'>> =>
+    '_strengthenOnPublish' in value
+
+  function strengthen(value: unknown): unknown {
+    if (typeof value !== 'object' || !value) return value
+
+    if (isStrengthenReference(value)) {
+      const {_strengthenOnPublish, _weak, ...rest} = value
+      return {
+        ...rest,
+        ...(_strengthenOnPublish.weak && {_weak: true}),
+      }
+    }
+
+    if (Array.isArray(value)) {
+      return value.map(strengthen)
+    }
+
+    return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, strengthen(v)]))
+  }
+
+  return strengthen(draft) as SanityDocument
+}

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}
+}