@dcentralab/d402-client 0.3.5 → 0.3.8

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { Account } from 'viem/accounts';
-import { PublicClient, WalletClient, Hash, Address } from 'viem';
+import { WalletClient, PublicClient, Hash, Address } from 'viem';
+import { Chain } from 'viem/chains';
 
 /**
  * Type definitions for D402 payment protocol
@@ -198,6 +199,11 @@ interface D402ClientConfig {
      * Typically from wagmi: `walletClient.account`
      */
     operatorAccount: Account;
+    /**
+     * Wallet client for signing (required for wagmi/browser use).
+     * This is needed because wagmi accounts don't have signTypedData directly.
+     */
+    walletClient?: WalletClient;
     /**
      * IATPWallet contract address.
      * Get from `createIATPWallet()` or `getWalletsByOwner()`.
@@ -267,6 +273,7 @@ interface D402ClientConfig {
  */
 declare class D402Client {
     private readonly operatorAccount;
+    private readonly walletClient?;
     private readonly iatpWalletAddress;
     private readonly maxValue?;
     private readonly paymentRequirementsSelector;
@@ -383,6 +390,45 @@ declare class D402Client {
      * ```
      */
     fetch(url: string, init?: RequestInit): Promise<Response>;
+    /**
+     * Call an MCP tool with automatic session initialization and payment handling.
+     *
+     * This is the simplest way to call an MCP tool. It handles:
+     * - MCP session initialization
+     * - JSON-RPC payload construction
+     * - HTTP 402 payment flow
+     * - SSE/JSON response parsing
+     *
+     * @param endpoint - MCP server endpoint URL
+     * @param toolName - Name of the tool to call
+     * @param input - Tool arguments
+     * @param options - Optional configuration
+     * @returns The tool's result data
+     *
+     * @example
+     * ```ts
+     * const client = new D402Client({
+     *   operatorAccount: walletClient.account,
+     *   walletClient,
+     *   iatpWalletAddress,
+     * })
+     *
+     * // Simple one-liner!
+     * const result = await client.mcpCall(
+     *   'https://my-mcp.example.com/mcp',
+     *   'google_search',
+     *   { q: 'test search' }
+     * )
+     *
+     * console.log(result) // { searchResults: [...] }
+     * ```
+     */
+    mcpCall(endpoint: string, toolName: string, input: Record<string, unknown>, options?: {
+        /** Skip session initialization (for stateless servers) */
+        skipInit?: boolean;
+        /** Custom JSON-RPC request ID */
+        requestId?: string | number;
+    }): Promise<unknown>;
 }
 
 /**
@@ -399,6 +445,7 @@ declare class D402Client {
  *
  * @param params - Signing parameters
  * @param params.operatorAccount - User's account for signing (from wagmi walletClient)
+ * @param params.walletClient - Optional wallet client for signing (wagmi). If provided, uses walletClient.signTypedData
  * @param params.paymentRequirement - Payment requirements from 402 response
  * @param params.iatpWalletAddress - IATPWallet contract address (optional)
  * @param params.requestPath - API request path (optional, uses payment_requirements.resource if not provided)
@@ -412,6 +459,7 @@ declare class D402Client {
  * // User signs payment (MetaMask popup appears)
  * const signedPayment = await signD402Payment({
  *   operatorAccount: walletClient.account,  // User's wallet
+ *   walletClient: walletClient,              // For signing with wagmi
  *   paymentRequirement: requirement,
  *   iatpWalletAddress: '0xUserIATPWallet...'
  * })
@@ -422,6 +470,7 @@ declare class D402Client {
  */
 declare function signD402Payment(params: {
     operatorAccount: Account;
+    walletClient?: WalletClient;
     paymentRequirement: PaymentRequirement;
     iatpWalletAddress: `0x${string}`;
     requestPath?: string;
@@ -542,6 +591,23 @@ declare function decodePaymentResponse(header: string): {
     message?: string;
 };
 
+/**
+ * Core type definitions shared across the package
+ */
+/**
+ * Supported blockchain networks (where IATP contracts are deployed)
+ */
+type SupportedNetwork = 'sepolia' | 'arbitrum';
+/**
+ * EIP-712 domain for signature verification
+ */
+interface EIP712Domain {
+    name: string;
+    version: string;
+    chainId: number;
+    verifyingContract: `0x${string}`;
+}
+
 /**
  * Type definitions for wallet module
  */
@@ -592,7 +658,7 @@ interface WithdrawalRequest {
  *
  * @param params - Creation parameters
  * @param params.ownerAccount - Owner's account (will own the wallet)
- * @param params.network - Network to deploy on (default: "sepolia")
+ * @param params.network - Network to deploy on: "sepolia" | "arbitrum" (default: "sepolia")
  * @param params.rpcUrl - Custom RPC URL (optional)
  * @returns Wallet creation result with addresses and keys
  *
@@ -613,7 +679,8 @@ interface WithdrawalRequest {
  */
 declare function createIATPWallet(params: {
     ownerAccount: Account;
-    network?: 'sepolia';
+    walletClient?: WalletClient;
+    network?: SupportedNetwork;
     rpcUrl?: string;
 }): Promise<WalletCreationResult>;
 
@@ -631,7 +698,7 @@ declare function createIATPWallet(params: {
  * @param params.publicClient - Viem PublicClient (from wagmi usePublicClient)
  * @param params.walletAddress - IATPWallet contract address
  * @param params.tokenAddress - Token contract address (e.g., USDC)
- * @param params.network - Network to query (default: "sepolia")
+ * @param params.network - Network to query: "sepolia" | "arbitrum" (default: "sepolia")
  * @returns Available balance in token's base units (wei)
  *
  * @example
@@ -654,7 +721,7 @@ declare function getAvailableBalance(params: {
     publicClient: PublicClient;
     walletAddress: Address;
     tokenAddress: Address;
-    network?: 'sepolia';
+    network?: SupportedNetwork;
 }): Promise<bigint>;
 /**
  * Get all IATPWallet addresses owned by a user.
@@ -666,7 +733,7 @@ declare function getAvailableBalance(params: {
  *
  * @param params - Query parameters
  * @param params.ownerAddress - User's wallet address (from MetaMask)
- * @param params.network - Network to query (default: "sepolia")
+ * @param params.network - Network to query: "sepolia" | "arbitrum" (default: "sepolia")
  * @param params.rpcUrl - Custom RPC URL (optional)
  * @returns Array of IATPWallet contract addresses (empty if user has no wallets)
  *
@@ -692,7 +759,7 @@ declare function getAvailableBalance(params: {
  */
 declare function getWalletsByOwner(params: {
     ownerAddress: Address;
-    network?: 'sepolia';
+    network?: SupportedNetwork;
     rpcUrl?: string;
 }): Promise<Address[]>;
 
@@ -710,7 +777,7 @@ declare function getWalletsByOwner(params: {
  * @param params.publicClient - Viem PublicClient
  * @param params.walletAddress - IATPWallet contract address
  * @param params.tokenAddress - Token contract address
- * @param params.network - Network to query (default: "sepolia")
+ * @param params.network - Network: "sepolia" | "arbitrum" (default: "sepolia")
  * @returns Withdrawal request details or null if no request exists
  *
  * @example
@@ -739,7 +806,7 @@ declare function getWithdrawalRequest(params: {
     publicClient: PublicClient;
     walletAddress: Address;
     tokenAddress: Address;
-    network?: 'sepolia';
+    network?: SupportedNetwork;
 }): Promise<{
     request: WithdrawalRequest;
     unlockTime: bigint;
@@ -757,7 +824,7 @@ declare function getWithdrawalRequest(params: {
  * @param params.tokenAddress - Token contract address
  * @param params.amount - Amount in token's base units (wei)
  * @param params.account - Account to sign transaction (operator)
- * @param params.network - Network (default: "sepolia")
+ * @param params.network - Network: "sepolia" | "arbitrum" (default: "sepolia")
  * @returns Transaction hash
  *
  * @example
@@ -782,7 +849,7 @@ declare function requestWithdrawal(params: {
     tokenAddress: Address;
     amount: bigint;
     account: Account;
-    network?: 'sepolia';
+    network?: SupportedNetwork;
 }): Promise<Hash>;
 /**
  * Execute a withdrawal from an IATPWallet (after unlock period).
@@ -796,7 +863,7 @@ declare function requestWithdrawal(params: {
  * @param params.walletAddress - IATPWallet contract address
  * @param params.tokenAddress - Token contract address
  * @param params.account - Account to sign transaction (operator)
- * @param params.network - Network (default: "sepolia")
+ * @param params.network - Network: "sepolia" | "arbitrum" (default: "sepolia")
  * @returns Transaction hash
  *
  * @example
@@ -818,9 +885,112 @@ declare function executeWithdrawal(params: {
     walletAddress: Address;
     tokenAddress: Address;
     account: Account;
-    network?: 'sepolia';
+    network?: SupportedNetwork;
 }): Promise<Hash>;
 
+/**
+ * MCP Session Management
+ *
+ * Handles MCP protocol session initialization.
+ */
+/**
+ * Initialize an MCP session with the server.
+ *
+ * Sends the `initialize` JSON-RPC method to establish a session.
+ * Some servers return a session ID in headers, others are stateless.
+ *
+ * @param endpoint - MCP server endpoint URL
+ * @returns Session ID if provided by server, null otherwise
+ */
+declare function initMcpSession(endpoint: string): Promise<string | null>;
+
+/**
+ * MCP Payload Builder
+ *
+ * Constructs JSON-RPC payloads for MCP tool calls.
+ */
+interface JsonRpcPayload {
+    jsonrpc: '2.0';
+    id: string | number;
+    method: string;
+    params: {
+        name: string;
+        arguments: Record<string, unknown>;
+    };
+}
+/**
+ * Build a JSON-RPC payload for an MCP tool call.
+ *
+ * @param toolName - Name of the MCP tool to call
+ * @param args - Tool arguments
+ * @param requestId - Optional custom request ID (default: 1)
+ * @returns Complete JSON-RPC payload ready to send
+ *
+ * @example
+ * ```ts
+ * const payload = buildToolCallPayload('google_search', { q: 'test' })
+ * // { jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name: 'google_search', arguments: { q: 'test' } } }
+ * ```
+ */
+declare function buildToolCallPayload(toolName: string, args: Record<string, unknown>, requestId?: string | number): JsonRpcPayload;
+/**
+ * Build headers for an MCP request.
+ *
+ * @param sessionId - Optional MCP session ID
+ * @returns Headers object for fetch
+ */
+declare function buildMcpHeaders(sessionId?: string | null): Record<string, string>;
+
+/**
+ * MCP Response Parser
+ *
+ * Handles parsing of MCP responses in both JSON and SSE formats.
+ */
+interface McpToolResult {
+    /** Whether the tool call was successful */
+    isError: boolean;
+    /** The tool's output content */
+    content: Array<{
+        type: string;
+        text?: string;
+        [key: string]: unknown;
+    }>;
+    /** Structured content if available */
+    structuredContent?: unknown;
+}
+interface ParsedMcpResponse {
+    /** JSON-RPC response ID */
+    id: string | number;
+    /** The tool result */
+    result: McpToolResult | unknown;
+    /** Error if the call failed */
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+/**
+ * Parse an MCP response, handling both SSE and JSON formats.
+ *
+ * MCP servers may return responses as:
+ * - `application/json`: Standard JSON response
+ * - `text/event-stream`: Server-Sent Events with `data: {...}` format
+ *
+ * @param response - Fetch Response object
+ * @returns Parsed response data
+ */
+declare function parseMcpResponse(response: Response): Promise<ParsedMcpResponse>;
+/**
+ * Extract the tool result from an MCP response.
+ *
+ * Handles the nested structure and returns just the useful data.
+ *
+ * @param response - Parsed MCP response
+ * @returns The tool's result data
+ */
+declare function extractToolResult(response: ParsedMcpResponse): unknown;
+
 /**
  * IATPSettlementLayer query functions
  */
@@ -835,7 +1005,7 @@ declare function executeWithdrawal(params: {
  * @param params.publicClient - Viem PublicClient (from wagmi usePublicClient)
  * @param params.providerAddress - Provider (utility agent) IATPWallet address
  * @param params.tokenAddress - Token contract address
- * @param params.network - Network (default: "sepolia")
+ * @param params.network - Network: "sepolia" | "arbitrum" (default: "sepolia")
  * @returns Locked balance in base units (wei)
  *
  * @example
@@ -856,7 +1026,7 @@ declare function getLockedBalanceForProvider(params: {
     publicClient: PublicClient;
     providerAddress: Address;
     tokenAddress: Address;
-    network?: 'sepolia';
+    network?: SupportedNetwork;
 }): Promise<bigint>;
 /**
  * Get unlocked balance for a provider across released epochs.
@@ -868,7 +1038,7 @@ declare function getLockedBalanceForProvider(params: {
  * @param params.publicClient - Viem PublicClient (from wagmi usePublicClient)
  * @param params.providerAddress - Provider (utility agent) IATPWallet address
  * @param params.tokenAddress - Token contract address
- * @param params.network - Network (default: "sepolia")
+ * @param params.network - Network: "sepolia" | "arbitrum" (default: "sepolia")
  * @returns Unlocked balance in base units (wei)
  *
  * @example
@@ -889,7 +1059,7 @@ declare function getUnlockedBalanceForProvider(params: {
     publicClient: PublicClient;
     providerAddress: Address;
     tokenAddress: Address;
-    network?: 'sepolia';
+    network?: SupportedNetwork;
 }): Promise<bigint>;
 
 /**
@@ -909,7 +1079,7 @@ declare function getUnlockedBalanceForProvider(params: {
  * @param params.walletClient - Viem WalletClient (from wagmi useWalletClient)
  * @param params.publicClient - Viem PublicClient (from wagmi usePublicClient)
  * @param params.tokenAddress - Token contract address to withdraw
- * @param params.network - Network (default: "sepolia")
+ * @param params.network - Network: "sepolia" | "arbitrum" (default: "sepolia")
  * @returns Transaction hash
  *
  * @example
@@ -930,26 +1100,9 @@ declare function withdrawAllAvailableEpochs(params: {
     walletClient: WalletClient;
     publicClient: PublicClient;
     tokenAddress: Address;
-    network?: 'sepolia';
+    network?: SupportedNetwork;
 }): Promise<Hash>;
 
-/**
- * Core type definitions shared across the package
- */
-/**
- * Supported blockchain networks (where IATP contracts are deployed)
- */
-type SupportedNetwork = 'sepolia';
-/**
- * EIP-712 domain for signature verification
- */
-interface EIP712Domain {
-    name: string;
-    version: string;
-    chainId: number;
-    verifyingContract: `0x${string}`;
-}
-
 /**
  * Contract configuration and utilities.
  *
@@ -970,8 +1123,7 @@ declare enum ContractName {
  * Get contract address for a given network.
  *
  * @param contractName - Name of the contract (use ContractName enum)
- * @param network - Network name (default: "sepolia")
- * @param useProxy - Use proxy address if true, implementation if false (default: true)
+ * @param network - Network: "sepolia" | "arbitrum" (default: "sepolia")
  * @returns Contract address as hex string, or null if not found
  *
  * @example
@@ -980,12 +1132,12 @@ declare enum ContractName {
  * console.log(factoryAddr) // "0x15D83638E339a0f29283f6B93dC1bb90b8339078"
  * ```
  */
-declare function getContractAddress(contractName: string | ContractName, network?: SupportedNetwork, useProxy?: boolean): string | null;
+declare function getContractAddress(contractName: string | ContractName, network?: SupportedNetwork): string | null;
 /**
  * Get contract ABI for a given network.
  *
  * @param contractName - Name of the contract (use ContractName enum)
- * @param network - Network name (default: "sepolia")
+ * @param network - Network: "sepolia" | "arbitrum" (default: "sepolia")
  * @returns Contract ABI as array of objects, or null if not found
  *
  * @example
@@ -999,7 +1151,7 @@ declare function getContractAbi(contractName: string | ContractName, network?: S
  * Get contract configuration (address and ABI) for a network.
  *
  * @param contractName - Name of the contract
- * @param network - Network name (default: "sepolia")
+ * @param network - Network: "sepolia" | "arbitrum" (default: "sepolia")
  * @returns Object with address and abi, or null if not found
  *
  * @example
@@ -1020,6 +1172,19 @@ declare function getContractConfig(contractName: string | ContractName, network?
  * Utility functions for D402 payment processing
  */
 
+/**
+ * Get viem Chain object for a supported network
+ *
+ * @param network - Network name
+ * @returns viem Chain object
+ *
+ * @example
+ * ```ts
+ * const chain = getChain('arbitrum')
+ * console.log(chain.id) // 42161
+ * ```
+ */
+declare function getChain(network: SupportedNetwork): Chain;
 /**
  * Parse a money string or number into atomic units (wei)
  *
@@ -1071,7 +1236,6 @@ declare function getUsdcAddress(network: SupportedNetwork): `0x${string}`;
  * ```ts
  * getChainId('sepolia')    // Returns 11155111
  * getChainId('11155111')   // Returns 11155111 (passthrough)
- * getChainId('base')       // Returns 8453 (for parsing 402 responses)
  * ```
  */
 declare function getChainId(network: string): number;
@@ -1172,4 +1336,4 @@ declare class UnsupportedNetworkError extends PaymentError {
     constructor(network: string);
 }
 
-export { ContractName, D402Client, type D402ClientConfig, type D402Response, type EIP712Domain, Invalid402ResponseError, MissingRequestConfigError, PaymentAlreadyAttemptedError, PaymentAmountExceededError, type PaymentAuthorization, PaymentError, type PaymentRequirement, type PaymentSelector, type PaymentSelectorOptions, PaymentVerificationError, type SignedPayment, type SupportedNetwork, UnsupportedNetworkError, UnsupportedSchemeError, type WalletCreationResult, type WithdrawalRequest, createIATPWallet, createPaymentSelector, decodePayment, decodePaymentResponse, encodePayment, executeWithdrawal, findMatchingPaymentRequirement, formatMoney, generateNonce, getAvailableBalance, getChainId, getContractAbi, getContractAddress, getContractConfig, getCurrentTimestamp, getLockedBalanceForProvider, getUnlockedBalanceForProvider, getUsdcAddress, getWalletsByOwner, getWithdrawalRequest, isValidAddress, normalizeAddress, parseAllPaymentRequirements, parseMoney, parsePaymentRequirement, requestWithdrawal, selectPaymentRequirement, signD402Payment, sortPaymentRequirements, usdToUsdc, withdrawAllAvailableEpochs };
+export { ContractName, D402Client, type D402ClientConfig, type D402Response, type EIP712Domain, Invalid402ResponseError, type JsonRpcPayload, type McpToolResult, MissingRequestConfigError, type ParsedMcpResponse, PaymentAlreadyAttemptedError, PaymentAmountExceededError, type PaymentAuthorization, PaymentError, type PaymentRequirement, type PaymentSelector, type PaymentSelectorOptions, PaymentVerificationError, type SignedPayment, type SupportedNetwork, UnsupportedNetworkError, UnsupportedSchemeError, type WalletCreationResult, type WithdrawalRequest, buildMcpHeaders, buildToolCallPayload, createIATPWallet, createPaymentSelector, decodePayment, decodePaymentResponse, encodePayment, executeWithdrawal, extractToolResult, findMatchingPaymentRequirement, formatMoney, generateNonce, getAvailableBalance, getChain, getChainId, getContractAbi, getContractAddress, getContractConfig, getCurrentTimestamp, getLockedBalanceForProvider, getUnlockedBalanceForProvider, getUsdcAddress, getWalletsByOwner, getWithdrawalRequest, initMcpSession, isValidAddress, normalizeAddress, parseAllPaymentRequirements, parseMcpResponse, parseMoney, parsePaymentRequirement, requestWithdrawal, selectPaymentRequirement, signD402Payment, sortPaymentRequirements, usdToUsdc, withdrawAllAvailableEpochs };