@x402/core - npm Package Compare versions

Comparing version 2.6.0 to 2.7.0

dist/cjs/x402HTTPResourceServer-COKLgLFM.d.ts

+import { x as x402ResourceServer, h as Price, N as Network, S as SettleResponse, c as PaymentRequired, P as PaymentPayload, a as PaymentRequirements } from './mechanisms-e8RNDWpU.js';
+
+/**
+ * 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;
+}
+/**
+ * HTTP request context that encapsulates all request data
+ */
+interface HTTPRequestContext {
+    adapter: HTTPAdapter;
+    path: string;
+    method: string;
+    paymentHeader?: 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;
+}
+/**
+ * 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[]);
+}
+/**
+ * HTTP-enhanced x402 resource server
+ * Provides framework-agnostic HTTP protocol handling
+ */
+declare class x402HTTPResourceServer {
+    private ResourceServer;
+    private compiledRoutes;
+    private routesConfig;
+    private paywallProvider?;
+    private protectedRequestHooks;
+    /**
+     * 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;
+    /**
+     * 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
+     * @returns ProcessSettleResultResponse - SettleResponse with headers if success or errorReason if failure
+     */
+    processSettlement(paymentPayload: PaymentPayload, requirements: PaymentRequirements, declaredExtensions?: Record<string, unknown>, transportContext?: HTTPTransportContext): 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 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 PaywallConfig as P, type RouteConfig as R, type SettlementFailedResponseBody as S, type UnpaidResponseBody as U, type HTTPRequestContext as a, type HTTPTransportContext as b, type HTTPResponseInstructions as c, type HTTPProcessResult as d, type PaywallProvider as e, type PaymentOption as f, type RoutesConfig as g, type DynamicPrice as h, type HTTPResponseBody as i, type ProcessSettleResultResponse as j, type ProcessSettleSuccessResponse as k, type ProcessSettleFailureResponse as l, type RouteValidationError as m, RouteConfigurationError as n, type ProtectedRequestHook as o, x402HTTPResourceServer as x };

dist/esm/chunk-5KCDBAZ7.mjs

