@mixrpay/agent-sdk 0.3.2 → 0.3.4

package/dist/index.cjs

@@ -1467,6 +1467,540 @@ var AgentWallet = class {
       createdAt: new Date(data.createdAt || data.created_at)
     };
   }
+  // ===========================================================================
+  // MCP (Model Context Protocol) Methods
+  // ===========================================================================
+  /**
+   * 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,
+   *   }),
+   * });
+   * ```
+   */
+  async getMCPAuthHeaders() {
+    const timestamp = Date.now().toString();
+    const message = `MixrPay MCP Auth
+Wallet: ${this.walletAddress}
+Timestamp: ${timestamp}`;
+    const signature = await this.sessionKey.signMessage(message);
+    return {
+      "X-Mixr-Wallet": this.walletAddress,
+      "X-Mixr-Signature": signature,
+      "X-Mixr-Timestamp": timestamp
+    };
+  }
+  /**
+   * 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}`);
+   * }
+   * ```
+   */
+  async listMCPTools() {
+    this.logger.debug("listMCPTools");
+    const response = await fetch(`${this.baseUrl}/api/mcp`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        method: "tools/list",
+        id: Date.now()
+      })
+    });
+    if (!response.ok) {
+      throw new MixrPayError(`Failed to list MCP tools: ${response.status}`);
+    }
+    const result = await response.json();
+    if (result.error) {
+      throw new MixrPayError(result.error.message || "Failed to list MCP tools");
+    }
+    return (result.result?.tools || []).map((tool) => ({
+      name: tool.name,
+      description: tool.description,
+      inputSchema: tool.inputSchema,
+      priceUsd: tool["x-mixrpay"]?.priceUsd || 0,
+      merchantName: tool["x-mixrpay"]?.merchantName,
+      merchantSlug: tool["x-mixrpay"]?.merchantSlug,
+      verified: tool["x-mixrpay"]?.verified || false
+    }));
+  }
+  /**
+   * 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}`);
+   * ```
+   */
+  async callMCPTool(toolName, args = {}) {
+    this.logger.debug("callMCPTool", { toolName, args });
+    const authHeaders = await this.getMCPAuthHeaders();
+    const response = await fetch(`${this.baseUrl}/api/mcp`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        ...authHeaders
+      },
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        method: "tools/call",
+        params: { name: toolName, arguments: args },
+        id: Date.now()
+      })
+    });
+    const result = await response.json();
+    if (result.error) {
+      throw new MixrPayError(result.error.message || "MCP tool call failed");
+    }
+    const content = result.result?.content?.[0];
+    const data = content?.text ? JSON.parse(content.text) : null;
+    const mixrpay = result.result?._mixrpay || {};
+    if (mixrpay.chargedUsd) {
+      const payment = {
+        amountUsd: mixrpay.chargedUsd,
+        recipient: toolName.split("/")[0] || toolName,
+        txHash: mixrpay.txHash,
+        timestamp: /* @__PURE__ */ new Date(),
+        description: `MCP: ${toolName}`,
+        url: `${this.baseUrl}/api/mcp`
+      };
+      this.payments.push(payment);
+      this.totalSpentUsd += mixrpay.chargedUsd;
+      this.logger.payment(mixrpay.chargedUsd, toolName, "MCP call");
+      if (this.onPayment) {
+        this.onPayment(payment);
+      }
+    }
+    return {
+      data,
+      chargedUsd: mixrpay.chargedUsd || 0,
+      txHash: mixrpay.txHash,
+      latencyMs: mixrpay.latencyMs
+    };
+  }
+  // ===========================================================================
+  // Agent Runtime API
+  // ===========================================================================
+  /**
+   * 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}`);
+   *     }
+   *   },
+   * });
+   * ```
+   */
+  async runAgent(options) {
+    const {
+      sessionId,
+      messages,
+      config = {},
+      stream = false,
+      idempotencyKey,
+      onEvent
+    } = options;
+    this.logger.debug("runAgent", { sessionId, messageCount: messages.length, config, stream });
+    const body = {
+      session_id: sessionId,
+      messages: messages.map((m) => ({ role: m.role, content: m.content })),
+      config: {
+        model: config.model,
+        max_iterations: config.maxIterations,
+        tools: config.tools,
+        system_prompt: config.systemPrompt
+      },
+      stream,
+      idempotency_key: idempotencyKey
+    };
+    const AGENT_RUN_TIMEOUT = 18e4;
+    if (!stream) {
+      const response = await fetch(`${this.baseUrl}/api/v2/agent/run`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "X-Mixr-Session": sessionId
+        },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(AGENT_RUN_TIMEOUT)
+      });
+      if (!response.ok) {
+        const error = await response.json().catch(() => ({}));
+        throw new MixrPayError(error.error || `Agent run failed: ${response.status}`);
+      }
+      const data = await response.json();
+      if (data.cost?.total_usd > 0) {
+        const payment = {
+          amountUsd: data.cost.total_usd,
+          recipient: "mixrpay-agent-run",
+          txHash: data.tx_hash,
+          timestamp: /* @__PURE__ */ new Date(),
+          description: `Agent run: ${data.run_id}`,
+          url: `${this.baseUrl}/api/v2/agent/run`
+        };
+        this.payments.push(payment);
+        this.totalSpentUsd += data.cost.total_usd;
+        this.logger.payment(data.cost.total_usd, "agent-run", data.run_id);
+        if (this.onPayment) {
+          this.onPayment(payment);
+        }
+      }
+      return {
+        runId: data.run_id,
+        status: data.status,
+        response: data.response,
+        iterations: data.iterations,
+        toolsUsed: data.tools_used,
+        cost: {
+          llmUsd: data.cost.llm_usd,
+          toolsUsd: data.cost.tools_usd,
+          totalUsd: data.cost.total_usd
+        },
+        tokens: data.tokens,
+        sessionRemainingUsd: data.session_remaining_usd,
+        txHash: data.tx_hash
+      };
+    }
+    return this.runAgentStreaming(sessionId, body, onEvent);
+  }
+  /**
+   * Internal: Handle streaming agent run via SSE
+   */
+  async runAgentStreaming(sessionId, body, onEvent) {
+    const STREAMING_TIMEOUT = 3e5;
+    const response = await fetch(`${this.baseUrl}/api/v2/agent/run`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Mixr-Session": sessionId
+      },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(STREAMING_TIMEOUT)
+    });
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      throw new MixrPayError(error.error || `Agent run failed: ${response.status}`);
+    }
+    const reader = response.body?.getReader();
+    if (!reader) {
+      throw new MixrPayError("No response body for streaming");
+    }
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let result = null;
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split("\n");
+      buffer = lines.pop() || "";
+      let currentEvent = "";
+      for (const line of lines) {
+        if (line.startsWith("event: ")) {
+          currentEvent = line.slice(7).trim();
+        } else if (line.startsWith("data: ") && currentEvent) {
+          try {
+            const data = JSON.parse(line.slice(6));
+            const event = this.parseSSEEvent(currentEvent, data);
+            if (event) {
+              onEvent?.(event);
+              if (currentEvent === "complete") {
+                result = {
+                  runId: data.run_id,
+                  status: "completed",
+                  response: data.response,
+                  iterations: data.iterations,
+                  toolsUsed: data.tools_used,
+                  cost: {
+                    llmUsd: 0,
+                    // Not provided in streaming complete
+                    toolsUsd: 0,
+                    totalUsd: data.total_cost_usd
+                  },
+                  tokens: { prompt: 0, completion: 0 },
+                  sessionRemainingUsd: 0,
+                  txHash: data.tx_hash
+                };
+                if (data.total_cost_usd > 0) {
+                  const payment = {
+                    amountUsd: data.total_cost_usd,
+                    recipient: "mixrpay-agent-run",
+                    txHash: data.tx_hash,
+                    timestamp: /* @__PURE__ */ new Date(),
+                    description: `Agent run: ${data.run_id}`,
+                    url: `${this.baseUrl}/api/v2/agent/run`
+                  };
+                  this.payments.push(payment);
+                  this.totalSpentUsd += data.total_cost_usd;
+                  if (this.onPayment) {
+                    this.onPayment(payment);
+                  }
+                }
+              }
+              if (currentEvent === "error") {
+                throw new MixrPayError(data.error || "Agent run failed");
+              }
+            }
+          } catch (e) {
+            if (e instanceof MixrPayError) throw e;
+            this.logger.warn("Failed to parse SSE event:", e);
+          }
+          currentEvent = "";
+        }
+      }
+    }
+    if (!result) {
+      throw new MixrPayError("Agent run completed without final result");
+    }
+    return result;
+  }
+  /**
+   * Internal: Parse SSE event into typed event object
+   */
+  parseSSEEvent(eventType, data) {
+    switch (eventType) {
+      case "run_start":
+        return { type: "run_start", runId: data.run_id };
+      case "iteration_start":
+        return { type: "iteration_start", iteration: data.iteration };
+      case "llm_chunk":
+        return { type: "llm_chunk", delta: data.delta };
+      case "tool_call":
+        return { type: "tool_call", tool: data.tool, arguments: data.arguments };
+      case "tool_result":
+        return {
+          type: "tool_result",
+          tool: data.tool,
+          success: data.success,
+          costUsd: data.cost_usd,
+          error: data.error
+        };
+      case "iteration_complete":
+        return {
+          type: "iteration_complete",
+          iteration: data.iteration,
+          tokens: data.tokens,
+          costUsd: data.cost_usd
+        };
+      case "complete":
+        return {
+          type: "complete",
+          runId: data.run_id,
+          response: data.response,
+          totalCostUsd: data.total_cost_usd,
+          txHash: data.tx_hash,
+          iterations: data.iterations,
+          toolsUsed: data.tools_used
+        };
+      case "error":
+        return {
+          type: "error",
+          error: data.error,
+          partialCostUsd: data.partial_cost_usd
+        };
+      default:
+        return null;
+    }
+  }
+  /**
+   * 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);
+   * }
+   * ```
+   */
+  async getAgentRunStatus(runId, sessionId) {
+    this.logger.debug("getAgentRunStatus", { runId, sessionId });
+    const response = await fetch(`${this.baseUrl}/api/v2/agent/run/${runId}`, {
+      headers: {
+        "X-Mixr-Session": sessionId
+      }
+    });
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      throw new MixrPayError(error.error || `Failed to get run status: ${response.status}`);
+    }
+    const data = await response.json();
+    return {
+      runId: data.run_id,
+      status: data.status,
+      response: data.response,
+      iterations: data.iterations,
+      toolsUsed: data.tools_used,
+      cost: {
+        llmUsd: data.cost.llm_usd,
+        toolsUsd: data.cost.tools_usd,
+        totalUsd: data.cost.total_usd
+      },
+      tokens: data.tokens,
+      txHash: data.tx_hash,
+      error: data.error,
+      startedAt: new Date(data.started_at),
+      completedAt: data.completed_at ? new Date(data.completed_at) : void 0
+    };
+  }
+  /**
+   * 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' }
+   * );
+   * ```
+   */
+  async callMCPToolWithSession(sessionId, toolName, args = {}) {
+    this.logger.debug("callMCPToolWithSession", { sessionId, toolName, args });
+    const response = await fetch(`${this.baseUrl}/api/mcp`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Mixr-Session": sessionId
+      },
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        method: "tools/call",
+        params: { name: toolName, arguments: args },
+        id: Date.now()
+      })
+    });
+    const result = await response.json();
+    if (result.error) {
+      throw new MixrPayError(result.error.message || "MCP tool call failed");
+    }
+    const content = result.result?.content?.[0];
+    const data = content?.text ? JSON.parse(content.text) : null;
+    const mixrpay = result.result?._mixrpay || {};
+    if (mixrpay.chargedUsd) {
+      const payment = {
+        amountUsd: mixrpay.chargedUsd,
+        recipient: toolName.split("/")[0] || toolName,
+        txHash: mixrpay.txHash,
+        timestamp: /* @__PURE__ */ new Date(),
+        description: `MCP: ${toolName}`,
+        url: `${this.baseUrl}/api/mcp`
+      };
+      this.payments.push(payment);
+      this.totalSpentUsd += mixrpay.chargedUsd;
+      this.logger.payment(mixrpay.chargedUsd, toolName, "MCP call (session)");
+      if (this.onPayment) {
+        this.onPayment(payment);
+      }
+    }
+    return {
+      data,
+      chargedUsd: mixrpay.chargedUsd || 0,
+      txHash: mixrpay.txHash,
+      latencyMs: mixrpay.latencyMs
+    };
+  }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {