@mixrpay/merchant-sdk 0.3.3 → 0.3.6

package/README.md

@@ -1,465 +1,100 @@
 # @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.
 
 ## 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_...
 ```
 
-### 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';
 import { mixrpay } from '@mixrpay/merchant-sdk/express';
 
 const app = express();
+app.use(express.json());
 
-// 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 { 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}`);
-  
   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' });
+app.post('/api/generate', { preHandler: mixrpay({ priceUsd: 0.05 }) }, async (req) => {
+  return { 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' });
-});
-```
-
-## 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
-
-```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);
-```
-
-### Payment Callbacks
-
-```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);
-```
-
-### Manual Verification
-
-```typescript
-import { verifyMixrPayment } from '@mixrpay/merchant-sdk';
+## Widget
 
-// 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,
-});
+```html
+<script 
+  src="https://www.mixrpay.com/widget.js"
+  data-seller-public-key="pk_live_..."
+  data-user-token="{{ userToken }}">
+</script>
 
-if (result.valid) {
-  console.log(`Valid payment from ${result.payer} via ${result.method}`);
-}
+<mixr-balance></mixr-balance>
 ```
 
-### Webhook Verification
+Generate user tokens server-side using your HMAC secret. See [Widget docs](https://www.mixrpay.com/seller/widget).
 
-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);
-  
-  // Verify signature using your webhook secret from the dashboard
-  if (!verifySessionWebhook(payload, signature, process.env.WEBHOOK_SECRET!)) {
+  const sig = req.headers['x-mixrpay-signature'] as string;
+  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;
-  }
-  
   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
