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

package/src/document/actions.ts

@@ -1,9 +1,15 @@
+import {type ReleaseDocument} from '@sanity/client'
 import {SanityEncoder} from '@sanity/mutate'
 import {type PatchMutation as SanityMutatePatchMutation} from '@sanity/mutate/_unstable_store'
-import {type PatchMutation, type PatchOperations, type SanityDocument} from '@sanity/types'
+import {type PatchMutation, type PatchOperations} from '@sanity/types'
+import {type SanityDocument} from 'groq'
 
-import {type DocumentHandle, type DocumentTypeHandle} from '../config/sanityConfig'
-import {getPublishedId} from '../utils/ids'
+import {
+  type DocumentHandle,
+  type DocumentTypeHandle,
+  type ReleaseHandle,
+} from '../config/sanityConfig'
+import {getEffectiveDocumentId} from './util'
 
 const isSanityMutatePatch = (value: unknown): value is SanityMutatePatchMutation => {
   if (typeof value !== 'object' || !value) return false
@@ -30,7 +36,10 @@ export interface CreateDocumentAction<
    * System fields (_id, _type, _rev, _createdAt, _updatedAt) are omitted as they are set automatically.
    */
   initialValue?: Partial<
-    Omit<SanityDocument, '_id' | '_type' | '_rev' | '_createdAt' | '_updatedAt'>
+    Omit<
+      SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`>,
+      '_id' | '_type' | '_rev' | '_createdAt' | '_updatedAt'
+    >
   >
 }
 
@@ -59,6 +68,21 @@ export interface EditDocumentAction<
 > extends DocumentHandle<TDocumentType, TDataset, TProjectId> {
   type: 'document.edit'
   patches?: PatchOperations[]
+  /**
+   * When `true`, the given `patches` are forwarded verbatim to the server and
+   * applied as-is locally, instead of being re-derived by diffing document
+   * snapshots. This preserves the operational intent of the patches (e.g.
+   * keyed array inserts/unsets), which lets concurrent edits from other
+   * clients interleave coherently instead of being overwritten by
+   * position-based patches computed from a stale snapshot.
+   *
+   * Use this when the patches were produced by an editor that tracks its own
+   * operations (e.g. a collaborative text editor). During a rebase onto a
+   * changed remote document, preserved patches are re-applied operationally;
+   * if a patch can no longer apply, the transaction is skipped and reported
+   * as a `rebase-error` document event.
+   */
+  preserveOperations?: boolean
 }
 
 /**
@@ -116,6 +140,17 @@ export type DocumentAction<
   | UnpublishDocumentAction<TDocumentType, TDataset, TProjectId>
   | DiscardDocumentAction<TDocumentType, TDataset, TProjectId>
 
+/**
+ * Union of every action accepted by `applyDocumentActions` — both document-
+ * level actions and release-lifecycle actions.
+ * @beta
+ */
+export type Action<
+  TDocumentType extends string = string,
+  TDataset extends string = string,
+  TProjectId extends string = string,
+> = DocumentAction<TDocumentType, TDataset, TProjectId> | ReleaseAction
+
 /**
  * Creates a `CreateDocumentAction` object.
  * @param doc - A handle identifying the document type, dataset, and project. An optional `documentId` can be provided.
@@ -130,15 +165,21 @@ export function createDocument<
 >(
   doc: DocumentTypeHandle<TDocumentType, TDataset, TProjectId>,
   initialValue?: Partial<
-    Omit<SanityDocument, '_id' | '_type' | '_rev' | '_createdAt' | '_updatedAt'>
+    Omit<
+      SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`>,
+      '_id' | '_type' | '_rev' | '_createdAt' | '_updatedAt'
+    >
   >,
 ): CreateDocumentAction<TDocumentType, TDataset, TProjectId> {
+  // users may pass in an explicit documentId -- make sure we format it correctly for the action
+  let effectiveDocumentId
+  if (typeof doc.documentId === 'string') {
+    effectiveDocumentId = getEffectiveDocumentId({...doc, documentId: doc.documentId})
+  }
   return {
     type: 'document.create',
     ...doc,
-    ...(doc.documentId && {
-      documentId: doc.liveEdit ? doc.documentId : getPublishedId(doc.documentId),
-    }),
+    ...(effectiveDocumentId && {documentId: effectiveDocumentId}),
     ...(initialValue && {initialValue}),
   }
 }
