@atxp/client 0.9.0 → 0.9.1

package/dist/index.cjs

@@ -295,25 +295,153 @@ class OAuthClient extends common.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.';
     }
 }
 
@@ -338,27 +466,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 = common.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) => {
@@ -403,9 +545,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
@@ -417,7 +561,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(), {
@@ -445,13 +593,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`);
@@ -699,7 +875,7 @@ class ATXPFetcher {
                 throw error;
             }
         };
-        const { account, db, destinationMakers, fetchFn = fetch, sideChannelFetch = fetchFn, strict = true, allowInsecureRequests = process.env.NODE_ENV === 'development', allowedAuthorizationServers = [common.DEFAULT_AUTHORIZATION_SERVER], approvePayment = async () => true, logger = new common.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 = [common.DEFAULT_AUTHORIZATION_SERVER], approvePayment = async () => true, logger = new common.ConsoleLogger(), onAuthorize = async () => { }, onAuthorizeFailure = async () => { }, onPayment = async () => { }, onPaymentFailure, onPaymentAttemptFailed } = config;
         // Use React Native safe fetch if in React Native environment
         const safeFetchFn = common.getIsReactNative() ? common.createReactNativeSafeFetch(fetchFn) : fetchFn;
         const safeSideChannelFetch = common.getIsReactNative() ? common.createReactNativeSafeFetch(sideChannelFetch) : sideChannelFetch;
@@ -728,6 +904,7 @@ class ATXPFetcher {
         this.onAuthorizeFailure = onAuthorizeFailure;
         this.onPayment = onPayment;
         this.onPaymentFailure = onPaymentFailure || this.defaultPaymentFailureHandler;
+        this.onPaymentAttemptFailed = onPaymentAttemptFailed;
     }
 }
 
@@ -16024,7 +16201,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
@@ -16338,18 +16516,26 @@ Object.defineProperty(exports, "ATXPAccount", {
 });
 exports.ATXPDestinationMaker = ATXPDestinationMaker;
 exports.ATXPLocalAccount = ATXPLocalAccount;
+exports.ATXPPaymentError = ATXPPaymentError;
 exports.DEFAULT_CLIENT_CONFIG = DEFAULT_CLIENT_CONFIG;
+exports.GasEstimationError = GasEstimationError;
 exports.InsufficientFundsError = InsufficientFundsError;
 exports.OAuthAuthenticationRequiredError = OAuthAuthenticationRequiredError;
 exports.OAuthClient = OAuthClient;
 exports.POLYGON_AMOY = POLYGON_AMOY;
 exports.POLYGON_MAINNET = POLYGON_MAINNET;
 exports.PassthroughDestinationMaker = PassthroughDestinationMaker;
+exports.PaymentExpiredError = PaymentExpiredError;
 exports.PaymentNetworkError = PaymentNetworkError;
+exports.PaymentServerError = PaymentServerError;
+exports.RpcError = RpcError;
+exports.TransactionRevertedError = TransactionRevertedError;
 exports.USDC_CONTRACT_ADDRESS_POLYGON_AMOY = USDC_CONTRACT_ADDRESS_POLYGON_AMOY;
 exports.USDC_CONTRACT_ADDRESS_POLYGON_MAINNET = USDC_CONTRACT_ADDRESS_POLYGON_MAINNET;
 exports.USDC_CONTRACT_ADDRESS_WORLD_MAINNET = USDC_CONTRACT_ADDRESS_WORLD_MAINNET;
 exports.USDC_CONTRACT_ADDRESS_WORLD_SEPOLIA = USDC_CONTRACT_ADDRESS_WORLD_SEPOLIA;
+exports.UnsupportedCurrencyError = UnsupportedCurrencyError;
+exports.UserRejectedError = UserRejectedError;
 exports.WORLD_CHAIN_MAINNET = WORLD_CHAIN_MAINNET;
 exports.WORLD_CHAIN_SEPOLIA = WORLD_CHAIN_SEPOLIA;
 exports.atxpClient = atxpClient;