@atxp/client 0.8.3 → 0.9.1

package/dist/index.d.ts

@@ -1,12 +1,126 @@
-import { Account, Network, DestinationMaker, AuthorizationServerUrl, AccountId, Currency, OAuthDb, FetchLike, Logger, OAuthResourceClient, ClientCredentials, PKCEValues, AccessToken, PaymentMaker, Destination, PaymentIdentifier, Source, PaymentRequestOption } 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';
 import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
 import * as oauth from 'oauth4webapi';
-import { ValidateTransferError as ValidateTransferError$1 } from '@solana/pay';
-import BigNumber$1 from 'bignumber.js';
-import { WalletClient, PublicActions, LocalAccount, Address, TypedData, Hex as Hex$1, SignableMessage, TransactionSerializable } from 'viem';
+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;
@@ -19,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;
@@ -44,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';
@@ -55,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>;
@@ -125,66 +250,6 @@ declare class OAuthClient extends OAuthResourceClient {
  */
 declare function atxpFetch(config: ClientConfig): FetchLike;
 
-declare const ValidateTransferError: typeof ValidateTransferError$1;
-declare class SolanaPaymentMaker implements PaymentMaker {
-    private connection;
-    private source;
-    private logger;
-    constructor(solanaEndpoint: string, sourceSecretKey: string, logger?: Logger);
-    getSourceAddress(_params: {
-        amount: BigNumber$1;
-        currency: Currency;
-        receiver: string;
-        memo: string;
-    }): string;
-    generateJWT: ({ paymentRequestId, codeChallenge, accountId }: {
-        paymentRequestId: string;
-        codeChallenge: string;
-        accountId?: AccountId | null;
-    }) => Promise<string>;
-    makePayment: (destinations: Destination[], memo: string, _paymentRequestId?: string) => Promise<PaymentIdentifier | null>;
-}
-
-type ExtendedWalletClient = WalletClient & PublicActions;
-declare class BasePaymentMaker implements PaymentMaker {
-    protected signingClient: ExtendedWalletClient;
-    protected logger: Logger;
-    constructor(baseRPCUrl: string, walletClient: WalletClient, logger?: Logger);
-    getSourceAddress(_params: {
-        amount: BigNumber;
-        currency: Currency;
-        receiver: string;
-        memo: string;
-    }): string;
-    generateJWT({ paymentRequestId, codeChallenge, accountId }: {
-        paymentRequestId: string;
-        codeChallenge: string;
-        accountId?: AccountId | null;
-    }): Promise<string>;
-    makePayment(destinations: Destination[], _memo: string, _paymentRequestId?: string): Promise<PaymentIdentifier | null>;
-}
-
-declare class SolanaAccount implements Account {
-    accountId: AccountId;
-    paymentMakers: PaymentMaker[];
-    private sourcePublicKey;
-    constructor(solanaEndpoint: string, sourceSecretKey: string);
-    /**
-     * Get sources for this account
-     */
-    getSources(): Promise<Source[]>;
-}
-
-declare const USDC_CONTRACT_ADDRESS_BASE = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
-declare const USDC_CONTRACT_ADDRESS_BASE_SEPOLIA = "0x036CbD53842c5426634e7929541eC2318f3dCF7e";
-/**
- * Get USDC contract address for Base chain by chain ID
- * @param chainId - Chain ID (8453 for mainnet, 84532 for sepolia)
- * @returns USDC contract address
- * @throws Error if chain ID is not supported
- */
-declare const getBaseUSDCAddress: (chainId: number) => string;
-
 /**
  * World Chain configuration type, compatible with viem's Chain interface
  */
@@ -291,23 +356,6 @@ declare const getPolygonByChainId: (chainId: number) => PolygonChain;
  */
 declare const getPolygonUSDCAddress: (chainId: number) => string;
 
-declare class BaseAccount implements Account {
-    accountId: AccountId;
-    paymentMakers: PaymentMaker[];
-    private walletClient;
-    private account;
-    constructor(baseRPCUrl: string, sourceSecretKey: string);
-    /**
-     * Get the LocalAccount (signer) for this account.
-     * This can be used with the x402 library or other signing operations.
-     */
-    getLocalAccount(): LocalAccount;
-    /**
-     * Get sources for this account
-     */
-    getSources(): Promise<Source[]>;
-}
-
 /**
  * ATXP implementation of viem's LocalAccount interface.
  * Delegates signing operations to the accounts-x402 API.
@@ -375,5 +423,5 @@ declare class PassthroughDestinationMaker implements DestinationMaker {
     makeDestinations(option: PaymentRequestOption, _logger: Logger, _paymentRequestId: string, _sources: Source[]): Promise<Destination[]>;
 }
 
-export { ATXPDestinationMaker, ATXPLocalAccount, BaseAccount, BasePaymentMaker, DEFAULT_CLIENT_CONFIG, InsufficientFundsError, OAuthAuthenticationRequiredError, OAuthClient, POLYGON_AMOY, POLYGON_MAINNET, PassthroughDestinationMaker, PaymentNetworkError, SolanaAccount, SolanaPaymentMaker, USDC_CONTRACT_ADDRESS_BASE, USDC_CONTRACT_ADDRESS_BASE_SEPOLIA, USDC_CONTRACT_ADDRESS_POLYGON_AMOY, USDC_CONTRACT_ADDRESS_POLYGON_MAINNET, USDC_CONTRACT_ADDRESS_WORLD_MAINNET, USDC_CONTRACT_ADDRESS_WORLD_SEPOLIA, ValidateTransferError, WORLD_CHAIN_MAINNET, WORLD_CHAIN_SEPOLIA, atxpClient, atxpFetch, buildClientConfig, buildStreamableTransport, getBaseUSDCAddress, 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,qBAAqB,EACrB,kBAAkB,EACnB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,gBAAgB,EACjB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,aAAa,EACd,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,WAAW,EACZ,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,0BAA0B,EAC1B,kCAAkC,EAClC,kBAAkB,EACnB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,mCAAmC,EACnC,mCAAmC,EACnC,mBAAmB,EACnB,mBAAmB,EACnB,2BAA2B,EAC3B,2BAA2B,EAC3B,sBAAsB,EACtB,wBAAwB,EACxB,KAAK,UAAU,EAChB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,qCAAqC,EACrC,kCAAkC,EAClC,eAAe,EACf,YAAY,EACZ,wBAAwB,EACxB,qBAAqB,EACrB,mBAAmB,EACnB,qBAAqB,EACrB,KAAK,YAAY,EAClB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,WAAW,EACZ,MAAM,kBAAkB,CAAC;AAG1B,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;AAEpB,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"}