@@ -156,10 +197,11 @@ export function deleteDocument<
 >(
   doc: DocumentHandle<TDocumentType, TDataset, TProjectId>,
 ): DeleteDocumentAction<TDocumentType, TDataset, TProjectId> {
+  const effectiveDocumentId = getEffectiveDocumentId(doc)
   return {
     type: 'document.delete',
     ...doc,
-    documentId: doc.liveEdit ? doc.documentId : getPublishedId(doc.documentId),
+    documentId: effectiveDocumentId,
   }
 }
 
@@ -174,12 +216,25 @@ function convertSanityMutatePatch(
   })
 }
 
+/**
+ * Options for creating an `EditDocumentAction`.
+ * @beta
+ */
+export interface EditDocumentOptions {
+  /**
+   * Forward the given patches verbatim instead of re-deriving them by
+   * diffing document snapshots. See {@link EditDocumentAction.preserveOperations}.
+   */
+  preserveOperations?: boolean
+}
+
 /**
  * Creates an `EditDocumentAction` object with patches for modifying a document.
  * Accepts patches in either the standard `PatchOperations` format or as a `SanityMutatePatchMutation` from `@sanity/mutate`.
  *
  * @param doc - A handle uniquely identifying the document to be edited.
  * @param sanityMutatePatch - A patch mutation object from `@sanity/mutate`.
+ * @param options - Options controlling how the patches are processed.
  * @returns An `EditDocumentAction` object ready for dispatch.
  * @beta
  */
@@ -190,12 +245,14 @@ export function editDocument<
 >(
   doc: DocumentHandle<TDocumentType, TDataset, TProjectId>,
   sanityMutatePatch: SanityMutatePatchMutation,
+  options?: EditDocumentOptions,
 ): EditDocumentAction<TDocumentType, TDataset, TProjectId>
 /**
  * Creates an `EditDocumentAction` object with patches for modifying a document.
  *
  * @param doc - A handle uniquely identifying the document to be edited.
  * @param patches - A single patch operation or an array of patch operations.
+ * @param options - Options controlling how the patches are processed.
  * @returns An `EditDocumentAction` object ready for dispatch.
  * @beta
  */
@@ -206,6 +263,7 @@ export function editDocument<
 >(
   doc: DocumentHandle<TDocumentType, TDataset, TProjectId>,
   patches?: PatchOperations | PatchOperations[],
+  options?: EditDocumentOptions,
 ): EditDocumentAction<TDocumentType, TDataset, TProjectId>
 /**
  * Creates an `EditDocumentAction` object with patches for modifying a document.
@@ -213,6 +271,7 @@ export function editDocument<
  *
  * @param doc - A handle uniquely identifying the document to be edited.
  * @param patches - Patches in various formats (`PatchOperations`, `PatchOperations[]`, or `SanityMutatePatchMutation`).
+ * @param options - Options controlling how the patches are processed.
  * @returns An `EditDocumentAction` object ready for dispatch.
  */
 export function editDocument<
@@ -222,24 +281,28 @@ export function editDocument<
 >(
   doc: DocumentHandle<TDocumentType, TDataset, TProjectId>,
   patches?: PatchOperations | PatchOperations[] | SanityMutatePatchMutation,
+  options?: EditDocumentOptions,
 ): EditDocumentAction<TDocumentType, TDataset, TProjectId> {
-  const documentId = doc.liveEdit ? doc.documentId : getPublishedId(doc.documentId)
+  const effectiveDocumentId = getEffectiveDocumentId(doc)
+  const preserveOperations = options?.preserveOperations && {preserveOperations: true as const}
 
   if (isSanityMutatePatch(patches)) {
     const converted = convertSanityMutatePatch(patches) ?? []
     return {
       ...doc,
       type: 'document.edit',
-      documentId,
+      documentId: effectiveDocumentId,
       patches: converted,
+      ...preserveOperations,
     }
   }
 
   return {
     ...doc,
     type: 'document.edit',
-    documentId,
+    documentId: effectiveDocumentId,
     ...(patches && {patches: Array.isArray(patches) ? patches : [patches]}),
+    ...preserveOperations,
   }
 }
 
@@ -256,10 +319,11 @@ export function publishDocument<
 >(
   doc: DocumentHandle<TDocumentType, TDataset, TProjectId>,
 ): PublishDocumentAction<TDocumentType, TDataset, TProjectId> {
+  const effectiveDocumentId = getEffectiveDocumentId(doc)
   return {
     type: 'document.publish',
     ...doc,
-    documentId: doc.liveEdit ? doc.documentId : getPublishedId(doc.documentId),
+    documentId: effectiveDocumentId,
   }
 }
 
