Throw WebServiceError instances and preserve error causes

CHANGELOG.md

@@ -7,6 +7,14 @@ CHANGELOG
 * **Breaking** Dropped support for Node.js 18 and 20. The minimum supported version is
   now 22.
 * **Breaking** Dropped commonjs support. The package is now only available as an ES module.
+* **Breaking** Errors from the web service client are now thrown as
+  `WebServiceError` instances, which extend `Error`, rather than as plain
+  objects. The `code`, `error`, `status`, and `url` properties are preserved,
+  so existing field access continues to work, but the thrown value is now an
+  `Error`. The original error is now preserved as the standard `cause`
+  property (for example, the network error behind a `FETCH_ERROR`). The
+  `WebServiceError` and `ArgumentError` classes and the `WebServiceClientError`
+  type are now exported from the package.
 * Added the input `/device/tracking_token`. This is the token generated by
   the [Device Tracking Add-on](https://dev.maxmind.com/minfraud/track-devices)
   for explicit device linking. You may provide this by providing

README.md

@@ -74,17 +74,23 @@ client.insights(transaction).then(insightsResponse => ...);
 client.factors(transaction).then(factorsResponse => ...);
 ```
 
-If the request fails, an error object will be returned in the catch in the form
-of:
+If the request fails, the returned promise rejects with a `WebServiceError`.
+This extends the built-in `Error` and has the following shape:
 
 ```js
 {
   code: string
   error: string
+  status?: number
   url: string
+  cause?: unknown // the underlying error, when one exists
 }
 ```
 
+`error` is also available as the standard `Error` `message`, and when the
+failure was caused by another error (for example, a network failure), the
+original error is available as `cause`.
+
 ### Reporting a transaction using the Report Transactions API
 
 MaxMind encourages the use of this API, as data received through this channel
@@ -115,25 +121,23 @@ See the API documentation for more details.
 
 If the request succeeds, no data is returned in the Promise.
 
-If the request fails, an error object will be returned in the catch in the
-form of:
-
-```js
-{
-  code: string
-  error: string
-  url: string
-}
-```
+If the request fails, the returned promise rejects with a `WebServiceError`
+(see above for its shape).
 
 ## Errors and Exceptions
 
 Thrown by the request and transaction models:
 * `ArgumentError` - Thrown when invalid data is passed to the Transaction
 and Transaction property constructors.
 
+Web service failures reject with a `WebServiceError`, which extends `Error`.
+It exposes `code`, `error`, an optional `status`, `url`, and, when the failure
+was caused by another error, the standard `cause` property. Both
+`ArgumentError` and `WebServiceError` (along with the `WebServiceClientError`
+type) are exported from the package.
+
 In addition to the [response errors](https://dev.maxmind.com/minfraud/api-documentation/responses/?lang=en#errors)
-returned by the web API, we also return:
+returned by the web API, we also return these `code` values:
 
 ```js
 {
@@ -162,6 +166,10 @@ returned by the web API, we also return:
 }
 ```
 
+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/errors.spec.ts

@@ -0,0 +1,105 @@
+import { ArgumentError, WebServiceError } from './errors.js';
+
+describe('WebServiceError', () => {
+  it('is an Error instance', () => {
+    const err = new WebServiceError({
+      code: 'FETCH_ERROR',
+      error: 'something went wrong',
+      url: 'https://example.com',
+    });
+
+    expect(err).toBeInstanceOf(Error);
+    expect(err).toBeInstanceOf(WebServiceError);
+    expect(err.name).toBe('WebServiceError');
+  });
+
+  it('exposes code, error, status, and url', () => {
+    const err = new WebServiceError({
+      code: 'SERVER_ERROR',
+      error: 'boom',
+      status: 500,
+      url: 'https://example.com',
+    });
+
+    expect(err.code).toBe('SERVER_ERROR');
+    expect(err.error).toBe('boom');
+    expect(err.status).toBe(500);
+    expect(err.url).toBe('https://example.com');
+  });
+
+  it('uses the error string as the message', () => {
+    const err = new WebServiceError({
+      code: 'FETCH_ERROR',
+      error: 'the message',
+      url: 'https://example.com',
+    });
+
+    expect(err.message).toBe('the message');
+    expect(err.error).toBe(err.message);
+  });
+
+  it('preserves the underlying cause', () => {
+    const cause = new TypeError('fetch failed');
+    const err = new WebServiceError(
+      {
+        code: 'FETCH_ERROR',
+        error: 'TypeError - fetch failed',
+        url: 'https://example.com',
+      },
+      { cause }
+    );
+
+    expect(err.cause).toBe(cause);
+  });
+
+  it('leaves cause undefined when not provided', () => {
+    const err = new WebServiceError({
+      code: 'FETCH_ERROR',
+      error: 'something went wrong',
+      url: 'https://example.com',
+    });
+
+    expect(err.cause).toBeUndefined();
+    expect(JSON.parse(JSON.stringify(err))).not.toHaveProperty('cause');
+  });
+
+  it('omits status when not provided', () => {
+    const err = new WebServiceError({
+      code: 'FETCH_ERROR',
+      error: 'something went wrong',
+      url: 'https://example.com',
+    });
+
+    expect(err.status).toBeUndefined();
+    expect(Object.prototype.hasOwnProperty.call(err, 'status')).toBe(false);
+  });
+
+  it('retains code, error, status, and url as enumerable properties', () => {
+    const err = new WebServiceError({
+      code: 'SERVER_ERROR',
+      error: 'boom',
+      status: 500,
+      url: 'https://example.com',
+    });
+
+    const serialized = JSON.parse(JSON.stringify(err));
+    expect(serialized).toMatchObject({
+      code: 'SERVER_ERROR',
+      error: 'boom',
+      status: 500,
+      url: 'https://example.com',
+    });
+    // `name` lives on the prototype, so it is not serialized.
+    expect(serialized).not.toHaveProperty('name');
+  });
+});
+
+describe('ArgumentError', () => {
+  it('is an Error instance', () => {
+    const err = new ArgumentError('bad input');
+
+    expect(err).toBeInstanceOf(Error);
+    expect(err.name).toBe('ArgumentError');
+    expect(err.message).toBe('bad input');
+  });
+});

src/errors.ts

@@ -1,7 +1,68 @@
+import { WebServiceClientError } from './types.js';
+
 /* tslint:disable:max-classes-per-file */
 export class ArgumentError extends Error {
   constructor(message: string) {
     super(message);
     this.name = this.constructor.name;
   }
 }
+
+/**
+ * An error returned by the minFraud web service or encountered while
+ * communicating with it.
+ *
+ * In addition to the standard `Error` properties (including `cause`, which
+ * holds the underlying error when one exists, such as the network error
+ * behind a `FETCH_ERROR`), it exposes the `code`, `status`, and `url`
+ * associated with the failure.
+ */
+export class WebServiceError extends Error implements WebServiceClientError {
+  /**
+   * The error code returned by the web service or generated by this client.
+   */
+  public readonly code: string;
+  /**
+   * A human-readable description of the error. This is an alias of `message`,
+   * retained for backward compatibility.
+   */
+  public readonly error: string;
+  /**
+   * The HTTP status code, when the error originated from an HTTP response.
+   *
+   * Declared with `declare` so that no class field is emitted: the property is
+   * absent (rather than set to `undefined`) when no status applies, e.g. on
+   * network-level errors such as `FETCH_ERROR` and `NETWORK_TIMEOUT`.
+   */
+  declare public readonly status?: number;
+  /**
+   * The URL that was being requested when the error occurred.
+   */
+  public readonly url: string;
+
+  constructor(
+    properties: {
+      code: string;
+      error: string;
+      status?: number;
+      url: string;
+    },
+    options?: { cause?: unknown }
+  ) {
+    super(properties.error, options);
+    this.code = properties.code;
+    this.error = properties.error;
+    // Only assign `status` when present so it stays genuinely optional: on
+    // network-level errors (e.g. FETCH_ERROR, NETWORK_TIMEOUT) the instance
+    // carries no `status` property at all, rather than `status: undefined`.
+    if (properties.status !== undefined) {
+      this.status = properties.status;
+    }
+    this.url = properties.url;
+  }
+}
+
+// Set `name` on the prototype rather than in the constructor. Using a string
+// literal keeps the name correct under minification, and keeping it off the
+// instance means it stays out of `JSON.stringify` output.
+WebServiceError.prototype.name = 'WebServiceError';

src/index.ts

@@ -1,4 +1,5 @@
 import * as Constants from './constants.js';
+import { ArgumentError, WebServiceError } from './errors.js';
 import Account from './request/account.js';
 import Billing from './request/billing.js';
 import CreditCard from './request/credit-card.js';
@@ -12,10 +13,12 @@ import Shipping from './request/shipping.js';
 import ShoppingCartItem from './request/shopping-cart-item.js';
 import Transaction from './request/transaction.js';
 import TransactionReport from './request/transaction-report.js';
+import { WebServiceClientError } from './types.js';
 import Client from './webServiceClient.js';
 
 export {
   Account,
+  ArgumentError,
   Billing,
   Client,
   Constants,
@@ -30,4 +33,7 @@ export {
   ShoppingCartItem,
   Transaction,
   TransactionReport,
+  WebServiceError,
 };
+
+export type { WebServiceClientError };

src/types.ts

@@ -3,4 +3,9 @@ export interface WebServiceClientError {
   error: string;
   status?: number;
   url: string;
+  /**
+   * The underlying error that caused this one, when available (for example,
+   * the network error behind a `FETCH_ERROR`).
+   */
+  cause?: unknown;
 }