@okxweb3/app-x402-core 0.1.2

package/dist/cjs/utils/index.js

@@ -0,0 +1,116 @@
+"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/utils/index.ts
+var utils_exports = {};
+__export(utils_exports, {
+  Base64EncodedRegex: () => Base64EncodedRegex,
+  deepEqual: () => deepEqual,
+  findByNetworkAndScheme: () => findByNetworkAndScheme,
+  findFacilitatorBySchemeAndNetwork: () => findFacilitatorBySchemeAndNetwork,
+  findSchemesByNetwork: () => findSchemesByNetwork,
+  safeBase64Decode: () => safeBase64Decode,
+  safeBase64Encode: () => safeBase64Encode
+});
+module.exports = __toCommonJS(utils_exports);
+var findSchemesByNetwork = (map, network) => {
+  let implementationsByScheme = map.get(network);
+  if (!implementationsByScheme) {
+    for (const [registeredNetworkPattern, implementations] of map.entries()) {
+      const pattern = registeredNetworkPattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&").replace(/\\\*/g, ".*");
+      const regex = new RegExp(`^${pattern}$`);
+      if (regex.test(network)) {
+        implementationsByScheme = implementations;
+        break;
+      }
+    }
+  }
+  return implementationsByScheme;
+};
+var findByNetworkAndScheme = (map, scheme, network) => {
+  return findSchemesByNetwork(map, network)?.get(scheme);
+};
+var findFacilitatorBySchemeAndNetwork = (schemeMap, scheme, network) => {
+  const schemeData = schemeMap.get(scheme);
+  if (!schemeData) return void 0;
+  if (schemeData.networks.has(network)) {
+    return schemeData.facilitator;
+  }
+  const patternRegex = new RegExp("^" + schemeData.pattern.replace("*", ".*") + "$");
+  if (patternRegex.test(network)) {
+    return schemeData.facilitator;
+  }
+  return void 0;
+};
+var Base64EncodedRegex = /^[A-Za-z0-9+/]*={0,2}$/;
+function safeBase64Encode(data) {
+  if (typeof globalThis !== "undefined" && typeof globalThis.btoa === "function") {
+    const bytes = new TextEncoder().encode(data);
+    const binaryString = Array.from(bytes, (byte) => String.fromCharCode(byte)).join("");
+    return globalThis.btoa(binaryString);
+  }
+  return Buffer.from(data, "utf8").toString("base64");
+}
+function safeBase64Decode(data) {
+  if (typeof globalThis !== "undefined" && typeof globalThis.atob === "function") {
+    const binaryString = globalThis.atob(data);
+    const bytes = new Uint8Array(binaryString.length);
+    for (let i = 0; i < binaryString.length; i++) {
+      bytes[i] = binaryString.charCodeAt(i);
+    }
+    const decoder = new TextDecoder("utf-8");
+    return decoder.decode(bytes);
+  }
+  return Buffer.from(data, "base64").toString("utf-8");
+}
+function deepEqual(obj1, obj2) {
+  const normalize = (obj) => {
+    if (obj === null || obj === void 0) return JSON.stringify(obj);
+    if (typeof obj !== "object") return JSON.stringify(obj);
+    if (Array.isArray(obj)) {
+      return JSON.stringify(
+        obj.map(
+          (item) => typeof item === "object" && item !== null ? JSON.parse(normalize(item)) : item
+        )
+      );
+    }
+    const sorted = {};
+    Object.keys(obj).sort().forEach((key) => {
+      const value = obj[key];
+      sorted[key] = typeof value === "object" && value !== null ? JSON.parse(normalize(value)) : value;
+    });
+    return JSON.stringify(sorted);
+  };
+  try {
+    return normalize(obj1) === normalize(obj2);
+  } catch {
+    return JSON.stringify(obj1) === JSON.stringify(obj2);
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Base64EncodedRegex,
+  deepEqual,
+  findByNetworkAndScheme,
+  findFacilitatorBySchemeAndNetwork,
+  findSchemesByNetwork,
+  safeBase64Decode,
+  safeBase64Encode
+});
+//# sourceMappingURL=index.js.map

