@mixrpay/agent-sdk 0.3.2 → 0.3.4

package/README.md

@@ -1,495 +1,71 @@
-# MixrPay Agent SDK for JavaScript/TypeScript
+# @mixrpay/agent-sdk
 
-Enable AI agents to make autonomous payments. Supports both session-based payments (for MixrPay merchants) and x402 protocol (for external APIs).
+Enable AI agents to make payments.
 
-[![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';
-
-const wallet = new AgentWallet({
-  sessionKey: 'sk_live_...'  // Get from wallet owner
-});
-
-// 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' }
-});
-
-// For external x402 APIs:
-const response = await wallet.fetch('https://external-api.com/query');
-```
-
-## 📦 Installation
+## Installation
 
 ```bash
 npm install @mixrpay/agent-sdk
-# or
-yarn add @mixrpay/agent-sdk
-# or
-pnpm add @mixrpay/agent-sdk
 ```
 
-## Two Payment Methods
-
-The Agent SDK supports **two payment patterns** depending on what API you're calling:
+## Setup
 
-### 1. Session-Based Payments (For MixrPay Merchants) ⭐ Recommended
-
-Use `callMerchantApi()` when the API uses MixrPay:
-
-```typescript
-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' },
-});
+```bash
+# .env
+MIXRPAY_SESSION_KEY=sk_live_...
 ```
 
-**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
-
-**When to use:** APIs built with MixrPay, or any API that accepts `X-Mixr-Session` headers.
+Get session keys from [mixrpay.com/wallet/sessions](https://www.mixrpay.com/wallet/sessions).
 
-### 2. x402 Protocol (For External APIs)
-
-Use `fetch()` when calling APIs that implement x402 but aren't MixrPay merchants:
+## Usage
 
 ```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 `/wallet/sessions`
-2. **Programmatically**: Via the MixrPay API
-
-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
-
-## 📖 Session Management
-
-### Automatic (Recommended)
+import { AgentWallet } from '@mixrpay/agent-sdk';
 
-`callMerchantApi()` handles sessions automatically:
+const wallet = new AgentWallet({
+  sessionKey: process.env.MIXRPAY_SESSION_KEY!
+});
 
-```typescript
-// Sessions are created and reused automatically
 const response = await wallet.callMerchantApi({
   url: 'https://api.merchant.com/generate',
-  merchantPublicKey: 'pk_live_abc123',
+  merchantPublicKey: 'pk_live_...',
   priceUsd: 0.05,
-  body: { prompt: 'Hello' }
-});
-```
-
-### Manual Control
-
-For fine-grained control over sessions:
-
-```typescript
-// Get or create a session
-const session = await wallet.getOrCreateSession({
-  merchantPublicKey: 'pk_live_abc123',
-  spendingLimitUsd: 25,    // Max total spending
-  durationDays: 7,         // Session validity
-});
-
-console.log('Session ID:', session.id);
-console.log('Remaining:', session.remainingLimitUsd);
-console.log('Expires:', session.expiresAt);
-
-// 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',
-    '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.remainingLimitUsd} 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
-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}`);
-  },
+  body: { prompt: 'Hello world' }
 });
 
-// Make requests
-const response = await wallet.callMerchantApi({ ... });
-
-// Check spending
-const stats = await wallet.getSpendingStats();
-console.log(`Total spent: $${stats.totalSpentUsd.toFixed(2)}`);
-console.log(`Transactions: ${stats.txCount}`);
+const data = await response.json();
 ```
 
-### Error Handling
+## Error Handling
 
 ```typescript
-import {
-  AgentWallet,
-  InsufficientBalanceError,
-  SpendingLimitExceededError,
-  SessionKeyExpiredError,
-  // Session Authorization Errors
-  SessionExpiredError,
-  SessionLimitExceededError,
-  SessionNotFoundError,
-  SessionRevokedError,
-} from '@mixrpay/agent-sdk';
-
-const wallet = new AgentWallet({ sessionKey: 'sk_live_...' });
+import { AgentWallet, InsufficientBalanceError, SessionLimitExceededError } from '@mixrpay/agent-sdk';
 
 try {
   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 ${error.sessionId} expired`);
