@zauthx402/sdk 0.1.9 → 0.1.12

package/README.md

@@ -43,9 +43,11 @@ app.get('/api/paid', ...);
 
 - **Non-invasive** - Observes requests/responses without interfering with payments
 - **Implementation agnostic** - Works with any x402 implementation (V1/V2)
+- **Multi-network** - Supports EVM (Base, Ethereum) and Solana out of the box
 - **Full telemetry** - Request params, response bodies, timing, payment details
 - **Response validation** - Detect empty, invalid, or error responses
 - **Auto-refunds** (optional) - Trigger refunds when responses are bad
+- **Per-endpoint config** - Customize validation and refund behavior per route
 
 ## How It Works
 
@@ -76,6 +78,8 @@ The SDK:
 
 ## Configuration
 
+### Full Example
+
 ```typescript
 import { createZauthMiddleware } from '@zauthx402/sdk/middleware';
 
@@ -83,43 +87,54 @@ app.use(createZauthMiddleware({
   apiKey: 'your-api-key',
   mode: 'provider',
 
-  // Validation rules
+  // Route filtering
+  includeRoutes: ['/api/.*'],           // Only monitor these routes
+  excludeRoutes: ['/health'],           // Skip these routes
+
+  // Response validation
   validation: {
-    requiredFields: ['data'],           // Must have these fields
-    errorFields: ['error', 'errors'],   // These indicate errors
-    minResponseSize: 10,                // Minimum response size
+    requiredFields: ['data'],           // Response must have these fields
+    errorFields: ['error', 'errors'],   // These fields indicate errors
+    minResponseSize: 10,                // Minimum response size in bytes
     rejectEmptyCollections: true,       // Reject empty arrays/objects
   },
 
-  // Route filtering
-  includeRoutes: ['/api/.*'],           // Only monitor these
-  excludeRoutes: ['/health'],           // Skip these
-
-  // Telemetry options
+  // Telemetry
   telemetry: {
     includeRequestBody: true,
     includeResponseBody: true,
-    maxBodySize: 10000,
-    redactHeaders: ['authorization'],
+    maxBodySize: 10000,                 // Truncate bodies larger than this
+    redactHeaders: ['authorization'],   // Strip sensitive headers
     redactFields: ['password', 'secret'],
-    sampleRate: 1.0,                    // 1.0 = all, 0.1 = 10%
+    sampleRate: 1.0,                    // 1.0 = all events, 0.1 = 10%
   },
 
-  // Auto-refunds (optional)
+  // Auto-refunds (see Refunds section below)
   refund: {
     enabled: true,
     privateKey: process.env.ZAUTH_REFUND_PRIVATE_KEY,
-    network: 'base',
-    maxRefundUsdc: '1.00',
+    solanaPrivateKey: process.env.ZAUTH_SOLANA_PRIVATE_KEY,
+    maxRefundUsd: 1.00,
+    dailyCapUsd: 50.00,
+    monthlyCapUsd: 500.00,
   },
 
   debug: true,
 }));
 ```
 
+### Environment Variables
+
+| Variable | Description | Required |
+|---|---|---|
+| `ZAUTH_API_KEY` | Your zauthx402 API key | Yes |
+| `ZAUTH_REFUND_PRIVATE_KEY` | EVM hot wallet private key (hex, `0x...`) | If refunds enabled on EVM |
+| `ZAUTH_SOLANA_PRIVATE_KEY` | Solana hot wallet private key (base58) | If refunds enabled on Solana |
+| `ZAUTH_API_ENDPOINT` | Custom API endpoint (default: `https://back.zauthx402.com`) | No |
+
 ## Auto-Refunds
 
