@mixrpay/merchant-sdk 0.3.5 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # @mixrpay/merchant-sdk
 
-Accept payments from AI agents and web apps with one middleware.
+Accept payments from AI agents and web apps. One SDK for backend middleware and frontend widget integration.
 
 ## Installation
 
@@ -8,19 +8,33 @@ Accept payments from AI agents and web apps with one middleware.
 npm install @mixrpay/merchant-sdk
 ```
 
-## Setup
+## Exports
+
+| Import Path | Purpose |
+|-------------|---------|
+| `@mixrpay/merchant-sdk` | Core utilities, webhook verification |
+| `@mixrpay/merchant-sdk/express` | Express middleware |
+| `@mixrpay/merchant-sdk/nextjs` | Next.js App Router wrapper |
+| `@mixrpay/merchant-sdk/fastify` | Fastify plugin |
+| `@mixrpay/merchant-sdk/widget` | Programmatic widget injection |
+| `@mixrpay/merchant-sdk/widget-elements` | TypeScript types for widget elements |
+
+## Environment Variables
 
 ```bash
-# .env
 MIXRPAY_PUBLIC_KEY=pk_live_...
 MIXRPAY_SECRET_KEY=sk_live_...
 MIXRPAY_WEBHOOK_SECRET=whsec_...
-MIXRPAY_HMAC_SECRET=hmac_...  # For Widget user linking
+MIXRPAY_HMAC_SECRET=hmac_...
 ```
 
 Get credentials from [Developer Settings](https://www.mixrpay.com/seller/developers).
 
-## API Middleware
+---
+
+## Backend Middleware
+
+Wrap your API routes to require payment. Works with sessions from the Widget or Agent SDK.
 
 ### Express
 
@@ -29,21 +43,22 @@ import express from 'express';
 import { mixrpay } from '@mixrpay/merchant-sdk/express';
 
 const app = express();
+app.use(express.json());
 
 app.post('/api/generate', mixrpay({ priceUsd: 0.05 }), (req, res) => {
-  const { payer, amountUsd } = req.mixrPayment!;
+  const { payer, amountUsd, method } = req.mixrPayment!;
   res.json({ result: 'success' });
 });
 ```
 
-### Next.js
+### Next.js (App Router)
 
 ```typescript
-import { withMixrPay } from '@mixrpay/merchant-sdk/nextjs';
+import { withMixrPay, MixrPayPaymentResult } from '@mixrpay/merchant-sdk/nextjs';
 import { NextRequest, NextResponse } from 'next/server';
 
-async function handler(req: NextRequest, payment) {
-  return NextResponse.json({ result: 'success' });
+async function handler(req: NextRequest, payment: MixrPayPaymentResult) {
+  return NextResponse.json({ result: 'success', payer: payment.payer });
 }
 
 export const POST = withMixrPay({ priceUsd: 0.05 }, handler);
@@ -53,50 +68,98 @@ export const POST = withMixrPay({ priceUsd: 0.05 }, handler);
 
 ```typescript
 import Fastify from 'fastify';
-import { mixrpayPlugin, mixrpay } from '@mixrpay/merchant-sdk/fastify';
+import { x402Plugin, x402 } from '@mixrpay/merchant-sdk/fastify';
 
 const app = Fastify();
-app.register(mixrpayPlugin);
+app.register(x402Plugin);
 
