@mixrpay/agent-sdk 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # MixrPay Agent SDK for JavaScript/TypeScript
 
-Enable AI agents to make autonomous payments using x402 protocol with session keys.
+Enable AI agents to make autonomous payments. Supports both session-based payments (for MixrPay merchants) and x402 protocol (for external APIs).
 
 [![npm version](https://img.shields.io/npm/v/@mixrpay/agent-sdk)](https://www.npmjs.com/package/@mixrpay/agent-sdk)
 [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue)](https://www.typescriptlang.org/)
@@ -10,20 +10,20 @@ Enable AI agents to make autonomous payments using x402 protocol with session ke
 ```typescript
 import { AgentWallet } from '@mixrpay/agent-sdk';
 
-// 1. Initialize with a session key (get this from the wallet owner)
 const wallet = new AgentWallet({
-  sessionKey: 'sk_live_...'
+  sessionKey: 'sk_live_...'  // Get from wallet owner
 });
 
-// 2. Make requests - payments are handled automatically!
-const response = await wallet.fetch('https://api.paid-service.com/query', {
-  method: 'POST',
-  headers: { 'Content-Type': 'application/json' },
-  body: JSON.stringify({ prompt: 'Hello world' })
+// For MixrPay merchants (recommended):
+const response = await wallet.callMerchantApi({
+  url: 'https://api.merchant.com/generate',
+  merchantPublicKey: 'pk_live_abc123',
+  priceUsd: 0.05,
+  body: { prompt: 'Hello world' }
 });
 
-// 3. Use the response just like regular fetch
-console.log(await response.json());
+// For external x402 APIs:
+const response = await wallet.fetch('https://external-api.com/query');
 ```
 
 ## 📦 Installation
@@ -36,52 +36,57 @@ yarn add @mixrpay/agent-sdk
 pnpm add @mixrpay/agent-sdk
 ```
 
-## 🔧 Configuration
+## Two Payment Methods
+
+The Agent SDK supports **two payment patterns** depending on what API you're calling:
+
+### 1. Session-Based Payments (For MixrPay Merchants) ⭐ Recommended
 
-By default, the SDK connects to `http://localhost:3000`. For production, set your MixrPay server URL:
+Use `callMerchantApi()` when the API uses MixrPay:
 
 ```typescript
-const wallet = new AgentWallet({
-  sessionKey: 'sk_live_...',
-  baseUrl: 'https://your-mixrpay-server.com',  // Your MixrPay deployment
+const response = await wallet.callMerchantApi({
+  url: 'https://api.merchant.com/generate',
+  merchantPublicKey: 'pk_live_abc123',  // Merchant's MixrPay public key
+  priceUsd: 0.05,
+  method: 'POST',
+  body: { prompt: 'Hello world' },
 });
-
-// Or use environment variable: MIXRPAY_BASE_URL
 ```
 
-## ✅ Verify Installation
+**How it works:**
+1. SDK creates/reuses a session authorization with the merchant
+2. SDK charges against the session
+3. Request is sent with `X-Mixr-Session` header
+4. No 402 round-trip needed—faster and cheaper
 
-Run this quick test to ensure the SDK is installed correctly:
+**When to use:** APIs built with MixrPay, or any API that accepts `X-Mixr-Session` headers.
 
-```typescript
-import { AgentWallet, SDK_VERSION } from '@mixrpay/agent-sdk';
+### 2. x402 Protocol (For External APIs)
 
-// Check SDK version
-console.log(`MixrPay Agent SDK v${SDK_VERSION}`);
+Use `fetch()` when calling APIs that implement x402 but aren't MixrPay merchants:
 
-// Create a wallet instance (will validate session key format)
-try {
-  const wallet = new AgentWallet({
-    sessionKey: 'sk_test_0000000000000000000000000000000000000000000000000000000000000000',
-    baseUrl: 'http://localhost:3000',
-  });
-  console.log('✓ SDK initialized successfully');
-  
-  // Check connection (will fail without a running server, but validates setup)
-  wallet.getBalance().catch(() => {
-    console.log('✓ SDK configured (server not running - expected in test)');
-  });
-} catch (error) {
-  console.error('✗ SDK initialization failed:', error);
-}
+```typescript
+const response = await wallet.fetch('https://external-api.com/query', {
+  method: 'POST',
+  body: JSON.stringify({ prompt: 'Hello' })
+});
 ```
 
+**How it works:**
+1. SDK makes initial request
+2. API returns `402 Payment Required`
+3. SDK signs payment authorization
+4. SDK retries with `X-PAYMENT` header
+
+**When to use:** External APIs that use standard x402 protocol.
+
 ## 🔑 Getting Session Keys
 
 Session keys are created by wallet owners and grant spending permissions to agents:
 
-1. **From a wallet owner**: They create a session key at your MixrPay server's `/wallet/sessions` page
-2. **Programmatically**: Via the MixrPay API (for applications managing their own wallets)
+1. **From a wallet owner**: They create a session key at `/wallet/sessions`
+2. **Programmatically**: Via the MixrPay API
 
 Session keys look like: `sk_live_abc123...` (mainnet) or `sk_test_abc123...` (testnet)
 
@@ -93,58 +98,76 @@ Each session key has configurable spending limits:
 - **Total**: Maximum lifetime spend
 - **Expiration**: When the key becomes invalid
 
-## 💡 How It Works
+## 📖 Session Management
 
-```
-┌─────────────┐     ┌─────────────┐     ┌─────────────┐
-│   Agent     │────▶│  Paid API   │────▶│ Facilitator │
-│   (you)     │◀────│  (402)      │◀────│   (x402)    │
-└─────────────┘     └─────────────┘     └─────────────┘
-       │                   │                   │
-       │ 1. Request        │                   │
-       ├──────────────────▶│                   │
-       │                   │                   │
-       │ 2. 402 + price    │                   │
-       │◀──────────────────┤                   │
-       │                   │                   │
-       │ 3. Sign payment   │                   │
-       ├──────────────────▶│                   │
-       │                   │ 4. Process        │
-       │                   ├──────────────────▶│
-       │                   │                   │
-       │ 5. Response       │ 5. Confirm        │
-       │◀──────────────────┤◀──────────────────┤
-       │                   │                   │
-```
+### Automatic (Recommended)
 
-1. Your agent makes a request to a paid API
-2. The server returns `402 Payment Required` with pricing
-3. The SDK automatically signs a USDC transfer authorization
-4. The facilitator processes the payment
-5. You receive the API response
+`callMerchantApi()` handles sessions automatically:
 
-## 📖 Usage Examples
+```typescript
+// Sessions are created and reused automatically
+const response = await wallet.callMerchantApi({
+  url: 'https://api.merchant.com/generate',
+  merchantPublicKey: 'pk_live_abc123',
+  priceUsd: 0.05,
+  body: { prompt: 'Hello' }
+});
+```
 
-### Basic Request
+### Manual Control
 
-```typescript
-import { AgentWallet } from '@mixrpay/agent-sdk';
+For fine-grained control over sessions:
 
-const wallet = new AgentWallet({
-  sessionKey: process.env.MIXRPAY_SESSION_KEY!,
+```typescript
+// Get or create a session
+const session = await wallet.getOrCreateSession({
+  merchantPublicKey: 'pk_live_abc123',
+  spendingLimitUsd: 25,    // Max total spending
+  durationDays: 7,         // Session validity
 });
 
-// GET request
-const response = await wallet.fetch('https://api.example.com/data');
+console.log('Session ID:', session.id);
+console.log('Remaining:', session.remainingUsd);
+console.log('Expires:', session.expiresAt);
 
-// POST request with JSON
-const result = await wallet.fetch('https://api.example.com/generate', {
+// Charge manually
+const charge = await wallet.chargeSession(session.id, 0.05, {
+  feature: 'generate',
+  idempotencyKey: `charge-${Date.now()}`,
+});
+
+// Then make your API call with the session
+const response = await fetch('https://api.merchant.com/generate', {
   method: 'POST',
-  headers: { 'Content-Type': 'application/json' },
-  body: JSON.stringify({ prompt: 'Write a poem' })
+  headers: {
+    'Content-Type': 'application/json',
+    'X-Mixr-Session': session.id,
+    'X-Mixr-Charged': 'true',  // Tell merchant payment is done
+  },
+  body: JSON.stringify({ prompt: 'Hello' }),
 });
 ```
 
+### List and Revoke Sessions
+
+```typescript
+// List all active sessions
+const sessions = await wallet.listSessions();
+for (const session of sessions) {
+  console.log(`${session.merchantName}: $${session.remainingUsd} remaining`);
+}
+
+// Revoke a session (e.g., when done with a merchant)
+await wallet.revokeSession(session.id);
+
+// Get session statistics
+const stats = await wallet.getSessionStats();
+console.log(`Active sessions: ${stats.activeCount}`);
+console.log(`Total authorized: $${stats.totalAuthorizedUsd}`);
+```
+
+## 💡 Usage Examples
+
 ### With Payment Tracking
 
 ```typescript
@@ -154,21 +177,16 @@ const wallet = new AgentWallet({
   sessionKey: 'sk_live_...',
   onPayment: (payment: PaymentEvent) => {
     console.log(`💸 Paid $${payment.amountUsd.toFixed(4)} to ${payment.recipient}`);
-    console.log(`   For: ${payment.description || 'API call'}`);
   },
 });
 
 // Make requests
-for (let i = 0; i < 5; i++) {
-  await wallet.fetch(`https://api.example.com/query/${i}`);
-}
+const response = await wallet.callMerchantApi({ ... });
 
 // Check spending
 const stats = await wallet.getSpendingStats();
-console.log(`\n📊 Session Summary:`);
-console.log(`   Total spent: $${stats.totalSpentUsd.toFixed(2)}`);
-console.log(`   Transactions: ${stats.txCount}`);
-console.log(`   Remaining daily: $${stats.remainingDailyUsd?.toFixed(2) ?? 'unlimited'}`);
+console.log(`Total spent: $${stats.totalSpentUsd.toFixed(2)}`);
+console.log(`Transactions: ${stats.txCount}`);
 ```
 
 ### Error Handling
@@ -179,25 +197,28 @@ import {
   InsufficientBalanceError,
   SpendingLimitExceededError,
   SessionKeyExpiredError,
+  SessionExpiredError,
+  SessionLimitExceededError,
 } from '@mixrpay/agent-sdk';
 
 const wallet = new AgentWallet({ sessionKey: 'sk_live_...' });
 
 try {
-  const response = await wallet.fetch('https://api.example.com/expensive');
-  console.log(await response.json());
+  const response = await wallet.callMerchantApi({ ... });
 } catch (error) {
   if (error instanceof InsufficientBalanceError) {
     console.log(`❌ Not enough funds: need $${error.required}, have $${error.available}`);
     console.log(`   Top up at: ${error.topUpUrl}`);
+  } else if (error instanceof SessionExpiredError) {
+    console.log('❌ Session expired, creating new one...');
+    // SDK will auto-create on next callMerchantApi()
+  } else if (error instanceof SessionLimitExceededError) {
+    console.log(`❌ Session limit exceeded: ${error.limitType}`);
+    console.log(`   Limit: $${error.limit}, Requested: $${error.requested}`);
   } else if (error instanceof SpendingLimitExceededError) {
-    console.log(`❌ Limit exceeded: ${error.limitType} limit is $${error.limit}`);
-    if (error.limitType === 'daily') {
-      console.log('   Try again tomorrow, or request a higher limit.');
-    }
+    console.log(`❌ Session key limit exceeded: ${error.limitType}`);
   } else if (error instanceof SessionKeyExpiredError) {
     console.log(`❌ Session key expired at ${error.expiredAt}`);
-    console.log('   Request a new key from the wallet owner.');
   } else {
     throw error;
   }
@@ -227,28 +248,6 @@ const wallet = new AgentWallet({
 
 // Or toggle at runtime
 wallet.setDebug(true);
-await wallet.fetch('https://api.example.com/endpoint');
-wallet.setDebug(false);
-```
-
-### Diagnostics
-
-```typescript
-const wallet = new AgentWallet({ sessionKey: 'sk_live_...' });
-
-// Run health checks
-const diagnostics = await wallet.runDiagnostics();
-
-if (diagnostics.healthy) {
-  console.log('✅ Wallet is ready to use');
-  console.log(`   Network: ${diagnostics.network}`);
-  console.log(`   Wallet: ${diagnostics.walletAddress}`);
-} else {
-  console.log('❌ Issues found:');
-  for (const issue of diagnostics.issues) {
-    console.log(`   - ${issue}`);
-  }
-}
 ```
 
 ## 🤖 AI Framework Integrations
@@ -256,15 +255,14 @@ if (diagnostics.healthy) {
 ### Vercel AI SDK
 
 ```typescript
-import { AgentWallet, InsufficientBalanceError, SpendingLimitExceededError } from '@mixrpay/agent-sdk';
+import { AgentWallet, SessionLimitExceededError } from '@mixrpay/agent-sdk';
 import { generateText } from 'ai';
 import { openai } from '@ai-sdk/openai';
 import { z } from 'zod';
 
 const wallet = new AgentWallet({
   sessionKey: process.env.MIXRPAY_SESSION_KEY!,
-  maxPaymentUsd: 1.00,  // Safety limit per request
-  onPayment: (p) => console.log(`Paid $${p.amountUsd} for API call`),
+  maxPaymentUsd: 1.00,
 });
 
 const result = await generateText({
@@ -275,25 +273,23 @@ const result = await generateText({
       parameters: z.object({ query: z.string() }),
       execute: async ({ query }) => {
         try {
-          const response = await wallet.fetch('https://api.search.com/query', {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({ query })
+          const response = await wallet.callMerchantApi({
+            url: 'https://api.search.com/query',
+            merchantPublicKey: 'pk_live_...',
+            priceUsd: 0.05,
+            body: { query }
           });
           return response.json();
         } catch (error) {
-          if (error instanceof InsufficientBalanceError) {
-            return { error: 'Insufficient funds', topUpUrl: error.topUpUrl };
+          if (error instanceof SessionLimitExceededError) {
+            return { error: 'Budget exceeded', limit: error.limitType };
           }
-          if (error instanceof SpendingLimitExceededError) {
-            return { error: 'Spending limit reached', limit: error.limitType };
-          }
-          throw error;  // Re-throw unexpected errors
+          throw error;
         }
       }
     }
   },
-  prompt: 'Search for the latest AI news and summarize it'
+  prompt: 'Search for the latest AI news'
 });
 ```
 
@@ -305,33 +301,30 @@ import { DynamicTool } from '@langchain/core/tools';
 
 const wallet = new AgentWallet({ 
   sessionKey: process.env.MIXRPAY_SESSION_KEY!,
-  maxPaymentUsd: 0.50,  // Cap per tool invocation
+  maxPaymentUsd: 0.50,
 });
 
 const paidSearchTool = new DynamicTool({
   name: 'paid_search',
-  description: 'Premium search API ($0.05/query) - use for high-quality results',
+  description: 'Premium search API ($0.05/query)',
   func: async (query: string) => {
     try {
-      const response = await wallet.fetch('https://api.search.com/query', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ query })
+      const response = await wallet.callMerchantApi({
+        url: 'https://api.search.com/query',
+        merchantPublicKey: 'pk_live_...',
+        priceUsd: 0.05,
+        body: { query }
       });
       const data = await response.json();
       return JSON.stringify(data.results);
     } catch (error) {
       if (error instanceof InsufficientBalanceError) {
-        return `Error: Low balance ($${error.available}). Need $${error.required}. Top up: ${error.topUpUrl}`;
+        return `Error: Low balance. Top up: ${error.topUpUrl}`;
       }
-      return `Error: ${error instanceof Error ? error.message : 'Unknown error'}`;
+      return `Error: ${error instanceof Error ? error.message : 'Unknown'}`;
     }
   }
 });
-
-// Check spending before expensive operations
-const stats = await wallet.getSpendingStats();
-console.log(`Budget remaining: $${stats.remainingDailyUsd ?? 'unlimited'}`);
 ```
 
 ## 📚 API Reference
@@ -354,11 +347,17 @@ new AgentWallet({
 })
 ```
 
-#### Methods
+### Methods
 
 | Method | Description |
 |--------|-------------|
-| `fetch(url, init?)` | Make HTTP request (drop-in for native fetch) |
+| `callMerchantApi(options)` | Make request to MixrPay merchant (session-based) |
+| `fetch(url, init?)` | Make request to x402 API (drop-in for native fetch) |
+| `getOrCreateSession(options)` | Get or create session with merchant |
+| `chargeSession(id, amount, options?)` | Charge against a session |
+| `listSessions()` | List all active sessions |
+| `revokeSession(id)` | Revoke a session |
+| `getSessionStats()` | Get session statistics |
 | `getBalance()` | Get USDC balance in USD |
 | `getSpendingStats()` | Get spending statistics |
 | `getSessionKeyInfo()` | Get session key details and limits |
@@ -369,44 +368,37 @@ new AgentWallet({
 | `isTestnet()` | Check if using testnet |
 | `runDiagnostics()` | Run health checks |
 | `setDebug(enable)` | Toggle debug logging |
-| `setLogLevel(level)` | Set log level |
 
 ### Types
 
 ```typescript
-interface PaymentEvent {
-  amountUsd: number;       // Payment amount in USD
-  recipient: string;       // Recipient address
-  txHash: string | null;   // Transaction hash
-  timestamp: Date;         // When payment was made
-  description?: string;    // What was paid for
-  url?: string;           // URL that triggered payment
+interface Session {
+  id: string;
+  merchantPublicKey: string;
+  merchantName?: string;
+  spendingLimitUsd: number;
+  spentUsd: number;
+  remainingUsd: number;
+  status: 'active' | 'expired' | 'revoked';
+  expiresAt: Date;
+  createdAt: Date;
 }
 
-interface SpendingStats {
-  totalSpentUsd: number;
-  txCount: number;
-  remainingDailyUsd: number | null;
-  remainingTotalUsd: number | null;
-  expiresAt: Date | null;
+interface ChargeResult {
+  success: boolean;
+  chargeId: string;
+  amountUsd: number;
+  txHash?: string;
+  remainingUsd: number;
 }
 
-interface SessionKeyInfo {
-  address: string;
-  isValid: boolean;
-  limits: {
-    perTxUsd: number | null;
-    dailyUsd: number | null;
-    totalUsd: number | null;
-  };
-  usage: {
-    todayUsd: number;
-    totalUsd: number;
-    txCount: number;
-  };
-  expiresAt: Date | null;
-  createdAt: Date | null;
-  name?: string;
+interface PaymentEvent {
+  amountUsd: number;
+  recipient: string;
+  txHash: string | null;
+  timestamp: Date;
+  description?: string;
+  url?: string;
 }
 ```
 
@@ -416,10 +408,14 @@ interface SessionKeyInfo {
 |-----------|-------------|
 | `InsufficientBalanceError` | Wallet doesn't have enough USDC |
 | `SessionKeyExpiredError` | Session key has expired |
-| `SpendingLimitExceededError` | Payment would exceed limits |
+| `SpendingLimitExceededError` | Would exceed session key limits |
+| `SessionExpiredError` | Session authorization has expired |
+| `SessionLimitExceededError` | Would exceed session spending limit |
+| `SessionNotFoundError` | Session ID is invalid |
+| `SessionRevokedError` | Session was revoked |
 | `PaymentFailedError` | Payment transaction failed |
 | `InvalidSessionKeyError` | Invalid session key format |
-| `X402ProtocolError` | Protocol handling error |
+| `X402ProtocolError` | x402 protocol handling error |
 
 ## 🌐 Networks
 
@@ -430,19 +426,15 @@ interface SessionKeyInfo {
 
 ### Testing on Testnet
 
-1. **Get test ETH**: Use the [Base Sepolia faucet](https://www.alchemy.com/faucets/base-sepolia)
-2. **Get test USDC**: Available from the wallet dashboard after funding with test ETH
-3. **Create test session key**: Use the wallet dashboard to create `sk_test_...` keys
-4. **Test your integration**: Use test keys with your development environment
-
 ```typescript
 // Test environment setup
 const wallet = new AgentWallet({
-  sessionKey: process.env.MIXRPAY_SESSION_KEY!,  // sk_test_...
-  baseUrl: 'http://localhost:3000',  // Your local MixrPay server
+  sessionKey: 'sk_test_...',  // Use test key
+  baseUrl: 'http://localhost:3000',  // Local dev server
 });
 
 // The SDK automatically detects testnet from sk_test_ prefix
+console.log(`Testnet: ${wallet.isTestnet()}`);  // true
 ```
 
 ## 🔧 Environment Variables
@@ -450,33 +442,7 @@ const wallet = new AgentWallet({
 | Variable | Required | Description |
 |----------|----------|-------------|
 | `MIXRPAY_SESSION_KEY` | Yes | Your session key (`sk_live_...` or `sk_test_...`) |
-| `MIXRPAY_BASE_URL` | No | MixrPay server URL (default: `http://localhost:3000`) |
-
-### x402 Facilitator
-
-The SDK uses the x402 protocol facilitator at `https://x402.org/facilitator` by default. The facilitator:
-- Verifies payment signatures
-- Submits transactions to the blockchain
-- Returns settlement confirmation
-
-You can use a custom facilitator for testing or self-hosted deployments:
-```typescript
-const wallet = new AgentWallet({
-  sessionKey: 'sk_live_...',
-  facilitatorUrl: 'https://your-facilitator.com',  // Custom facilitator
-});
-```
-
-Example `.env` file:
-```bash
-# Production
-MIXRPAY_SESSION_KEY=sk_live_abc123...
-MIXRPAY_BASE_URL=https://your-mixrpay-server.com
-
-# Development (testnet)
-MIXRPAY_SESSION_KEY=sk_test_abc123...
-MIXRPAY_BASE_URL=http://localhost:3000
-```
+| `MIXRPAY_BASE_URL` | No | MixrPay server URL (default: `https://mixrpay.com`) |
 
 ## 🔒 Security Best Practices
 
@@ -486,22 +452,19 @@ MIXRPAY_BASE_URL=http://localhost:3000
 4. **Use testnet first** - Test with `sk_test_` keys before production
 5. **Configure base URL** - Always set `baseUrl` explicitly in production
 
-## 🌐 Browser Support
-
-This SDK works in both Node.js and browser environments. In browsers, it uses the native `fetch` and `crypto` APIs.
-
 ## 📋 Changelog
 
-### v0.1.0 (Current)
+### v0.2.0 (Current)
+- Added session-based payments (`callMerchantApi()`)
+- Added session management (`getOrCreateSession()`, `listSessions()`, `revokeSession()`)
+- Added session-related error types
+- Improved documentation
+
+### v0.1.0
 - Initial release
-- Core `AgentWallet` class with x402 payment handling
-- Automatic 402 response detection and payment flow
-- Session key validation and spending limit enforcement
-- Payment callbacks and spending statistics
-- Vercel AI SDK and LangChain.js integration examples
-- Debug mode and diagnostics
-
-See [CHANGELOG.md](./CHANGELOG.md) for full release history.
+- x402 payment handling via `fetch()`
+- Session key validation and spending limits
+- Payment callbacks and statistics
 
 ## 📝 License