@mixrpay/agent-sdk 0.3.3 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # @mixrpay/agent-sdk
 
-Enable AI agents to make payments.
+Enable AI agents to make payments to MixrPay-powered APIs. Session-based authentication with spending limits, automatic payment handling, and Agent Runtime for agentic workflows.
 
 ## Installation
 
@@ -8,16 +8,7 @@ Enable AI agents to make payments.
 npm install @mixrpay/agent-sdk
 ```
 
-## Setup
-
-```bash
-# .env
-MIXRPAY_SESSION_KEY=sk_live_...
-```
-
-Get session keys from [mixrpay.com/wallet/sessions](https://www.mixrpay.com/wallet/sessions).
-
-## Usage
+## Quick Start
 
 ```typescript
 import { AgentWallet } from '@mixrpay/agent-sdk';
@@ -26,6 +17,7 @@ const wallet = new AgentWallet({
   sessionKey: process.env.MIXRPAY_SESSION_KEY!
 });
 
+// Call any MixrPay merchant API - payments handled automatically
 const response = await wallet.callMerchantApi({
   url: 'https://api.merchant.com/generate',
   merchantPublicKey: 'pk_live_...',
@@ -36,35 +28,380 @@ const response = await wallet.callMerchantApi({
 const data = await response.json();
 ```
 
+Get session keys from [mixrpay.com/wallet/sessions](https://www.mixrpay.com/wallet/sessions).
+
+---
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| **Auto-Pay Fetch** | Drop-in `fetch()` replacement that handles 402 payments |
+| **Session Management** | Create, list, and revoke spending sessions with merchants |
+| **Agent Runtime** | Full agentic loop with LLM + tools + bundled billing |
+| **MCP Tools** | Access web scraping, search, and other tools |
+| **Spending Controls** | Client-side limits and payment tracking |
+
+---
+
+## Core Methods
+
+### Auto-Pay Fetch
+
+Use `fetch()` as a drop-in replacement - payments are handled automatically when servers return 402:
+
+```typescript
+// Just like native fetch, but handles 402 payments automatically
+const response = await wallet.fetch('https://api.example.com/ai/endpoint', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ prompt: 'Hello world' })
+});
+
+const data = await response.json();
+```
+
+### Call Merchant APIs
+
+For MixrPay-integrated merchants, use the session-based approach:
+
+```typescript
+const response = await wallet.callMerchantApi({
+  url: 'https://api.merchant.com/generate',
+  merchantPublicKey: 'pk_live_abc123...',
+  method: 'POST',
+  body: { prompt: 'Analyze this data' },
+  priceUsd: 0.05,
+  feature: 'ai-analysis', // Optional: for tracking
+});
+```
+
+---
+
+## Session Management
+
+Sessions allow spending limits with specific merchants.
+
+### Create or Get Session
+
+```typescript
+const session = await wallet.getOrCreateSession({
+  merchantPublicKey: 'pk_live_abc123...',
+  spendingLimitUsd: 25.00,
+  durationDays: 7,
+});
+
+console.log(`Session: ${session.id}`);
+console.log(`Remaining: $${session.remainingLimitUsd}`);
+```
+
+### List All Sessions
+
+```typescript
+const sessions = await wallet.listSessions();
+
+for (const session of sessions) {
+  console.log(`${session.merchantName}: $${session.remainingLimitUsd} remaining`);
+}
+```
+
+### Session Statistics
+
+```typescript
+const stats = await wallet.getSessionStats();
+
+console.log(`Active sessions: ${stats.activeCount}`);
+console.log(`Total authorized: $${stats.totalAuthorizedUsd}`);
+console.log(`Total remaining: $${stats.totalRemainingUsd}`);
+```
+
+### Revoke Session
+
+```typescript
+await wallet.revokeSession('sess_abc123');
+```
+
+### Charge Session Directly
+
+```typescript
+const result = await wallet.chargeSession('sess_abc123', 0.05, {
+  feature: 'image-generation',
+  idempotencyKey: 'unique-request-id',
+});
+
+console.log(`Charged: $${result.amountUsd}`);
+console.log(`Remaining: $${result.remainingSessionBalanceUsd}`);
+```
+
+---
+
+## Agent Runtime
+
+Run full agentic workflows with LLM reasoning and tool execution. Costs are bundled into a single charge.
+
+### Basic Agent Run
+
+```typescript
+const result = await wallet.runAgent({
+  sessionId: 'sess_abc123',
+  messages: [
+    { role: 'user', content: 'Find AI startups in San Francisco and summarize their products' }
+  ],
+});
+
+console.log(result.response);
+console.log(`Cost: $${result.cost.totalUsd.toFixed(4)}`);
+console.log(`Tools used: ${result.toolsUsed.join(', ')}`);
+```
+
+### With Custom Configuration
+
+```typescript
+const result = await wallet.runAgent({
+  sessionId: 'sess_abc123',
+  messages: [
+    { role: 'user', content: 'Research quantum computing breakthroughs in 2024' }
+  ],
+  config: {
+    model: 'gpt-4o',                    // LLM model
+    maxIterations: 15,                   // Max reasoning loops
+    tools: ['platform/exa-search', 'platform/firecrawl-scrape'],
+    systemPrompt: 'You are a research analyst. Be thorough and cite sources.',
+  },
+});
+```
+
+### With Streaming
+
+```typescript
+await wallet.runAgent({
+  sessionId: 'sess_abc123',
+  messages: [{ role: 'user', content: 'Explain machine learning' }],
+  stream: true,
+  onEvent: (event) => {
+    switch (event.type) {
+      case 'llm_chunk':
+        process.stdout.write(event.delta);
+        break;
+      case 'tool_call':
+        console.log(`\nCalling: ${event.tool}`);
+        break;
+      case 'tool_result':
+        console.log(`Tool ${event.tool}: ${event.success ? 'success' : 'failed'}`);
+        break;
+      case 'complete':
+        console.log(`\n\nTotal cost: $${event.totalCostUsd.toFixed(4)}`);
+        break;
+    }
+  },
+});
+```
+
+### Get Run Status
+
+```typescript
+const status = await wallet.getAgentRunStatus('run_abc123', 'sess_xyz789');
+
+console.log(`Status: ${status.status}`);
+if (status.status === 'completed') {
+  console.log(status.response);
+}
+```
+
+---
+
+## MCP Tools
+
+Access external tools like web scraping and search.
+
+### List Available Tools
+
+```typescript
+const tools = await wallet.listMCPTools();
+
+for (const tool of tools) {
+  console.log(`${tool.name}: $${tool.priceUsd} - ${tool.description}`);
+}
+```
+
+### Call Tool (Direct Pay)
+
+```typescript
+const result = await wallet.callMCPTool('firecrawl/scrape', {
+  url: 'https://example.com',
+});
+
+console.log(result.data);
+console.log(`Charged: $${result.chargedUsd}`);
+```
+
+### Call Tool (With Session)
+
+```typescript
+// Create session with tool provider
+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' }
+);
+```
+
+---
+
+## Wallet Information
+
+### Get Balance
+
+```typescript
+const balance = await wallet.getBalance();
+console.log(`Balance: $${balance.toFixed(2)}`);
+```
+
+### Get Spending Stats
+
+```typescript
+const stats = await wallet.getSpendingStats();
+
+console.log(`Total spent: $${stats.totalSpentUsd}`);
+console.log(`Transactions: ${stats.txCount}`);
+console.log(`Daily remaining: $${stats.remainingDailyUsd ?? 'unlimited'}`);
+```
+
+### Get Session Key Info
+
+```typescript
+const info = await wallet.getSessionKeyInfo();
+
+console.log(`Daily limit: $${info.limits.dailyUsd}`);
+console.log(`Expires: ${info.expiresAt}`);
+```
+
+### Payment History
+
+```typescript
+const payments = wallet.getPaymentHistory();
+
+for (const payment of payments) {
+  console.log(`$${payment.amountUsd} to ${payment.recipient} - ${payment.description}`);
+}
+```
+
+---
+
 ## Error Handling
 
 ```typescript
