@mixrpay/agent-sdk 0.1.0

package/README.md

@@ -0,0 +1,508 @@
+# MixrPay Agent SDK for JavaScript/TypeScript
+
+Enable AI agents to make autonomous payments using x402 protocol with session keys.
+
+[![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/)
+
+## 🚀 Quick Start
+
+```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_...'
+});
+
+// 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' })
+});
+
+// 3. Use the response just like regular fetch
+console.log(await response.json());
+```
+
+## 📦 Installation
+
+```bash
+npm install @mixrpay/agent-sdk
+# or
+yarn add @mixrpay/agent-sdk
+# or
+pnpm add @mixrpay/agent-sdk
+```
+
+## 🔧 Configuration
+
+By default, the SDK connects to `http://localhost:3000`. For production, set your MixrPay server URL:
+
+```typescript
+const wallet = new AgentWallet({
+  sessionKey: 'sk_live_...',
+  baseUrl: 'https://your-mixrpay-server.com',  // Your MixrPay deployment
+});
+
+// Or use environment variable: MIXRPAY_BASE_URL
+```
+
+## ✅ Verify Installation
+
+Run this quick test to ensure the SDK is installed correctly:
+
+```typescript
+import { AgentWallet, SDK_VERSION } from '@mixrpay/agent-sdk';
+
+// Check SDK version
+console.log(`MixrPay Agent SDK v${SDK_VERSION}`);
+
+// 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);
+}
+```
+
+## 🔑 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)
+
+Session keys look like: `sk_live_abc123...` (mainnet) or `sk_test_abc123...` (testnet)
+
+### Session Key Limits
+
+Each session key has configurable spending limits:
+- **Per-transaction**: Maximum amount per single request
+- **Daily**: Maximum total per 24 hours
+- **Total**: Maximum lifetime spend
+- **Expiration**: When the key becomes invalid
+
+## 💡 How It Works
+
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│   Agent     │────▶│  Paid API   │────▶│ Facilitator │
+│   (you)     │◀────│  (402)      │◀────│   (x402)    │
+└─────────────┘     └─────────────┘     └─────────────┘
+       │                   │                   │
+       │ 1. Request        │                   │
+       ├──────────────────▶│                   │
+       │                   │                   │
+       │ 2. 402 + price    │                   │
+       │◀──────────────────┤                   │
+       │                   │                   │
+       │ 3. Sign payment   │                   │
+       ├──────────────────▶│                   │
+       │                   │ 4. Process        │
+       │                   ├──────────────────▶│
+       │                   │                   │
+       │ 5. Response       │ 5. Confirm        │
+       │◀──────────────────┤◀──────────────────┤
+       │                   │                   │
+```
+
+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
+
+## 📖 Usage Examples
+
+### Basic Request
+
+```typescript
+import { AgentWallet } from '@mixrpay/agent-sdk';
+
+const wallet = new AgentWallet({
+  sessionKey: process.env.MIXRPAY_SESSION_KEY!,
+});
+
+// GET request
+const response = await wallet.fetch('https://api.example.com/data');
+
+// POST request with JSON
+const result = await wallet.fetch('https://api.example.com/generate', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ prompt: 'Write a poem' })
+});
+```
+
+### With Payment Tracking
+
+```typescript
+import { AgentWallet, PaymentEvent } from '@mixrpay/agent-sdk';
+
+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}`);
+}
+
+// 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'}`);
+```
+
+### Error Handling
+
+```typescript
+import {
+  AgentWallet,
+  InsufficientBalanceError,
+  SpendingLimitExceededError,
+  SessionKeyExpiredError,
+} 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());
+} 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 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.');
+    }
+  } 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;
+  }
+}
+```
+
+### With Client-Side Safety Limit
+
+```typescript
+const wallet = new AgentWallet({
+  sessionKey: 'sk_live_...',
+  maxPaymentUsd: 1.0,  // Never pay more than $1 per request
+});
+
+// If an API tries to charge more than $1, the SDK will throw
+// SpendingLimitExceededError with limitType: 'client_max'
+```
+
+### Debug Mode
+
+```typescript
+// Enable logging during initialization
+const wallet = new AgentWallet({
+  sessionKey: 'sk_live_...',
+  logLevel: 'debug',  // 'debug' | 'info' | 'warn' | 'error' | 'none'
+});
+
+// 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
+
+### Vercel AI SDK
+
+```typescript
+import { AgentWallet, InsufficientBalanceError, SpendingLimitExceededError } 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`),
+});
+
+const result = await generateText({
+  model: openai('gpt-4'),
+  tools: {
+    paidSearch: {
+      description: 'Search using a premium paid API',
+      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 })
+          });
+          return response.json();
+        } catch (error) {
+          if (error instanceof InsufficientBalanceError) {
+            return { error: 'Insufficient funds', topUpUrl: error.topUpUrl };
+          }
+          if (error instanceof SpendingLimitExceededError) {
+            return { error: 'Spending limit reached', limit: error.limitType };
+          }
+          throw error;  // Re-throw unexpected errors
+        }
+      }
+    }
+  },
+  prompt: 'Search for the latest AI news and summarize it'
+});
+```
+
+### LangChain.js
+
+```typescript
+import { AgentWallet, InsufficientBalanceError } from '@mixrpay/agent-sdk';
+import { DynamicTool } from '@langchain/core/tools';
+
+const wallet = new AgentWallet({ 
+  sessionKey: process.env.MIXRPAY_SESSION_KEY!,
+  maxPaymentUsd: 0.50,  // Cap per tool invocation
+});
+
+const paidSearchTool = new DynamicTool({
+  name: 'paid_search',
+  description: 'Premium search API ($0.05/query) - use for high-quality results',
+  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 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: ${error instanceof Error ? error.message : 'Unknown error'}`;
+    }
+  }
+});
+
+// Check spending before expensive operations
+const stats = await wallet.getSpendingStats();
+console.log(`Budget remaining: $${stats.remainingDailyUsd ?? 'unlimited'}`);
+```
+
+## 📚 API Reference
+
+### AgentWallet
+
+```typescript
+new AgentWallet({
+  // Required
+  sessionKey: string;              // Session key (sk_live_... or sk_test_...)
+  
+  // Optional
+  walletAddress?: string;          // Smart wallet address (auto-detected)
+  maxPaymentUsd?: number;          // Client-side payment limit
+  onPayment?: (PaymentEvent) => void;  // Payment callback
+  facilitatorUrl?: string;         // x402 facilitator URL
+  baseUrl?: string;                // MixrPay API base URL
+  timeout?: number;                // Request timeout in ms (default: 30000)
+  logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'none';
+})
+```
+
+#### Methods
+
+| Method | Description |
+|--------|-------------|
+| `fetch(url, init?)` | Make HTTP request (drop-in for native fetch) |
+| `getBalance()` | Get USDC balance in USD |
+| `getSpendingStats()` | Get spending statistics |
+| `getSessionKeyInfo()` | Get session key details and limits |
+| `getPaymentHistory()` | Get list of payments made |
+| `getTotalSpent()` | Get total amount spent |
+| `getWalletAddress()` | Get wallet address |
+| `getNetwork()` | Get network info (Base or Base Sepolia) |
+| `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 SpendingStats {
+  totalSpentUsd: number;
+  txCount: number;
+  remainingDailyUsd: number | null;
+  remainingTotalUsd: number | null;
+  expiresAt: Date | null;
+}
+
+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;
+}
+```
+
+### Exceptions
+
+| Exception | When Thrown |
+|-----------|-------------|
+| `InsufficientBalanceError` | Wallet doesn't have enough USDC |
+| `SessionKeyExpiredError` | Session key has expired |
+| `SpendingLimitExceededError` | Payment would exceed limits |
+| `PaymentFailedError` | Payment transaction failed |
+| `InvalidSessionKeyError` | Invalid session key format |
+| `X402ProtocolError` | Protocol handling error |
+
+## 🌐 Networks
+
+| Network | Chain ID | Session Key Prefix | USDC Address |
+|---------|----------|-------------------|--------------|
+| Base Mainnet | 8453 | `sk_live_` | Production USDC |
+| Base Sepolia | 84532 | `sk_test_` | Test USDC |
+
+### 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
+});
+
+// The SDK automatically detects testnet from sk_test_ prefix
+```
+
+## 🔧 Environment Variables
+
+| 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
+```
+
+## 🔒 Security Best Practices
+
+1. **Store session keys securely** - Use environment variables, never commit to source
+2. **Set appropriate limits** - Use `maxPaymentUsd` as a safety net
+3. **Monitor spending** - Use `onPayment` callback and `getSpendingStats()`
+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)
+- 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.
+
+## 📝 License
+
+MIT