@alleyboss/micropay-solana-x402-paywall 3.3.15 → 3.5.0

package/README.md

@@ -21,6 +21,7 @@ npm install @alleyboss/micropay-solana-x402-paywall @x402/core @x402/svm @solana
 
 | Feature | Description | Status |
 |---------|-------------|--------|
+| 🔥 **x402Fetch** | Drop-in `fetch()` replacement with auto-payment | ✅ **NEW in v3.4** |
 | 💰 **SOL & USDC** | Native SOL and SPL tokens (USDC, USDT) | ✅ Verified by `@x402/svm` |
 | 🔐 **x402 Protocol** | Full HTTP 402 compliance | ✅ Powered by `@x402/core` |
 | 🌐 **PayAI Format** | Multi-chain payment format support | ✅ Built-in |
@@ -33,6 +34,96 @@ npm install @alleyboss/micropay-solana-x402-paywall @x402/core @x402/svm @solana
 | 📦 **Versioned Tx** | v0 Transaction support | ✅ Native (x402 SDK) |
 | 🌳 **Tree-Shakeable** | Modular exports | ✅ Built-in |
 
+## 🔥 x402Fetch — The Killer Feature (NEW in v3.4)
+
+Replace `fetch()` with `x402Fetch()` and **402 responses are handled automatically**.
+
+```typescript
+import { createX402Fetch } from '@alleyboss/micropay-solana-x402-paywall/fetch';
+import { useWallet } from '@solana/wallet-adapter-react';
+
+// Create configured fetch instance
+const x402Fetch = createX402Fetch({
+  wallet: useWallet(),           // Browser wallet adapter
+  network: 'mainnet-beta',
+  onPaymentRequired: async (req) => {
+    return confirm(`Pay ${req.amount} lamports to ${req.payTo}?`);
+  },
+});
+
+// Use it like fetch — that's it!
+const response = await x402Fetch('https://api.example.com/premium-data');
+const data = await response.json();
+```
+
+### Server-Side / AI Agent Usage
+
+```typescript
+import { createX402Fetch } from '@alleyboss/micropay-solana-x402-paywall/fetch';
+import { Keypair } from '@solana/web3.js';
+import bs58 from 'bs58';
+
+const agentKeypair = Keypair.fromSecretKey(
+  bs58.decode(process.env.AGENT_PRIVATE_KEY!)
+);
+
+const x402Fetch = createX402Fetch({
+  wallet: agentKeypair,  // Server-side keypair
+  network: 'mainnet-beta',
+});
+
+// Autonomous payment — no user interaction needed
+const response = await x402Fetch('https://api.example.com/ai-data');
+```
+
+### Error Handling
+
+```typescript
+import { X402PaymentError, isUserRejection } from '@alleyboss/micropay-solana-x402-paywall/fetch';
+
+try {
+  await x402Fetch('/api/premium');
+} catch (error) {
+  if (isUserRejection(error)) {
+    console.log('User declined payment');
+  } else if (error instanceof X402PaymentError) {
+    console.log('Payment failed:', error.code);
+    // Codes: USER_REJECTED, INSUFFICIENT_BALANCE, TRANSACTION_FAILED, etc.
+  }
+}
+```
+
+### Security Configuration (v3.4.1)
+
+Protect your wallet from malicious 402 responses:
+
+```typescript
+const x402Fetch = createX402Fetch({
+  wallet,
+  network: 'mainnet-beta',
+
+  // 🔒 Critical: Maximum payment per request (prevents wallet drain)
+  maxPaymentPerRequest: BigInt(10_000_000), // Max 0.01 SOL
+
+  // 🔒 Critical: Whitelist of allowed recipients (prevents phishing)
+  allowedRecipients: ['7fPjN...', 'ABC123...'],
+
+  // ⚡ UX: Transaction speed (processed=fast, finalized=safe)
+  commitment: 'confirmed', // 'processed' | 'confirmed' | 'finalized'
+
+  // 🛡️ Rate limiting (prevents infinite loops)
+  rateLimit: {
+    maxPayments: 10,      // Max 10 payments
+    windowMs: 60_000,     // Per minute
+  },
+});
+```
+
+**Security Error Codes:**
+- `AMOUNT_EXCEEDS_LIMIT` — Payment blocked: amount exceeds `maxPaymentPerRequest`
+- `RECIPIENT_NOT_ALLOWED` — Payment blocked: recipient not in whitelist
+- `RATE_LIMIT_EXCEEDED` — Payment blocked: too many payments in time window
+
 ## 📦 Quick Example (Express.js)
 
 ```typescript
@@ -92,6 +183,9 @@ export const GET = withMicropay(handler, {
 Import only what you need:
 
 ```typescript
