@atxp/client 0.10.6 → 0.10.8

package/dist/index.d.ts

@@ -1,11 +1,50 @@
-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 { Account, Logger, FetchLike, Currency, Network, DestinationMaker, AuthorizationServerUrl, AccountId, OAuthDb, ProtocolFlag, OAuthResourceClient, ClientCredentials, PKCEValues, AccessToken, PaymentRequestOption, Source, Destination, PaymentProtocol, AuthorizeResult } from '@atxp/common';
+export { ATXPAccount, Account, AuthorizeResult, 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 { LocalAccount, Address, TypedData, Hex as Hex$1, SignableMessage, TransactionSerializable } from 'viem';
 
+/**
+ * Configuration passed to protocol handlers.
+ */
+interface ProtocolConfig {
+    account: Account;
+    logger: Logger;
+    fetchFn: FetchLike;
+    approvePayment: (payment: ProspectivePayment) => Promise<boolean>;
+    onPayment: (args: {
+        payment: ProspectivePayment;
+        transactionHash: string;
+        network: string;
+    }) => Promise<void>;
+    onPaymentFailure: (context: PaymentFailureContext) => Promise<void>;
+}
+/**
+ * Strategy interface for handling different payment protocol challenges.
+ *
+ * Implementations detect whether a response contains a payment challenge
+ * they can handle, and execute the payment flow if so.
+ */
+interface ProtocolHandler {
+    /** Unique protocol identifier */
+    readonly protocol: string;
+    /**
+     * Check if this handler can handle the given response.
+     * Must not consume the response body (use clone if needed).
+     */
+    canHandle(response: Response): Promise<boolean>;
+    /**
+     * Handle a payment challenge from the response.
+     * Returns the retry response after payment, or null if the challenge couldn't be handled.
+     */
+    handlePaymentChallenge(response: Response, originalRequest: {
+        url: string | URL;
+        init?: RequestInit;
+    }, config: ProtocolConfig): Promise<Response | null>;
+}
+
 /**
  * Base class for all ATXP payment errors with structured error codes and actionable guidance
  */
@@ -185,6 +224,10 @@ type ClientConfig = {
         error: Error;
         remainingNetworks: string[];
     }) => Promise<void>;
+    /** Optional protocol handlers for multi-protocol support (strategy pattern) */
+    protocolHandlers?: ProtocolHandler[];
+    /** Optional protocol flag function to select protocol for omni-challenges */
+    protocolFlag?: ProtocolFlag;
 };
 type RequiredClientConfigFields$1 = 'mcpServer' | 'account';
 type RequiredClientConfig = Pick<ClientConfig, RequiredClientConfigFields$1>;
@@ -194,7 +237,7 @@ type FetchWrapper = (config: ClientArgs) => FetchLike;
 
 type RequiredClientConfigFields = 'mcpServer' | 'account';
 type OptionalClientConfig = Omit<ClientConfig, RequiredClientConfigFields>;
-type BuildableClientConfigFields = 'oAuthDb' | 'logger' | 'destinationMakers';
+type BuildableClientConfigFields = 'oAuthDb' | 'logger' | 'destinationMakers' | 'protocolHandlers' | 'protocolFlag';
 declare const DEFAULT_CLIENT_CONFIG: Required<Omit<OptionalClientConfig, BuildableClientConfigFields>>;
 declare function buildClientConfig(args: ClientArgs): ClientConfig;
 declare function buildStreamableTransport(args: ClientArgs): StreamableHTTPClientTransport;
@@ -425,5 +468,140 @@ declare class PassthroughDestinationMaker implements DestinationMaker {
     makeDestinations(option: PaymentRequestOption, _logger: Logger, _paymentRequestId: string, _sources: Source[]): Promise<Destination[]>;
 }
 