package/dist/cjs/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/utils/index.ts"],"sourcesContent":["import { Network } from \"../types\";\n\n/**\n * Scheme data structure for facilitator storage\n */\nexport interface SchemeData<T> {\n  facilitator: T;\n  networks: Set<Network>;\n  pattern: Network;\n}\n\nexport const findSchemesByNetwork = <T>(\n  map: Map<string, Map<string, T>>,\n  network: Network,\n): Map<string, T> | undefined => {\n  // Direct match first\n  let implementationsByScheme = map.get(network);\n\n  if (!implementationsByScheme) {\n    // Try pattern matching for registered network patterns\n    for (const [registeredNetworkPattern, implementations] of map.entries()) {\n      // Convert the registered network pattern to a regex\n      // e.g., \"eip155:*\" becomes /^eip155:.*$/\n      const pattern = registeredNetworkPattern\n        .replace(/[.*+?^${}()|[\\]\\\\]/g, \"\\\\$&\") // Escape special regex chars except *\n        .replace(/\\\\\\*/g, \".*\"); // Replace escaped * with .*\n\n      const regex = new RegExp(`^${pattern}$`);\n\n      if (regex.test(network)) {\n        implementationsByScheme = implementations;\n        break;\n      }\n    }\n  }\n\n  return implementationsByScheme;\n};\n\nexport const findByNetworkAndScheme = <T>(\n  map: Map<string, Map<string, T>>,\n  scheme: string,\n  network: Network,\n): T | undefined => {\n  return findSchemesByNetwork(map, network)?.get(scheme);\n};\n\n/**\n * Finds a facilitator by scheme and network using pattern matching.\n * Works with new SchemeData storage structure.\n *\n * @param schemeMap - Map of scheme names to SchemeData\n * @param scheme - The scheme to find\n * @param network - The network to match against\n * @returns The facilitator if found, undefined otherwise\n */\nexport const findFacilitatorBySchemeAndNetwork = <T>(\n  schemeMap: Map<string, SchemeData<T>>,\n  scheme: string,\n  network: Network,\n): T | undefined => {\n  const schemeData = schemeMap.get(scheme);\n  if (!schemeData) return undefined;\n\n  // Check if network is in the stored networks set\n  if (schemeData.networks.has(network)) {\n    return schemeData.facilitator;\n  }\n\n  // Try pattern matching\n  const patternRegex = new RegExp(\"^\" + schemeData.pattern.replace(\"*\", \".*\") + \"$\");\n  if (patternRegex.test(network)) {\n    return schemeData.facilitator;\n  }\n\n  return undefined;\n};\n\nexport const Base64EncodedRegex = /^[A-Za-z0-9+/]*={0,2}$/;\n\n/**\n * Encodes a string to base64 format\n *\n * @param data - The string to be encoded to base64\n * @returns The base64 encoded string\n */\nexport function safeBase64Encode(data: string): string {\n  if (typeof globalThis !== \"undefined\" && typeof globalThis.btoa === \"function\") {\n    const bytes = new TextEncoder().encode(data);\n    const binaryString = Array.from(bytes, byte => String.fromCharCode(byte)).join(\"\");\n    return globalThis.btoa(binaryString);\n  }\n  return Buffer.from(data, \"utf8\").toString(\"base64\");\n}\n\n/**\n * Decodes a base64 string back to its original format\n *\n * @param data - The base64 encoded string to be decoded\n * @returns The decoded string in UTF-8 format\n */\nexport function safeBase64Decode(data: string): string {\n  if (typeof globalThis !== \"undefined\" && typeof globalThis.atob === \"function\") {\n    const binaryString = globalThis.atob(data);\n    const bytes = new Uint8Array(binaryString.length);\n    for (let i = 0; i < binaryString.length; i++) {\n      bytes[i] = binaryString.charCodeAt(i);\n    }\n    const decoder = new TextDecoder(\"utf-8\");\n    return decoder.decode(bytes);\n  }\n  return Buffer.from(data, \"base64\").toString(\"utf-8\");\n}\n\n/**\n * Deep equality comparison for payment requirements\n * Uses a normalized JSON.stringify for consistent comparison\n *\n * @param obj1 - First object to compare\n * @param obj2 - Second object to compare\n * @returns True if objects are deeply equal\n */\nexport function deepEqual(obj1: unknown, obj2: unknown): boolean {\n  // Normalize and stringify both objects for comparison\n  // This handles nested objects, arrays, and different property orders\n  const normalize = (obj: unknown): string => {\n    // Handle primitives and null/undefined\n    if (obj === null || obj === undefined) return JSON.stringify(obj);\n    if (typeof obj !== \"object\") return JSON.stringify(obj);\n\n    // Handle arrays\n    if (Array.isArray(obj)) {\n      return JSON.stringify(\n        obj.map(item =>\n          typeof item === \"object\" && item !== null ? JSON.parse(normalize(item)) : item,\n        ),\n      );\n    }\n\n    // Handle objects - sort keys and recursively normalize values\n    const sorted: Record<string, unknown> = {};\n    Object.keys(obj as Record<string, unknown>)\n      .sort()\n      .forEach(key => {\n        const value = (obj as Record<string, unknown>)[key];\n        sorted[key] =\n          typeof value === \"object\" && value !== null ? JSON.parse(normalize(value)) : value;\n      });\n    return JSON.stringify(sorted);\n  };\n\n  try {\n    return normalize(obj1) === normalize(obj2);\n  } catch {\n    // Fallback to simple comparison if normalization fails\n    return JSON.stringify(obj1) === JSON.stringify(obj2);\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/cjs/x402HTTPResourceServer-CcsAkcgI.d.ts