+// 🔥 x402Fetch - Drop-in fetch replacement (NEW!)
+import { createX402Fetch } from '@alleyboss/micropay-solana-x402-paywall/fetch';
+
 // Express Middleware
 import { x402Middleware } from '@alleyboss/micropay-solana-x402-paywall/express';
 

package/dist/fetch/index.cjs

@@ -0,0 +1,421 @@
+'use strict';
+
+var web3_js = require('@solana/web3.js');
+
+// src/fetch/x402Fetch.ts
+
+// src/fetch/types.ts
+var X402ErrorCode = {
+  /** User rejected the payment */
+  USER_REJECTED: "USER_REJECTED",
+  /** Insufficient wallet balance */
+  INSUFFICIENT_BALANCE: "INSUFFICIENT_BALANCE",
+  /** Transaction failed on-chain */
+  TRANSACTION_FAILED: "TRANSACTION_FAILED",
+  /** Payment verification failed */
+  VERIFICATION_FAILED: "VERIFICATION_FAILED",
+  /** Network/RPC error */
+  NETWORK_ERROR: "NETWORK_ERROR",
+  /** Invalid 402 response format */
+  INVALID_402_RESPONSE: "INVALID_402_RESPONSE",
+  /** Payment timeout */
+  TIMEOUT: "TIMEOUT",
+  /** Wallet not connected */
+  WALLET_NOT_CONNECTED: "WALLET_NOT_CONNECTED",
+  /** Payment amount exceeds maxPaymentPerRequest */
+  AMOUNT_EXCEEDS_LIMIT: "AMOUNT_EXCEEDS_LIMIT",
+  /** Recipient address not in allowedRecipients whitelist */
+  RECIPIENT_NOT_ALLOWED: "RECIPIENT_NOT_ALLOWED",
+  /** Rate limit exceeded */
+  RATE_LIMIT_EXCEEDED: "RATE_LIMIT_EXCEEDED"
+};
+
+// src/fetch/errors.ts
+var X402PaymentError = class _X402PaymentError extends Error {
+  constructor(message, code, requirements, cause) {
+    super(message);
+    this.code = code;
+    this.requirements = requirements;
+    this.cause = cause;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _X402PaymentError);
+    }
+  }
+  name = "X402PaymentError";
+  /**
+   * Check if error is retryable
+   */
+  get isRetryable() {
+    const retryableCodes = [
+      X402ErrorCode.NETWORK_ERROR,
+      X402ErrorCode.TIMEOUT,
+      X402ErrorCode.TRANSACTION_FAILED
+    ];
+    return retryableCodes.includes(this.code);
+  }
+  /**
+   * Convert to JSON-serializable object
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      code: this.code,
+      requirements: this.requirements,
+      isRetryable: this.isRetryable
+    };
+  }
+};
+function userRejectedError(requirements) {
+  return new X402PaymentError(
+    "User rejected the payment request",
+    X402ErrorCode.USER_REJECTED,
+    requirements
+  );
+}
+function insufficientBalanceError(requirements, balance) {
+  return new X402PaymentError(
+    `Insufficient balance: have ${balance} lamports, need ${requirements.amount}`,
+    X402ErrorCode.INSUFFICIENT_BALANCE,
+    requirements
+  );
+}
+function transactionFailedError(requirements, cause) {
+  return new X402PaymentError(
+    `Transaction failed: ${cause?.message ?? "Unknown error"}`,
+    X402ErrorCode.TRANSACTION_FAILED,
+    requirements,
+    cause
+  );
+}
+function verificationFailedError(requirements, reason) {
+  return new X402PaymentError(
+    `Payment verification failed: ${reason ?? "Unknown reason"}`,
+    X402ErrorCode.VERIFICATION_FAILED,
+    requirements
+  );
+}
+function networkError(cause) {
+  return new X402PaymentError(
+    `Network error: ${cause?.message ?? "Connection failed"}`,
+    X402ErrorCode.NETWORK_ERROR,
+    void 0,
+    cause
+  );
+}
+function invalid402ResponseError(details) {
+  return new X402PaymentError(
+    `Invalid 402 response: ${details ?? "Missing or malformed payment requirements"}`,
+    X402ErrorCode.INVALID_402_RESPONSE
+  );
+}
+function timeoutError(requirements) {
+  return new X402PaymentError(
+    "Payment flow timed out",
+    X402ErrorCode.TIMEOUT,
+    requirements
+  );
+}
+function walletNotConnectedError() {
+  return new X402PaymentError(
+    "Wallet is not connected",
+    X402ErrorCode.WALLET_NOT_CONNECTED
+  );
+}
+function amountExceedsLimitError(requirements, limit) {
+  return new X402PaymentError(
+    `Payment amount ${requirements.amount} exceeds limit of ${limit} lamports`,
+    X402ErrorCode.AMOUNT_EXCEEDS_LIMIT,
+    requirements
+  );
+}
+function recipientNotAllowedError(requirements, recipient) {
+  return new X402PaymentError(
+    `Recipient ${recipient} is not in the allowed recipients list`,
+    X402ErrorCode.RECIPIENT_NOT_ALLOWED,
+    requirements
+  );
+}
+function rateLimitExceededError(limit, windowMs) {
+  return new X402PaymentError(
+    `Rate limit exceeded: max ${limit} payments per ${windowMs / 1e3}s`,
+    X402ErrorCode.RATE_LIMIT_EXCEEDED
+  );
+}
+function isX402PaymentError(error) {
+  return error instanceof X402PaymentError;
+}
+function isUserRejection(error) {
+  return isX402PaymentError(error) && error.code === X402ErrorCode.USER_REJECTED;
+}
+
+// src/shared/constants.ts
+var RPC_ENDPOINTS = {
+  "mainnet-beta": "https://api.mainnet-beta.solana.com",
+  "devnet": "https://api.devnet.solana.com",
+  "testnet": "https://api.testnet.solana.com"
+};
+var DEFAULT_CONFIRMATION_TIMEOUT = 3e4;
+var DEFAULT_MAX_RETRIES = 3;
+var DEFAULT_RATE_LIMIT_WINDOW_MS = 6e4;
+var DEFAULT_RATE_LIMIT_MAX_PAYMENTS = 10;
+
+// src/fetch/x402Fetch.ts
+function isKeypair(wallet) {
+  return wallet instanceof web3_js.Keypair;
+}
+function isWalletConnected(wallet) {
+  if (isKeypair(wallet)) return true;
+  return wallet.connected && wallet.publicKey != null;
+}
+function getPublicKey(wallet) {
+  if (isKeypair(wallet)) return wallet.publicKey;
+  if (!wallet.publicKey) throw walletNotConnectedError();
+  return wallet.publicKey;
+}
+function parse402Response(response) {
+  const x402Header = response.headers.get("X-Payment-Requirements");
+  if (x402Header) {
+    try {
+      const parsed = JSON.parse(x402Header);
+      return {
+        payTo: parsed.payTo ?? parsed.recipient,
+        amount: String(parsed.amount),
+        asset: parsed.asset ?? "SOL",
+        network: parsed.network ?? "solana-mainnet",
+        description: parsed.description,
+        resource: parsed.resource,
+        maxAge: parsed.maxAge
+      };
+    } catch {
+      throw invalid402ResponseError("Invalid X-Payment-Requirements header");
+    }
+  }
+  const wwwAuth = response.headers.get("WWW-Authenticate");
+  if (wwwAuth?.startsWith("X402")) {
+    try {
+      const base64Part = wwwAuth.slice(5).trim();
+      const jsonStr = atob(base64Part);
+      const parsed = JSON.parse(jsonStr);
+      return {
+        payTo: parsed.payTo ?? parsed.recipient,
+        amount: String(parsed.amount),
+        asset: parsed.asset ?? "SOL",
+        network: parsed.network ?? "solana-mainnet",
+        description: parsed.description,
+        resource: parsed.resource,
+        maxAge: parsed.maxAge
+      };
+    } catch {
+      throw invalid402ResponseError("Invalid WWW-Authenticate header");
+    }
+  }
+  throw invalid402ResponseError("No payment requirements found in 402 response");
+}
+function buildPaymentHeader(signature) {
+  const payload = {
+    x402Version: 2,
+    scheme: "exact",
+    payload: { signature }
+  };
+  return `X402 ${btoa(JSON.stringify(payload))}`;
+}
+function createX402Fetch(config) {
+  const {
+    wallet,
+    network = "mainnet-beta",
+    connection: providedConnection,
+    facilitatorUrl: _facilitatorUrl,
+    // Reserved for future facilitator integration
+    onPaymentRequired,
+    onPaymentSuccess,
+    onPaymentError,
+    priorityFee,
+    maxRetries = DEFAULT_MAX_RETRIES,
+    timeout = DEFAULT_CONFIRMATION_TIMEOUT,
+    // Security options
+    maxPaymentPerRequest,
+    allowedRecipients,
+    // UX options
+    commitment = "confirmed",
+    rateLimit
+  } = config;
+  const paymentTimestamps = [];
+  const rateLimitMax = rateLimit?.maxPayments ?? DEFAULT_RATE_LIMIT_MAX_PAYMENTS;
+  const rateLimitWindow = rateLimit?.windowMs ?? DEFAULT_RATE_LIMIT_WINDOW_MS;
+  function checkRateLimit() {
+    const now = Date.now();
+    while (paymentTimestamps.length > 0 && paymentTimestamps[0] < now - rateLimitWindow) {
+      paymentTimestamps.shift();
+    }
+    if (paymentTimestamps.length >= rateLimitMax) {
+      throw rateLimitExceededError(rateLimitMax, rateLimitWindow);
+    }
+  }
+  function recordPayment() {
+    paymentTimestamps.push(Date.now());
+  }
+  function validateSecurityRequirements(requirements) {
+    const amountLamports = BigInt(requirements.amount);
+    if (maxPaymentPerRequest !== void 0 && amountLamports > maxPaymentPerRequest) {
+      throw amountExceedsLimitError(requirements, maxPaymentPerRequest);
+    }
+    if (allowedRecipients !== void 0 && allowedRecipients.length > 0) {
+      if (!allowedRecipients.includes(requirements.payTo)) {
+        throw recipientNotAllowedError(requirements, requirements.payTo);
+      }
+    }
+  }
+  const connection = providedConnection ?? new web3_js.Connection(RPC_ENDPOINTS[network], {
+    commitment
+  });
+  async function executePayment(requirements) {
+    const payer = getPublicKey(wallet);
+    const recipient = new web3_js.PublicKey(requirements.payTo);
+    const amountLamports = BigInt(requirements.amount);
+    const balance = await connection.getBalance(payer);
+    if (BigInt(balance) < amountLamports) {
+      throw insufficientBalanceError(requirements, BigInt(balance));
+    }
+    const instructions = [];
+    if (priorityFee?.enabled) {
+      instructions.push(
+        web3_js.ComputeBudgetProgram.setComputeUnitPrice({
+          microLamports: priorityFee.microLamports ?? 5e3
+        })
+      );
+    }
+    instructions.push(
+      web3_js.SystemProgram.transfer({
+        fromPubkey: payer,
+        toPubkey: recipient,
+        lamports: amountLamports
+      })
+    );
+    const { blockhash, lastValidBlockHeight } = await connection.getLatestBlockhash();
+    const messageV0 = new web3_js.TransactionMessage({
+      payerKey: payer,
+      recentBlockhash: blockhash,
+      instructions
+    }).compileToV0Message();
+    const tx = new web3_js.VersionedTransaction(messageV0);
+    if (isKeypair(wallet)) {
+      tx.sign([wallet]);
+    } else {
+      const signerWallet = wallet;
+      if (!signerWallet.signTransaction) {
+        throw new X402PaymentError(
+          "Wallet does not support transaction signing. Use a SignerWalletAdapter.",
+          "WALLET_NOT_CONNECTED"
+        );
+      }
+      const signedTx = await signerWallet.signTransaction(tx);
+      if (signedTx.signatures[0]) {
+        tx.signatures[0] = signedTx.signatures[0];
+      }
+    }
+    const signature = await connection.sendTransaction(tx, {
+      maxRetries
+    });
+    await connection.confirmTransaction({
+      signature,
+      blockhash,
+      lastValidBlockHeight
+    }, commitment);
+    return signature;
+  }
+  async function x402Fetch(input, init) {
+    const { skipPayment, paymentOverride, ...fetchInit } = init ?? {};
+    let response;
+    try {
+      response = await fetch(input, fetchInit);
+    } catch (error) {
+      throw networkError(error instanceof Error ? error : void 0);
+    }
+    if (response.status !== 402) {
+      return response;
+    }
+    if (skipPayment) {
+      return response;
+    }
+    if (!isWalletConnected(wallet)) {
+      throw walletNotConnectedError();
+    }
+    let requirements;
+    try {
+      requirements = parse402Response(response);
+      if (paymentOverride) {
+        requirements = { ...requirements, ...paymentOverride };
+      }
+    } catch (error) {
+      if (error instanceof X402PaymentError) throw error;
+      throw invalid402ResponseError(error instanceof Error ? error.message : void 0);
+    }
+    validateSecurityRequirements(requirements);
+    checkRateLimit();
+    if (onPaymentRequired) {
+      const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+      const shouldProceed = await onPaymentRequired(requirements, url);
+      if (!shouldProceed) {
+        throw userRejectedError(requirements);
+      }
+    }
+    let signature;
+    try {
+      const paymentPromise = executePayment(requirements);
+      const timeoutPromise = new Promise((_, reject) => {
+        setTimeout(() => reject(timeoutError(requirements)), timeout);
+      });
+      signature = await Promise.race([paymentPromise, timeoutPromise]);
+      recordPayment();
+      if (onPaymentSuccess) {
+        await onPaymentSuccess(signature, requirements);
+      }
+    } catch (error) {
+      if (error instanceof X402PaymentError) {
+        if (onPaymentError) {
+          await onPaymentError(error, requirements);
+        }
+        throw error;
+      }
+      const wrappedError = transactionFailedError(
+        requirements,
+        error instanceof Error ? error : void 0
+      );
+      if (onPaymentError) {
+        await onPaymentError(wrappedError, requirements);
+      }
+      throw wrappedError;
+    }
+    const retryHeaders = new Headers(fetchInit?.headers);
+    retryHeaders.set("Authorization", buildPaymentHeader(signature));
+    try {
+      return await fetch(input, {
+        ...fetchInit,
+        headers: retryHeaders
+      });
+    } catch (error) {
+      throw networkError(error instanceof Error ? error : void 0);
+    }
+  }
+  return x402Fetch;
+}
+
+exports.X402ErrorCode = X402ErrorCode;
+exports.X402PaymentError = X402PaymentError;
+exports.amountExceedsLimitError = amountExceedsLimitError;
+exports.buildPaymentHeader = buildPaymentHeader;
+exports.createX402Fetch = createX402Fetch;
+exports.insufficientBalanceError = insufficientBalanceError;
+exports.invalid402ResponseError = invalid402ResponseError;
+exports.isUserRejection = isUserRejection;
+exports.isX402PaymentError = isX402PaymentError;
+exports.networkError = networkError;
+exports.parsePaymentRequirements = parse402Response;
+exports.rateLimitExceededError = rateLimitExceededError;
+exports.recipientNotAllowedError = recipientNotAllowedError;
+exports.timeoutError = timeoutError;
+exports.transactionFailedError = transactionFailedError;
+exports.userRejectedError = userRejectedError;
+exports.verificationFailedError = verificationFailedError;
+exports.walletNotConnectedError = walletNotConnectedError;