-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 };
+interface X402ProtocolHandlerConfig {
+    accountsServer?: string;
+}
+/**
+ * Protocol handler for X402 payment challenges.
+ *
+ * Detects HTTP 402 responses with x402Version in the JSON body.
+ * Creates payment headers using the x402 library and retries the request.
+ */
+declare class X402ProtocolHandler implements ProtocolHandler {
+    readonly protocol = "x402";
+    private accountsServer;
+    constructor(config?: X402ProtocolHandlerConfig);
+    canHandle(response: Response): Promise<boolean>;
+    handlePaymentChallenge(response: Response, originalRequest: {
+        url: string | URL;
+        init?: RequestInit;
+    }, config: ProtocolConfig): Promise<Response | null>;
+    private reconstructResponse;
+}
+
+/**
+ * Protocol handler for ATXP-MCP payment challenges.
+ *
+ * Detects JSON-RPC errors with code -30402 (PAYMENT_REQUIRED_ERROR_CODE) in
+ * MCP responses (both SSE and JSON formats).
+ */
+declare class ATXPProtocolHandler implements ProtocolHandler {
+    readonly protocol = "atxp";
+    canHandle(response: Response): Promise<boolean>;
+    handlePaymentChallenge(response: Response, _originalRequest: {
+        url: string | URL;
+        init?: RequestInit;
+    }, config: ProtocolConfig): Promise<Response | null>;
+    private extractPaymentRequests;
+}
+
+/**
+ * Configuration for MPP protocol handler.
+ */
+interface MPPProtocolHandlerConfig {
+    accountsServer?: string;
+}
+/**
+ * Protocol handler for MPP (Machine Payments Protocol) payment challenges.
+ *
+ * Detects MPP challenges in two forms:
+ * 1. HTTP level: HTTP 402 with WWW-Authenticate: Payment header
+ * 2. MCP level: JSON-RPC error with code -32042 containing MPP data
+ *
+ * Handles the challenge by calling /authorize/mpp on the accounts service
+ * and retrying with an Authorization: Payment header.
+ */
+declare class MPPProtocolHandler implements ProtocolHandler {
+    readonly protocol = "mpp";
+    private accountsServer;
+    constructor(config?: MPPProtocolHandlerConfig);
+    canHandle(response: Response): Promise<boolean>;
+    handlePaymentChallenge(response: Response, originalRequest: {
+        url: string | URL;
+        init?: RequestInit;
+    }, config: ProtocolConfig): Promise<Response | null>;
+    /**
+     * Extract MPP challenge from response - tries HTTP header first, then MCP error body.
+     * Returns both the challenge and the body text to avoid double-consumption.
+     */
+    private extractChallenge;
+    /**
+     * Build a ProspectivePayment from an MPP challenge.
+     */
+    private buildProspectivePayment;
+    /**
+     * Report a payment failure via the onPaymentFailure callback.
+     */
+    private reportFailure;
+    /**
+     * Call /authorize/mpp on accounts service and retry the original request with the credential.
+     */
+    private authorizeAndRetry;
+    private reconstructResponse;
+}
+
+/**
+ * Build protocol-specific payment headers for retrying a request after authorization.
+ *
+ * @param result - The authorization result containing protocol and credential
+ * @param originalHeaders - Optional original request headers to preserve
+ * @returns New Headers object with protocol-specific payment headers added
+ */
+declare function buildPaymentHeaders(result: AuthorizeResult, originalHeaders?: HeadersInit): Headers;
+/**
+ * Client for authorizing payments.
+ *
+ * Resolves the payment protocol via protocolFlag, then delegates to
+ * account.authorize() for the actual authorization logic.
+ */
+declare class PaymentClient {
+    private protocolFlag?;
+    private logger;
+    constructor(config: {
+        protocolFlag?: ProtocolFlag;
+        logger: Logger;
+        /** @deprecated No longer used — authorization delegates to account.authorize() */
+        accountsServer?: string;
+        /** @deprecated No longer used — authorization delegates to account.authorize() */
+        fetchFn?: FetchLike;
+    });
+    /**
+     * Authorize a payment by delegating to the account's authorize method.
+     *
+     * PaymentClient resolves the protocol (via explicit param or protocolFlag),
+     * then delegates all protocol-specific logic to account.authorize().
+     *
+     * @param params.account - The account to authorize the payment through
+     * @param params.userId - Passed to protocolFlag for protocol selection
+     * @param params.destination - Payment destination address
+     * @param params.protocol - Explicit protocol override (skips protocolFlag)
+     * @param params.amount - Payment amount
+     * @param params.memo - Payment memo
+     * @param params.paymentRequirements - X402 payment requirements
+     * @param params.challenge - MPP challenge object
+     * @returns AuthorizeResult with protocol and opaque credential
+     */
+    authorize(params: {
+        account: Account;
+        userId: string;
+        destination: string;
+        protocol?: PaymentProtocol;
+        amount?: BigNumber;
+        memo?: string;
+        paymentRequirements?: unknown;
+        challenge?: unknown;
+    }): Promise<AuthorizeResult>;
+}
+
+export { ATXPDestinationMaker, ATXPLocalAccount, ATXPPaymentError, ATXPProtocolHandler, DEFAULT_CLIENT_CONFIG, GasEstimationError, InsufficientFundsError, MPPProtocolHandler, OAuthAuthenticationRequiredError, OAuthClient, POLYGON_AMOY, POLYGON_MAINNET, PassthroughDestinationMaker, PaymentClient, 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, X402ProtocolHandler, atxpClient, atxpFetch, buildClientConfig, buildPaymentHeaders, buildStreamableTransport, getPolygonAmoyWithRPC, getPolygonByChainId, getPolygonMainnetWithRPC, getPolygonUSDCAddress, getWorldChainByChainId, getWorldChainMainnetWithRPC, getWorldChainSepoliaWithRPC, getWorldChainUSDCAddress };
+export type { AccountIdString, ClientArgs, ClientConfig, FetchWrapper, Hex, OAuthClientConfig, PaymentFailureContext, PolygonChain, ProspectivePayment, ProtocolConfig, ProtocolHandler, 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,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"}
+{"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;AAGtC,YAAY,EACV,eAAe,EACf,cAAc,EACf,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,mBAAmB,EACpB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACL,mBAAmB,EACpB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACL,kBAAkB,EACnB,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EACL,aAAa,EACb,mBAAmB,EACnB,KAAK,eAAe,EACrB,MAAM,oBAAoB,CAAC"}