@alleyboss/micropay-solana-x402-paywall 2.1.2 → 2.2.0

package/README.md

@@ -19,7 +19,7 @@ npm install @alleyboss/micropay-solana-x402-paywall @solana/web3.js
 | Feature | Description |
 |---------|-------------|
 | 💰 **SOL & USDC Payments** | Native SOL and SPL tokens (USDC, USDT) |
-| 🔐 **x402 Protocol** | HTTP 402 Payment Required standard |
+| 🔐 **x402 Protocol** | Full HTTP 402 compliance with `X-Payment-Required` headers |
 | 🔑 **JWT Sessions** | Secure unlock tracking with anti-replay |
 | 🛡️ **Signature Store** | Prevent double-spend at app layer |
 | 🔌 **Express & Next.js** | Zero-boilerplate middleware |
@@ -82,27 +82,42 @@ import { getSolPrice, formatPriceDisplay, configurePricing } from '@alleyboss/mi
 import { withRetry } from '@alleyboss/micropay-solana-x402-paywall/utils';
 ```
 
-## 🔥 New in v2.1.0
+## 🔥 New in v2.2.0
 
-- **RPC Fallback Support** — Automatic failover on primary RPC failure (configurable, default: off)
-- **Priority Fees** — Compute budget instructions for landing transactions faster (configurable, default: off)
-- **Versioned Transactions** — Full v0 transaction support with lookup tables
-- **TDD Test Suite** — Comprehensive tests with vitest (must pass before npm publish)
+### x402 Protocol Compliance
+
+Full compliance with the [x402.org](https://x402.org) specification:
 
 ```typescript
-// RPC Fallback configuration
-const config = {
-  network: 'mainnet-beta',
-  rpcUrl: 'https://primary-rpc.com',
-  enableFallback: true, // default: false
-  fallbackRpcUrls: [
-    'https://fallback1.com',
-    'https://fallback2.com',
-  ],
-};
+import { create402Response, parsePaymentHeader, encodePaymentRequirement } from '@alleyboss/micropay-solana-x402-paywall/x402';
+
+// Create 402 response with X-Payment-Required header
+const response = create402Response({
+  scheme: 'exact',
+  network: 'solana-mainnet',
+  maxAmountRequired: '10000000',
+  payTo: 'CreatorWallet...',
+  resource: '/api/premium',
+  description: 'Premium content access',
+  maxTimeoutSeconds: 300,
+  asset: 'native',
+});
+// Response includes: X-Payment-Required: <base64-encoded-requirement>
 
+// Parse X-Payment header from client
+const payload = parsePaymentHeader(request.headers.get('x-payment'));
+```
+
+### Previous Features (v2.1.x)
+
+- **RPC Fallback Support** — Automatic failover on primary RPC failure
+- **Priority Fees** — Compute budget instructions for landing transactions faster
+- **Versioned Transactions** — Full v0 transaction support with lookup tables
+- **TDD Test Suite** — Comprehensive tests with vitest
+
+```typescript
 // Priority fees
-import { createPriorityFeeInstructions, estimatePriorityFee } from '@alleyboss/micropay-solana-x402-paywall/solana';
+import { createPriorityFeeInstructions } from '@alleyboss/micropay-solana-x402-paywall/solana';
 
 const instructions = createPriorityFeeInstructions({
   enabled: true,

package/dist/index.cjs

@@ -829,9 +829,28 @@ function parsePaymentHeader(header) {
     return null;
   }
 }
+function encodePaymentRequirement(requirement) {
+  return Buffer.from(JSON.stringify(requirement)).toString("base64");
+}
 function encodePaymentResponse(response) {
   return Buffer.from(JSON.stringify(response)).toString("base64");
 }
+function create402Response(requirement, body) {
+  const headers = new Headers({
+    "Content-Type": "application/json",
+    "X-Payment-Required": encodePaymentRequirement(requirement)
+  });
+  const responseBody = body || {
+    error: "Payment Required",
+    message: "This resource requires payment to access",
+    x402Version: 1,
+    accepts: [requirement]
+  };
+  return new Response(JSON.stringify(responseBody), {
+    status: 402,
+    headers
+  });
+}
 
 // src/store/memory.ts
 function createMemoryStore(options = {}) {
@@ -976,16 +995,22 @@ function createPaywallMiddleware(config2) {
     const sessionToken = cookies[cookieName];
     const result = await checkPaywallAccess(path, sessionToken, config2);
     if (!result.allowed && result.requiresPayment) {
+      const headers = {
+        "Content-Type": "application/json"
+      };
+      if (config2.paymentRequirement) {
+        const requirement = typeof config2.paymentRequirement === "function" ? config2.paymentRequirement(path) : config2.paymentRequirement;
+        headers["X-Payment-Required"] = encodePaymentRequirement(requirement);
+      }
       const body = config2.custom402Response ? config2.custom402Response(path) : {
         error: "Payment Required",
         message: "This resource requires payment to access",
+        x402Version: 1,
         path
       };
       return new Response(JSON.stringify(body), {
         status: 402,
-        headers: {
-          "Content-Type": "application/json"
-        }
+        headers
       });
     }
     return null;
@@ -1314,6 +1339,7 @@ exports.checkPaywallAccess = checkPaywallAccess;
 exports.clearPriceCache = clearPriceCache;
 exports.configurePricing = configurePricing;
 exports.create402Headers = create402Headers;
+exports.create402Response = create402Response;
 exports.create402ResponseBody = create402ResponseBody;
 exports.createMemoryStore = createMemoryStore;
 exports.createPaymentFlow = createPaymentFlow;
@@ -1324,6 +1350,7 @@ exports.createRedisStore = createRedisStore;
 exports.createSession = createSession;
 exports.decodePaymentRequired = decodePaymentRequired;
 exports.encodePaymentRequired = encodePaymentRequired;
+exports.encodePaymentRequirement = encodePaymentRequirement;
 exports.encodePaymentResponse = encodePaymentResponse;
 exports.estimatePriorityFee = estimatePriorityFee;
 exports.fetchLookupTables = fetchLookupTables;