@sanity/sdk 2.15.0 → 2.17.0

package/src/auth/refreshStampedToken.ts

@@ -2,8 +2,6 @@ import {
   distinctUntilChanged,
   exhaustMap,
   filter,
-  firstValueFrom,
-  from,
   map,
   Observable,
   type Subscription,
@@ -19,37 +17,6 @@ import {AuthStateType} from './authStateType'
 import {type AuthState, type AuthStoreState} from './authStore'
 
 const REFRESH_INTERVAL = 12 * 60 * 60 * 1000 // 12 hours in milliseconds
-const LOCK_NAME = 'sanity-token-refresh-lock'
-
-/** @internal */
-export function getLastRefreshTime(storageArea: Storage | undefined, storageKey: string): number {
-  try {
-    const data = storageArea?.getItem(`${storageKey}_last_refresh`)
-    const parsed = data ? parseInt(data, 10) : 0
-    return isNaN(parsed) ? 0 : parsed
-  } catch {
-    return 0
-  }
-}
-
-/** @internal */
-export function setLastRefreshTime(storageArea: Storage | undefined, storageKey: string): void {
-  try {
-    storageArea?.setItem(`${storageKey}_last_refresh`, Date.now().toString())
-  } catch {
-    // Ignore storage errors
-  }
-}
-
-/** @internal */
-export function getNextRefreshDelay(storageArea: Storage | undefined, storageKey: string): number {
-  const lastRefresh = getLastRefreshTime(storageArea, storageKey)
-  if (!lastRefresh) return 0
-
-  const now = Date.now()
-  const nextRefreshTime = lastRefresh + REFRESH_INTERVAL
-  return Math.max(0, nextRefreshTime - now)
-}
 
 function createTokenRefreshStream(
   token: string,
@@ -82,57 +49,6 @@ function createTokenRefreshStream(
   })
 }
 
