@mixrpay/merchant-sdk 0.3.3 → 0.3.5

package/README.md

@@ -1,33 +1,28 @@
 # @mixrpay/merchant-sdk
 
-Accept payments from AI agents and web apps with one middleware. Supports session-based payments (Agent SDK, Widget) and x402 protocol.
+Accept payments from AI agents and web apps with one middleware.
 
 ## Installation
 
 ```bash
 npm install @mixrpay/merchant-sdk
-# or
-yarn add @mixrpay/merchant-sdk
-# or
-pnpm add @mixrpay/merchant-sdk
 ```
 
-## Quick Start
-
-### 1. Set Environment Variables
+## Setup
 
 ```bash
 # .env
-MIXRPAY_PUBLIC_KEY=pk_live_...        # Your merchant public key
-MIXRPAY_SECRET_KEY=sk_live_...        # Your merchant secret key
-
-# Optional: for x402 protocol support
-MIXRPAY_MERCHANT_ADDRESS=0xYourWalletAddress
+MIXRPAY_PUBLIC_KEY=pk_live_...
+MIXRPAY_SECRET_KEY=sk_live_...
+MIXRPAY_WEBHOOK_SECRET=whsec_...
+MIXRPAY_HMAC_SECRET=hmac_...  # For Widget user linking
 ```
 