+import {
+  x402Version
+} from "./chunk-VE37GDG2.mjs";
+import {
+  SettleError,
+  VerifyError
+} from "./chunk-HRQUGJ3Y.mjs";
+import {
+  Base64EncodedRegex,
+  safeBase64Decode,
+  safeBase64Encode
+} from "./chunk-TDLQZ6MP.mjs";
+import {
+  __require
+} from "./chunk-BJTO5JO5.mjs";
+
+// src/http/x402HTTPResourceServer.ts
+var RouteConfigurationError = class extends Error {
+  /**
+   * Creates a new RouteConfigurationError with the given validation errors.
+   *
+   * @param errors - The validation errors that caused this exception.
+   */
+  constructor(errors) {
+    const message = `x402 Route Configuration Errors:
+${errors.map((e) => `  - ${e.message}`).join("\n")}`;
+    super(message);
+    this.name = "RouteConfigurationError";
+    this.errors = errors;
+  }
+};
+var x402HTTPResourceServer = class {
+  /**
+   * Creates a new x402HTTPResourceServer instance.
+   *
+   * @param ResourceServer - The core x402ResourceServer instance to use
+   * @param routes - Route configuration for payment-protected endpoints
+   */
+  constructor(ResourceServer, routes) {
+    this.compiledRoutes = [];
+    this.protectedRequestHooks = [];
+    this.ResourceServer = ResourceServer;
+    this.routesConfig = routes;
+    const normalizedRoutes = typeof routes === "object" && !("accepts" in routes) ? routes : { "*": routes };
+    for (const [pattern, config] of Object.entries(normalizedRoutes)) {
+      const parsed = this.parseRoutePattern(pattern);
+      this.compiledRoutes.push({
+        verb: parsed.verb,
+        regex: parsed.regex,
+        config
+      });
+    }
+  }
+  /**
+   * Get the underlying x402ResourceServer instance.
+   *
+   * @returns The underlying x402ResourceServer instance
+   */
+  get server() {
+    return this.ResourceServer;
+  }
+  /**
+   * Get the routes configuration.
+   *
+   * @returns The routes configuration
+   */
+  get routes() {
+    return this.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();
+   * ```
+   */
+  async initialize() {
+    await this.ResourceServer.initialize();
+    const errors = this.validateRouteConfiguration();
+    if (errors.length > 0) {
+      throw new RouteConfigurationError(errors);
+    }
+  }
+  /**
+   * Register a custom paywall provider for generating HTML
+   *
+   * @param provider - PaywallProvider instance
+   * @returns This service instance for chaining
+   */
+  registerPaywallProvider(provider) {
+    this.paywallProvider = provider;
+    return 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) {
+    this.protectedRequestHooks.push(hook);
+    return 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
+   */
+  async processHTTPRequest(context, paywallConfig) {
+    const { adapter, path, method } = context;
+    const routeConfig = this.getRouteConfig(path, method);
+    if (!routeConfig) {
+      return { type: "no-payment-required" };
+    }
+    for (const hook of this.protectedRequestHooks) {
+      const result = await hook(context, routeConfig);
+      if (result && "grantAccess" in result) {
+        return { type: "no-payment-required" };
+      }
+      if (result && "abort" in result) {
+        return {
+          type: "payment-error",
+          response: {
+            status: 403,
+            headers: { "Content-Type": "application/json" },
+            body: { error: result.reason }
+          }
+        };
+      }
+    }
+    const paymentOptions = this.normalizePaymentOptions(routeConfig);
+    const paymentPayload = this.extractPayment(adapter);
+    const resourceInfo = {
+      url: routeConfig.resource || context.adapter.getUrl(),
+      description: routeConfig.description || "",
+      mimeType: routeConfig.mimeType || ""
+    };
+    let requirements = await this.ResourceServer.buildPaymentRequirementsFromOptions(
+      paymentOptions,
+      context
+    );
+    let extensions = routeConfig.extensions;
+    if (extensions) {
+      extensions = this.ResourceServer.enrichExtensions(extensions, context);
+    }
+    const transportContext = { request: context };
+    const paymentRequired = await this.ResourceServer.createPaymentRequiredResponse(
+      requirements,
+      resourceInfo,
+      !paymentPayload ? "Payment required" : void 0,
+      extensions,
+      transportContext
+    );
+    if (!paymentPayload) {
+      const unpaidBody = routeConfig.unpaidResponseBody ? await routeConfig.unpaidResponseBody(context) : void 0;
+      return {
+        type: "payment-error",
+        response: this.createHTTPResponse(
+          paymentRequired,
+          this.isWebBrowser(adapter),
+          paywallConfig,
+          routeConfig.customPaywallHtml,
+          unpaidBody
+        )
+      };
+    }
+    try {
+      const matchingRequirements = this.ResourceServer.findMatchingRequirements(
+        paymentRequired.accepts,
+        paymentPayload
+      );
+      if (!matchingRequirements) {
+        const errorResponse = await this.ResourceServer.createPaymentRequiredResponse(
+          requirements,
+          resourceInfo,
+          "No matching payment requirements",
+          routeConfig.extensions,
+          transportContext
+        );
+        return {
+          type: "payment-error",
+          response: this.createHTTPResponse(errorResponse, false, paywallConfig)
+        };
+      }
+      const verifyResult = await this.ResourceServer.verifyPayment(
+        paymentPayload,
+        matchingRequirements
+      );
+      if (!verifyResult.isValid) {
+        const errorResponse = await this.ResourceServer.createPaymentRequiredResponse(
+          requirements,
+          resourceInfo,
+          verifyResult.invalidReason,
+          routeConfig.extensions,
+          transportContext
+        );
+        return {
+          type: "payment-error",
+          response: this.createHTTPResponse(errorResponse, false, paywallConfig)
+        };
+      }
+      return {
+        type: "payment-verified",
+        paymentPayload,
+        paymentRequirements: matchingRequirements,
+        declaredExtensions: routeConfig.extensions
+      };
+    } catch (error) {
+      const errorResponse = await this.ResourceServer.createPaymentRequiredResponse(
+        requirements,
+        resourceInfo,
+        error instanceof Error ? error.message : "Payment verification failed",
+        routeConfig.extensions,
+        transportContext
+      );
+      return {
+        type: "payment-error",
+        response: this.createHTTPResponse(errorResponse, false, paywallConfig)
+      };
+    }
+  }
+  /**
+   * 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
+   * @returns ProcessSettleResultResponse - SettleResponse with headers if success or errorReason if failure
+   */
+  async processSettlement(paymentPayload, requirements, declaredExtensions, transportContext) {
+    try {
+      const settleResponse = await this.ResourceServer.settlePayment(
+        paymentPayload,
+        requirements,
+        declaredExtensions,
+        transportContext
+      );
+      if (!settleResponse.success) {
+        const failure = {
+          ...settleResponse,
+          success: false,
+          errorReason: settleResponse.errorReason || "Settlement failed",
+          errorMessage: settleResponse.errorMessage || settleResponse.errorReason || "Settlement failed",
+          headers: this.createSettlementHeaders(settleResponse)
+        };
+        const response = await this.buildSettlementFailureResponse(failure, transportContext);
+        return { ...failure, response };
+      }
+      return {
+        ...settleResponse,
+        success: true,
+        headers: this.createSettlementHeaders(settleResponse),
+        requirements
+      };
+    } catch (error) {
+      if (error instanceof SettleError) {
+        const errorReason2 = error.errorReason || error.message;
+        const settleResponse2 = {
+          success: false,
+          errorReason: errorReason2,
+          errorMessage: error.errorMessage || errorReason2,
+          payer: error.payer,
+          network: error.network,
+          transaction: error.transaction
+        };
+        const failure2 = {
+          ...settleResponse2,
+          success: false,
+          errorReason: errorReason2,
+          headers: this.createSettlementHeaders(settleResponse2)
+        };
+        const response2 = await this.buildSettlementFailureResponse(failure2, transportContext);
+        return { ...failure2, response: response2 };
+      }
+      const errorReason = error instanceof Error ? error.message : "Settlement failed";
+      const settleResponse = {
+        success: false,
+        errorReason,
+        errorMessage: errorReason,
+        network: requirements.network,
+        transaction: ""
+      };
+      const failure = {
+        ...settleResponse,
+        success: false,
+        errorReason,
+        headers: this.createSettlementHeaders(settleResponse)
+      };
+      const response = await this.buildSettlementFailureResponse(failure, transportContext);
+      return { ...failure, response };
+    }
+  }
+  /**
+   * 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) {
+    const routeConfig = this.getRouteConfig(context.path, context.method);
+    return routeConfig !== void 0;
+  }
+  /**
+   * 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
+   */
+  async buildSettlementFailureResponse(failure, transportContext) {
+    const settlementHeaders = failure.headers;
+    const routeConfig = transportContext ? this.getRouteConfig(transportContext.request.path, transportContext.request.method) : void 0;
+    const customBody = routeConfig?.settlementFailedResponseBody ? await routeConfig.settlementFailedResponseBody(transportContext.request, failure) : void 0;
+    const contentType = customBody ? customBody.contentType : "application/json";
+    const body = customBody ? customBody.body : {};
+    return {
+      status: 402,
+      headers: {
+        "Content-Type": contentType,
+        ...settlementHeaders
+      },
+      body,
+      isHtml: contentType.includes("text/html")
+    };
+  }
+  /**
+   * 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
+   */
+  normalizePaymentOptions(routeConfig) {
+    return Array.isArray(routeConfig.accepts) ? routeConfig.accepts : [routeConfig.accepts];
+  }
+  /**
+   * 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)
+   */
+  validateRouteConfiguration() {
+    const errors = [];
+    const normalizedRoutes = typeof this.routesConfig === "object" && !("accepts" in this.routesConfig) ? Object.entries(this.routesConfig) : [["*", this.routesConfig]];
+    for (const [pattern, config] of normalizedRoutes) {
+      const paymentOptions = this.normalizePaymentOptions(config);
+      for (const option of paymentOptions) {
+        if (!this.ResourceServer.hasRegisteredScheme(option.network, option.scheme)) {
+          errors.push({
+            routePattern: pattern,
+            scheme: option.scheme,
+            network: option.network,
+            reason: "missing_scheme",
+            message: `Route "${pattern}": No scheme implementation registered for "${option.scheme}" on network "${option.network}"`
+          });
+          continue;
+        }
+        const supportedKind = this.ResourceServer.getSupportedKind(
+          x402Version,
+          option.network,
+          option.scheme
+        );
+        if (!supportedKind) {
+          errors.push({
+            routePattern: pattern,
+            scheme: option.scheme,
+            network: option.network,
+            reason: "missing_facilitator",
+            message: `Route "${pattern}": Facilitator does not support scheme "${option.scheme}" on network "${option.network}"`
+          });
+        }
+      }
+    }
+    return errors;
+  }
+  /**
+   * Get route configuration for a request
+   *
+   * @param path - Request path
+   * @param method - HTTP method
+   * @returns Route configuration or undefined if no match
+   */
+  getRouteConfig(path, method) {
+    const normalizedPath = this.normalizePath(path);
+    const upperMethod = method.toUpperCase();
+    const matchingRoute = this.compiledRoutes.find(
+      (route) => route.regex.test(normalizedPath) && (route.verb === "*" || route.verb === upperMethod)
+    );
+    return matchingRoute?.config;
+  }
+  /**
+   * Extract payment from HTTP headers (handles v1 and v2)
+   *
+   * @param adapter - HTTP adapter
+   * @returns Decoded payment payload or null
+   */
+  extractPayment(adapter) {
+    const header = adapter.getHeader("payment-signature") || adapter.getHeader("PAYMENT-SIGNATURE");
+    if (header) {
+      try {
+        return decodePaymentSignatureHeader(header);
+      } catch (error) {
+        console.warn("Failed to decode PAYMENT-SIGNATURE header:", error);
+      }
+    }
+    return null;
+  }
+  /**
+   * Check if request is from a web browser
+   *
+   * @param adapter - HTTP adapter
+   * @returns True if request appears to be from a browser
+   */
+  isWebBrowser(adapter) {
+    const accept = adapter.getAcceptHeader();
+    const userAgent = adapter.getUserAgent();
+    return accept.includes("text/html") && userAgent.includes("Mozilla");
+  }
+  /**
+   * 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
+   */
+  createHTTPResponse(paymentRequired, isWebBrowser, paywallConfig, customHtml, unpaidResponse) {
+    const status = paymentRequired.error === "permit2_allowance_required" ? 412 : 402;
+    if (isWebBrowser) {
+      const html = this.generatePaywallHTML(paymentRequired, paywallConfig, customHtml);
+      return {
+        status,
+        headers: { "Content-Type": "text/html" },
+        body: html,
+        isHtml: true
+      };
+    }
+    const response = this.createHTTPPaymentRequiredResponse(paymentRequired);
+    const contentType = unpaidResponse ? unpaidResponse.contentType : "application/json";
+    const body = unpaidResponse ? unpaidResponse.body : {};
+    return {
+      status,
+      headers: {
+        "Content-Type": contentType,
+        ...response.headers
+      },
+      body
+    };
+  }
+  /**
+   * 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
+   */
+  createHTTPPaymentRequiredResponse(paymentRequired) {
+    return {
+      headers: {
+        "PAYMENT-REQUIRED": encodePaymentRequiredHeader(paymentRequired)
+      }
+    };
+  }
+  /**
+   * Create settlement response headers
+   *
+   * @param settleResponse - Settlement response
+   * @returns Headers to add to response
+   */
+  createSettlementHeaders(settleResponse) {
+    const encoded = encodePaymentResponseHeader(settleResponse);
+    return { "PAYMENT-RESPONSE": encoded };
+  }
+  /**
+   * 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
+   */
+  parseRoutePattern(pattern) {
+    const [verb, path] = pattern.includes(" ") ? pattern.split(/\s+/) : ["*", pattern];
+    const regex = new RegExp(
+      `^${path.replace(/[$()+.?^{|}]/g, "\\$&").replace(/\*/g, ".*?").replace(/\[([^\]]+)\]/g, "[^/]+").replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, "[^/]+").replace(/\//g, "\\/")}$`,
+      "i"
+    );
+    return { verb: verb.toUpperCase(), regex };
+  }
+  /**
+   * Normalize path for matching
+   *
+   * @param path - Raw path from request
+   * @returns Normalized path
+   */
+  normalizePath(path) {
+    const pathWithoutQuery = path.split(/[?#]/)[0];
+    let decodedOrRawPath;
+    try {
+      decodedOrRawPath = decodeURIComponent(pathWithoutQuery);
+    } catch {
+      decodedOrRawPath = pathWithoutQuery;
+    }
+    return decodedOrRawPath.replace(/\\/g, "/").replace(/\/+/g, "/").replace(/(.+?)\/+$/, "$1");
+  }
+  /**
+   * 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
+   */
+  generatePaywallHTML(paymentRequired, paywallConfig, customHtml) {
+    if (customHtml) {
+      return customHtml;
+    }
+    if (this.paywallProvider) {
+      return this.paywallProvider.generateHtml(paymentRequired, paywallConfig);
+    }
+    try {
+      const paywall = __require("@x402/paywall");
+      const displayAmount2 = this.getDisplayAmount(paymentRequired);
+      const resource2 = paymentRequired.resource;
+      return paywall.getPaywallHtml({
+        amount: displayAmount2,
+        paymentRequired,
+        currentUrl: resource2?.url || paywallConfig?.currentUrl || "",
+        testnet: paywallConfig?.testnet ?? true,
+        appName: paywallConfig?.appName,
+        appLogo: paywallConfig?.appLogo,
+        sessionTokenEndpoint: paywallConfig?.sessionTokenEndpoint
+      });
+    } catch {
+    }
+    const resource = paymentRequired.resource;
+    const displayAmount = this.getDisplayAmount(paymentRequired);
+    return `
+      <!DOCTYPE html>
+      <html>
+        <head>
+          <title>Payment Required</title>
+          <meta charset="UTF-8">
+          <meta name="viewport" content="width=device-width, initial-scale=1.0">
+        </head>
+        <body>
+          <div style="max-width: 600px; margin: 50px auto; padding: 20px; font-family: system-ui, -apple-system, sans-serif;">
+            ${paywallConfig?.appLogo ? `<img src="${paywallConfig.appLogo}" alt="${paywallConfig.appName || "App"}" style="max-width: 200px; margin-bottom: 20px;">` : ""}
+            <h1>Payment Required</h1>
+            ${resource ? `<p><strong>Resource:</strong> ${resource.description || resource.url}</p>` : ""}
+            <p><strong>Amount:</strong> $${displayAmount.toFixed(2)} USDC</p>
+            <div id="payment-widget" 
+                 data-requirements='${JSON.stringify(paymentRequired)}'
+                 data-app-name="${paywallConfig?.appName || ""}"
+                 data-testnet="${paywallConfig?.testnet || false}">
+              <!-- Install @x402/paywall for full wallet integration -->
+              <p style="margin-top: 2rem; padding: 1rem; background: #fef3c7; border-radius: 0.5rem;">
+                <strong>Note:</strong> Install <code>@x402/paywall</code> for full wallet connection and payment UI.
+              </p>
+            </div>
+          </div>
+        </body>
+      </html>
+    `;
+  }
+  /**
+   * Extract display amount from payment requirements.
+   *
+   * @param paymentRequired - The payment required object
+   * @returns The display amount in decimal format
+   */
+  getDisplayAmount(paymentRequired) {
+    const accepts = paymentRequired.accepts;
+    if (accepts && accepts.length > 0) {
+      const firstReq = accepts[0];
+      if ("amount" in firstReq) {
+        return parseFloat(firstReq.amount) / 1e6;
+      }
+    }
+    return 0;
+  }
+};
+
+// src/http/httpFacilitatorClient.ts
+var DEFAULT_FACILITATOR_URL = "https://x402.org/facilitator";
+var GET_SUPPORTED_RETRIES = 3;
+var GET_SUPPORTED_RETRY_DELAY_MS = 1e3;
+var HTTPFacilitatorClient = class {
+  /**
+   * Creates a new HTTPFacilitatorClient instance.
+   *
+   * @param config - Configuration options for the facilitator client
+   */
+  constructor(config) {
+    this.url = config?.url || DEFAULT_FACILITATOR_URL;
+    this._createAuthHeaders = config?.createAuthHeaders;
+  }
+  /**
+   * Verify a payment with the facilitator
+   *
+   * @param paymentPayload - The payment to verify
+   * @param paymentRequirements - The requirements to verify against
+   * @returns Verification response
+   */
+  async verify(paymentPayload, paymentRequirements) {
+    let headers = {
+      "Content-Type": "application/json"
+    };
+    if (this._createAuthHeaders) {
+      const authHeaders = await this.createAuthHeaders("verify");
+      headers = { ...headers, ...authHeaders.headers };
+    }
+    const response = await fetch(`${this.url}/verify`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        x402Version: paymentPayload.x402Version,
+        paymentPayload: this.toJsonSafe(paymentPayload),
+        paymentRequirements: this.toJsonSafe(paymentRequirements)
+      })
+    });
+    const data = await response.json();
+    if (typeof data === "object" && data !== null && "isValid" in data) {
+      const verifyResponse = data;
+      if (!response.ok) {
+        throw new VerifyError(response.status, verifyResponse);
+      }
+      return verifyResponse;
+    }
+    throw new Error(`Facilitator verify failed (${response.status}): ${JSON.stringify(data)}`);
+  }
+  /**
+   * Settle a payment with the facilitator
+   *
+   * @param paymentPayload - The payment to settle
+   * @param paymentRequirements - The requirements for settlement
+   * @returns Settlement response
+   */
+  async settle(paymentPayload, paymentRequirements) {
+    let headers = {
+      "Content-Type": "application/json"
+    };
+    if (this._createAuthHeaders) {
+      const authHeaders = await this.createAuthHeaders("settle");
+      headers = { ...headers, ...authHeaders.headers };
+    }
+    const response = await fetch(`${this.url}/settle`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        x402Version: paymentPayload.x402Version,
+        paymentPayload: this.toJsonSafe(paymentPayload),
+        paymentRequirements: this.toJsonSafe(paymentRequirements)
+      })
+    });
+    const data = await response.json();
+    if (typeof data === "object" && data !== null && "success" in data) {
+      const settleResponse = data;
+      if (!response.ok) {
+        throw new SettleError(response.status, settleResponse);
+      }
+      return settleResponse;
+    }
+    throw new Error(`Facilitator settle failed (${response.status}): ${JSON.stringify(data)}`);
+  }
+  /**
+   * Get supported payment kinds and extensions from the facilitator.
+   * Retries with exponential backoff on 429 rate limit errors.
+   *
+   * @returns Supported payment kinds and extensions
+   */
+  async getSupported() {
+    let headers = {
+      "Content-Type": "application/json"
+    };
+    if (this._createAuthHeaders) {
+      const authHeaders = await this.createAuthHeaders("supported");
+      headers = { ...headers, ...authHeaders.headers };
+    }
+    let lastError = null;
+    for (let attempt = 0; attempt < GET_SUPPORTED_RETRIES; attempt++) {
+      const response = await fetch(`${this.url}/supported`, {
+        method: "GET",
+        headers
+      });
+      if (response.ok) {
+        return await response.json();
+      }
+      const errorText = await response.text().catch(() => response.statusText);
+      lastError = new Error(`Facilitator getSupported failed (${response.status}): ${errorText}`);
+      if (response.status === 429 && attempt < GET_SUPPORTED_RETRIES - 1) {
+        const delay = GET_SUPPORTED_RETRY_DELAY_MS * Math.pow(2, attempt);
+        await new Promise((resolve) => setTimeout(resolve, delay));
+        continue;
+      }
+      throw lastError;
+    }
+    throw lastError ?? new Error("Facilitator getSupported failed after retries");
+  }
+  /**
+   * Creates authentication headers for a specific path.
+   *
+   * @param path - The path to create authentication headers for (e.g., "verify", "settle", "supported")
+   * @returns An object containing the authentication headers for the specified path
+   */
+  async createAuthHeaders(path) {
+    if (this._createAuthHeaders) {
+      const authHeaders = await this._createAuthHeaders();
+      return {
+        headers: authHeaders[path] ?? {}
+      };
+    }
+    return {
+      headers: {}
+    };
+  }
+  /**
+   * Helper to convert objects to JSON-safe format.
+   * Handles BigInt and other non-JSON types.
+   *
+   * @param obj - The object to convert
+   * @returns The JSON-safe representation of the object
+   */
+  toJsonSafe(obj) {
+    return JSON.parse(
+      JSON.stringify(obj, (_, value) => typeof value === "bigint" ? value.toString() : value)
+    );
+  }
+};
+
+// src/http/x402HTTPClient.ts
+var x402HTTPClient = class {
+  /**
+   * Creates a new x402HTTPClient instance.
+   *
+   * @param client - The underlying x402Client for payment logic
+   */
+  constructor(client) {
+    this.client = client;
+    this.paymentRequiredHooks = [];
+  }
+  /**
+   * Register a hook to handle 402 responses before payment.
+   * Hooks run in order; first to return headers wins.
+   *
+   * @param hook - The hook function to register
+   * @returns This instance for chaining
+   */
+  onPaymentRequired(hook) {
+    this.paymentRequiredHooks.push(hook);
+    return this;
+  }
+  /**
+   * Run hooks and return headers if any hook provides them.
+   *
+   * @param paymentRequired - The payment required response from the server
+   * @returns Headers to use for retry, or null to proceed to payment
+   */
+  async handlePaymentRequired(paymentRequired) {
+    for (const hook of this.paymentRequiredHooks) {
+      const result = await hook({ paymentRequired });
+      if (result?.headers) {
+        return result.headers;
+      }
+    }
+    return null;
+  }
+  /**
+   * Encodes a payment payload into appropriate HTTP headers based on version.
+   *
+   * @param paymentPayload - The payment payload to encode
+   * @returns HTTP headers containing the encoded payment signature
+   */
+  encodePaymentSignatureHeader(paymentPayload) {
+    switch (paymentPayload.x402Version) {
+      case 2:
+        return {
+          "PAYMENT-SIGNATURE": encodePaymentSignatureHeader(paymentPayload)
+        };
+      case 1:
+        return {
+          "X-PAYMENT": encodePaymentSignatureHeader(paymentPayload)
+        };
+      default:
+        throw new Error(
+          `Unsupported x402 version: ${paymentPayload.x402Version}`
+        );
+    }
+  }
+  /**
+   * Extracts payment required information from HTTP response.
+   *
+   * @param getHeader - Function to retrieve header value by name (case-insensitive)
+   * @param body - Optional response body for v1 compatibility
+   * @returns The payment required object
+   */
+  getPaymentRequiredResponse(getHeader, body) {
+    const paymentRequired = getHeader("PAYMENT-REQUIRED");
+    if (paymentRequired) {
+      return decodePaymentRequiredHeader(paymentRequired);
+    }
+    if (body && body instanceof Object && "x402Version" in body && body.x402Version === 1) {
+      return body;
+    }
+    throw new Error("Invalid payment required response");
+  }
+  /**
+   * Extracts payment settlement response from HTTP headers.
+   *
+   * @param getHeader - Function to retrieve header value by name (case-insensitive)
+   * @returns The settlement response object
+   */
+  getPaymentSettleResponse(getHeader) {
+    const paymentResponse = getHeader("PAYMENT-RESPONSE");
+    if (paymentResponse) {
+      return decodePaymentResponseHeader(paymentResponse);
+    }
+    const xPaymentResponse = getHeader("X-PAYMENT-RESPONSE");
+    if (xPaymentResponse) {
+      return decodePaymentResponseHeader(xPaymentResponse);
+    }
+    throw new Error("Payment response header not found");
+  }
+  /**
+   * Creates a payment payload for the given payment requirements.
+   * Delegates to the underlying x402Client.
+   *
+   * @param paymentRequired - The payment required response from the server
+   * @returns Promise resolving to the payment payload
+   */
+  async createPaymentPayload(paymentRequired) {
+    return this.client.createPaymentPayload(paymentRequired);
+  }
+};
+
+// src/http/index.ts
+function encodePaymentSignatureHeader(paymentPayload) {
+  return safeBase64Encode(JSON.stringify(paymentPayload));
+}
+function decodePaymentSignatureHeader(paymentSignatureHeader) {
+  if (!Base64EncodedRegex.test(paymentSignatureHeader)) {
+    throw new Error("Invalid payment signature header");
+  }
+  return JSON.parse(safeBase64Decode(paymentSignatureHeader));
+}
+function encodePaymentRequiredHeader(paymentRequired) {
+  return safeBase64Encode(JSON.stringify(paymentRequired));
+}
+function decodePaymentRequiredHeader(paymentRequiredHeader) {
+  if (!Base64EncodedRegex.test(paymentRequiredHeader)) {
+    throw new Error("Invalid payment required header");
+  }
+  return JSON.parse(safeBase64Decode(paymentRequiredHeader));
+}
+function encodePaymentResponseHeader(paymentResponse) {
+  return safeBase64Encode(JSON.stringify(paymentResponse));
+}
+function decodePaymentResponseHeader(paymentResponseHeader) {
+  if (!Base64EncodedRegex.test(paymentResponseHeader)) {
+    throw new Error("Invalid payment response header");
+  }
+  return JSON.parse(safeBase64Decode(paymentResponseHeader));
+}
+
+export {
+  RouteConfigurationError,
+  x402HTTPResourceServer,
+  HTTPFacilitatorClient,
+  encodePaymentSignatureHeader,
+  decodePaymentSignatureHeader,
+  encodePaymentRequiredHeader,
+  decodePaymentRequiredHeader,
+  encodePaymentResponseHeader,
+  decodePaymentResponseHeader,
+  x402HTTPClient
+};
+//# sourceMappingURL=chunk-5KCDBAZ7.mjs.map

