@sanity/sdk 3.6.0 → 3.7.0

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