-When enabled, the SDK can automatically refund users who receive bad responses:
+When enabled, the SDK automatically refunds users who receive bad responses.
 
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'actorBkg': '#1a1a1a', 'actorTextColor': '#fff', 'actorLineColor': '#666', 'signalColor': '#666', 'signalTextColor': '#fff', 'labelBoxBkgColor': '#1a1a1a', 'labelTextColor': '#fff', 'altSectionBkgColor': '#2d2d2d' }}}%%
@@ -143,21 +158,187 @@ sequenceDiagram
     end
 ```
 
-**Requirements:**
-- `viem` package installed
-- Hot wallet private key configured
-- Network matches endpoint network
+### Refund Triggers
+
+The SDK can trigger refunds based on these conditions:
+
+```typescript
+refund: {
+  enabled: true,
+  triggers: {
+    serverError: true,       // 5xx status codes
+    timeout: true,           // Request timeouts
+    emptyResponse: true,     // Empty or meaningless response body
+    schemaValidation: false, // Response doesn't match expected schema
+    minMeaningfulness: 0.3,  // AI-scored meaningfulness threshold (0-1)
+  },
+}
+```
+
+### EVM-Only Setup (Base)
+
+If your endpoint only accepts EVM payments:
+
+```bash
+npm install viem
+```
+
+```typescript
+app.use(zauthProvider('your-api-key', {
+  refund: {
+    enabled: true,
+    privateKey: process.env.ZAUTH_REFUND_PRIVATE_KEY,
+    network: 'base',
+    maxRefundUsd: 1.00,
+  },
+}));
+```
+
+```bash
+# .env
+ZAUTH_REFUND_PRIVATE_KEY=0xYourEvmPrivateKeyHex
+```
+
+### Solana-Only Setup
+
+If your endpoint only accepts Solana payments:
+
+```typescript
+app.use(zauthProvider('your-api-key', {
+  refund: {
+    enabled: true,
+    solanaPrivateKey: process.env.ZAUTH_SOLANA_PRIVATE_KEY,
+    network: 'solana',
+    maxRefundUsd: 1.00,
+  },
+}));
+```
+
+```bash
+# .env
+ZAUTH_SOLANA_PRIVATE_KEY=YourSolanaPrivateKeyBase58
+```
+
+### Dual-Network Setup (EVM + Solana)
+
+If your endpoint accepts both EVM and Solana payments (x402 V2), provide both keys. The SDK automatically routes refunds to the correct network based on how the user originally paid.
 
 ```bash
 npm install viem
-export ZAUTH_REFUND_PRIVATE_KEY=your-hot-wallet-key
+```
+
+```typescript
+app.use(zauthProvider('your-api-key', {
+  refund: {
+    enabled: true,
+    privateKey: process.env.ZAUTH_REFUND_PRIVATE_KEY,
+    solanaPrivateKey: process.env.ZAUTH_SOLANA_PRIVATE_KEY,
+    maxRefundUsd: 1.00,
+    dailyCapUsd: 50.00,
+  },
+}));
+```
+
+```bash
+# .env
+ZAUTH_REFUND_PRIVATE_KEY=0xYourEvmPrivateKeyHex
+ZAUTH_SOLANA_PRIVATE_KEY=YourSolanaPrivateKeyBase58
+```
+
+If a user pays via Base and gets a bad response, the refund goes out on Base using your EVM key. If they pay via Solana, it goes out on Solana using your Solana key. If you only configure one key, refunds on the other network will fail gracefully with a log message.
+
+### Safety Limits
+
+```typescript
+refund: {
+  enabled: true,
+  maxRefundUsd: 1.00,      // Max per single refund
+  dailyCapUsd: 50.00,      // Max total refunds per day
+  monthlyCapUsd: 500.00,   // Max total refunds per month
+},
+```
+
+### Refund Callbacks
+
+```typescript
+refund: {
+  enabled: true,
+  onRefund: (refund) => {
+    console.log(`Refunded $${refund.amountUsd} to ${refund.recipient} on ${refund.network}`);
+    console.log(`Tx: ${refund.txHash}`);
+  },
+  onRefundError: (error) => {
+    console.error(`Refund failed for ${error.url}: ${error.error}`);
+  },
+},
+```
+
+## Per-Endpoint Configuration
+
+You can customize validation and refund behavior for individual endpoints using `expectedResponse` and per-endpoint overrides.
+
+### `expectedResponse`
+
+The `expectedResponse` field is a plain-text description of what a valid response looks like. It's used for AI-powered validation — the SDK scores how "meaningful" a response is relative to what was expected.
+
+```typescript
+app.use(createZauthMiddleware({
+  apiKey: 'your-api-key',
+  mode: 'provider',
+
+  refund: {
+    enabled: true,
+    privateKey: process.env.ZAUTH_REFUND_PRIVATE_KEY,
+    solanaPrivateKey: process.env.ZAUTH_SOLANA_PRIVATE_KEY,
+    maxRefundUsd: 1.00,
+
+    endpoints: {
+      '/api/weather': {
+        expectedResponse: 'JSON object with temperature, humidity, wind speed, and forecast for the requested location',
+        maxRefundUsd: 0.50,
+        triggers: {
+          emptyResponse: true,
+          minMeaningfulness: 0.5,
+        },
+      },
+      '/api/translate': {
+        expectedResponse: 'JSON with translated_text field containing the translation in the target language',
+        maxRefundUsd: 0.10,
+      },
+      '/api/expensive-report': {
+        maxRefundUsd: 5.00,       // Higher cap for expensive endpoint
+        enabled: true,
+      },
+      '/api/beta-endpoint': {
+        enabled: false,            // Disable refunds for this endpoint
+      },
+    },
+  },
+}));
+```
+
+### Custom Refund Logic
+
+For full control, use `shouldRefund` to decide per-request:
+
+```typescript
+endpoints: {
+  '/api/data': {
+    shouldRefund: (response, statusCode, validationResult) => {
+      // Only refund if the response is truly empty
+      if (statusCode >= 500) return true;
+      if (!response || Object.keys(response).length === 0) return true;
+      return false;
+    },
+  },
+},
 ```
 
 ## Examples
 
 See the `/examples` directory:
 
-- `provider-express/` - Express server with monitoring
+- `provider-express/` - Express server with monitoring and refunds
 
 ## Local Development
 
@@ -190,6 +371,16 @@ export { RefundHandler, createRefundHandler } from '@zauthx402/sdk';
 export * from '@zauthx402/sdk'; // All types
 ```
 