dist/esm/x402HTTPResourceServer-CDXLbP9A.d.mts

+import { x as x402ResourceServer, h as Price, N as Network, S as SettleResponse, c as PaymentRequired, P as PaymentPayload, a as PaymentRequirements } from './mechanisms-e8RNDWpU.mjs';
+
+/**
+ * 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;
+}
+/**
+ * HTTP request context that encapsulates all request data
+ */
+interface HTTPRequestContext {
+    adapter: HTTPAdapter;
+    path: string;
+    method: string;
+    paymentHeader?: 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;
+}
+/**
+ * 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[]);
+}
+/**
+ * HTTP-enhanced x402 resource server
+ * Provides framework-agnostic HTTP protocol handling
+ */
+declare class x402HTTPResourceServer {
+    private ResourceServer;
+    private compiledRoutes;
+    private routesConfig;
+    private paywallProvider?;
+    private protectedRequestHooks;
+    /**
+     * 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;
+    /**
+     * 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
+     * @returns ProcessSettleResultResponse - SettleResponse with headers if success or errorReason if failure
+     */
+    processSettlement(paymentPayload: PaymentPayload, requirements: PaymentRequirements, declaredExtensions?: Record<string, unknown>, transportContext?: HTTPTransportContext): 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 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 PaywallConfig as P, type RouteConfig as R, type SettlementFailedResponseBody as S, type UnpaidResponseBody as U, type HTTPRequestContext as a, type HTTPTransportContext as b, type HTTPResponseInstructions as c, type HTTPProcessResult as d, type PaywallProvider as e, type PaymentOption as f, type RoutesConfig as g, type DynamicPrice as h, type HTTPResponseBody as i, type ProcessSettleResultResponse as j, type ProcessSettleSuccessResponse as k, type ProcessSettleFailureResponse as l, type RouteValidationError as m, RouteConfigurationError as n, type ProtectedRequestHook as o, x402HTTPResourceServer as x };

