x402-core-mantle 2.1.1-mantle

package/dist/esm/client/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/client/x402Client.ts"],"sourcesContent":["import { x402Version } from \"..\";\nimport { SchemeNetworkClient } from \"../types/mechanisms\";\nimport { PaymentPayload, PaymentRequirements } from \"../types/payments\";\nimport { Network, PaymentRequired } from \"../types\";\nimport { findByNetworkAndScheme, findSchemesByNetwork } from \"../utils\";\n\n/**\n * Client Hook Context Interfaces\n */\n\nexport interface PaymentCreationContext {\n  paymentRequired: PaymentRequired;\n  selectedRequirements: PaymentRequirements;\n}\n\nexport interface PaymentCreatedContext extends PaymentCreationContext {\n  paymentPayload: PaymentPayload;\n}\n\nexport interface PaymentCreationFailureContext extends PaymentCreationContext {\n  error: Error;\n}\n\n/**\n * Client Hook Type Definitions\n */\n\nexport type BeforePaymentCreationHook = (\n  context: PaymentCreationContext,\n) => Promise<void | { abort: true; reason: string }>;\n\nexport type AfterPaymentCreationHook = (context: PaymentCreatedContext) => Promise<void>;\n\nexport type OnPaymentCreationFailureHook = (\n  context: PaymentCreationFailureContext,\n) => Promise<void | { recovered: true; payload: PaymentPayload }>;\n\nexport type SelectPaymentRequirements = (x402Version: number, paymentRequirements: PaymentRequirements[]) => PaymentRequirements;\n\n/**\n * A policy function that filters or transforms payment requirements.\n * Policies are applied in order before the selector chooses the final option.\n *\n * @param x402Version - The x402 protocol version\n * @param paymentRequirements - Array of payment requirements to filter/transform\n * @returns Filtered array of payment requirements\n */\nexport type PaymentPolicy = (x402Version: number, paymentRequirements: PaymentRequirements[]) => PaymentRequirements[];\n\n\n/**\n * Configuration for registering a payment scheme with a specific network\n */\nexport interface SchemeRegistration {\n  /**\n   * The network identifier (e.g., 'eip155:8453', 'solana:mainnet')\n   */\n  network: Network;\n\n  /**\n   * The scheme client implementation for this network\n   */\n  client: SchemeNetworkClient;\n\n  /**\n   * The x402 protocol version to use for this scheme\n   *\n   * @default 2\n   */\n  x402Version?: number;\n}\n\n/**\n * Configuration options for the fetch wrapper\n */\nexport interface x402ClientConfig {\n  /**\n   * Array of scheme registrations defining which payment methods are supported\n   */\n  schemes: SchemeRegistration[];\n\n  /**\n   * Policies to apply to the client\n   */\n  policies?: PaymentPolicy[];\n\n  /**\n   * Custom payment requirements selector function\n   * If not provided, uses the default selector (first available option)\n   */\n  paymentRequirementsSelector?: SelectPaymentRequirements;\n}\n\n/**\n * Core client for managing x402 payment schemes and creating payment payloads.\n *\n * Handles registration of payment schemes, policy-based filtering of payment requirements,\n * and creation of payment payloads based on server requirements.\n */\nexport class x402Client {\n  private readonly paymentRequirementsSelector: SelectPaymentRequirements;\n  private readonly registeredClientSchemes: Map<number, Map<string, Map<string, SchemeNetworkClient>>> = new Map();\n  private readonly policies: PaymentPolicy[] = [];\n\n  private beforePaymentCreationHooks: BeforePaymentCreationHook[] = [];\n  private afterPaymentCreationHooks: AfterPaymentCreationHook[] = [];\n  private onPaymentCreationFailureHooks: OnPaymentCreationFailureHook[] = [];\n\n  /**\n   * Creates a new x402Client instance.\n   *\n   * @param paymentRequirementsSelector - Function to select payment requirements from available options\n   */\n  constructor(paymentRequirementsSelector?: SelectPaymentRequirements) {\n    this.paymentRequirementsSelector = paymentRequirementsSelector || ((x402Version, accepts) => accepts[0]);\n  }\n\n  /**\n   * Creates a new x402Client instance from a configuration object.\n   *\n   * @param config - The client configuration including schemes, policies, and payment requirements selector\n   * @returns A configured x402Client instance\n   */\n  static fromConfig(config: x402ClientConfig): x402Client {\n    const client = new x402Client(config.paymentRequirementsSelector);\n    config.schemes.forEach(scheme => {\n      if (scheme.x402Version === 1) {\n        client.registerV1(scheme.network, scheme.client);\n      } else {\n        client.register(scheme.network, scheme.client);\n      }\n    });\n    config.policies?.forEach(policy => {\n      client.registerPolicy(policy);\n    });\n    return client;\n  }\n\n  /**\n   * Registers a scheme client for the current x402 version.\n   *\n   * @param network - The network to register the client for\n   * @param client - The scheme network client to register\n   * @returns The x402Client instance for chaining\n   */\n  register(network: Network, client: SchemeNetworkClient): x402Client {\n    return this._registerScheme(x402Version, network, client);\n  }\n\n  /**\n   * Registers a scheme client for x402 version 1.\n   *\n   * @param network - The v1 network identifier (e.g., 'base-sepolia', 'solana-devnet')\n   * @param client - The scheme network client to register\n   * @returns The x402Client instance for chaining\n   */\n  registerV1(network: string, client: SchemeNetworkClient): x402Client {\n    return this._registerScheme(1, network as Network, client);\n  }\n\n  /**\n   * Registers a policy to filter or transform payment requirements.\n   *\n   * Policies are applied in order after filtering by registered schemes\n   * and before the selector chooses the final payment requirement.\n   *\n   * @param policy - Function to filter/transform payment requirements\n   * @returns The x402Client instance for chaining\n   *\n   * @example\n   * ```typescript\n   * // Prefer cheaper options\n   * client.registerPolicy((version, reqs) =>\n   *   reqs.filter(r => BigInt(r.value) < BigInt('1000000'))\n   * );\n   *\n   * // Prefer specific networks\n   * client.registerPolicy((version, reqs) =>\n   *   reqs.filter(r => r.network.startsWith('eip155:'))\n   * );\n   * ```\n   */\n  registerPolicy(policy: PaymentPolicy): x402Client {\n    this.policies.push(policy);\n    return this;\n  }\n\n  /**\n   * Register a hook to execute before payment payload creation.\n   * Can abort creation by returning { abort: true, reason: string }\n   *\n   * @param hook - The hook function to register\n   * @returns The x402Client instance for chaining\n   */\n  onBeforePaymentCreation(hook: BeforePaymentCreationHook): x402Client {\n    this.beforePaymentCreationHooks.push(hook);\n    return this;\n  }\n\n  /**\n   * Register a hook to execute after successful payment payload creation.\n   *\n   * @param hook - The hook function to register\n   * @returns The x402Client instance for chaining\n   */\n  onAfterPaymentCreation(hook: AfterPaymentCreationHook): x402Client {\n    this.afterPaymentCreationHooks.push(hook);\n    return this;\n  }\n\n  /**\n   * Register a hook to execute when payment payload creation fails.\n   * Can recover from failure by returning { recovered: true, payload: PaymentPayload }\n   *\n   * @param hook - The hook function to register\n   * @returns The x402Client instance for chaining\n   */\n  onPaymentCreationFailure(hook: OnPaymentCreationFailureHook): x402Client {\n    this.onPaymentCreationFailureHooks.push(hook);\n    return this;\n  }\n\n  /**\n   * Creates a payment payload based on a PaymentRequired response.\n   *\n   * Automatically extracts x402Version, resource, and extensions from the PaymentRequired\n   * response and constructs a complete PaymentPayload with the accepted requirements.\n   *\n   * @param paymentRequired - The PaymentRequired response from the server\n   * @returns Promise resolving to the complete payment payload\n   */\n  async createPaymentPayload(\n    paymentRequired: PaymentRequired,\n  ): Promise<PaymentPayload> {\n    const clientSchemesByNetwork = this.registeredClientSchemes.get(paymentRequired.x402Version);\n    if (!clientSchemesByNetwork) {\n      throw new Error(`No client registered for x402 version: ${paymentRequired.x402Version}`);\n    }\n\n    const requirements = this.selectPaymentRequirements(paymentRequired.x402Version, paymentRequired.accepts);\n\n    const context: PaymentCreationContext = {\n      paymentRequired,\n      selectedRequirements: requirements,\n    };\n\n    // Execute beforePaymentCreation hooks\n    for (const hook of this.beforePaymentCreationHooks) {\n      const result = await hook(context);\n      if (result && \"abort\" in result && result.abort) {\n        throw new Error(`Payment creation aborted: ${result.reason}`);\n      }\n    }\n\n    try {\n      const schemeNetworkClient = findByNetworkAndScheme(clientSchemesByNetwork, requirements.scheme, requirements.network);\n      if (!schemeNetworkClient) {\n        throw new Error(`No client registered for scheme: ${requirements.scheme} and network: ${requirements.network}`);\n      }\n\n      const partialPayload = await schemeNetworkClient.createPaymentPayload(paymentRequired.x402Version, requirements);\n\n      let paymentPayload: PaymentPayload;\n      if (partialPayload.x402Version == 1) {\n        paymentPayload = partialPayload as PaymentPayload;\n      } else {\n        paymentPayload = {\n          ...partialPayload,\n          extensions: paymentRequired.extensions,\n          resource: paymentRequired.resource,\n          accepted: requirements,\n        };\n      }\n\n      // Execute afterPaymentCreation hooks\n      const createdContext: PaymentCreatedContext = {\n        ...context,\n        paymentPayload,\n      };\n\n      for (const hook of this.afterPaymentCreationHooks) {\n        await hook(createdContext);\n      }\n\n      return paymentPayload;\n    } catch (error) {\n      const failureContext: PaymentCreationFailureContext = {\n        ...context,\n        error: error as Error,\n      };\n\n      // Execute onPaymentCreationFailure hooks\n      for (const hook of this.onPaymentCreationFailureHooks) {\n        const result = await hook(failureContext);\n        if (result && \"recovered\" in result && result.recovered) {\n          return result.payload;\n        }\n      }\n\n      throw error;\n    }\n  }\n\n\n\n  /**\n   * Selects appropriate payment requirements based on registered clients and policies.\n   *\n   * Selection process:\n   * 1. Filter by registered schemes (network + scheme support)\n   * 2. Apply all registered policies in order\n   * 3. Use selector to choose final requirement\n   *\n   * @param x402Version - The x402 protocol version\n   * @param paymentRequirements - Array of available payment requirements\n   * @returns The selected payment requirements\n   */\n  private selectPaymentRequirements(x402Version: number, paymentRequirements: PaymentRequirements[]): PaymentRequirements {\n    const clientSchemesByNetwork = this.registeredClientSchemes.get(x402Version);\n    if (!clientSchemesByNetwork) {\n      throw new Error(`No client registered for x402 version: ${x402Version}`);\n    }\n\n    // Step 1: Filter by registered schemes\n    const supportedPaymentRequirements = paymentRequirements.filter(requirement => {\n      let clientSchemes = findSchemesByNetwork(clientSchemesByNetwork, requirement.network);\n      if (!clientSchemes) {\n        return false;\n      }\n\n      return clientSchemes.has(requirement.scheme);\n    })\n\n    if (supportedPaymentRequirements.length === 0) {\n      throw new Error(`No network/scheme registered for x402 version: ${x402Version} which comply with the payment requirements. ${JSON.stringify({\n        x402Version,\n        paymentRequirements,\n        x402Versions: Array.from(this.registeredClientSchemes.keys()),\n        networks: Array.from(clientSchemesByNetwork.keys()),\n        schemes: Array.from(clientSchemesByNetwork.values()).map(schemes => Array.from(schemes.keys())).flat(),\n      })}`);\n    }\n\n    // Step 2: Apply all policies in order\n    let filteredRequirements = supportedPaymentRequirements;\n    for (const policy of this.policies) {\n      filteredRequirements = policy(x402Version, filteredRequirements);\n\n      if (filteredRequirements.length === 0) {\n        throw new Error(`All payment requirements were filtered out by policies for x402 version: ${x402Version}`);\n      }\n    }\n\n    // Step 3: Use selector to choose final requirement\n    return this.paymentRequirementsSelector(x402Version, filteredRequirements);\n  }\n\n  /**\n   * Internal method to register a scheme client.\n   *\n   * @param x402Version - The x402 protocol version\n   * @param network - The network to register the client for\n   * @param client - The scheme network client to register\n   * @returns The x402Client instance for chaining\n   */\n  private _registerScheme(x402Version: number, network: Network, client: SchemeNetworkClient): x402Client {\n    if (!this.registeredClientSchemes.has(x402Version)) {\n      this.registeredClientSchemes.set(x402Version, new Map());\n    }\n    const clientSchemesByNetwork = this.registeredClientSchemes.get(x402Version)!;\n    if (!clientSchemesByNetwork.has(network)) {\n      clientSchemesByNetwork.set(network, new Map());\n    }\n\n    const clientByScheme = clientSchemesByNetwork.get(network)!;\n    if (!clientByScheme.has(client.scheme)) {\n      clientByScheme.set(client.scheme, client);\n    }\n\n    return this;\n  }\n}\n"],"mappings":"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","names":["x402Version"]}

