@atxp/client 0.9.0 → 0.9.2

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Account, Network, DestinationMaker, AuthorizationServerUrl, AccountId, Currency, OAuthDb, FetchLike, Logger, OAuthResourceClient, ClientCredentials, PKCEValues, AccessToken, PaymentRequestOption, Source, Destination } from '@atxp/common';
+import { Currency, Account, Network, DestinationMaker, AuthorizationServerUrl, AccountId, OAuthDb, FetchLike, Logger, OAuthResourceClient, ClientCredentials, PKCEValues, AccessToken, PaymentRequestOption, Source, Destination } from '@atxp/common';
 export { ATXPAccount, Account, PaymentMaker } from '@atxp/common';
 import { ClientOptions, Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { Implementation } from '@modelcontextprotocol/sdk/types.js';
@@ -6,6 +6,122 @@ import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/
 import * as oauth from 'oauth4webapi';
 import { LocalAccount, Address, TypedData, Hex as Hex$1, SignableMessage, TransactionSerializable } from 'viem';
 
+/**
+ * Base class for all ATXP payment errors with structured error codes and actionable guidance
+ */
+declare abstract class ATXPPaymentError extends Error {
+    readonly context?: Record<string, unknown> | undefined;
+    abstract readonly code: string;
+    abstract readonly retryable: boolean;
+    abstract readonly actionableMessage: string;
+    constructor(message: string, context?: Record<string, unknown> | undefined);
+}
+/**
+ * Thrown when the user's wallet has insufficient funds for a payment
+ */
+declare class InsufficientFundsError extends ATXPPaymentError {
+    readonly currency: Currency;
+    readonly required: BigNumber;
+    readonly available?: BigNumber | undefined;
+    readonly network?: string | undefined;
+    readonly code = "INSUFFICIENT_FUNDS";
+    readonly retryable = true;
+    readonly actionableMessage: string;
+    constructor(currency: Currency, required: BigNumber, available?: BigNumber | undefined, network?: string | undefined);
+}
+/**
+ * Thrown when a blockchain transaction is reverted
+ */
+declare class TransactionRevertedError extends ATXPPaymentError {
+    readonly transactionHash: string;
+    readonly network: string;
+    readonly revertReason?: string | undefined;
+    readonly code = "TRANSACTION_REVERTED";
+    readonly retryable = false;
+    readonly actionableMessage: string;
+    constructor(transactionHash: string, network: string, revertReason?: string | undefined);
+}
+/**
+ * Thrown when an unsupported currency is requested
+ */
+declare class UnsupportedCurrencyError extends ATXPPaymentError {
+    readonly currency: string;
+    readonly network: string;
+    readonly supportedCurrencies: string[];
+    readonly code = "UNSUPPORTED_CURRENCY";
+    readonly retryable = false;
+    readonly actionableMessage: string;
+    constructor(currency: string, network: string, supportedCurrencies: string[]);
+}
+/**
+ * Thrown when gas estimation fails for a transaction
+ */
+declare class GasEstimationError extends ATXPPaymentError {
+    readonly network: string;
+    readonly reason?: string | undefined;
+    readonly code = "GAS_ESTIMATION_FAILED";
+    readonly retryable = true;
+    readonly actionableMessage = "Unable to estimate gas for this transaction. Ensure you have sufficient funds for both the payment amount and gas fees, then try again.";
+    constructor(network: string, reason?: string | undefined);
+}
+/**
+ * Thrown when RPC/network connectivity fails
+ */
+declare class RpcError extends ATXPPaymentError {
+    readonly network: string;
+    readonly rpcUrl?: string | undefined;
+    readonly originalError?: Error | undefined;
+    readonly code = "RPC_ERROR";
+    readonly retryable = true;
+    readonly actionableMessage = "Unable to connect to the blockchain network. Please check your internet connection and try again.";
+    constructor(network: string, rpcUrl?: string | undefined, originalError?: Error | undefined);
+}
+/**
+ * Thrown when the user rejects a transaction in their wallet
+ */
+declare class UserRejectedError extends ATXPPaymentError {
+    readonly network: string;
+    readonly code = "USER_REJECTED";
+    readonly retryable = true;
+    readonly actionableMessage = "You cancelled the transaction. To complete the payment, please approve the transaction in your wallet.";
+    constructor(network: string);
+}
+/**
+ * Thrown when the payment server returns an error
+ */
+declare class PaymentServerError extends ATXPPaymentError {
+    readonly statusCode: number;
+    readonly endpoint: string;
+    readonly serverMessage?: string | undefined;
+    readonly details?: unknown | undefined;
+    readonly code: string;
+    readonly retryable = true;
+    readonly actionableMessage = "The payment server encountered an error. Please try again in a few moments.";
+    constructor(statusCode: number, endpoint: string, serverMessage?: string | undefined, errorCode?: string, details?: unknown | undefined);
+}
+/**
+ * Thrown when a payment request has expired
+ */
+declare class PaymentExpiredError extends ATXPPaymentError {
+    readonly paymentRequestId: string;
+    readonly expiresAt?: Date | undefined;
+    readonly code = "PAYMENT_EXPIRED";
+    readonly retryable = false;
+    readonly actionableMessage = "This payment request has expired. Please make a new request to the service.";
+    constructor(paymentRequestId: string, expiresAt?: Date | undefined);
+}
+/**
+ * Generic network error for backward compatibility and uncategorized errors
+ */
+declare class PaymentNetworkError extends ATXPPaymentError {
+    readonly network: string;
+    readonly originalError?: Error | undefined;
+    readonly code = "NETWORK_ERROR";
+    readonly retryable = true;
+    readonly actionableMessage = "A network error occurred during payment processing. Please try again.";
+    constructor(network: string, message: string, originalError?: Error | undefined);
+}
+
 type Hex = `0x${string}`;
 type AccountPrefix = Network;
 type AccountIdString = `${AccountPrefix}${string}`;
@@ -17,6 +133,23 @@ type ProspectivePayment = {
     amount: BigNumber;
     iss: string;
 };
+/**
+ * Rich context provided when a payment fails
+ */
+interface PaymentFailureContext {
+    /** The payment that failed */
+    payment: ProspectivePayment;
+    /** The error that caused the failure */
+    error: Error;
+    /** Networks that were attempted for payment */
+    attemptedNetworks: string[];
+    /** Map of network to error for each failed attempt */
+    failureReasons: Map<string, Error>;
+    /** Whether the payment can be retried */
+    retryable: boolean;
+    /** Timestamp when the failure occurred */
+    timestamp: Date;
+}
 type ClientConfig = {
     mcpServer: string;
     account: Account;
@@ -42,10 +175,15 @@ type ClientConfig = {
     }) => Promise<void>;
     onPayment: (args: {
         payment: ProspectivePayment;
+        transactionHash: string;
+        network: string;
     }) => Promise<void>;
-    onPaymentFailure: (args: {
-        payment: ProspectivePayment;
+    onPaymentFailure: (context: PaymentFailureContext) => Promise<void>;
+    /** Optional callback when a single payment attempt fails (before trying other networks) */
+    onPaymentAttemptFailed?: (args: {
+        network: string;
         error: Error;
+        remainingNetworks: string[];
     }) => Promise<void>;
 };
 type RequiredClientConfigFields$1 = 'mcpServer' | 'account';
@@ -53,17 +191,6 @@ type RequiredClientConfig = Pick<ClientConfig, RequiredClientConfigFields$1>;
 type OptionalClientConfig$1 = Omit<ClientConfig, RequiredClientConfigFields$1>;
 type ClientArgs = RequiredClientConfig & Partial<OptionalClientConfig$1>;
 type FetchWrapper = (config: ClientArgs) => FetchLike;
-declare class InsufficientFundsError extends Error {
-    readonly currency: Currency;
-    readonly required: BigNumber;
-    readonly available?: BigNumber | undefined;
-    readonly network?: string | undefined;
-    constructor(currency: Currency, required: BigNumber, available?: BigNumber | undefined, network?: string | undefined);
-}
-declare class PaymentNetworkError extends Error {
-    readonly originalError?: Error | undefined;
-    constructor(message: string, originalError?: Error | undefined);
-}
 
 type RequiredClientConfigFields = 'mcpServer' | 'account';
 type OptionalClientConfig = Omit<ClientConfig, RequiredClientConfigFields>;
@@ -296,5 +423,5 @@ declare class PassthroughDestinationMaker implements DestinationMaker {
     makeDestinations(option: PaymentRequestOption, _logger: Logger, _paymentRequestId: string, _sources: Source[]): Promise<Destination[]>;
 }
 
-export { ATXPDestinationMaker, ATXPLocalAccount, DEFAULT_CLIENT_CONFIG, InsufficientFundsError, OAuthAuthenticationRequiredError, OAuthClient, POLYGON_AMOY, POLYGON_MAINNET, PassthroughDestinationMaker, PaymentNetworkError, USDC_CONTRACT_ADDRESS_POLYGON_AMOY, USDC_CONTRACT_ADDRESS_POLYGON_MAINNET, USDC_CONTRACT_ADDRESS_WORLD_MAINNET, USDC_CONTRACT_ADDRESS_WORLD_SEPOLIA, WORLD_CHAIN_MAINNET, WORLD_CHAIN_SEPOLIA, atxpClient, atxpFetch, buildClientConfig, buildStreamableTransport, getPolygonAmoyWithRPC, getPolygonByChainId, getPolygonMainnetWithRPC, getPolygonUSDCAddress, getWorldChainByChainId, getWorldChainMainnetWithRPC, getWorldChainSepoliaWithRPC, getWorldChainUSDCAddress };
-export type { AccountIdString, ClientArgs, ClientConfig, FetchWrapper, Hex, OAuthClientConfig, PolygonChain, ProspectivePayment, WorldChain };
+export { ATXPDestinationMaker, ATXPLocalAccount, ATXPPaymentError, DEFAULT_CLIENT_CONFIG, GasEstimationError, InsufficientFundsError, OAuthAuthenticationRequiredError, OAuthClient, POLYGON_AMOY, POLYGON_MAINNET, PassthroughDestinationMaker, PaymentExpiredError, PaymentNetworkError, PaymentServerError, RpcError, TransactionRevertedError, USDC_CONTRACT_ADDRESS_POLYGON_AMOY, USDC_CONTRACT_ADDRESS_POLYGON_MAINNET, USDC_CONTRACT_ADDRESS_WORLD_MAINNET, USDC_CONTRACT_ADDRESS_WORLD_SEPOLIA, UnsupportedCurrencyError, UserRejectedError, WORLD_CHAIN_MAINNET, WORLD_CHAIN_SEPOLIA, atxpClient, atxpFetch, buildClientConfig, buildStreamableTransport, getPolygonAmoyWithRPC, getPolygonByChainId, getPolygonMainnetWithRPC, getPolygonUSDCAddress, getWorldChainByChainId, getWorldChainMainnetWithRPC, getWorldChainSepoliaWithRPC, getWorldChainUSDCAddress };
+export type { AccountIdString, ClientArgs, ClientConfig, FetchWrapper, Hex, OAuthClientConfig, PaymentFailureContext, PolygonChain, ProspectivePayment, WorldChain };

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,qBAAqB,EACrB,iBAAiB,EACjB,wBAAwB,EACxB,UAAU,EACX,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,gCAAgC,EAChC,KAAK,iBAAiB,EACtB,WAAW,EACZ,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,SAAS,EACV,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,WAAW,EACZ,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,mCAAmC,EACnC,mCAAmC,EACnC,mBAAmB,EACnB,mBAAmB,EACnB,2BAA2B,EAC3B,2BAA2B,EAC3B,sBAAsB,EACtB,wBAAwB,EACxB,KAAK,UAAU,EAChB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EACL,qCAAqC,EACrC,kCAAkC,EAClC,eAAe,EACf,YAAY,EACZ,wBAAwB,EACxB,qBAAqB,EACrB,mBAAmB,EACnB,qBAAqB,EACrB,KAAK,YAAY,EAClB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,KAAK,GAAG,EACR,KAAK,eAAe,EACpB,KAAK,OAAO,EACZ,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,sBAAsB,EACtB,mBAAmB,EACnB,KAAK,YAAY,EAClB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,gBAAgB,EACjB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,oBAAoB,EACpB,2BAA2B,GAC5B,MAAM,8BAA8B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,qBAAqB,EACrB,iBAAiB,EACjB,wBAAwB,EACxB,UAAU,EACX,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,gCAAgC,EAChC,KAAK,iBAAiB,EACtB,WAAW,EACZ,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,SAAS,EACV,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,WAAW,EACZ,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,mCAAmC,EACnC,mCAAmC,EACnC,mBAAmB,EACnB,mBAAmB,EACnB,2BAA2B,EAC3B,2BAA2B,EAC3B,sBAAsB,EACtB,wBAAwB,EACxB,KAAK,UAAU,EAChB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EACL,qCAAqC,EACrC,kCAAkC,EAClC,eAAe,EACf,YAAY,EACZ,wBAAwB,EACxB,qBAAqB,EACrB,mBAAmB,EACnB,qBAAqB,EACrB,KAAK,YAAY,EAClB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,KAAK,GAAG,EACR,KAAK,eAAe,EACpB,KAAK,OAAO,EACZ,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,YAAY,EAClB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,gBAAgB,EAChB,sBAAsB,EACtB,wBAAwB,EACxB,wBAAwB,EACxB,kBAAkB,EAClB,QAAQ,EACR,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACnB,mBAAmB,EACpB,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,gBAAgB,EACjB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,oBAAoB,EACpB,2BAA2B,GAC5B,MAAM,8BAA8B,CAAC"}

package/dist/index.js

@@ -1,4 +1,4 @@
-import { crypto as crypto$1, OAuthResourceClient, ConsoleLogger, PAYMENT_REQUIRED_ERROR_CODE, isSSEResponse, parseMcpMessages, parsePaymentRequests, paymentRequiredError, DEFAULT_AUTHORIZATION_SERVER, getIsReactNative, createReactNativeSafeFetch, isEnumValue, ChainEnum, CurrencyEnum, NetworkEnum, assertNever, DEFAULT_ATXP_ACCOUNTS_SERVER, MemoryOAuthDb, ATXPAccount } from '@atxp/common';
+import { crypto as crypto$1, OAuthResourceClient, ConsoleLogger, getErrorRecoveryHint, PAYMENT_REQUIRED_ERROR_CODE, isSSEResponse, parseMcpMessages, parsePaymentRequests, paymentRequiredError, DEFAULT_AUTHORIZATION_SERVER, getIsReactNative, createReactNativeSafeFetch, isEnumValue, ChainEnum, CurrencyEnum, NetworkEnum, assertNever, DEFAULT_ATXP_ACCOUNTS_SERVER, MemoryOAuthDb, ATXPAccount } from '@atxp/common';
 export { ATXPAccount } from '@atxp/common';
 import * as oauth from 'oauth4webapi';
 import { BigNumber } from 'bignumber.js';
@@ -275,25 +275,153 @@ class OAuthClient extends OAuthResourceClient {
     }
 }
 
-class InsufficientFundsError extends Error {
+/**
+ * Base class for all ATXP payment errors with structured error codes and actionable guidance
+ */
+class ATXPPaymentError extends Error {
+    constructor(message, context) {
+        super(message);
+        this.context = context;
+        this.name = this.constructor.name;
+    }
+}
+/**
+ * Thrown when the user's wallet has insufficient funds for a payment
+ */
+class InsufficientFundsError extends ATXPPaymentError {
     constructor(currency, required, available, network) {
+        const shortfall = available ? required.minus(available).toString() : required.toString();
         const availableText = available ? `, Available: ${available}` : '';
         const networkText = network ? ` on ${network}` : '';
         super(`Payment failed due to insufficient ${currency} funds${networkText}. ` +
             `Required: ${required}${availableText}. ` +
-            `Please ensure your account has adequate balance before retrying.`);
+            `Please ensure your account has adequate balance before retrying.`, { currency, required: required.toString(), available: available?.toString(), network, shortfall });
         this.currency = currency;
         this.required = required;
         this.available = available;
         this.network = network;
-        this.name = 'InsufficientFundsError';
+        this.code = 'INSUFFICIENT_FUNDS';
+        this.retryable = true;
+        this.actionableMessage = available
+            ? `Add at least ${shortfall} ${currency} to your ${network} wallet and try again.`
+            : `Ensure your ${network} wallet has at least ${required} ${currency} and try again.`;
+    }
+}
+/**
+ * Thrown when a blockchain transaction is reverted
+ */
+class TransactionRevertedError extends ATXPPaymentError {
+    constructor(transactionHash, network, revertReason) {
+        super(`Transaction ${transactionHash} reverted on ${network}${revertReason ? `: ${revertReason}` : ''}`, { transactionHash, network, revertReason });
+        this.transactionHash = transactionHash;
+        this.network = network;
+        this.revertReason = revertReason;
+        this.code = 'TRANSACTION_REVERTED';
+        this.retryable = false;
+        // Provide specific guidance based on revert reason
+        if (revertReason?.toLowerCase().includes('allowance')) {
+            this.actionableMessage = 'Approve token spending before making the payment. You may need to increase the token allowance.';
+        }
+        else if (revertReason?.toLowerCase().includes('balance')) {
+            this.actionableMessage = 'Ensure your wallet has sufficient token balance and native token for gas fees.';
+        }
+        else {
+            this.actionableMessage = 'The transaction was rejected by the blockchain. Check the transaction details on a block explorer and verify your wallet settings.';
+        }
+    }
+}
+/**
+ * Thrown when an unsupported currency is requested
+ */
+class UnsupportedCurrencyError extends ATXPPaymentError {
+    constructor(currency, network, supportedCurrencies) {
+        super(`Currency ${currency} is not supported on ${network}`, { currency, network, supportedCurrencies });
+        this.currency = currency;
+        this.network = network;
+        this.supportedCurrencies = supportedCurrencies;
+        this.code = 'UNSUPPORTED_CURRENCY';
+        this.retryable = false;
+        this.actionableMessage = `Please use one of the supported currencies: ${supportedCurrencies.join(', ')}`;
+    }
+}
+/**
+ * Thrown when gas estimation fails for a transaction
+ */
+class GasEstimationError extends ATXPPaymentError {
+    constructor(network, reason) {
+        super(`Failed to estimate gas on ${network}${reason ? `: ${reason}` : ''}`, { network, reason });
+        this.network = network;
+        this.reason = reason;
+        this.code = 'GAS_ESTIMATION_FAILED';
+        this.retryable = true;
+        this.actionableMessage = 'Unable to estimate gas for this transaction. Ensure you have sufficient funds for both the payment amount and gas fees, then try again.';
+    }
+}
+/**
+ * Thrown when RPC/network connectivity fails
+ */
+class RpcError extends ATXPPaymentError {
+    constructor(network, rpcUrl, originalError) {
+        super(`RPC call failed on ${network}${rpcUrl ? ` (${rpcUrl})` : ''}`, { network, rpcUrl, originalError: originalError?.message });
+        this.network = network;
+        this.rpcUrl = rpcUrl;
+        this.originalError = originalError;
+        this.code = 'RPC_ERROR';
+        this.retryable = true;
+        this.actionableMessage = 'Unable to connect to the blockchain network. Please check your internet connection and try again.';
+    }
+}
+/**
+ * Thrown when the user rejects a transaction in their wallet
+ */
+class UserRejectedError extends ATXPPaymentError {
+    constructor(network) {
+        super(`User rejected transaction on ${network}`, { network });
+        this.network = network;
+        this.code = 'USER_REJECTED';
+        this.retryable = true;
+        this.actionableMessage = 'You cancelled the transaction. To complete the payment, please approve the transaction in your wallet.';
+    }
+}
+/**
+ * Thrown when the payment server returns an error
+ */
+class PaymentServerError extends ATXPPaymentError {
+    constructor(statusCode, endpoint, serverMessage, errorCode, details) {
+        super(`Payment server returned ${statusCode} from ${endpoint}${serverMessage ? `: ${serverMessage}` : ''}`, { statusCode, endpoint, serverMessage, errorCode, details });
+        this.statusCode = statusCode;
+        this.endpoint = endpoint;
+        this.serverMessage = serverMessage;
+        this.details = details;
+        this.retryable = true;
+        this.actionableMessage = 'The payment server encountered an error. Please try again in a few moments.';
+        this.code = errorCode || 'PAYMENT_SERVER_ERROR';
     }
 }
-class PaymentNetworkError extends Error {
-    constructor(message, originalError) {
-        super(`Payment failed due to network error: ${message}`);
+/**
+ * Thrown when a payment request has expired
+ */
+class PaymentExpiredError extends ATXPPaymentError {
+    constructor(paymentRequestId, expiresAt) {
+        super(`Payment request ${paymentRequestId} has expired`, { paymentRequestId, expiresAt: expiresAt?.toISOString() });
+        this.paymentRequestId = paymentRequestId;
+        this.expiresAt = expiresAt;
+        this.code = 'PAYMENT_EXPIRED';
+        this.retryable = false;
+        this.actionableMessage = 'This payment request has expired. Please make a new request to the service.';
+    }
+}
+/**
+ * Generic network error for backward compatibility and uncategorized errors
+ */
+class PaymentNetworkError extends ATXPPaymentError {
+    constructor(network, message, originalError) {
+        super(`Payment failed on ${network} network: ${message}`, { network, originalError: originalError?.message });
+        this.network = network;
         this.originalError = originalError;
-        this.name = 'PaymentNetworkError';
+        this.code = 'NETWORK_ERROR';
+        this.retryable = true;
+        this.actionableMessage = 'A network error occurred during payment processing. Please try again.';
     }
 }
 
@@ -318,27 +446,41 @@ function atxpFetch(config) {
         onAuthorize: config.onAuthorize,
         onAuthorizeFailure: config.onAuthorizeFailure,
         onPayment: config.onPayment,
-        onPaymentFailure: config.onPaymentFailure
+        onPaymentFailure: config.onPaymentFailure,
+        onPaymentAttemptFailed: config.onPaymentAttemptFailed
     });
     return fetcher.fetch;
 }
 class ATXPFetcher {
     constructor(config) {
-        this.defaultPaymentFailureHandler = async ({ payment, error }) => {
+        this.defaultPaymentFailureHandler = async (context) => {
+            const { payment, error, attemptedNetworks, retryable } = context;
+            const recoveryHint = getErrorRecoveryHint(error);
+            this.logger.info(`PAYMENT FAILED: ${recoveryHint.title}`);
+            this.logger.info(`Description: ${recoveryHint.description}`);
+            if (attemptedNetworks.length > 0) {
+                this.logger.info(`Attempted networks: ${attemptedNetworks.join(', ')}`);
+            }
+            this.logger.info(`Account: ${payment.accountId}`);
+            // Log actionable guidance
+            if (recoveryHint.actions.length > 0) {
+                this.logger.info(`What to do:`);
+                recoveryHint.actions.forEach((action, index) => {
+                    this.logger.info(`  ${index + 1}. ${action}`);
+                });
+            }
+            if (retryable) {
+                this.logger.info(`This payment can be retried.`);
+            }
+            // Log additional context for specific error types
             if (error instanceof InsufficientFundsError) {
-                const networkText = error.network ? ` on ${error.network}` : '';
-                this.logger.info(`PAYMENT FAILED: Insufficient ${error.currency} funds${networkText}`);
                 this.logger.info(`Required: ${error.required} ${error.currency}`);
                 if (error.available) {
                     this.logger.info(`Available: ${error.available} ${error.currency}`);
                 }
-                this.logger.info(`Account: ${payment.accountId}`);
             }
-            else if (error instanceof PaymentNetworkError) {
-                this.logger.info(`PAYMENT FAILED: Network error: ${error.message}`);
-            }
-            else {
-                this.logger.info(`PAYMENT FAILED: ${error.message}`);
+            else if (error instanceof ATXPPaymentError && error.context) {
+                this.logger.debug(`Error context: ${JSON.stringify(error.context)}`);
             }
         };
         this.handleMultiDestinationPayment = async (paymentRequest, paymentRequestUrl, paymentRequestId) => {
@@ -383,9 +525,11 @@ class ATXPFetcher {
                 this.logger.info(`ATXP: payment request denied by callback function`);
                 return false;
             }
-            // Try each payment maker in order
+            // Try each payment maker in order, tracking attempts
             let lastPaymentError = null;
             let paymentAttempted = false;
+            const attemptedNetworks = [];
+            const failureReasons = new Map();
             for (const paymentMaker of this.account.paymentMakers) {
                 try {
                     // Pass all destinations to payment maker - it will filter and pick the one it can handle
@@ -397,7 +541,11 @@ class ATXPFetcher {
                     paymentAttempted = true;
                     // Payment was successful
                     this.logger.info(`ATXP: made payment of ${firstDest.amount.toString()} ${firstDest.currency} on ${result.chain}: ${result.transactionId}`);
-                    await this.onPayment({ payment: prospectivePayment });
+                    await this.onPayment({
+                        payment: prospectivePayment,
+                        transactionHash: result.transactionId,
+                        network: result.chain
+                    });
                     // Submit payment to the server
                     const jwt = await paymentMaker.generateJWT({ paymentRequestId, codeChallenge: '', accountId: this.account.accountId });
                     const response = await this.sideChannelFetch(paymentRequestUrl.toString(), {
@@ -425,13 +573,41 @@ class ATXPFetcher {
                     const typedError = error;
                     paymentAttempted = true;
                     lastPaymentError = typedError;
-                    this.logger.warn(`ATXP: payment maker failed: ${typedError.message}`);
-                    await this.onPaymentFailure({ payment: prospectivePayment, error: typedError });
+                    // Extract network from error context if available
+                    let network = 'unknown';
+                    if (typedError instanceof ATXPPaymentError && typedError.context?.network) {
+                        network = typeof typedError.context.network === 'string' ? typedError.context.network : 'unknown';
+                    }
+                    attemptedNetworks.push(network);
+                    failureReasons.set(network, typedError);
+                    this.logger.warn(`ATXP: payment maker failed on ${network}: ${typedError.message}`);
+                    // Call optional per-attempt failure callback
+                    if (this.onPaymentAttemptFailed) {
+                        const remainingMakers = this.account.paymentMakers.length - (attemptedNetworks.length);
+                        const remainingNetworks = remainingMakers > 0 ? ['next available'] : [];
+                        await this.onPaymentAttemptFailed({
+                            network,
+                            error: typedError,
+                            remainingNetworks
+                        });
+                    }
                     // Continue to next payment maker
                 }
             }
-            // If payment was attempted but all failed, rethrow the last error
+            // If payment was attempted but all failed, create full context and call onPaymentFailure
             if (paymentAttempted && lastPaymentError) {
+                const isRetryable = lastPaymentError instanceof ATXPPaymentError
+                    ? lastPaymentError.retryable
+                    : true; // Default to retryable for unknown errors
+                const failureContext = {
+                    payment: prospectivePayment,
+                    error: lastPaymentError,
+                    attemptedNetworks,
+                    failureReasons,
+                    retryable: isRetryable,
+                    timestamp: new Date()
+                };
+                await this.onPaymentFailure(failureContext);
                 throw lastPaymentError;
             }
             this.logger.info(`ATXP: no payment maker could handle these destinations`);
@@ -679,7 +855,7 @@ class ATXPFetcher {
                 throw error;
             }
         };
-        const { account, db, destinationMakers, fetchFn = fetch, sideChannelFetch = fetchFn, strict = true, allowInsecureRequests = process.env.NODE_ENV === 'development', allowedAuthorizationServers = [DEFAULT_AUTHORIZATION_SERVER], approvePayment = async () => true, logger = new ConsoleLogger(), onAuthorize = async () => { }, onAuthorizeFailure = async () => { }, onPayment = async () => { }, onPaymentFailure = async () => { } } = config;
+        const { account, db, destinationMakers, fetchFn = fetch, sideChannelFetch = fetchFn, strict = true, allowInsecureRequests = process.env.NODE_ENV === 'development', allowedAuthorizationServers = [DEFAULT_AUTHORIZATION_SERVER], approvePayment = async () => true, logger = new ConsoleLogger(), onAuthorize = async () => { }, onAuthorizeFailure = async () => { }, onPayment = async () => { }, onPaymentFailure, onPaymentAttemptFailed } = config;
         // Use React Native safe fetch if in React Native environment
         const safeFetchFn = getIsReactNative() ? createReactNativeSafeFetch(fetchFn) : fetchFn;
         const safeSideChannelFetch = getIsReactNative() ? createReactNativeSafeFetch(sideChannelFetch) : sideChannelFetch;
@@ -708,6 +884,7 @@ class ATXPFetcher {
         this.onAuthorizeFailure = onAuthorizeFailure;
         this.onPayment = onPayment;
         this.onPaymentFailure = onPaymentFailure || this.defaultPaymentFailureHandler;
+        this.onPaymentAttemptFailed = onPaymentAttemptFailed;
     }
 }
 
@@ -16004,7 +16181,8 @@ const DEFAULT_CLIENT_CONFIG = {
     onAuthorize: async () => { },
     onAuthorizeFailure: async () => { },
     onPayment: async () => { },
-    onPaymentFailure: async () => { }
+    onPaymentFailure: async () => { },
+    onPaymentAttemptFailed: async () => { }
 };
 function buildClientConfig(args) {
     // Use fetchFn for oAuthChannelFetch if the latter isn't explicitly set
@@ -16312,5 +16490,5 @@ class ATXPLocalAccount {
     }
 }
 
-export { ATXPDestinationMaker, ATXPLocalAccount, DEFAULT_CLIENT_CONFIG, InsufficientFundsError, OAuthAuthenticationRequiredError, OAuthClient, POLYGON_AMOY, POLYGON_MAINNET, PassthroughDestinationMaker, PaymentNetworkError, USDC_CONTRACT_ADDRESS_POLYGON_AMOY, USDC_CONTRACT_ADDRESS_POLYGON_MAINNET, USDC_CONTRACT_ADDRESS_WORLD_MAINNET, USDC_CONTRACT_ADDRESS_WORLD_SEPOLIA, WORLD_CHAIN_MAINNET, WORLD_CHAIN_SEPOLIA, atxpClient, atxpFetch, buildClientConfig, buildStreamableTransport, getPolygonAmoyWithRPC, getPolygonByChainId, getPolygonMainnetWithRPC, getPolygonUSDCAddress, getWorldChainByChainId, getWorldChainMainnetWithRPC, getWorldChainSepoliaWithRPC, getWorldChainUSDCAddress };
+export { ATXPDestinationMaker, ATXPLocalAccount, ATXPPaymentError, DEFAULT_CLIENT_CONFIG, GasEstimationError, InsufficientFundsError, OAuthAuthenticationRequiredError, OAuthClient, POLYGON_AMOY, POLYGON_MAINNET, PassthroughDestinationMaker, PaymentExpiredError, PaymentNetworkError, PaymentServerError, RpcError, TransactionRevertedError, USDC_CONTRACT_ADDRESS_POLYGON_AMOY, USDC_CONTRACT_ADDRESS_POLYGON_MAINNET, USDC_CONTRACT_ADDRESS_WORLD_MAINNET, USDC_CONTRACT_ADDRESS_WORLD_SEPOLIA, UnsupportedCurrencyError, UserRejectedError, WORLD_CHAIN_MAINNET, WORLD_CHAIN_SEPOLIA, atxpClient, atxpFetch, buildClientConfig, buildStreamableTransport, getPolygonAmoyWithRPC, getPolygonByChainId, getPolygonMainnetWithRPC, getPolygonUSDCAddress, getWorldChainByChainId, getWorldChainMainnetWithRPC, getWorldChainSepoliaWithRPC, getWorldChainUSDCAddress };
 //# sourceMappingURL=index.js.map