@@ -276,10 +340,11 @@ export function unpublishDocument<
 >(
   doc: DocumentHandle<TDocumentType, TDataset, TProjectId>,
 ): UnpublishDocumentAction<TDocumentType, TDataset, TProjectId> {
+  const effectiveDocumentId = getEffectiveDocumentId(doc)
   return {
     type: 'document.unpublish',
     ...doc,
-    documentId: doc.liveEdit ? doc.documentId : getPublishedId(doc.documentId),
+    documentId: effectiveDocumentId,
   }
 }
 
@@ -296,9 +361,141 @@ export function discardDocument<
 >(
   doc: DocumentHandle<TDocumentType, TDataset, TProjectId>,
 ): DiscardDocumentAction<TDocumentType, TDataset, TProjectId> {
+  const effectiveDocumentId = getEffectiveDocumentId(doc)
   return {
     type: 'document.discard',
     ...doc,
-    documentId: doc.liveEdit ? doc.documentId : getPublishedId(doc.documentId),
+    documentId: effectiveDocumentId,
   }
 }
+
+/**
+ * Creates a new release. The `releaseId` must be unique within the current
+ * retention period.
+ * @beta
+ */
+export interface CreateReleaseAction extends ReleaseHandle {
+  type: 'release.create'
+  metadata: ReleaseDocument['metadata']
+}
+
+/**
+ * Patches the metadata of an existing release.
+ * @beta
+ */
+export interface EditReleaseAction extends ReleaseHandle {
+  type: 'release.edit'
+  patch: PatchOperations
+}
+
+/**
+ * Publishes all version documents in a release.
+ * @beta
+ */
+export interface PublishReleaseAction extends ReleaseHandle {
+  type: 'release.publish'
+}
+
+/**
+ * Schedules a release to be published at the given UTC time. Locks the
+ * version documents server-side until the release is unscheduled or published.
+ * @beta
+ */
+export interface ScheduleReleaseAction extends ReleaseHandle {
+  type: 'release.schedule'
+  publishAt: string
+}
+
+/**
+ * Unschedules a release that was previously scheduled, returning it to the
+ * active editable state.
+ * @beta
+ */
+export interface UnscheduleReleaseAction extends ReleaseHandle {
+  type: 'release.unschedule'
+}
+
+/**
+ * Archives an active release. Version documents within the release are
+ * removed and no longer queryable, though still recoverable through history
+ * during the retention period.
+ * @beta
+ */
+export interface ArchiveReleaseAction extends ReleaseHandle {
+  type: 'release.archive'
+}
+
+/**
+ * Restores an archived release. Only possible during the retention period.
+ * @beta
+ */
+export interface UnarchiveReleaseAction extends ReleaseHandle {
+  type: 'release.unarchive'
+}
+
+/**
+ * Permanently deletes an archived or published release. To remove an active
+ * release, use the archive action first.
+ * @beta
+ */
+export interface DeleteReleaseAction extends ReleaseHandle {
+  type: 'release.delete'
+}
+
+/**
+ * Union of all release actions that can be dispatched alongside document
+ * actions through `applyDocumentActions`.
+ * @beta
+ */
+export type ReleaseAction =
+  | CreateReleaseAction
+  | EditReleaseAction
+  | PublishReleaseAction
+  | ScheduleReleaseAction
+  | UnscheduleReleaseAction
+  | ArchiveReleaseAction
+  | UnarchiveReleaseAction
+  | DeleteReleaseAction
+
+/** @beta */
+export function createRelease(
+  handle: ReleaseHandle,
+  metadata: ReleaseDocument['metadata'] = {releaseType: 'undecided'},
+): CreateReleaseAction {
+  return {type: 'release.create', ...handle, metadata}
+}
+
+/** @beta */
+export function editRelease(handle: ReleaseHandle, patch: PatchOperations): EditReleaseAction {
+  return {type: 'release.edit', ...handle, patch}
+}
+
+/** @beta */
+export function publishRelease(handle: ReleaseHandle): PublishReleaseAction {
+  return {type: 'release.publish', ...handle}
+}
+
+/** @beta */
+export function scheduleRelease(handle: ReleaseHandle, publishAt: string): ScheduleReleaseAction {
+  return {type: 'release.schedule', ...handle, publishAt}
+}
+
+/** @beta */
+export function unscheduleRelease(handle: ReleaseHandle): UnscheduleReleaseAction {
+  return {type: 'release.unschedule', ...handle}
+}
+
+/** @beta */
+export function archiveRelease(handle: ReleaseHandle): ArchiveReleaseAction {
+  return {type: 'release.archive', ...handle}
+}
+
+/** @beta */
+export function unarchiveRelease(handle: ReleaseHandle): UnarchiveReleaseAction {
+  return {type: 'release.unarchive', ...handle}
+}
+
+/** @beta */
+export function deleteRelease(handle: ReleaseHandle): DeleteReleaseAction {
+  return {type: 'release.delete', ...handle}
+}