package/dist/esm/facilitator/index.d.mts

@@ -0,0 +1,192 @@
+import { P as PaymentPayload, a as PaymentRequirements, V as VerifyResponse, S as SettleResponse, N as Network, b as SchemeNetworkFacilitator } from '../mechanisms-CzuGzYsS.mjs';
+
+/**
+ * Facilitator Hook Context Interfaces
+ */
+interface FacilitatorVerifyContext {
+    paymentPayload: PaymentPayload;
+    requirements: PaymentRequirements;
+}
+interface FacilitatorVerifyResultContext extends FacilitatorVerifyContext {
+    result: VerifyResponse;
+}
+interface FacilitatorVerifyFailureContext extends FacilitatorVerifyContext {
+    error: Error;
+}
+interface FacilitatorSettleContext {
+    paymentPayload: PaymentPayload;
+    requirements: PaymentRequirements;
+}
+interface FacilitatorSettleResultContext extends FacilitatorSettleContext {
+    result: SettleResponse;
+}
+interface FacilitatorSettleFailureContext extends FacilitatorSettleContext {
+    error: Error;
+}
+/**
+ * Facilitator Hook Type Definitions
+ */
+type FacilitatorBeforeVerifyHook = (context: FacilitatorVerifyContext) => Promise<void | {
+    abort: true;
+    reason: string;
+}>;
+type FacilitatorAfterVerifyHook = (context: FacilitatorVerifyResultContext) => Promise<void>;
+type FacilitatorOnVerifyFailureHook = (context: FacilitatorVerifyFailureContext) => Promise<void | {
+    recovered: true;
+    result: VerifyResponse;
+}>;
+type FacilitatorBeforeSettleHook = (context: FacilitatorSettleContext) => Promise<void | {
+    abort: true;
+    reason: string;
+}>;
+type FacilitatorAfterSettleHook = (context: FacilitatorSettleResultContext) => Promise<void>;
+type FacilitatorOnSettleFailureHook = (context: FacilitatorSettleFailureContext) => Promise<void | {
+    recovered: true;
+    result: SettleResponse;
+}>;
+/**
+ * Facilitator client for the x402 payment protocol.
+ * Manages payment scheme registration, verification, and settlement.
+ */
+declare class x402Facilitator {
+    private readonly registeredFacilitatorSchemes;
+    private readonly extensions;
+    private beforeVerifyHooks;
+    private afterVerifyHooks;
+    private onVerifyFailureHooks;
+    private beforeSettleHooks;
+    private afterSettleHooks;
+    private onSettleFailureHooks;
+    /**
+     * Registers a scheme facilitator for the current x402 version.
+     * Networks are stored and used for getSupported() - no need to specify them later.
+     *
+     * @param networks - Single network or array of networks this facilitator supports
+     * @param facilitator - The scheme network facilitator to register
+     * @returns The x402Facilitator instance for chaining
+     */
+    register(networks: Network | Network[], facilitator: SchemeNetworkFacilitator): x402Facilitator;
+    /**
+     * Registers a scheme facilitator for x402 version 1.
+     * Networks are stored and used for getSupported() - no need to specify them later.
+     *
+     * @param networks - Single network or array of networks this facilitator supports
+     * @param facilitator - The scheme network facilitator to register
+     * @returns The x402Facilitator instance for chaining
+     */
+    registerV1(networks: Network | Network[], facilitator: SchemeNetworkFacilitator): x402Facilitator;
+    /**
+     * Registers a protocol extension.
+     *
+     * @param extension - The extension name to register (e.g., "bazaar", "sign_in_with_x")
+     * @returns The x402Facilitator instance for chaining
+     */
+    registerExtension(extension: string): x402Facilitator;
+    /**
+     * Gets the list of registered extensions.
+     *
+     * @returns Array of extension names
+     */
+    getExtensions(): string[];
+    /**
+     * Register a hook to execute before facilitator payment verification.
+     * Can abort verification by returning { abort: true, reason: string }
+     *
+     * @param hook - The hook function to register
+     * @returns The x402Facilitator instance for chaining
+     */
+    onBeforeVerify(hook: FacilitatorBeforeVerifyHook): x402Facilitator;
+    /**
+     * Register a hook to execute after successful facilitator payment verification (isValid: true).
+     * This hook is NOT called when verification fails (isValid: false) - use onVerifyFailure for that.
+     *
+     * @param hook - The hook function to register
+     * @returns The x402Facilitator instance for chaining
+     */
+    onAfterVerify(hook: FacilitatorAfterVerifyHook): x402Facilitator;
+    /**
+     * Register a hook to execute when facilitator payment verification fails.
+     * Called when: verification returns isValid: false, or an exception is thrown during verification.
+     * Can recover from failure by returning { recovered: true, result: VerifyResponse }
+     *
+     * @param hook - The hook function to register
+     * @returns The x402Facilitator instance for chaining
+     */
+    onVerifyFailure(hook: FacilitatorOnVerifyFailureHook): x402Facilitator;
+    /**
+     * Register a hook to execute before facilitator payment settlement.
+     * Can abort settlement by returning { abort: true, reason: string }
+     *
+     * @param hook - The hook function to register
+     * @returns The x402Facilitator instance for chaining
+     */
+    onBeforeSettle(hook: FacilitatorBeforeSettleHook): x402Facilitator;
+    /**
+     * Register a hook to execute after successful facilitator payment settlement.
+     *
+     * @param hook - The hook function to register
+     * @returns The x402Facilitator instance for chaining
+     */
+    onAfterSettle(hook: FacilitatorAfterSettleHook): x402Facilitator;
+    /**
+     * Register a hook to execute when facilitator payment settlement fails.
+     * Can recover from failure by returning { recovered: true, result: SettleResponse }
+     *
+     * @param hook - The hook function to register
+     * @returns The x402Facilitator instance for chaining
+     */
+    onSettleFailure(hook: FacilitatorOnSettleFailureHook): x402Facilitator;
+    /**
+     * Gets supported payment kinds, extensions, and signers.
+     * Uses networks registered during register() calls - no parameters needed.
+     * Returns flat array format for backward compatibility with V1 clients.
+     *
+     * @returns Supported response with kinds as array (with version in each element), extensions, and signers
+     */
+    getSupported(): {
+        kinds: Array<{
+            x402Version: number;
+            scheme: string;
+            network: string;
+            extra?: Record<string, unknown>;
+        }>;
+        extensions: string[];
+        signers: Record<string, string[]>;
+    };
+    /**
+     * Verifies a payment payload against requirements.
+     *
+     * @param paymentPayload - The payment payload to verify
+     * @param paymentRequirements - The payment requirements to verify against
+     * @returns Promise resolving to the verification response
+     */
+    verify(paymentPayload: PaymentPayload, paymentRequirements: PaymentRequirements): Promise<VerifyResponse>;
+    /**
+     * Settles a payment based on the payload and requirements.
+     *
+     * @param paymentPayload - The payment payload to settle
+     * @param paymentRequirements - The payment requirements for settlement
+     * @returns Promise resolving to the settlement response
+     */
+    settle(paymentPayload: PaymentPayload, paymentRequirements: PaymentRequirements): Promise<SettleResponse>;
+    /**
+     * Internal method to register a scheme facilitator.
+     *
+     * @param x402Version - The x402 protocol version
+     * @param networks - Array of concrete networks this facilitator supports
+     * @param facilitator - The scheme network facilitator to register
+     * @returns The x402Facilitator instance for chaining
+     */
+    private _registerScheme;
+    /**
+     * Derives a wildcard pattern from an array of networks.
+     * If all networks share the same namespace, returns wildcard pattern.
+     * Otherwise returns the first network for exact matching.
+     *
+     * @param networks - Array of networks
+     * @returns Derived pattern for matching
+     */
+    private derivePattern;
+}
+
+export { type FacilitatorAfterSettleHook, type FacilitatorAfterVerifyHook, type FacilitatorBeforeSettleHook, type FacilitatorBeforeVerifyHook, type FacilitatorOnSettleFailureHook, type FacilitatorOnVerifyFailureHook, type FacilitatorSettleContext, type FacilitatorSettleFailureContext, type FacilitatorSettleResultContext, type FacilitatorVerifyContext, type FacilitatorVerifyFailureContext, type FacilitatorVerifyResultContext, x402Facilitator };

