@alleyboss/micropay-solana-x402-paywall 2.0.0 → 2.0.2

package/README.md

@@ -1,165 +1,113 @@
 # @alleyboss/micropay-solana-x402-paywall
 
-> Production-ready Solana micropayments library implementing the x402 protocol with SPL token support.
+> Production-ready Solana micropayments library implementing the x402 protocol.
 
-[![npm version](https://img.shields.io/npm/v/@alleyboss/micropay-solana-x402-paywall)](https://www.npmjs.com/package/@alleyboss/micropay-solana-x402-paywall)
+[![npm](https://img.shields.io/npm/v/@alleyboss/micropay-solana-x402-paywall)](https://www.npmjs.com/package/@alleyboss/micropay-solana-x402-paywall)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Bundle Size](https://img.shields.io/badge/bundle-38KB-green)](https://bundlephobia.com/package/@alleyboss/micropay-solana-x402-paywall)
 
-## Features
+## 🚀 What It Does
 
-- 🔐 **x402 Protocol** — HTTP 402 Payment Required standard
-- ⚡ **Solana Native** — Fast, low-cost SOL & USDC micropayments
-- 🔑 **JWT Sessions** — Secure unlock tracking with anti-replay
-- 📦 **Framework Agnostic** — Express, Next.js, Fastify ready
-- 🌳 **Tree-shakeable** — Import only what you need (35KB full, 1-13KB per module)
-- 💰 **SPL Tokens** — USDC, USDT, and custom token support
-- 🔄 **Retry Logic** — Built-in resilience for RPC failures
-
-## Installation
+Turn any content into paid content with **one-time micropayments** on Solana. No subscriptions, no recurring charges—just pay to unlock.
 
 ```bash
 npm install @alleyboss/micropay-solana-x402-paywall @solana/web3.js
 ```
 
-## Quick Start
+## ✨ Features
+
+| Feature | Description |
+|---------|-------------|
+| 💰 **SOL & USDC Payments** | Native SOL and SPL tokens (USDC, USDT) |
+| 🔐 **x402 Protocol** | HTTP 402 Payment Required standard |
+| 🔑 **JWT Sessions** | Secure unlock tracking with anti-replay |
+| �️ **Signature Store** | Prevent double-spend at app layer |
+| 🔌 **Express & Next.js** | Zero-boilerplate middleware |
+| � **Price Conversion** | USD↔SOL with multi-provider fallback |
+| 🌳 **Tree-Shakeable** | Import only what you need |
 
-### Verify a Payment (SOL or USDC)
+## 📦 Quick Example
 
 ```typescript
-import { verifyPayment, verifySPLPayment } from '@alleyboss/micropay-solana-x402-paywall';
+import { verifyPayment, createSession } from '@alleyboss/micropay-solana-x402-paywall';
 
-// SOL payment
+// Verify on-chain payment
 const result = await verifyPayment({
   signature: 'tx...',
   expectedRecipient: 'CreatorWallet',
   expectedAmount: 10_000_000n, // 0.01 SOL
-  clientConfig: { network: 'devnet' },
-});
-
-// USDC payment
-const usdcResult = await verifySPLPayment({
-  signature: 'tx...',
-  expectedRecipient: 'CreatorWallet',
-  expectedAmount: 1_000_000n, // 1 USDC
-  asset: 'usdc',
   clientConfig: { network: 'mainnet-beta' },
 });
-```
-
-### Express Middleware (Zero Boilerplate)
 
-```typescript
-import express from 'express';
-import { createExpressMiddleware } from '@alleyboss/micropay-solana-x402-paywall/middleware';
-
-const app = express();
-
-app.use('/api/premium', createExpressMiddleware({
-  sessionSecret: process.env.SESSION_SECRET!,
-  protectedPaths: ['/**'],
-}));
-
-app.get('/api/premium/content', (req, res) => {
-  res.json({ content: 'Premium!', wallet: req.session?.walletAddress });
-});
+// Create session for unlocked content
+if (result.valid) {
+  const { token } = await createSession(
+    result.from!,
+    'article-123',
+    { secret: process.env.SESSION_SECRET!, durationHours: 24 }
+  );
+}
 ```
 
-### Next.js Middleware
-
-```typescript
-// middleware.ts
-import { createPaywallMiddleware } from '@alleyboss/micropay-solana-x402-paywall/middleware';
-
-export const middleware = createPaywallMiddleware({
-  sessionSecret: process.env.SESSION_SECRET!,
-  protectedPaths: ['/api/premium/*', '/api/content/*'],
-});
-
-export const config = { matcher: ['/api/premium/:path*'] };
-```
+## 🔧 Modules
 
-### Prevent Signature Replay (Anti-Double-Spend)
+9 tree-shakeable entry points for minimal bundle size:
 
 ```typescript
-import { createMemoryStore, createRedisStore } from '@alleyboss/micropay-solana-x402-paywall/store';
-
-// Development
-const store = createMemoryStore();
+// Core verification
+import { verifyPayment, verifySPLPayment } from '@alleyboss/micropay-solana-x402-paywall/solana';
 
-// Production (with ioredis or node-redis)
-const store = createRedisStore({ client: redisClient });
-
-// Check before verification
-if (await store.hasBeenUsed(signature)) {
-  throw new Error('Payment already used');
-}
+// Session management  
+import { createSession, validateSession } from '@alleyboss/micropay-solana-x402-paywall/session';
 
-// Mark after successful verification
-await store.markAsUsed(signature, articleId, new Date(Date.now() + 86400000));
-```
+// x402 protocol
+import { buildPaymentRequirement } from '@alleyboss/micropay-solana-x402-paywall/x402';
 
-### Client-Side Payment Flow
+// Express/Next.js middleware
+import { createExpressMiddleware, createPaywallMiddleware } from '@alleyboss/micropay-solana-x402-paywall/middleware';
 
-```typescript
-import { createPaymentFlow, formatPriceDisplay } from '@alleyboss/micropay-solana-x402-paywall';
+// Anti-replay signature store
+import { createMemoryStore, createRedisStore } from '@alleyboss/micropay-solana-x402-paywall/store';
 
-const flow = createPaymentFlow({
-  network: 'mainnet-beta',
-  recipientWallet: 'CreatorWallet',
-  amount: 10_000_000n,
-});
+// Client-side helpers
+import { createPaymentFlow, buildSolanaPayUrl } from '@alleyboss/micropay-solana-x402-paywall/client';
 
-// Generate QR code for mobile wallets
-const qrUrl = flow.getSolanaPayUrl({ label: 'Unlock Article' });
+// Price conversion (4-provider rotation)
+import { getSolPrice, formatPriceDisplay, configurePricing } from '@alleyboss/micropay-solana-x402-paywall/pricing';
 
-// Display price with USD equivalent
-const price = await formatPriceDisplay(10_000_000n);
-// "0.0100 SOL (~$1.50)"
+// Retry utilities
+import { withRetry } from '@alleyboss/micropay-solana-x402-paywall/utils';
 ```
 
-## Module Exports
-
-Import only what you need for minimal bundle size:
+## 🔥 New in v2.0
 
-| Import Path | Size | Functions |
-|-------------|------|-----------|
-| `@.../solana` | 13KB | `verifyPayment`, `verifySPLPayment`, `getConnection` |
-| `@.../session` | 4.5KB | `createSession`, `validateSession`, `isArticleUnlocked` |
-| `@.../x402` | 10KB | `buildPaymentRequirement`, `verifyX402Payment` |
-| `@.../middleware` | 8KB | `createExpressMiddleware`, `createPaywallMiddleware` |
-| `@.../store` | 2.6KB | `createMemoryStore`, `createRedisStore` |
-| `@.../client` | 3.3KB | `createPaymentFlow`, `buildSolanaPayUrl` |
-| `@.../pricing` | 2KB | `getSolPrice`, `formatPriceDisplay` |
-| `@.../utils` | 1.7KB | `withRetry`, `isRetryableRPCError` |
+- **SPL Token Support** — USDC, USDT, custom tokens
+- **Multi-Provider Pricing** — CoinCap → Binance → CoinGecko → Kraken fallback
+- **Custom Price API** — `configurePricing({ customProvider: yourFn })`
+- **Express Middleware** — Works with Express, Fastify, Polka
+- **Signature Store** — Memory & Redis adapters for anti-replay
+- **Client Helpers** — Solana Pay URLs for QR codes
 
-## TypeScript Support
+## 📚 Documentation
 
-Full TypeScript with exported types:
+**Full documentation, API reference, and examples:**
 
-```typescript
-import type {
-  PaymentRequirement,
-  PaymentAsset,
-  SessionData,
-  SignatureStore,
-  PaywallMiddlewareConfig,
-} from '@alleyboss/micropay-solana-x402-paywall';
-```
+👉 **[solana-x402-paywall.vercel.app/docs](https://solana-x402-paywall.vercel.app/docs)**
 
-## RPC Configuration
+## 🛠️ RPC Providers
 
-Supports multiple RPC providers:
+Works with any Solana RPC provider:
 
 ```typescript
-const clientConfig = {
+const config = {
   network: 'mainnet-beta',
-  // Option 1: Tatum.io
-  tatumApiKey: 'your-api-key',
-  // Option 2: Custom RPC (Helius, QuickNode, etc.)
-  rpcUrl: 'https://your-rpc-endpoint.com',
+  // Tatum.io
+  tatumApiKey: 'your-key',
+  // Or custom (Helius, QuickNode, etc.)
+  rpcUrl: 'https://your-rpc.com',
 };
 ```
 
-## License
+## 📄 License
 
 MIT © AlleyBoss

package/dist/index.cjs

@@ -15,8 +15,8 @@ var TOKEN_MINTS = {
 };
 var cachedConnection = null;
 var cachedNetwork = null;
-function buildRpcUrl(config) {
-  const { network, rpcUrl, tatumApiKey } = config;
+function buildRpcUrl(config2) {
+  const { network, rpcUrl, tatumApiKey } = config2;
   if (rpcUrl) {
     if (rpcUrl.includes("tatum.io") && tatumApiKey && !rpcUrl.includes(tatumApiKey)) {
       return rpcUrl.endsWith("/") ? `${rpcUrl}${tatumApiKey}` : `${rpcUrl}/${tatumApiKey}`;
@@ -29,12 +29,12 @@ function buildRpcUrl(config) {
   }
   return web3_js.clusterApiUrl(network);
 }
-function getConnection(config) {
-  const { network } = config;
+function getConnection(config2) {
+  const { network } = config2;
   if (cachedConnection && cachedNetwork === network) {
     return cachedConnection;
   }
-  const rpcUrl = buildRpcUrl(config);
+  const rpcUrl = buildRpcUrl(config2);
   cachedConnection = new web3_js.Connection(rpcUrl, {
     commitment: "confirmed",
     confirmTransactionInitialTimeout: 6e4
@@ -420,19 +420,19 @@ function validateArticleId(articleId) {
   const safeIdRegex = /^[a-zA-Z0-9_-]+$/;
   return safeIdRegex.test(articleId);
 }
-async function createSession(walletAddress, articleId, config, siteWide = false) {
+async function createSession(walletAddress, articleId, config2, siteWide = false) {
   if (!validateWalletAddress(walletAddress)) {
     throw new Error("Invalid wallet address format");
   }
   if (!validateArticleId(articleId)) {
     throw new Error("Invalid article ID format");
   }
-  if (!config.durationHours || config.durationHours <= 0 || config.durationHours > 720) {
+  if (!config2.durationHours || config2.durationHours <= 0 || config2.durationHours > 720) {
     throw new Error("Session duration must be between 1 and 720 hours");
   }
   const sessionId = uuid.v4();
   const now = Math.floor(Date.now() / 1e3);
-  const expiresAt = now + config.durationHours * 3600;
+  const expiresAt = now + config2.durationHours * 3600;
   const session = {
     id: sessionId,
     walletAddress,
@@ -449,7 +449,7 @@ async function createSession(walletAddress, articleId, config, siteWide = false)
     iat: now,
     exp: expiresAt
   };
-  const token = await new jose.SignJWT(payload).setProtectedHeader({ alg: "HS256" }).setIssuedAt().setExpirationTime(`${config.durationHours}h`).sign(getSecretKey(config.secret));
+  const token = await new jose.SignJWT(payload).setProtectedHeader({ alg: "HS256" }).setIssuedAt().setExpirationTime(`${config2.durationHours}h`).sign(getSecretKey(config2.secret));
   return { token, session };
 }
 async function validateSession(token, secret) {
@@ -806,8 +806,8 @@ function matchesProtectedPath(path, patterns) {
   }
   return false;
 }
-async function checkPaywallAccess(path, sessionToken, config) {
-  if (!matchesProtectedPath(path, config.protectedPaths)) {
+async function checkPaywallAccess(path, sessionToken, config2) {
+  if (!matchesProtectedPath(path, config2.protectedPaths)) {
     return { allowed: true };
   }
   if (!sessionToken) {
@@ -817,7 +817,7 @@ async function checkPaywallAccess(path, sessionToken, config) {
       requiresPayment: true
     };
   }
-  const validation = await validateSession(sessionToken, config.sessionSecret);
+  const validation = await validateSession(sessionToken, config2.sessionSecret);
   if (!validation.valid || !validation.session) {
     return {
       allowed: false,
@@ -830,8 +830,8 @@ async function checkPaywallAccess(path, sessionToken, config) {
     session: validation.session
   };
 }
-function createPaywallMiddleware(config) {
-  const { cookieName = "x402_session" } = config;
+function createPaywallMiddleware(config2) {
+  const { cookieName = "x402_session" } = config2;
   return async function middleware(request) {
     const url = new URL(request.url);
     const path = url.pathname;
@@ -843,9 +843,9 @@ function createPaywallMiddleware(config) {
       })
     );
     const sessionToken = cookies[cookieName];
-    const result = await checkPaywallAccess(path, sessionToken, config);
+    const result = await checkPaywallAccess(path, sessionToken, config2);
     if (!result.allowed && result.requiresPayment) {
-      const body = config.custom402Response ? config.custom402Response(path) : {
+      const body = config2.custom402Response ? config2.custom402Response(path) : {
         error: "Payment Required",
         message: "This resource requires payment to access",
         path
@@ -981,8 +981,8 @@ function buildSolanaPayUrl(params) {
   }
   return url.toString();
 }
-function createPaymentFlow(config) {
-  const { network, recipientWallet, amount, asset = "native", memo } = config;
+function createPaymentFlow(config2) {
+  const { network, recipientWallet, amount, asset = "native", memo } = config2;
   let decimals = 9;
   let mintAddress;
   if (asset === "usdc") {
@@ -998,7 +998,7 @@ function createPaymentFlow(config) {
   const naturalAmount = Number(amount) / Math.pow(10, decimals);
   return {
     /** Get the payment configuration */
-    getConfig: () => ({ ...config }),
+    getConfig: () => ({ ...config2 }),
     /** Get amount in natural display units (e.g., 0.01 SOL) */
     getDisplayAmount: () => naturalAmount,
     /** Get amount formatted with symbol */
@@ -1044,43 +1044,100 @@ function createPaymentReference() {
 
 // src/pricing/index.ts
 var cachedPrice = null;
-var CACHE_TTL_MS = 6e4;
-async function getSolPrice() {
-  if (cachedPrice && Date.now() - cachedPrice.fetchedAt.getTime() < CACHE_TTL_MS) {
-    return cachedPrice;
-  }
+var config = {};
+var lastProviderIndex = -1;
+function configurePricing(newConfig) {
+  config = { ...config, ...newConfig };
+  cachedPrice = null;
+}
+var PROVIDERS = [
+  {
+    name: "coincap",
+    url: "https://api.coincap.io/v2/assets/solana",
+    parse: (data) => parseFloat(data.data?.priceUsd || "0")
+  },
+  {
+    name: "binance",
+    url: "https://api.binance.com/api/v3/ticker/price?symbol=SOLUSDT",
+    parse: (data) => parseFloat(data.price || "0")
+  },
+  {
+    name: "coingecko",
+    url: "https://api.coingecko.com/api/v3/simple/price?ids=solana&vs_currencies=usd",
+    parse: (data) => data.solana?.usd || 0
+  },
+  {
+    name: "kraken",
+    url: "https://api.kraken.com/0/public/Ticker?pair=SOLUSD",
+    parse: (data) => parseFloat(data.result?.SOLUSD?.c?.[0] || "0")
+  }
+];
+async function fetchFromProvider(provider, timeout) {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeout);
   try {
-    const response = await fetch(
-      "https://api.coingecko.com/api/v3/simple/price?ids=solana&vs_currencies=usd",
-      {
-        headers: { "Accept": "application/json" },
-        signal: AbortSignal.timeout(5e3)
-      }
-    );
+    const response = await fetch(provider.url, {
+      headers: { "Accept": "application/json" },
+      signal: controller.signal
+    });
     if (!response.ok) {
-      throw new Error(`Price fetch failed: ${response.status}`);
+      throw new Error(`HTTP ${response.status}`);
     }
     const data = await response.json();
-    if (!data.solana?.usd) {
-      throw new Error("Invalid price response");
+    const price = provider.parse(data);
+    if (!price || price <= 0) {
+      throw new Error("Invalid price");
     }
-    cachedPrice = {
-      solPrice: data.solana.usd,
-      fetchedAt: /* @__PURE__ */ new Date(),
-      source: "coingecko"
-    };
+    return price;
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+async function getSolPrice() {
+  const cacheTTL = config.cacheTTL ?? 6e4;
+  const timeout = config.timeout ?? 5e3;
+  if (cachedPrice && Date.now() - cachedPrice.fetchedAt.getTime() < cacheTTL) {
     return cachedPrice;
-  } catch (error) {
-    if (cachedPrice) {
+  }
+  if (config.customProvider) {
+    try {
+      const price = await config.customProvider();
+      if (price > 0) {
+        cachedPrice = {
+          solPrice: price,
+          fetchedAt: /* @__PURE__ */ new Date(),
+          source: "custom"
+        };
+        return cachedPrice;
+      }
+    } catch {
+    }
+  }
+  for (let i = 0; i < PROVIDERS.length; i++) {
+    const idx = (lastProviderIndex + 1 + i) % PROVIDERS.length;
+    const provider = PROVIDERS[idx];
+    try {
+      const price = await fetchFromProvider(provider, timeout);
+      lastProviderIndex = idx;
+      cachedPrice = {
+        solPrice: price,
+        fetchedAt: /* @__PURE__ */ new Date(),
+        source: provider.name
+      };
       return cachedPrice;
+    } catch {
+      continue;
     }
-    return {
-      solPrice: 150,
-      // Fallback price
-      fetchedAt: /* @__PURE__ */ new Date(),
-      source: "fallback"
-    };
   }
+  if (cachedPrice) {
+    return cachedPrice;
+  }
+  return {
+    solPrice: 150,
+    // Reasonable fallback
+    fetchedAt: /* @__PURE__ */ new Date(),
+    source: "fallback"
+  };
 }
 async function lamportsToUsd(lamports) {
   const { solPrice } = await getSolPrice();
@@ -1109,6 +1166,10 @@ function formatPriceSync(lamports, solPrice) {
 }
 function clearPriceCache() {
   cachedPrice = null;
+  lastProviderIndex = -1;
+}
+function getProviders() {
+  return PROVIDERS.map((p) => ({ name: p.name, url: p.url }));
 }
 
 exports.TOKEN_MINTS = TOKEN_MINTS;
@@ -1118,6 +1179,7 @@ exports.buildPaymentRequirement = buildPaymentRequirement;
 exports.buildSolanaPayUrl = buildSolanaPayUrl;
 exports.checkPaywallAccess = checkPaywallAccess;
 exports.clearPriceCache = clearPriceCache;
+exports.configurePricing = configurePricing;
 exports.create402Headers = create402Headers;
 exports.create402ResponseBody = create402ResponseBody;
 exports.createMemoryStore = createMemoryStore;
@@ -1132,6 +1194,7 @@ exports.encodePaymentResponse = encodePaymentResponse;
 exports.formatPriceDisplay = formatPriceDisplay;
 exports.formatPriceSync = formatPriceSync;
 exports.getConnection = getConnection;
+exports.getProviders = getProviders;
 exports.getSolPrice = getSolPrice;
 exports.getTokenDecimals = getTokenDecimals;
 exports.getWalletTransactions = getWalletTransactions;