-### 2. Add to Your Routes
+Get credentials from [Developer Settings](https://www.mixrpay.com/seller/developers).
 
-#### Express
+## API Middleware
+
+### Express
 
 ```typescript
 import express from 'express';
@@ -35,431 +30,102 @@ import { mixrpay } from '@mixrpay/merchant-sdk/express';
 
 const app = express();
 
-// Accepts payments from Widget, Agent SDK, and x402 agents
 app.post('/api/generate', mixrpay({ priceUsd: 0.05 }), (req, res) => {
-  // Payment verified! Access via req.mixrPayment
-  const { payer, amountUsd, method } = req.mixrPayment!;
-  
-  console.log(`Payment: $${amountUsd} via ${method} from ${payer}`);
-  
-  const result = processRequest(req.body);
-  res.json(result);
+  const { payer, amountUsd } = req.mixrPayment!;
+  res.json({ result: 'success' });
 });
-
-// Dynamic pricing based on request
-app.post('/api/ai', mixrpay({ 
-  getPrice: (req) => req.body?.premium ? 0.10 : 0.05 
-}), handler);
 ```
 
-#### Next.js (App Router)
+### Next.js
 
 ```typescript
-// app/api/generate/route.ts
-import { withMixrPay, MixrPayment } from '@mixrpay/merchant-sdk/nextjs';
+import { withMixrPay } from '@mixrpay/merchant-sdk/nextjs';
 import { NextRequest, NextResponse } from 'next/server';
 
-async function handler(req: NextRequest, payment: MixrPayment) {
-  // payment contains: { payer, amountUsd, method, sessionId?, chargeId?, txHash? }
-  console.log(`Paid by ${payment.payer}: $${payment.amountUsd} via ${payment.method}`);
-  
+async function handler(req: NextRequest, payment) {
   return NextResponse.json({ result: 'success' });
 }
 
 export const POST = withMixrPay({ priceUsd: 0.05 }, handler);
 ```
 
-#### Fastify
+### Fastify
 
 ```typescript
 import Fastify from 'fastify';
 import { mixrpayPlugin, mixrpay } from '@mixrpay/merchant-sdk/fastify';
 
 const app = Fastify();
+app.register(mixrpayPlugin);
 
-// Register plugin with defaults
-app.register(mixrpayPlugin, { 
-  publicKey: process.env.MIXRPAY_PUBLIC_KEY,
-  secretKey: process.env.MIXRPAY_SECRET_KEY,
-});
-
-// Use on routes
 app.post('/api/generate', { 
   preHandler: mixrpay({ priceUsd: 0.05 }) 
-}, async (req, reply) => {
-  return { result: 'success', payer: req.mixrPayment?.payer };
-});
-```
-
-## Accepted Payment Methods
-
-The middleware automatically handles **three payment methods**:
-
-| Header | Source | Description |
-|--------|--------|-------------|
-| `X-Mixr-Session` | Agent SDK | Session-based payment (recommended for MixrPay clients) |
-| `X-Mixr-Payment` | Widget | Widget payment proof JWT |
-| `X-PAYMENT` | x402 | External agent payment via x402 protocol |
-
-```typescript
-app.post('/api/generate', mixrpay({ priceUsd: 0.05 }), (req, res) => {
-  const { method } = req.mixrPayment!;
-  
-  switch (method) {
-    case 'session':
-      console.log('Payment from Agent SDK');
-      break;
-    case 'widget':
-      console.log('Payment from Widget user');
-      break;
-    case 'x402':
-      console.log('Payment from external x402 agent');
-      break;
-  }
-  
-  res.json({ result: 'success' });
-});
-```
-
-## How It Works
-
-### Session-Based Flow (Agent SDK / Widget)
-
-```
-Agent/User                    Your API                    MixrPay
-    │                            │                           │
-    │  1. Request with           │                           │
-    │     X-Mixr-Session header  │                           │
-    ├───────────────────────────▶│                           │
-    │                            │  2. Validate session      │
-    │                            ├──────────────────────────▶│
-    │                            │◀──────────────────────────┤
-    │  3. Response               │                           │
-    │◀───────────────────────────┤                           │
-```
-
-### x402 Flow (External Agents)
-
-```
-Agent                        Your API                    Facilitator
-    │                            │                           │
-    │  1. Request (no payment)   │                           │
-    ├───────────────────────────▶│                           │
-    │◀── 402 Payment Required ───┤                           │
-    │                            │                           │
-    │  2. Request with           │                           │
-    │     X-PAYMENT header       │                           │
-    ├───────────────────────────▶│                           │
-    │                            │  3. Verify & settle       │
-    │                            ├──────────────────────────▶│
-    │                            │◀──────────────────────────┤
-    │  4. Response               │                           │
-    │◀───────────────────────────┤                           │
-```
-
-## Configuration Options
-
-### MixrPayOptions
-
-```typescript
-interface MixrPayOptions {
-  /** Price in USD (e.g., 0.05 for 5 cents) */
-  priceUsd?: number;
-  
-  /** Dynamic pricing function */
-  getPrice?: (req: Request) => number | Promise<number>;
-  
-  /** Your public key (defaults to MIXRPAY_PUBLIC_KEY env var) */
-  publicKey?: string;
-  
-  /** Your secret key (defaults to MIXRPAY_SECRET_KEY env var) */
-  secretKey?: string;
-  
-  /** Wallet address for x402 (defaults to MIXRPAY_MERCHANT_ADDRESS env var) */
-  merchantAddress?: string;
-  
-  /** x402 facilitator URL (default: https://x402.org/facilitator) */
-  facilitator?: string;
-  
-  /** Description shown to payer */
-  description?: string;
-  
-  /** Callback after successful payment */
-  onPayment?: (payment: MixrPayment) => void | Promise<void>;
-  
-  /** Skip payment for certain requests */
-  skip?: (req: Request) => boolean | Promise<boolean>;
-  
-  /** Test mode - accepts test payments */
-  testMode?: boolean;
-}
-```
-
-### Payment Result
-
-```typescript
-interface MixrPayment {
-  /** Whether payment is valid */
-  valid: boolean;
-  
-  /** Payment method used */
-  method: 'session' | 'widget' | 'x402';
-  
-  /** Payer's wallet address */
-  payer: string;
-  
-  /** Amount paid in USD */
-  amountUsd: number;
-  
-  /** Session ID (for session-based payments) */
-  sessionId?: string;
-  
-  /** Charge record ID */
-  chargeId?: string;
-  
-  /** Settlement transaction hash (for x402) */
-  txHash?: string;
-  
-  /** When payment was made */
-  timestamp: Date;
-  
-  /** Error message if invalid */
-  error?: string;
-  
-  /** Whether payment was pre-charged by the agent (session only) */
-  preCharged?: boolean;
-}
-```
-
-### Pre-Charged Sessions
-
-When AI agents use the Agent SDK, they can pre-charge before calling your API by passing `X-Mixr-Charged: <amount>`. The middleware detects this and validates the session without double-charging:
-
-```typescript
-// Agent SDK calls your API with pre-charged session
-// Headers: { 'X-Mixr-Session': 'sess_abc', 'X-Mixr-Charged': '0.05' }
-
-app.post('/api/query', mixrpay({ priceUsd: 0.05 }), (req, res) => {
-  const { preCharged, amountUsd, payer } = req.mixrPayment!;
-  
-  if (preCharged) {
-    // Agent pre-charged - session validated only, no additional charge made
-    console.log(`Pre-charged payment of $${amountUsd} from ${payer}`);
-  } else {
-    // Middleware charged the session
-    console.log(`Charged $${amountUsd} from ${payer}`);
-  }
-  
-  res.json({ result: 'success' });
+}, async (req) => {
+  return { result: 'success' };
 });
 ```
 
-## Advanced Usage
-
-### Dynamic Pricing
-
-```typescript
-app.post('/api/ai', mixrpay({
-  getPrice: async (req) => {
-    const { model, tokens } = req.body;
-    
-    // Price based on model and usage
-    const rates = { 'gpt-4': 0.03, 'gpt-3.5': 0.002 };
-    const rate = rates[model] || 0.01;
-    
-    return rate * (tokens / 1000);
-  }
-}), handler);
-```
-
-### Skip Payment for Certain Requests
+## Widget Integration
 
-```typescript
-app.post('/api/query', mixrpay({
-  priceUsd: 0.05,
-  skip: async (req) => {
-    // Free for authenticated premium users
-    const user = await getUser(req.headers.authorization);
-    return user?.isPremium || false;
-  }
-}), handler);
-```
+```html
+<script 
+  src="https://www.mixrpay.com/widget.js"
+  data-seller-public-key="pk_live_..."
+  data-user-token="{{ signedToken }}">
+</script>
 
-### Payment Callbacks
+<mixr-balance></mixr-balance>
 
-```typescript
-app.post('/api/query', mixrpay({
-  priceUsd: 0.05,
-  onPayment: async (payment) => {
-    // Log to your analytics
-    await analytics.track('payment_received', {
-      payer: payment.payer,
-      amount: payment.amountUsd,
-      method: payment.method,
-    });
-    
-    // Store in database
-    await db.payments.create({
-      data: {
-        payer: payment.payer,
-        amount: payment.amountUsd,
-        chargeId: payment.chargeId,
-      }
-    });
-  }
-}), handler);
+<button data-meter-feature="generate" data-meter-price-usd="0.10">
+  Generate ($0.10)
+</button>
 ```
 
-### Manual Verification
+### Generate User Tokens
 
 ```typescript
-import { verifyMixrPayment } from '@mixrpay/merchant-sdk';
+import crypto from 'crypto';
 
-// Manual verification without middleware
-const result = await verifyMixrPayment(req.headers, {
-  publicKey: process.env.MIXRPAY_PUBLIC_KEY,
-  secretKey: process.env.MIXRPAY_SECRET_KEY,
-  expectedAmount: 0.05,
-});
-
-if (result.valid) {
-  console.log(`Valid payment from ${result.payer} via ${result.method}`);
+function generateUserToken(userId: string): string {
+  const timestamp = Date.now();
+  const data = `${userId}:${timestamp}`;
+  const signature = crypto
+    .createHmac('sha256', process.env.MIXRPAY_HMAC_SECRET!)
+    .update(data)
+    .digest('hex');
+  return `${data}:${signature}`;
 }
 ```
 
-### Webhook Verification
-
-Verify webhook signatures to ensure events are from MixrPay:
+## Webhooks
 
 ```typescript
 import { verifySessionWebhook } from '@mixrpay/merchant-sdk';
 
 app.post('/webhooks/mixrpay', (req, res) => {
-  const signature = req.headers['x-mixrpay-signature'] as string;
-  const payload = JSON.stringify(req.body);
+  const sig = req.headers['x-mixrpay-signature'] as string;
   
-  // Verify signature using your webhook secret from the dashboard
-  if (!verifySessionWebhook(payload, signature, process.env.WEBHOOK_SECRET!)) {
+  if (!verifySessionWebhook(JSON.stringify(req.body), sig, process.env.MIXRPAY_WEBHOOK_SECRET!)) {
     return res.status(401).json({ error: 'Invalid signature' });
   }
   
-  const event = req.body;
-  
-  switch (event.event) {
-    case 'session.created':
-      // New session authorized
-      console.log(`Session created: ${event.session_id} from ${event.user_wallet}`);
-      console.log(`Spending limit: $${event.spending_limit_usd}`);
-      break;
-      
-    case 'session.charged':
-      // Successful charge against a session
-      console.log(`Charged $${event.amount_usd} from ${event.user_wallet}`);
-      console.log(`Remaining: $${event.remaining_usd}`);
-      // Update your database, trigger fulfillment, etc.
-      break;
-      
-    case 'session.revoked':
-      // User revoked their session
-      console.log(`Session revoked: ${event.session_id}`);
-      break;
-      
-    case 'session.expired':
-      // Session expired
-      console.log(`Session expired: ${event.session_id}`);
-      break;
-  }
-  
+  // Handle event
   res.json({ received: true });
 });
 ```
 
-Configure webhook URLs in your [MixrPay Dashboard](https://www.mixrpay.com/seller/developers).
-
-## Testing
-
-Enable test mode to accept test payments during development:
-
-```typescript
-app.post('/api/query', mixrpay({ 
-  priceUsd: 0.05,
-  testMode: process.env.NODE_ENV !== 'production',
-}), handler);
-```
-
-## Environment Variables
-
-| Variable | Description | Required |
-|----------|-------------|----------|
-| `MIXRPAY_PUBLIC_KEY` | Your merchant public key (pk_...) | Yes |
-| `MIXRPAY_SECRET_KEY` | Your merchant secret key | Yes |
-| `MIXRPAY_MERCHANT_ADDRESS` | Wallet address for x402 payments | For x402 |
-
-## Supported Chains
-
-| Chain | Chain ID | USDC Contract |
-|-------|----------|---------------|
-| Base Mainnet | 8453 | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |
-| Base Sepolia | 84532 | `0x036CbD53842c5426634e7929541eC2318f3dCF7e` |
-
-## Error Handling
-
-The middleware returns appropriate HTTP status codes:
-
-- `402 Payment Required` - No payment or invalid payment
-- `403 Forbidden` - Session limit exceeded or revoked
-- `500 Internal Server Error` - Configuration issues
-
-Error responses include details:
-
-```json
-{
-  "error": "payment_required",
-  "message": "No valid payment provided",
-  "paymentInfo": {
-    "priceUsd": 0.05,
-    "recipient": "0x...",
-    "acceptedMethods": ["X-Mixr-Session", "X-Mixr-Payment", "X-PAYMENT"]
-  }
-}
-```
-
-## TypeScript Support
-
-Full TypeScript support with type definitions included.
+## TypeScript
 
 ```typescript
 import type { MixrPayOptions, MixrPayment } from '@mixrpay/merchant-sdk';
-```
 
-### Widget Custom Elements (React/JSX)
-
-If you're using the MixrPay widget with TypeScript and React, import the type declarations:
-
-```typescript
-// In your app's entry file or a .d.ts file
+// Widget element types
 import '@mixrpay/merchant-sdk/widget-elements';
-
-// Now these work without TypeScript errors:
-<mixr-balance data-theme="dark" />
-<mixr-wallet />
 ```
 
-## Migration from x402-Only
-
-If you were using the old x402-only middleware:
-
-```typescript
-// Before (x402 only)
-import { x402 } from '@mixrpay/merchant-sdk/express';
-app.post('/api/query', x402({ price: 0.05 }), handler);
-
-// After (unified - backwards compatible)
-import { mixrpay } from '@mixrpay/merchant-sdk/express';
-app.post('/api/query', mixrpay({ priceUsd: 0.05 }), handler);
-```
+## Documentation
 
-The new `mixrpay` middleware is backwards compatible—it still accepts x402 payments via `X-PAYMENT` header, but now also accepts session-based payments.
+Full documentation at [mixrpay.com/seller/docs](https://www.mixrpay.com/seller/docs)
 
 ## License