-import { AgentWallet, InsufficientBalanceError, SessionLimitExceededError } from '@mixrpay/agent-sdk';
+import { 
+  AgentWallet,
+  InsufficientBalanceError,
+  SessionLimitExceededError,
+  SessionExpiredError,
+  SessionRevokedError,
+  SpendingLimitExceededError,
+  PaymentFailedError,
+} from '@mixrpay/agent-sdk';
 
 try {
-  const response = await wallet.callMerchantApi({ ... });
+  await wallet.callMerchantApi({ ... });
 } catch (error) {
   if (error instanceof InsufficientBalanceError) {
-    console.log(`Top up at: ${error.topUpUrl}`);
+    console.log(`Need $${error.required}, have $${error.available}`);
+  } else if (error instanceof SessionLimitExceededError) {
+    console.log(`Session limit: $${error.limit}, tried: $${error.attempted}`);
+  } else if (error instanceof SessionExpiredError) {
+    console.log(`Session ${error.sessionId} expired`);
+  } else if (error instanceof SpendingLimitExceededError) {
+    console.log(`${error.limitType} limit exceeded`);
   }
 }
 ```
 
-## Spending Controls
+---
+
+## Configuration Options
 
 ```typescript
 const wallet = new AgentWallet({
+  // Required
   sessionKey: 'sk_live_...',
-  maxPaymentUsd: 1.0,
-  onPayment: (payment) => console.log(`Paid $${payment.amountUsd}`),
+  
+  // Optional
+  walletAddress: '0x...',        // Override wallet address
+  maxPaymentUsd: 5.0,            // Client-side safety limit
+  baseUrl: 'https://...',        // Custom API URL
+  timeout: 60000,                // Request timeout (ms)
+  logLevel: 'info',              // 'debug' | 'info' | 'warn' | 'error' | 'none'
+  
+  // Callbacks
+  onPayment: (payment) => {
+    console.log(`Paid $${payment.amountUsd} to ${payment.recipient}`);
+  },
 });
