feat: replace generic Error throws with typed error classes

Add ZeroExValidationError, ZeroExUnsupportedOperationError,
ZeroExTransactionRevertedError, and ZeroExTimeoutError. Replace all
generic Error instances in interface methods with the appropriate
typed class. Export new classes from index.js.

Update README fee mapping table with legacy fee/bridgeFee column and
add new error types to the error reference table.

Author: jlin27

README.md

@@ -153,11 +153,11 @@ For native ETH (or any chain's native token) as a **buy token**, use `0xEeeeeEee
 
 ## Fee mapping
 
-| 0x response field | `SwidgeFeeType` | Notes |
-|---|---|---|
-| `totalNetworkFee` | `network` | Denominated in the chain's native token (e.g. ETH) |
-| `fees.zeroExFee` | `protocol` | 0x protocol fee |
-| `fees.integratorFee` | `affiliate` | Integrator / referral fee |
+| 0x response field | `SwidgeFeeType` | Notes | Legacy mapping |
+|---|---|---|---|
+| `totalNetworkFee` | `network` | Denominated in the chain's native token (e.g. ETH) | `fee` |
+| `fees.zeroExFee` | `protocol` | 0x protocol fee | `bridgeFee` |
+| `fees.integratorFee` | `affiliate` | Integrator / referral fee | not visible |
 
 Fee caps (`maxNetworkFeeBps`, `maxProtocolFeeBps`) are only enforced when the fee token matches the sell token. Cross-token comparisons are skipped because price data is not available in the API response.
 
@@ -171,6 +171,10 @@ Fee caps (`maxNetworkFeeBps`, `maxProtocolFeeBps`) are only enforced when the fe
 | `ZeroExInsufficientLiquidityError` | `liquidityAvailable: false` in the price response |
 | `ZeroExFeeLimitExceededError` | A quoted fee exceeds a configured `maxNetworkFeeBps` or `maxProtocolFeeBps` cap |
 | `ZeroExReadOnlyError` | `swidge` is called without a full signing account |
+| `ZeroExValidationError` | Invalid or missing input parameters |
+| `ZeroExUnsupportedOperationError` | An unsupported operation is requested (e.g. cross-chain `toChain`) |
+| `ZeroExTransactionRevertedError` | The swap transaction reverted on-chain |
+| `ZeroExTimeoutError` | Timed out waiting for transaction confirmation |
 | `NotImplementedError` | `getSupportedTokens()` is called |
 
 ---

index.js

@@ -33,5 +33,5 @@
 /** @typedef {import('./src/0x-protocol.js').ZeroExProtocolConfig} ZeroExProtocolConfig */
 
 export { default, default as ZeroExProtocol } from './src/0x-protocol.js'
-export { ZeroExApiError, ZeroExInsufficientLiquidityError, ZeroExFeeLimitExceededError, ZeroExReadOnlyError } from './src/errors.js'
+export { ZeroExApiError, ZeroExInsufficientLiquidityError, ZeroExFeeLimitExceededError, ZeroExReadOnlyError, ZeroExValidationError, ZeroExUnsupportedOperationError, ZeroExTransactionRevertedError, ZeroExTimeoutError } from './src/errors.js'
 export { ISwidgeProtocol } from '@tetherto/wdk-wallet/protocols'

src/0x-protocol.js

@@ -18,7 +18,7 @@ import { SwidgeProtocol } from '@tetherto/wdk-wallet/protocols'
 import { NotImplementedError } from '@tetherto/wdk-wallet'
 
 import ZeroExApiClient from './api-client.js'
-import { ZeroExFeeLimitExceededError, ZeroExInsufficientLiquidityError, ZeroExReadOnlyError } from './errors.js'
+import { ZeroExFeeLimitExceededError, ZeroExInsufficientLiquidityError, ZeroExReadOnlyError, ZeroExValidationError, ZeroExUnsupportedOperationError, ZeroExTransactionRevertedError, ZeroExTimeoutError } from './errors.js'
 
 /** @typedef {import('@tetherto/wdk-wallet').IWalletAccount} IWalletAccount */
 /** @typedef {import('@tetherto/wdk-wallet').IWalletAccountReadOnly} IWalletAccountReadOnly */
@@ -154,13 +154,13 @@ export default class ZeroExProtocol extends SwidgeProtocol {
    */
   async quoteSwidge (options) {
     if (options.fromTokenAmount == null && options.toTokenAmount == null) {
-      throw new Error('Either fromTokenAmount (exact-in) or toTokenAmount (exact-out) must be provided.')
+      throw new ZeroExValidationError('Either fromTokenAmount (exact-in) or toTokenAmount (exact-out) must be provided.')
     }
 
     const chainId = Number(this._config.chainId)
 
     if (options.toChain != null && Number(options.toChain) !== chainId) {
-      throw new Error(
+      throw new ZeroExUnsupportedOperationError(
         `Cross-chain bridging is not supported. toChain (${options.toChain}) must match the configured chainId (${chainId}).`
       )
     }
@@ -242,7 +242,7 @@ export default class ZeroExProtocol extends SwidgeProtocol {
     const chainId = Number(this._config.chainId)
 
     if (options.toChain != null && Number(options.toChain) !== chainId) {
-      throw new Error(
+      throw new ZeroExUnsupportedOperationError(
         `Cross-chain bridging is not supported. toChain (${options.toChain}) must match the configured chainId (${chainId}).`
       )
     }
@@ -280,7 +280,7 @@ export default class ZeroExProtocol extends SwidgeProtocol {
     // Handle ERC-20 approval if required
     if (!isNative && !this._config.skipApproval && quote.issues?.allowance != null) {
       if (typeof this._account.approve !== 'function') {
-        throw new Error(
+        throw new ZeroExValidationError(
           'Cannot approve the sell token: the wallet account does not support ERC-20 approvals.'
         )
       }
@@ -332,7 +332,7 @@ export default class ZeroExProtocol extends SwidgeProtocol {
    */
   async getSwidgeStatus (id, options) {
     if (typeof id !== 'string' || id.length === 0) {
-      throw new Error('Invalid swidge identifier.')
+      throw new ZeroExValidationError('Invalid swidge identifier.')
     }
 
     let chainId, hash
@@ -343,7 +343,7 @@ export default class ZeroExProtocol extends SwidgeProtocol {
     } else {
       const fromChain = options?.fromChain ?? this._config.chainId
       if (fromChain == null) {
-        throw new Error(
+        throw new ZeroExValidationError(
           "Cannot resolve the source chain: pass an id in the '<chainId>:<hash>' format, or provide the fromChain status option."
         )
       }
@@ -352,7 +352,7 @@ export default class ZeroExProtocol extends SwidgeProtocol {
     }
 
     if (!hash.startsWith('0x') || hash.length < 10) {
-      throw new Error(`Invalid transaction hash in swidge identifier: '${hash}'.`)
+      throw new ZeroExValidationError(`Invalid transaction hash in swidge identifier: '${hash}'.`)
     }
 
     /** @type {SwidgeTransaction[]} */
@@ -554,13 +554,13 @@ export default class ZeroExProtocol extends SwidgeProtocol {
       if (receipt) {
         const success = receipt.status === 1 || receipt.status === 1n || receipt.status === true
         if (!success) {
-          throw new Error(`Transaction '${hash}' reverted.`)
+          throw new ZeroExTransactionRevertedError(hash)
         }
         return receipt
       }
       await new Promise(resolve => setTimeout(resolve, intervalMs))
     }
 
-    throw new Error(`Timed out waiting for transaction '${hash}' to be mined.`)
+    throw new ZeroExTimeoutError(hash)
   }
 }

src/errors.js

@@ -60,6 +60,62 @@ export class ZeroExReadOnlyError extends Error {
   }
 }
 
+/**
+ * Thrown when invalid or missing input parameters are passed to an interface method.
+ */
+export class ZeroExValidationError extends Error {
+  /**
+   * @param {string} message
+   */
+  constructor (message) {
+    super(message)
+    this.name = 'ZeroExValidationError'
+  }
+}
+
+/**
+ * Thrown when an operation is not supported by this module (e.g. cross-chain bridging).
+ */
+export class ZeroExUnsupportedOperationError extends Error {
+  /**
+   * @param {string} message
+   */
+  constructor (message) {
+    super(message)
+    this.name = 'ZeroExUnsupportedOperationError'
+  }
+}
+
+/**
+ * Thrown when a swap transaction reverts on-chain.
+ */
+export class ZeroExTransactionRevertedError extends Error {
+  /**
+   * @param {string} hash - The transaction hash that reverted.
+   */
+  constructor (hash) {
+    super(`Transaction '${hash}' reverted.`)
+    this.name = 'ZeroExTransactionRevertedError'
+    /** @type {string} */
+    this.hash = hash
+  }
+}
+
+/**
+ * Thrown when polling for a transaction receipt exceeds the timeout.
+ */
+export class ZeroExTimeoutError extends Error {
+  /**
+   * @param {string} hash - The transaction hash that timed out.
+   */
+  constructor (hash) {
+    super(`Timed out waiting for transaction '${hash}' to be mined.`)
+    this.name = 'ZeroExTimeoutError'
+    /** @type {string} */
+    this.hash = hash
+  }
+}
+
 /**
  * Thrown when a quoted fee exceeds a configured fee cap.
  */