@open-xchange/soap-client 0.1.3 → 0.1.5

package/CHANGELOG.md

@@ -4,6 +4,24 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.1.5] - 2026-05-26
+
+### Fixed
+
+- Retry the WSDL fetch on transient network errors (ECONNRESET / ETIMEDOUT / etc.). The per-method `pRetry` wrapper was already handling SOAP method calls, but `SOAP.createClientAsync()` itself (which fetches the WSDL via axios under the hood) was unretried, so a single TLS hiccup during bootstrap would kill the whole test run.
+
+### Changed
+
+- Retry policy tuned to ride out a recovery window of up to ~3 minutes per call: 10 retries (11 attempts total) with exponential backoff from 1s up to 30s, capped, with jitter. Previous 3-retry / 10s-cap budget was useful for one-packet blips but ran out before a recovering service could come back. The same policy now applies to both the WSDL fetch and per-method SOAP calls (factored into a shared constant). Permanent SOAP faults (already-exists, auth failure, etc.) still abort immediately via `shouldAbortRetry`.
+
+## [0.1.4] - 2026-05-21
+
+### Fixed
+
+- Retry log lines no longer print `(undefined)` when SOAP errors come wrapped in `{ error: ... }` envelopes
+- Preserve `faultstring`, `faultcode`, `detail`, `root`, `response`, `body` on thrown errors so consumers can pattern-match on the SOAP fault structure
+- Unwrap `original_error` (snake_case) from `PropagatedError` chains in addition to `originalError` / `error`
+
 ## [0.1.3] - 2026-04-28
 
 ### Fixed
@@ -41,7 +59,7 @@ All notable changes to this project will be documented in this file.
 
 - Exponential backoff with jitter to SOAP client retries
 
-## [0.0.9] - 2025-12-12
+## 0.0.9 - 2025-12-12
 
 ### Changed
 
@@ -89,8 +107,25 @@ All notable changes to this project will be documented in this file.
 
 - Update dependencies
 
-## [0.0.1] - 2025-02-28
+## 0.0.1 - 2025-02-28
 
 ### Added
 
 - Initial release: extract SOAP client into its own library
+
+[unreleased]: https://gitlab.com/openxchange/appsuite/web-foundation/tools/-/compare/soap-client-0.1.5...main
+[0.1.5]: https://gitlab.com/openxchange/appsuite/web-foundation/tools/-/compare/soap-client-0.1.4...soap-client-0.1.5
+[0.1.4]: https://gitlab.com/openxchange/appsuite/web-foundation/tools/-/compare/soap-client-0.1.3...soap-client-0.1.4
+[0.1.3]: https://gitlab.com/openxchange/appsuite/web-foundation/tools/-/compare/soap-client-0.1.2...soap-client-0.1.3
+[0.1.2]: https://gitlab.com/openxchange/appsuite/web-foundation/tools/-/compare/soap-client-0.1.1...soap-client-0.1.2
+[0.1.0]: https://gitlab.com/openxchange/appsuite/web-foundation/tools/-/compare/soap-client-0.0.12...soap-client-0.1.0
+[0.0.12]: https://gitlab.com/openxchange/appsuite/web-foundation/tools/-/compare/soap-client-0.0.11...soap-client-0.0.12
+[0.0.11]: https://gitlab.com/openxchange/appsuite/web-foundation/tools/-/compare/soap-client-0.0.10...soap-client-0.0.11
+[0.0.10]: https://gitlab.com/openxchange/appsuite/web-foundation/tools/-/compare/soap-client-0.0.8...soap-client-0.0.10
+[0.0.8]: https://gitlab.com/openxchange/appsuite/web-foundation/tools/-/compare/soap-client-0.0.7...soap-client-0.0.8
+[0.0.7]: https://gitlab.com/openxchange/appsuite/web-foundation/tools/-/compare/soap-client-0.0.6...soap-client-0.0.7
+[0.0.6]: https://gitlab.com/openxchange/appsuite/web-foundation/tools/-/compare/soap-client-0.0.5...soap-client-0.0.6
+[0.0.5]: https://gitlab.com/openxchange/appsuite/web-foundation/tools/-/compare/soap-client-0.0.4...soap-client-0.0.5
+[0.0.4]: https://gitlab.com/openxchange/appsuite/web-foundation/tools/-/compare/soap-client-0.0.3...soap-client-0.0.4
+[0.0.3]: https://gitlab.com/openxchange/appsuite/web-foundation/tools/-/compare/soap-client-0.0.2...soap-client-0.0.3
+[0.0.2]: https://gitlab.com/openxchange/appsuite/web-foundation/tools/-/tags/soap-client-0.0.2

