@dcentralab/d402-client 0.3.4 → 0.3.7

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { Account } from 'viem/accounts';
-import { PublicClient, WalletClient, Hash, Address } from 'viem';
+import { WalletClient, PublicClient, Hash, Address } from 'viem';
 
 /**
  * Type definitions for D402 payment protocol
@@ -198,6 +198,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 +272,7 @@ interface D402ClientConfig {
  */
 declare class D402Client {
     private readonly operatorAccount;
+    private readonly walletClient?;
     private readonly iatpWalletAddress;
     private readonly maxValue?;
     private readonly paymentRequirementsSelector;
@@ -383,6 +389,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 +444,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 +458,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,8 +469,9 @@ declare class D402Client {
  */
 declare function signD402Payment(params: {
     operatorAccount: Account;
+    walletClient?: WalletClient;
     paymentRequirement: PaymentRequirement;
-    iatpWalletAddress?: `0x${string}`;
+    iatpWalletAddress: `0x${string}`;
     requestPath?: string;
     d402Version?: number;
 }): Promise<SignedPayment>;
@@ -613,6 +661,7 @@ interface WithdrawalRequest {
  */
 declare function createIATPWallet(params: {
     ownerAccount: Account;
+    walletClient?: WalletClient;
     network?: 'sepolia';
     rpcUrl?: string;
 }): Promise<WalletCreationResult>;
@@ -821,6 +870,109 @@ declare function executeWithdrawal(params: {
     network?: 'sepolia';
 }): 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
  */
@@ -1172,4 +1324,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, getChainId, getContractAbi, getContractAddress, getContractConfig, getCurrentTimestamp, getLockedBalanceForProvider, getUnlockedBalanceForProvider, getUsdcAddress, getWalletsByOwner, getWithdrawalRequest, initMcpSession, isValidAddress, normalizeAddress, parseAllPaymentRequirements, parseMcpResponse, parseMoney, parsePaymentRequirement, requestWithdrawal, selectPaymentRequirement, signD402Payment, sortPaymentRequirements, usdToUsdc, withdrawAllAvailableEpochs };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { Account } from 'viem/accounts';
-import { PublicClient, WalletClient, Hash, Address } from 'viem';
+import { WalletClient, PublicClient, Hash, Address } from 'viem';
 
 /**
  * Type definitions for D402 payment protocol
@@ -198,6 +198,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 +272,7 @@ interface D402ClientConfig {
  */
 declare class D402Client {
     private readonly operatorAccount;
+    private readonly walletClient?;
     private readonly iatpWalletAddress;
     private readonly maxValue?;
     private readonly paymentRequirementsSelector;
@@ -383,6 +389,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 +444,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 +458,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,8 +469,9 @@ declare class D402Client {
  */
 declare function signD402Payment(params: {
     operatorAccount: Account;
+    walletClient?: WalletClient;
     paymentRequirement: PaymentRequirement;
-    iatpWalletAddress?: `0x${string}`;
+    iatpWalletAddress: `0x${string}`;
     requestPath?: string;
     d402Version?: number;
 }): Promise<SignedPayment>;
@@ -613,6 +661,7 @@ interface WithdrawalRequest {
  */
 declare function createIATPWallet(params: {
     ownerAccount: Account;
+    walletClient?: WalletClient;
     network?: 'sepolia';
     rpcUrl?: string;
 }): Promise<WalletCreationResult>;
@@ -821,6 +870,109 @@ declare function executeWithdrawal(params: {
     network?: 'sepolia';
 }): 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
  */
@@ -1172,4 +1324,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, getChainId, getContractAbi, getContractAddress, getContractConfig, getCurrentTimestamp, getLockedBalanceForProvider, getUnlockedBalanceForProvider, getUsdcAddress, getWalletsByOwner, getWithdrawalRequest, initMcpSession, isValidAddress, normalizeAddress, parseAllPaymentRequirements, parseMcpResponse, parseMoney, parsePaymentRequirement, requestWithdrawal, selectPaymentRequirement, signD402Payment, sortPaymentRequirements, usdToUsdc, withdrawAllAvailableEpochs };