@alleyboss/micropay-solana-x402-paywall 3.3.10 → 3.3.12

package/README.md

@@ -133,6 +133,32 @@ const withMicropay = createX402Middleware({
 | **Setup** | Zero-config | Requires RPC URL |
 | **Best For** | Quick startups, MVPs | Production, High-Volume, Agents |
 
+## 🌐 Public Facilitator Mode (New in v3.3.12)
+
+Use a public facilitator service like [x402.org](https://x402.org) or [PayAI Network](https://facilitator.payai.network) without running your own RPC node:
+
+```typescript
+import { RemoteSvmFacilitator } from '@alleyboss/micropay-solana-x402-paywall';
+
+// Use a public facilitator for verification
+const facilitator = new RemoteSvmFacilitator('https://x402.org/facilitator');
+
+// Or in middleware config
+const withMicropay = createX402Middleware({
+    walletAddress: 'YOUR_WALLET',
+    network: 'mainnet-beta',
+    facilitatorUrl: 'https://facilitator.payai.network'
+    // No rpcUrl = uses remote facilitator
+});
+```
+
+### 🆚 Verification Modes Comparison
+
+| Mode | Class | Best For |
+|------|-------|----------|
+| **Self-Sovereign** | `LocalSvmFacilitator` | Full control, privacy, production |
+| **Public Facilitator** | `RemoteSvmFacilitator` | Quick setup, no RPC management |
+
 ## 🤖 AI Agent Payments
 
 Enable autonomous AI agents to pay for premium API access.

package/dist/index.cjs

@@ -223,6 +223,94 @@ var LocalSvmFacilitator = class {
     };
   }
 };
+var RemoteSvmFacilitator = class {
+  scheme = "exact";
+  facilitatorUrl;
+  constructor(facilitatorUrl = "https://facilitator.payai.network") {
+    this.facilitatorUrl = facilitatorUrl.replace(/\/$/, "");
+  }
+  /**
+   * Get supported payment kinds
+   */
+  async getSupported(extensionKeys = []) {
+    try {
+      const response = await fetch(`${this.facilitatorUrl}/supported`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ extensionKeys })
+      });
+      if (!response.ok) {
+        throw new Error(`Facilitator error: ${response.statusText}`);
+      }
+      return await response.json();
+    } catch (error) {
+      throw error;
+    }
+  }
+  /**
+   * Verify a payment remotely
+   */
+  async verify(payload, requirements) {
+    try {
+      const response = await fetch(`${this.facilitatorUrl}/verify`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          payload,
+          requirements
+        })
+      });
+      if (!response.ok) {
+        const errorBody = await response.text();
+        return {
+          isValid: false,
+          invalidReason: `Remote Verify Failed (${response.status}): ${errorBody}`
+        };
+      }
+      const result = await response.json();
+      return result;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : "Unknown error";
+      throw new types.VerifyError(500, {
+        isValid: false,
+        invalidReason: `Network error: ${errorMessage}`
+      });
+    }
+  }
+  /**
+   * Settle a payment remotely
+   */
+  async settle(payload, requirements) {
+    try {
+      const response = await fetch(`${this.facilitatorUrl}/settle`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          payload,
+          requirements
+        })
+      });
+      if (!response.ok) {
+        const errorBody = await response.text();
+        throw new types.SettleError(response.status, {
+          success: false,
+          errorReason: errorBody,
+          transaction: payload.payload.signature,
+          network: requirements.network
+        });
+      }
+      return await response.json();
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : "Unknown error";
+      throw new types.SettleError(500, {
+        success: false,
+        errorReason: errorMessage,
+        transaction: payload.payload.signature,
+        network: requirements.network
+      });
+    }
+  }
+};
 var DEFAULT_COMPUTE_UNITS = 2e5;
 var DEFAULT_MICRO_LAMPORTS = 1e3;
 function createPriorityFeeInstructions(config = {}) {
@@ -717,6 +805,7 @@ function getProviders() {
 }
 
 exports.LocalSvmFacilitator = LocalSvmFacilitator;
+exports.RemoteSvmFacilitator = RemoteSvmFacilitator;
 exports.addCredits = addCredits;
 exports.clearPriceCache = clearPriceCache;
 exports.configurePricing = configurePricing;

package/dist/index.d.cts

@@ -8,7 +8,7 @@ export { CustomPriceProvider, PriceConfig, PriceData, clearPriceCache, configure
 import '@solana/web3.js';
 import './types-BWYQMw03.cjs';
 
-interface FacilitatorClient {
+interface FacilitatorClient$1 {
     verify(paymentPayload: PaymentPayload, paymentRequirements: PaymentRequirements): Promise<VerifyResponse>;
     settle(paymentPayload: PaymentPayload, paymentRequirements: PaymentRequirements): Promise<SettleResponse>;
     getSupported(extensionKeys?: string[]): Promise<SupportedResponse>;
@@ -19,7 +19,7 @@ interface FacilitatorClient {
  * Verifies and settles Solana payments locally using a direct RPC connection,
  * bypassing the need for a hosted facilitator service.
  */
-declare class LocalSvmFacilitator implements FacilitatorClient {
+declare class LocalSvmFacilitator implements FacilitatorClient$1 {
     readonly scheme = "exact";
     readonly caipFamily = "solana:*";
     private connection;
@@ -98,4 +98,33 @@ declare class LocalSvmFacilitator implements FacilitatorClient {
     settle(payload: PaymentPayload, requirements: PaymentRequirements): Promise<SettleResponse>;
 }
 
-export { LocalSvmFacilitator };
+interface FacilitatorClient {
+    verify(paymentPayload: PaymentPayload, paymentRequirements: PaymentRequirements): Promise<VerifyResponse>;
+    settle(paymentPayload: PaymentPayload, paymentRequirements: PaymentRequirements): Promise<SettleResponse>;
+    getSupported(extensionKeys?: string[]): Promise<SupportedResponse>;
+}
+/**
+ * Remote SVM Facilitator
+ *
+ * Verifies payments by delegating to a hosted facilitator service (e.g. PayAI or x402.org).
+ * This allows using advanced features like cross-chain swaps or fiat abstraction handled by the facilitator.
+ */
+declare class RemoteSvmFacilitator implements FacilitatorClient {
+    readonly scheme = "exact";
+    private facilitatorUrl;
+    constructor(facilitatorUrl?: string);
+    /**
+     * Get supported payment kinds
+     */
+    getSupported(extensionKeys?: string[]): Promise<SupportedResponse>;
+    /**
+     * Verify a payment remotely
+     */
+    verify(payload: PaymentPayload, requirements: PaymentRequirements): Promise<VerifyResponse>;
+    /**
+     * Settle a payment remotely
+     */
+    settle(payload: PaymentPayload, requirements: PaymentRequirements): Promise<SettleResponse>;
+}
+
+export { LocalSvmFacilitator, RemoteSvmFacilitator };

package/dist/index.d.ts

@@ -8,7 +8,7 @@ export { CustomPriceProvider, PriceConfig, PriceData, clearPriceCache, configure
 import '@solana/web3.js';
 import './types-BWYQMw03.js';
 
-interface FacilitatorClient {
+interface FacilitatorClient$1 {
     verify(paymentPayload: PaymentPayload, paymentRequirements: PaymentRequirements): Promise<VerifyResponse>;
     settle(paymentPayload: PaymentPayload, paymentRequirements: PaymentRequirements): Promise<SettleResponse>;
     getSupported(extensionKeys?: string[]): Promise<SupportedResponse>;
@@ -19,7 +19,7 @@ interface FacilitatorClient {
  * Verifies and settles Solana payments locally using a direct RPC connection,
  * bypassing the need for a hosted facilitator service.
  */
-declare class LocalSvmFacilitator implements FacilitatorClient {
+declare class LocalSvmFacilitator implements FacilitatorClient$1 {
     readonly scheme = "exact";
     readonly caipFamily = "solana:*";
     private connection;
@@ -98,4 +98,33 @@ declare class LocalSvmFacilitator implements FacilitatorClient {
     settle(payload: PaymentPayload, requirements: PaymentRequirements): Promise<SettleResponse>;
 }
 
-export { LocalSvmFacilitator };
+interface FacilitatorClient {
+    verify(paymentPayload: PaymentPayload, paymentRequirements: PaymentRequirements): Promise<VerifyResponse>;
+    settle(paymentPayload: PaymentPayload, paymentRequirements: PaymentRequirements): Promise<SettleResponse>;
+    getSupported(extensionKeys?: string[]): Promise<SupportedResponse>;
+}
+/**
+ * Remote SVM Facilitator
+ *
+ * Verifies payments by delegating to a hosted facilitator service (e.g. PayAI or x402.org).
+ * This allows using advanced features like cross-chain swaps or fiat abstraction handled by the facilitator.
+ */
+declare class RemoteSvmFacilitator implements FacilitatorClient {
+    readonly scheme = "exact";
+    private facilitatorUrl;
+    constructor(facilitatorUrl?: string);
+    /**
+     * Get supported payment kinds
+     */
+    getSupported(extensionKeys?: string[]): Promise<SupportedResponse>;
+    /**
+     * Verify a payment remotely
+     */
+    verify(payload: PaymentPayload, requirements: PaymentRequirements): Promise<VerifyResponse>;
+    /**
+     * Settle a payment remotely
+     */
+    settle(payload: PaymentPayload, requirements: PaymentRequirements): Promise<SettleResponse>;
+}
+
+export { LocalSvmFacilitator, RemoteSvmFacilitator };

package/dist/index.js

@@ -218,6 +218,94 @@ var LocalSvmFacilitator = class {
     };
   }
 };
+var RemoteSvmFacilitator = class {
+  scheme = "exact";
+  facilitatorUrl;
+  constructor(facilitatorUrl = "https://facilitator.payai.network") {
+    this.facilitatorUrl = facilitatorUrl.replace(/\/$/, "");
+  }
+  /**
+   * Get supported payment kinds
+   */
+  async getSupported(extensionKeys = []) {
+    try {
+      const response = await fetch(`${this.facilitatorUrl}/supported`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ extensionKeys })
+      });
+      if (!response.ok) {
+        throw new Error(`Facilitator error: ${response.statusText}`);
+      }
+      return await response.json();
+    } catch (error) {
+      throw error;
+    }
+  }
+  /**
+   * Verify a payment remotely
+   */
+  async verify(payload, requirements) {
+    try {
+      const response = await fetch(`${this.facilitatorUrl}/verify`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          payload,
+          requirements
+        })
+      });
+      if (!response.ok) {
+        const errorBody = await response.text();
+        return {
+          isValid: false,
+          invalidReason: `Remote Verify Failed (${response.status}): ${errorBody}`
+        };
+      }
+      const result = await response.json();
+      return result;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : "Unknown error";
+      throw new VerifyError(500, {
+        isValid: false,
+        invalidReason: `Network error: ${errorMessage}`
+      });
+    }
+  }
+  /**
+   * Settle a payment remotely
+   */
+  async settle(payload, requirements) {
+    try {
+      const response = await fetch(`${this.facilitatorUrl}/settle`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          payload,
+          requirements
+        })
+      });
+      if (!response.ok) {
+        const errorBody = await response.text();
+        throw new SettleError(response.status, {
+          success: false,
+          errorReason: errorBody,
+          transaction: payload.payload.signature,
+          network: requirements.network
+        });
+      }
+      return await response.json();
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : "Unknown error";
+      throw new SettleError(500, {
+        success: false,
+        errorReason: errorMessage,
+        transaction: payload.payload.signature,
+        network: requirements.network
+      });
+    }
+  }
+};
 var DEFAULT_COMPUTE_UNITS = 2e5;
 var DEFAULT_MICRO_LAMPORTS = 1e3;
 function createPriorityFeeInstructions(config = {}) {
@@ -711,4 +799,4 @@ function getProviders() {
   return PROVIDERS.map((p) => ({ name: p.name, url: p.url }));
 }
 
-export { LocalSvmFacilitator, addCredits, clearPriceCache, configurePricing, createCreditSession, executeAgentPayment, formatPriceDisplay, formatPriceSync, generateAgentKeypair, getAgentBalance, getProviders, getRemainingCredits, getSolPrice, hasAgentSufficientBalance, keypairFromBase58, lamportsToSol, lamportsToUsd, usdToLamports, useCredit, validateCreditSession };
+export { LocalSvmFacilitator, RemoteSvmFacilitator, addCredits, clearPriceCache, configurePricing, createCreditSession, executeAgentPayment, formatPriceDisplay, formatPriceSync, generateAgentKeypair, getAgentBalance, getProviders, getRemainingCredits, getSolPrice, hasAgentSufficientBalance, keypairFromBase58, lamportsToSol, lamportsToUsd, usdToLamports, useCredit, validateCreditSession };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@alleyboss/micropay-solana-x402-paywall",
-    "version": "3.3.10",
+    "version": "3.3.12",
     "description": "Production-ready Solana micropayments library wrapper for official x402 SDK",
     "author": "AlleyBoss",
     "license": "MIT",