-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);
-```
+## Documentation
 
-The new `mixrpay` middleware is backwards compatible—it still accepts x402 payments via `X-PAYMENT` header, but now also accepts session-based payments.
+[mixrpay.com/seller/docs](https://www.mixrpay.com/seller/docs)
 
 ## License
 

package/dist/index.d.mts

@@ -77,6 +77,68 @@ interface SessionGrant {
  */
 declare function verifySessionWebhook(payload: string, signature: string, secret: string): boolean;
 
+/**
+ * MixrPay Merchant SDK - Utilities
+ */
+
+/**
+ * Get the MixrPay widget script URL.
+ *
+ * @example
+ * ```html
+ * <script src="${getWidgetUrl()}"
+ *   data-seller-public-key="pk_live_..."
+ *   data-user-token="..."></script>
+ * ```
+ */
+declare function getWidgetUrl(): string;
+/**
+ * MixrPay API base URL
+ */
+declare const MIXRPAY_API_URL = "https://www.mixrpay.com";
+/**
+ * Widget script URL (for convenience)
+ */
+declare const WIDGET_SCRIPT_URL = "https://www.mixrpay.com/widget.js";
+/**
+ * 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;
+interface EnvValidationResult {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+    config: {
+        publicKey: string | null;
+        secretKey: string | null;
+        hmacSecret: string | null;
+        webhookSecret: string | null;
+        merchantAddress: string | null;
+    };
+}
+/**
+ * Validate MixrPay environment variables and provide helpful feedback.
+ *
+ * @example
+ * ```typescript
+ * import { validateEnv } from '@mixrpay/merchant-sdk';
+ *
+ * const result = validateEnv();
+ * if (!result.valid) {
+ *   console.error('MixrPay configuration errors:', result.errors);
+ * }
+ * ```
+ */
+declare function validateEnv(env?: Record<string, string | undefined>): EnvValidationResult;
+/**
+ * Log environment validation results to console with formatting.
+ */
+declare function logEnvValidation(result?: EnvValidationResult): void;
+
 /**
  * MixrPay Widget Custom Element Type Declarations
  * 
@@ -149,6 +211,43 @@ interface MixrState {
 // Global API Types
 // =============================================================================
 
+/**
+ * Session state object returned by window.Mixr.getSessionState()
+ */
+interface MixrSessionState {
+  /** Whether user has an active session */
+  hasSession: boolean;
+  /** Current session ID */
+  sessionId: string | null;
+  /** Remaining spending limit in USD */
+  remainingUsd: number;
+  /** Total spending limit in USD */
+  spendingLimitUsd: number;
+  /** Session expiration date */
+  expiresAt: Date | null;
+  /** Session status */
+  status: 'active' | 'expired' | 'revoked' | null;
+  /** Session type */
+  type: 'session_key' | 'authorization' | null;
+}
+
+/**
+ * Diagnostic result from Mixr.diagnose()
+ */
+interface MixrDiagnosticResult {
+  config: {
+    hasPublicKey: boolean;
+    hasUserToken: boolean;
+    hasWidgetToken: boolean;
+    mode: 'wallet_auth' | 'domain_verified' | 'hmac';
+  };
+  state: MixrState;
+  session: MixrSessionState;
+  issues: string[];
+  warnings: string[];
+  isLocalhost: boolean;
+}
+
 /**
  * MixrPay global API available on window.Mixr
  */
@@ -165,6 +264,12 @@ interface MixrAPI {
   /** Get current widget state */
   getState(): MixrState;
   
+  /** Get current session state */
+  getSessionState(): MixrSessionState;
+  
+  /** Fetch fresh session state from server */
+  getSession(): Promise<MixrSessionState>;
+  
   /** Refresh user balance and state */
   refresh(): Promise<void>;
   
@@ -175,6 +280,69 @@ interface MixrAPI {
    * @param element - The element that triggered the charge (for UI feedback)
    */
   charge(feature: string, priceUsd: string, element: HTMLElement): Promise<void>;
+  
+  /** Check if user is authenticated */
+  isAuthenticated(): boolean;
+  
+  /** Get user's wallet address */
+  getWalletAddress(): string | null;
+  
+  /** Check if user can afford a given amount */
+  canAfford(amountUsd: number): boolean;
+  
+  /** Check if widget is ready for transactions */
+  isReady(minBalance?: number): boolean;
+  
+  /** Get detailed readiness status */
+  getReadinessStatus(minBalance?: number): {
+    ready: boolean;
+    issues: string[];
+    balanceUsd: number;
+    sessionId: string | null;
+    sessionRemaining: number;
+  };
+  
+  /** Trigger wallet connection (for wallet-auth mode) */
+  connect(): void;
+  
+  /** Disconnect and clear local session */
+  disconnect(): void;
+  
+  /** Prompt user to authorize a spending session */
+  authorizeSession(spendingLimitUsd?: number, durationDays?: number): Promise<boolean>;
+  
+  /** Check if wallet is non-custodial */
+  isNonCustodial(): boolean;
+  
+  /** Get current theme */
+  getTheme(): 'dark' | 'light';
+  
+  /** Set theme */
+  setTheme(theme: 'dark' | 'light' | 'auto'): void;
+  
+  /**
+   * Configure widget callbacks
+   */
+  setConfig(config: {
+    onSessionChange?: (session: MixrSessionState) => void;
+    onStateChange?: (state: MixrState) => void;
+    defaultSessionLimit?: number;
+    defaultSessionDuration?: number;
+  }): void;
+  
+  /**
+   * Diagnostic tool for debugging widget issues.
+   * Call Mixr.diagnose() in browser console to see widget status.
+   */
+  diagnose(): MixrDiagnosticResult;
+  
+  /** Enable debug mode for verbose logging */
+  enableDebug(): void;
+  
+  /**
+   * Make an authenticated fetch request with MixrPay headers
+   */
+  fetch(url: string, options?: RequestInit & { autoPrompt?: boolean }): Promise<Response>;
 }
 
 // =============================================================================
@@ -286,4 +454,4 @@ declare global {
   }
 }
 
-export { PaymentReceipt, type SessionGrant, verifyPaymentReceipt, verifySessionWebhook };
+export { type EnvValidationResult, MIXRPAY_API_URL, PaymentReceipt, type SessionGrant, WIDGET_SCRIPT_URL, getWidgetUrl, logEnvValidation, minorToUsd, usdToMinor, validateEnv, verifyPaymentReceipt, verifySessionWebhook };