@@ -0,0 +1,466 @@
+import { o as Price, N as Network, S as SettleResponse, P as PaymentPayload, a as PaymentRequirements, c as PaymentRequired, x as x402ResourceServer, n as SettlementOverrides } from './mechanisms-sojpSwWW.js';
+
+declare const SETTLEMENT_OVERRIDES_HEADER = "settlement-overrides";
+/**
+ * Framework-agnostic HTTP adapter interface
+ * Implementations provide framework-specific HTTP operations
+ */
+interface HTTPAdapter {
+    getHeader(name: string): string | undefined;
+    getMethod(): string;
+    getPath(): string;
+    getUrl(): string;
+    getAcceptHeader(): string;
+    getUserAgent(): string;
+    /**
+     * Get query parameters from the request URL
+     *
+     * @returns Record of query parameter key-value pairs
+     */
+    getQueryParams?(): Record<string, string | string[]>;
+    /**
+     * Get a specific query parameter by name
+     *
+     * @param name - The query parameter name
+     * @returns The query parameter value(s) or undefined
+     */
+    getQueryParam?(name: string): string | string[] | undefined;
+    /**
+     * Get the parsed request body
+     * Framework adapters should parse JSON/form data appropriately
+     *
+     * @returns The parsed request body
+     */
+    getBody?(): unknown;
+}
+/**
+ * Paywall configuration for HTML responses
+ */
+interface PaywallConfig {
+    appName?: string;
+    appLogo?: string;
+    sessionTokenEndpoint?: string;
+    currentUrl?: string;
+    testnet?: boolean;
+}
+/**
+ * Paywall provider interface for generating HTML
+ */
+interface PaywallProvider {
+    generateHtml(paymentRequired: PaymentRequired, config?: PaywallConfig): string;
+}
+/**
+ * Dynamic payTo function that receives HTTP request context
+ */
+type DynamicPayTo = (context: HTTPRequestContext) => string | Promise<string>;
+/**
+ * Dynamic price function that receives HTTP request context
+ */
+type DynamicPrice = (context: HTTPRequestContext) => Price | Promise<Price>;
+/**
+ * Result of response body callbacks containing content type and body.
+ */
+interface HTTPResponseBody {
+    /**
+     * The content type for the response (e.g., 'application/json', 'text/plain').
+     */
+    contentType: string;
+    /**
+     * The response body to include in the 402 response.
+     */
+    body: unknown;
+}
+/**
+ * Dynamic function to generate a custom response for unpaid requests.
+ * Receives the HTTP request context and returns the content type and body to include in the 402 response.
+ */
+type UnpaidResponseBody = (context: HTTPRequestContext) => HTTPResponseBody | Promise<HTTPResponseBody>;
+/**
+ * Dynamic function to generate a custom response for settlement failures.
+ * Receives the HTTP request context and settle failure result, returns the content type and body.
+ */
+type SettlementFailedResponseBody = (context: HTTPRequestContext, settleResult: Omit<ProcessSettleFailureResponse, "response">) => HTTPResponseBody | Promise<HTTPResponseBody>;
+/**
+ * A single payment option for a route
+ * Represents one way a client can pay for access to the resource
+ */
+interface PaymentOption {
+    scheme: string;
+    payTo: string | DynamicPayTo;
+    price: Price | DynamicPrice;
+    network: Network;
+    maxTimeoutSeconds?: number;
+    extra?: Record<string, unknown>;
+}
+/**
+ * Route configuration for HTTP endpoints
+ *
+ * The 'accepts' field defines payment options for the route.
+ * Can be a single PaymentOption or an array of PaymentOptions for multiple payment methods.
+ */
+interface RouteConfig {
+    accepts: PaymentOption | PaymentOption[];
+    resource?: string;
+    description?: string;
+    mimeType?: string;
+    customPaywallHtml?: string;
+    /**
+     * Optional callback to generate a custom response for unpaid API requests.
+     * This allows servers to return preview data, error messages, or other content
+     * when a request lacks payment.
+     *
+     * For browser requests (Accept: text/html), the paywall HTML takes precedence.
+     * This callback is only used for API clients.
+     *
+     * If not provided, defaults to { contentType: 'application/json', body: {} }.
+     *
+     * @param context - The HTTP request context
+     * @returns An object containing both contentType and body for the 402 response
+     */
+    unpaidResponseBody?: UnpaidResponseBody;
+    /**
+     * Optional callback to generate a custom response for settlement failures.
+     * If not provided, defaults to { contentType: 'application/json', body: {} }.
+     *
+     * @param context - The HTTP request context
+     * @param settleResult - The settlement failure result
+     * @returns An object containing both contentType and body for the 402 response
+     */
+    settlementFailedResponseBody?: SettlementFailedResponseBody;
+    extensions?: Record<string, unknown>;
+}
+/**
+ * Routes configuration - maps path patterns to route configs
+ */
+type RoutesConfig = Record<string, RouteConfig> | RouteConfig;
+/**
+ * Hook that runs on every request to a protected route, before payment processing.
+ * Can grant access without payment, deny the request, or continue to payment flow.
+ *
+ * @returns
+ * - `void` - Continue to payment processing (default behavior)
+ * - `{ grantAccess: true }` - Grant access without requiring payment
+ * - `{ abort: true; reason: string }` - Deny the request (returns 403)
+ */
+type ProtectedRequestHook = (context: HTTPRequestContext, routeConfig: RouteConfig) => Promise<void | {
+    grantAccess: true;
+} | {
+    abort: true;
+    reason: string;
+}>;
+/**
+ * Compiled route for efficient matching
+ */
+interface CompiledRoute {
+    verb: string;
+    regex: RegExp;
+    config: RouteConfig;
+    pattern: string;
+}
+/**
+ * HTTP request context that encapsulates all request data
+ */
+interface HTTPRequestContext {
+    adapter: HTTPAdapter;
+    path: string;
+    method: string;
+    paymentHeader?: string;
+    routePattern?: string;
+}
+/**
+ * HTTP transport context contains both request context and optional response data.
+ */
+interface HTTPTransportContext {
+    /** The HTTP request context */
+    request: HTTPRequestContext;
+    /** The response body buffer */
+    responseBody?: Buffer;
+    /** Response headers set by the route handler (used for settlement overrides) */
+    responseHeaders?: Record<string, string>;
+}
+/**
+ * HTTP response instructions for the framework middleware
+ */
+interface HTTPResponseInstructions {
+    status: number;
+    headers: Record<string, string>;
+    body?: unknown;
+    isHtml?: boolean;
+}
+/**
+ * Result of processing an HTTP request for payment
+ */
+type HTTPProcessResult = {
+    type: "no-payment-required";
+} | {
+    type: "payment-verified";
+    paymentPayload: PaymentPayload;
+    paymentRequirements: PaymentRequirements;
+    declaredExtensions?: Record<string, unknown>;
+} | {
+    type: "payment-error";
+    response: HTTPResponseInstructions;
+};
+/**
+ * Result of processSettlement
+ */
+type ProcessSettleSuccessResponse = SettleResponse & {
+    success: true;
+    headers: Record<string, string>;
+    requirements: PaymentRequirements;
+};
+type ProcessSettleFailureResponse = SettleResponse & {
+    success: false;
+    errorReason: string;
+    errorMessage?: string;
+    headers: Record<string, string>;
+    response: HTTPResponseInstructions;
+};
+type ProcessSettleResultResponse = ProcessSettleSuccessResponse | ProcessSettleFailureResponse;
+/**
+ * Represents a validation error for a specific route's payment configuration.
+ */
+interface RouteValidationError {
+    /** The route pattern (e.g., "GET /api/weather") */
+    routePattern: string;
+    /** The payment scheme that failed validation */
+    scheme: string;
+    /** The network that failed validation */
+    network: Network;
+    /** The type of validation failure */
+    reason: "missing_scheme" | "missing_facilitator";
+    /** Human-readable error message */
+    message: string;
+}
+/**
+ * Error thrown when route configuration validation fails.
+ */
+declare class RouteConfigurationError extends Error {
+    /** The validation errors that caused this exception */
+    readonly errors: RouteValidationError[];
+    /**
+     * Creates a new RouteConfigurationError with the given validation errors.
+     *
+     * @param errors - The validation errors that caused this exception.
+     */
+    constructor(errors: RouteValidationError[]);
+}
+/**
+ * Hook called when the facilitator returns status="timeout".
+ * Receives the tx hash and network so the server can verify on-chain.
+ * Return { confirmed: true } to deliver the resource; { confirmed: false } to return 402.
+ */
+type OnSettlementTimeoutHook = (txHash: string, network: string) => Promise<{
+    confirmed: boolean;
+}>;
+/**
+ * HTTP-enhanced x402 resource server
+ * Provides framework-agnostic HTTP protocol handling
+ */
+declare class x402HTTPResourceServer {
+    private ResourceServer;
+    private compiledRoutes;
+    private routesConfig;
+    private paywallProvider?;
+    private protectedRequestHooks;
+    private timeoutRecoveryHook?;
+    private pollDeadlineMs;
+    /**
+     * Creates a new x402HTTPResourceServer instance.
+     *
+     * @param ResourceServer - The core x402ResourceServer instance to use
+     * @param routes - Route configuration for payment-protected endpoints
+     */
+    constructor(ResourceServer: x402ResourceServer, routes: RoutesConfig);
+    /**
+     * Get the underlying x402ResourceServer instance.
+     *
+     * @returns The underlying x402ResourceServer instance
+     */
+    get server(): x402ResourceServer;
+    /**
+     * Get the routes configuration.
+     *
+     * @returns The routes configuration
+     */
+    get routes(): RoutesConfig;
+    /**
+     * Initialize the HTTP resource server.
+     *
+     * This method initializes the underlying resource server (fetching facilitator support)
+     * and then validates that all route payment configurations have corresponding
+     * registered schemes and facilitator support.
+     *
+     * @throws RouteConfigurationError if any route's payment options don't have
+     *         corresponding registered schemes or facilitator support
+     *
+     * @example
+     * ```typescript
+     * const httpServer = new x402HTTPResourceServer(server, routes);
+     * await httpServer.initialize();
+     * ```
+     */
+    initialize(): Promise<void>;
+    /**
+     * Register a custom paywall provider for generating HTML
+     *
+     * @param provider - PaywallProvider instance
+     * @returns This service instance for chaining
+     */
+    registerPaywallProvider(provider: PaywallProvider): this;
+    /**
+     * Register a hook that runs on every request to a protected route, before payment processing.
+     * Hooks are executed in order of registration. The first hook to return a non-void result wins.
+     *
+     * @param hook - The request hook function
+     * @returns The x402HTTPResourceServer instance for chaining
+     */
+    onProtectedRequest(hook: ProtectedRequestHook): this;
+    /**
+     * Register a hook to call when the facilitator returns status="timeout".
+     * The hook should verify the tx on-chain and return { confirmed: boolean }.
+     * If confirmed=true the resource is delivered (200); otherwise 402 is returned.
+     *
+     * @param hook - On-chain verification callback
+     * @returns The x402HTTPResourceServer instance for chaining
+     */
+    onSettlementTimeout(hook: OnSettlementTimeoutHook): this;
+    /**
+     * Set the poll deadline for settle/status polling on timeout recovery.
+     * Default is 5000ms.
+     *
+     * @param deadlineMs - Maximum time to poll in milliseconds
+     * @returns The x402HTTPResourceServer instance for chaining
+     */
+    setPollDeadline(deadlineMs: number): this;
+    /**
+     * Process HTTP request and return response instructions
+     * This is the main entry point for framework middleware
+     *
+     * @param context - HTTP request context
+     * @param paywallConfig - Optional paywall configuration
+     * @returns Process result indicating next action for middleware
+     */
+    processHTTPRequest(context: HTTPRequestContext, paywallConfig?: PaywallConfig): Promise<HTTPProcessResult>;
+    /**
+     * Process settlement after successful response
+     *
+     * @param paymentPayload - The verified payment payload
+     * @param requirements - The matching payment requirements
+     * @param declaredExtensions - Optional declared extensions (for per-key enrichment)
+     * @param transportContext - Optional HTTP transport context
+     * @param settlementOverrides - Optional settlement overrides (e.g., partial settlement amount)
+     * @returns ProcessSettleResultResponse - SettleResponse with headers if success or errorReason if failure
+     */
+    processSettlement(paymentPayload: PaymentPayload, requirements: PaymentRequirements, declaredExtensions?: Record<string, unknown>, transportContext?: HTTPTransportContext, settlementOverrides?: SettlementOverrides): Promise<ProcessSettleResultResponse>;
+    /**
+     * Check if a request requires payment based on route configuration
+     *
+     * @param context - HTTP request context
+     * @returns True if the route requires payment, false otherwise
+     */
+    requiresPayment(context: HTTPRequestContext): boolean;
+    /**
+     * Build HTTPResponseInstructions for settlement failure.
+     * Uses settlementFailedResponseBody hook if configured, otherwise defaults to empty body.
+     *
+     * @param failure - Settlement failure result with headers
+     * @param transportContext - Optional HTTP transport context for the request
+     * @returns HTTP response instructions for the 402 settlement failure response
+     */
+    private buildSettlementFailureResponse;
+    /**
+     * Normalizes a RouteConfig's accepts field into an array of PaymentOptions
+     * Handles both single PaymentOption and array formats
+     *
+     * @param routeConfig - Route configuration
+     * @returns Array of payment options
+     */
+    private normalizePaymentOptions;
+    /**
+     * Validates that all payment options in routes have corresponding registered schemes
+     * and facilitator support.
+     *
+     * @returns Array of validation errors (empty if all routes are valid)
+     */
+    private validateRouteConfiguration;
+    /**
+     * Get route configuration for a request
+     *
+     * @param path - Request path
+     * @param method - HTTP method
+     * @returns Route configuration and pattern, or undefined if no match
+     */
+    private getRouteConfig;
+    /**
+     * Extract payment from HTTP headers (handles v1 and v2)
+     *
+     * @param adapter - HTTP adapter
+     * @returns Decoded payment payload or null
+     */
+    private extractPayment;
+    /**
+     * Check if request is from a web browser
+     *
+     * @param adapter - HTTP adapter
+     * @returns True if request appears to be from a browser
+     */
+    private isWebBrowser;
+    /**
+     * Create HTTP response instructions from payment required
+     *
+     * @param paymentRequired - Payment requirements
+     * @param isWebBrowser - Whether request is from browser
+     * @param paywallConfig - Paywall configuration
+     * @param customHtml - Custom HTML template
+     * @param unpaidResponse - Optional custom response (content type and body) for unpaid API requests
+     * @returns Response instructions
+     */
+    private createHTTPResponse;
+    /**
+     * Create HTTP payment required response (v1 puts in body, v2 puts in header)
+     *
+     * @param paymentRequired - Payment required object
+     * @returns Headers and body for the HTTP response
+     */
+    private createHTTPPaymentRequiredResponse;
+    /**
+     * Create settlement response headers
+     *
+     * @param settleResponse - Settlement response
+     * @returns Headers to add to response
+     */
+    private createSettlementHeaders;
+    /**
+     * Parse route pattern into verb and regex
+     *
+     * @param pattern - Route pattern like "GET /api/*", "/api/[id]", or "/api/:id"
+     * @returns Parsed pattern with verb and regex
+     */
+    private parseRoutePattern;
+    /**
+     * Normalize path for matching
+     *
+     * @param path - Raw path from request
+     * @returns Normalized path
+     */
+    private normalizePath;
+    /**
+     * Generate paywall HTML for browser requests
+     *
+     * @param paymentRequired - Payment required response
+     * @param paywallConfig - Optional paywall configuration
+     * @param customHtml - Optional custom HTML template
+     * @returns HTML string
+     */
+    private generatePaywallHTML;
+    /**
+     * Extract display amount from payment requirements.
+     *
+     * @param paymentRequired - The payment required object
+     * @returns The display amount in decimal format
+     */
+    private getDisplayAmount;
+}
+
+export { type CompiledRoute as C, type DynamicPayTo as D, type HTTPAdapter as H, type OnSettlementTimeoutHook as O, type PaymentOption as P, type RouteConfig as R, type SettlementFailedResponseBody as S, type UnpaidResponseBody as U, type DynamicPrice as a, type HTTPProcessResult as b, type HTTPRequestContext as c, type HTTPResponseBody as d, type HTTPResponseInstructions as e, type HTTPTransportContext as f, type PaywallConfig as g, type PaywallProvider as h, type ProcessSettleFailureResponse as i, type ProcessSettleResultResponse as j, type ProcessSettleSuccessResponse as k, type ProtectedRequestHook as l, RouteConfigurationError as m, type RouteValidationError as n, type RoutesConfig as o, SETTLEMENT_OVERRIDES_HEADER as p, x402HTTPResourceServer as x };

