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

package/dist/fetch/index.js

@@ -0,0 +1,402 @@
+import { Connection, PublicKey, ComputeBudgetProgram, SystemProgram, TransactionMessage, VersionedTransaction, Keypair } from '@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 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 Connection(RPC_ENDPOINTS[network], {
+    commitment
+  });
+  async function executePayment(requirements) {
+    const payer = getPublicKey(wallet);
+    const recipient = new 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(
+        ComputeBudgetProgram.setComputeUnitPrice({
+          microLamports: priorityFee.microLamports ?? 5e3
+        })
+      );
+    }
+    instructions.push(
+      SystemProgram.transfer({
+        fromPubkey: payer,
+        toPubkey: recipient,
+        lamports: amountLamports
+      })
+    );
+    const { blockhash, lastValidBlockHeight } = await connection.getLatestBlockhash();
+    const messageV0 = new TransactionMessage({
+      payerKey: payer,
+      recentBlockhash: blockhash,
+      instructions
+    }).compileToV0Message();
+    const tx = new 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;
+}
+
+export { X402ErrorCode, X402PaymentError, amountExceedsLimitError, buildPaymentHeader, createX402Fetch, insufficientBalanceError, invalid402ResponseError, isUserRejection, isX402PaymentError, networkError, parse402Response as parsePaymentRequirements, rateLimitExceededError, recipientNotAllowedError, timeoutError, transactionFailedError, userRejectedError, verificationFailedError, walletNotConnectedError };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@alleyboss/micropay-solana-x402-paywall",
-    "version": "3.3.15",
+    "version": "3.5.0",
     "description": "Production-ready Solana micropayments library wrapper for official x402 SDK",
     "author": "AlleyBoss",
     "license": "MIT",
@@ -16,7 +16,8 @@
         "micropayments",
         "web3",
         "coinbase",
-        "agent-payments"
+        "agent-payments",
+        "fetch"
     ],
     "type": "module",
     "main": "./dist/index.cjs",
@@ -92,6 +93,16 @@
                 "types": "./dist/session/index.d.cts",
                 "default": "./dist/session/index.cjs"
             }
+        },
+        "./fetch": {
+            "import": {
+                "types": "./dist/fetch/index.d.ts",
+                "default": "./dist/fetch/index.js"
+            },
+            "require": {
+                "types": "./dist/fetch/index.d.cts",
+                "default": "./dist/fetch/index.cjs"
+            }
         }
     },
     "files": [
@@ -118,10 +129,23 @@
     },
     "peerDependencies": {
         "@solana/web3.js": "^1.90.0",
+        "@solana/wallet-adapter-base": "^0.9.0",
         "react": ">=16.8.0",
         "react-dom": ">=16.8.0"
     },
+    "peerDependenciesMeta": {
+        "@solana/wallet-adapter-base": {
+            "optional": true
+        },
+        "react": {
+            "optional": true
+        },
+        "react-dom": {
+            "optional": true
+        }
+    },
     "devDependencies": {
+        "@solana/wallet-adapter-base": "^0.9.27",
         "@solana/web3.js": "^1.98.4",
         "@types/express": "^5.0.6",
         "@types/node": "^20",