@sanity/sdk 2.20.2 → 2.21.0

package/src/document/documentStore.test.ts

@@ -10,10 +10,12 @@ import {
   type RawQueryResponse,
   type ResponseQueryOptions,
   type SanityClient,
+  ServerError,
   type SingleActionResult,
   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'
@@ -55,6 +57,7 @@ import {
 } from './documentStore'
 import {
   type ActionErrorEvent,
+  type DocumentEvent,
   type DocumentRemotePatchesEvent,
   type TransactionRevertedEvent,
 } from './events'
@@ -786,7 +789,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)
   })
 
@@ -834,7 +843,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'},
   })
 
@@ -1406,6 +1415,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 {
@@ -1416,6 +1428,12 @@ vi.mock('./documentConstants.ts', async (importOriginal) => {
     OUT_OF_SYNC_RETRY_MAX_DELAY: 0,
     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
+    },
   }
 })
 
@@ -1820,3 +1838,277 @@ beforeEach(() => {
   } as SanityClient
   client$.next(client)
 })
+
+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,4 +1,10 @@
-import {type Action, ClientError, CorsOriginError, type Mutation} from '@sanity/client'
+import {
+  type Action,
+  ClientError,
+  CorsOriginError,
+  type Mutation,
+  type SanityClient,
+} from '@sanity/client'
 import {DocumentId, getDraftId, getPublishedId, getVersionId} from '@sanity/id-utils'
 import {jsonMatch} from '@sanity/json-match'
 import {type SanityDocument} from 'groq'
@@ -6,6 +12,7 @@ import {type ExprNode} from 'groq-js'
 import {
   catchError,
   concatMap,
+  defer,
   distinctUntilChanged,
   EMPTY,
   filter,
@@ -17,6 +24,7 @@ import {
   Observable,
   of,
   pairwise,
+  race,
   retry,
   startWith,
   Subject,
@@ -54,6 +62,8 @@ import {
   INITIAL_OUTGOING_THROTTLE_TIME,
   OUT_OF_SYNC_RETRY_BASE_DELAY,
   OUT_OF_SYNC_RETRY_MAX_DELAY,
+  SUBMISSION_RETRY_BASE_DELAY,
+  SUBMISSION_RETRY_MAX_DELAY,
 } from './documentConstants'
 import {
   type DocumentEvent,
@@ -85,6 +95,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}
@@ -393,12 +404,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(
@@ -417,51 +455,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.

package/src/document/submissionErrors.test.ts

@@ -0,0 +1,63 @@
+import {ClientError, CorsOriginError, ServerError} from '@sanity/client'
+import {describe, expect, it} from 'vitest'
+
+import {classifySubmissionError} from './submissionErrors'
+
+const clientError = (statusCode: number, body: unknown = {}) =>
+  new ClientError({statusCode, headers: {}, body})
+
+describe('classifySubmissionError', () => {
+  it('retries an expired or missing session', () => {
+    expect(
+      classifySubmissionError(
+        clientError(401, {statusCode: 401, error: 'Unauthorized', message: 'Session not found'}),
+      ),
+    ).toBe('retry')
+  })
+
+  it('retries server errors, timeouts, rate limits and network failures', () => {
+    expect(classifySubmissionError(new ServerError({statusCode: 503, headers: {}, body: {}}))).toBe(
+      'retry',
+    )
+    expect(classifySubmissionError(clientError(408))).toBe('retry')
+    expect(classifySubmissionError(clientError(429))).toBe('retry')
+    expect(classifySubmissionError(new Error('Request error while attempting to reach'))).toBe(
+      'retry',
+    )
+    expect(classifySubmissionError('not an error')).toBe('retry')
+  })
+
+  it('retries a transaction that hit contention while committing', () => {
+    expect(
+      classifySubmissionError(
+        clientError(409, {
+          error: {type: 'transactionConflictError', description: 'transaction conflict'},
+        }),
+      ),
+    ).toBe('retry')
+  })
+
+  it('treats an already recorded transaction ID as an ack', () => {
+    expect(
+      classifySubmissionError(
+        clientError(409, {
+          error: {type: 'transactionAlreadyExistsError', description: 'already exists'},
+        }),
+      ),
+    ).toBe('accepted')
+  })
+
+  it('reverts transactions the server rejected', () => {
+    for (const statusCode of [400, 402, 403, 404, 410, 412, 413, 422]) {
+      expect(classifySubmissionError(clientError(statusCode))).toBe('revert')
+    }
+    expect(
+      classifySubmissionError(
+        clientError(409, {
+          error: {type: 'documentRevisionIDDoesNotMatchError', description: 'revision mismatch'},
+        }),
+      ),
+    ).toBe('revert')
+    expect(classifySubmissionError(new CorsOriginError({projectId: 'p'}))).toBe('revert')
+  })
+})

package/src/document/submissionErrors.ts

@@ -0,0 +1,51 @@
+import {ClientError, CorsOriginError} from '@sanity/client'
+
+/**
+ * What the document store does with an outgoing transaction whose submission
+ * failed.
+ *
+ * - `retry`: the failure is about the connection, the credentials or
+ *   contention on the server, not the transaction. Keep the transaction and
+ *   its optimistic local state, and submit it again.
+ * - `accepted`: the server already recorded this transaction ID, so an earlier
+ *   attempt was committed even though its response never arrived.
+ * - `revert`: the server rejected the transaction itself. Submitting it again
+ *   cannot succeed, so drop it and rebuild local state from the server copy.
+ *
+ * @internal
+ */
+export type SubmissionErrorClass = 'retry' | 'accepted' | 'revert'
+
+// Mirrors Studio's `TERMINAL_COMMIT_STATUSES` (checkoutPair.ts) without 401. A
+// 401 rejects the credentials (usually an expired session), not the
+// transaction, so the same transaction succeeds once the user re-authenticates.
+const REJECTED_TRANSACTION_STATUS_CODES = new Set([400, 402, 403, 404, 409, 410, 412, 413, 422])
+
+function getErrorType(error: ClientError): unknown {
+  const details: unknown = error.details
+  if (details && typeof details === 'object' && 'type' in details) return details.type
+  return undefined
+}
+
+/**
+ * Classifies a failed transaction submission. Unknown failures (network
+ * errors, timeouts, 5xx and 429 responses, and anything that is not a
+ * `ClientError`) default to `retry`: wrongly retrying a rejected transaction
+ * leaves the document visibly unsynced with the edits still on screen, while
+ * wrongly reverting a transient failure silently discards the user's work.
+ *
+ * @internal
+ */
+export function classifySubmissionError(error: unknown): SubmissionErrorClass {
+  if (error instanceof CorsOriginError) return 'revert'
+  if (!(error instanceof ClientError)) return 'retry'
+  if (error.statusCode === 409) {
+    const errorType = getErrorType(error)
+    if (errorType === 'transactionAlreadyExistsError') return 'accepted'
+    // contention while committing, not a verdict on the transaction; the
+    // server rolled it back, so the same transaction ID is safe to resend
+    if (errorType === 'transactionConflictError') return 'retry'
+  }
+  if (REJECTED_TRANSACTION_STATUS_CODES.has(error.statusCode)) return 'revert'
+  return 'retry'
+}