@oobe-protocol-labs/synapse-client-sdk 1.0.0-beta → 1.0.2

package/dist/esm/ai/gateway/x402/facilitator.js

@@ -0,0 +1,284 @@
+/**
+ * @module ai/gateway/x402/facilitator
+ * @description x402 Facilitator Client — HTTP client for the x402 facilitator service.
+ *
+ * The facilitator is a third-party service that:
+ *  1. Verifies payment payloads (checks signatures, balances, allowances)
+ *  2. Settles payments on-chain (co-signs, submits, confirms)
+ *  3. Reports supported payment kinds (scheme + network pairs)
+ *
+ * Supports both direct URL config and known facilitator selection:
+ *
+ * @example
+ * ```ts
+ * // Known facilitator (one-liner)
+ * const f = createFacilitator(KnownFacilitator.PayAI);
+ *
+ * // Custom URL
+ * const f = createFacilitator({ url: 'https://my-facilitator.com' });
+ * ```
+ *
+ * @since 1.0.0
+ */
+import { KnownFacilitator } from './types.js';
+import { resolveKnownFacilitator } from './registry.js';
+/* ═══════════════════════════════════════════════════════════════
+ *  Constants
+ * ═══════════════════════════════════════════════════════════════ */
+const DEFAULT_FACILITATOR_URL = 'https://facilitator.payai.network';
+const DEFAULT_TIMEOUT_MS = 30_000;
+/* ═══════════════════════════════════════════════════════════════
+ *  Errors
+ * ═══════════════════════════════════════════════════════════════ */
+/**
+ * @description Error thrown by the FacilitatorClient when a request fails.
+ * @since 1.0.0
+ */
+export class FacilitatorError extends Error {
+    endpoint;
+    statusCode;
+    responseBody;
+    constructor(message, endpoint, statusCode, responseBody) {
+        super(message);
+        this.endpoint = endpoint;
+        this.statusCode = statusCode;
+        this.responseBody = responseBody;
+        this.name = 'FacilitatorError';
+    }
+}
+/**
+ * @description Error thrown when payment verification fails at the facilitator.
+ * @since 1.0.0
+ */
+export class VerifyError extends FacilitatorError {
+    constructor(statusCode, response) {
+        super(`Payment verification failed: ${response.invalidReason ?? 'unknown'}`, '/verify', statusCode, response);
+        this.name = 'VerifyError';
+    }
+}
+/**
+ * @description Error thrown when payment settlement fails at the facilitator.
+ * @since 1.0.0
+ */
+export class SettleError extends FacilitatorError {
+    constructor(statusCode, response) {
+        super(`Payment settlement failed: ${response.errorReason ?? 'unknown'}`, '/settle', statusCode, response);
+        this.name = 'SettleError';
+    }
+}
+/* ═══════════════════════════════════════════════════════════════
+ *  FacilitatorClient
+ * ═══════════════════════════════════════════════════════════════ */
+/**
+ * @description HTTP client for an x402 facilitator.
+ *
+ * @example
+ * ```ts
+ * // From known facilitator enum
+ * const facilitator = new FacilitatorClient(KnownFacilitator.PayAI);
+ *
+ * // From config object
+ * const facilitator = new FacilitatorClient({
+ *   url: 'https://x402.org/facilitator',
+ *   createAuthHeaders: async () => ({
+ *     verify: { Authorization: 'Bearer ...' },
+ *     settle: { Authorization: 'Bearer ...' },
+ *     supported: {},
+ *   }),
+ * });
+ *
+ * const verifyResult = await facilitator.verify(payload, requirements);
+ * const settleResult = await facilitator.settle(payload, requirements);
+ * const supported = await facilitator.supported();
+ * ```
+ *
+ * @since 1.0.0
+ */
+export class FacilitatorClient {
+    url;
+    config;
+    /** @description The known facilitator id if one was used, otherwise undefined @since 1.0.0 */
+    knownFacilitator;
+    /**
+     * @description Create a new FacilitatorClient.
+     * @param {KnownFacilitator | Partial<X402FacilitatorConfig>} [config] - Known facilitator enum or custom config. Defaults to PayAI free tier.
+     * @since 1.0.0
+     */
+    constructor(config) {
+        // Resolve known facilitator enum to config
+        if (typeof config === 'string' && Object.values(KnownFacilitator).includes(config)) {
+            this.knownFacilitator = config;
+            const resolved = resolveKnownFacilitator(config);
+            this.config = resolved;
+        }
+        else {
+            const cfg = config;
+            this.config = {
+                url: cfg?.url ?? DEFAULT_FACILITATOR_URL,
+                createAuthHeaders: cfg?.createAuthHeaders,
+                timeoutMs: cfg?.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+            };
+        }
+        this.url = this.config.url.replace(/\/$/, ''); // strip trailing slash
+    }
+    /* ── Verify ──────────────────────────────────────────────── */
+    /**
+     * @description Verify a payment payload against requirements.
+     * POST /verify
+     *
+     * @param {X402PaymentPayload} paymentPayload - The client's signed payment payload
+     * @param {X402PaymentRequirements} paymentRequirements - The accepted payment requirements
+     * @returns {Promise<X402VerifyResponse>} Verification result
+     * @throws {VerifyError} If verification fails
+     * @since 1.0.0
+     */
+    async verify(paymentPayload, paymentRequirements) {
+        const headers = await this.getHeaders('verify');
+        const res = await this.fetch(`${this.url}/verify`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', ...headers },
+            body: JSON.stringify({
+                paymentPayload: this.toJsonSafe(paymentPayload),
+                paymentRequirements: this.toJsonSafe(paymentRequirements),
+            }),
+        });
+        const data = await res.json();
+        if (res.status !== 200 || !data.isValid) {
+            throw new VerifyError(res.status, data);
+        }
+        return data;
+    }
+    /* ── Settle ──────────────────────────────────────────────── */
+    /**
+     * @description Settle a verified payment on-chain.
+     * POST /settle
+     *
+     * @param {X402PaymentPayload} paymentPayload - The client's signed payment payload
+     * @param {X402PaymentRequirements} paymentRequirements - The accepted payment requirements
+     * @returns {Promise<X402SettleResponse>} Settlement result with on-chain tx signature
+     * @throws {SettleError} If settlement fails
+     * @since 1.0.0
+     */
+    async settle(paymentPayload, paymentRequirements) {
+        const headers = await this.getHeaders('settle');
+        const res = await this.fetch(`${this.url}/settle`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', ...headers },
+            body: JSON.stringify({
+                paymentPayload: this.toJsonSafe(paymentPayload),
+                paymentRequirements: this.toJsonSafe(paymentRequirements),
+            }),
+        });
+        const data = await res.json();
+        if (res.status !== 200 || !data.success) {
+            throw new SettleError(res.status, data);
+        }
+        return data;
+    }
+    /* ── Supported ───────────────────────────────────────────── */
+    /**
+     * @description Query the facilitator for supported payment kinds.
+     * GET /supported
+     *
+     * @returns {Promise<X402SupportedResponse>} Supported scheme + network pairs (+ extra like feePayer)
+     * @throws {FacilitatorError} If the request fails
+     * @since 1.0.0
+     */
+    async supported() {
+        const headers = await this.getHeaders('supported');
+        const res = await this.fetch(`${this.url}/supported`, {
+            method: 'GET',
+            headers,
+        });
+        if (res.status !== 200) {
+            throw new FacilitatorError(`Failed to fetch supported kinds: ${res.status} ${res.statusText}`, '/supported', res.status);
+        }
+        return await res.json();
+    }
+    /* ── Helpers ─────────────────────────────────────────────── */
+    async getHeaders(endpoint) {
+        if (!this.config.createAuthHeaders)
+            return {};
+        const authHeaders = await this.config.createAuthHeaders();
+        return authHeaders[endpoint] ?? {};
+    }
+    /**
+     * @description Fetch with timeout support via AbortController.
+     * @param {string} url - The URL to fetch
+     * @param {RequestInit} init - Fetch options
+     * @returns {Promise<Response>} The response
+     * @throws {FacilitatorError} On timeout
+     * @since 1.0.0
+     */
+    async fetch(url, init) {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.config.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+        try {
+            return await globalThis.fetch(url, {
+                ...init,
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            if (err.name === 'AbortError') {
+                throw new FacilitatorError(`Facilitator request timed out after ${this.config.timeoutMs}ms`, url, 0);
+            }
+            throw err;
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    /**
+     * @description Ensure BigInt values are serialized as strings for JSON transport.
+     * @param {unknown} obj - The object to serialize
+     * @returns {unknown} A JSON-safe copy of the object
+     * @since 1.0.0
+     */
+    toJsonSafe(obj) {
+        return JSON.parse(JSON.stringify(obj, (_key, value) => typeof value === 'bigint' ? value.toString() : value));
+    }
+    /**
+     * @description Get the configured facilitator URL.
+     * @returns {string} The facilitator base URL
+     * @since 1.0.0
+     */
+    get facilitatorUrl() {
+        return this.url;
+    }
+}
+/* ═══════════════════════════════════════════════════════════════
+ *  Factory
+ * ═══════════════════════════════════════════════════════════════ */
+/**
+ * @description Create a facilitator client from a known facilitator enum or custom config.
+ *
+ * @example
+ * ```ts
+ * import { createFacilitator, KnownFacilitator } from '@oobe-protocol-labs/synapse-client-sdk';
+ *
+ * // One-liner with a known facilitator
+ * const facilitator = createFacilitator(KnownFacilitator.PayAI);
+ * const facilitator = createFacilitator(KnownFacilitator.RelAI);
+ * const facilitator = createFacilitator(KnownFacilitator.Dexter);
+ * const facilitator = createFacilitator(KnownFacilitator.CDP);
+ *
+ * // Custom URL
+ * const facilitator = createFacilitator({ url: 'https://my-facilitator.com' });
+ *
+ * // Known facilitator + auth override
+ * const facilitator = createFacilitator(KnownFacilitator.PayAI);
+ * // Then set PAYAI_API_KEY_ID / PAYAI_API_KEY_SECRET env vars for production.
+ *
+ * // Default (PayAI free tier)
+ * const facilitator = createFacilitator();
+ * ```
+ *
+ * @param {KnownFacilitator | Partial<X402FacilitatorConfig>} [config] - Known facilitator or custom config
+ * @returns {FacilitatorClient} A new FacilitatorClient instance
+ * @since 1.0.0
+ */
+export function createFacilitator(config) {
+    return new FacilitatorClient(config);
+}
+//# sourceMappingURL=facilitator.js.map

package/dist/esm/ai/gateway/x402/facilitator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"facilitator.js","sourceRoot":"","sources":["../../../../../src/ai/gateway/x402/facilitator.ts"],"names":[],"mappings":"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"}

package/dist/esm/ai/gateway/x402/index.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @module ai/gateway/x402
+ * @description x402 Protocol Module — HTTP-native payments for agent-to-agent commerce.
+ *
+ * This module implements the Coinbase x402 protocol v1 & v2 for Solana and Base (EVM),
+ * enabling agents to buy and sell RPC access using on-chain stablecoin payments.
+ *
+ * Architecture:
+ *  - types.ts       — Canonical x402 v1/v2 type definitions + enums
+ *  - registry.ts    — Known facilitator registry (PayAI, Dexter, RelAI, CDP, ...)
+ *  - facilitator.ts — HTTP client for the facilitator service
+ *  - paywall.ts     — Resource server side (seller generates 402 responses)
+ *  - client.ts      — Buyer side (handles 402 responses, signs payments)
+ *
+ * The developer controls all configuration: facilitator selection, auth headers,
+ * signer, pricing, network, and asset.
+ *
+ * @example Quick start with known facilitator
+ * ```ts
+ * import { createFacilitator, KnownFacilitator } from '@oobe-protocol-labs/synapse-client-sdk';
+ *
+ * const facilitator = createFacilitator(KnownFacilitator.PayAI);
+ * const supported = await facilitator.supported();
+ * ```
+ *
+ * @example Resource Server (Seller) on Solana
+ * ```ts
+ * import { X402Paywall, KnownFacilitator, SOLANA_MAINNET, USDC_SOLANA_MAINNET } from '@oobe-protocol-labs/synapse-client-sdk';
+ *
+ * const paywall = new X402Paywall({
+ *   enabled: true,
+ *   payTo: 'YourSolanaWalletAddress',
+ *   facilitator: { url: 'https://facilitator.payai.network' },
+ *   defaultNetwork: SOLANA_MAINNET,
+ *   defaultAsset: USDC_SOLANA_MAINNET,
+ *   defaultPrice: '1000', // 0.001 USDC per call
+ * });
+ * ```
+ *
+ * @example Resource Server (Seller) on Base
+ * ```ts
+ * import { X402Paywall, BASE_MAINNET, USDC_BASE_MAINNET } from '@oobe-protocol-labs/synapse-client-sdk';
+ *
+ * const paywall = new X402Paywall({
+ *   enabled: true,
+ *   payTo: '0xYourEthAddress',
+ *   facilitator: { url: 'https://facilitator.x402.fi' },
+ *   defaultNetwork: BASE_MAINNET,
+ *   defaultAsset: USDC_BASE_MAINNET,
+ *   defaultPrice: '1000',
+ * });
+ * ```
+ *
+ * @example Client (Buyer)
+ * ```ts
+ * import { X402Client, SOLANA_MAINNET, USDC_SOLANA_MAINNET } from '@oobe-protocol-labs/synapse-client-sdk';
+ *
+ * const client = new X402Client({
+ *   enabled: true,
+ *   signer: async (requirements, resource) => {
+ *     return { x402Version: 2, accepted: requirements, resource, payload: { transaction: '...' } };
+ *   },
+ *   preferredNetwork: SOLANA_MAINNET,
+ *   preferredAsset: USDC_SOLANA_MAINNET,
+ *   maxAmountPerCall: '10000',
+ * });
+ * ```
+ *
+ * @since 1.0.0
+ */
+export type { X402Network, X402ResourceInfo, X402PaymentRequirements, X402PaymentRequired, X402PaymentPayload, ExactSvmPayload, ExactEvmEip3009Payload, ExactEvmPermit2Payload, X402VerifyResponse, X402SettleResponse, X402SettlementResponse, X402CreateAuthHeaders, X402FacilitatorConfig, X402SupportedKind, X402SupportedResponse, X402RouteConfig, X402Config, KnownFacilitatorInfo, } from './types';
+export { SOLANA_MAINNET, SOLANA_DEVNET, USDC_SOLANA_MAINNET, USDC_SOLANA_DEVNET, USDC_MAINNET, // deprecated alias
+USDC_DEVNET, // deprecated alias
+BASE_MAINNET, BASE_SEPOLIA, ETHEREUM_MAINNET, POLYGON_MAINNET, AVALANCHE_MAINNET, SEI_MAINNET, USDC_BASE_MAINNET, USDC_BASE_SEPOLIA, USDC_ETHEREUM_MAINNET, X402_PERMIT2_PROXY, SVM_NETWORKS, EVM_NETWORKS, isSvmNetwork, isEvmNetwork, KnownFacilitator, EvmTransferMethod, X402ProtocolVersion, X402_HEADER_PAYMENT_REQUIRED, X402_HEADER_PAYMENT_SIGNATURE, X402_HEADER_PAYMENT_RESPONSE, X402_STATUS_CODE, X402_VERSION, } from './types';
+export { FACILITATOR_REGISTRY, getFacilitatorInfo, findFacilitatorsByNetwork, findGasSponsoredFacilitators, listKnownFacilitators, resolveKnownFacilitator, } from './registry';
+export { FacilitatorClient, FacilitatorError, VerifyError, SettleError, createFacilitator, } from './facilitator';
+export { X402Paywall, encodePaymentHeader, decodePaymentHeader, } from './paywall';
+export type { PaywallResult, SettleResult, } from './paywall';
+export { X402Client, X402ClientError, NoAcceptablePaymentError, PaymentSigningError, PaymentRetryError, defaultRequirementsSelector, createX402Client, } from './client';
+export type { X402PayloadSigner, X402RequirementsSelector, X402BudgetCheck, X402ClientConfig, X402PaymentOutcome, } from './client';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/ai/gateway/x402/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/ai/gateway/x402/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqEG;AAGH,YAAY,EACV,WAAW,EACX,gBAAgB,EAChB,uBAAuB,EACvB,mBAAmB,EACnB,kBAAkB,EAClB,eAAe,EACf,sBAAsB,EACtB,sBAAsB,EACtB,kBAAkB,EAClB,kBAAkB,EAClB,sBAAsB,EACtB,qBAAqB,EACrB,qBAAqB,EACrB,iBAAiB,EACjB,qBAAqB,EACrB,eAAe,EACf,UAAU,EACV,oBAAoB,GACrB,MAAM,SAAS,CAAC;AAEjB,OAAO,EAEL,cAAc,EACd,aAAa,EACb,mBAAmB,EACnB,kBAAkB,EAClB,YAAY,EAAG,mBAAmB;AAClC,WAAW,EAAI,mBAAmB;AAGlC,YAAY,EACZ,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,WAAW,EACX,iBAAiB,EACjB,iBAAiB,EACjB,qBAAqB,EACrB,kBAAkB,EAGlB,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,YAAY,EAGZ,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EAGnB,4BAA4B,EAC5B,6BAA6B,EAC7B,4BAA4B,EAC5B,gBAAgB,EAChB,YAAY,GACb,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,yBAAyB,EACzB,4BAA4B,EAC5B,qBAAqB,EACrB,uBAAuB,GACxB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,WAAW,EACX,WAAW,EACX,iBAAiB,GAClB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,WAAW,EACX,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,WAAW,CAAC;AAEnB,YAAY,EACV,aAAa,EACb,YAAY,GACb,MAAM,WAAW,CAAC;AAGnB,OAAO,EACL,UAAU,EACV,eAAe,EACf,wBAAwB,EACxB,mBAAmB,EACnB,iBAAiB,EACjB,2BAA2B,EAC3B,gBAAgB,GACjB,MAAM,UAAU,CAAC;AAElB,YAAY,EACV,iBAAiB,EACjB,wBAAwB,EACxB,eAAe,EACf,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,UAAU,CAAC"}

package/dist/esm/ai/gateway/x402/index.js

@@ -0,0 +1,91 @@
+/**
+ * @module ai/gateway/x402
+ * @description x402 Protocol Module — HTTP-native payments for agent-to-agent commerce.
+ *
+ * This module implements the Coinbase x402 protocol v1 & v2 for Solana and Base (EVM),
+ * enabling agents to buy and sell RPC access using on-chain stablecoin payments.
+ *
+ * Architecture:
+ *  - types.ts       — Canonical x402 v1/v2 type definitions + enums
+ *  - registry.ts    — Known facilitator registry (PayAI, Dexter, RelAI, CDP, ...)
+ *  - facilitator.ts — HTTP client for the facilitator service
+ *  - paywall.ts     — Resource server side (seller generates 402 responses)
+ *  - client.ts      — Buyer side (handles 402 responses, signs payments)
+ *
+ * The developer controls all configuration: facilitator selection, auth headers,
+ * signer, pricing, network, and asset.
+ *
+ * @example Quick start with known facilitator
+ * ```ts
+ * import { createFacilitator, KnownFacilitator } from '@oobe-protocol-labs/synapse-client-sdk';
+ *
+ * const facilitator = createFacilitator(KnownFacilitator.PayAI);
+ * const supported = await facilitator.supported();
+ * ```
+ *
+ * @example Resource Server (Seller) on Solana
+ * ```ts
+ * import { X402Paywall, KnownFacilitator, SOLANA_MAINNET, USDC_SOLANA_MAINNET } from '@oobe-protocol-labs/synapse-client-sdk';
+ *
+ * const paywall = new X402Paywall({
+ *   enabled: true,
+ *   payTo: 'YourSolanaWalletAddress',
+ *   facilitator: { url: 'https://facilitator.payai.network' },
+ *   defaultNetwork: SOLANA_MAINNET,
+ *   defaultAsset: USDC_SOLANA_MAINNET,
+ *   defaultPrice: '1000', // 0.001 USDC per call
+ * });
+ * ```
+ *
+ * @example Resource Server (Seller) on Base
+ * ```ts
+ * import { X402Paywall, BASE_MAINNET, USDC_BASE_MAINNET } from '@oobe-protocol-labs/synapse-client-sdk';
+ *
+ * const paywall = new X402Paywall({
+ *   enabled: true,
+ *   payTo: '0xYourEthAddress',
+ *   facilitator: { url: 'https://facilitator.x402.fi' },
+ *   defaultNetwork: BASE_MAINNET,
+ *   defaultAsset: USDC_BASE_MAINNET,
+ *   defaultPrice: '1000',
+ * });
+ * ```
+ *
+ * @example Client (Buyer)
+ * ```ts
+ * import { X402Client, SOLANA_MAINNET, USDC_SOLANA_MAINNET } from '@oobe-protocol-labs/synapse-client-sdk';
+ *
+ * const client = new X402Client({
+ *   enabled: true,
+ *   signer: async (requirements, resource) => {
+ *     return { x402Version: 2, accepted: requirements, resource, payload: { transaction: '...' } };
+ *   },
+ *   preferredNetwork: SOLANA_MAINNET,
+ *   preferredAsset: USDC_SOLANA_MAINNET,
+ *   maxAmountPerCall: '10000',
+ * });
+ * ```
+ *
+ * @since 1.0.0
+ */
+export { 
+/* ── Solana networks & assets ── */
+SOLANA_MAINNET, SOLANA_DEVNET, USDC_SOLANA_MAINNET, USDC_SOLANA_DEVNET, USDC_MAINNET, // deprecated alias
+USDC_DEVNET, // deprecated alias
+/* ── Base / EVM networks & assets ── */
+BASE_MAINNET, BASE_SEPOLIA, ETHEREUM_MAINNET, POLYGON_MAINNET, AVALANCHE_MAINNET, SEI_MAINNET, USDC_BASE_MAINNET, USDC_BASE_SEPOLIA, USDC_ETHEREUM_MAINNET, X402_PERMIT2_PROXY, 
+/* ── Network collections & helpers ── */
+SVM_NETWORKS, EVM_NETWORKS, isSvmNetwork, isEvmNetwork, 
+/* ── Enums ── */
+KnownFacilitator, EvmTransferMethod, X402ProtocolVersion, 
+/* ── Header constants ── */
+X402_HEADER_PAYMENT_REQUIRED, X402_HEADER_PAYMENT_SIGNATURE, X402_HEADER_PAYMENT_RESPONSE, X402_STATUS_CODE, X402_VERSION, } from './types.js';
+/* ── Facilitator Registry ────────────────────────────────────── */
+export { FACILITATOR_REGISTRY, getFacilitatorInfo, findFacilitatorsByNetwork, findGasSponsoredFacilitators, listKnownFacilitators, resolveKnownFacilitator, } from './registry.js';
+/* ── Facilitator Client ──────────────────────────────────────── */
+export { FacilitatorClient, FacilitatorError, VerifyError, SettleError, createFacilitator, } from './facilitator.js';
+/* ── Paywall (Resource Server / Seller) ──────────────────────── */
+export { X402Paywall, encodePaymentHeader, decodePaymentHeader, } from './paywall.js';
+/* ── Client (Buyer) ──────────────────────────────────────────── */
+export { X402Client, X402ClientError, NoAcceptablePaymentError, PaymentSigningError, PaymentRetryError, defaultRequirementsSelector, createX402Client, } from './client.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/ai/gateway/x402/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../src/ai/gateway/x402/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqEG;AAwBH,OAAO;AACL,oCAAoC;AACpC,cAAc,EACd,aAAa,EACb,mBAAmB,EACnB,kBAAkB,EAClB,YAAY,EAAG,mBAAmB;AAClC,WAAW,EAAI,mBAAmB;AAElC,wCAAwC;AACxC,YAAY,EACZ,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,WAAW,EACX,iBAAiB,EACjB,iBAAiB,EACjB,qBAAqB,EACrB,kBAAkB;AAElB,yCAAyC;AACzC,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,YAAY;AAEZ,iBAAiB;AACjB,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB;AAEnB,4BAA4B;AAC5B,4BAA4B,EAC5B,6BAA6B,EAC7B,4BAA4B,EAC5B,gBAAgB,EAChB,YAAY,GACb,MAAM,SAAS,CAAC;AAEjB,oEAAoE;AACpE,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,yBAAyB,EACzB,4BAA4B,EAC5B,qBAAqB,EACrB,uBAAuB,GACxB,MAAM,YAAY,CAAC;AAEpB,oEAAoE;AACpE,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,WAAW,EACX,WAAW,EACX,iBAAiB,GAClB,MAAM,eAAe,CAAC;AAEvB,oEAAoE;AACpE,OAAO,EACL,WAAW,EACX,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,WAAW,CAAC;AAOnB,oEAAoE;AACpE,OAAO,EACL,UAAU,EACV,eAAe,EACf,wBAAwB,EACxB,mBAAmB,EACnB,iBAAiB,EACjB,2BAA2B,EAC3B,gBAAgB,GACjB,MAAM,UAAU,CAAC"}

package/dist/esm/ai/gateway/x402/paywall.d.ts

@@ -0,0 +1,148 @@
+/**
+ * @module ai/gateway/x402/paywall
+ * @description x402 Paywall — Resource Server side of the x402 protocol.
+ *
+ * When the gateway acts as a SELLER, this module handles:
+ *  1. Generating 402 Payment Required responses with proper headers
+ *  2. Parsing incoming PAYMENT-SIGNATURE headers from buyers
+ *  3. Coordinating verify → execute → settle flow with the facilitator
+ *  4. Attaching PAYMENT-RESPONSE headers to successful responses
+ *
+ * The paywall is transport-agnostic: it produces header/body objects
+ * that can be used with Express, Hono, Next.js, raw HTTP, or any framework.
+ *
+ * @since 1.0.0
+ */
+import type { X402PaymentRequired, X402PaymentPayload, X402PaymentRequirements, X402VerifyResponse, X402SettleResponse, X402Config } from './types';
+import { FacilitatorClient } from './facilitator';
+/**
+ * @description Encode an object to base64 JSON (for x402 headers).
+ * @param {unknown} obj - The object to encode
+ * @returns {string} Base64-encoded JSON string
+ * @since 1.0.0
+ */
+export declare function encodePaymentHeader(obj: unknown): string;
+/**
+ * @description Decode a base64 JSON header back to an object.
+ * @template T The expected type of the decoded object
+ * @param {string} base64 - The base64-encoded JSON string
+ * @returns {T} The decoded object
+ * @since 1.0.0
+ */
+export declare function decodePaymentHeader<T>(base64: string): T;
+/**
+ * @description The result of processing an incoming request through the paywall.
+ * @since 1.0.0
+ */
+export type PaywallResult = {
+    type: 'payment-required';
+    statusCode: 402;
+    headers: Record<string, string>;
+    body: X402PaymentRequired;
+} | {
+    type: 'payment-valid';
+    verifyResponse: X402VerifyResponse;
+    paymentPayload: X402PaymentPayload;
+    requirements: X402PaymentRequirements;
+} | {
+    type: 'no-payment-needed';
+};
+/**
+ * @description The result of settling a payment after the resource was served.
+ * @since 1.0.0
+ */
+export interface SettleResult {
+    success: boolean;
+    settleResponse: X402SettleResponse | null;
+    /** Base64-encoded PAYMENT-RESPONSE header value */
+    responseHeader: string | null;
+}
+/**
+ * @description Resource Server paywall for x402.
+ *
+ * The developer provides an X402Config, and the paywall handles
+ * the full verify → execute → settle lifecycle.
+ *
+ * @example
+ * ```ts
+ * const paywall = new X402Paywall(x402Config);
+ *
+ * // On incoming request:
+ * const result = await paywall.processRequest('getBalance', headers);
+ *
+ * if (result.type === 'payment-required') {
+ *   return new Response(JSON.stringify(result.body), {
+ *     status: 402,
+ *     headers: result.headers,
+ *   });
+ * }
+ *
+ * if (result.type === 'payment-valid') {
+ *   // Execute the RPC call, then settle
+ *   const settle = await paywall.settleAfterResponse(
+ *     result.paymentPayload,
+ *     result.requirements,
+ *   );
+ *   // Attach settle.responseHeader to the response
+ * }
+ * ```
+ *
+ * @since 1.0.0
+ */
+export declare class X402Paywall {
+    private readonly config;
+    private readonly facilitator;
+    /** Cached supported kinds from the facilitator */
+    private supportedKindsCache;
+    private readonly supportedKindsCacheTtlMs;
+    /**
+     * @description Create a new X402Paywall.
+     * @param {X402Config} config - x402 configuration including facilitator and pricing
+     * @since 1.0.0
+     */
+    constructor(config: X402Config);
+    /**
+     * @description Process an incoming request and determine if payment is needed.
+     *
+     * @param {string} method - The RPC method being called (used to look up route config)
+     * @param {Record<string, string | undefined>} headers - Incoming HTTP headers (to check for PAYMENT-SIGNATURE)
+     * @returns {Promise<PaywallResult>} PaywallResult indicating what to do next
+     * @since 1.0.0
+     */
+    processRequest(method: string, headers: Record<string, string | undefined>): Promise<PaywallResult>;
+    /**
+     * @description Settle the payment after the resource has been served.
+     * Call this after successfully executing the RPC call.
+     *
+     * @param {X402PaymentPayload} paymentPayload - The verified payment payload
+     * @param {X402PaymentRequirements} requirements - The requirements that were fulfilled
+     * @returns {Promise<SettleResult>} SettleResult with the PAYMENT-RESPONSE header
+     * @since 1.0.0
+     */
+    settleAfterResponse(paymentPayload: X402PaymentPayload, requirements: X402PaymentRequirements): Promise<SettleResult>;
+    /**
+     * @description Build PaymentRequirements for a given method.
+     * @param {string} method - The RPC method name
+     * @returns {X402PaymentRequirements} The constructed payment requirements
+     * @since 1.0.0
+     */
+    buildRequirements(method: string): X402PaymentRequirements;
+    /**
+     * @description Build PaymentRequirements with feePayer resolved from the facilitator.
+     * This calls /supported to get the facilitator's feePayer address.
+     * @param {string} method - The RPC method name
+     * @returns {Promise<X402PaymentRequirements>} Requirements with feePayer resolved
+     * @since 1.0.0
+     */
+    buildRequirementsWithFeePayer(method: string): Promise<X402PaymentRequirements>;
+    private buildPaymentRequired;
+    /**
+     * Get the facilitator's feePayer address for a given network.
+     * Caches the result for 1 minute.
+     */
+    private getFeePayer;
+    private findFeePayer;
+    /** Get the underlying facilitator client */
+    get facilitatorClient(): FacilitatorClient;
+}
+//# sourceMappingURL=paywall.d.ts.map

package/dist/esm/ai/gateway/x402/paywall.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paywall.d.ts","sourceRoot":"","sources":["../../../../../src/ai/gateway/x402/paywall.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EACV,mBAAmB,EACnB,kBAAkB,EAClB,uBAAuB,EAEvB,kBAAkB,EAClB,kBAAkB,EAElB,UAAU,EAGX,MAAM,SAAS,CAAC;AAQjB,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAMlD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAExD;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,CAAC,CAExD;AAMD;;;GAGG;AACH,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,UAAU,EAAE,GAAG,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,IAAI,EAAE,mBAAmB,CAAA;CAAE,GACzG;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,cAAc,EAAE,kBAAkB,CAAC;IAAC,cAAc,EAAE,kBAAkB,CAAC;IAAC,YAAY,EAAE,uBAAuB,CAAA;CAAE,GACxI;IAAE,IAAI,EAAE,mBAAmB,CAAA;CAAE,CAAC;AAElC;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,cAAc,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAC1C,mDAAmD;IACnD,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;IACpC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoB;IAEhD,kDAAkD;IAClD,OAAO,CAAC,mBAAmB,CAAoH;IAC/I,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAAU;IAEnD;;;;OAIG;gBACS,MAAM,EAAE,UAAU;IAO9B;;;;;;;OAOG;IACG,cAAc,CAClB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAC1C,OAAO,CAAC,aAAa,CAAC;IA2CzB;;;;;;;;OAQG;IACG,mBAAmB,CACvB,cAAc,EAAE,kBAAkB,EAClC,YAAY,EAAE,uBAAuB,GACpC,OAAO,CAAC,YAAY,CAAC;IA2BxB;;;;;OAKG;IACH,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,uBAAuB;IAc1D;;;;;;OAMG;IACG,6BAA6B,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,CAAC;YAcvE,oBAAoB;IAkClC;;;OAGG;YACW,WAAW;IAwBzB,OAAO,CAAC,YAAY;IAYpB,4CAA4C;IAC5C,IAAI,iBAAiB,IAAI,iBAAiB,CAEzC;CACF"}