-    // SDK will auto-create on next callMerchantApi()
-  } else if (error instanceof SessionLimitExceededError) {
-    console.log(`❌ Session limit exceeded`);
-    console.log(`   Limit: $${error.limit}, Requested: $${error.requested}, Remaining: $${error.remaining}`);
-  } else if (error instanceof SessionNotFoundError) {
-    console.log(`❌ Session ${error.sessionId} not found`);
-  } else if (error instanceof SessionRevokedError) {
-    console.log(`❌ Session ${error.sessionId} was revoked: ${error.reason || 'no reason given'}`);
-  } else if (error instanceof SpendingLimitExceededError) {
-    console.log(`❌ Session key limit exceeded: ${error.limitType}`);
-  } else if (error instanceof SessionKeyExpiredError) {
-    console.log(`❌ Session key expired at ${error.expiredAt}`);
-  } else {
-    throw error;
+    console.log(`Top up at: ${error.topUpUrl}`);
   }
 }
 ```
 
-### With Client-Side Safety Limit
+## Spending Controls
 
 ```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);
-```
-
-## 🤖 AI Framework Integrations
-
-### Vercel AI SDK
-
-```typescript
-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,
+  maxPaymentUsd: 1.0,
+  onPayment: (payment) => console.log(`Paid $${payment.amountUsd}`),
 });
 
-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.callMerchantApi({
-            url: 'https://api.search.com/query',
-            merchantPublicKey: 'pk_live_...',
-            priceUsd: 0.05,
-            body: { query }
-          });
-          return response.json();
-        } catch (error) {
-          if (error instanceof SessionLimitExceededError) {
-            return { error: 'Budget exceeded', limit: error.limitType };
-          }
-          throw error;
-        }
-      }
-    }
-  },
-  prompt: 'Search for the latest AI news'
-});
+const balance = await wallet.getBalance();
 ```
 
-### 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,
-});
-
-const paidSearchTool = new DynamicTool({
-  name: 'paid_search',
-  description: 'Premium search API ($0.05/query)',
-  func: async (query: string) => {
-    try {
-      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. Top up: ${error.topUpUrl}`;
-      }
-      return `Error: ${error instanceof Error ? error.message : 'Unknown'}`;
-    }
-  }
-});
-```
-
-## 📚 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 |
-|--------|-------------|
-| `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 |
-| `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 |
-
-### Types
-
-```typescript
-interface SessionAuthorization {
-  id: string;
-  merchantId: string;
-  merchantName: string;
-  status: 'pending' | 'active' | 'expired' | 'revoked';
-  spendingLimitUsd: number;
-  amountUsedUsd: number;
-  remainingLimitUsd: number;
-  expiresAt: Date;
-  createdAt: Date;
-}
-
-interface SessionStats {
-  activeCount: number;
-  expiredCount: number;
-  revokedCount: number;
-  totalAuthorizedUsd: number;
-  totalSpentUsd: number;
-  totalRemainingUsd: number;
-  activeSessions: Array<{
-    id: string;
-    merchantName: string;
-    merchantPublicKey: string;
-    spendingLimitUsd: number;
-    remainingUsd: number;
-    expiresAt: Date;
-  }>;
-}
-
-interface ChargeResult {
-  success: boolean;
-  chargeId: string;
-  amountUsd: number;
-  txHash?: string;
-  remainingSessionBalanceUsd: number;
-}
-
-interface PaymentEvent {
-  amountUsd: number;
-  recipient: string;
-  txHash: string | null;
-  timestamp: Date;
-  description?: string;
-  url?: string;
-}
-```
-
-### Exceptions
-
-| Exception | When Thrown |
-|-----------|-------------|
-| `InsufficientBalanceError` | Wallet doesn't have enough USDC |
-| `SessionKeyExpiredError` | Session key has expired |
-| `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` | x402 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
-
-```typescript
-// Test environment setup
-const wallet = new AgentWallet({
-  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
-
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `MIXRPAY_SESSION_KEY` | Yes | Your session key (`sk_live_...` or `sk_test_...`) |
-| `MIXRPAY_BASE_URL` | No | MixrPay server URL (default: `https://www.mixrpay.com`) |
-
-## 🔒 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
-
-## 📋 Changelog
-
-### v0.2.0 (Current)
-- Added session-based payments (`callMerchantApi()`)
-- Added session management (`getOrCreateSession()`, `listSessions()`, `revokeSession()`)
-- Added session-related error types
-- Improved documentation
+## Documentation
 
-### v0.1.0
-- Initial release
-- x402 payment handling via `fetch()`
-- Session key validation and spending limits
-- Payment callbacks and statistics
+[mixrpay.com/docs](https://www.mixrpay.com/docs)
 
-## 📝 License
+## License
 
 MIT