@mixrpay/merchant-sdk 0.1.1 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # @mixrpay/merchant-sdk
 
-Add x402 payments to your API in minutes. Let AI agents pay for your services automatically with USDC - no signups, no API keys, no invoices.
+Accept payments from AI agents and web apps with one middleware. Supports session-based payments (Agent SDK, Widget) and x402 protocol.
 
 ## Installation
 
@@ -14,10 +14,14 @@ pnpm add @mixrpay/merchant-sdk
 
 ## Quick Start
 
-### 1. Set Your Wallet Address
+### 1. Set Environment Variables
 
 ```bash
-# In your .env file
+# .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
 ```
 
@@ -27,118 +31,166 @@ MIXRPAY_MERCHANT_ADDRESS=0xYourWalletAddress
 
 ```typescript
 import express from 'express';
-import { x402 } from '@mixrpay/merchant-sdk/express';
+import { mixrpay } from '@mixrpay/merchant-sdk/express';
 
 const app = express();
 
-// Fixed price - $0.05 per request
-app.post('/api/query', x402({ price: 0.05 }), (req, res) => {
-  // This only runs after payment is verified
-  const { payer, amount, txHash } = req.x402Payment!;
+// 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 received: $${amount} from ${payer}`);
+  console.log(`Payment: $${amountUsd} via ${method} from ${payer}`);
   
-  const result = processQuery(req.body);
+  const result = processRequest(req.body);
   res.json(result);
 });
 
 // Dynamic pricing based on request