-async function acquireTokenRefreshLock(
-  refreshFn: () => Promise<void>,
-  storageArea: Storage | undefined,
-  storageKey: string,
-): Promise<boolean> {
-  if (!navigator.locks) {
-    // If Web Locks API is not supported, perform an immediate, uncoordinated refresh.
-    // eslint-disable-next-line no-console
-    console.warn('Web Locks API not supported. Proceeding with uncoordinated refresh.')
-    await refreshFn()
-    setLastRefreshTime(storageArea, storageKey)
-    return true // Indicate success to allow stream processing, though it won't loop.
-  }
-
-  try {
-    // Attempt to acquire an exclusive lock for token refresh coordination.
-    // The callback handles the continuous refresh cycle while the lock is held.
-    const result = await navigator.locks.request(LOCK_NAME, {mode: 'exclusive'}, async (lock) => {
-      if (!lock) return false // Lock not granted
-
-      // Problematic infinite loop - needs redesign for graceful termination.
-      // This loop continuously refreshes the token at REFRESH_INTERVAL.
-      while (true) {
-        const delay = getNextRefreshDelay(storageArea, storageKey)
-        if (delay > 0) {
-          await new Promise((resolve) => setTimeout(resolve, delay))
-        }
-        try {
-          await refreshFn()
-          setLastRefreshTime(storageArea, storageKey)
-        } catch (error) {
-          // eslint-disable-next-line no-console
-          console.error('Token refresh failed within lock:', error)
-          // Decide how to handle errors - break, retry, etc.? Currently logs and continues.
-        }
-        // Wait for the next interval
-        await new Promise((resolve) => setTimeout(resolve, REFRESH_INTERVAL))
-      }
-      // Unreachable due to while(true)
-    })
-    // The promise from navigator.locks.request resolves with the callback's return value,
-    // but only if the callback finishes. The infinite loop prevents this.
-    return result === true
-  } catch (error) {
-    // Handle potential errors during the initial lock request itself.
-    // eslint-disable-next-line no-console
-    console.error('Failed to request token refresh lock:', error)
-    return false // Indicate lock acquisition failure.
-  }
-}
-
 function shouldRefreshToken(lastRefresh: number | undefined): boolean {
   if (!lastRefresh) return true
   const timeSinceLastRefresh = Date.now() - lastRefresh
@@ -140,6 +56,14 @@ function shouldRefreshToken(lastRefresh: number | undefined): boolean {
 }
 
 /**
+ * Periodically refreshes stamped auth tokens (those containing `-st`).
+ *
+ * Two triggers cause a refresh while the user stays logged in:
+ * - a 12-hour interval timer (only fires while the tab is visible)
+ * - the tab becoming visible again after `lastTokenRefresh` has gone stale
+ *
+ * Non-stamped tokens (e.g. personal access tokens) are never refreshed.
+ *
  * @internal
  */
 export const refreshStampedToken = ({
@@ -151,96 +75,27 @@ export const refreshStampedToken = ({
   const {clientFactory, apiHost, storageArea, storageKey} = state.get().options
 
   const refreshToken$ = state.observable.pipe(
-    map((storeState) => ({
-      authState: storeState.authState,
-      dashboardContext: storeState.dashboardContext,
-    })),
+    map((storeState) => storeState.authState),
     filter(
-      (
-        storeState,
-      ): storeState is {
-        authState: Extract<AuthState, {type: AuthStateType.LOGGED_IN}>
-        dashboardContext: AuthStoreState['dashboardContext']
-      } => storeState.authState.type === AuthStateType.LOGGED_IN,
+      (authState): authState is Extract<AuthState, {type: AuthStateType.LOGGED_IN}> =>
+        authState.type === AuthStateType.LOGGED_IN,
     ),
-    distinctUntilChanged(
-      (prev, curr) =>
-        prev.authState.type === curr.authState.type &&
-        prev.authState.token === curr.authState.token && // Only care about token for distinctness here
-        prev.dashboardContext === curr.dashboardContext,
-    ), // Make distinctness check explicit
-    filter((storeState) => storeState.authState.token.includes('-st')), // Ensure we only try to refresh stamped tokens
-    exhaustMap((storeState) => {
-      // USE exhaustMap instead of switchMap
-      // Create a function that performs a single refresh and updates state/storage
-      const performRefresh = async () => {
-        // Read the latest token directly from state inside refresh
-        const currentState = state.get()
-        if (currentState.authState.type !== AuthStateType.LOGGED_IN) {
-          logger.debug('Token refresh aborted - user logged out')
-          throw new Error('User logged out before refresh could complete') // Abort refresh
-        }
-        const currentToken = currentState.authState.token
-
-        logger.debug('Refreshing stamped token')
-        const response = await firstValueFrom(
-          createTokenRefreshStream(currentToken, clientFactory, apiHost),
-        )
-
-        logger.info('Token refreshed successfully')
-        state.set('setRefreshStampedToken', (prev) => ({
-          authState:
-            prev.authState.type === AuthStateType.LOGGED_IN
-              ? {...prev.authState, token: response.token}
-              : prev.authState,
-        }))
-        storageArea?.setItem(storageKey, JSON.stringify({token: response.token}))
-      }
-
-      if (storeState.dashboardContext) {
-        return new Observable<{token: string}>((subscriber) => {
-          const visibilityHandler = () => {
-            const currentState = state.get()
-            if (
-              document.visibilityState === 'visible' &&
-              currentState.authState.type === AuthStateType.LOGGED_IN &&
-              shouldRefreshToken(currentState.authState.lastTokenRefresh)
-            ) {
-              createTokenRefreshStream(
-                currentState.authState.token,
-                clientFactory,
-                apiHost,
-              ).subscribe({
-                next: (response) => {
-                  state.set('setRefreshStampedToken', (prev) => ({
-                    authState:
-                      prev.authState.type === AuthStateType.LOGGED_IN
-                        ? {
-                            ...prev.authState,
-                            token: response.token,
-                            lastTokenRefresh: Date.now(),
-                          }
-                        : prev.authState,
-                  }))
-                  subscriber.next(response)
-                },
-                error: (error) => subscriber.error(error),
-              })
-            }
-          }
-
-          const timerSubscription = timer(REFRESH_INTERVAL, REFRESH_INTERVAL)
-            .pipe(
-              filter(() => document.visibilityState === 'visible'),
-              switchMap(() => {
-                const currentState = state.get().authState
-                if (currentState.type !== AuthStateType.LOGGED_IN) {
-                  throw new Error('User logged out before refresh could complete')
-                }
-                return createTokenRefreshStream(currentState.token, clientFactory, apiHost)
-              }),
-            )
-            .subscribe({
+    distinctUntilChanged((prev, curr) => prev.token === curr.token),
+    filter((authState) => authState.token.includes('-st')), // Ensure we only try to refresh stamped tokens
+    exhaustMap(() =>
+      new Observable<{token: string}>((subscriber) => {
+        const visibilityHandler = () => {
+          const currentState = state.get()
+          if (
+            document.visibilityState === 'visible' &&
+            currentState.authState.type === AuthStateType.LOGGED_IN &&
+            shouldRefreshToken(currentState.authState.lastTokenRefresh)
+          ) {
+            createTokenRefreshStream(
+              currentState.authState.token,
+              clientFactory,
+              apiHost,
+            ).subscribe({
               next: (response) => {
                 state.set('setRefreshStampedToken', (prev) => ({
                   authState:
@@ -256,31 +111,48 @@ export const refreshStampedToken = ({
               },
               error: (error) => subscriber.error(error),
             })
-
-          document.addEventListener('visibilitychange', visibilityHandler)
-
-          return () => {
-            document.removeEventListener('visibilitychange', visibilityHandler)
-            timerSubscription.unsubscribe()
           }
-        }).pipe(
-          takeWhile(() => state.get().authState.type === AuthStateType.LOGGED_IN),
-          map((response: {token: string}) => ({token: response.token})),
-        )
-      }
+        }
 
-      // If not in dashboard context, use lock-based refresh
-      return from(acquireTokenRefreshLock(performRefresh, storageArea, storageKey)).pipe(
-        filter((hasLock) => hasLock),
-        map(() => {
-          const currentState = state.get().authState
-          if (currentState.type !== AuthStateType.LOGGED_IN) {
-            throw new Error('User logged out before refresh could complete')
-          }
-          return {token: currentState.token} as const
-        }),
-      )
-    }),
+        const timerSubscription = timer(REFRESH_INTERVAL, REFRESH_INTERVAL)
+          .pipe(
+            filter(() => document.visibilityState === 'visible'),
+            switchMap(() => {
+              const currentState = state.get().authState
+              if (currentState.type !== AuthStateType.LOGGED_IN) {
+                throw new Error('User logged out before refresh could complete')
+              }
+              return createTokenRefreshStream(currentState.token, clientFactory, apiHost)
+            }),
+          )
+          .subscribe({
+            next: (response) => {
+              state.set('setRefreshStampedToken', (prev) => ({
+                authState:
+                  prev.authState.type === AuthStateType.LOGGED_IN
+                    ? {
+                        ...prev.authState,
+                        token: response.token,
+                        lastTokenRefresh: Date.now(),
+                      }
+                    : prev.authState,
+              }))
+              subscriber.next(response)
+            },
+            error: (error) => subscriber.error(error),
+          })
+
+        document.addEventListener('visibilitychange', visibilityHandler)
+
+        return () => {
+          document.removeEventListener('visibilitychange', visibilityHandler)
+          timerSubscription.unsubscribe()
+        }
+      }).pipe(
+        takeWhile(() => state.get().authState.type === AuthStateType.LOGGED_IN),
+        map((response: {token: string}) => ({token: response.token})),
+      ),
+    ),
   )
 
   return refreshToken$.subscribe({

package/src/client/liveEvents.test.ts

@@ -0,0 +1,151 @@
+import {
+  ConnectionFailedError,
+  CorsOriginError,
+  DisconnectError,
+  type LiveEvent,
+  type LiveEventMessage,
+  type SanityClient,
+} from '@sanity/client'
+import {of, Subject} from 'rxjs'
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {createSanityInstance, type SanityInstance} from '../store/createSanityInstance'
+import {type StateSource} from '../store/createStateSourceAction'
+import {getClientState} from './clientStore'
+import {LIVE_EVENTS_RETRY_DELAY, observeLiveEvents} from './liveEvents'
+
+vi.mock('./clientStore', () => ({getClientState: vi.fn()}))
+
+describe('observeLiveEvents', () => {
+  let instance: SanityInstance
+  let liveEventSubjects: Subject<LiveEvent>[]
+  let events: ReturnType<typeof vi.fn>
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    instance = createSanityInstance({projectId: 'test', dataset: 'test'})
+
+    liveEventSubjects = []
+    events = vi.fn().mockImplementation(() => {
+      const subject = new Subject<LiveEvent>()
+      liveEventSubjects.push(subject)
+      return subject
+    })
+
+    vi.mocked(getClientState).mockReturnValue({
+      observable: of({
+        config: vi.fn().mockReturnValue({token: 'token'}),
+        live: {events},
+      } as unknown as SanityClient),
+    } as StateSource<SanityClient>)
+  })
+
+  afterEach(() => {
+    instance.dispose()
+  })
+
+  it('emits only message events', () => {
+    const messages: LiveEventMessage[] = []
+    const subscription = observeLiveEvents(instance, {onCorsError: vi.fn()}).subscribe((message) =>
+      messages.push(message),
+    )
+
+    liveEventSubjects[0].next({type: 'welcome'} as LiveEvent)
+    liveEventSubjects[0].next({type: 'message', id: 'e1', tags: ['s1:a']} as LiveEvent)
+
+    expect(messages).toEqual([{type: 'message', id: 'e1', tags: ['s1:a']}])
+    subscription.unsubscribe()
+  })
+
+  it('reports CORS errors through onCorsError and completes without erroring', () => {
+    const onCorsError = vi.fn()
+    const error = vi.fn()
+    const complete = vi.fn()
+    observeLiveEvents(instance, {onCorsError}).subscribe({error, complete})
+
+    const corsError = new CorsOriginError({projectId: 'test'})
+    liveEventSubjects[0].error(corsError)
+
+    expect(onCorsError).toHaveBeenCalledWith(corsError)
+    expect(error).not.toHaveBeenCalled()
+    expect(complete).toHaveBeenCalled()
+  })
+
+  it('completes without retrying on DisconnectError', async () => {
+    vi.useFakeTimers()
+    try {
+      const error = vi.fn()
+      const complete = vi.fn()
+      observeLiveEvents(instance, {onCorsError: vi.fn()}).subscribe({error, complete})
+
+      liveEventSubjects[0].error(new DisconnectError('Server disconnected client'))
+      await vi.advanceTimersByTimeAsync(LIVE_EVENTS_RETRY_DELAY * 5)
+
+      expect(error).not.toHaveBeenCalled()
+      expect(complete).toHaveBeenCalled()
+      expect(events).toHaveBeenCalledTimes(1)
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('completes without retrying on a 4xx connection rejection', async () => {
+    vi.useFakeTimers()
+    try {
+      const error = vi.fn()
+      const complete = vi.fn()
+      observeLiveEvents(instance, {onCorsError: vi.fn()}).subscribe({error, complete})
+
+      // The server rejected the connection with a 401 (e.g. expired token) —
+      // it will keep rejecting, so retrying would reconnect once per second
+      // forever
+      liveEventSubjects[0].error(
+        new ConnectionFailedError('EventSource connection failed', {status: 401}),
+      )
+      await vi.advanceTimersByTimeAsync(LIVE_EVENTS_RETRY_DELAY * 5)
+
+      expect(error).not.toHaveBeenCalled()
+      expect(complete).toHaveBeenCalled()
+      expect(events).toHaveBeenCalledTimes(1)
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('retries a connection failure without a status (transient network failure)', async () => {
+    vi.useFakeTimers()
+    try {
+      const error = vi.fn()
+      const subscription = observeLiveEvents(instance, {onCorsError: vi.fn()}).subscribe({error})
+
+      // No status means the failure could be transient (native EventSource
+      // exposes no status) — reconnecting is correct here
+      liveEventSubjects[0].error(new ConnectionFailedError('EventSource connection failed'))
+      await vi.advanceTimersByTimeAsync(LIVE_EVENTS_RETRY_DELAY)
+
+      expect(events).toHaveBeenCalledTimes(2)
+      expect(error).not.toHaveBeenCalled()
+      subscription.unsubscribe()
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('retries the connection after server-initiated errors', async () => {
+    vi.useFakeTimers()
+    try {
+      const error = vi.fn()
+      const subscription = observeLiveEvents(instance, {onCorsError: vi.fn()}).subscribe({error})
+      expect(events).toHaveBeenCalledTimes(1)
+
+      liveEventSubjects[0].error(new Error('ChannelError'))
+      await vi.advanceTimersByTimeAsync(LIVE_EVENTS_RETRY_DELAY)
+
+      expect(events).toHaveBeenCalledTimes(2)
+      expect(error).not.toHaveBeenCalled()
+      subscription.unsubscribe()
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+})

package/src/client/liveEvents.ts

@@ -0,0 +1,107 @@
+import {
+  ConnectionFailedError,
+  CorsOriginError,
+  DisconnectError,
+  type LiveEventMessage,
+} from '@sanity/client'
+import {catchError, defer, EMPTY, filter, type Observable, retry, switchMap} from 'rxjs'
+
+import {type DocumentResource} from '../config/sanityConfig'
+import {type SanityInstance} from '../store/createSanityInstance'
+import {getClientState} from './clientStore'
+
+/**
+ * All live-events subscriptions must use identical connection options
+ * (API version, request tag, `includeDrafts`): `@sanity/client` caches the
+ * underlying EventSource per URL + options, so divergent options would
+ * silently split what should be a single shared connection.
+ */
+const LIVE_EVENTS_API_VERSION = 'v2025-05-06'
+
+/**
+ * Delay before re-establishing the live events connection after a
+ * server-initiated error (e.g. ChannelError, MessageError). Live errors are
+ * retried rather than surfaced because an errored live connection would
+ * otherwise poison the consuming store. Plain connection drops never reach
+ * this — they are reconnected inside `@sanity/client`.
+ *
+ * @internal
+ */
+export const LIVE_EVENTS_RETRY_DELAY = 1000
+
+/**
+ * Options for {@link observeLiveEvents}.
+ * @internal
+ */
+export interface ObserveLiveEventsOptions {
+  /** Resource to scope the underlying client and live connection to. */
+  resource?: DocumentResource
+  /**
+   * Called when the connection fails due to a CORS misconfiguration. The
+   * error is swallowed (the stream never errors; it idles until a new client
+   * is emitted) so consumers can surface it as store state instead of a
+   * stream error.
+   */
+  onCorsError: (error: unknown) => void
+}
+
+/**
+ * Emits Live Content API messages for a dataset so consumers can invalidate
+ * fetched data via sync tags.
+ *
+ * All consumers observe the same underlying EventSource connection:
+ * `@sanity/client` caches the live-events stream per URL and connection
+ * options, and every subscription made through this function uses the same
+ * API version and request tag.
+ *
+ * @internal
+ */
+export function observeLiveEvents(
+  instance: SanityInstance,
+  {resource, onCorsError}: ObserveLiveEventsOptions,
+): Observable<LiveEventMessage> {
+  return getClientState(instance, {
+    apiVersion: LIVE_EVENTS_API_VERSION,
+    resource,
+  }).observable.pipe(
+    switchMap((client) =>
+      defer(() =>
+        client.live.events({includeDrafts: !!client.config().token, tag: 'live-events'}),
+      ).pipe(
+        catchError((error) => {
+          if (error instanceof CorsOriginError) {
+            // Swallow CORS errors without bubbling up so that they can be
+            // handled by the consumer (e.g. shown via the Cors Error component)
+            onCorsError(error)
+            return EMPTY
+          }
+          if (error instanceof DisconnectError) {
+            // The server explicitly told this client to stop reconnecting —
+            // end live updates without erroring (consumers keep serving data,
+            // they just stop receiving live invalidation)
+            return EMPTY
+          }
+          if (
+            error instanceof ConnectionFailedError &&
+            typeof error.status === 'number' &&
+            error.status >= 400 &&
+            error.status < 500
+          ) {
+            // The server rejected the connection with a 4xx (e.g. a 401 from
+            // an expired token) — it will keep rejecting, so retrying would
+            // reconnect once per second forever. End live updates like a
+            // DisconnectError. A ConnectionFailedError without a status stays
+            // retryable: it may be a transient network failure.
+            return EMPTY
+          }
+          throw error
+        }),
+        // Server-initiated live errors (e.g. ChannelError, MessageError) are
+        // retried, not surfaced. Dropped connections are already reconnected
+        // inside @sanity/client.
+        retry({delay: LIVE_EVENTS_RETRY_DELAY}),
+      ),
+    ),
+    filter((e): e is LiveEventMessage => e.type === 'message'),
+  )
+}

package/src/document/actions.ts

@@ -68,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
 }
 
 /**
@@ -201,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
  */
@@ -217,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
  */
@@ -233,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.
@@ -240,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<
@@ -249,8 +281,10 @@ export function editDocument<
 >(
   doc: DocumentHandle<TDocumentType, TDataset, TProjectId>,
   patches?: PatchOperations | PatchOperations[] | SanityMutatePatchMutation,
+  options?: EditDocumentOptions,
 ): EditDocumentAction<TDocumentType, TDataset, TProjectId> {
   const effectiveDocumentId = getEffectiveDocumentId(doc)
+  const preserveOperations = options?.preserveOperations && {preserveOperations: true as const}
 
   if (isSanityMutatePatch(patches)) {
     const converted = convertSanityMutatePatch(patches) ?? []
@@ -259,6 +293,7 @@ export function editDocument<
       type: 'document.edit',
       documentId: effectiveDocumentId,
       patches: converted,
+      ...preserveOperations,
     }
   }
 
@@ -267,6 +302,7 @@ export function editDocument<
     type: 'document.edit',
     documentId: effectiveDocumentId,
     ...(patches && {patches: Array.isArray(patches) ? patches : [patches]}),
+    ...preserveOperations,
   }
 }