dist/cjs/http/index.d.ts

 import { P as PaymentPayload, c as PaymentRequired, S as SettleResponse } from '../mechanisms-e8RNDWpU.js';
 export { d as FacilitatorClient, e as FacilitatorConfig, H as HTTPFacilitatorClient } from '../mechanisms-e8RNDWpU.js';
-export { C as CompiledRoute, D as DynamicPayTo, h as DynamicPrice, H as HTTPAdapter, d as HTTPProcessResult, a as HTTPRequestContext, i as HTTPResponseBody, c as HTTPResponseInstructions, b as HTTPTransportContext, f as PaymentOption, P as PaywallConfig, e as PaywallProvider, l as ProcessSettleFailureResponse, j as ProcessSettleResultResponse, k as ProcessSettleSuccessResponse, o as ProtectedRequestHook, R as RouteConfig, n as RouteConfigurationError, m as RouteValidationError, g as RoutesConfig, S as SettlementFailedResponseBody, U as UnpaidResponseBody, x as x402HTTPResourceServer } from '../x402HTTPResourceServer-BlkP6vzv.js';
+export { C as CompiledRoute, D as DynamicPayTo, h as DynamicPrice, H as HTTPAdapter, d as HTTPProcessResult, a as HTTPRequestContext, i as HTTPResponseBody, c as HTTPResponseInstructions, b as HTTPTransportContext, f as PaymentOption, P as PaywallConfig, e as PaywallProvider, l as ProcessSettleFailureResponse, j as ProcessSettleResultResponse, k as ProcessSettleSuccessResponse, o as ProtectedRequestHook, R as RouteConfig, n as RouteConfigurationError, m as RouteValidationError, g as RoutesConfig, S as SettlementFailedResponseBody, U as UnpaidResponseBody, x as x402HTTPResourceServer } from '../x402HTTPResourceServer-COKLgLFM.js';
 export { PaymentRequiredContext, PaymentRequiredHook, x402HTTPClient } from '../client/index.js';
@@ -5,0 +5,0 @@

dist/cjs/http/index.js

@@ -578,3 +578,3 @@ "use strict";
    *
-   * @param pattern - Route pattern like "GET /api/*" or "/api/[id]"
+   * @param pattern - Route pattern like "GET /api/*", "/api/[id]", or "/api/:id"
    * @returns Parsed pattern with verb and regex
@@ -585,3 +585,3 @@ */
     const regex = new RegExp(
-      `^${path.replace(/[$()+.?^{|}]/g, "\\$&").replace(/\*/g, ".*?").replace(/\[([^\]]+)\]/g, "[^/]+").replace(/\//g, "\\/")}$`,
+      `^${path.replace(/[$()+.?^{|}]/g, "\\$&").replace(/\*/g, ".*?").replace(/\[([^\]]+)\]/g, "[^/]+").replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, "[^/]+").replace(/\//g, "\\/")}$`,
       "i"
@@ -588,0 +588,0 @@ );

dist/cjs/server/index.d.ts

 export { d as FacilitatorClient, e as FacilitatorConfig, H as HTTPFacilitatorClient, R as ResourceConfig, g as SettleResultContext, x as x402ResourceServer } from '../mechanisms-e8RNDWpU.js';
-export { C as CompiledRoute, H as HTTPAdapter, d as HTTPProcessResult, a as HTTPRequestContext, i as HTTPResponseBody, c as HTTPResponseInstructions, b as HTTPTransportContext, P as PaywallConfig, e as PaywallProvider, l as ProcessSettleFailureResponse, j as ProcessSettleResultResponse, k as ProcessSettleSuccessResponse, R as RouteConfig, n as RouteConfigurationError, m as RouteValidationError, g as RoutesConfig, S as SettlementFailedResponseBody, U as UnpaidResponseBody, x as x402HTTPResourceServer } from '../x402HTTPResourceServer-BlkP6vzv.js';
+export { C as CompiledRoute, H as HTTPAdapter, d as HTTPProcessResult, a as HTTPRequestContext, i as HTTPResponseBody, c as HTTPResponseInstructions, b as HTTPTransportContext, P as PaywallConfig, e as PaywallProvider, l as ProcessSettleFailureResponse, j as ProcessSettleResultResponse, k as ProcessSettleSuccessResponse, R as RouteConfig, n as RouteConfigurationError, m as RouteValidationError, g as RoutesConfig, S as SettlementFailedResponseBody, U as UnpaidResponseBody, x as x402HTTPResourceServer } from '../x402HTTPResourceServer-COKLgLFM.js';

dist/cjs/server/index.js

@@ -1425,3 +1425,3 @@ "use strict";
    *
-   * @param pattern - Route pattern like "GET /api/*" or "/api/[id]"
+   * @param pattern - Route pattern like "GET /api/*", "/api/[id]", or "/api/:id"
    * @returns Parsed pattern with verb and regex
@@ -1432,3 +1432,3 @@ */
     const regex = new RegExp(
-      `^${path.replace(/[$()+.?^{|}]/g, "\\$&").replace(/\*/g, ".*?").replace(/\[([^\]]+)\]/g, "[^/]+").replace(/\//g, "\\/")}$`,
+      `^${path.replace(/[$()+.?^{|}]/g, "\\$&").replace(/\*/g, ".*?").replace(/\[([^\]]+)\]/g, "[^/]+").replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, "[^/]+").replace(/\//g, "\\/")}$`,
       "i"
@@ -1435,0 +1435,0 @@ );