package/dist/esm/facilitator/index.mjs

@@ -0,0 +1,373 @@
+import {
+  x402Version
+} from "../chunk-VE37GDG2.mjs";
+import "../chunk-BJTO5JO5.mjs";
+
+// src/facilitator/x402Facilitator.ts
+var x402Facilitator = class {
+  constructor() {
+    this.registeredFacilitatorSchemes = /* @__PURE__ */ new Map();
+    this.extensions = [];
+    this.beforeVerifyHooks = [];
+    this.afterVerifyHooks = [];
+    this.onVerifyFailureHooks = [];
+    this.beforeSettleHooks = [];
+    this.afterSettleHooks = [];
+    this.onSettleFailureHooks = [];
+  }
+  /**
+   * Registers a scheme facilitator for the current x402 version.
+   * Networks are stored and used for getSupported() - no need to specify them later.
+   *
+   * @param networks - Single network or array of networks this facilitator supports
+   * @param facilitator - The scheme network facilitator to register
+   * @returns The x402Facilitator instance for chaining
+   */
+  register(networks, facilitator) {
+    const networksArray = Array.isArray(networks) ? networks : [networks];
+    return this._registerScheme(x402Version, networksArray, facilitator);
+  }
+  /**
+   * Registers a scheme facilitator for x402 version 1.
+   * Networks are stored and used for getSupported() - no need to specify them later.
+   *
+   * @param networks - Single network or array of networks this facilitator supports
+   * @param facilitator - The scheme network facilitator to register
+   * @returns The x402Facilitator instance for chaining
+   */
+  registerV1(networks, facilitator) {
+    const networksArray = Array.isArray(networks) ? networks : [networks];
+    return this._registerScheme(1, networksArray, facilitator);
+  }
+  /**
+   * Registers a protocol extension.
+   *
+   * @param extension - The extension name to register (e.g., "bazaar", "sign_in_with_x")
+   * @returns The x402Facilitator instance for chaining
+   */
+  registerExtension(extension) {
+    if (!this.extensions.includes(extension)) {
+      this.extensions.push(extension);
+    }
+    return this;
+  }
+  /**
+   * Gets the list of registered extensions.
+   *
+   * @returns Array of extension names
+   */
+  getExtensions() {
+    return [...this.extensions];
+  }
+  /**
+   * Register a hook to execute before facilitator payment verification.
+   * Can abort verification by returning { abort: true, reason: string }
+   *
+   * @param hook - The hook function to register
+   * @returns The x402Facilitator instance for chaining
+   */
+  onBeforeVerify(hook) {
+    this.beforeVerifyHooks.push(hook);
+    return this;
+  }
+  /**
+   * Register a hook to execute after successful facilitator payment verification (isValid: true).
+   * This hook is NOT called when verification fails (isValid: false) - use onVerifyFailure for that.
+   *
+   * @param hook - The hook function to register
+   * @returns The x402Facilitator instance for chaining
+   */
+  onAfterVerify(hook) {
+    this.afterVerifyHooks.push(hook);
+    return this;
+  }
+  /**
+   * Register a hook to execute when facilitator payment verification fails.
+   * Called when: verification returns isValid: false, or an exception is thrown during verification.
+   * Can recover from failure by returning { recovered: true, result: VerifyResponse }
+   *
+   * @param hook - The hook function to register
+   * @returns The x402Facilitator instance for chaining
+   */
+  onVerifyFailure(hook) {
+    this.onVerifyFailureHooks.push(hook);
+    return this;
+  }
+  /**
+   * Register a hook to execute before facilitator payment settlement.
+   * Can abort settlement by returning { abort: true, reason: string }
+   *
+   * @param hook - The hook function to register
+   * @returns The x402Facilitator instance for chaining
+   */
+  onBeforeSettle(hook) {
+    this.beforeSettleHooks.push(hook);
+    return this;
+  }
+  /**
+   * Register a hook to execute after successful facilitator payment settlement.
+   *
+   * @param hook - The hook function to register
+   * @returns The x402Facilitator instance for chaining
+   */
+  onAfterSettle(hook) {
+    this.afterSettleHooks.push(hook);
+    return this;
+  }
+  /**
+   * Register a hook to execute when facilitator payment settlement fails.
+   * Can recover from failure by returning { recovered: true, result: SettleResponse }
+   *
+   * @param hook - The hook function to register
+   * @returns The x402Facilitator instance for chaining
+   */
+  onSettleFailure(hook) {
+    this.onSettleFailureHooks.push(hook);
+    return this;
+  }
+  /**
+   * Gets supported payment kinds, extensions, and signers.
+   * Uses networks registered during register() calls - no parameters needed.
+   * Returns flat array format for backward compatibility with V1 clients.
+   *
+   * @returns Supported response with kinds as array (with version in each element), extensions, and signers
+   */
+  getSupported() {
+    const kinds = [];
+    const signersByFamily = {};
+    for (const [version, schemeDataArray] of this.registeredFacilitatorSchemes) {
+      for (const schemeData of schemeDataArray) {
+        const { facilitator, networks } = schemeData;
+        const scheme = facilitator.scheme;
+        for (const network of networks) {
+          const extra = facilitator.getExtra(network);
+          kinds.push({
+            x402Version: version,
+            scheme,
+            network,
+            ...extra && { extra }
+          });
+          const family = facilitator.caipFamily;
+          if (!signersByFamily[family]) {
+            signersByFamily[family] = /* @__PURE__ */ new Set();
+          }
+          facilitator.getSigners(network).forEach((signer) => signersByFamily[family].add(signer));
+        }
+      }
+    }
+    const signers = {};
+    for (const [family, signerSet] of Object.entries(signersByFamily)) {
+      signers[family] = Array.from(signerSet);
+    }
+    return {
+      kinds,
+      extensions: this.extensions,
+      signers
+    };
+  }
+  /**
+   * Verifies a payment payload against requirements.
+   *
+   * @param paymentPayload - The payment payload to verify
+   * @param paymentRequirements - The payment requirements to verify against
+   * @returns Promise resolving to the verification response
+   */
+  async verify(paymentPayload, paymentRequirements) {
+    const context = {
+      paymentPayload,
+      requirements: paymentRequirements
+    };
+    for (const hook of this.beforeVerifyHooks) {
+      const result = await hook(context);
+      if (result && "abort" in result && result.abort) {
+        return {
+          isValid: false,
+          invalidReason: result.reason
+        };
+      }
+    }
+    try {
+      const schemeDataArray = this.registeredFacilitatorSchemes.get(paymentPayload.x402Version);
+      if (!schemeDataArray) {
+        throw new Error(
+          `No facilitator registered for x402 version: ${paymentPayload.x402Version}`
+        );
+      }
+      let schemeNetworkFacilitator;
+      for (const schemeData of schemeDataArray) {
+        if (schemeData.facilitator.scheme === paymentRequirements.scheme) {
+          if (schemeData.networks.has(paymentRequirements.network)) {
+            schemeNetworkFacilitator = schemeData.facilitator;
+            break;
+          }
+          const patternRegex = new RegExp("^" + schemeData.pattern.replace("*", ".*") + "$");
+          if (patternRegex.test(paymentRequirements.network)) {
+            schemeNetworkFacilitator = schemeData.facilitator;
+            break;
+          }
+        }
+      }
+      if (!schemeNetworkFacilitator) {
+        throw new Error(
+          `No facilitator registered for scheme: ${paymentRequirements.scheme} and network: ${paymentRequirements.network}`
+        );
+      }
+      const verifyResult = await schemeNetworkFacilitator.verify(
+        paymentPayload,
+        paymentRequirements
+      );
+      if (!verifyResult.isValid) {
+        const failureContext = {
+          ...context,
+          error: new Error(verifyResult.invalidReason || "Verification failed")
+        };
+        for (const hook of this.onVerifyFailureHooks) {
+          const result = await hook(failureContext);
+          if (result && "recovered" in result && result.recovered) {
+            const recoveredContext = {
+              ...context,
+              result: result.result
+            };
+            for (const hook2 of this.afterVerifyHooks) {
+              await hook2(recoveredContext);
+            }
+            return result.result;
+          }
+        }
+        return verifyResult;
+      }
+      const resultContext = {
+        ...context,
+        result: verifyResult
+      };
+      for (const hook of this.afterVerifyHooks) {
+        await hook(resultContext);
+      }
+      return verifyResult;
+    } catch (error) {
+      const failureContext = {
+        ...context,
+        error
+      };
+      for (const hook of this.onVerifyFailureHooks) {
+        const result = await hook(failureContext);
+        if (result && "recovered" in result && result.recovered) {
+          return result.result;
+        }
+      }
+      throw error;
+    }
+  }
+  /**
+   * Settles a payment based on the payload and requirements.
+   *
+   * @param paymentPayload - The payment payload to settle
+   * @param paymentRequirements - The payment requirements for settlement
+   * @returns Promise resolving to the settlement response
+   */
+  async settle(paymentPayload, paymentRequirements) {
+    const context = {
+      paymentPayload,
+      requirements: paymentRequirements
+    };
+    for (const hook of this.beforeSettleHooks) {
+      const result = await hook(context);
+      if (result && "abort" in result && result.abort) {
+        throw new Error(`Settlement aborted: ${result.reason}`);
+      }
+    }
+    try {
+      const schemeDataArray = this.registeredFacilitatorSchemes.get(paymentPayload.x402Version);
+      if (!schemeDataArray) {
+        throw new Error(
+          `No facilitator registered for x402 version: ${paymentPayload.x402Version}`
+        );
+      }
+      let schemeNetworkFacilitator;
+      for (const schemeData of schemeDataArray) {
+        if (schemeData.facilitator.scheme === paymentRequirements.scheme) {
+          if (schemeData.networks.has(paymentRequirements.network)) {
+            schemeNetworkFacilitator = schemeData.facilitator;
+            break;
+          }
+          const patternRegex = new RegExp("^" + schemeData.pattern.replace("*", ".*") + "$");
+          if (patternRegex.test(paymentRequirements.network)) {
+            schemeNetworkFacilitator = schemeData.facilitator;
+            break;
+          }
+        }
+      }
+      if (!schemeNetworkFacilitator) {
+        throw new Error(
+          `No facilitator registered for scheme: ${paymentRequirements.scheme} and network: ${paymentRequirements.network}`
+        );
+      }
+      const settleResult = await schemeNetworkFacilitator.settle(
+        paymentPayload,
+        paymentRequirements
+      );
+      const resultContext = {
+        ...context,
+        result: settleResult
+      };
+      for (const hook of this.afterSettleHooks) {
+        await hook(resultContext);
+      }
+      return settleResult;
+    } catch (error) {
+      const failureContext = {
+        ...context,
+        error
+      };
+      for (const hook of this.onSettleFailureHooks) {
+        const result = await hook(failureContext);
+        if (result && "recovered" in result && result.recovered) {
+          return result.result;
+        }
+      }
+      throw error;
+    }
+  }
+  /**
+   * Internal method to register a scheme facilitator.
+   *
+   * @param x402Version - The x402 protocol version
+   * @param networks - Array of concrete networks this facilitator supports
+   * @param facilitator - The scheme network facilitator to register
+   * @returns The x402Facilitator instance for chaining
+   */
+  _registerScheme(x402Version2, networks, facilitator) {
+    if (!this.registeredFacilitatorSchemes.has(x402Version2)) {
+      this.registeredFacilitatorSchemes.set(x402Version2, []);
+    }
+    const schemeDataArray = this.registeredFacilitatorSchemes.get(x402Version2);
+    schemeDataArray.push({
+      facilitator,
+      networks: new Set(networks),
+      pattern: this.derivePattern(networks)
+    });
+    return this;
+  }
+  /**
+   * Derives a wildcard pattern from an array of networks.
+   * If all networks share the same namespace, returns wildcard pattern.
+   * Otherwise returns the first network for exact matching.
+   *
+   * @param networks - Array of networks
+   * @returns Derived pattern for matching
+   */
+  derivePattern(networks) {
+    if (networks.length === 0) return "";
+    if (networks.length === 1) return networks[0];
+    const namespaces = networks.map((n) => n.split(":")[0]);
+    const uniqueNamespaces = new Set(namespaces);
+    if (uniqueNamespaces.size === 1) {
+      return `${namespaces[0]}:*`;
+    }
+    return networks[0];
+  }
+};
+export {
+  x402Facilitator
+};
+//# sourceMappingURL=index.mjs.map