+### Supported Networks
+
+| Network | Value | Key Config |
+|---|---|---|
+| Base (mainnet) | `'base'` | `privateKey` |
+| Base Sepolia (testnet) | `'base-sepolia'` | `privateKey` |
+| Solana (mainnet) | `'solana'` | `solanaPrivateKey` |
+| Solana Devnet | `'solana-devnet'` | `solanaPrivateKey` |
+| Solana Testnet | `'solana-testnet'` | `solanaPrivateKey` |
+
 ## Get Your API Key
 
 Sign up at [zauthx402.com](https://zauthx402.com) to get your API key and access the monitoring dashboard.

package/dist/index.js

@@ -4600,7 +4600,8 @@ function decodePaymentHeader(paymentHeader) {
     if (!payer && parsed.payload?.transaction) {
       payer = extractSolanaFeePayer(parsed.payload.transaction);
     }
-    const amount = parsed.payload?.authorization?.value || // x402 V2
+    const amount = parsed.payload?.authorization?.value || // x402 V2 EVM
+    parsed.accepted?.amount || // x402 V2 (accepted payment requirements)
     parsed.amount || parsed.payload?.amount || null;
     let network = parsed.payload?.authorization?.network || // x402 V2 EVM
     parsed.network || parsed.payload?.network || null;
@@ -5678,11 +5679,11 @@ function createZauthMiddleware(options) {
       let paymentResponse = reqPaymentInfo || headerPaymentResponse;
       if (facilitatorResponse?.payer) {
         const defaultAmount = options.defaultPaymentAmountUsdc;
+        const decodedAmountUsdc = decodedPayment?.amount ? baseUnitsToUsdc(decodedPayment.amount) : null;
         paymentResponse = {
           transactionHash: facilitatorResponse.transaction || null,
-          amountPaid: null,
-          // Amount not in facilitator response
-          amountPaidUsdc: defaultAmount || null,
+          amountPaid: decodedPayment?.amount || null,
+          amountPaidUsdc: decodedAmountUsdc || defaultAmount || null,
           network: facilitatorResponse.network || "base",
           payTo: null,
           asset: "USDC",