-app.post('/api/generate', { 
-  preHandler: mixrpay({ priceUsd: 0.05 }) 
-}, async (req) => {
+app.post('/api/generate', { preHandler: x402({ price: 0.05 }) }, async (req) => {
   return { result: 'success' };
 });
 ```
 
-## Widget Integration
+### Middleware Options
+
+```typescript
+mixrpay({
+  priceUsd: 0.05,                    // Fixed price
+  getPrice: (req) => calculatePrice(req.body),  // Dynamic pricing
+  feature: 'ai-chat',                // Feature slug for tracking
+  onPayment: (payment) => log(payment),  // Callback on success
+  skip: (req) => req.user?.isPremium,    // Skip payment conditionally
+})
+```
+
+---
+
+## Frontend Widget
+
+### HTML (Simple)
 
 ```html
 <script 
   src="https://www.mixrpay.com/widget.js"
   data-seller-public-key="pk_live_..."
-  data-user-token="{{ signedToken }}">
+  data-user-token="{{ serverGeneratedToken }}">
 </script>
 
 <mixr-balance></mixr-balance>
 
-<button data-meter-feature="generate" data-meter-price-usd="0.10">
-  Generate ($0.10)
+<button data-meter-feature="generate" data-meter-price-usd="0.05">
+  Generate ($0.05)
 </button>
 ```
 
-### Generate User Tokens
+### Programmatic (SPA/React/Vue)
 
 ```typescript
-import crypto from 'crypto';
-
-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}`;
+import { injectWidget, isWidgetLoaded } from '@mixrpay/merchant-sdk/widget';
+
+// Inject widget with config
+await injectWidget({
+  publicKey: 'pk_live_...',
+  userToken: serverGeneratedToken,
+  theme: 'dark',
+});
+
+// Use the widget API
+if (isWidgetLoaded()) {
+  window.Mixr.openWallet();
+  window.Mixr.charge('feature', '0.05', buttonElement);
 }
 ```
 
+### Widget Events
+
+```typescript
+window.addEventListener('mixr:charge-success', (e) => {
+  const { feature, price, txHash } = e.detail;
+  // Payment succeeded, unlock feature
+});
+
+window.addEventListener('mixr:low-balance', (e) => {
+  // User needs to add funds
+});
+
+window.addEventListener('mixr:session-updated', (e) => {
+  const { sessionId, remainingUsd } = e.detail;
+  // Session state changed
+});
+```
+
+### TypeScript Support
+
+```typescript
+// For custom element types in JSX
+import '@mixrpay/merchant-sdk/widget-elements';
+
+// Now TypeScript knows about:
+<mixr-balance data-theme="dark" />
+<mixr-wallet />
+```
+
+---
+
 ## Webhooks
 
 ```typescript
@@ -109,23 +172,20 @@ app.post('/webhooks/mixrpay', (req, res) => {
     return res.status(401).json({ error: 'Invalid signature' });
   }
   
-  // Handle event
+  const { event, amount_usd, user_wallet } = req.body;
+  // Handle: session.created, session.charged, session.revoked, session.expired
+  
   res.json({ received: true });
 });
 ```
 
-## TypeScript
-
-```typescript
-import type { MixrPayOptions, MixrPayment } from '@mixrpay/merchant-sdk';
-
-// Widget element types
-import '@mixrpay/merchant-sdk/widget-elements';
-```
+---
 
 ## Documentation
 
-Full documentation at [mixrpay.com/seller/docs](https://www.mixrpay.com/seller/docs)
+- [Integration Guide](https://www.mixrpay.com/seller/integrate)
+- [API Reference](https://www.mixrpay.com/seller/api-reference)
+- [Widget Docs](https://www.mixrpay.com/seller/widget)
 
 ## License
 

package/dist/index.d.mts

@@ -1,49 +1,4 @@
-import { V as VerifyReceiptOptions, P as PaymentReceipt } from './types-BwiuIaOu.mjs';
-export { M as MixrPayOptions, a as MixrPayPaymentResult, b as PaymentMethod, c as PriceContext } from './types-BwiuIaOu.mjs';
-
-/**
- * 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>;
+export { M as MixrPayOptions, a as MixrPayPaymentResult, P as PaymentMethod, b as PriceContext } from './types-BO8cImOi.mjs';
 
 interface SessionGrant {
     /** Session key ID */
@@ -343,6 +298,47 @@ interface MixrAPI {
    * Make an authenticated fetch request with MixrPay headers
    */
   fetch(url: string, options?: RequestInit & { autoPrompt?: boolean }): Promise<Response>;
+  
+  /** Check and refresh session state from server */
+  checkSession(): Promise<void>;
+  
+  /** Reset prompt limit counters (for auto-prompt functionality) */
+  resetPromptLimit(): void;
+  
+  /** 
+   * Get URL for wallet actions
+   * @param tab - Optional tab to open
+   */
+  getActionUrl(tab?: string): string;
+  
+  /**
+   * Open agent chat in a popup window
+   * @param agentId - The agent ID to chat with
+   * @returns The popup window reference, or null if config is invalid
+   */
+  openAgent(agentId: string): Window | null;
+  
+  /**
+   * Get embeddable URL for agent chat
+   * @param agentId - The agent ID
+   * @param options - Embed options
+   */
+  getAgentEmbedUrl(agentId: string, options?: { embed?: boolean }): string;
+  
+  /**
+   * Verify widget credentials with MixrPay server.
+   * Useful for debugging HMAC or configuration issues.
+   * @param testUserId - Optional test user ID for signature verification
+   */
+  verifyCredentials(testUserId?: string): Promise<{
+    valid: boolean;
+    error?: string;
+    merchant?: {
+      id: string;
+      name: string;
+    };
+    mode?: string;
+  }>;
 }
 
 // =============================================================================
@@ -356,6 +352,10 @@ interface MixrChargeSuccessDetail {
   price: string;
   /** Unique charge ID */
   chargeId?: string;
+  /** Transaction hash if available */
+  txHash?: string;
+  /** New balance after charge in USD */
+  newBalance?: number;
 }
 
 interface MixrChargeErrorDetail {
@@ -388,6 +388,58 @@ interface MixrTransactionDetail {
   amount: number;
 }
 
+interface MixrReadyDetail {
+  /** Whether widget is ready for transactions */
+  ready: boolean;
+  /** List of issues preventing readiness */
+  issues: string[];
+  /** Current balance in USD */
+  balanceUsd: number;
+  /** Current session ID if any */
+  sessionId: string | null;
+  /** Remaining session spending limit */
+  sessionRemaining: number;
+}
+
+interface MixrSessionAuthorizedDetail {
+  /** The newly authorized session ID */
+  sessionId: string;
+  /** Spending limit in USD */
+  spendingLimitUsd: number;
+  /** Session expiration timestamp */
+  expiresAt: string;
+}
+
+interface MixrErrorDetail {
+  /** Error code (e.g., 'INVALID_WIDGET_TOKEN', 'NETWORK_ERROR') */
+  code: string;
+  /** Human-readable error message */
+  message?: string;
+  /** Server error message if from API */
+  serverError?: string;
+  /** Original error message if wrapped */
+  originalError?: string;
+}
+
+interface MixrAuthenticatedDetail {
+  /** User's wallet address */
+  walletAddress: string;
+  /** Privy user ID if available */
+  privyUserId?: string;
+}
+
+interface MixrSessionLimitDetail {
+  /** Remaining session spending limit */
+  remaining: number;
+  /** Required amount for the operation */
+  required: number;
+}
+
+interface MixrThemeChangedDetail {
+  /** Current effective theme */
+  theme: 'dark' | 'light';
+}
+
 // =============================================================================
 // Custom Events Map
 // =============================================================================
@@ -403,12 +455,33 @@ interface MixrTransactionDetail {
  * ```
  */
 interface MixrEventMap {
+  // Charge events
   'mixr:charge-success': CustomEvent<MixrChargeSuccessDetail>;
   'mixr:charge-error': CustomEvent<MixrChargeErrorDetail>;
+  
+  // Balance events
   'mixr:low-balance': CustomEvent<MixrLowBalanceDetail>;
-  'mixr:state-updated': CustomEvent<MixrStateUpdatedDetail>;
   'mixr:funding': CustomEvent<MixrFundingDetail>;
   'mixr:transaction': CustomEvent<MixrTransactionDetail>;
+  
+  // State events
+  'mixr:state-updated': CustomEvent<MixrStateUpdatedDetail>;
+  'mixr:ready': CustomEvent<MixrReadyDetail>;
+  'mixr:theme-changed': CustomEvent<MixrThemeChangedDetail>;
+  
+  // Session events
+  'mixr:session-updated': CustomEvent<MixrSessionState>;
+  'mixr:session-authorized': CustomEvent<MixrSessionAuthorizedDetail>;
+  'mixr:session-error': CustomEvent<{ error: string }>;
+  'mixr:session-limit': CustomEvent<MixrSessionLimitDetail>;
+  
+  // Authentication events
+  'mixr:authenticated': CustomEvent<MixrAuthenticatedDetail>;
+  'mixr:auth-cancelled': CustomEvent<void>;
+  'mixr:disconnected': CustomEvent<void>;
+  
+  // Error events
+  'mixr:error': CustomEvent<MixrErrorDetail>;
 }
 
 // =============================================================================
@@ -454,4 +527,4 @@ declare global {
   }
 }
 
-export { type EnvValidationResult, MIXRPAY_API_URL, PaymentReceipt, type SessionGrant, WIDGET_SCRIPT_URL, getWidgetUrl, logEnvValidation, minorToUsd, usdToMinor, validateEnv, verifyPaymentReceipt, verifySessionWebhook };
+export { type EnvValidationResult, MIXRPAY_API_URL, type SessionGrant, WIDGET_SCRIPT_URL, getWidgetUrl, logEnvValidation, minorToUsd, usdToMinor, validateEnv, verifySessionWebhook };

package/dist/index.d.ts

@@ -1,49 +1,4 @@
-import { V as VerifyReceiptOptions, P as PaymentReceipt } from './types-BwiuIaOu.js';
-export { M as MixrPayOptions, a as MixrPayPaymentResult, b as PaymentMethod, c as PriceContext } from './types-BwiuIaOu.js';
-
-/**
- * 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>;
+export { M as MixrPayOptions, a as MixrPayPaymentResult, P as PaymentMethod, b as PriceContext } from './types-BO8cImOi.js';
 
 interface SessionGrant {
     /** Session key ID */
@@ -343,6 +298,47 @@ interface MixrAPI {
    * Make an authenticated fetch request with MixrPay headers
    */
   fetch(url: string, options?: RequestInit & { autoPrompt?: boolean }): Promise<Response>;
+  
+  /** Check and refresh session state from server */
+  checkSession(): Promise<void>;
+  
+  /** Reset prompt limit counters (for auto-prompt functionality) */
+  resetPromptLimit(): void;
+  
+  /** 
+   * Get URL for wallet actions
+   * @param tab - Optional tab to open
+   */
+  getActionUrl(tab?: string): string;
+  
+  /**
+   * Open agent chat in a popup window
+   * @param agentId - The agent ID to chat with
+   * @returns The popup window reference, or null if config is invalid
+   */
+  openAgent(agentId: string): Window | null;
+  
+  /**
+   * Get embeddable URL for agent chat
+   * @param agentId - The agent ID
+   * @param options - Embed options
+   */
+  getAgentEmbedUrl(agentId: string, options?: { embed?: boolean }): string;
+  
+  /**
+   * Verify widget credentials with MixrPay server.
+   * Useful for debugging HMAC or configuration issues.
+   * @param testUserId - Optional test user ID for signature verification
+   */
+  verifyCredentials(testUserId?: string): Promise<{
+    valid: boolean;
+    error?: string;
+    merchant?: {
+      id: string;
+      name: string;
+    };
+    mode?: string;
+  }>;
 }
 
 // =============================================================================
@@ -356,6 +352,10 @@ interface MixrChargeSuccessDetail {
   price: string;
   /** Unique charge ID */
   chargeId?: string;
+  /** Transaction hash if available */
+  txHash?: string;
+  /** New balance after charge in USD */
+  newBalance?: number;
 }
 
 interface MixrChargeErrorDetail {
@@ -388,6 +388,58 @@ interface MixrTransactionDetail {
   amount: number;
 }
 
+interface MixrReadyDetail {
+  /** Whether widget is ready for transactions */
+  ready: boolean;
+  /** List of issues preventing readiness */
+  issues: string[];
+  /** Current balance in USD */
+  balanceUsd: number;
+  /** Current session ID if any */
+  sessionId: string | null;
+  /** Remaining session spending limit */
+  sessionRemaining: number;
+}
+
+interface MixrSessionAuthorizedDetail {
+  /** The newly authorized session ID */
+  sessionId: string;
+  /** Spending limit in USD */
+  spendingLimitUsd: number;
+  /** Session expiration timestamp */
+  expiresAt: string;
+}
+
+interface MixrErrorDetail {
+  /** Error code (e.g., 'INVALID_WIDGET_TOKEN', 'NETWORK_ERROR') */
+  code: string;
+  /** Human-readable error message */
+  message?: string;
+  /** Server error message if from API */
+  serverError?: string;
+  /** Original error message if wrapped */
+  originalError?: string;
+}
+
+interface MixrAuthenticatedDetail {
+  /** User's wallet address */
+  walletAddress: string;
+  /** Privy user ID if available */
+  privyUserId?: string;
+}
+
+interface MixrSessionLimitDetail {
+  /** Remaining session spending limit */
+  remaining: number;
+  /** Required amount for the operation */
+  required: number;
+}
+
+interface MixrThemeChangedDetail {
+  /** Current effective theme */
+  theme: 'dark' | 'light';
+}
+
 // =============================================================================
 // Custom Events Map
 // =============================================================================
@@ -403,12 +455,33 @@ interface MixrTransactionDetail {
  * ```
  */
 interface MixrEventMap {
+  // Charge events
   'mixr:charge-success': CustomEvent<MixrChargeSuccessDetail>;
   'mixr:charge-error': CustomEvent<MixrChargeErrorDetail>;
+  
+  // Balance events
   'mixr:low-balance': CustomEvent<MixrLowBalanceDetail>;
-  'mixr:state-updated': CustomEvent<MixrStateUpdatedDetail>;
   'mixr:funding': CustomEvent<MixrFundingDetail>;
   'mixr:transaction': CustomEvent<MixrTransactionDetail>;
+  
+  // State events
+  'mixr:state-updated': CustomEvent<MixrStateUpdatedDetail>;
+  'mixr:ready': CustomEvent<MixrReadyDetail>;
+  'mixr:theme-changed': CustomEvent<MixrThemeChangedDetail>;
+  
+  // Session events
+  'mixr:session-updated': CustomEvent<MixrSessionState>;
+  'mixr:session-authorized': CustomEvent<MixrSessionAuthorizedDetail>;
+  'mixr:session-error': CustomEvent<{ error: string }>;
+  'mixr:session-limit': CustomEvent<MixrSessionLimitDetail>;
+  
+  // Authentication events
+  'mixr:authenticated': CustomEvent<MixrAuthenticatedDetail>;
+  'mixr:auth-cancelled': CustomEvent<void>;
+  'mixr:disconnected': CustomEvent<void>;
+  
+  // Error events
+  'mixr:error': CustomEvent<MixrErrorDetail>;
 }
 
 // =============================================================================
@@ -454,4 +527,4 @@ declare global {
   }
 }
 
-export { type EnvValidationResult, MIXRPAY_API_URL, PaymentReceipt, type SessionGrant, WIDGET_SCRIPT_URL, getWidgetUrl, logEnvValidation, minorToUsd, usdToMinor, validateEnv, verifyPaymentReceipt, verifySessionWebhook };
+export { type EnvValidationResult, MIXRPAY_API_URL, type SessionGrant, WIDGET_SCRIPT_URL, getWidgetUrl, logEnvValidation, minorToUsd, usdToMinor, validateEnv, verifySessionWebhook };