package/dist/esm/facilitator/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/facilitator/x402Facilitator.ts"],"sourcesContent":["import { x402Version } from \"..\";\nimport { SettleResponse, VerifyResponse } from \"../types/facilitator\";\nimport { SchemeNetworkFacilitator } from \"../types/mechanisms\";\nimport { PaymentPayload, PaymentRequirements } from \"../types/payments\";\nimport { Network } from \"../types\";\nimport { type SchemeData } from \"../utils\";\n\n/**\n * Facilitator Hook Context Interfaces\n */\n\nexport interface FacilitatorVerifyContext {\n  paymentPayload: PaymentPayload;\n  requirements: PaymentRequirements;\n}\n\nexport interface FacilitatorVerifyResultContext extends FacilitatorVerifyContext {\n  result: VerifyResponse;\n}\n\nexport interface FacilitatorVerifyFailureContext extends FacilitatorVerifyContext {\n  error: Error;\n}\n\nexport interface FacilitatorSettleContext {\n  paymentPayload: PaymentPayload;\n  requirements: PaymentRequirements;\n}\n\nexport interface FacilitatorSettleResultContext extends FacilitatorSettleContext {\n  result: SettleResponse;\n}\n\nexport interface FacilitatorSettleFailureContext extends FacilitatorSettleContext {\n  error: Error;\n}\n\n/**\n * Facilitator Hook Type Definitions\n */\n\nexport type FacilitatorBeforeVerifyHook = (\n  context: FacilitatorVerifyContext,\n) => Promise<void | { abort: true; reason: string }>;\n\nexport type FacilitatorAfterVerifyHook = (context: FacilitatorVerifyResultContext) => Promise<void>;\n\nexport type FacilitatorOnVerifyFailureHook = (\n  context: FacilitatorVerifyFailureContext,\n) => Promise<void | { recovered: true; result: VerifyResponse }>;\n\nexport type FacilitatorBeforeSettleHook = (\n  context: FacilitatorSettleContext,\n) => Promise<void | { abort: true; reason: string }>;\n\nexport type FacilitatorAfterSettleHook = (context: FacilitatorSettleResultContext) => Promise<void>;\n\nexport type FacilitatorOnSettleFailureHook = (\n  context: FacilitatorSettleFailureContext,\n) => Promise<void | { recovered: true; result: SettleResponse }>;\n\n/**\n * Facilitator client for the x402 payment protocol.\n * Manages payment scheme registration, verification, and settlement.\n */\nexport class x402Facilitator {\n  private readonly registeredFacilitatorSchemes: Map<\n    number,\n    SchemeData<SchemeNetworkFacilitator>[] // Array to support multiple facilitators per version\n  > = new Map();\n  private readonly extensions: string[] = [];\n\n  private beforeVerifyHooks: FacilitatorBeforeVerifyHook[] = [];\n  private afterVerifyHooks: FacilitatorAfterVerifyHook[] = [];\n  private onVerifyFailureHooks: FacilitatorOnVerifyFailureHook[] = [];\n  private beforeSettleHooks: FacilitatorBeforeSettleHook[] = [];\n  private afterSettleHooks: FacilitatorAfterSettleHook[] = [];\n  private onSettleFailureHooks: FacilitatorOnSettleFailureHook[] = [];\n\n  /**\n   * Registers a scheme facilitator for the current x402 version.\n   * Networks are stored and used for getSupported() - no need to specify them later.\n   *\n   * @param networks - Single network or array of networks this facilitator supports\n   * @param facilitator - The scheme network facilitator to register\n   * @returns The x402Facilitator instance for chaining\n   */\n  register(networks: Network | Network[], facilitator: SchemeNetworkFacilitator): x402Facilitator {\n    const networksArray = Array.isArray(networks) ? networks : [networks];\n    return this._registerScheme(x402Version, networksArray, facilitator);\n  }\n\n  /**\n   * Registers a scheme facilitator for x402 version 1.\n   * Networks are stored and used for getSupported() - no need to specify them later.\n   *\n   * @param networks - Single network or array of networks this facilitator supports\n   * @param facilitator - The scheme network facilitator to register\n   * @returns The x402Facilitator instance for chaining\n   */\n  registerV1(\n    networks: Network | Network[],\n    facilitator: SchemeNetworkFacilitator,\n  ): x402Facilitator {\n    const networksArray = Array.isArray(networks) ? networks : [networks];\n    return this._registerScheme(1, networksArray, facilitator);\n  }\n\n  /**\n   * Registers a protocol extension.\n   *\n   * @param extension - The extension name to register (e.g., \"bazaar\", \"sign_in_with_x\")\n   * @returns The x402Facilitator instance for chaining\n   */\n  registerExtension(extension: string): x402Facilitator {\n    // Check if already registered\n    if (!this.extensions.includes(extension)) {\n      this.extensions.push(extension);\n    }\n    return this;\n  }\n\n  /**\n   * Gets the list of registered extensions.\n   *\n   * @returns Array of extension names\n   */\n  getExtensions(): string[] {\n    return [...this.extensions];\n  }\n\n  /**\n   * Register a hook to execute before facilitator payment verification.\n   * Can abort verification by returning { abort: true, reason: string }\n   *\n   * @param hook - The hook function to register\n   * @returns The x402Facilitator instance for chaining\n   */\n  onBeforeVerify(hook: FacilitatorBeforeVerifyHook): x402Facilitator {\n    this.beforeVerifyHooks.push(hook);\n    return this;\n  }\n\n  /**\n   * Register a hook to execute after successful facilitator payment verification (isValid: true).\n   * This hook is NOT called when verification fails (isValid: false) - use onVerifyFailure for that.\n   *\n   * @param hook - The hook function to register\n   * @returns The x402Facilitator instance for chaining\n   */\n  onAfterVerify(hook: FacilitatorAfterVerifyHook): x402Facilitator {\n    this.afterVerifyHooks.push(hook);\n    return this;\n  }\n\n  /**\n   * Register a hook to execute when facilitator payment verification fails.\n   * Called when: verification returns isValid: false, or an exception is thrown during verification.\n   * Can recover from failure by returning { recovered: true, result: VerifyResponse }\n   *\n   * @param hook - The hook function to register\n   * @returns The x402Facilitator instance for chaining\n   */\n  onVerifyFailure(hook: FacilitatorOnVerifyFailureHook): x402Facilitator {\n    this.onVerifyFailureHooks.push(hook);\n    return this;\n  }\n\n  /**\n   * Register a hook to execute before facilitator payment settlement.\n   * Can abort settlement by returning { abort: true, reason: string }\n   *\n   * @param hook - The hook function to register\n   * @returns The x402Facilitator instance for chaining\n   */\n  onBeforeSettle(hook: FacilitatorBeforeSettleHook): x402Facilitator {\n    this.beforeSettleHooks.push(hook);\n    return this;\n  }\n\n  /**\n   * Register a hook to execute after successful facilitator payment settlement.\n   *\n   * @param hook - The hook function to register\n   * @returns The x402Facilitator instance for chaining\n   */\n  onAfterSettle(hook: FacilitatorAfterSettleHook): x402Facilitator {\n    this.afterSettleHooks.push(hook);\n    return this;\n  }\n\n  /**\n   * Register a hook to execute when facilitator payment settlement fails.\n   * Can recover from failure by returning { recovered: true, result: SettleResponse }\n   *\n   * @param hook - The hook function to register\n   * @returns The x402Facilitator instance for chaining\n   */\n  onSettleFailure(hook: FacilitatorOnSettleFailureHook): x402Facilitator {\n    this.onSettleFailureHooks.push(hook);\n    return this;\n  }\n\n  /**\n   * Gets supported payment kinds, extensions, and signers.\n   * Uses networks registered during register() calls - no parameters needed.\n   * Returns flat array format for backward compatibility with V1 clients.\n   *\n   * @returns Supported response with kinds as array (with version in each element), extensions, and signers\n   */\n  getSupported(): {\n    kinds: Array<{\n      x402Version: number;\n      scheme: string;\n      network: string;\n      extra?: Record<string, unknown>;\n    }>;\n    extensions: string[];\n    signers: Record<string, string[]>;\n  } {\n    const kinds: Array<{\n      x402Version: number;\n      scheme: string;\n      network: string;\n      extra?: Record<string, unknown>;\n    }> = [];\n    const signersByFamily: Record<string, Set<string>> = {};\n\n    // Iterate over registered scheme data (array supports multiple facilitators per version)\n    for (const [version, schemeDataArray] of this.registeredFacilitatorSchemes) {\n      for (const schemeData of schemeDataArray) {\n        const { facilitator, networks } = schemeData;\n        const scheme = facilitator.scheme;\n\n        // Iterate over stored concrete networks\n        for (const network of networks) {\n          const extra = facilitator.getExtra(network);\n          kinds.push({\n            x402Version: version,\n            scheme,\n            network,\n            ...(extra && { extra }),\n          });\n\n          // Collect signers by CAIP family for this network\n          const family = facilitator.caipFamily;\n          if (!signersByFamily[family]) {\n            signersByFamily[family] = new Set();\n          }\n          facilitator.getSigners(network).forEach(signer => signersByFamily[family].add(signer));\n        }\n      }\n    }\n\n    // Convert signer sets to arrays\n    const signers: Record<string, string[]> = {};\n    for (const [family, signerSet] of Object.entries(signersByFamily)) {\n      signers[family] = Array.from(signerSet);\n    }\n\n    return {\n      kinds,\n      extensions: this.extensions,\n      signers,\n    };\n  }\n\n  /**\n   * Verifies a payment payload against requirements.\n   *\n   * @param paymentPayload - The payment payload to verify\n   * @param paymentRequirements - The payment requirements to verify against\n   * @returns Promise resolving to the verification response\n   */\n  async verify(\n    paymentPayload: PaymentPayload,\n    paymentRequirements: PaymentRequirements,\n  ): Promise<VerifyResponse> {\n    const context: FacilitatorVerifyContext = {\n      paymentPayload,\n      requirements: paymentRequirements,\n    };\n\n    // Execute beforeVerify hooks\n    for (const hook of this.beforeVerifyHooks) {\n      const result = await hook(context);\n      if (result && \"abort\" in result && result.abort) {\n        return {\n          isValid: false,\n          invalidReason: result.reason,\n        };\n      }\n    }\n\n    try {\n      const schemeDataArray = this.registeredFacilitatorSchemes.get(paymentPayload.x402Version);\n      if (!schemeDataArray) {\n        throw new Error(\n          `No facilitator registered for x402 version: ${paymentPayload.x402Version}`,\n        );\n      }\n\n      // Find matching facilitator from array\n      let schemeNetworkFacilitator: SchemeNetworkFacilitator | undefined;\n      for (const schemeData of schemeDataArray) {\n        if (schemeData.facilitator.scheme === paymentRequirements.scheme) {\n          // Check if network matches\n          if (schemeData.networks.has(paymentRequirements.network)) {\n            schemeNetworkFacilitator = schemeData.facilitator;\n            break;\n          }\n          // Try pattern matching\n          const patternRegex = new RegExp(\"^\" + schemeData.pattern.replace(\"*\", \".*\") + \"$\");\n          if (patternRegex.test(paymentRequirements.network)) {\n            schemeNetworkFacilitator = schemeData.facilitator;\n            break;\n          }\n        }\n      }\n\n      if (!schemeNetworkFacilitator) {\n        throw new Error(\n          `No facilitator registered for scheme: ${paymentRequirements.scheme} and network: ${paymentRequirements.network}`,\n        );\n      }\n\n      const verifyResult = await schemeNetworkFacilitator.verify(\n        paymentPayload,\n        paymentRequirements,\n      );\n\n      // Check if verification failed (isValid: false)\n      if (!verifyResult.isValid) {\n        const failureContext: FacilitatorVerifyFailureContext = {\n          ...context,\n          error: new Error(verifyResult.invalidReason || \"Verification failed\"),\n        };\n\n        // Execute onVerifyFailure hooks\n        for (const hook of this.onVerifyFailureHooks) {\n          const result = await hook(failureContext);\n          if (result && \"recovered\" in result && result.recovered) {\n            // If recovered, execute afterVerify hooks with recovered result\n            const recoveredContext: FacilitatorVerifyResultContext = {\n              ...context,\n              result: result.result,\n            };\n            for (const hook of this.afterVerifyHooks) {\n              await hook(recoveredContext);\n            }\n            return result.result;\n          }\n        }\n\n        return verifyResult;\n      }\n\n      // Execute afterVerify hooks only for successful verification\n      const resultContext: FacilitatorVerifyResultContext = {\n        ...context,\n        result: verifyResult,\n      };\n\n      for (const hook of this.afterVerifyHooks) {\n        await hook(resultContext);\n      }\n\n      return verifyResult;\n    } catch (error) {\n      const failureContext: FacilitatorVerifyFailureContext = {\n        ...context,\n        error: error as Error,\n      };\n\n      // Execute onVerifyFailure hooks\n      for (const hook of this.onVerifyFailureHooks) {\n        const result = await hook(failureContext);\n        if (result && \"recovered\" in result && result.recovered) {\n          return result.result;\n        }\n      }\n\n      throw error;\n    }\n  }\n\n  /**\n   * Settles a payment based on the payload and requirements.\n   *\n   * @param paymentPayload - The payment payload to settle\n   * @param paymentRequirements - The payment requirements for settlement\n   * @returns Promise resolving to the settlement response\n   */\n  async settle(\n    paymentPayload: PaymentPayload,\n    paymentRequirements: PaymentRequirements,\n  ): Promise<SettleResponse> {\n    const context: FacilitatorSettleContext = {\n      paymentPayload,\n      requirements: paymentRequirements,\n    };\n\n    // Execute beforeSettle hooks\n    for (const hook of this.beforeSettleHooks) {\n      const result = await hook(context);\n      if (result && \"abort\" in result && result.abort) {\n        throw new Error(`Settlement aborted: ${result.reason}`);\n      }\n    }\n\n    try {\n      const schemeDataArray = this.registeredFacilitatorSchemes.get(paymentPayload.x402Version);\n      if (!schemeDataArray) {\n        throw new Error(\n          `No facilitator registered for x402 version: ${paymentPayload.x402Version}`,\n        );\n      }\n\n      // Find matching facilitator from array\n      let schemeNetworkFacilitator: SchemeNetworkFacilitator | undefined;\n      for (const schemeData of schemeDataArray) {\n        if (schemeData.facilitator.scheme === paymentRequirements.scheme) {\n          // Check if network matches\n          if (schemeData.networks.has(paymentRequirements.network)) {\n            schemeNetworkFacilitator = schemeData.facilitator;\n            break;\n          }\n          // Try pattern matching\n          const patternRegex = new RegExp(\"^\" + schemeData.pattern.replace(\"*\", \".*\") + \"$\");\n          if (patternRegex.test(paymentRequirements.network)) {\n            schemeNetworkFacilitator = schemeData.facilitator;\n            break;\n          }\n        }\n      }\n\n      if (!schemeNetworkFacilitator) {\n        throw new Error(\n          `No facilitator registered for scheme: ${paymentRequirements.scheme} and network: ${paymentRequirements.network}`,\n        );\n      }\n\n      const settleResult = await schemeNetworkFacilitator.settle(\n        paymentPayload,\n        paymentRequirements,\n      );\n\n      // Execute afterSettle hooks\n      const resultContext: FacilitatorSettleResultContext = {\n        ...context,\n        result: settleResult,\n      };\n\n      for (const hook of this.afterSettleHooks) {\n        await hook(resultContext);\n      }\n\n      return settleResult;\n    } catch (error) {\n      const failureContext: FacilitatorSettleFailureContext = {\n        ...context,\n        error: error as Error,\n      };\n\n      // Execute onSettleFailure hooks\n      for (const hook of this.onSettleFailureHooks) {\n        const result = await hook(failureContext);\n        if (result && \"recovered\" in result && result.recovered) {\n          return result.result;\n        }\n      }\n\n      throw error;\n    }\n  }\n\n  /**\n   * Internal method to register a scheme facilitator.\n   *\n   * @param x402Version - The x402 protocol version\n   * @param networks - Array of concrete networks this facilitator supports\n   * @param facilitator - The scheme network facilitator to register\n   * @returns The x402Facilitator instance for chaining\n   */\n  private _registerScheme(\n    x402Version: number,\n    networks: Network[],\n    facilitator: SchemeNetworkFacilitator,\n  ): x402Facilitator {\n    if (!this.registeredFacilitatorSchemes.has(x402Version)) {\n      this.registeredFacilitatorSchemes.set(x402Version, []);\n    }\n    const schemeDataArray = this.registeredFacilitatorSchemes.get(x402Version)!;\n\n    // Add new scheme data (supports multiple facilitators with same scheme name)\n    schemeDataArray.push({\n      facilitator,\n      networks: new Set(networks),\n      pattern: this.derivePattern(networks),\n    });\n\n    return this;\n  }\n\n  /**\n   * Derives a wildcard pattern from an array of networks.\n   * If all networks share the same namespace, returns wildcard pattern.\n   * Otherwise returns the first network for exact matching.\n   *\n   * @param networks - Array of networks\n   * @returns Derived pattern for matching\n   */\n  private derivePattern(networks: Network[]): Network {\n    if (networks.length === 0) return \"\" as Network;\n    if (networks.length === 1) return networks[0];\n\n    // Extract namespaces (e.g., \"eip155\" from \"eip155:84532\")\n    const namespaces = networks.map(n => n.split(\":\")[0]);\n    const uniqueNamespaces = new Set(namespaces);\n\n    // If all same namespace, use wildcard\n    if (uniqueNamespaces.size === 1) {\n      return `${namespaces[0]}:*` as Network;\n    }\n\n    // Mixed namespaces - use first network for exact matching\n    return networks[0];\n  }\n}\n"],"mappings":"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","names":["hook","x402Version"]}