@sanity/sdk 3.6.0 → 3.7.0-next.20260929183120

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/sdk",
-  "version": "3.6.0",
+  "version": "3.7.0-next.20260929183120",
   "private": false,
   "description": "Sanity SDK",
   "keywords": [

package/src/_exports/index.ts

@@ -186,6 +186,7 @@ export {
   type DocumentUnpublishedEvent,
   type TransactionAcceptedEvent,
   type TransactionRevertedEvent,
+  type TransactionSubmissionFailedEvent,
 } from '../document/events'
 export {type JsonMatch} from '../document/patchOperations'
 export {type DocumentPermissionsResult, type PermissionDeniedReason} from '../document/permissions'

package/src/auth/authStore.test.ts

@@ -542,6 +542,38 @@ describe('authStore', () => {
       expect(checkForCookieAuth).not.toHaveBeenCalled()
     })
 
+    it('switches to the renewed token when the Studio token source emits one', () => {
+      // Studio broadcasts the new token to every open tab when the user logs in
+      // again in any of them, so a tab with an expired session receives it
+      // without reloading
+      let tokenObserver!: {next: (token: string | null) => void}
+      const mockSubscribe = vi.fn((observer: {next: (token: string | null) => void}) => {
+        tokenObserver = observer
+        return {unsubscribe: vi.fn()}
+      })
+      const mockTokenSource = {subscribe: mockSubscribe}
+
+      instance = createSanityInstance({
+        projectId: 'studio-project',
+        dataset: 'production',
+        studio: {
+          auth: {token: mockTokenSource},
+        },
+      })
+
+      getAuthState(instance)
+      tokenObserver.next('expired-session-token')
+      expect(getTokenState(instance).getCurrent()).toBe('expired-session-token')
+
+      tokenObserver.next('renewed-session-token')
+
+      expect(getAuthState(instance).getCurrent()).toMatchObject({
+        type: AuthStateType.LOGGED_IN,
+        token: 'renewed-session-token',
+      })
+      expect(getTokenState(instance).getCurrent()).toBe('renewed-session-token')
+    })
+
     it('falls back to default auth (storage token) when studio mode is disabled', () => {
       const storageToken = 'regular-storage-token'
       vi.mocked(getTokenFromStorage).mockReturnValue(storageToken)

package/src/document/documentConstants.ts

@@ -35,3 +35,14 @@ export const OUT_OF_SYNC_RETRY_COUNT = 5
  */
 export const ACL_RETRY_BASE_DELAY = 500
 export const ACL_RETRY_MAX_DELAY = 10_000
+
+/**
+ * Base delay (ms) before resubmitting an outgoing transaction whose submission
+ * failed with a retryable error (a network error, a 5xx, 408 or 429 response,
+ * a 401 from an expired session, or a 409 `transactionConflictError` from
+ * contention while committing). Backoff doubles on each successive
+ * attempt, capped at {@link SUBMISSION_RETRY_MAX_DELAY}. A change of client
+ * (new credentials) triggers the next attempt immediately.
+ */
+export const SUBMISSION_RETRY_BASE_DELAY = 1000
+export const SUBMISSION_RETRY_MAX_DELAY = 10_000

package/src/document/documentStore.test.ts

@@ -15,6 +15,7 @@ import {
   type UnfilteredResponseQueryOptions,
   type WelcomeEvent,
 } from '@sanity/client'
+import {makePatches, stringifyPatches} from '@sanity/diff-match-patch'
 import {diffValue} from '@sanity/diff-patch'
 import {DocumentId, getDraftId, getPublishedId} from '@sanity/id-utils'
 import {type Mutation, type SanityDocument} from '@sanity/types'
@@ -60,6 +61,7 @@ import {
 } from './documentStore'
 import {
   type ActionErrorEvent,
+  type DocumentEvent,
   type DocumentRemotePatchesEvent,
   type TransactionRevertedEvent,
 } from './events'
@@ -820,7 +822,13 @@ it('reverts failed outgoing transaction locally', async () => {
   const clientActionMockImplementation = vi.mocked(client.action).getMockImplementation()!
   vi.mocked(client.action).mockImplementation(async (...args) => {
     const [, {transactionId} = {}] = args
-    if (transactionId === 'force-revert') throw new Error('example error')
+    if (transactionId === 'force-revert') {
+      throw new ClientError({
+        statusCode: 400,
+        headers: {},
+        body: {error: 'Bad Request', message: 'example error'},
+      })
+    }
     return await clientActionMockImplementation(...args)
   })
 
@@ -868,7 +876,7 @@ it('reverts failed outgoing transaction locally', async () => {
 
   await expect(revertedEventPromise).resolves.toMatchObject({
     type: 'reverted',
-    message: 'example error',
+    message: 'Bad Request - example error',
     outgoing: {transactionId: 'force-revert'},
   })
 
@@ -1428,6 +1436,9 @@ vi.mock('./sharedListener.ts', () => {
   }
 })
 
+// read through getters so a test can lengthen the submission backoff
+const submissionRetryDelay = vi.hoisted(() => ({ms: 5}))
+
 vi.mock('./documentConstants.ts', async (importOriginal) => {
   const original = await importOriginal<typeof import('./documentConstants')>()
   return {
@@ -1439,6 +1450,12 @@ vi.mock('./documentConstants.ts', async (importOriginal) => {
     OUT_OF_SYNC_RETRY_COUNT: 2,
     ACL_RETRY_BASE_DELAY: 0,
     ACL_RETRY_MAX_DELAY: 0,
+    get SUBMISSION_RETRY_BASE_DELAY() {
+      return submissionRetryDelay.ms
+    },
+    get SUBMISSION_RETRY_MAX_DELAY() {
+      return submissionRetryDelay.ms
+    },
   }
 })
 
@@ -2033,3 +2050,277 @@ it('keeps its retry budget per failure, not per listener', async () => {
   expect(() => documentState.getCurrent()).not.toThrow()
   unsubscribe()
 })
+
+it('keeps edits made while the session is expired and submits them after re-authentication', async () => {
+  // Same status and body the actions API returned on an expired SAML session
+  const sessionExpired = new ClientError({
+    statusCode: 401,
+    headers: {},
+    body: {statusCode: 401, error: 'Unauthorized', message: 'Session not found'},
+  })
+  let sessionValid = true
+  let rejectedAttempts = 0
+  const actualAction = vi.mocked(client.action).getMockImplementation()!
+  vi.mocked(client.action).mockImplementation(async (...args) => {
+    if (!sessionValid) {
+      rejectedAttempts++
+      throw sessionExpired
+    }
+    return await actualAction(...args)
+  })
+
+  const events: DocumentEvent[] = []
+  const unsubscribeEvents = subscribeDocumentEvents(instance, {
+    resource,
+    eventHandler: (e) => events.push(e),
+  })
+
+  const doc = createDocumentHandle({
+    documentId: DocumentId('session-expiry'),
+    documentType: 'article',
+  })
+  const state = getDocumentState<TestDocument>(instance, doc)
+  const syncStatus = getDocumentSyncStatus(instance, doc)
+  const unsubscribe = state.subscribe()
+  const unsubscribeSync = syncStatus.subscribe()
+
+  await applyDocumentActions(instance, {
+    actions: [createDocument(doc), editDocument(doc, {set: {title: 'saved'}})],
+    resource,
+  }).then((r) => r.submitted())
+
+  // the session expires while the user keeps typing, one batch per flush
+  sessionValid = false
+  const results = ['saved, one', 'saved, one two', 'saved, one two three'].map((title) =>
+    applyDocumentActions(instance, {
+      actions: [editDocument(doc, {set: {title}})],
+      resource,
+      disableBatching: true,
+    }),
+  )
+  await expect.poll(() => rejectedAttempts).toBeGreaterThanOrEqual(3)
+
+  // nothing is reverted: the edits stay on screen and the document reports
+  // that it is not in sync
+  expect(events.filter((e) => e.type === 'reverted')).toEqual([])
+  expect(events.filter((e) => e.type === 'submission-failed').slice(0, 3)).toMatchObject([
+    {message: 'Unauthorized - Session not found', attempt: 1},
+    {message: 'Unauthorized - Session not found', attempt: 2},
+    {message: 'Unauthorized - Session not found', attempt: 3},
+  ])
+  expect(state.getCurrent()?.title).toBe('saved, one two three')
+  expect(syncStatus.getCurrent()).toBe(false)
+
+  // the user re-authenticates and every edit lands
+  sessionValid = true
+  await Promise.all(results.map((r) => r.then((x) => x.submitted())))
+  expect(state.getCurrent()?.title).toBe('saved, one two three')
+  expect(syncStatus.getCurrent()).toBe(true)
+  expect(events.filter((e) => e.type === 'reverted')).toEqual([])
+
+  unsubscribeSync()
+  unsubscribe()
+  unsubscribeEvents()
+  vi.mocked(client.action).mockImplementation(actualAction)
+})
+
+it('retries a submission that failed with a server error or a dropped connection', async () => {
+  const failures: unknown[] = [
+    new ServerError({statusCode: 503, headers: {}, body: {}}),
+    new Error('Request error while attempting to reach https://p.api.sanity.io'),
+  ]
+  const actualAction = vi.mocked(client.action).getMockImplementation()!
+  vi.mocked(client.action).mockImplementation(async (...args) => {
+    const [, {transactionId} = {}] = args
+    if (transactionId === 'flaky' && failures.length) throw failures.shift()
+    return await actualAction(...args)
+  })
+
+  const doc = createDocumentHandle({
+    documentId: DocumentId('flaky-network'),
+    documentType: 'article',
+  })
+  const state = getDocumentState<TestDocument>(instance, doc)
+  const unsubscribe = state.subscribe()
+
+  await applyDocumentActions(instance, {actions: [createDocument(doc)], resource}).then((r) =>
+    r.submitted(),
+  )
+  await applyDocumentActions(instance, {
+    actions: [editDocument(doc, {set: {title: 'kept'}})],
+    transactionId: 'flaky',
+    resource,
+  }).then((r) => r.submitted())
+
+  expect(failures).toEqual([])
+  expect(state.getCurrent()?.title).toBe('kept')
+
+  unsubscribe()
+  vi.mocked(client.action).mockImplementation(actualAction)
+})
+
+it('treats transactionAlreadyExistsError on a retry as an ack of the earlier attempt', async () => {
+  // the first attempt is committed but its response is lost; the retry then
+  // collides with the transaction ID the server already recorded
+  const actualAction = vi.mocked(client.action).getMockImplementation()!
+  let attempts = 0
+  vi.mocked(client.action).mockImplementation(async (...args) => {
+    const [, {transactionId} = {}] = args
+    if (transactionId !== 'lost-response') return await actualAction(...args)
+    attempts++
+    if (attempts === 1) {
+      await actualAction(...args)
+      throw new Error('Request error while attempting to reach https://p.api.sanity.io')
+    }
+    throw new ClientError({
+      statusCode: 409,
+      headers: {},
+      body: {
+        error: {
+          type: 'transactionAlreadyExistsError',
+          description: 'The transaction ID "lost-response" already exists',
+        },
+      },
+    })
+  })
+
+  const reverted: TransactionRevertedEvent[] = []
+  const unsubscribeEvents = subscribeDocumentEvents(instance, {
+    resource,
+    eventHandler: (e) => {
+      if (e.type === 'reverted') reverted.push(e)
+    },
+  })
+
+  const doc = createDocumentHandle({
+    documentId: DocumentId('lost-response'),
+    documentType: 'article',
+  })
+  const state = getDocumentState<TestDocument>(instance, doc)
+  const unsubscribe = state.subscribe()
+
+  await applyDocumentActions(instance, {actions: [createDocument(doc)], resource}).then((r) =>
+    r.submitted(),
+  )
+  await applyDocumentActions(instance, {
+    actions: [editDocument(doc, {set: {title: 'committed once'}})],
+    transactionId: 'lost-response',
+    resource,
+  }).then((r) => r.submitted())
+
+  expect(attempts).toBe(2)
+  expect(reverted).toEqual([])
+  expect(state.getCurrent()?.title).toBe('committed once')
+
+  unsubscribe()
+  unsubscribeEvents()
+  vi.mocked(client.action).mockImplementation(actualAction)
+})
+
+it('resubmits held text edits as soon as the credentials change, in order and once each', async () => {
+  // The sequence from a writer whose session expired mid-edit: a text field
+  // written with operation-preserving diffMatchPatch edits (what
+  // @portabletext/plugin-sdk-value sends), every write on the old token
+  // rejected with a 401, then a new token from logging in again in another tab
+  const client$ = (getClientState as () => StateSource<SanityClient>)()
+    .observable as ReplaySubject<SanityClient>
+  const actualAction = vi.mocked(client.action).getMockImplementation()!
+  let sessionValid = true
+  let rejectedAttempts = 0
+  vi.mocked(client.action).mockImplementation(async (...args) => {
+    if (sessionValid) return await actualAction(...args)
+    rejectedAttempts++
+    throw new ClientError({
+      statusCode: 401,
+      headers: {},
+      body: {statusCode: 401, error: 'Unauthorized', message: 'Session not found'},
+    })
+  })
+  // the client store builds a new client when the token changes; it carries
+  // the renewed token, so the server accepts its writes
+  const renewedClient = {
+    ...client,
+    observable: {
+      ...client.observable,
+      action: (...args: Parameters<typeof actualAction>) => from(actualAction(...args)),
+    },
+  } as SanityClient
+
+  const reverted: TransactionRevertedEvent[] = []
+  const unsubscribeEvents = subscribeDocumentEvents(instance, {
+    resource,
+    eventHandler: (e) => {
+      if (e.type === 'reverted') reverted.push(e)
+    },
+  })
+
+  const doc = createDocumentHandle({
+    documentId: DocumentId('renewed-session'),
+    documentType: 'article',
+  })
+  const state = getDocumentState<TestDocument>(instance, doc)
+  const unsubscribe = state.subscribe()
+
+  const typeText = (before: string, after: string) =>
+    applyDocumentActions(instance, {
+      actions: [
+        {
+          ...editDocument(doc, {
+            diffMatchPatch: {title: stringifyPatches(makePatches(before, after))},
+          }),
+          preserveOperations: true,
+        },
+      ],
+      resource,
+      disableBatching: true,
+    })
+
+  submissionRetryDelay.ms = 60_000
+  try {
+    await applyDocumentActions(instance, {
+      actions: [createDocument(doc), editDocument(doc, {set: {title: 'Start:'}})],
+      resource,
+    }).then((r) => r.submitted())
+
+    sessionValid = false
+    const results = [
+      typeText('Start:', 'Start: the'),
+      typeText('Start: the', 'Start: the mayor'),
+      typeText('Start: the mayor', 'Start: the mayor said'),
+    ]
+
+    // the first write is rejected and the 60s backoff holds its retry, while
+    // every edit stays applied locally
+    await expect.poll(() => rejectedAttempts).toBe(1)
+    await new Promise((resolve) => setTimeout(resolve, 100))
+    expect(rejectedAttempts).toBe(1)
+    expect(state.getCurrent()?.title).toBe('Start: the mayor said')
+
+    // logging in again: the held write and the queued ones land long before
+    // the backoff would have elapsed
+    client$.next(renewedClient)
+    await Promise.race([
+      Promise.all(results.map((r) => r.then((x) => x.submitted()))),
+      new Promise((_, reject) =>
+        setTimeout(() => reject(new Error('edits were not resubmitted on the new client')), 2000),
+      ),
+    ])
+
+    expect(rejectedAttempts).toBe(1)
+    expect(reverted).toEqual([])
+    expect(state.getCurrent()?.title).toBe('Start: the mayor said')
+    // the server copy has each edit applied exactly once
+    await expect(
+      client.fetch<string>(
+        '*[_id == $id][0].title',
+        {id: getDraftId(DocumentId('renewed-session'))},
+        {filterResponse: true},
+      ),
+    ).resolves.toBe('Start: the mayor said')
+  } finally {
+    submissionRetryDelay.ms = 5
+    unsubscribe()
+    unsubscribeEvents()
+    vi.mocked(client.action).mockImplementation(actualAction)
+  }
+})

package/src/document/documentStore.ts

@@ -1,10 +1,18 @@
-import {type Action, ClientError, CorsOriginError, type Mutation, ServerError} from '@sanity/client'
+import {
+  type Action,
+  ClientError,
+  CorsOriginError,
+  type Mutation,
+  type SanityClient,
+  ServerError,
+} from '@sanity/client'
 import {DocumentId, getDraftId} from '@sanity/id-utils'
 import {jsonMatch} from '@sanity/json-match'
 import {type ExprNode} from 'groq-js'
 import {
   catchError,
   concatMap,
+  defer,
   distinctUntilChanged,
   EMPTY,
   filter,
@@ -16,6 +24,7 @@ import {
   Observable,
   of,
   pairwise,
+  race,
   retry,
   startWith,
   Subject,
@@ -54,6 +63,8 @@ import {
   OUT_OF_SYNC_RETRY_BASE_DELAY,
   OUT_OF_SYNC_RETRY_COUNT,
   OUT_OF_SYNC_RETRY_MAX_DELAY,
+  SUBMISSION_RETRY_BASE_DELAY,
+  SUBMISSION_RETRY_MAX_DELAY,
 } from './documentConstants'
 import {
   type DocumentEvent,
@@ -86,6 +97,7 @@ import {
   type UnverifiedDocumentRevision,
 } from './reducers'
 import {createFetchDocument, createSharedListener, type SharedListener} from './sharedListener'
+import {classifySubmissionError} from './submissionErrors'
 
 export interface DocumentStoreState {
   documentStates: {[TDocumentId in string]?: DocumentState}
@@ -415,12 +427,39 @@ const subscribeToQueuedAndApplyNextTransaction = ({
     .subscribe({error: (error) => state.set('setError', {error})})
 }
 
+const getErrorMessage = (error: unknown) =>
+  error instanceof Error ? error.message : 'Request failed'
+
+const submitOutgoingTransaction = (client: SanityClient, outgoing: OutgoingTransaction) => {
+  // liveEdit transactions route to the mutations API; everything else routes
+  // to the actions API. processActions rejects transactions that mix the two,
+  // and reducers won't batch across that boundary, so a batch is always
+  // entirely liveEdit or entirely not.
+  if (outgoing.actions.some((action) => !isReleaseAction(action) && action.liveEdit)) {
+    return client.observable.mutate(outgoing.outgoingMutations as Mutation[], {
+      transactionId: outgoing.transactionId,
+      visibility: 'async',
+      returnDocuments: false,
+      returnFirst: false,
+      tag: 'document.mutate',
+      skipCrossDatasetReferenceValidation: true,
+    })
+  }
+
+  return client.observable.action(outgoing.outgoingActions as Action[], {
+    transactionId: outgoing.transactionId,
+    skipCrossDatasetReferenceValidation: true,
+    tag: 'document.action',
+  })
+}
+
 const subscribeToAppliedAndSubmitNextTransaction = ({
   state,
   instance,
   key: {resource},
 }: StoreContext<DocumentStoreState, BoundResourceKey>) => {
   const {events} = state.get()
+  const clients$ = getClientState(instance, {apiVersion: API_VERSION, resource}).observable
 
   return state.observable
     .pipe(
@@ -439,51 +478,59 @@ const subscribeToAppliedAndSubmitNextTransaction = ({
       tap((next) => state.set('transitionAppliedTransactionsToOutgoing', next)),
       map((s) => s.outgoing),
       distinctUntilChanged(),
-      withLatestFrom(
-        getClientState(instance, {
-          apiVersion: API_VERSION,
-          resource,
-        }).observable,
-      ),
-      concatMap(([outgoing, client]) => {
+      withLatestFrom(clients$),
+      concatMap(([outgoing, initialClient]) => {
         if (!outgoing) return EMPTY
 
-        const revertOnError = catchError((error: unknown) => {
-          state.set('revertOutgoingTransaction', revertOutgoingTransaction)
-          const message = error instanceof Error ? error.message : 'Request failed'
-          events.next({type: 'reverted', message, outgoing, error})
-          return EMPTY
-        })
-
-        const toResult = map((result: unknown) => ({
-          result: result as DocumentTransactionSubmissionResult,
-          outgoing,
-        }))
-
-        // liveEdit transactions route to the mutations API; everything else routes
-        // to the actions API. processActions rejects transactions that mix the two,
-        // and reducers won't batch across that boundary, so a batch is always
-        // entirely liveEdit or entirely not.
-        if (outgoing.actions.some((action) => !isReleaseAction(action) && action.liveEdit)) {
-          return client.observable
-            .mutate(outgoing.outgoingMutations as Mutation[], {
-              transactionId: outgoing.transactionId,
-              visibility: 'async',
-              returnDocuments: false,
-              returnFirst: false,
-              tag: 'document.mutate',
-              skipCrossDatasetReferenceValidation: true,
-            })
-            .pipe(revertOnError, toResult)
-        }
+        // the client that made the latest attempt. the client store rebuilds
+        // its clients when the token changes, so a different client means
+        // different credentials and a retry after a 401 can go right away
+        let attemptClient: SanityClient | undefined
 
-        return client.observable
-          .action(outgoing.outgoingActions as Action[], {
-            transactionId: outgoing.transactionId,
-            skipCrossDatasetReferenceValidation: true,
-            tag: 'document.action',
-          })
-          .pipe(revertOnError, toResult)
+        return defer(() => (attemptClient ? clients$.pipe(first()) : of(initialClient))).pipe(
+          concatMap((client) => {
+            attemptClient = client
+            return submitOutgoingTransaction(client, outgoing)
+          }),
+          retry({
+            delay: (error: unknown, retryCount) => {
+              if (classifySubmissionError(error) !== 'retry') return throwError(() => error)
+
+              // keep the transaction and its optimistic local state. the
+              // document stays out of sync (see `getDocumentSyncStatus`) and
+              // later edits queue behind this transaction until it lands
+              events.next({
+                type: 'submission-failed',
+                message: getErrorMessage(error),
+                error,
+                outgoing,
+                attempt: retryCount,
+              })
+              const backoff = Math.min(
+                SUBMISSION_RETRY_BASE_DELAY * 2 ** (retryCount - 1),
+                SUBMISSION_RETRY_MAX_DELAY,
+              )
+              return race(
+                timer(backoff),
+                clients$.pipe(first((client) => client !== attemptClient)),
+              )
+            },
+          }),
+          catchError((error: unknown) => {
+            if (classifySubmissionError(error) === 'accepted') {
+              // an earlier attempt was committed and only its response was
+              // lost, so this is an ack
+              return of({transactionId: outgoing.transactionId, documentIds: [], results: []})
+            }
+            state.set('revertOutgoingTransaction', revertOutgoingTransaction)
+            events.next({type: 'reverted', message: getErrorMessage(error), outgoing, error})
+            return EMPTY
+          }),
+          map((result: unknown) => ({
+            result: result as DocumentTransactionSubmissionResult,
+            outgoing,
+          })),
+        )
       }),
       tap(({outgoing, result}) => {
         state.set('cleanupOutgoingTransaction', cleanupOutgoingTransaction)

package/src/document/events.ts

@@ -14,6 +14,7 @@ export type DocumentTransactionSubmissionResult =
 export type DocumentEvent =
   | ActionErrorEvent
   | TransactionRevertedEvent
+  | TransactionSubmissionFailedEvent
   | TransactionAcceptedEvent
   | DocumentRebaseErrorEvent
   | DocumentEditedEvent
@@ -55,6 +56,22 @@ export interface TransactionRevertedEvent {
   error: unknown
   outgoing: OutgoingTransaction
 }
+/**
+ * @beta
+ * Event emitted when submitting a transaction fails with an error the store
+ * retries: a network failure, a 5xx, 408 or 429 response, a 401 (for example
+ * an expired session), or a 409 `transactionConflictError` (contention while
+ * committing). The transaction and its local changes are kept
+ * and submitted again, so the document stays out of sync until an attempt
+ * succeeds. Emitted once per failed attempt; `attempt` starts at 1.
+ */
+export interface TransactionSubmissionFailedEvent {
+  type: 'submission-failed'
+  message: string
+  error: unknown
+  outgoing: OutgoingTransaction
+  attempt: number
+}
 /**
  * @beta
  * Event emitted when an attempt to apply local changes to a modified remote document fails.
@@ -188,12 +205,10 @@ export function getDocumentEvents(outgoing: OutgoingTransaction): DocumentEvent[
   )
 
   return Object.entries(documentIdsByAction).flatMap(([actionType, documentIds]) =>
-    Array.from(documentIds ?? []).map(
-      (documentId): DocumentEvent => ({
-        type: actionMap[actionType as MappedActionType],
-        documentId,
-        outgoing,
-      }),
-    ),
+    Array.from(documentIds ?? []).map((documentId): DocumentEvent => ({
+      type: actionMap[actionType as MappedActionType],
+      documentId,
+      outgoing,
+    })),
   )
 }