package/README.md

@@ -15,7 +15,7 @@ This project provides an API facade for the OX App Suite Middleware SOAP API, ma
 You can use the built-in provisioning script to automate resource creation. Simply run:
 
 ```sh
-npx @open-xchange/soap-client
+pnpm dlx @open-xchange/soap-client
 ```
 If you already have installed the package in your project, you can run the script directly:
 
@@ -26,7 +26,7 @@ pnpm provision.js
 This will execute the provisioning tool, which reads configuration from a JSON file (default: `./provisioning.json`). You can specify a different file with the `-f` option:
 
 ```sh
-npx @open-xchange/soap-client -f example-provisioning.json
+pnpm dlx @open-xchange/soap-client -f example-provisioning.json
 ```
 The JSON file should contain the resources to provision. For example:
 
@@ -81,17 +81,17 @@ The JSON file should contain the resources to provision. For example:
 The CLI supports creating contexts, users, and secondary accounts:
 
 ```sh
-npx @open-xchange/soap-client create context --name my-context
-npx @open-xchange/soap-client create user --context-id 123 --email user@example.com --name myuser
-npx @open-xchange/soap-client create account --context-id 123 --name info --email info@example.com --users 1,2,3
+pnpm dlx @open-xchange/soap-client create context --name my-context
+pnpm dlx @open-xchange/soap-client create user --context-id 123 --email user@example.com --name myuser
+pnpm dlx @open-xchange/soap-client create account --context-id 123 --name info --email info@example.com --users 1,2,3
 ```
 
 ### Example: Deleting Resources
 
 ```sh
-npx @open-xchange/soap-client delete context --id 123
-npx @open-xchange/soap-client delete user --context-id 123 --id 456
-npx @open-xchange/soap-client delete account --context-id 123 --email info@example.com --users 1,2,3
+pnpm dlx @open-xchange/soap-client delete context --id 123
+pnpm dlx @open-xchange/soap-client delete user --context-id 123 --id 456
+pnpm dlx @open-xchange/soap-client delete account --context-id 123 --email info@example.com --users 1,2,3
 ```
 
 ## API Usage

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-xchange/soap-client",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "SOAP client for OX App Suite",
   "main": "index.js",
   "type": "module",
@@ -22,13 +22,15 @@
   "dependencies": {
     "commander": "^14.0.3",
     "p-retry": "^8.0.0",
-    "soap": "^1.8.0"
+    "soap": "^1.9.3"
   },
   "devDependencies": {
+    "vitest": "^4.1.7",
     "@open-xchange/lint": "0.3.0"
   },
   "scripts": {
     "lint": "eslint .",
+    "test": "vitest --run",
     "provision": "node ./bin/provision.js"
   }
 }

package/soap.js

@@ -25,6 +25,21 @@ import pRetry, { AbortError as RetryAbortError } from 'p-retry'
 // Set AbortError correctly
 const AbortError = RetryAbortError
 
+// Shared retry policy for both the WSDL fetch and per-method SOAP calls.
+// Designed to ride out a service recovery window of up to ~3 minutes:
+// fast retries for the first ~30s catch transient blips cheaply, then the
+// schedule settles into 30s polling so a recovering service is picked up
+// within one poll. Note: each pRetry cycle is independent, so back-to-back
+// failures (WSDL + method) can spend up to ~6 minutes total — keep the CI
+// job timeout above that or recovery won't be observable.
+const RETRY_OPTIONS = {
+  retries: 10,        // 11 attempts total
+  factor: 2,          // exponential growth, doubling each attempt
+  minTimeout: 1000,   // first wait = 1s
+  maxTimeout: 30000,  // cap at 30s once growth exceeds it
+  randomize: true     // jitter to avoid thundering herd across parallel shards
+}
+
 for (const envFile of ['.env', '.env.defaults']) {
   try { process.loadEnvFile(envFile) } catch {}
 }