-app.post('/api/generate', x402({ 
-  getPrice: (ctx) => ctx.body?.premium ? 0.10 : 0.05 
+app.post('/api/ai', mixrpay({ 
+  getPrice: (req) => req.body?.premium ? 0.10 : 0.05 
 }), handler);
 ```
 
 #### Next.js (App Router)
 
 ```typescript
-// app/api/query/route.ts
-import { withX402 } from '@mixrpay/merchant-sdk/nextjs';
+// app/api/generate/route.ts
+import { withMixrPay, MixrPayment } from '@mixrpay/merchant-sdk/nextjs';
 import { NextRequest, NextResponse } from 'next/server';
 
-async function handler(req: NextRequest, payment: X402PaymentResult) {
-  // payment contains: { payer, amount, txHash, settledAt }
-  console.log(`Paid by ${payment.payer}: $${payment.amount}`);
+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}`);
   
   return NextResponse.json({ result: 'success' });
 }
 
-export const POST = withX402({ price: 0.05 }, handler);
+export const POST = withMixrPay({ priceUsd: 0.05 }, handler);
 ```
 
 #### Fastify
 
 ```typescript
 import Fastify from 'fastify';
-import { x402Plugin, x402 } from '@mixrpay/merchant-sdk/fastify';
+import { mixrpayPlugin, mixrpay } from '@mixrpay/merchant-sdk/fastify';
 
 const app = Fastify();
 
 // Register plugin with defaults
-app.register(x402Plugin, { 
-  recipient: process.env.MIXRPAY_MERCHANT_ADDRESS,
+app.register(mixrpayPlugin, { 
+  publicKey: process.env.MIXRPAY_PUBLIC_KEY,
+  secretKey: process.env.MIXRPAY_SECRET_KEY,
 });
 
 // Use on routes
-app.post('/api/query', { 
-  preHandler: x402({ price: 0.05 }) 
+app.post('/api/generate', { 
+  preHandler: mixrpay({ priceUsd: 0.05 }) 
 }, async (req, reply) => {
-  return { result: 'success', payer: req.x402Payment?.payer };
+  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
 
-1. **Client makes request** without payment header
-2. **Server returns 402** with payment requirements (amount, recipient, etc.)
-3. **Client signs USDC transfer** using their session key
-4. **Client retries** with `X-PAYMENT` header containing signed authorization
-5. **Server verifies signature** and submits to facilitator for settlement
-6. **Server processes request** after payment confirmation
+### 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)
 
 ```
-Client                          Server                      Facilitator
-  |                                |                              |
-  |-- POST /api/query ------------>|                              |
-  |<-- 402 Payment Required -------|                              |
-  |                                |                              |
-  |-- POST /api/query ------------>|                              |
-  |   X-PAYMENT: <signed auth>     |                              |
-  |                                |-- verify & settle ---------->|
-  |                                |<-- tx hash -----------------|
-  |<-- 200 OK --------------------|                              |
+Agent                        Your API                    Facilitator
+    │                            │                           │
+    │  1. Request (no payment)   │                           │
+    ├───────────────────────────▶│                           │
+    │◀── 402 Payment Required ───┤                           │
+    │                            │                           │
+    │  2. Request with           │                           │
+    │     X-PAYMENT header       │                           │
+    ├───────────────────────────▶│                           │
+    │                            │  3. Verify & settle       │
+    │                            ├──────────────────────────▶│
+    │                            │◀──────────────────────────┤
+    │  4. Response               │                           │
+    │◀───────────────────────────┤                           │
 ```
 
 ## Configuration Options
 
-### X402Options
+### MixrPayOptions
 
 ```typescript
-interface X402Options {
+interface MixrPayOptions {
   /** Price in USD (e.g., 0.05 for 5 cents) */
-  price: number;
+  priceUsd?: number;
+  
+  /** Dynamic pricing function */
+  getPrice?: (req: Request) => number | Promise<number>;
   
-  /** Your wallet address (defaults to MIXRPAY_MERCHANT_ADDRESS env var) */
-  recipient?: string;
+  /** Your public key (defaults to MIXRPAY_PUBLIC_KEY env var) */
+  publicKey?: string;
   
-  /** Chain ID (default: 8453 for Base) */
-  chainId?: number;
+  /** Your secret key (defaults to MIXRPAY_SECRET_KEY env var) */
+  secretKey?: string;
   
-  /** Facilitator URL (default: https://x402.org/facilitator) */
+  /** 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;
   
-  /** Dynamic pricing function */
-  getPrice?: (context: PriceContext) => number | Promise<number>;
-  
   /** Callback after successful payment */
-  onPayment?: (payment: X402PaymentResult) => void | Promise<void>;
+  onPayment?: (payment: MixrPayment) => void | Promise<void>;
   
   /** Skip payment for certain requests */
-  skip?: (context: SkipContext) => boolean | Promise<boolean>;
+  skip?: (req: Request) => boolean | Promise<boolean>;
   
-  /** Test mode - skips on-chain settlement */
+  /** Test mode - accepts test payments */
   testMode?: boolean;
 }
 ```
@@ -146,21 +198,30 @@ interface X402Options {
 ### Payment Result
 
 ```typescript
-interface X402PaymentResult {
+interface MixrPayment {
   /** Whether payment is valid */
   valid: boolean;
   
+  /** Payment method used */
+  method: 'session' | 'widget' | 'x402';
+  
   /** Payer's wallet address */
-  payer?: string;
+  payer: string;
   
   /** Amount paid in USD */
-  amount?: number;
+  amountUsd: number;
+  
+  /** Session ID (for session-based payments) */
+  sessionId?: string;
   
-  /** Settlement transaction hash */
+  /** Charge record ID */
+  chargeId?: string;
+  
+  /** Settlement transaction hash (for x402) */
   txHash?: string;
   
-  /** When payment was settled */
-  settledAt?: Date;
+  /** When payment was made */
+  timestamp: Date;
   
   /** Error message if invalid */
   error?: string;
@@ -172,9 +233,9 @@ interface X402PaymentResult {
 ### Dynamic Pricing
 
 ```typescript
-app.post('/api/ai', x402({
-  getPrice: async (ctx) => {
-    const { model, tokens } = ctx.body;
+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 };
@@ -188,11 +249,12 @@ app.post('/api/ai', x402({
 ### Skip Payment for Certain Requests
 
 ```typescript
-app.post('/api/query', x402({
-  price: 0.05,
-  skip: (ctx) => {
+app.post('/api/query', mixrpay({
+  priceUsd: 0.05,
+  skip: async (req) => {
     // Free for authenticated premium users
-    return ctx.headers['x-premium-token'] === 'valid';
+    const user = await getUser(req.headers.authorization);
+    return user?.isPremium || false;
   }
 }), handler);
 ```
@@ -200,52 +262,52 @@ app.post('/api/query', x402({
 ### Payment Callbacks
 
 ```typescript
-app.post('/api/query', x402({
-  price: 0.05,
+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.amount,
-      txHash: payment.txHash,
+      amount: payment.amountUsd,
+      method: payment.method,
     });
     
     // Store in database
     await db.payments.create({
       data: {
         payer: payment.payer,
-        amount: payment.amount,
-        txHash: payment.txHash,
+        amount: payment.amountUsd,
+        chargeId: payment.chargeId,
       }
     });
   }
 }), handler);
 ```
 
-### Custom Verification
+### Manual Verification
 
 ```typescript
-import { verifyX402Payment, usdToMinor } from '@mixrpay/merchant-sdk';
+import { verifyMixrPayment } from '@mixrpay/merchant-sdk';
 
 // Manual verification without middleware
-const result = await verifyX402Payment(paymentHeader, {
-  expectedAmount: usdToMinor(0.05),
-  expectedRecipient: '0x...',
-  chainId: 8453,
+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}`);
+  console.log(`Valid payment from ${result.payer} via ${result.method}`);
 }
 ```
 
 ## Testing
 
-Enable test mode to skip on-chain settlement during development:
+Enable test mode to accept test payments during development:
 
 ```typescript
-app.post('/api/query', x402({ 
-  price: 0.05,
+app.post('/api/query', mixrpay({ 
+  priceUsd: 0.05,
   testMode: process.env.NODE_ENV !== 'production',
 }), handler);
 ```
@@ -254,7 +316,9 @@ app.post('/api/query', x402({
 
 | Variable | Description | Required |
 |----------|-------------|----------|
-| `MIXRPAY_MERCHANT_ADDRESS` | Your wallet address to receive payments | Yes (or pass `recipient` option) |
+| `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
 
@@ -268,14 +332,20 @@ app.post('/api/query', x402({
 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": "Invalid payment",
-  "reason": "Insufficient payment: expected 50000, got 10000"
+  "error": "payment_required",
+  "message": "No valid payment provided",
+  "paymentInfo": {
+    "priceUsd": 0.05,
+    "recipient": "0x...",
+    "acceptedMethods": ["X-Mixr-Session", "X-Mixr-Payment", "X-PAYMENT"]
+  }
 }
 ```
 
@@ -284,10 +354,38 @@ Error responses include details:
 Full TypeScript support with type definitions included.
 
 ```typescript
-import type { X402Options, X402PaymentResult } from '@mixrpay/merchant-sdk';
+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
+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);
 ```
 
+The new `mixrpay` middleware is backwards compatible—it still accepts x402 payments via `X-PAYMENT` header, but now also accepts session-based payments.
+
 ## License
 
 MIT
-