@mixrpay/merchant-sdk 0.1.0

package/README.md

@@ -0,0 +1,293 @@
+# @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.
+
+## Installation
+
+```bash
+npm install @mixrpay/merchant-sdk
+# or
+yarn add @mixrpay/merchant-sdk
+# or
+pnpm add @mixrpay/merchant-sdk
+```
+
+## Quick Start
+
+### 1. Set Your Wallet Address
+
+```bash
+# In your .env file
+MIXRPAY_MERCHANT_ADDRESS=0xYourWalletAddress
+```
+
+### 2. Add to Your Routes
+
+#### Express
+
+```typescript
+import express from 'express';
+import { x402 } 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!;
+  
+  console.log(`Payment received: $${amount} from ${payer}`);
+  
+  const result = processQuery(req.body);
+  res.json(result);
+});
+
+// Dynamic pricing based on request
+app.post('/api/generate', x402({ 
+  getPrice: (ctx) => ctx.body?.premium ? 0.10 : 0.05 
+}), handler);
+```
+
+#### Next.js (App Router)
+
+```typescript
+// app/api/query/route.ts
+import { withX402 } 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}`);
+  
+  return NextResponse.json({ result: 'success' });
+}
+
+export const POST = withX402({ price: 0.05 }, handler);
+```
+
+#### Fastify
+
+```typescript
+import Fastify from 'fastify';
+import { x402Plugin, x402 } from '@mixrpay/merchant-sdk/fastify';
+
+const app = Fastify();
+
+// Register plugin with defaults
+app.register(x402Plugin, { 
+  recipient: process.env.MIXRPAY_MERCHANT_ADDRESS,
+});
+
+// Use on routes
+app.post('/api/query', { 
+  preHandler: x402({ price: 0.05 }) 
+}, async (req, reply) => {
+  return { result: 'success', payer: req.x402Payment?.payer };
+});
+```
+
+## 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
+
+```
+Client                          Server                      Facilitator
+  |                                |                              |
+  |-- POST /api/query ------------>|                              |
+  |<-- 402 Payment Required -------|                              |
+  |                                |                              |
+  |-- POST /api/query ------------>|                              |
+  |   X-PAYMENT: <signed auth>     |                              |
+  |                                |-- verify & settle ---------->|
+  |                                |<-- tx hash -----------------|
+  |<-- 200 OK --------------------|                              |
+```
+
+## Configuration Options
+
+### X402Options
+
+```typescript
+interface X402Options {
+  /** Price in USD (e.g., 0.05 for 5 cents) */
+  price: number;
+  
+  /** Your wallet address (defaults to MIXRPAY_MERCHANT_ADDRESS env var) */
+  recipient?: string;
+  
+  /** Chain ID (default: 8453 for Base) */
+  chainId?: number;
+  
+  /** 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>;
+  
+  /** Skip payment for certain requests */
+  skip?: (context: SkipContext) => boolean | Promise<boolean>;
+  
+  /** Test mode - skips on-chain settlement */
+  testMode?: boolean;
+}
+```
+
+### Payment Result
+
+```typescript
+interface X402PaymentResult {
+  /** Whether payment is valid */
+  valid: boolean;
+  
+  /** Payer's wallet address */
+  payer?: string;
+  
+  /** Amount paid in USD */
+  amount?: number;
+  
+  /** Settlement transaction hash */
+  txHash?: string;
+  
+  /** When payment was settled */
+  settledAt?: Date;
+  
+  /** Error message if invalid */
+  error?: string;
+}
+```
+
+## Advanced Usage
+
+### Dynamic Pricing
+
+```typescript
+app.post('/api/ai', x402({
+  getPrice: async (ctx) => {
+    const { model, tokens } = ctx.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
+
+```typescript
+app.post('/api/query', x402({
+  price: 0.05,
+  skip: (ctx) => {
+    // Free for authenticated premium users
+    return ctx.headers['x-premium-token'] === 'valid';
+  }
+}), handler);
+```
+
+### Payment Callbacks
+
+```typescript
+app.post('/api/query', x402({
+  price: 0.05,
+  onPayment: async (payment) => {
+    // Log to your analytics
+    await analytics.track('payment_received', {
+      payer: payment.payer,
+      amount: payment.amount,
+      txHash: payment.txHash,
+    });
+    
+    // Store in database
+    await db.payments.create({
+      data: {
+        payer: payment.payer,
+        amount: payment.amount,
+        txHash: payment.txHash,
+      }
+    });
+  }
+}), handler);
+```
+
+### Custom Verification
+
+```typescript
+import { verifyX402Payment, usdToMinor } from '@mixrpay/merchant-sdk';
+
+// Manual verification without middleware
+const result = await verifyX402Payment(paymentHeader, {
+  expectedAmount: usdToMinor(0.05),
+  expectedRecipient: '0x...',
+  chainId: 8453,
+});
+
+if (result.valid) {
+  console.log(`Valid payment from ${result.payer}`);
+}
+```
+
+## Testing
+
+Enable test mode to skip on-chain settlement during development:
+
+```typescript
+app.post('/api/query', x402({ 
+  price: 0.05,
+  testMode: process.env.NODE_ENV !== 'production',
+}), handler);
+```
+
+## Environment Variables
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `MIXRPAY_MERCHANT_ADDRESS` | Your wallet address to receive payments | Yes (or pass `recipient` option) |
+
+## 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
+- `500 Internal Server Error` - Configuration issues
+
+Error responses include details:
+
+```json
+{
+  "error": "Invalid payment",
+  "reason": "Insufficient payment: expected 50000, got 10000"
+}
+```
+
+## TypeScript Support
+
+Full TypeScript support with type definitions included.
+
+```typescript
+import type { X402Options, X402PaymentResult } from '@mixrpay/merchant-sdk';
+```
+
+## License
+
+MIT
+

package/dist/index.d.mts

@@ -0,0 +1,291 @@
+import { V as VerifyOptions, X as X402PaymentResult, a as VerifyReceiptOptions, P as PaymentReceipt } from './types-BJNy6Hhb.mjs';
+export { E as EIP712Domain, e as PriceContext, R as ReceiptMode, S as SkipContext, T as TransferWithAuthorizationMessage, b as X402Options, d as X402PaymentPayload, c as X402PaymentRequired } from './types-BJNy6Hhb.mjs';
+export { default as expressX402 } from './middleware/express.mjs';
+export { createPaymentRequired, withX402 } from './middleware/nextjs.mjs';
+export { x402 as fastifyX402, x402Plugin } from './middleware/fastify.mjs';
+import 'express';
+import 'next/server';
+import 'fastify';
+
+/**
+ * MixrPay Merchant SDK - Payment Verification
+ */
+
+/**
+ * Verify an X-PAYMENT header and optionally settle the payment.
+ *
+ * @param paymentHeader - The X-PAYMENT header value (base64 encoded JSON)
+ * @param options - Verification options
+ * @returns Payment verification result
+ *
+ * @example
+ * ```typescript
+ * const result = await verifyX402Payment(req.headers['x-payment'], {
+ *   expectedAmount: 50000n, // 0.05 USDC
+ *   expectedRecipient: '0x...',
+ * });
+ *
+ * if (result.valid) {
+ *   console.log(`Payment from ${result.payer}: $${result.amount}`);
+ * }
+ * ```
+ */
+declare function verifyX402Payment(paymentHeader: string, options: VerifyOptions): Promise<X402PaymentResult>;
+/**
+ * Parse and validate an X-PAYMENT header without settlement.
+ * Useful for checking if a payment is structurally valid before processing.
+ */
+declare function parseX402Payment(paymentHeader: string, chainId?: number): Promise<{
+    valid: boolean;
+    error?: string;
+    payer?: string;
+    recipient?: string;
+    amount?: number;
+    amountMinor?: bigint;
+    expiresAt?: Date;
+}>;
+
+/**
+ * MixrPay Merchant SDK - Payment Receipt Verification
+ *
+ * Verify JWT payment receipts issued by MixrPay after successful x402 payments.
+ *
+ * @example
+ * ```typescript
+ * import { verifyPaymentReceipt } from '@mixrpay/merchant-sdk';
+ *
+ * const receipt = req.headers['x-payment-receipt'];
+ * const payment = await verifyPaymentReceipt(receipt);
+ *
+ * console.log(`Payment received: $${payment.amountUsd} from ${payment.payer}`);
+ * console.log(`Transaction: ${payment.txHash}`);
+ * ```
+ */
+
+/**
+ * Verify a JWT payment receipt from MixrPay.
+ *
+ * This function:
+ * 1. Fetches the JWKS from MixrPay (cached for 1 hour)
+ * 2. Verifies the JWT signature using RS256
+ * 3. Validates standard JWT claims (exp, iat)
+ * 4. Returns the typed payment receipt
+ *
+ * @param receipt - The JWT receipt string from X-Payment-Receipt header
+ * @param options - Optional configuration (custom JWKS URL, issuer validation)
+ * @returns Verified payment receipt
+ * @throws Error if verification fails
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const payment = await verifyPaymentReceipt(receipt);
+ *
+ * // With custom JWKS URL (for testing or self-hosted)
+ * const payment = await verifyPaymentReceipt(receipt, {
+ *   jwksUrl: 'https://your-mixrpay.com/.well-known/jwks'
+ * });
+ * ```
+ */
+declare function verifyPaymentReceipt(receipt: string, options?: VerifyReceiptOptions): Promise<PaymentReceipt>;
+/**
+ * Parse a JWT payment receipt without verification.
+ *
+ * WARNING: This does NOT verify the signature. Use only for debugging
+ * or when you've already verified the receipt elsewhere.
+ *
+ * @param receipt - The JWT receipt string
+ * @returns Decoded payload (unverified)
+ */
+declare function parsePaymentReceipt(receipt: string): PaymentReceipt;
+/**
+ * Check if a receipt is expired.
+ *
+ * @param receipt - The JWT receipt string or parsed PaymentReceipt
+ * @returns true if expired, false otherwise
+ */
+declare function isReceiptExpired(receipt: string | PaymentReceipt): boolean;
+/**
+ * Clear the JWKS cache.
+ * Useful for testing or when keys have rotated.
+ */
+declare function clearJWKSCache(): void;
+/**
+ * Get the default JWKS URL.
+ */
+declare function getDefaultJWKSUrl(): string;
+
+/**
+ * MixrPay Merchant SDK - Utilities
+ */
+
+declare const USDC_CONTRACTS: Record<number, `0x${string}`>;
+declare const DEFAULT_FACILITATOR = "https://x402.org/facilitator";
+/**
+ * Convert USD dollars to USDC minor units (6 decimals)
+ */
+declare function usdToMinor(usd: number): bigint;
+/**
+ * Convert USDC minor units to USD dollars
+ */
+declare function minorToUsd(minor: bigint): number;
+/**
+ * Generate a random nonce for x402 payments
+ */
+declare function generateNonce(): `0x${string}`;
+/**
+ * Check if an address is valid
+ */
+declare function isValidAddress(address: string): address is `0x${string}`;
+/**
+ * Normalize an address to lowercase checksum format
+ */
+declare function normalizeAddress(address: string): `0x${string}`;
+
+/**
+ * MixrPay Charges Module
+ *
+ * Create and manage charges using session signers.
+ * Session signers allow you to charge user wallets without
+ * requiring approval for each transaction.
+ */
+interface CreateChargeParams {
+    /** Session key ID granted by the user */
+    sessionId: string;
+    /** Amount to charge in USD (e.g., 0.05 for 5 cents) */
+    amountUsd: number;
+    /** Unique reference for idempotency (e.g., "order_123") */
+    reference: string;
+    /** Optional metadata */
+    metadata?: Record<string, unknown>;
+}
+interface Charge {
+    /** Unique charge ID */
+    id: string;
+    /** Current status */
+    status: 'pending' | 'submitted' | 'confirmed' | 'failed';
+    /** Amount in USD */
+    amountUsd: number;
+    /** Formatted USDC amount */
+    amountUsdc: string;
+    /** Transaction hash (if submitted) */
+    txHash?: string;
+    /** Block explorer URL */
+    explorerUrl?: string;
+    /** From wallet address */
+    fromAddress: string;
+    /** To wallet address */
+    toAddress: string;
+    /** Your reference */
+    reference: string;
+    /** When the charge was created */
+    createdAt: string;
+    /** When the charge was confirmed */
+    confirmedAt?: string;
+    /** Session name */
+    sessionName?: string;
+    /** User wallet address */
+    userWallet?: string;
+    /** Error message if failed */
+    error?: string;
+}
+interface CreateChargeResult {
+    success: boolean;
+    charge?: Charge;
+    /** True if this is a replay of an existing charge */
+    idempotentReplay?: boolean;
+    error?: string;
+    details?: string;
+}
+interface SessionGrant {
+    /** Session key ID */
+    sessionId: string;
+    /** User's wallet address */
+    userWallet: string;
+    /** Your merchant wallet address */
+    merchantWallet: string;
+    /** Spending limits */
+    limits: {
+        maxTotalUsd?: number;
+        maxPerTxUsd?: number;
+        expiresAt: string;
+    };
+    /** When the session was granted */
+    grantedAt: string;
+}
+interface ChargesClientOptions {
+    /** Your API key */
+    apiKey: string;
+    /** MixrPay API base URL */
+    baseUrl?: string;
+}
+declare class ChargesClient {
+    private apiKey;
+    private baseUrl;
+    constructor(options: ChargesClientOptions);
+    /**
+     * Create a new charge.
+     *
+     * @example
+     * ```typescript
+     * const result = await charges.create({
+     *   sessionId: 'sk_xxx',
+     *   amountUsd: 0.05,
+     *   reference: 'image_gen_123',
+     *   metadata: { feature: 'image_generation' }
+     * });
+     *
+     * if (result.success) {
+     *   console.log(`Charged ${result.charge.amountUsdc}`);
+     *   console.log(`TX: ${result.charge.explorerUrl}`);
+     * }
+     * ```
+     */
+    create(params: CreateChargeParams): Promise<CreateChargeResult>;
+    /**
+     * Get a charge by ID.
+     *
+     * @example
+     * ```typescript
+     * const charge = await charges.get('chg_xxx');
+     * console.log(charge.status); // 'confirmed'
+     * ```
+     */
+    get(chargeId: string): Promise<Charge | null>;
+    /**
+     * Get a charge by transaction hash.
+     */
+    getByTxHash(txHash: string): Promise<Charge | null>;
+}
+/**
+ * Verify a session.granted webhook signature.
+ *
+ * @example
+ * ```typescript
+ * const payload = req.body;
+ * const signature = req.headers['x-mixrpay-signature'];
+ *
+ * if (verifySessionWebhook(JSON.stringify(payload), signature, webhookSecret)) {
+ *   const grant = parseSessionGrant(payload);
+ *   console.log(`User ${grant.userWallet} granted access`);
+ * }
+ * ```
+ */
+declare function verifySessionWebhook(payload: string, signature: string, secret: string): boolean;
+/**
+ * Parse a session.granted webhook payload.
+ */
+declare function parseSessionGrant(payload: {
+    event: string;
+    session_id: string;
+    user_wallet: string;
+    merchant_wallet: string;
+    limits: {
+        max_total_usd?: number;
+        max_per_tx_usd?: number;
+        expires_at: string;
+    };
+    granted_at: string;
+}): SessionGrant;
+
+export { type Charge, ChargesClient, type ChargesClientOptions, type CreateChargeParams, type CreateChargeResult, DEFAULT_FACILITATOR, PaymentReceipt, type SessionGrant, USDC_CONTRACTS, VerifyOptions, VerifyReceiptOptions, X402PaymentResult, clearJWKSCache, generateNonce, getDefaultJWKSUrl, isReceiptExpired, isValidAddress, minorToUsd, normalizeAddress, parsePaymentReceipt, parseSessionGrant, parseX402Payment, usdToMinor, verifyPaymentReceipt, verifySessionWebhook, verifyX402Payment };