@t402/core 2.3.1 → 2.5.0

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

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/client/t402Client.ts","../../../src/client/tokenSelector.ts"],"sourcesContent":["import { t402Version } 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 = (t402Version: 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 t402Version - The t402 protocol version\n * @param paymentRequirements - Array of payment requirements to filter/transform\n * @returns Filtered array of payment requirements\n */\nexport type PaymentPolicy = (t402Version: 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 t402 protocol version to use for this scheme\n   *\n   * @default 2\n   */\n  t402Version?: number;\n}\n\n/**\n * Configuration options for the fetch wrapper\n */\nexport interface t402ClientConfig {\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 t402 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 t402Client {\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 t402Client instance.\n   *\n   * @param paymentRequirementsSelector - Function to select payment requirements from available options\n   */\n  constructor(paymentRequirementsSelector?: SelectPaymentRequirements) {\n    this.paymentRequirementsSelector = paymentRequirementsSelector || ((_t402Version, accepts) => accepts[0]);\n  }\n\n  /**\n   * Creates a new t402Client instance from a configuration object.\n   *\n   * @param config - The client configuration including schemes, policies, and payment requirements selector\n   * @returns A configured t402Client instance\n   */\n  static fromConfig(config: t402ClientConfig): t402Client {\n    const client = new t402Client(config.paymentRequirementsSelector);\n    config.schemes.forEach(scheme => {\n      if (scheme.t402Version === 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 t402 version.\n   *\n   * @param network - The network to register the client for\n   * @param client - The scheme network client to register\n   * @returns The t402Client instance for chaining\n   */\n  register(network: Network, client: SchemeNetworkClient): t402Client {\n    return this._registerScheme(t402Version, network, client);\n  }\n\n  /**\n   * Registers a scheme client for t402 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 t402Client instance for chaining\n   */\n  registerV1(network: string, client: SchemeNetworkClient): t402Client {\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 t402Client 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): t402Client {\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 t402Client instance for chaining\n   */\n  onBeforePaymentCreation(hook: BeforePaymentCreationHook): t402Client {\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 t402Client instance for chaining\n   */\n  onAfterPaymentCreation(hook: AfterPaymentCreationHook): t402Client {\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 t402Client instance for chaining\n   */\n  onPaymentCreationFailure(hook: OnPaymentCreationFailureHook): t402Client {\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 t402Version, 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.t402Version);\n    if (!clientSchemesByNetwork) {\n      throw new Error(`No client registered for t402 version: ${paymentRequired.t402Version}`);\n    }\n\n    const requirements = this.selectPaymentRequirements(paymentRequired.t402Version, 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.t402Version, requirements);\n\n      let paymentPayload: PaymentPayload;\n      if (partialPayload.t402Version == 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 t402Version - The t402 protocol version\n   * @param paymentRequirements - Array of available payment requirements\n   * @returns The selected payment requirements\n   */\n  private selectPaymentRequirements(t402Version: number, paymentRequirements: PaymentRequirements[]): PaymentRequirements {\n    const clientSchemesByNetwork = this.registeredClientSchemes.get(t402Version);\n    if (!clientSchemesByNetwork) {\n      throw new Error(`No client registered for t402 version: ${t402Version}`);\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 t402 version: ${t402Version} which comply with the payment requirements. ${JSON.stringify({\n        t402Version,\n        paymentRequirements,\n        t402Versions: 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(t402Version, filteredRequirements);\n\n      if (filteredRequirements.length === 0) {\n        throw new Error(`All payment requirements were filtered out by policies for t402 version: ${t402Version}`);\n      }\n    }\n\n    // Step 3: Use selector to choose final requirement\n    return this.paymentRequirementsSelector(t402Version, filteredRequirements);\n  }\n\n  /**\n   * Internal method to register a scheme client.\n   *\n   * @param t402Version - The t402 protocol version\n   * @param network - The network to register the client for\n   * @param client - The scheme network client to register\n   * @returns The t402Client instance for chaining\n   */\n  private _registerScheme(t402Version: number, network: Network, client: SchemeNetworkClient): t402Client {\n    if (!this.registeredClientSchemes.has(t402Version)) {\n      this.registeredClientSchemes.set(t402Version, new Map());\n    }\n    const clientSchemesByNetwork = this.registeredClientSchemes.get(t402Version)!;\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","/**\n * Token Selector Utility for T402 Clients\n *\n * Helps clients select the best payment method from available payment requirements.\n * Prioritizes tokens based on:\n * 1. User token balances\n * 2. Token priority (USDT0 > USDC > legacy tokens)\n * 3. Network gas costs\n */\n\nimport type { PaymentRequirements } from \"../types\";\n\n/**\n * User token balance information\n */\nexport interface UserTokenBalance {\n  /** Token contract address */\n  asset: string;\n  /** Network in CAIP-2 format (e.g., \"eip155:42161\") */\n  network: string;\n  /** Token balance in smallest units */\n  amount: string;\n  /** Token symbol (optional, for display) */\n  symbol?: string;\n}\n\n/**\n * Token priority configuration\n * Lower number = higher priority\n */\nexport const DEFAULT_TOKEN_PRIORITY: Record<string, number> = {\n  USDT0: 1, // Highest priority - gasless, cross-chain native\n  USDC: 2, // Second - wide support, EIP-3009\n  EURC: 3, // Euro stablecoin\n  DAI: 4, // Decentralized stablecoin\n  USDT: 10, // Lower priority - requires approval transaction (legacy)\n};\n\n/**\n * Options for token selection\n */\nexport interface TokenSelectionOptions {\n  /** Custom token priorities (overrides defaults) */\n  tokenPriority?: Record<string, number>;\n  /** Preferred networks (will be prioritized) */\n  preferredNetworks?: string[];\n  /** Only consider tokens the user has sufficient balance for */\n  requireSufficientBalance?: boolean;\n}\n\n/**\n * Result of token selection\n */\nexport interface TokenSelectionResult {\n  /** The selected payment requirements */\n  selected: PaymentRequirements | null;\n  /** All valid payment options sorted by priority */\n  alternatives: PaymentRequirements[];\n  /** Reason if no payment method was selected */\n  reason?: string;\n}\n\n/**\n * Select the best payment method from available requirements\n *\n * @param requirements - Array of payment requirements from the server\n * @param userBalances - Array of user's token balances\n * @param options - Selection options\n * @returns The best payment requirement and alternatives\n *\n * @example\n * ```typescript\n * const result = selectBestPaymentMethod(\n *   paymentRequirements,\n *   [\n *     { asset: \"0x...\", network: \"eip155:42161\", amount: \"1000000000\" },\n *   ],\n *   { requireSufficientBalance: true }\n * );\n *\n * if (result.selected) {\n *   // Use result.selected for payment\n * }\n * ```\n */\nexport function selectBestPaymentMethod(\n  requirements: PaymentRequirements[],\n  userBalances: UserTokenBalance[],\n  options: TokenSelectionOptions = {},\n): TokenSelectionResult {\n  const { tokenPriority = DEFAULT_TOKEN_PRIORITY, preferredNetworks = [], requireSufficientBalance = true } = options;\n\n  if (requirements.length === 0) {\n    return {\n      selected: null,\n      alternatives: [],\n      reason: \"No payment requirements provided\",\n    };\n  }\n\n  // Create a map for quick balance lookup\n  const balanceMap = new Map<string, bigint>();\n  for (const balance of userBalances) {\n    const key = `${balance.network}:${balance.asset.toLowerCase()}`;\n    balanceMap.set(key, BigInt(balance.amount));\n  }\n\n  // Filter and score requirements\n  const scored = requirements\n    .map((req) => {\n      const key = `${req.network}:${req.asset.toLowerCase()}`;\n      const userBalance = balanceMap.get(key) ?? 0n;\n      const requiredAmount = BigInt(req.amount);\n      const hasSufficientBalance = userBalance >= requiredAmount;\n\n      // Get token symbol from extra or default\n      const symbol = (req.extra?.symbol as string) || (req.extra?.name as string) || \"UNKNOWN\";\n\n      // Calculate priority score\n      let priorityScore = tokenPriority[symbol.toUpperCase()] ?? 100;\n\n      // Boost preferred networks\n      if (preferredNetworks.includes(req.network)) {\n        priorityScore -= 0.5;\n      }\n\n      // Penalize if insufficient balance\n      if (!hasSufficientBalance) {\n        priorityScore += 1000;\n      }\n\n      return {\n        requirement: req,\n        priorityScore,\n        hasSufficientBalance,\n        userBalance,\n        symbol,\n      };\n    })\n    .sort((a, b) => a.priorityScore - b.priorityScore);\n\n  // Filter based on balance requirement\n  const validOptions = requireSufficientBalance ? scored.filter((s) => s.hasSufficientBalance) : scored;\n\n  if (validOptions.length === 0) {\n    return {\n      selected: null,\n      alternatives: scored.map((s) => s.requirement),\n      reason: requireSufficientBalance\n        ? \"No payment method with sufficient balance\"\n        : \"No valid payment methods available\",\n    };\n  }\n\n  return {\n    selected: validOptions[0].requirement,\n    alternatives: validOptions.slice(1).map((s) => s.requirement),\n  };\n}\n\n/**\n * Check if a payment requirement uses a gasless token (EIP-3009)\n *\n * @param requirement - The payment requirement to check\n * @returns True if the payment is gasless\n */\nexport function isGaslessPayment(requirement: PaymentRequirements): boolean {\n  const tokenType = requirement.extra?.tokenType;\n  return tokenType === \"eip3009\";\n}\n\n/**\n * Check if a payment requirement is for USDT0\n *\n * @param requirement - The payment requirement to check\n * @returns True if the payment is for USDT0\n */\nexport function isUsdt0Payment(requirement: PaymentRequirements): boolean {\n  const symbol = requirement.extra?.symbol;\n  return symbol === \"USDT0\";\n}\n\n/**\n * Get payment requirements for a specific token\n *\n * @param requirements - The payment requirements to filter\n * @param symbol - The token symbol to filter by\n * @returns Filtered payment requirements matching the token\n */\nexport function filterByToken(requirements: PaymentRequirements[], symbol: string): PaymentRequirements[] {\n  return requirements.filter((req) => {\n    const reqSymbol = (req.extra?.symbol as string) || \"\";\n    return reqSymbol.toUpperCase() === symbol.toUpperCase();\n  });\n}\n\n/**\n * Get payment requirements for a specific network\n *\n * @param requirements - The payment requirements to filter\n * @param network - The network to filter by\n * @returns Filtered payment requirements matching the network\n */\nexport function filterByNetwork(requirements: PaymentRequirements[], network: string): PaymentRequirements[] {\n  return requirements.filter((req) => req.network === network);\n}\n\n/**\n * Get all unique networks from payment requirements\n *\n * @param requirements - The payment requirements to extract networks from\n * @returns Array of unique network identifiers\n */\nexport function getAvailableNetworks(requirements: PaymentRequirements[]): string[] {\n  return [...new Set(requirements.map((req) => req.network))];\n}\n\n/**\n * Get all unique tokens from payment requirements\n *\n * @param requirements - The payment requirements to extract tokens from\n * @returns Array of unique token symbols\n */\nexport function getAvailableTokens(requirements: PaymentRequirements[]): string[] {\n  return [\n    ...new Set(\n      requirements.map((req) => (req.extra?.symbol as string) || (req.extra?.name as string) || \"UNKNOWN\"),\n    ),\n  ];\n}\n"],"mappings":"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","names":["t402Version"]}
+{"version":3,"sources":["../../../src/client/t402Client.ts","../../../src/client/tokenSelector.ts"],"sourcesContent":["import { t402Version } 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 = (t402Version: 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 t402Version - The t402 protocol version\n * @param paymentRequirements - Array of payment requirements to filter/transform\n * @returns Filtered array of payment requirements\n */\nexport type PaymentPolicy = (t402Version: 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 t402 protocol version to use for this scheme\n   *\n   * @default 2\n   */\n  t402Version?: number;\n}\n\n/**\n * Configuration options for the fetch wrapper\n */\nexport interface t402ClientConfig {\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 t402 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 t402Client {\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 t402Client instance.\n   *\n   * @param paymentRequirementsSelector - Function to select payment requirements from available options\n   */\n  constructor(paymentRequirementsSelector?: SelectPaymentRequirements) {\n    this.paymentRequirementsSelector = paymentRequirementsSelector || ((_t402Version, accepts) => accepts[0]);\n  }\n\n  /**\n   * Creates a new t402Client instance from a configuration object.\n   *\n   * @param config - The client configuration including schemes, policies, and payment requirements selector\n   * @returns A configured t402Client instance\n   */\n  static fromConfig(config: t402ClientConfig): t402Client {\n    const client = new t402Client(config.paymentRequirementsSelector);\n    config.schemes.forEach(scheme => {\n      if (scheme.t402Version === 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 t402 version.\n   *\n   * @param network - The network to register the client for\n   * @param client - The scheme network client to register\n   * @returns The t402Client instance for chaining\n   */\n  register(network: Network, client: SchemeNetworkClient): t402Client {\n    return this._registerScheme(t402Version, network, client);\n  }\n\n  /**\n   * Registers a scheme client for t402 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 t402Client instance for chaining\n   */\n  registerV1(network: string, client: SchemeNetworkClient): t402Client {\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 t402Client 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): t402Client {\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 t402Client instance for chaining\n   */\n  onBeforePaymentCreation(hook: BeforePaymentCreationHook): t402Client {\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 t402Client instance for chaining\n   */\n  onAfterPaymentCreation(hook: AfterPaymentCreationHook): t402Client {\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 t402Client instance for chaining\n   */\n  onPaymentCreationFailure(hook: OnPaymentCreationFailureHook): t402Client {\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 t402Version, 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.t402Version);\n    if (!clientSchemesByNetwork) {\n      throw new Error(`No client registered for t402 version: ${paymentRequired.t402Version}`);\n    }\n\n    const requirements = this.selectPaymentRequirements(paymentRequired.t402Version, 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.t402Version, requirements);\n\n      let paymentPayload: PaymentPayload;\n      if (partialPayload.t402Version == 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 t402Version - The t402 protocol version\n   * @param paymentRequirements - Array of available payment requirements\n   * @returns The selected payment requirements\n   */\n  private selectPaymentRequirements(t402Version: number, paymentRequirements: PaymentRequirements[]): PaymentRequirements {\n    const clientSchemesByNetwork = this.registeredClientSchemes.get(t402Version);\n    if (!clientSchemesByNetwork) {\n      throw new Error(`No client registered for t402 version: ${t402Version}`);\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 t402 version: ${t402Version} which comply with the payment requirements. ${JSON.stringify({\n        t402Version,\n        paymentRequirements,\n        t402Versions: 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(t402Version, filteredRequirements);\n\n      if (filteredRequirements.length === 0) {\n        throw new Error(`All payment requirements were filtered out by policies for t402 version: ${t402Version}`);\n      }\n    }\n\n    // Step 3: Use selector to choose final requirement\n    return this.paymentRequirementsSelector(t402Version, filteredRequirements);\n  }\n\n  /**\n   * Internal method to register a scheme client.\n   *\n   * @param t402Version - The t402 protocol version\n   * @param network - The network to register the client for\n   * @param client - The scheme network client to register\n   * @returns The t402Client instance for chaining\n   */\n  private _registerScheme(t402Version: number, network: Network, client: SchemeNetworkClient): t402Client {\n    if (!this.registeredClientSchemes.has(t402Version)) {\n      this.registeredClientSchemes.set(t402Version, new Map());\n    }\n    const clientSchemesByNetwork = this.registeredClientSchemes.get(t402Version)!;\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","/**\n * Token Selector Utility for T402 Clients\n *\n * Helps clients select the best payment method from available payment requirements.\n * Prioritizes tokens based on:\n * 1. User token balances\n * 2. Token priority (USDT0 > USDC > legacy tokens)\n * 3. Network gas costs\n */\n\nimport type { PaymentRequirements } from \"../types\";\n\n/**\n * User token balance information\n */\nexport interface UserTokenBalance {\n  /** Token contract address */\n  asset: string;\n  /** Network in CAIP-2 format (e.g., \"eip155:42161\") */\n  network: string;\n  /** Token balance in smallest units */\n  amount: string;\n  /** Token symbol (optional, for display) */\n  symbol?: string;\n}\n\n/**\n * Token priority configuration\n * Lower number = higher priority\n */\nexport const DEFAULT_TOKEN_PRIORITY: Record<string, number> = {\n  USDT0: 1, // Highest priority - gasless, cross-chain native\n  USDC: 2, // Second - wide support, EIP-3009\n  EURC: 3, // Euro stablecoin\n  DAI: 4, // Decentralized stablecoin\n  USDT: 10, // Lower priority - requires approval transaction (legacy)\n};\n\n/**\n * Options for token selection\n */\nexport interface TokenSelectionOptions {\n  /** Custom token priorities (overrides defaults) */\n  tokenPriority?: Record<string, number>;\n  /** Preferred networks (will be prioritized) */\n  preferredNetworks?: string[];\n  /** Only consider tokens the user has sufficient balance for */\n  requireSufficientBalance?: boolean;\n}\n\n/**\n * Result of token selection\n */\nexport interface TokenSelectionResult {\n  /** The selected payment requirements */\n  selected: PaymentRequirements | null;\n  /** All valid payment options sorted by priority */\n  alternatives: PaymentRequirements[];\n  /** Reason if no payment method was selected */\n  reason?: string;\n}\n\n/**\n * Select the best payment method from available requirements\n *\n * @param requirements - Array of payment requirements from the server\n * @param userBalances - Array of user's token balances\n * @param options - Selection options\n * @returns The best payment requirement and alternatives\n *\n * @example\n * ```typescript\n * const result = selectBestPaymentMethod(\n *   paymentRequirements,\n *   [\n *     { asset: \"0x...\", network: \"eip155:42161\", amount: \"1000000000\" },\n *   ],\n *   { requireSufficientBalance: true }\n * );\n *\n * if (result.selected) {\n *   // Use result.selected for payment\n * }\n * ```\n */\nexport function selectBestPaymentMethod(\n  requirements: PaymentRequirements[],\n  userBalances: UserTokenBalance[],\n  options: TokenSelectionOptions = {},\n): TokenSelectionResult {\n  const { tokenPriority = DEFAULT_TOKEN_PRIORITY, preferredNetworks = [], requireSufficientBalance = true } = options;\n\n  if (requirements.length === 0) {\n    return {\n      selected: null,\n      alternatives: [],\n      reason: \"No payment requirements provided\",\n    };\n  }\n\n  // Create a map for quick balance lookup\n  const balanceMap = new Map<string, bigint>();\n  for (const balance of userBalances) {\n    const key = `${balance.network}:${balance.asset.toLowerCase()}`;\n    balanceMap.set(key, BigInt(balance.amount));\n  }\n\n  // Filter and score requirements\n  const scored = requirements\n    .map((req) => {\n      const key = `${req.network}:${req.asset.toLowerCase()}`;\n      const userBalance = balanceMap.get(key) ?? 0n;\n      const requiredAmount = BigInt(req.amount);\n      const hasSufficientBalance = userBalance >= requiredAmount;\n\n      // Get token symbol from extra or default\n      const symbol = (req.extra?.symbol as string) || (req.extra?.name as string) || \"UNKNOWN\";\n\n      // Calculate priority score\n      let priorityScore = tokenPriority[symbol.toUpperCase()] ?? 100;\n\n      // Boost preferred networks\n      if (preferredNetworks.includes(req.network)) {\n        priorityScore -= 0.5;\n      }\n\n      // Penalize if insufficient balance\n      if (!hasSufficientBalance) {\n        priorityScore += 1000;\n      }\n\n      return {\n        requirement: req,\n        priorityScore,\n        hasSufficientBalance,\n        userBalance,\n        symbol,\n      };\n    })\n    .sort((a, b) => a.priorityScore - b.priorityScore);\n\n  // Filter based on balance requirement\n  const validOptions = requireSufficientBalance ? scored.filter((s) => s.hasSufficientBalance) : scored;\n\n  if (validOptions.length === 0) {\n    return {\n      selected: null,\n      alternatives: scored.map((s) => s.requirement),\n      reason: requireSufficientBalance\n        ? \"No payment method with sufficient balance\"\n        : \"No valid payment methods available\",\n    };\n  }\n\n  return {\n    selected: validOptions[0].requirement,\n    alternatives: validOptions.slice(1).map((s) => s.requirement),\n  };\n}\n\n/**\n * Check if a payment requirement uses a gasless token (EIP-3009)\n *\n * @param requirement - The payment requirement to check\n * @returns True if the payment is gasless\n */\nexport function isGaslessPayment(requirement: PaymentRequirements): boolean {\n  const tokenType = requirement.extra?.tokenType;\n  return tokenType === \"eip3009\";\n}\n\n/**\n * Check if a payment requirement is for USDT0\n *\n * @param requirement - The payment requirement to check\n * @returns True if the payment is for USDT0\n */\nexport function isUsdt0Payment(requirement: PaymentRequirements): boolean {\n  const symbol = requirement.extra?.symbol;\n  return symbol === \"USDT0\";\n}\n\n/**\n * Get payment requirements for a specific token\n *\n * @param requirements - The payment requirements to filter\n * @param symbol - The token symbol to filter by\n * @returns Filtered payment requirements matching the token\n */\nexport function filterByToken(requirements: PaymentRequirements[], symbol: string): PaymentRequirements[] {\n  return requirements.filter((req) => {\n    const reqSymbol = (req.extra?.symbol as string) || \"\";\n    return reqSymbol.toUpperCase() === symbol.toUpperCase();\n  });\n}\n\n/**\n * Get payment requirements for a specific network\n *\n * @param requirements - The payment requirements to filter\n * @param network - The network to filter by\n * @returns Filtered payment requirements matching the network\n */\nexport function filterByNetwork(requirements: PaymentRequirements[], network: string): PaymentRequirements[] {\n  return requirements.filter((req) => req.network === network);\n}\n\n/**\n * Get all unique networks from payment requirements\n *\n * @param requirements - The payment requirements to extract networks from\n * @returns Array of unique network identifiers\n */\nexport function getAvailableNetworks(requirements: PaymentRequirements[]): string[] {\n  return [...new Set(requirements.map((req) => req.network))];\n}\n\n/**\n * Get all unique tokens from payment requirements\n *\n * @param requirements - The payment requirements to extract tokens from\n * @returns Array of unique token symbols\n */\nexport function getAvailableTokens(requirements: PaymentRequirements[]): string[] {\n  return [\n    ...new Set(\n      requirements.map((req) => (req.extra?.symbol as string) || (req.extra?.name as string) || \"UNKNOWN\"),\n    ),\n  ];\n}\n"],"mappings":"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","names":["t402Version"]}

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

@@ -1,4 +1,5 @@
-import { a as PaymentPayload, P as PaymentRequirements, V as VerifyResponse, S as SettleResponse, N as Network, b as SchemeNetworkFacilitator } from '../mechanisms-B-vz5yOj.mjs';
+import { a as PaymentPayload, P as PaymentRequirements, S as SettleResponse, V as VerifyResponse, N as Network, b as SchemeNetworkFacilitator } from '../mechanisms-dYCiYgko.mjs';
+import 'zod';
 
 /**
  * Facilitator Hook Context Interfaces

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

@@ -1,6 +1,7 @@
-import { a as PaymentPayload, c as PaymentRequired, S as SettleResponse, P as PaymentRequirements } from '../mechanisms-B-vz5yOj.mjs';
-export { C as CompiledRoute, D as DynamicPayTo, i as DynamicPrice, F as FacilitatorClient, o as FacilitatorConfig, a as HTTPAdapter, H as HTTPFacilitatorClient, d as HTTPProcessResult, b as HTTPRequestContext, c as HTTPResponseInstructions, f as PaymentOption, P as PaywallConfig, e as PaywallProvider, m as ProcessSettleFailureResponse, k as ProcessSettleResultResponse, l as ProcessSettleSuccessResponse, g as RouteConfig, R as RouteConfigurationError, n as RouteValidationError, h as RoutesConfig, U as UnpaidResponseBody, j as UnpaidResponseResult, t as t402HTTPResourceServer } from '../t402HTTPResourceServer-BbQ6HVBC.mjs';
-export { f as t402HTTPClient } from '../t402HTTPClient-DbZqiMSO.mjs';
+import { c as PaymentRequired, S as SettleResponse, a as PaymentPayload, P as PaymentRequirements } from '../mechanisms-dYCiYgko.mjs';
+export { C as CompiledRoute, D as DynamicPayTo, a as DynamicPrice, F as FacilitatorClient, b as FacilitatorConfig, H as HTTPAdapter, c as HTTPFacilitatorClient, d as HTTPProcessResult, e as HTTPRequestContext, f as HTTPResponseInstructions, P as PaymentOption, g as PaywallConfig, h as PaywallProvider, i as ProcessSettleFailureResponse, j as ProcessSettleResultResponse, k as ProcessSettleSuccessResponse, R as RouteConfig, l as RouteConfigurationError, m as RouteValidationError, n as RoutesConfig, U as UnpaidResponseBody, o as UnpaidResponseResult, t as t402HTTPResourceServer } from '../t402HTTPResourceServer-CstWZOsH.mjs';
+export { f as t402HTTPClient } from '../t402HTTPClient-DbIXpGXL.mjs';
+import 'zod';
 
 type QueryParamMethods = "GET" | "HEAD" | "DELETE";
 type BodyMethods = "POST" | "PUT" | "PATCH";
@@ -13,9 +14,11 @@ type BodyMethods = "POST" | "PUT" | "PATCH";
 declare function encodePaymentSignatureHeader(paymentPayload: PaymentPayload): string;
 /**
  * Decodes a base64 payment signature header into a payment payload.
+ * Validates the payload structure using Zod schema.
  *
  * @param paymentSignatureHeader - The base64 encoded payment signature header
- * @returns The decoded payment payload
+ * @returns The decoded and validated payment payload
+ * @throws Error if the header is invalid or fails schema validation
  */
 declare function decodePaymentSignatureHeader(paymentSignatureHeader: string): PaymentPayload;
 /**
@@ -27,9 +30,11 @@ declare function decodePaymentSignatureHeader(paymentSignatureHeader: string): P
 declare function encodePaymentRequiredHeader(paymentRequired: PaymentRequired): string;
 /**
  * Decodes a base64 payment required header into a payment required object.
+ * Validates the structure using Zod schema.
  *
  * @param paymentRequiredHeader - The base64 encoded payment required header
- * @returns The decoded payment required object
+ * @returns The decoded and validated payment required object
+ * @throws Error if the header is invalid or fails schema validation
  */
 declare function decodePaymentRequiredHeader(paymentRequiredHeader: string): PaymentRequired;
 /**
@@ -43,9 +48,11 @@ declare function encodePaymentResponseHeader(paymentResponse: SettleResponse & {
 }): string;
 /**
  * Decodes a base64 payment response header into a settle response.
+ * Validates the structure using Zod schema.
  *
  * @param paymentResponseHeader - The base64 encoded payment response header
- * @returns The decoded settle response
+ * @returns The decoded and validated settle response
+ * @throws Error if the header is invalid or fails schema validation
  */
 declare function decodePaymentResponseHeader(paymentResponseHeader: string): SettleResponse;
 

package/dist/esm/http/index.mjs

@@ -9,9 +9,10 @@ import {
   encodePaymentSignatureHeader,
   t402HTTPClient,
   t402HTTPResourceServer
-} from "../chunk-773TNE2Y.mjs";
+} from "../chunk-7RHSIMQL.mjs";
 import "../chunk-3VTYR43U.mjs";
-import "../chunk-3IUBYRYG.mjs";
+import "../chunk-STKQDKUH.mjs";
+import "../chunk-LJ4M5Z5U.mjs";
 import "../chunk-4W2Y3RJM.mjs";
 export {
   HTTPFacilitatorClient,