dist/esm/client/index.mjs

 import {
   x402HTTPClient
-} from "../chunk-CM4FD6HG.mjs";
+} from "../chunk-5KCDBAZ7.mjs";
 import {
@@ -5,0 +5,0 @@ x402Version

dist/esm/http/index.d.mts

 import { P as PaymentPayload, c as PaymentRequired, S as SettleResponse } from '../mechanisms-e8RNDWpU.mjs';
 export { d as FacilitatorClient, e as FacilitatorConfig, H as HTTPFacilitatorClient } from '../mechanisms-e8RNDWpU.mjs';
-export { C as CompiledRoute, D as DynamicPayTo, h as DynamicPrice, H as HTTPAdapter, d as HTTPProcessResult, a as HTTPRequestContext, i as HTTPResponseBody, c as HTTPResponseInstructions, b as HTTPTransportContext, f as PaymentOption, P as PaywallConfig, e as PaywallProvider, l as ProcessSettleFailureResponse, j as ProcessSettleResultResponse, k as ProcessSettleSuccessResponse, o as ProtectedRequestHook, R as RouteConfig, n as RouteConfigurationError, m as RouteValidationError, g as RoutesConfig, S as SettlementFailedResponseBody, U as UnpaidResponseBody, x as x402HTTPResourceServer } from '../x402HTTPResourceServer-B-i4cmSW.mjs';
+export { C as CompiledRoute, D as DynamicPayTo, h as DynamicPrice, H as HTTPAdapter, d as HTTPProcessResult, a as HTTPRequestContext, i as HTTPResponseBody, c as HTTPResponseInstructions, b as HTTPTransportContext, f as PaymentOption, P as PaywallConfig, e as PaywallProvider, l as ProcessSettleFailureResponse, j as ProcessSettleResultResponse, k as ProcessSettleSuccessResponse, o as ProtectedRequestHook, R as RouteConfig, n as RouteConfigurationError, m as RouteValidationError, g as RoutesConfig, S as SettlementFailedResponseBody, U as UnpaidResponseBody, x as x402HTTPResourceServer } from '../x402HTTPResourceServer-CDXLbP9A.mjs';
 export { PaymentRequiredContext, PaymentRequiredHook, x402HTTPClient } from '../client/index.mjs';
@@ -5,0 +5,0 @@

dist/esm/http/index.mjs

@@ -12,3 +12,3 @@ import {
   x402HTTPResourceServer
-} from "../chunk-CM4FD6HG.mjs";
+} from "../chunk-5KCDBAZ7.mjs";
 import "../chunk-VE37GDG2.mjs";
@@ -15,0 +15,0 @@ import "../chunk-HRQUGJ3Y.mjs";

dist/esm/server/index.d.mts

 export { d as FacilitatorClient, e as FacilitatorConfig, H as HTTPFacilitatorClient, R as ResourceConfig, g as SettleResultContext, x as x402ResourceServer } from '../mechanisms-e8RNDWpU.mjs';
-export { C as CompiledRoute, H as HTTPAdapter, d as HTTPProcessResult, a as HTTPRequestContext, i as HTTPResponseBody, c as HTTPResponseInstructions, b as HTTPTransportContext, P as PaywallConfig, e as PaywallProvider, l as ProcessSettleFailureResponse, j as ProcessSettleResultResponse, k as ProcessSettleSuccessResponse, R as RouteConfig, n as RouteConfigurationError, m as RouteValidationError, g as RoutesConfig, S as SettlementFailedResponseBody, U as UnpaidResponseBody, x as x402HTTPResourceServer } from '../x402HTTPResourceServer-B-i4cmSW.mjs';
+export { C as CompiledRoute, H as HTTPAdapter, d as HTTPProcessResult, a as HTTPRequestContext, i as HTTPResponseBody, c as HTTPResponseInstructions, b as HTTPTransportContext, P as PaywallConfig, e as PaywallProvider, l as ProcessSettleFailureResponse, j as ProcessSettleResultResponse, k as ProcessSettleSuccessResponse, R as RouteConfig, n as RouteConfigurationError, m as RouteValidationError, g as RoutesConfig, S as SettlementFailedResponseBody, U as UnpaidResponseBody, x as x402HTTPResourceServer } from '../x402HTTPResourceServer-CDXLbP9A.mjs';

dist/esm/server/index.mjs