package/src/document/applyDocumentActions.test.ts

@@ -1,11 +1,9 @@
-// applyDocumentActions.test.ts
 import {type SanityDocument} from '@sanity/types'
 import {Subject} from 'rxjs'
 import {describe, expect, it} from 'vitest'
 
 import {bindActionByResource} from '../store/createActionBinder'
 import {createSanityInstance, type SanityInstance} from '../store/createSanityInstance'
-import {} from '../store/createStateSourceAction'
 import {createStoreState, type StoreState} from '../store/createStoreState'
 import {type DocumentAction} from './actions'
 import {type DocumentStoreState} from './documentStore'
@@ -47,7 +45,7 @@ describe('applyDocumentActions', () => {
       events: eventsSubject,
     }
     state = createStoreState(initialState)
-    instance = createSanityInstance()
+    instance = createSanityInstance({projectId: 'p', dataset: 'd'})
     const key = {name: 'p.d', resource: {projectId: 'p', dataset: 'd'}}
 
     vi.mocked(bindActionByResource).mockImplementation(
@@ -69,7 +67,6 @@ describe('applyDocumentActions', () => {
       documentId: 'doc1',
       documentType: 'example',
       patches: [{set: {foo: 'bar'}}],
-      resource: {projectId: 'p', dataset: 'd'},
     }
 
     // Call applyDocumentActions with a fixed transactionId for reproducibility.
@@ -128,7 +125,6 @@ describe('applyDocumentActions', () => {
       documentId: 'doc1',
       documentType: 'example',
       patches: [{set: {foo: 'error'}}],
-      resource: {projectId: 'p', dataset: 'd'},
     }
 
     // Call applyDocumentActions with a fixed transactionId.
@@ -150,24 +146,26 @@ describe('applyDocumentActions', () => {
     await expect(applyPromise).rejects.toThrow('Simulated error')
   })
 
-  it('uses explicit resource even when instance default differs', async () => {
-    const otherInstance = createSanityInstance({
-      defaultResource: {projectId: 'child-p', dataset: 'child-d'},
-    })
+  it('uses the explicit resource when it does not match the instance config', async () => {
+    // The instance is configured for one resource...
+    const scopedInstance = createSanityInstance({projectId: 'child-p', dataset: 'child-d'})
+    // ...while the action refers to a different one
     const action: DocumentAction = {
       type: 'document.edit',
       documentId: 'doc1',
       documentType: 'example',
       patches: [{set: {foo: 'childTest'}}],
-      resource: {projectId: 'p', dataset: 'd'},
+      projectId: 'p',
+      dataset: 'd',
     }
-    const applyPromise = applyDocumentActions(instance, {
+    // The explicit `resource` option should win over the instance's own config
+    const applyPromise = applyDocumentActions(scopedInstance, {
       actions: [action],
       transactionId: 'txn-child-match',
       resource: {projectId: 'p', dataset: 'd'},
     })
 
-    // Simulate an applied transaction on the parent's instance
+    // Simulate an applied transaction for the explicitly-passed resource
     const appliedTx: AppliedTransaction = {
       transactionId: 'txn-child-match',
       actions: [action],
@@ -198,6 +196,30 @@ describe('applyDocumentActions', () => {
     const submittedResult = await result.submitted()
     expect(submittedResult).toEqual(acceptedResult)
 
-    otherInstance.dispose()
+    scopedInstance.dispose()
+  })
+
+  it('normalizes actions for the bound resource before queueing', async () => {
+    // A plain edit action with no `liveEdit` flag. Canvas forces liveEdit, so
+    // the queued action should come back with `liveEdit: true` — proving that
+    // `applyDocumentActions` runs `normalizeActionsForResource`.
+    const action: DocumentAction = {
+      type: 'document.edit',
+      documentId: 'doc1',
+      documentType: 'sanity.canvas.document',
+      patches: [{set: {foo: 'bar'}}],
+    }
+
+    // Don't await — we only need to inspect the synchronously-queued transaction.
+    applyDocumentActions(instance, {
+      actions: [action],
+      transactionId: 'txn-normalize',
+      resource: {canvasId: 'c'},
+    })
+
+    const queued = state.get().queued.find((t) => t.transactionId === 'txn-normalize')
+    expect(queued).toBeDefined()
+    const [queuedAction] = queued!.actions
+    expect(queuedAction).toMatchObject({type: 'document.edit', liveEdit: true})
   })
 })

package/src/document/applyDocumentActions.ts

@@ -1,15 +1,16 @@
-import {type SanityClient} from '@sanity/client'
-import {type SanityDocument} from '@sanity/types'
+import {type SanityDocument} from 'groq'
 import {distinctUntilChanged, filter, first, firstValueFrom, map, race} from 'rxjs'
 
 import {type DocumentResource} from '../config/sanityConfig'
 import {bindActionByResource} from '../store/createActionBinder'
 import {type SanityInstance} from '../store/createSanityInstance'
 import {type StoreContext} from '../store/defineStore'
-import {type DocumentAction} from './actions'
+import {type Action} from './actions'
 import {documentStore, type DocumentStoreState} from './documentStore'
+import {type DocumentTransactionSubmissionResult} from './events'
 import {type DocumentSet} from './processMutations'
 import {type AppliedTransaction, type QueuedTransaction, queueTransaction} from './reducers'
+import {normalizeActionsForResource} from './resourceRules'
 
 /** @beta */
 export interface ActionsResult<TDocument extends SanityDocument = SanityDocument> {
@@ -20,20 +21,21 @@ export interface ActionsResult<TDocument extends SanityDocument = SanityDocument
   appeared: string[]
   updated: string[]
   disappeared: string[]
-  submitted: () => ReturnType<SanityClient['action']>
+  submitted: () => Promise<DocumentTransactionSubmissionResult>
 }
 
 /** @beta */
 export interface ApplyDocumentActionsOptions {
   /**
-   * List of actions to apply.
+   * List of actions to apply. Accepts both document actions and release
+   * lifecycle actions because they share the same transaction pipeline.
    */
-  actions: DocumentAction[]
+  actions: Action[]
 
   /**
    * The resource to which the documents being acted on belong.
    */
-  resource: DocumentResource
+  resource?: DocumentResource
 
   /**
    * Optionally provide an ID to be used as this transaction ID
@@ -45,6 +47,15 @@ export interface ApplyDocumentActionsOptions {
   disableBatching?: boolean
 }
 
+/** @beta */
+export function applyDocumentActions<
+  TDocumentType extends string = string,
+  TDataset extends string = string,
+  TProjectId extends string = string,
+>(
+  instance: SanityInstance,
+  options: ApplyDocumentActionsOptions,
+): Promise<ActionsResult<SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`>>>
 /** @beta */
 export function applyDocumentActions(
   instance: SanityInstance,
@@ -63,13 +74,23 @@ const boundApplyDocumentActions = bindActionByResource(documentStore, _applyDocu
 /** @internal */
 async function _applyDocumentActions(
   {state}: StoreContext<DocumentStoreState>,
-  {actions, transactionId = crypto.randomUUID(), disableBatching}: ApplyDocumentActionsOptions,
+  {
+    actions,
+    resource,
+    transactionId = crypto.randomUUID(),
+    disableBatching,
+  }: ApplyDocumentActionsOptions,
 ): Promise<ActionsResult> {
   const {events} = state.get()
 
+  // Rewrite edit actions to match the bound resource's editing model (e.g.
+  // forcing liveEdit for Canvas, stripping unsupported release perspectives).
+  // Non-edit and release actions pass through unchanged.
+  const normalizedActions = normalizeActionsForResource(actions, resource)
+
   const transaction: QueuedTransaction = {
     transactionId,
-    actions,
+    actions: normalizedActions,
     ...(disableBatching && {disableBatching}),
   }
 

package/src/document/documentConstants.ts

@@ -8,3 +8,18 @@
 export const DOCUMENT_STATE_CLEAR_DELAY = 1000
 export const INITIAL_OUTGOING_THROTTLE_TIME = 1000
 export const API_VERSION = 'v2025-05-06'
+
+/**
+ * Base delay (ms) before retrying a document listener after an `OutOfSyncError`.
+ * Backoff doubles on each successive retry, capped at {@link OUT_OF_SYNC_RETRY_MAX_DELAY}.
+ */
+export const OUT_OF_SYNC_RETRY_BASE_DELAY = 500
+export const OUT_OF_SYNC_RETRY_MAX_DELAY = 10_000
+
+/**
+ * Base delay (ms) before retrying the dataset ACL fetch after a transient
+ * failure (a network error or 5xx response). Backoff doubles on each
+ * successive retry, capped at {@link ACL_RETRY_MAX_DELAY}.
+ */
+export const ACL_RETRY_BASE_DELAY = 500
+export const ACL_RETRY_MAX_DELAY = 10_000