+```
 
-const balance = await wallet.getBalance();
+---
+
+## Diagnostics
+
+```typescript
+const diagnostics = await wallet.runDiagnostics();
+
+if (diagnostics.healthy) {
+  console.log('Wallet is ready to use');
+} else {
+  console.log('Issues found:');
+  diagnostics.issues.forEach(issue => console.log(`  - ${issue}`));
+}
 ```
 
+---
+
+## Network Info
+
+```typescript
+// Check if testnet
+if (wallet.isTestnet()) {
+  console.log('Using Base Sepolia testnet');
+}
+
+// Get network details
+const network = wallet.getNetwork();
+console.log(`Chain: ${network.name} (${network.chainId})`);
+```
+
+---
+
+## TypeScript Types
+
+All types are exported for TypeScript users:
+
+```typescript
+import type {
+  AgentWalletConfig,
+  PaymentEvent,
+  SpendingStats,
+  SessionAuthorization,
+  AgentMessage,
+  AgentRunConfig,
+  AgentRunOptions,
+  AgentRunResult,
+  AgentRunEvent,
+} from '@mixrpay/agent-sdk';
+```
+
+---
+
 ## Documentation
 
-[mixrpay.com/docs](https://www.mixrpay.com/docs)
+- [Full Documentation](https://www.mixrpay.com/build)
+- [API Reference](https://www.mixrpay.com/build/api)
+- [Agent Runtime Guide](https://www.mixrpay.com/build/api#agent-runtime)
 
 ## License