@openfacilitator/sdk 0.1.1 → 0.2.0

package/README.md

@@ -28,20 +28,32 @@ const facilitator = createDefaultFacilitator();
 ### Verify a Payment
 
 ```typescript
-const result = await facilitator.verify({
+// Payment payload from the client
+const payment = {
   x402Version: 1,
   scheme: 'exact',
   network: 'base',
   payload: {
     signature: '0x...',
     authorization: {
-      from: '0x...',
-      to: '0x...',
+      from: '0xSenderAddress',
+      to: '0xRecipientAddress',
       amount: '1000000',
-      asset: '0x...',
+      asset: '0xTokenAddress',
     },
   },
-});
+};
+
+// Requirements from the server/resource
+const requirements = {
+  scheme: 'exact',
+  network: 'base',
+  maxAmountRequired: '1000000',
+  asset: '0xTokenAddress',
+  payTo: '0xRecipientAddress',
+};
+
+const result = await facilitator.verify(payment, requirements);
 
 if (result.valid) {
   console.log('Payment is valid!');
@@ -53,20 +65,7 @@ if (result.valid) {
 ### Settle a Payment
 
 ```typescript
-const result = await facilitator.settle({
-  x402Version: 1,
-  scheme: 'exact',
-  network: 'base',
-  payload: {
-    signature: '0x...',
-    authorization: {
-      from: '0x...',
-      to: '0x...',
-      amount: '1000000',
-      asset: '0x...',
-    },
-  },
-});
+const result = await facilitator.settle(payment, requirements);
 
 if (result.success) {
   console.log('Transaction hash:', result.transactionHash);
@@ -117,7 +116,7 @@ import {
 } from '@openfacilitator/sdk';
 
 try {
-  await facilitator.settle(payment);
+  await facilitator.settle(payment, requirements);
 } catch (error) {
   if (error instanceof SettlementError) {
     console.error('Settlement failed:', error.message);

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 interface FacilitatorConfig {
-    /** Facilitator URL (e.g., https://pay.honeypot.game) */
-    url: string;
+    /** Facilitator URL (defaults to https://pay.openfacilitator.io) */
+    url?: string;
     /** Optional timeout in ms (default: 30000) */
     timeout?: number;
     /** Optional custom headers */
@@ -137,7 +137,9 @@ declare class OpenFacilitator {
     private readonly baseUrl;
     private readonly timeout;
     private readonly headers;
-    constructor(config: FacilitatorConfig);
+    private supportedCache;
+    private supportedPromise;
+    constructor(config?: FacilitatorConfig);
     /**
      * Get the facilitator URL
      */
@@ -162,6 +164,30 @@ declare class OpenFacilitator {
      * Health check - verify facilitator is reachable
      */
     health(): Promise<boolean>;
+    /**
+     * Get fee payer address for a specific network.
+     * Fee payers are wallet addresses that pay transaction fees when settling payments.
+     * Currently only Solana networks have fee payers.
+     * @param network - Network identifier (e.g., "solana", "solana:mainnet")
+     * @returns Fee payer address or undefined if not available for the network
+     */
+    getFeePayer(network: string): Promise<string | undefined>;
+    /**
+     * Get all fee payers mapped by network.
+     * Fee payers are wallet addresses that pay transaction fees when settling payments.
+     * @returns Map of network identifiers to fee payer addresses
+     */
+    getFeePayerMap(): Promise<Record<string, string>>;
+    /**
+     * Get cached supported response, fetching if needed.
+     * Uses deduplication to prevent concurrent requests.
+     */
+    private getSupportedCached;
+    /**
+     * Clear cached supported response.
+     * Useful if facilitator configuration may have changed.
+     */
+    clearCache(): void;
     /**
      * Internal request helper
      */
@@ -169,6 +195,7 @@ declare class OpenFacilitator {
 }
 /**
  * Create a facilitator client with default OpenFacilitator URL
+ * @deprecated Just use `new OpenFacilitator()` - it defaults to the public endpoint
  */
 declare function createDefaultFacilitator(): OpenFacilitator;
 

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 interface FacilitatorConfig {
-    /** Facilitator URL (e.g., https://pay.honeypot.game) */
-    url: string;
+    /** Facilitator URL (defaults to https://pay.openfacilitator.io) */
+    url?: string;
     /** Optional timeout in ms (default: 30000) */
     timeout?: number;
     /** Optional custom headers */
@@ -137,7 +137,9 @@ declare class OpenFacilitator {
     private readonly baseUrl;
     private readonly timeout;
     private readonly headers;
-    constructor(config: FacilitatorConfig);
+    private supportedCache;
+    private supportedPromise;
+    constructor(config?: FacilitatorConfig);
     /**
      * Get the facilitator URL
      */
@@ -162,6 +164,30 @@ declare class OpenFacilitator {
      * Health check - verify facilitator is reachable
      */
     health(): Promise<boolean>;
+    /**
+     * Get fee payer address for a specific network.
+     * Fee payers are wallet addresses that pay transaction fees when settling payments.
+     * Currently only Solana networks have fee payers.
+     * @param network - Network identifier (e.g., "solana", "solana:mainnet")
+     * @returns Fee payer address or undefined if not available for the network
+     */
+    getFeePayer(network: string): Promise<string | undefined>;
+    /**
+     * Get all fee payers mapped by network.
+     * Fee payers are wallet addresses that pay transaction fees when settling payments.
+     * @returns Map of network identifiers to fee payer addresses
+     */
+    getFeePayerMap(): Promise<Record<string, string>>;
+    /**
+     * Get cached supported response, fetching if needed.
+     * Uses deduplication to prevent concurrent requests.
+     */
+    private getSupportedCached;
+    /**
+     * Clear cached supported response.
+     * Useful if facilitator configuration may have changed.
+     */
+    clearCache(): void;
     /**
      * Internal request helper
      */
@@ -169,6 +195,7 @@ declare class OpenFacilitator {
 }
 /**
  * Create a facilitator client with default OpenFacilitator URL
+ * @deprecated Just use `new OpenFacilitator()` - it defaults to the public endpoint
  */
 declare function createDefaultFacilitator(): OpenFacilitator;
 

package/dist/index.js

@@ -89,12 +89,12 @@ function isPaymentPayload(value) {
 
 // src/client.ts
 var DEFAULT_TIMEOUT = 3e4;
+var DEFAULT_URL = "https://pay.openfacilitator.io";
 var OpenFacilitator = class {
-  constructor(config) {
-    if (!config.url) {
-      throw new ConfigurationError("Facilitator URL is required");
-    }
-    this.baseUrl = normalizeUrl(config.url);
+  constructor(config = {}) {
+    this.supportedCache = null;
+    this.supportedPromise = null;
+    this.baseUrl = normalizeUrl(config.url ?? DEFAULT_URL);
     this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
     this.headers = {
       "Content-Type": "application/json",
@@ -185,6 +185,64 @@ var OpenFacilitator = class {
       return false;
     }
   }
+  /**
+   * Get fee payer address for a specific network.
+   * Fee payers are wallet addresses that pay transaction fees when settling payments.
+   * Currently only Solana networks have fee payers.
+   * @param network - Network identifier (e.g., "solana", "solana:mainnet")
+   * @returns Fee payer address or undefined if not available for the network
+   */
+  async getFeePayer(network) {
+    const supported = await this.getSupportedCached();
+    for (const kind of supported.kinds) {
+      if (kind.network === network || kind.network.includes(network) || network.includes(kind.network)) {
+        if (kind.extra?.feePayer) {
+          return kind.extra.feePayer;
+        }
+      }
+    }
+    return void 0;
+  }
+  /**
+   * Get all fee payers mapped by network.
+   * Fee payers are wallet addresses that pay transaction fees when settling payments.
+   * @returns Map of network identifiers to fee payer addresses
+   */
+  async getFeePayerMap() {
+    const supported = await this.getSupportedCached();
+    const feePayerMap = {};
+    for (const kind of supported.kinds) {
+      if (kind.extra?.feePayer) {
+        feePayerMap[kind.network] = kind.extra.feePayer;
+      }
+    }
+    return feePayerMap;
+  }
+  /**
+   * Get cached supported response, fetching if needed.
+   * Uses deduplication to prevent concurrent requests.
+   */
+  async getSupportedCached() {
+    if (this.supportedCache) {
+      return this.supportedCache;
+    }
+    if (!this.supportedPromise) {
+      this.supportedPromise = this.supported().then((response) => {
+        this.supportedCache = response;
+        this.supportedPromise = null;
+        return response;
+      });
+    }
+    return this.supportedPromise;
+  }
+  /**
+   * Clear cached supported response.
+   * Useful if facilitator configuration may have changed.
+   */
+  clearCache() {
+    this.supportedCache = null;
+    this.supportedPromise = null;
+  }
   /**
    * Internal request helper
    */
@@ -226,9 +284,7 @@ var OpenFacilitator = class {
   }
 };
 function createDefaultFacilitator() {
-  return new OpenFacilitator({
-    url: "https://x402.openfacilitator.io"
-  });
+  return new OpenFacilitator();
 }
 
 // src/networks.ts

package/dist/index.mjs

@@ -48,12 +48,12 @@ function isPaymentPayload(value) {
 
 // src/client.ts
 var DEFAULT_TIMEOUT = 3e4;
+var DEFAULT_URL = "https://pay.openfacilitator.io";
 var OpenFacilitator = class {
-  constructor(config) {
-    if (!config.url) {
-      throw new ConfigurationError("Facilitator URL is required");
-    }
-    this.baseUrl = normalizeUrl(config.url);
+  constructor(config = {}) {
+    this.supportedCache = null;
+    this.supportedPromise = null;
+    this.baseUrl = normalizeUrl(config.url ?? DEFAULT_URL);
     this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
     this.headers = {
       "Content-Type": "application/json",
@@ -144,6 +144,64 @@ var OpenFacilitator = class {
       return false;
     }
   }
+  /**
+   * Get fee payer address for a specific network.
+   * Fee payers are wallet addresses that pay transaction fees when settling payments.
+   * Currently only Solana networks have fee payers.
+   * @param network - Network identifier (e.g., "solana", "solana:mainnet")
+   * @returns Fee payer address or undefined if not available for the network
+   */
+  async getFeePayer(network) {
+    const supported = await this.getSupportedCached();
+    for (const kind of supported.kinds) {
+      if (kind.network === network || kind.network.includes(network) || network.includes(kind.network)) {
+        if (kind.extra?.feePayer) {
+          return kind.extra.feePayer;
+        }
+      }
+    }
+    return void 0;
+  }
+  /**
+   * Get all fee payers mapped by network.
+   * Fee payers are wallet addresses that pay transaction fees when settling payments.
+   * @returns Map of network identifiers to fee payer addresses
+   */
+  async getFeePayerMap() {
+    const supported = await this.getSupportedCached();
+    const feePayerMap = {};
+    for (const kind of supported.kinds) {
+      if (kind.extra?.feePayer) {
+        feePayerMap[kind.network] = kind.extra.feePayer;
+      }
+    }
+    return feePayerMap;
+  }
+  /**
+   * Get cached supported response, fetching if needed.
+   * Uses deduplication to prevent concurrent requests.
+   */
+  async getSupportedCached() {
+    if (this.supportedCache) {
+      return this.supportedCache;
+    }
+    if (!this.supportedPromise) {
+      this.supportedPromise = this.supported().then((response) => {
+        this.supportedCache = response;
+        this.supportedPromise = null;
+        return response;
+      });
+    }
+    return this.supportedPromise;
+  }
+  /**
+   * Clear cached supported response.
+   * Useful if facilitator configuration may have changed.
+   */
+  clearCache() {
+    this.supportedCache = null;
+    this.supportedPromise = null;
+  }
   /**
    * Internal request helper
    */
@@ -185,9 +243,7 @@ var OpenFacilitator = class {
   }
 };
 function createDefaultFacilitator() {
-  return new OpenFacilitator({
-    url: "https://x402.openfacilitator.io"
-  });
+  return new OpenFacilitator();
 }
 
 // src/networks.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openfacilitator/sdk",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "TypeScript SDK for x402 payment facilitation",
   "main": "dist/index.js",
   "module": "dist/index.mjs",