@@ -32,14 +47,59 @@ for (const envFile of ['.env', '.env.defaults']) {
 // This flag enables debug output including timing information.
 const debug = process.env.DEBUG_SOAP === 'true'
 
+/**
+ * Walk one layer of common error-wrapper shapes:
+ *   - `{ originalError }` — soap-client retry/catch chain
+ *   - `{ error }`         — soap@1.9.x http handler envelope
+ *   - `{ original_error }` — appsuite-codeceptjs `PropagatedError` (snake_case)
+ *
+ * Returns the inner value, or the input unchanged if it doesn't match any shape.
+ *
+ * @param {any} e
+ * @returns {any}
+ */
+function unwrapError (e) {
+  return e?.originalError ?? e?.error ?? e?.original_error ?? e
+}
+
+/**
+ * Unwrap common SOAP error shapes and produce a useful one-line description.
+ *
+ * The `soap` library and various intermediate layers throw errors in
+ * inconsistent shapes — sometimes a real Error with `.message`, sometimes a
+ * plain object whose Error lives under `.originalError`, `.error`, or
+ * `.original_error`, and sometimes the raw SOAP fault object (no `.message`,
+ * but the human-readable text is at `.root.Envelope.Body.Fault.faultstring`).
+ * Without unwrapping, `${err.message}` interpolates as `"undefined"` and a
+ * retry/failure log tells you nothing about why the call actually failed.
+ *
+ * Falls back through: unwrap → message → SOAP fault string → error code →
+ * JSON dump (truncated) → "unknown".
+ *
+ * @param {any} err The thrown value (real Error, wrapped object, or plain SOAP fault).
+ * @returns {string} A short human-readable description, never undefined.
+ */
+function describeError (err) {
+  if (err == null) return 'unknown'
+  const e = unwrapError(err)
+  if (e == null) return 'unknown'
+  return e?.message ||
+    e?.root?.Envelope?.Body?.Fault?.faultstring ||
+    e?.code ||
+    (typeof e === 'string' ? e : null) ||
+    (() => { try { return JSON.stringify(e)?.slice(0, 200) } catch { return null } })() ||
+    'unknown'
+}
+
 // Handle specifically timeout-related unhandled promise rejections as fallback
 process.on('unhandledRejection', (reason, promise) => {
-  if (reason?.code === 'ECONNABORTED' && (reason?.message?.includes('timeout') || reason?.message?.includes('exceeded'))) {
+  const r = unwrapError(reason)
+  if (r?.code === 'ECONNABORTED' && (r?.message?.includes('timeout') || r?.message?.includes('exceeded'))) {
     return
   }
 
   // Log other unhandled rejections as they indicate real problems
-  console.error('Unhandled promise rejection:', reason?.message || reason)
+  console.error('Unhandled promise rejection:', describeError(reason))
 })
 
 // This URL is used to create the SOAP client.
@@ -71,7 +131,38 @@ const obs = new PerformanceObserver((items) => {
 obs.observe({ entryTypes: ['measure'] })
 
 async function logSoapError (e) {
-  console.error(e?.originalError?.root?.Envelope?.Body?.Fault?.faultstring || e.message)
+  console.error(describeError(e))
+}
+
+/**
+ * If `e` carries a SOAP fault (after one level of wrapper unwrap), return a
+ * new Error whose `.message` is the friendly `"SOAP Fault: <faultstring>"` and
+ * whose structured fault fields are preserved as own properties. Otherwise
+ * return `e` unchanged.
+ *
+ * Why: the proxy catch used to throw `new Error("SOAP Fault: ...")` which
+ * stripped `.faultstring`, `.detail`, `.root`, `.response`, and `.body` — and
+ * downstream code in `appsuite-codeceptjs` pattern-matches on those exact
+ * fields (e.g. `err.faultstring` to ignore "No such user"). Preserving them
+ * keeps those consumer paths working while still giving operators a clean
+ * one-line message.
+ *
+ * @param {any} e
+ * @returns {any}
+ */
+function wrapSoapFault (e) {
+  const unwrapped = unwrapError(e)
+  const fault = unwrapped?.root?.Envelope?.Body?.Fault
+  if (!fault) return e
+  const wrapped = new Error(`SOAP Fault: ${fault.faultstring}`)
+  return Object.assign(wrapped, {
+    faultstring: fault.faultstring,
+    faultcode: fault.faultcode,
+    detail: fault.detail,
+    root: unwrapped.root,
+    response: unwrapped.response,
+    body: unwrapped.body
+  })
 }
 
 /**
@@ -80,18 +171,21 @@ async function logSoapError (e) {
  * @returns {boolean} True if the error should abort the retry, false otherwise.
  **/
 function shouldAbortRetry (error) {
+  // Same unwrapping rules as describeError — the real SOAP fault may live
+  // one layer deep.
+  const err = unwrapError(error)
   try {
     // Handle timeout errors - these should NOT abort retry, let them retry
-    if (error?.code === 'ETIMEDOUT' || error?.code === 'ECONNRESET' || error?.code === 'ECONNABORTED' || error?.message?.includes('timeout')) {
+    if (err?.code === 'ETIMEDOUT' || err?.code === 'ECONNRESET' || err?.code === 'ECONNABORTED' || err?.message?.includes('timeout')) {
       return false // Allow retry for timeout errors
     }
 
     // Handle cases where error doesn't have the expected structure
-    if (!error?.root?.Envelope?.Body?.Fault) {
+    if (!err?.root?.Envelope?.Body?.Fault) {
       return false // Let it retry for unexpected error structures
     }
 
-    const fault = error.root.Envelope.Body.Fault
+    const fault = err.root.Envelope.Body.Fault
     const details = fault.detail
     const blockedFaultStrings = [
       /Context \d+ already exists/,
@@ -134,13 +228,23 @@ async function createClientAsync (type) {
   performance.mark(startMark)
   const endpoint = `${provisioningUrl}/webservices/${type}`
   const url = `${endpoint}/?wsdl`
-  const client = await SOAP.createClientAsync(url, {
+  // The WSDL fetch itself can hit transient network errors (ECONNRESET,
+  // ETIMEDOUT, ...). Without retry here, a single TLS hiccup during
+  // bootstrap kills the whole job before any per-method pRetry below has
+  // a chance to run.
+  const client = await pRetry(() => SOAP.createClientAsync(url, {
     endpoint,
     suppressStack: true,
     wsdl_options: {
       forever: true
     },
     gzip: true
+  }), {
+    ...RETRY_OPTIONS,
+    onFailedAttempt: async error => {
+      if (shouldAbortRetry(error)) throw new AbortError(error)
+      console.log(`Retrying WSDL fetch (${type}) in ${error.retriesLeft} attempts (${describeError(error)})`)
+    }
   })
 
   // https://stackoverflow.com/questions/30740415/namespace-for-array-field-in-node-soap-client-node-js
@@ -167,13 +271,10 @@ async function createClientAsync (type) {
 
           try {
             const result = await pRetry(() => origMethod.apply(this, [soapOptions, { timeout: 30000, ...clientOptions }, ...args]), {
-              retries: 3,
-              minTimeout: 1000,  // Start with 1 second delay between retries
-              maxTimeout: 10000, // Cap retry delay at 10 seconds
-              randomize: true,   // Add jitter to spread out concurrent retries
+              ...RETRY_OPTIONS,
               onFailedAttempt: async error => {
                 if (shouldAbortRetry(error)) throw new AbortError(error)
-                console.log(`Retrying ${String(prop)} in ${error.retriesLeft} attempts (${error.message})`)
+                console.log(`Retrying ${String(prop)} in ${error.retriesLeft} attempts (${describeError(error)})`)
               }
             })
 
@@ -183,11 +284,7 @@ async function createClientAsync (type) {
             if (!result || !result[0]) return
             return result[0]?.return
           } catch (e) {
-            const soapError = e?.originalError?.root?.Envelope?.Body?.Fault
-            if (soapError) {
-              throw new Error(`SOAP Fault: ${soapError.faultstring}`)
-            }
-            throw e
+            throw wrapSoapFault(e)
           }
         }
       } else {
@@ -197,4 +294,4 @@ async function createClientAsync (type) {
   })
 }
 
-export { createClientAsync, logSoapError }
+export { createClientAsync, logSoapError, describeError, shouldAbortRetry, wrapSoapFault, unwrapError }

package/test/soap.test.js

@@ -0,0 +1,226 @@
+/**
+ * @copyright Copyright (c) Open-Xchange GmbH, Germany <info@open-xchange.com>
+ * @license AGPL-3.0
+ */
+
+// soap.js reads PROVISIONING_URL at module load to build the SOAP endpoint URL.
+// We don't exercise that path here; set a stub so the import doesn't crash.
+process.env.PROVISIONING_URL = 'http://soap.test/'
+
+const { describeError, shouldAbortRetry, wrapSoapFault } = await import('../soap.js')
+
+// Build a SOAP fault object matching the real shape (from soap@1.9.x).
+function soapFault (faultstring, detail = {}) {
+  return {
+    root: { Envelope: { Body: { Fault: { faultstring, faultcode: 'soap:Server', detail } } } },
+    response: { status: 500, statusText: 'Internal Server Error' },
+    body: '<soap:Envelope>...</soap:Envelope>'
+  }
+}
+
+// Build the wrapped shape that crashed the retry log: { error: <Error w/ SOAP fault props> }
+function wrappedFault (faultstring, detail = {}) {
+  const err = new Error(`soap:Server: ${faultstring}`)
+  Object.assign(err, soapFault(faultstring, detail))
+  return { error: err }
+}
+
+describe('describeError', () => {
+  it('returns the message of a plain Error', () => {
+    expect(describeError(new Error('boom'))).toBe('boom')
+  })
+
+  it('unwraps { originalError: <Error> } and returns the inner message', () => {
+    const inner = new Error('inner-msg')
+    expect(describeError({ originalError: inner })).toBe('inner-msg')
+  })
+
+  it('unwraps { error: <Error> } (the shape that produced "(undefined)" in retry logs)', () => {
+    const inner = new Error('inner-msg')
+    expect(describeError({ error: inner })).toBe('inner-msg')
+  })
+
+  it('falls back to the SOAP faultstring when the wrapped Error has none', () => {
+    // Real-world: soap@1.9.x sometimes throws an Error whose .message lives
+    // *inside* the SOAP fault rather than on the Error itself. Verify the
+    // faultstring path kicks in.
+    const fault = soapFault('Could not acquire claim for context 2572225')
+    // strip the message so the .root.Envelope... path is the only signal
+    const e = Object.assign(Object.create(Error.prototype), fault)
+    expect(describeError(e)).toBe('Could not acquire claim for context 2572225')
+  })
+
+  it('falls back to the SOAP faultstring through one level of { error: ... } wrapping', () => {
+    const wrapped = wrappedFault('Context 99 already exists')
+    // Stripping the inner message forces the faultstring fallback.
+    delete wrapped.error.message
+    expect(describeError(wrapped)).toBe('Context 99 already exists')
+  })
+
+  it('returns the error code for timeout-shaped errors (no message, no fault)', () => {
+    const e = { code: 'ETIMEDOUT' }
+    expect(describeError(e)).toBe('ETIMEDOUT')
+  })
+
+  it('returns a stringified preview if nothing else matches', () => {
+    const e = { weird: 'shape', no: 'normal fields' }
+    const out = describeError(e)
+    expect(out).toMatch(/weird/)
+    expect(out.length).toBeLessThanOrEqual(200)
+  })
+
+  it('returns "unknown" rather than the literal string "undefined" for empty input', () => {
+    expect(describeError(undefined)).toBe('unknown')
+    expect(describeError(null)).toBe('unknown')
+  })
+
+  it('handles strings thrown directly', () => {
+    expect(describeError('plain string error')).toBe('plain string error')
+  })
+
+  it('unwraps { original_error: <Error> } (snake_case from PropagatedError chains)', () => {
+    const inner = new Error('inner-msg')
+    expect(describeError({ original_error: inner })).toBe('inner-msg')
+  })
+
+  it('falls back to the SOAP faultstring through one level of { original_error: ... } wrapping', () => {
+    const inner = Object.assign(Object.create(Error.prototype), soapFault('Context 7 already exists'))
+    expect(describeError({ original_error: inner })).toBe('Context 7 already exists')
+  })
+})
+
+describe('shouldAbortRetry', () => {
+  it('does NOT abort on ETIMEDOUT / ECONNRESET / ECONNABORTED — these are retryable', () => {
+    expect(shouldAbortRetry({ code: 'ETIMEDOUT' })).toBe(false)
+    expect(shouldAbortRetry({ code: 'ECONNRESET' })).toBe(false)
+    expect(shouldAbortRetry({ code: 'ECONNABORTED' })).toBe(false)
+  })
+
+  it('does NOT abort on transient SOAP faults (e.g. context-claim conflict) — they retry until the lock frees', () => {
+    // This is the actual fault from the user's report — we *want* the retry
+    // loop to keep trying until the conflicting writer commits.
+    const e = soapFault('Could not acquire claim for context 2572225 due to another conflicting provisioning operation. Please try again later.')
+    expect(shouldAbortRetry(e)).toBe(false)
+  })
+
+  it('aborts on "Context N already exists" — re-running will keep failing', () => {
+    const e = soapFault('Context 4242 already exists')
+    expect(shouldAbortRetry(e)).toBe(true)
+  })
+
+  it('aborts on "Authentication failed"', () => {
+    const e = soapFault('Authentication failed')
+    expect(shouldAbortRetry(e)).toBe(true)
+  })
+
+  it('aborts on blocked exceptions in the fault detail (e.g. ContextExistsException)', () => {
+    const e = soapFault('some message', { ContextExistsException: {} })
+    expect(shouldAbortRetry(e)).toBe(true)
+  })
+
+  it('looks through one level of { error: ... } wrapping when probing the fault', () => {
+    const wrapped = wrappedFault('Context 4242 already exists')
+    expect(shouldAbortRetry(wrapped)).toBe(true)
+  })
+
+  it('looks through { originalError: ... } wrapping too', () => {
+    const inner = new Error('whatever')
+    Object.assign(inner, soapFault('Authentication failed'))
+    expect(shouldAbortRetry({ originalError: inner })).toBe(true)
+  })
+
+  it('looks through { original_error: ... } (snake_case) wrapping too', () => {
+    const inner = new Error('whatever')
+    Object.assign(inner, soapFault('Context 4242 already exists'))
+    expect(shouldAbortRetry({ original_error: inner })).toBe(true)
+  })
+
+  it('does NOT abort on completely unknown error structures — retry and let it sort itself out', () => {
+    expect(shouldAbortRetry({ random: 'object' })).toBe(false)
+    expect(shouldAbortRetry(undefined)).toBe(false)
+    expect(shouldAbortRetry(null)).toBe(false)
+  })
+})
+
+describe('wrapSoapFault', () => {
+  it('returns the input unchanged when no SOAP fault is present', () => {
+    const e = new Error('plain timeout')
+    expect(wrapSoapFault(e)).toBe(e)
+  })
+
+  it('returns the input unchanged for non-SOAP wrapped errors (e.g. axios timeout)', () => {
+    const e = Object.assign(new Error('timeout'), { code: 'ETIMEDOUT' })
+    expect(wrapSoapFault({ error: e })).toEqual({ error: e })
+  })
+
+  it('returns a NEW Error with the fault structure preserved on it', () => {
+    // Real-world: the soap library hands us an Error whose .root/.response/.body
+    // carry the structured fault. The proxy catch used to throw a plain new
+    // Error("SOAP Fault: …"), which DELETED the structured fields and broke
+    // downstream consumers that pattern-match on err.faultstring.
+    const inner = Object.assign(new Error('original'), soapFault('Context 42 already exists', { ContextExistsException: {} }))
+    const out = wrapSoapFault(inner)
+    expect(out).not.toBe(inner) // it's a new Error so the message can be friendly
+    expect(out).toBeInstanceOf(Error)
+    expect(out.message).toBe('SOAP Fault: Context 42 already exists')
+    expect(out.faultstring).toBe('Context 42 already exists')
+    expect(out.faultcode).toBe('soap:Server')
+    expect(out.detail).toEqual({ ContextExistsException: {} })
+    expect(out.root).toBe(inner.root)
+    expect(out.response).toBe(inner.response)
+    expect(out.body).toBe(inner.body)
+  })
+
+  it('unwraps { error: <Error w/ fault> } before extracting the fault', () => {
+    const inner = Object.assign(new Error('original'), soapFault('Authentication failed'))
+    const out = wrapSoapFault({ error: inner })
+    expect(out.faultstring).toBe('Authentication failed')
+    expect(out.message).toBe('SOAP Fault: Authentication failed')
+  })
+
+  it('unwraps { original_error: <Error w/ fault> } (snake_case) before extracting the fault', () => {
+    const inner = Object.assign(new Error('original'), soapFault('No such user'))
+    const out = wrapSoapFault({ original_error: inner })
+    expect(out.faultstring).toBe('No such user')
+  })
+})
+
+// Regression: the exact shape from the original incident report — a transient
+// "Could not acquire claim" fault wrapped in soap@1.9.x's `{ error: <Error> }`
+// envelope, with the StorageException nested in detail. Three concerns checked
+// together so the next person debugging this flow can see the whole pipeline
+// pass against the real symptom in one place.
+describe('real-world: transient "Could not acquire claim" fault wrapped in { error: ... }', () => {
+  const faultstring = 'Could not acquire claim for context 2572225 due to another conflicting provisioning operation. Please try again later.; exceptionId -1132283668-9930'
+  function realWorldThrownValue () {
+    const err = new Error(`soap:Server: ${faultstring}`)
+    Object.assign(err, soapFault(faultstring, { StorageException: { StorageException: null } }))
+    return { error: err }
+  }
+
+  it('describeError produces a useful retry-log line (not "(undefined)")', () => {
+    const out = describeError(realWorldThrownValue())
+    expect(out).toContain('Could not acquire claim for context 2572225')
+    expect(out).not.toBe('undefined')
+    expect(out).not.toBe('unknown')
+  })
+
+  it('shouldAbortRetry returns false — this is transient, keep retrying', () => {
+    // StorageException is NOT in the blockedExceptions list, and the
+    // faultstring doesn't match any blockedFaultStrings regex, so the retry
+    // loop must keep going until the conflicting writer commits.
+    expect(shouldAbortRetry(realWorldThrownValue())).toBe(false)
+  })
+
+  it('wrapSoapFault preserves .faultstring, .detail.StorageException, .root, .response, .body', () => {
+    const out = wrapSoapFault(realWorldThrownValue())
+    expect(out).toBeInstanceOf(Error)
+    expect(out.message).toMatch(/^SOAP Fault: Could not acquire claim for context 2572225/)
+    expect(out.faultstring).toContain('Could not acquire claim for context 2572225')
+    expect(out.faultcode).toBe('soap:Server')
+    expect(out.detail).toEqual({ StorageException: { StorageException: null } })
+    expect(out.root.Envelope.Body.Fault.faultstring).toContain('Could not acquire')
+    expect(out.response.status).toBe(500)
+    expect(out.body).toMatch(/soap:Envelope/)
+  })
+})

package/vitest.config.js

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    globals: true,
+    include: ['test/**/*.test.*']
+  }
+})