Include the underlying cause in the FETCH_ERROR message

A FETCH_ERROR previously surfaced only "TypeError - fetch failed", with
the real reason (DNS failure, refused connection, TLS error, etc.) hidden
in the cause. Consumers that log only `code`/`error` never saw it.

Append the underlying cause's message to the error string so the reason
is visible without inspecting `cause`, which is still attached.

STF-803

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: oschwald

README.md

@@ -166,6 +166,10 @@ returned by the web API, we also return these `code` values:
 }
 ```
 
+For `FETCH_ERROR`, the `error` message includes the underlying failure reason
+(for example, a DNS or connection error) when one is available, and the
+original error is also attached as `cause`.
+
 ## Example
 
 ```js

src/webServiceClient.spec.ts

@@ -1089,6 +1089,26 @@ describe('WebServiceClient', () => {
       expect((err.cause as Error).message).toBe(error);
     });
 
+    it('includes the underlying cause in the FETCH_ERROR message', async () => {
+      const fetchError = Object.assign(new TypeError('fetch failed'), {
+        cause: new Error('connect ECONNREFUSED 1.2.3.4:443'),
+      });
+
+      nockInstance
+        .post(fullPath('score'), score.request.basic)
+        .basicAuth(auth)
+        .replyWithError(fetchError);
+
+      const err = await expectError(client.score(transaction), {
+        code: 'FETCH_ERROR',
+        error: 'TypeError - fetch failed: connect ECONNREFUSED 1.2.3.4:443',
+        url: baseUrl + fullPath('score'),
+        cause: 'defined',
+      });
+      // The original error (with its own cause) is still attached.
+      expect((err.cause as Error).message).toBe('fetch failed');
+    });
+
     test.each`
       status | code                       | error
       ${400} | ${'IP_ADDRESS_INVALID'}    | ${'ip address invalid'}

src/webServiceClient.ts

@@ -119,10 +119,15 @@ export default class WebServiceClient {
           { cause: error }
         );
       }
+      // Include the underlying cause's message in the error string so the
+      // reason (e.g. a DNS or connection failure) is visible to consumers that
+      // only log `code`/`error`, not just available via `cause`.
+      const causeDetail =
+        error.cause instanceof Error ? `: ${error.cause.message}` : '';
       throw new WebServiceError(
         {
           code: 'FETCH_ERROR',
-          error: `${error.name} - ${error.message}`,
+          error: `${error.name} - ${error.message}${causeDetail}`,
           url,
         },
         { cause: error }