package/dist/esm/OKXFacilitatorClient-D5E3LX50.d.mts

@@ -0,0 +1,59 @@
+import { d as FacilitatorClient, h as SupportedResponse, P as PaymentPayload, a as PaymentRequirements, V as VerifyResponse, S as SettleResponse, i as SettleStatusResponse } from './mechanisms-sojpSwWW.mjs';
+
+interface OKXConfig {
+    apiKey: string;
+    secretKey: string;
+    passphrase: string;
+    baseUrl?: string;
+    /**
+     * OKX exact-scheme extension: when true, the settle call tells the facilitator to
+     * wait for on-chain confirmation before responding (syncSettle=true in request body).
+     * The facilitator then returns status="success" directly (no polling needed).
+     * When false (default), the facilitator responds with status="pending" immediately.
+     */
+    syncSettle?: boolean;
+}
+/**
+ * OKX facilitator client implementing the FacilitatorClient interface.
+ * Uses HMAC-SHA256 signing per OKX REST API authentication spec.
+ */
+declare class OKXFacilitatorClient implements FacilitatorClient {
+    private config;
+    /**
+     *
+     * @param config
+     */
+    constructor(config: OKXConfig);
+    /**
+     *
+     * @param method
+     * @param path
+     * @param body
+     */
+    private createHeaders;
+    /**
+     *
+     */
+    getSupported(): Promise<SupportedResponse>;
+    /**
+     *
+     * @param payload
+     * @param requirements
+     */
+    verify(payload: PaymentPayload, requirements: PaymentRequirements): Promise<VerifyResponse>;
+    /**
+     *
+     * @param payload
+     * @param requirements
+     */
+    settle(payload: PaymentPayload, requirements: PaymentRequirements): Promise<SettleResponse>;
+    /**
+     * Query on-chain settlement status by transaction hash.
+     *
+     * @param txHash - The transaction hash to query
+     * @returns Settlement status response
+     */
+    getSettleStatus(txHash: string): Promise<SettleStatusResponse>;
+}
+
+export { type OKXConfig as O, OKXFacilitatorClient as a };