@@ -5,3 +5,3 @@ import {
   x402HTTPResourceServer
-} from "../chunk-CM4FD6HG.mjs";
+} from "../chunk-5KCDBAZ7.mjs";
 import {
@@ -8,0 +8,0 @@ x402Version

package.json

 {
   "name": "@x402/core",
-  "version": "2.6.0",
+  "version": "2.7.0",
   "main": "./dist/cjs/index.js",
@@ -5,0 +5,0 @@ "module": "./dist/esm/index.js",

dist/cjs/x402HTTPResourceServer-BlkP6vzv.d.ts

-import { x as x402ResourceServer, h as Price, N as Network, S as SettleResponse, c as PaymentRequired, P as PaymentPayload, a as PaymentRequirements } from './mechanisms-e8RNDWpU.js';
-
-/**
- * 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;
-}
-/**
- * HTTP request context that encapsulates all request data
- */
-interface HTTPRequestContext {
-    adapter: HTTPAdapter;
-    path: string;
-    method: string;
-    paymentHeader?: 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;
-}
-/**
- * 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[]);
-}
-/**
- * HTTP-enhanced x402 resource server
- * Provides framework-agnostic HTTP protocol handling
- */
-declare class x402HTTPResourceServer {
-    private ResourceServer;
-    private compiledRoutes;
-    private routesConfig;
-    private paywallProvider?;
-    private protectedRequestHooks;
-    /**
-     * 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;
-    /**
-     * 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
-     * @returns ProcessSettleResultResponse - SettleResponse with headers if success or errorReason if failure
-     */
-    processSettlement(paymentPayload: PaymentPayload, requirements: PaymentRequirements, declaredExtensions?: Record<string, unknown>, transportContext?: HTTPTransportContext): 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 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/*" 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 PaywallConfig as P, type RouteConfig as R, type SettlementFailedResponseBody as S, type UnpaidResponseBody as U, type HTTPRequestContext as a, type HTTPTransportContext as b, type HTTPResponseInstructions as c, type HTTPProcessResult as d, type PaywallProvider as e, type PaymentOption as f, type RoutesConfig as g, type DynamicPrice as h, type HTTPResponseBody as i, type ProcessSettleResultResponse as j, type ProcessSettleSuccessResponse as k, type ProcessSettleFailureResponse as l, type RouteValidationError as m, RouteConfigurationError as n, type ProtectedRequestHook as o, x402HTTPResourceServer as x };

dist/esm/chunk-CM4FD6HG.mjs

-import {
-  x402Version
-} from "./chunk-VE37GDG2.mjs";
-import {
-  SettleError,
-  VerifyError
-} from "./chunk-HRQUGJ3Y.mjs";
-import {
-  Base64EncodedRegex,
-  safeBase64Decode,
-  safeBase64Encode
-} from "./chunk-TDLQZ6MP.mjs";
-import {
-  __require
-} from "./chunk-BJTO5JO5.mjs";
-
-// src/http/x402HTTPResourceServer.ts
-var RouteConfigurationError = class extends Error {
-  /**
-   * Creates a new RouteConfigurationError with the given validation errors.
-   *
-   * @param errors - The validation errors that caused this exception.
-   */
-  constructor(errors) {
-    const message = `x402 Route Configuration Errors:
-${errors.map((e) => `  - ${e.message}`).join("\n")}`;
-    super(message);
-    this.name = "RouteConfigurationError";
-    this.errors = errors;
-  }
-};
-var x402HTTPResourceServer = class {
-  /**
-   * Creates a new x402HTTPResourceServer instance.
-   *
-   * @param ResourceServer - The core x402ResourceServer instance to use
-   * @param routes - Route configuration for payment-protected endpoints
-   */
-  constructor(ResourceServer, routes) {
-    this.compiledRoutes = [];
-    this.protectedRequestHooks = [];
-    this.ResourceServer = ResourceServer;
-    this.routesConfig = routes;
-    const normalizedRoutes = typeof routes === "object" && !("accepts" in routes) ? routes : { "*": routes };
-    for (const [pattern, config] of Object.entries(normalizedRoutes)) {
-      const parsed = this.parseRoutePattern(pattern);
-      this.compiledRoutes.push({
-        verb: parsed.verb,
-        regex: parsed.regex,
-        config
-      });
-    }
-  }
-  /**
-   * Get the underlying x402ResourceServer instance.
-   *
-   * @returns The underlying x402ResourceServer instance
-   */
-  get server() {
-    return this.ResourceServer;
-  }
-  /**
-   * Get the routes configuration.
-   *
-   * @returns The routes configuration
-   */
-  get routes() {
-    return this.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();
-   * ```
-   */
-  async initialize() {
-    await this.ResourceServer.initialize();
-    const errors = this.validateRouteConfiguration();
-    if (errors.length > 0) {
-      throw new RouteConfigurationError(errors);
-    }
-  }
-  /**
-   * Register a custom paywall provider for generating HTML
-   *
-   * @param provider - PaywallProvider instance
-   * @returns This service instance for chaining
-   */
-  registerPaywallProvider(provider) {
-    this.paywallProvider = provider;
-    return 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) {
-    this.protectedRequestHooks.push(hook);
-    return 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
-   */
-  async processHTTPRequest(context, paywallConfig) {
-    const { adapter, path, method } = context;
-    const routeConfig = this.getRouteConfig(path, method);
-    if (!routeConfig) {
-      return { type: "no-payment-required" };
-    }
-    for (const hook of this.protectedRequestHooks) {
-      const result = await hook(context, routeConfig);
-      if (result && "grantAccess" in result) {
-        return { type: "no-payment-required" };
-      }
-      if (result && "abort" in result) {
-        return {
-          type: "payment-error",
-          response: {
-            status: 403,
-            headers: { "Content-Type": "application/json" },
-            body: { error: result.reason }
-          }
-        };
-      }
-    }
-    const paymentOptions = this.normalizePaymentOptions(routeConfig);
-    const paymentPayload = this.extractPayment(adapter);
-    const resourceInfo = {
-      url: routeConfig.resource || context.adapter.getUrl(),
-      description: routeConfig.description || "",
-      mimeType: routeConfig.mimeType || ""
-    };
-    let requirements = await this.ResourceServer.buildPaymentRequirementsFromOptions(
-      paymentOptions,
-      context
-    );
-    let extensions = routeConfig.extensions;
-    if (extensions) {
-      extensions = this.ResourceServer.enrichExtensions(extensions, context);
-    }
-    const transportContext = { request: context };
-    const paymentRequired = await this.ResourceServer.createPaymentRequiredResponse(
-      requirements,
-      resourceInfo,
-      !paymentPayload ? "Payment required" : void 0,
-      extensions,
-      transportContext
-    );
-    if (!paymentPayload) {
-      const unpaidBody = routeConfig.unpaidResponseBody ? await routeConfig.unpaidResponseBody(context) : void 0;
-      return {
-        type: "payment-error",
-        response: this.createHTTPResponse(
-          paymentRequired,
-          this.isWebBrowser(adapter),
-          paywallConfig,
-          routeConfig.customPaywallHtml,
-          unpaidBody
-        )
-      };
-    }
-    try {
-      const matchingRequirements = this.ResourceServer.findMatchingRequirements(
-        paymentRequired.accepts,
-        paymentPayload
-      );
-      if (!matchingRequirements) {
-        const errorResponse = await this.ResourceServer.createPaymentRequiredResponse(
-          requirements,
-          resourceInfo,
-          "No matching payment requirements",
-          routeConfig.extensions,
-          transportContext
-        );
-        return {
-          type: "payment-error",
-          response: this.createHTTPResponse(errorResponse, false, paywallConfig)
-        };
-      }
-      const verifyResult = await this.ResourceServer.verifyPayment(
-        paymentPayload,
-        matchingRequirements
-      );
-      if (!verifyResult.isValid) {
-        const errorResponse = await this.ResourceServer.createPaymentRequiredResponse(
-          requirements,
-          resourceInfo,
-          verifyResult.invalidReason,
-          routeConfig.extensions,
-          transportContext
-        );
-        return {
-          type: "payment-error",
-          response: this.createHTTPResponse(errorResponse, false, paywallConfig)
-        };
-      }
-      return {
-        type: "payment-verified",
-        paymentPayload,
-        paymentRequirements: matchingRequirements,
-        declaredExtensions: routeConfig.extensions
-      };
-    } catch (error) {
-      const errorResponse = await this.ResourceServer.createPaymentRequiredResponse(
-        requirements,
-        resourceInfo,
-        error instanceof Error ? error.message : "Payment verification failed",
-        routeConfig.extensions,
-        transportContext
-      );
-      return {
-        type: "payment-error",
-        response: this.createHTTPResponse(errorResponse, false, paywallConfig)
-      };
-    }
-  }
-  /**
-   * 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
-   * @returns ProcessSettleResultResponse - SettleResponse with headers if success or errorReason if failure
-   */
-  async processSettlement(paymentPayload, requirements, declaredExtensions, transportContext) {
-    try {
-      const settleResponse = await this.ResourceServer.settlePayment(
-        paymentPayload,
-        requirements,
-        declaredExtensions,
-        transportContext
-      );
-      if (!settleResponse.success) {
-        const failure = {
-          ...settleResponse,
-          success: false,
-          errorReason: settleResponse.errorReason || "Settlement failed",
-          errorMessage: settleResponse.errorMessage || settleResponse.errorReason || "Settlement failed",
-          headers: this.createSettlementHeaders(settleResponse)
-        };
-        const response = await this.buildSettlementFailureResponse(failure, transportContext);
-        return { ...failure, response };
-      }
-      return {
-        ...settleResponse,
-        success: true,
-        headers: this.createSettlementHeaders(settleResponse),
-        requirements
-      };
-    } catch (error) {
-      if (error instanceof SettleError) {
-        const errorReason2 = error.errorReason || error.message;
-        const settleResponse2 = {
-          success: false,
-          errorReason: errorReason2,
-          errorMessage: error.errorMessage || errorReason2,
-          payer: error.payer,
-          network: error.network,
-          transaction: error.transaction
-        };
-        const failure2 = {
-          ...settleResponse2,
-          success: false,
-          errorReason: errorReason2,
-          headers: this.createSettlementHeaders(settleResponse2)
-        };
-        const response2 = await this.buildSettlementFailureResponse(failure2, transportContext);
-        return { ...failure2, response: response2 };
-      }
-      const errorReason = error instanceof Error ? error.message : "Settlement failed";
-      const settleResponse = {
-        success: false,
-        errorReason,
-        errorMessage: errorReason,
-        network: requirements.network,
-        transaction: ""
-      };
-      const failure = {
-        ...settleResponse,
-        success: false,
-        errorReason,
-        headers: this.createSettlementHeaders(settleResponse)
-      };
-      const response = await this.buildSettlementFailureResponse(failure, transportContext);
-      return { ...failure, response };
-    }
-  }
-  /**
-   * 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) {
-    const routeConfig = this.getRouteConfig(context.path, context.method);
-    return routeConfig !== void 0;
-  }
-  /**
-   * 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
-   */
-  async buildSettlementFailureResponse(failure, transportContext) {
-    const settlementHeaders = failure.headers;
-    const routeConfig = transportContext ? this.getRouteConfig(transportContext.request.path, transportContext.request.method) : void 0;
-    const customBody = routeConfig?.settlementFailedResponseBody ? await routeConfig.settlementFailedResponseBody(transportContext.request, failure) : void 0;
-    const contentType = customBody ? customBody.contentType : "application/json";
-    const body = customBody ? customBody.body : {};
-    return {
-      status: 402,
-      headers: {
-        "Content-Type": contentType,
-        ...settlementHeaders
-      },
-      body,
-      isHtml: contentType.includes("text/html")
-    };
-  }
-  /**
-   * 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
-   */
-  normalizePaymentOptions(routeConfig) {
-    return Array.isArray(routeConfig.accepts) ? routeConfig.accepts : [routeConfig.accepts];
-  }
-  /**
-   * 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)
-   */
-  validateRouteConfiguration() {
-    const errors = [];
-    const normalizedRoutes = typeof this.routesConfig === "object" && !("accepts" in this.routesConfig) ? Object.entries(this.routesConfig) : [["*", this.routesConfig]];
-    for (const [pattern, config] of normalizedRoutes) {
-      const paymentOptions = this.normalizePaymentOptions(config);
-      for (const option of paymentOptions) {
-        if (!this.ResourceServer.hasRegisteredScheme(option.network, option.scheme)) {
-          errors.push({
-            routePattern: pattern,
-            scheme: option.scheme,
-            network: option.network,
-            reason: "missing_scheme",
-            message: `Route "${pattern}": No scheme implementation registered for "${option.scheme}" on network "${option.network}"`
-          });
-          continue;
-        }
-        const supportedKind = this.ResourceServer.getSupportedKind(
-          x402Version,
-          option.network,
-          option.scheme
-        );
-        if (!supportedKind) {
-          errors.push({
-            routePattern: pattern,
-            scheme: option.scheme,
-            network: option.network,
-            reason: "missing_facilitator",
-            message: `Route "${pattern}": Facilitator does not support scheme "${option.scheme}" on network "${option.network}"`
-          });
-        }
-      }
-    }
-    return errors;
-  }
-  /**
-   * Get route configuration for a request
-   *
-   * @param path - Request path
-   * @param method - HTTP method
-   * @returns Route configuration or undefined if no match
-   */
-  getRouteConfig(path, method) {
-    const normalizedPath = this.normalizePath(path);
-    const upperMethod = method.toUpperCase();
-    const matchingRoute = this.compiledRoutes.find(
-      (route) => route.regex.test(normalizedPath) && (route.verb === "*" || route.verb === upperMethod)
-    );
-    return matchingRoute?.config;
-  }
-  /**
-   * Extract payment from HTTP headers (handles v1 and v2)
-   *
-   * @param adapter - HTTP adapter
-   * @returns Decoded payment payload or null
-   */
-  extractPayment(adapter) {
-    const header = adapter.getHeader("payment-signature") || adapter.getHeader("PAYMENT-SIGNATURE");
-    if (header) {
-      try {
-        return decodePaymentSignatureHeader(header);
-      } catch (error) {
-        console.warn("Failed to decode PAYMENT-SIGNATURE header:", error);
-      }
-    }
-    return null;
-  }
-  /**
-   * Check if request is from a web browser
-   *
-   * @param adapter - HTTP adapter
-   * @returns True if request appears to be from a browser
-   */
-  isWebBrowser(adapter) {
-    const accept = adapter.getAcceptHeader();
-    const userAgent = adapter.getUserAgent();
-    return accept.includes("text/html") && userAgent.includes("Mozilla");
-  }
-  /**
-   * 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
-   */
-  createHTTPResponse(paymentRequired, isWebBrowser, paywallConfig, customHtml, unpaidResponse) {
-    const status = paymentRequired.error === "permit2_allowance_required" ? 412 : 402;
-    if (isWebBrowser) {
-      const html = this.generatePaywallHTML(paymentRequired, paywallConfig, customHtml);
-      return {
-        status,
-        headers: { "Content-Type": "text/html" },
-        body: html,
-        isHtml: true
-      };
-    }
-    const response = this.createHTTPPaymentRequiredResponse(paymentRequired);
-    const contentType = unpaidResponse ? unpaidResponse.contentType : "application/json";
-    const body = unpaidResponse ? unpaidResponse.body : {};
-    return {
-      status,
-      headers: {
-        "Content-Type": contentType,
-        ...response.headers
-      },
-      body
-    };
-  }
-  /**
-   * 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
-   */
-  createHTTPPaymentRequiredResponse(paymentRequired) {
-    return {
-      headers: {
-        "PAYMENT-REQUIRED": encodePaymentRequiredHeader(paymentRequired)
-      }
-    };
-  }
-  /**
-   * Create settlement response headers
-   *
-   * @param settleResponse - Settlement response
-   * @returns Headers to add to response
-   */
-  createSettlementHeaders(settleResponse) {
-    const encoded = encodePaymentResponseHeader(settleResponse);
-    return { "PAYMENT-RESPONSE": encoded };
-  }
-  /**
-   * Parse route pattern into verb and regex
-   *
-   * @param pattern - Route pattern like "GET /api/*" or "/api/[id]"
-   * @returns Parsed pattern with verb and regex
-   */
-  parseRoutePattern(pattern) {
-    const [verb, path] = pattern.includes(" ") ? pattern.split(/\s+/) : ["*", pattern];
-    const regex = new RegExp(
-      `^${path.replace(/[$()+.?^{|}]/g, "\\$&").replace(/\*/g, ".*?").replace(/\[([^\]]+)\]/g, "[^/]+").replace(/\//g, "\\/")}$`,
-      "i"
-    );
-    return { verb: verb.toUpperCase(), regex };
-  }
-  /**
-   * Normalize path for matching
-   *
-   * @param path - Raw path from request
-   * @returns Normalized path
-   */
-  normalizePath(path) {
-    const pathWithoutQuery = path.split(/[?#]/)[0];
-    let decodedOrRawPath;
-    try {
-      decodedOrRawPath = decodeURIComponent(pathWithoutQuery);
-    } catch {
-      decodedOrRawPath = pathWithoutQuery;
-    }
-    return decodedOrRawPath.replace(/\\/g, "/").replace(/\/+/g, "/").replace(/(.+?)\/+$/, "$1");
-  }
-  /**
-   * 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
-   */
-  generatePaywallHTML(paymentRequired, paywallConfig, customHtml) {
-    if (customHtml) {
-      return customHtml;
-    }
-    if (this.paywallProvider) {
-      return this.paywallProvider.generateHtml(paymentRequired, paywallConfig);
-    }
-    try {
-      const paywall = __require("@x402/paywall");
-      const displayAmount2 = this.getDisplayAmount(paymentRequired);
-      const resource2 = paymentRequired.resource;
-      return paywall.getPaywallHtml({
-        amount: displayAmount2,
-        paymentRequired,
-        currentUrl: resource2?.url || paywallConfig?.currentUrl || "",
-        testnet: paywallConfig?.testnet ?? true,
-        appName: paywallConfig?.appName,
-        appLogo: paywallConfig?.appLogo,
-        sessionTokenEndpoint: paywallConfig?.sessionTokenEndpoint
-      });
-    } catch {
-    }
-    const resource = paymentRequired.resource;
-    const displayAmount = this.getDisplayAmount(paymentRequired);
-    return `
-      <!DOCTYPE html>
-      <html>
-        <head>
-          <title>Payment Required</title>
-          <meta charset="UTF-8">
-          <meta name="viewport" content="width=device-width, initial-scale=1.0">
-        </head>
-        <body>
-          <div style="max-width: 600px; margin: 50px auto; padding: 20px; font-family: system-ui, -apple-system, sans-serif;">
-            ${paywallConfig?.appLogo ? `<img src="${paywallConfig.appLogo}" alt="${paywallConfig.appName || "App"}" style="max-width: 200px; margin-bottom: 20px;">` : ""}
-            <h1>Payment Required</h1>
-            ${resource ? `<p><strong>Resource:</strong> ${resource.description || resource.url}</p>` : ""}
-            <p><strong>Amount:</strong> $${displayAmount.toFixed(2)} USDC</p>
-            <div id="payment-widget" 
-                 data-requirements='${JSON.stringify(paymentRequired)}'
-                 data-app-name="${paywallConfig?.appName || ""}"
-                 data-testnet="${paywallConfig?.testnet || false}">
-              <!-- Install @x402/paywall for full wallet integration -->
-              <p style="margin-top: 2rem; padding: 1rem; background: #fef3c7; border-radius: 0.5rem;">
-                <strong>Note:</strong> Install <code>@x402/paywall</code> for full wallet connection and payment UI.
-              </p>
-            </div>
-          </div>
-        </body>
-      </html>
-    `;
-  }
-  /**
-   * Extract display amount from payment requirements.
-   *
-   * @param paymentRequired - The payment required object
-   * @returns The display amount in decimal format
-   */
-  getDisplayAmount(paymentRequired) {
-    const accepts = paymentRequired.accepts;
-    if (accepts && accepts.length > 0) {
-      const firstReq = accepts[0];
-      if ("amount" in firstReq) {
-        return parseFloat(firstReq.amount) / 1e6;
-      }
-    }
-    return 0;
-  }
-};
-
-// src/http/httpFacilitatorClient.ts
-var DEFAULT_FACILITATOR_URL = "https://x402.org/facilitator";
-var GET_SUPPORTED_RETRIES = 3;
-var GET_SUPPORTED_RETRY_DELAY_MS = 1e3;
-var HTTPFacilitatorClient = class {
-  /**
-   * Creates a new HTTPFacilitatorClient instance.
-   *
-   * @param config - Configuration options for the facilitator client
-   */
-  constructor(config) {
-    this.url = config?.url || DEFAULT_FACILITATOR_URL;
-    this._createAuthHeaders = config?.createAuthHeaders;
-  }
-  /**
-   * Verify a payment with the facilitator
-   *
-   * @param paymentPayload - The payment to verify
-   * @param paymentRequirements - The requirements to verify against
-   * @returns Verification response
-   */
-  async verify(paymentPayload, paymentRequirements) {
-    let headers = {
-      "Content-Type": "application/json"
-    };
-    if (this._createAuthHeaders) {
-      const authHeaders = await this.createAuthHeaders("verify");
-      headers = { ...headers, ...authHeaders.headers };
-    }
-    const response = await fetch(`${this.url}/verify`, {
-      method: "POST",
-      headers,
-      body: JSON.stringify({
-        x402Version: paymentPayload.x402Version,
-        paymentPayload: this.toJsonSafe(paymentPayload),
-        paymentRequirements: this.toJsonSafe(paymentRequirements)
-      })
-    });
-    const data = await response.json();
-    if (typeof data === "object" && data !== null && "isValid" in data) {
-      const verifyResponse = data;
-      if (!response.ok) {
-        throw new VerifyError(response.status, verifyResponse);
-      }
-      return verifyResponse;
-    }
-    throw new Error(`Facilitator verify failed (${response.status}): ${JSON.stringify(data)}`);
-  }
-  /**
-   * Settle a payment with the facilitator
-   *
-   * @param paymentPayload - The payment to settle
-   * @param paymentRequirements - The requirements for settlement
-   * @returns Settlement response
-   */
-  async settle(paymentPayload, paymentRequirements) {
-    let headers = {
-      "Content-Type": "application/json"
-    };
-    if (this._createAuthHeaders) {
-      const authHeaders = await this.createAuthHeaders("settle");
-      headers = { ...headers, ...authHeaders.headers };
-    }
-    const response = await fetch(`${this.url}/settle`, {
-      method: "POST",
-      headers,
-      body: JSON.stringify({
-        x402Version: paymentPayload.x402Version,
-        paymentPayload: this.toJsonSafe(paymentPayload),
-        paymentRequirements: this.toJsonSafe(paymentRequirements)
-      })
-    });
-    const data = await response.json();
-    if (typeof data === "object" && data !== null && "success" in data) {
-      const settleResponse = data;
-      if (!response.ok) {
-        throw new SettleError(response.status, settleResponse);
-      }
-      return settleResponse;
-    }
-    throw new Error(`Facilitator settle failed (${response.status}): ${JSON.stringify(data)}`);
-  }
-  /**
-   * Get supported payment kinds and extensions from the facilitator.
-   * Retries with exponential backoff on 429 rate limit errors.
-   *
-   * @returns Supported payment kinds and extensions
-   */
-  async getSupported() {
-    let headers = {
-      "Content-Type": "application/json"
-    };
-    if (this._createAuthHeaders) {
-      const authHeaders = await this.createAuthHeaders("supported");
-      headers = { ...headers, ...authHeaders.headers };
-    }
-    let lastError = null;
-    for (let attempt = 0; attempt < GET_SUPPORTED_RETRIES; attempt++) {
-      const response = await fetch(`${this.url}/supported`, {
-        method: "GET",
-        headers
-      });
-      if (response.ok) {
-        return await response.json();
-      }
-      const errorText = await response.text().catch(() => response.statusText);
-      lastError = new Error(`Facilitator getSupported failed (${response.status}): ${errorText}`);
-      if (response.status === 429 && attempt < GET_SUPPORTED_RETRIES - 1) {
-        const delay = GET_SUPPORTED_RETRY_DELAY_MS * Math.pow(2, attempt);
-        await new Promise((resolve) => setTimeout(resolve, delay));
-        continue;
-      }
-      throw lastError;
-    }
-    throw lastError ?? new Error("Facilitator getSupported failed after retries");
-  }
-  /**
-   * Creates authentication headers for a specific path.
-   *
-   * @param path - The path to create authentication headers for (e.g., "verify", "settle", "supported")
-   * @returns An object containing the authentication headers for the specified path
-   */
-  async createAuthHeaders(path) {
-    if (this._createAuthHeaders) {
-      const authHeaders = await this._createAuthHeaders();
-      return {
-        headers: authHeaders[path] ?? {}
-      };
-    }
-    return {
-      headers: {}
-    };
-  }
-  /**
-   * Helper to convert objects to JSON-safe format.
-   * Handles BigInt and other non-JSON types.
-   *
-   * @param obj - The object to convert
-   * @returns The JSON-safe representation of the object
-   */
-  toJsonSafe(obj) {
-    return JSON.parse(
-      JSON.stringify(obj, (_, value) => typeof value === "bigint" ? value.toString() : value)
-    );
-  }
-};
-
-// src/http/x402HTTPClient.ts
-var x402HTTPClient = class {
-  /**
-   * Creates a new x402HTTPClient instance.
-   *
-   * @param client - The underlying x402Client for payment logic
-   */
-  constructor(client) {
-    this.client = client;
-    this.paymentRequiredHooks = [];
-  }
-  /**
-   * Register a hook to handle 402 responses before payment.
-   * Hooks run in order; first to return headers wins.
-   *
-   * @param hook - The hook function to register
-   * @returns This instance for chaining
-   */
-  onPaymentRequired(hook) {
-    this.paymentRequiredHooks.push(hook);
-    return this;
-  }
-  /**
-   * Run hooks and return headers if any hook provides them.
-   *
-   * @param paymentRequired - The payment required response from the server
-   * @returns Headers to use for retry, or null to proceed to payment
-   */
-  async handlePaymentRequired(paymentRequired) {
-    for (const hook of this.paymentRequiredHooks) {
-      const result = await hook({ paymentRequired });
-      if (result?.headers) {
-        return result.headers;
-      }
-    }
-    return null;
-  }
-  /**
-   * Encodes a payment payload into appropriate HTTP headers based on version.
-   *
-   * @param paymentPayload - The payment payload to encode
-   * @returns HTTP headers containing the encoded payment signature
-   */
-  encodePaymentSignatureHeader(paymentPayload) {
-    switch (paymentPayload.x402Version) {
-      case 2:
-        return {
-          "PAYMENT-SIGNATURE": encodePaymentSignatureHeader(paymentPayload)
-        };
-      case 1:
-        return {
-          "X-PAYMENT": encodePaymentSignatureHeader(paymentPayload)
-        };
-      default:
-        throw new Error(
-          `Unsupported x402 version: ${paymentPayload.x402Version}`
-        );
-    }
-  }
-  /**
-   * Extracts payment required information from HTTP response.
-   *
-   * @param getHeader - Function to retrieve header value by name (case-insensitive)
-   * @param body - Optional response body for v1 compatibility
-   * @returns The payment required object
-   */
-  getPaymentRequiredResponse(getHeader, body) {
-    const paymentRequired = getHeader("PAYMENT-REQUIRED");
-    if (paymentRequired) {
-      return decodePaymentRequiredHeader(paymentRequired);
-    }
-    if (body && body instanceof Object && "x402Version" in body && body.x402Version === 1) {
-      return body;
-    }
-    throw new Error("Invalid payment required response");
-  }
-  /**
-   * Extracts payment settlement response from HTTP headers.
-   *
-   * @param getHeader - Function to retrieve header value by name (case-insensitive)
-   * @returns The settlement response object
-   */
-  getPaymentSettleResponse(getHeader) {
-    const paymentResponse = getHeader("PAYMENT-RESPONSE");
-    if (paymentResponse) {
-      return decodePaymentResponseHeader(paymentResponse);
-    }
-    const xPaymentResponse = getHeader("X-PAYMENT-RESPONSE");
-    if (xPaymentResponse) {
-      return decodePaymentResponseHeader(xPaymentResponse);
-    }
-    throw new Error("Payment response header not found");
-  }
-  /**
-   * Creates a payment payload for the given payment requirements.
-   * Delegates to the underlying x402Client.
-   *
-   * @param paymentRequired - The payment required response from the server
-   * @returns Promise resolving to the payment payload
-   */
-  async createPaymentPayload(paymentRequired) {
-    return this.client.createPaymentPayload(paymentRequired);
-  }
-};
-
-// src/http/index.ts
-function encodePaymentSignatureHeader(paymentPayload) {
-  return safeBase64Encode(JSON.stringify(paymentPayload));
-}
-function decodePaymentSignatureHeader(paymentSignatureHeader) {
-  if (!Base64EncodedRegex.test(paymentSignatureHeader)) {
-    throw new Error("Invalid payment signature header");
-  }
-  return JSON.parse(safeBase64Decode(paymentSignatureHeader));
-}
-function encodePaymentRequiredHeader(paymentRequired) {
-  return safeBase64Encode(JSON.stringify(paymentRequired));
-}
-function decodePaymentRequiredHeader(paymentRequiredHeader) {
-  if (!Base64EncodedRegex.test(paymentRequiredHeader)) {
-    throw new Error("Invalid payment required header");
-  }
-  return JSON.parse(safeBase64Decode(paymentRequiredHeader));
-}
-function encodePaymentResponseHeader(paymentResponse) {
-  return safeBase64Encode(JSON.stringify(paymentResponse));
-}
-function decodePaymentResponseHeader(paymentResponseHeader) {
-  if (!Base64EncodedRegex.test(paymentResponseHeader)) {
-    throw new Error("Invalid payment response header");
-  }
-  return JSON.parse(safeBase64Decode(paymentResponseHeader));
-}
-
-export {
-  RouteConfigurationError,
-  x402HTTPResourceServer,
-  HTTPFacilitatorClient,
-  encodePaymentSignatureHeader,
-  decodePaymentSignatureHeader,
-  encodePaymentRequiredHeader,
-  decodePaymentRequiredHeader,
-  encodePaymentResponseHeader,
-  decodePaymentResponseHeader,
-  x402HTTPClient
-};
-//# sourceMappingURL=chunk-CM4FD6HG.mjs.map

dist/esm/x402HTTPResourceServer-B-i4cmSW.d.mts

-import { x as x402ResourceServer, h as Price, N as Network, S as SettleResponse, c as PaymentRequired, P as PaymentPayload, a as PaymentRequirements } from './mechanisms-e8RNDWpU.mjs';
-
-/**
- * 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;
-}
-/**
- * HTTP request context that encapsulates all request data
- */
-interface HTTPRequestContext {
-    adapter: HTTPAdapter;
-    path: string;
-    method: string;
-    paymentHeader?: 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;
-}
-/**
- * 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[]);
-}
-/**
- * HTTP-enhanced x402 resource server
- * Provides framework-agnostic HTTP protocol handling
- */
-declare class x402HTTPResourceServer {
-    private ResourceServer;
-    private compiledRoutes;
-    private routesConfig;
-    private paywallProvider?;
-    private protectedRequestHooks;
-    /**
-     * 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;
-    /**
-     * 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
-     * @returns ProcessSettleResultResponse - SettleResponse with headers if success or errorReason if failure
-     */
-    processSettlement(paymentPayload: PaymentPayload, requirements: PaymentRequirements, declaredExtensions?: Record<string, unknown>, transportContext?: HTTPTransportContext): 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 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/*" 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 PaywallConfig as P, type RouteConfig as R, type SettlementFailedResponseBody as S, type UnpaidResponseBody as U, type HTTPRequestContext as a, type HTTPTransportContext as b, type HTTPResponseInstructions as c, type HTTPProcessResult as d, type PaywallProvider as e, type PaymentOption as f, type RoutesConfig as g, type DynamicPrice as h, type HTTPResponseBody as i, type ProcessSettleResultResponse as j, type ProcessSettleSuccessResponse as k, type ProcessSettleFailureResponse as l, type RouteValidationError as m, RouteConfigurationError as n, type ProtectedRequestHook as o, x402HTTPResourceServer as x };

New alerts

Network access

Supply chain risk

This module accesses the network.

Found 1 instance in 1 package

Long strings

Supply chain risk

Contains long string literals, which may be a sign of obfuscated or packed code.

Found 1 instance in 1 package

Fixed alerts

Network access

Supply chain risk

This module accesses the network.

Found 1 instance in 1 package

Long strings

Supply chain risk

Contains long string literals, which may be a sign of obfuscated or packed code.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

903352

0.08%

No dependency changes