@payai/x402/dist/cjs/facilitator/index.d.ts

PayAI-distributed wrapper for @x402/core v2

import { P as PaymentPayload, a as PaymentRequirements, V as VerifyResponse, S as SettleResponse, N as Network, b as SchemeNetworkFacilitator, F as FacilitatorExtension } from '../mechanisms-CDlcy1I8.js';

/**
 * 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 object to register
     * @returns The x402Facilitator instance for chaining
     */
    registerExtension(extension: FacilitatorExtension): x402Facilitator;
    /**
     * Gets the list of registered extension keys.
     *
     * @returns Array of extension key strings
     */
    getExtensions(): string[];
    /**
     * Gets a registered extension by key.
     *
     * @param key - The extension key to look up
     * @returns The extension object, or undefined if not registered
     */
    getExtension<T extends FacilitatorExtension = FacilitatorExtension>(key: string): T | undefined;
    /**
     * 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>;
    /**
     * Builds a FacilitatorContext from the registered extensions map.
     * Passed to mechanism verify/settle so they can access extension capabilities.
     *
     * @returns A FacilitatorContext backed by this facilitator's registered extensions
     */
    private buildFacilitatorContext;
    /**
     * 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 };