@openfacilitator/sdk 0.1.0

package/README.md

@@ -0,0 +1,160 @@
+# @openfacilitator/sdk
+
+TypeScript SDK for x402 payment facilitation. Works with OpenFacilitator or any x402-compatible facilitator.
+
+## Installation
+
+```bash
+npm install @openfacilitator/sdk
+```
+
+## Quick Start
+
+```typescript
+import { OpenFacilitator } from '@openfacilitator/sdk';
+
+// Use custom facilitator
+const facilitator = new OpenFacilitator({
+  url: 'https://pay.yourdomain.com',
+});
+
+// Or use the default OpenFacilitator
+import { createDefaultFacilitator } from '@openfacilitator/sdk';
+const facilitator = createDefaultFacilitator();
+```
+
+## Usage
+
+### Verify a Payment
+
+```typescript
+const result = await facilitator.verify({
+  x402Version: 1,
+  scheme: 'exact',
+  network: 'base',
+  payload: {
+    signature: '0x...',
+    authorization: {
+      from: '0x...',
+      to: '0x...',
+      amount: '1000000',
+      asset: '0x...',
+    },
+  },
+});
+
+if (result.valid) {
+  console.log('Payment is valid!');
+} else {
+  console.error('Invalid payment:', result.error);
+}
+```
+
+### 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...',
+    },
+  },
+});
+
+if (result.success) {
+  console.log('Transaction hash:', result.transactionHash);
+} else {
+  console.error('Settlement failed:', result.error);
+}
+```
+
+### Get Supported Networks
+
+```typescript
+const supported = await facilitator.supported();
+
+console.log('Supported networks:');
+supported.kinds.forEach(kind => {
+  console.log(`- ${kind.network} (v${kind.x402Version})`);
+});
+```
+
+### Network Utilities
+
+```typescript
+import {
+  getNetwork,
+  getNetworkType,
+  toV2NetworkId,
+  NETWORKS,
+} from '@openfacilitator/sdk';
+
+// Get network info
+const base = getNetwork('base');
+console.log(base?.chainId); // 8453
+
+// Convert v1 to v2 ID
+const v2Id = toV2NetworkId('base'); // 'eip155:8453'
+
+// Get all mainnets
+const mainnets = NETWORKS.filter(n => !n.testnet);
+```
+
+## Error Handling
+
+```typescript
+import {
+  FacilitatorError,
+  VerificationError,
+  SettlementError,
+} from '@openfacilitator/sdk';
+
+try {
+  await facilitator.settle(payment);
+} catch (error) {
+  if (error instanceof SettlementError) {
+    console.error('Settlement failed:', error.message);
+  } else if (error instanceof FacilitatorError) {
+    console.error('Facilitator error:', error.code, error.message);
+  }
+}
+```
+
+## x402 Version Support
+
+This SDK supports both x402 v1 and v2:
+
+- **v1**: Human-readable network names (`base`, `solana`)
+- **v2**: CAIP-2 chain identifiers (`eip155:8453`, `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`)
+
+## Supported Networks
+
+### EVM Mainnets
+
+| Network   | v1 ID       | v2 ID (CAIP-2)   | Chain ID |
+| --------- | ----------- | ---------------- | -------- |
+| Base      | `base`      | `eip155:8453`    | 8453     |
+| Polygon   | `polygon`   | `eip155:137`     | 137      |
+| Avalanche | `avalanche` | `eip155:43114`   | 43114    |
+| Sei       | `sei`       | `eip155:1329`    | 1329     |
+| IoTeX     | `iotex`     | `eip155:4689`    | 4689     |
+| Peaq      | `peaq`      | `eip155:3338`    | 3338     |
+| X Layer   | `xlayer`    | `eip155:196`     | 196      |
+
+### Solana
+
+| Network       | v1 ID           | v2 ID (CAIP-2)                           |
+| ------------- | --------------- | ---------------------------------------- |
+| Solana        | `solana`        | `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp` |
+| Solana Devnet | `solana-devnet` | `solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1` |
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,197 @@
+interface FacilitatorConfig {
+    /** Facilitator URL (e.g., https://pay.honeypot.game) */
+    url: string;
+    /** Optional timeout in ms (default: 30000) */
+    timeout?: number;
+    /** Optional custom headers */
+    headers?: Record<string, string>;
+}
+/**
+ * Payment payload for verification/settlement
+ * Supports both x402 v1 and v2 formats
+ */
+interface PaymentPayload {
+    /** x402 version (1 or 2) */
+    x402Version: 1 | 2;
+    /** Payment scheme (e.g., "exact") */
+    scheme: string;
+    /** Network identifier - v1: "base", v2: "eip155:8453" */
+    network: string;
+    /** Payment details */
+    payload: {
+        /** Signature of the payment */
+        signature: string;
+        /** Payment authorization */
+        authorization: PaymentAuthorization;
+    };
+}
+interface PaymentAuthorization {
+    /** Sender address */
+    from: string;
+    /** Recipient address */
+    to: string;
+    /** Amount in base units (string to handle large numbers) */
+    amount: string;
+    /** Token/asset address or identifier */
+    asset: string;
+    /** Chain ID (for EVM) */
+    chainId?: number;
+    /** Nonce */
+    nonce?: string;
+    /** Expiration timestamp */
+    validUntil?: number;
+    /** Additional fields for specific schemes */
+    [key: string]: unknown;
+}
+interface VerifyResponse {
+    /** Whether the payment is valid */
+    valid: boolean;
+    /** Error message if invalid */
+    error?: string;
+    /** Additional verification details */
+    details?: {
+        /** Verified amount */
+        amount?: string;
+        /** Verified recipient */
+        recipient?: string;
+        /** Payment scheme used */
+        scheme?: string;
+    };
+}
+interface SettleResponse {
+    /** Whether settlement was successful */
+    success: boolean;
+    /** Transaction hash/signature */
+    transactionHash?: string;
+    /** Network the transaction was settled on */
+    network?: string;
+    /** Error message if failed */
+    error?: string;
+}
+interface SupportedResponse {
+    /** Supported payment kinds */
+    kinds: PaymentKind[];
+    /** Signer addresses by network namespace */
+    signers?: Record<string, string[]>;
+    /** Supported extensions */
+    extensions?: string[];
+}
+interface PaymentKind {
+    /** x402 version */
+    x402Version: 1 | 2;
+    /** Payment scheme */
+    scheme: string;
+    /** Network identifier */
+    network: string;
+    /** Extra data (e.g., feePayer for Solana) */
+    extra?: {
+        feePayer?: string;
+        [key: string]: unknown;
+    };
+}
+type NetworkType = 'evm' | 'solana';
+interface NetworkInfo {
+    /** v1 identifier (e.g., "base") */
+    v1Id: string;
+    /** v2 CAIP-2 identifier (e.g., "eip155:8453") */
+    v2Id: string;
+    /** Human-readable name */
+    name: string;
+    /** Network type */
+    type: NetworkType;
+    /** Chain ID (EVM only) */
+    chainId?: number;
+    /** Whether this is a testnet */
+    testnet: boolean;
+}
+
+declare class OpenFacilitator {
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly headers;
+    constructor(config: FacilitatorConfig);
+    /**
+     * Get the facilitator URL
+     */
+    get url(): string;
+    /**
+     * Verify a payment is valid
+     */
+    verify(payment: PaymentPayload): Promise<VerifyResponse>;
+    /**
+     * Settle/broadcast a payment transaction
+     */
+    settle(payment: PaymentPayload): Promise<SettleResponse>;
+    /**
+     * Get supported networks and payment kinds
+     */
+    supported(): Promise<SupportedResponse>;
+    /**
+     * Health check - verify facilitator is reachable
+     */
+    health(): Promise<boolean>;
+    /**
+     * Internal request helper
+     */
+    private request;
+}
+/**
+ * Create a facilitator client with default OpenFacilitator URL
+ */
+declare function createDefaultFacilitator(): OpenFacilitator;
+
+declare class FacilitatorError extends Error {
+    code: string;
+    statusCode?: number | undefined;
+    details?: unknown | undefined;
+    constructor(message: string, code: string, statusCode?: number | undefined, details?: unknown | undefined);
+}
+declare class NetworkError extends FacilitatorError {
+    constructor(message: string, details?: unknown);
+}
+declare class VerificationError extends FacilitatorError {
+    constructor(message: string, details?: unknown);
+}
+declare class SettlementError extends FacilitatorError {
+    constructor(message: string, details?: unknown);
+}
+declare class ConfigurationError extends FacilitatorError {
+    constructor(message: string);
+}
+
+declare const NETWORKS: NetworkInfo[];
+/**
+ * Get network info by v1 or v2 identifier
+ */
+declare function getNetwork(id: string): NetworkInfo | undefined;
+/**
+ * Get network type from identifier
+ */
+declare function getNetworkType(id: string): 'evm' | 'solana' | undefined;
+/**
+ * Convert v1 network ID to v2 (CAIP-2)
+ */
+declare function toV2NetworkId(id: string): string;
+/**
+ * Convert v2 network ID to v1
+ */
+declare function toV1NetworkId(id: string): string;
+/**
+ * Check if network ID is valid
+ */
+declare function isValidNetwork(id: string): boolean;
+/**
+ * Get all mainnet networks
+ */
+declare function getMainnets(): NetworkInfo[];
+/**
+ * Get all testnet networks
+ */
+declare function getTestnets(): NetworkInfo[];
+
+/**
+ * Type guard for checking if value is a valid payment payload
+ */
+declare function isPaymentPayload(value: unknown): value is PaymentPayload;
+
+export { ConfigurationError, type FacilitatorConfig, FacilitatorError, NETWORKS, NetworkError, type NetworkInfo, type NetworkType, OpenFacilitator, type PaymentAuthorization, type PaymentKind, type PaymentPayload, type SettleResponse, SettlementError, type SupportedResponse, VerificationError, type VerifyResponse, createDefaultFacilitator, getMainnets, getNetwork, getNetworkType, getTestnets, isPaymentPayload, isValidNetwork, toV1NetworkId, toV2NetworkId };

package/dist/index.d.ts

@@ -0,0 +1,197 @@
+interface FacilitatorConfig {
+    /** Facilitator URL (e.g., https://pay.honeypot.game) */
+    url: string;
+    /** Optional timeout in ms (default: 30000) */
+    timeout?: number;
+    /** Optional custom headers */
+    headers?: Record<string, string>;
+}
+/**
+ * Payment payload for verification/settlement
+ * Supports both x402 v1 and v2 formats
+ */
+interface PaymentPayload {
+    /** x402 version (1 or 2) */
+    x402Version: 1 | 2;
+    /** Payment scheme (e.g., "exact") */
+    scheme: string;
+    /** Network identifier - v1: "base", v2: "eip155:8453" */
+    network: string;
+    /** Payment details */
+    payload: {
+        /** Signature of the payment */
+        signature: string;
+        /** Payment authorization */
+        authorization: PaymentAuthorization;
+    };
+}
+interface PaymentAuthorization {
+    /** Sender address */
+    from: string;
+    /** Recipient address */
+    to: string;
+    /** Amount in base units (string to handle large numbers) */
+    amount: string;
+    /** Token/asset address or identifier */
+    asset: string;
+    /** Chain ID (for EVM) */
+    chainId?: number;
+    /** Nonce */
+    nonce?: string;
+    /** Expiration timestamp */
+    validUntil?: number;
+    /** Additional fields for specific schemes */
+    [key: string]: unknown;
+}
+interface VerifyResponse {
+    /** Whether the payment is valid */
+    valid: boolean;
+    /** Error message if invalid */
+    error?: string;
+    /** Additional verification details */
+    details?: {
+        /** Verified amount */
+        amount?: string;
+        /** Verified recipient */
+        recipient?: string;
+        /** Payment scheme used */
+        scheme?: string;
+    };
+}
+interface SettleResponse {
+    /** Whether settlement was successful */
+    success: boolean;
+    /** Transaction hash/signature */
+    transactionHash?: string;
+    /** Network the transaction was settled on */
+    network?: string;
+    /** Error message if failed */
+    error?: string;
+}
+interface SupportedResponse {
+    /** Supported payment kinds */
+    kinds: PaymentKind[];
+    /** Signer addresses by network namespace */
+    signers?: Record<string, string[]>;
+    /** Supported extensions */
+    extensions?: string[];
+}
+interface PaymentKind {
+    /** x402 version */
+    x402Version: 1 | 2;
+    /** Payment scheme */
+    scheme: string;
+    /** Network identifier */
+    network: string;
+    /** Extra data (e.g., feePayer for Solana) */
+    extra?: {
+        feePayer?: string;
+        [key: string]: unknown;
+    };
+}
+type NetworkType = 'evm' | 'solana';
+interface NetworkInfo {
+    /** v1 identifier (e.g., "base") */
+    v1Id: string;
+    /** v2 CAIP-2 identifier (e.g., "eip155:8453") */
+    v2Id: string;
+    /** Human-readable name */
+    name: string;
+    /** Network type */
+    type: NetworkType;
+    /** Chain ID (EVM only) */
+    chainId?: number;
+    /** Whether this is a testnet */
+    testnet: boolean;
+}
+
+declare class OpenFacilitator {
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly headers;
+    constructor(config: FacilitatorConfig);
+    /**
+     * Get the facilitator URL
+     */
+    get url(): string;
+    /**
+     * Verify a payment is valid
+     */
+    verify(payment: PaymentPayload): Promise<VerifyResponse>;
+    /**
+     * Settle/broadcast a payment transaction
+     */
+    settle(payment: PaymentPayload): Promise<SettleResponse>;
+    /**
+     * Get supported networks and payment kinds
+     */
+    supported(): Promise<SupportedResponse>;
+    /**
+     * Health check - verify facilitator is reachable
+     */
+    health(): Promise<boolean>;
+    /**
+     * Internal request helper
+     */
+    private request;
+}
+/**
+ * Create a facilitator client with default OpenFacilitator URL
+ */
+declare function createDefaultFacilitator(): OpenFacilitator;
+
+declare class FacilitatorError extends Error {
+    code: string;
+    statusCode?: number | undefined;
+    details?: unknown | undefined;
+    constructor(message: string, code: string, statusCode?: number | undefined, details?: unknown | undefined);
+}
+declare class NetworkError extends FacilitatorError {
+    constructor(message: string, details?: unknown);
+}
+declare class VerificationError extends FacilitatorError {
+    constructor(message: string, details?: unknown);
+}
+declare class SettlementError extends FacilitatorError {
+    constructor(message: string, details?: unknown);
+}
+declare class ConfigurationError extends FacilitatorError {
+    constructor(message: string);
+}
+
+declare const NETWORKS: NetworkInfo[];
+/**
+ * Get network info by v1 or v2 identifier
+ */
+declare function getNetwork(id: string): NetworkInfo | undefined;
+/**
+ * Get network type from identifier
+ */
+declare function getNetworkType(id: string): 'evm' | 'solana' | undefined;
+/**
+ * Convert v1 network ID to v2 (CAIP-2)
+ */
+declare function toV2NetworkId(id: string): string;
+/**
+ * Convert v2 network ID to v1
+ */
+declare function toV1NetworkId(id: string): string;
+/**
+ * Check if network ID is valid
+ */
+declare function isValidNetwork(id: string): boolean;
+/**
+ * Get all mainnet networks
+ */
+declare function getMainnets(): NetworkInfo[];
+/**
+ * Get all testnet networks
+ */
+declare function getTestnets(): NetworkInfo[];
+
+/**
+ * Type guard for checking if value is a valid payment payload
+ */
+declare function isPaymentPayload(value: unknown): value is PaymentPayload;
+
+export { ConfigurationError, type FacilitatorConfig, FacilitatorError, NETWORKS, NetworkError, type NetworkInfo, type NetworkType, OpenFacilitator, type PaymentAuthorization, type PaymentKind, type PaymentPayload, type SettleResponse, SettlementError, type SupportedResponse, VerificationError, type VerifyResponse, createDefaultFacilitator, getMainnets, getNetwork, getNetworkType, getTestnets, isPaymentPayload, isValidNetwork, toV1NetworkId, toV2NetworkId };

package/dist/index.js

@@ -0,0 +1,285 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ConfigurationError: () => ConfigurationError,
+  FacilitatorError: () => FacilitatorError,
+  NETWORKS: () => NETWORKS,
+  NetworkError: () => NetworkError,
+  OpenFacilitator: () => OpenFacilitator,
+  SettlementError: () => SettlementError,
+  VerificationError: () => VerificationError,
+  createDefaultFacilitator: () => createDefaultFacilitator,
+  getMainnets: () => getMainnets,
+  getNetwork: () => getNetwork,
+  getNetworkType: () => getNetworkType,
+  getTestnets: () => getTestnets,
+  isPaymentPayload: () => isPaymentPayload,
+  isValidNetwork: () => isValidNetwork,
+  toV1NetworkId: () => toV1NetworkId,
+  toV2NetworkId: () => toV2NetworkId
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var FacilitatorError = class extends Error {
+  constructor(message, code, statusCode, details) {
+    super(message);
+    this.code = code;
+    this.statusCode = statusCode;
+    this.details = details;
+    this.name = "FacilitatorError";
+  }
+};
+var NetworkError = class extends FacilitatorError {
+  constructor(message, details) {
+    super(message, "NETWORK_ERROR", void 0, details);
+    this.name = "NetworkError";
+  }
+};
+var VerificationError = class extends FacilitatorError {
+  constructor(message, details) {
+    super(message, "VERIFICATION_ERROR", void 0, details);
+    this.name = "VerificationError";
+  }
+};
+var SettlementError = class extends FacilitatorError {
+  constructor(message, details) {
+    super(message, "SETTLEMENT_ERROR", void 0, details);
+    this.name = "SettlementError";
+  }
+};
+var ConfigurationError = class extends FacilitatorError {
+  constructor(message) {
+    super(message, "CONFIGURATION_ERROR");
+    this.name = "ConfigurationError";
+  }
+};
+
+// src/utils.ts
+function normalizeUrl(url) {
+  return url.replace(/\/+$/, "");
+}
+function buildUrl(baseUrl, path) {
+  return `${normalizeUrl(baseUrl)}${path}`;
+}
+function isPaymentPayload(value) {
+  if (!value || typeof value !== "object") return false;
+  const obj = value;
+  return (obj.x402Version === 1 || obj.x402Version === 2) && typeof obj.scheme === "string" && typeof obj.network === "string" && obj.payload !== void 0;
+}
+
+// src/client.ts
+var DEFAULT_TIMEOUT = 3e4;
+var OpenFacilitator = class {
+  constructor(config) {
+    if (!config.url) {
+      throw new ConfigurationError("Facilitator URL is required");
+    }
+    this.baseUrl = normalizeUrl(config.url);
+    this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
+    this.headers = {
+      "Content-Type": "application/json",
+      ...config.headers
+    };
+  }
+  /**
+   * Get the facilitator URL
+   */
+  get url() {
+    return this.baseUrl;
+  }
+  /**
+   * Verify a payment is valid
+   */
+  async verify(payment) {
+    try {
+      const response = await this.request("/verify", {
+        method: "POST",
+        body: JSON.stringify(payment)
+      });
+      return response;
+    } catch (error) {
+      if (error instanceof FacilitatorError) throw error;
+      throw new VerificationError(
+        `Verification failed: ${error instanceof Error ? error.message : "Unknown error"}`,
+        error
+      );
+    }
+  }
+  /**
+   * Settle/broadcast a payment transaction
+   */
+  async settle(payment) {
+    try {
+      const response = await this.request("/settle", {
+        method: "POST",
+        body: JSON.stringify(payment)
+      });
+      return response;
+    } catch (error) {
+      if (error instanceof FacilitatorError) throw error;
+      throw new SettlementError(
+        `Settlement failed: ${error instanceof Error ? error.message : "Unknown error"}`,
+        error
+      );
+    }
+  }
+  /**
+   * Get supported networks and payment kinds
+   */
+  async supported() {
+    try {
+      const response = await this.request("/supported", {
+        method: "GET"
+      });
+      return response;
+    } catch (error) {
+      if (error instanceof FacilitatorError) throw error;
+      throw new NetworkError(
+        `Failed to fetch supported networks: ${error instanceof Error ? error.message : "Unknown error"}`,
+        error
+      );
+    }
+  }
+  /**
+   * Health check - verify facilitator is reachable
+   */
+  async health() {
+    try {
+      await this.supported();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Internal request helper
+   */
+  async request(path, init) {
+    const url = buildUrl(this.baseUrl, path);
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch(url, {
+        ...init,
+        headers: {
+          ...this.headers,
+          ...init.headers
+        },
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      if (!response.ok) {
+        let errorMessage = `HTTP ${response.status}`;
+        try {
+          const errorBody = await response.json();
+          errorMessage = errorBody.error || errorBody.message || errorMessage;
+        } catch {
+        }
+        throw new FacilitatorError(errorMessage, "HTTP_ERROR", response.status);
+      }
+      return await response.json();
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof FacilitatorError) throw error;
+      if (error instanceof Error && error.name === "AbortError") {
+        throw new NetworkError(`Request timeout after ${this.timeout}ms`);
+      }
+      throw new NetworkError(
+        `Request failed: ${error instanceof Error ? error.message : "Unknown error"}`,
+        error
+      );
+    }
+  }
+};
+function createDefaultFacilitator() {
+  return new OpenFacilitator({
+    url: "https://x402.openfacilitator.io"
+  });
+}
+
+// src/networks.ts
+var NETWORKS = [
+  // EVM Mainnets
+  { v1Id: "base", v2Id: "eip155:8453", name: "Base", type: "evm", chainId: 8453, testnet: false },
+  { v1Id: "polygon", v2Id: "eip155:137", name: "Polygon", type: "evm", chainId: 137, testnet: false },
+  { v1Id: "avalanche", v2Id: "eip155:43114", name: "Avalanche", type: "evm", chainId: 43114, testnet: false },
+  { v1Id: "sei", v2Id: "eip155:1329", name: "Sei", type: "evm", chainId: 1329, testnet: false },
+  { v1Id: "iotex", v2Id: "eip155:4689", name: "IoTeX", type: "evm", chainId: 4689, testnet: false },
+  { v1Id: "peaq", v2Id: "eip155:3338", name: "Peaq", type: "evm", chainId: 3338, testnet: false },
+  { v1Id: "xlayer", v2Id: "eip155:196", name: "X Layer", type: "evm", chainId: 196, testnet: false },
+  // EVM Testnets
+  { v1Id: "base-sepolia", v2Id: "eip155:84532", name: "Base Sepolia", type: "evm", chainId: 84532, testnet: true },
+  { v1Id: "polygon-amoy", v2Id: "eip155:80002", name: "Polygon Amoy", type: "evm", chainId: 80002, testnet: true },
+  { v1Id: "avalanche-fuji", v2Id: "eip155:43113", name: "Avalanche Fuji", type: "evm", chainId: 43113, testnet: true },
+  { v1Id: "sei-testnet", v2Id: "eip155:1328", name: "Sei Testnet", type: "evm", chainId: 1328, testnet: true },
+  { v1Id: "xlayer-testnet", v2Id: "eip155:195", name: "X Layer Testnet", type: "evm", chainId: 195, testnet: true },
+  // Solana
+  { v1Id: "solana", v2Id: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp", name: "Solana", type: "solana", testnet: false },
+  { v1Id: "solana-devnet", v2Id: "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1", name: "Solana Devnet", type: "solana", testnet: true }
+];
+function getNetwork(id) {
+  return NETWORKS.find((n) => n.v1Id === id || n.v2Id === id);
+}
+function getNetworkType(id) {
+  const network = getNetwork(id);
+  if (network) return network.type;
+  if (id.startsWith("eip155:")) return "evm";
+  if (id.startsWith("solana:")) return "solana";
+  return void 0;
+}
+function toV2NetworkId(id) {
+  const network = getNetwork(id);
+  return network?.v2Id ?? id;
+}
+function toV1NetworkId(id) {
+  const network = getNetwork(id);
+  return network?.v1Id ?? id;
+}
+function isValidNetwork(id) {
+  return getNetwork(id) !== void 0;
+}
+function getMainnets() {
+  return NETWORKS.filter((n) => !n.testnet);
+}
+function getTestnets() {
+  return NETWORKS.filter((n) => n.testnet);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ConfigurationError,
+  FacilitatorError,
+  NETWORKS,
+  NetworkError,
+  OpenFacilitator,
+  SettlementError,
+  VerificationError,
+  createDefaultFacilitator,
+  getMainnets,
+  getNetwork,
+  getNetworkType,
+  getTestnets,
+  isPaymentPayload,
+  isValidNetwork,
+  toV1NetworkId,
+  toV2NetworkId
+});

package/dist/index.mjs

@@ -0,0 +1,243 @@
+// src/errors.ts
+var FacilitatorError = class extends Error {
+  constructor(message, code, statusCode, details) {
+    super(message);
+    this.code = code;
+    this.statusCode = statusCode;
+    this.details = details;
+    this.name = "FacilitatorError";
+  }
+};
+var NetworkError = class extends FacilitatorError {
+  constructor(message, details) {
+    super(message, "NETWORK_ERROR", void 0, details);
+    this.name = "NetworkError";
+  }
+};
+var VerificationError = class extends FacilitatorError {
+  constructor(message, details) {
+    super(message, "VERIFICATION_ERROR", void 0, details);
+    this.name = "VerificationError";
+  }
+};
+var SettlementError = class extends FacilitatorError {
+  constructor(message, details) {
+    super(message, "SETTLEMENT_ERROR", void 0, details);
+    this.name = "SettlementError";
+  }
+};
+var ConfigurationError = class extends FacilitatorError {
+  constructor(message) {
+    super(message, "CONFIGURATION_ERROR");
+    this.name = "ConfigurationError";
+  }
+};
+
+// src/utils.ts
+function normalizeUrl(url) {
+  return url.replace(/\/+$/, "");
+}
+function buildUrl(baseUrl, path) {
+  return `${normalizeUrl(baseUrl)}${path}`;
+}
+function isPaymentPayload(value) {
+  if (!value || typeof value !== "object") return false;
+  const obj = value;
+  return (obj.x402Version === 1 || obj.x402Version === 2) && typeof obj.scheme === "string" && typeof obj.network === "string" && obj.payload !== void 0;
+}
+
+// src/client.ts
+var DEFAULT_TIMEOUT = 3e4;
+var OpenFacilitator = class {
+  constructor(config) {
+    if (!config.url) {
+      throw new ConfigurationError("Facilitator URL is required");
+    }
+    this.baseUrl = normalizeUrl(config.url);
+    this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
+    this.headers = {
+      "Content-Type": "application/json",
+      ...config.headers
+    };
+  }
+  /**
+   * Get the facilitator URL
+   */
+  get url() {
+    return this.baseUrl;
+  }
+  /**
+   * Verify a payment is valid
+   */
+  async verify(payment) {
+    try {
+      const response = await this.request("/verify", {
+        method: "POST",
+        body: JSON.stringify(payment)
+      });
+      return response;
+    } catch (error) {
+      if (error instanceof FacilitatorError) throw error;
+      throw new VerificationError(
+        `Verification failed: ${error instanceof Error ? error.message : "Unknown error"}`,
+        error
+      );
+    }
+  }
+  /**
+   * Settle/broadcast a payment transaction
+   */
+  async settle(payment) {
+    try {
+      const response = await this.request("/settle", {
+        method: "POST",
+        body: JSON.stringify(payment)
+      });
+      return response;
+    } catch (error) {
+      if (error instanceof FacilitatorError) throw error;
+      throw new SettlementError(
+        `Settlement failed: ${error instanceof Error ? error.message : "Unknown error"}`,
+        error
+      );
+    }
+  }
+  /**
+   * Get supported networks and payment kinds
+   */
+  async supported() {
+    try {
+      const response = await this.request("/supported", {
+        method: "GET"
+      });
+      return response;
+    } catch (error) {
+      if (error instanceof FacilitatorError) throw error;
+      throw new NetworkError(
+        `Failed to fetch supported networks: ${error instanceof Error ? error.message : "Unknown error"}`,
+        error
+      );
+    }
+  }
+  /**
+   * Health check - verify facilitator is reachable
+   */
+  async health() {
+    try {
+      await this.supported();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Internal request helper
+   */
+  async request(path, init) {
+    const url = buildUrl(this.baseUrl, path);
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch(url, {
+        ...init,
+        headers: {
+          ...this.headers,
+          ...init.headers
+        },
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      if (!response.ok) {
+        let errorMessage = `HTTP ${response.status}`;
+        try {
+          const errorBody = await response.json();
+          errorMessage = errorBody.error || errorBody.message || errorMessage;
+        } catch {
+        }
+        throw new FacilitatorError(errorMessage, "HTTP_ERROR", response.status);
+      }
+      return await response.json();
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof FacilitatorError) throw error;
+      if (error instanceof Error && error.name === "AbortError") {
+        throw new NetworkError(`Request timeout after ${this.timeout}ms`);
+      }
+      throw new NetworkError(
+        `Request failed: ${error instanceof Error ? error.message : "Unknown error"}`,
+        error
+      );
+    }
+  }
+};
+function createDefaultFacilitator() {
+  return new OpenFacilitator({
+    url: "https://x402.openfacilitator.io"
+  });
+}
+
+// src/networks.ts
+var NETWORKS = [
+  // EVM Mainnets
+  { v1Id: "base", v2Id: "eip155:8453", name: "Base", type: "evm", chainId: 8453, testnet: false },
+  { v1Id: "polygon", v2Id: "eip155:137", name: "Polygon", type: "evm", chainId: 137, testnet: false },
+  { v1Id: "avalanche", v2Id: "eip155:43114", name: "Avalanche", type: "evm", chainId: 43114, testnet: false },
+  { v1Id: "sei", v2Id: "eip155:1329", name: "Sei", type: "evm", chainId: 1329, testnet: false },
+  { v1Id: "iotex", v2Id: "eip155:4689", name: "IoTeX", type: "evm", chainId: 4689, testnet: false },
+  { v1Id: "peaq", v2Id: "eip155:3338", name: "Peaq", type: "evm", chainId: 3338, testnet: false },
+  { v1Id: "xlayer", v2Id: "eip155:196", name: "X Layer", type: "evm", chainId: 196, testnet: false },
+  // EVM Testnets
+  { v1Id: "base-sepolia", v2Id: "eip155:84532", name: "Base Sepolia", type: "evm", chainId: 84532, testnet: true },
+  { v1Id: "polygon-amoy", v2Id: "eip155:80002", name: "Polygon Amoy", type: "evm", chainId: 80002, testnet: true },
+  { v1Id: "avalanche-fuji", v2Id: "eip155:43113", name: "Avalanche Fuji", type: "evm", chainId: 43113, testnet: true },
+  { v1Id: "sei-testnet", v2Id: "eip155:1328", name: "Sei Testnet", type: "evm", chainId: 1328, testnet: true },
+  { v1Id: "xlayer-testnet", v2Id: "eip155:195", name: "X Layer Testnet", type: "evm", chainId: 195, testnet: true },
+  // Solana
+  { v1Id: "solana", v2Id: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp", name: "Solana", type: "solana", testnet: false },
+  { v1Id: "solana-devnet", v2Id: "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1", name: "Solana Devnet", type: "solana", testnet: true }
+];
+function getNetwork(id) {
+  return NETWORKS.find((n) => n.v1Id === id || n.v2Id === id);
+}
+function getNetworkType(id) {
+  const network = getNetwork(id);
+  if (network) return network.type;
+  if (id.startsWith("eip155:")) return "evm";
+  if (id.startsWith("solana:")) return "solana";
+  return void 0;
+}
+function toV2NetworkId(id) {
+  const network = getNetwork(id);
+  return network?.v2Id ?? id;
+}
+function toV1NetworkId(id) {
+  const network = getNetwork(id);
+  return network?.v1Id ?? id;
+}
+function isValidNetwork(id) {
+  return getNetwork(id) !== void 0;
+}
+function getMainnets() {
+  return NETWORKS.filter((n) => !n.testnet);
+}
+function getTestnets() {
+  return NETWORKS.filter((n) => n.testnet);
+}
+export {
+  ConfigurationError,
+  FacilitatorError,
+  NETWORKS,
+  NetworkError,
+  OpenFacilitator,
+  SettlementError,
+  VerificationError,
+  createDefaultFacilitator,
+  getMainnets,
+  getNetwork,
+  getNetworkType,
+  getTestnets,
+  isPaymentPayload,
+  isValidNetwork,
+  toV1NetworkId,
+  toV2NetworkId
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@openfacilitator/sdk",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for x402 payment facilitation",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "test": "vitest",
+    "lint": "eslint src/",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "x402",
+    "payments",
+    "crypto",
+    "facilitator",
+    "solana",
+    "evm",
+    "base"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/your-repo/openfacilitator"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}