@mixrpay/agent-sdk 0.3.2 → 0.3.4

package/dist/index.d.ts

@@ -745,6 +745,359 @@ declare class AgentWallet {
      * Parse session response data into SessionAuthorization object.
      */
     private parseSessionResponse;
+    /**
+     * Get authentication headers for MCP wallet-based authentication.
+     *
+     * These headers prove wallet ownership without transmitting the private key.
+     * Use for direct pay-per-call mode (no session needed).
+     *
+     * @returns Headers object with X-Mixr-Wallet, X-Mixr-Signature, X-Mixr-Timestamp
+     *
+     * @example
+     * ```typescript
+     * const headers = await wallet.getMCPAuthHeaders();
+     * const response = await fetch('https://mixrpay.com/api/mcp', {
+     *   method: 'POST',
+     *   headers: {
+     *     'Content-Type': 'application/json',
+     *     ...headers,
+     *   },
+     *   body: JSON.stringify({
+     *     jsonrpc: '2.0',
+     *     method: 'tools/list',
+     *     id: 1,
+     *   }),
+     * });
+     * ```
+     */
+    getMCPAuthHeaders(): Promise<Record<string, string>>;
+    /**
+     * List available MCP tools from the MixrPay gateway.
+     *
+     * Returns all tools exposed by MCP providers on the MixrPay marketplace.
+     * Each tool includes pricing information.
+     *
+     * @returns Array of MCP tools with pricing and metadata
+     *
+     * @example
+     * ```typescript
+     * const tools = await wallet.listMCPTools();
+     * for (const tool of tools) {
+     *   console.log(`${tool.name}: $${tool.priceUsd} - ${tool.description}`);
+     * }
+     * ```
+     */
+    listMCPTools(): Promise<MCPTool[]>;
+    /**
+     * Call an MCP tool with wallet authentication (direct pay per call).
+     *
+     * This method signs a fresh auth message for each call, charging
+     * directly from your wallet balance without needing a session.
+     *
+     * @param toolName - The tool name in format "merchant/tool"
+     * @param args - Arguments to pass to the tool
+     * @returns Tool execution result
+     *
+     * @example
+     * ```typescript
+     * const result = await wallet.callMCPTool('firecrawl/scrape', {
+     *   url: 'https://example.com',
+     * });
+     * console.log(result.data);
+     * console.log(`Charged: $${result.chargedUsd}`);
+     * ```
+     */
+    callMCPTool(toolName: string, args?: Record<string, unknown>): Promise<MCPToolResult>;
+    /**
+     * Run an AI agent with LLM and tool execution.
+     *
+     * This method orchestrates a full agentic loop:
+     * - Multi-turn reasoning with LLM
+     * - Automatic tool execution
+     * - Bundled billing (single charge at end)
+     * - Optional streaming via SSE
+     *
+     * @param options - Agent run options
+     * @returns Agent run result with response and cost breakdown
+     *
+     * @example Basic usage
+     * ```typescript
+     * const result = await wallet.runAgent({
+     *   sessionId: 'sess_abc123',
+     *   messages: [{ role: 'user', content: 'Find AI startups in SF' }],
+     * });
+     *
+     * console.log(result.response);
+     * console.log(`Cost: $${result.cost.totalUsd.toFixed(4)}`);
+     * ```
+     *
+     * @example With custom config
+     * ```typescript
+     * const result = await wallet.runAgent({
+     *   sessionId: 'sess_abc123',
+     *   messages: [{ role: 'user', content: 'Research quantum computing' }],
+     *   config: {
+     *     model: 'gpt-4o',
+     *     maxIterations: 15,
+     *     tools: ['platform/exa-search', 'platform/firecrawl-scrape'],
+     *     systemPrompt: 'You are a research assistant.',
+     *   },
+     * });
+     * ```
+     *
+     * @example With streaming
+     * ```typescript
+     * await wallet.runAgent({
+     *   sessionId: 'sess_abc123',
+     *   messages: [{ role: 'user', content: 'Analyze this company' }],
+     *   stream: true,
+     *   onEvent: (event) => {
+     *     if (event.type === 'llm_chunk') {
+     *       process.stdout.write(event.delta);
+     *     } else if (event.type === 'tool_call') {
+     *       console.log(`Calling tool: ${event.tool}`);
+     *     }
+     *   },
+     * });
+     * ```
+     */
+    runAgent(options: AgentRunOptions): Promise<AgentRunResult>;
+    /**
+     * Internal: Handle streaming agent run via SSE
+     */
+    private runAgentStreaming;
+    /**
+     * Internal: Parse SSE event into typed event object
+     */
+    private parseSSEEvent;
+    /**
+     * Get the status of an agent run by ID.
+     *
+     * @param runId - The agent run ID
+     * @param sessionId - The session ID (for authentication)
+     * @returns Agent run status and results
+     *
+     * @example
+     * ```typescript
+     * const status = await wallet.getAgentRunStatus('run_abc123', 'sess_xyz789');
+     * console.log(`Status: ${status.status}`);
+     * if (status.status === 'completed') {
+     *   console.log(status.response);
+     * }
+     * ```
+     */
+    getAgentRunStatus(runId: string, sessionId: string): Promise<AgentRunStatusResult>;
+    /**
+     * Call an MCP tool using session authorization (pre-authorized spending limit).
+     *
+     * Use this when you've already created a session with the tool provider
+     * and want to use that spending limit instead of direct wallet charges.
+     *
+     * @param sessionId - The session ID for the tool provider
+     * @param toolName - The tool name in format "merchant/tool"
+     * @param args - Arguments to pass to the tool
+     * @returns Tool execution result
+     *
+     * @example
+     * ```typescript
+     * // Create session with provider first
+     * const session = await wallet.getOrCreateSession({
+     *   merchantPublicKey: 'pk_live_firecrawl_...',
+     *   spendingLimitUsd: 50,
+     * });
+     *
+     * // Use session for multiple calls
+     * const result = await wallet.callMCPToolWithSession(
+     *   session.id,
+     *   'firecrawl/scrape',
+     *   { url: 'https://example.com' }
+     * );
+     * ```
+     */
+    callMCPToolWithSession(sessionId: string, toolName: string, args?: Record<string, unknown>): Promise<MCPToolResult>;
+}
+/**
+ * MCP Tool definition returned by listMCPTools()
+ */
+interface MCPTool {
+    /** Tool name in format "merchant/tool" */
+    name: string;
+    /** Human-readable description with price */
+    description: string;
+    /** JSON Schema for tool input parameters */
+    inputSchema: Record<string, unknown>;
+    /** Price per call in USD */
+    priceUsd: number;
+    /** Merchant/provider name */
+    merchantName: string;
+    /** Merchant slug for session creation */
+    merchantSlug: string;
+    /** Whether the provider is domain-verified */
+    verified: boolean;
+}
+/**
+ * Result from calling an MCP tool
+ */
+interface MCPToolResult {
+    /** The tool's response data */
+    data: unknown;
+    /** Amount charged in USD */
+    chargedUsd: number;
+    /** On-chain transaction hash (if available) */
+    txHash?: string;
+    /** Execution latency in milliseconds */
+    latencyMs?: number;
+}
+/**
+ * Message in an agent conversation
+ */
+interface AgentMessage {
+    /** Message role */
+    role: 'user' | 'assistant' | 'system' | 'tool';
+    /** Message content */
+    content: string;
+}
+/**
+ * Configuration for an agent run
+ */
+interface AgentRunConfig {
+    /** LLM model to use (default: gpt-4o-mini) */
+    model?: string;
+    /** Maximum iterations before stopping (default: 10, max: 25) */
+    maxIterations?: number;
+    /** Specific tools to enable (e.g., ['platform/exa-search', 'platform/firecrawl-scrape']) */
+    tools?: string[];
+    /** Custom system prompt for the agent */
+    systemPrompt?: string;
+}
+/**
+ * Options for running an agent
+ */
+interface AgentRunOptions {
+    /** Session ID for authentication and billing */
+    sessionId: string;
+    /** Conversation messages */
+    messages: AgentMessage[];
+    /** Agent configuration */
+    config?: AgentRunConfig;
+    /** Enable SSE streaming (default: false) */
+    stream?: boolean;
+    /** Unique key for idempotency */
+    idempotencyKey?: string;
+    /** Callback for streaming events */
+    onEvent?: (event: AgentRunEvent) => void;
+}
+/**
+ * Result from an agent run
+ */
+interface AgentRunResult {
+    /** Unique run ID */
+    runId: string;
+    /** Run status */
+    status: 'completed' | 'failed';
+    /** Final response from the agent */
+    response: string;
+    /** Number of iterations performed */
+    iterations: number;
+    /** Tools used during the run */
+    toolsUsed: string[];
+    /** Cost breakdown */
+    cost: {
+        /** LLM cost in USD */
+        llmUsd: number;
+        /** Tool execution cost in USD */
+        toolsUsd: number;
+        /** Total cost in USD */
+        totalUsd: number;
+    };
+    /** Token usage */
+    tokens: {
+        /** Prompt tokens used */
+        prompt: number;
+        /** Completion tokens used */
+        completion: number;
+    };
+    /** Remaining session balance in USD */
+    sessionRemainingUsd: number;
+    /** On-chain transaction hash for payment */
+    txHash?: string;
+}
+/**
+ * Streaming events from an agent run
+ */
+type AgentRunEvent = {
+    type: 'run_start';
+    runId: string;
+} | {
+    type: 'iteration_start';
+    iteration: number;
+} | {
+    type: 'llm_chunk';
+    delta: string;
+} | {
+    type: 'tool_call';
+    tool: string;
+    arguments: unknown;
+} | {
+    type: 'tool_result';
+    tool: string;
+    success: boolean;
+    costUsd: number;
+    error?: string;
+} | {
+    type: 'iteration_complete';
+    iteration: number;
+    tokens?: {
+        prompt?: number;
+        completion?: number;
+    };
+    costUsd?: number;
+} | {
+    type: 'complete';
+    runId: string;
+    response: string;
+    totalCostUsd: number;
+    txHash?: string;
+    iterations: number;
+    toolsUsed: string[];
+} | {
+    type: 'error';
+    error: string;
+    partialCostUsd?: number;
+};
+/**
+ * Result from getting agent run status
+ */
+interface AgentRunStatusResult {
+    /** Unique run ID */
+    runId: string;
+    /** Run status */
+    status: 'running' | 'completed' | 'failed' | 'interrupted';
+    /** Final response (if completed) */
+    response?: string;
+    /** Number of iterations performed */
+    iterations: number;
+    /** Tools used during the run */
+    toolsUsed: string[];
+    /** Cost breakdown */
+    cost: {
+        llmUsd: number;
+        toolsUsd: number;
+        totalUsd: number;
+    };
+    /** Token usage */
+    tokens: {
+        prompt: number;
+        completion: number;
+    };
+    /** On-chain transaction hash */
+    txHash?: string;
+    /** Error message (if failed) */
+    error?: string;
+    /** When the run started */
+    startedAt: Date;
+    /** When the run completed */
+    completedAt?: Date;
 }
 
 /**
@@ -1075,4 +1428,4 @@ declare class SessionRevokedError extends MixrPayError {
  */
 declare function isMixrPayError(error: unknown): error is MixrPayError;
 
-export { AgentWallet, type AgentWalletConfig, type CallMerchantApiOptions, type ChargeResult, InsufficientBalanceError, InvalidSessionKeyError, MixrPayError, type PaymentEvent, PaymentFailedError, SDK_VERSION, type SessionAuthorization, SessionExpiredError, SessionKeyExpiredError, SessionLimitExceededError, SessionNotFoundError, SessionRevokedError, type SessionStats, SpendingLimitExceededError, type SpendingStats, isMixrPayError };
+export { type AgentMessage, type AgentRunConfig, type AgentRunEvent, type AgentRunOptions, type AgentRunResult, type AgentRunStatusResult, AgentWallet, type AgentWalletConfig, type CallMerchantApiOptions, type ChargeResult, InsufficientBalanceError, InvalidSessionKeyError, MixrPayError, type PaymentEvent, PaymentFailedError, SDK_VERSION, type SessionAuthorization, SessionExpiredError, SessionKeyExpiredError, SessionLimitExceededError, SessionNotFoundError, SessionRevokedError, type SessionStats, SpendingLimitExceededError, type SpendingStats, isMixrPayError };