@payai/x402
Version:
PayAI-distributed wrapper for @x402/core v2
273 lines (269 loc) • 10.8 kB
TypeScript
import { c as PaymentRequired, a as PaymentRequirements, P as PaymentPayload, N as Network, e as SchemeNetworkClient, S as SettleResponse } from '../mechanisms-Q3XXOYVv.js';
/**
* Client Hook Context Interfaces
*/
interface PaymentCreationContext {
paymentRequired: PaymentRequired;
selectedRequirements: PaymentRequirements;
}
interface PaymentCreatedContext extends PaymentCreationContext {
paymentPayload: PaymentPayload;
}
interface PaymentCreationFailureContext extends PaymentCreationContext {
error: Error;
}
/**
* Client Hook Type Definitions
*/
type BeforePaymentCreationHook = (context: PaymentCreationContext) => Promise<void | {
abort: true;
reason: string;
}>;
type AfterPaymentCreationHook = (context: PaymentCreatedContext) => Promise<void>;
type OnPaymentCreationFailureHook = (context: PaymentCreationFailureContext) => Promise<void | {
recovered: true;
payload: PaymentPayload;
}>;
type SelectPaymentRequirements = (x402Version: number, paymentRequirements: PaymentRequirements[]) => PaymentRequirements;
/**
* A policy function that filters or transforms payment requirements.
* Policies are applied in order before the selector chooses the final option.
*
* @param x402Version - The x402 protocol version
* @param paymentRequirements - Array of payment requirements to filter/transform
* @returns Filtered array of payment requirements
*/
type PaymentPolicy = (x402Version: number, paymentRequirements: PaymentRequirements[]) => PaymentRequirements[];
/**
* Configuration for registering a payment scheme with a specific network
*/
interface SchemeRegistration {
/**
* The network identifier (e.g., 'eip155:8453', 'solana:mainnet')
*/
network: Network;
/**
* The scheme client implementation for this network
*/
client: SchemeNetworkClient;
/**
* The x402 protocol version to use for this scheme
*
* @default 2
*/
x402Version?: number;
}
/**
* Configuration options for the fetch wrapper
*/
interface x402ClientConfig {
/**
* Array of scheme registrations defining which payment methods are supported
*/
schemes: SchemeRegistration[];
/**
* Policies to apply to the client
*/
policies?: PaymentPolicy[];
/**
* Custom payment requirements selector function
* If not provided, uses the default selector (first available option)
*/
paymentRequirementsSelector?: SelectPaymentRequirements;
}
/**
* Core client for managing x402 payment schemes and creating payment payloads.
*
* Handles registration of payment schemes, policy-based filtering of payment requirements,
* and creation of payment payloads based on server requirements.
*/
declare class x402Client {
private readonly paymentRequirementsSelector;
private readonly registeredClientSchemes;
private readonly policies;
private beforePaymentCreationHooks;
private afterPaymentCreationHooks;
private onPaymentCreationFailureHooks;
/**
* Creates a new x402Client instance.
*
* @param paymentRequirementsSelector - Function to select payment requirements from available options
*/
constructor(paymentRequirementsSelector?: SelectPaymentRequirements);
/**
* Creates a new x402Client instance from a configuration object.
*
* @param config - The client configuration including schemes, policies, and payment requirements selector
* @returns A configured x402Client instance
*/
static fromConfig(config: x402ClientConfig): x402Client;
/**
* Registers a scheme client for the current x402 version.
*
* @param network - The network to register the client for
* @param client - The scheme network client to register
* @returns The x402Client instance for chaining
*/
register(network: Network, client: SchemeNetworkClient): x402Client;
/**
* Registers a scheme client for x402 version 1.
*
* @param network - The v1 network identifier (e.g., 'base-sepolia', 'solana-devnet')
* @param client - The scheme network client to register
* @returns The x402Client instance for chaining
*/
registerV1(network: string, client: SchemeNetworkClient): x402Client;
/**
* Registers a policy to filter or transform payment requirements.
*
* Policies are applied in order after filtering by registered schemes
* and before the selector chooses the final payment requirement.
*
* @param policy - Function to filter/transform payment requirements
* @returns The x402Client instance for chaining
*
* @example
* ```typescript
* // Prefer cheaper options
* client.registerPolicy((version, reqs) =>
* reqs.filter(r => BigInt(r.value) < BigInt('1000000'))
* );
*
* // Prefer specific networks
* client.registerPolicy((version, reqs) =>
* reqs.filter(r => r.network.startsWith('eip155:'))
* );
* ```
*/
registerPolicy(policy: PaymentPolicy): x402Client;
/**
* Register a hook to execute before payment payload creation.
* Can abort creation by returning { abort: true, reason: string }
*
* @param hook - The hook function to register
* @returns The x402Client instance for chaining
*/
onBeforePaymentCreation(hook: BeforePaymentCreationHook): x402Client;
/**
* Register a hook to execute after successful payment payload creation.
*
* @param hook - The hook function to register
* @returns The x402Client instance for chaining
*/
onAfterPaymentCreation(hook: AfterPaymentCreationHook): x402Client;
/**
* Register a hook to execute when payment payload creation fails.
* Can recover from failure by returning { recovered: true, payload: PaymentPayload }
*
* @param hook - The hook function to register
* @returns The x402Client instance for chaining
*/
onPaymentCreationFailure(hook: OnPaymentCreationFailureHook): x402Client;
/**
* Creates a payment payload based on a PaymentRequired response.
*
* Automatically extracts x402Version, resource, and extensions from the PaymentRequired
* response and constructs a complete PaymentPayload with the accepted requirements.
*
* @param paymentRequired - The PaymentRequired response from the server
* @returns Promise resolving to the complete payment payload
*/
createPaymentPayload(paymentRequired: PaymentRequired): Promise<PaymentPayload>;
/**
* Selects appropriate payment requirements based on registered clients and policies.
*
* Selection process:
* 1. Filter by registered schemes (network + scheme support)
* 2. Apply all registered policies in order
* 3. Use selector to choose final requirement
*
* @param x402Version - The x402 protocol version
* @param paymentRequirements - Array of available payment requirements
* @returns The selected payment requirements
*/
private selectPaymentRequirements;
/**
* Internal method to register a scheme client.
*
* @param x402Version - The x402 protocol version
* @param network - The network to register the client for
* @param client - The scheme network client to register
* @returns The x402Client instance for chaining
*/
private _registerScheme;
}
/**
* Context provided to onPaymentRequired hooks.
*/
interface PaymentRequiredContext {
paymentRequired: PaymentRequired;
}
/**
* Hook called when a 402 response is received, before payment processing.
* Return headers to try before payment, or void to proceed directly to payment.
*/
type PaymentRequiredHook = (context: PaymentRequiredContext) => Promise<{
headers: Record<string, string>;
} | void>;
/**
* HTTP-specific client for handling x402 payment protocol over HTTP.
*
* Wraps a x402Client to provide HTTP-specific encoding/decoding functionality
* for payment headers and responses while maintaining the builder pattern.
*/
declare class x402HTTPClient {
private readonly client;
private paymentRequiredHooks;
/**
* Creates a new x402HTTPClient instance.
*
* @param client - The underlying x402Client for payment logic
*/
constructor(client: x402Client);
/**
* Register a hook to handle 402 responses before payment.
* Hooks run in order; first to return headers wins.
*
* @param hook - The hook function to register
* @returns This instance for chaining
*/
onPaymentRequired(hook: PaymentRequiredHook): this;
/**
* Run hooks and return headers if any hook provides them.
*
* @param paymentRequired - The payment required response from the server
* @returns Headers to use for retry, or null to proceed to payment
*/
handlePaymentRequired(paymentRequired: PaymentRequired): Promise<Record<string, string> | null>;
/**
* Encodes a payment payload into appropriate HTTP headers based on version.
*
* @param paymentPayload - The payment payload to encode
* @returns HTTP headers containing the encoded payment signature
*/
encodePaymentSignatureHeader(paymentPayload: PaymentPayload): Record<string, string>;
/**
* Extracts payment required information from HTTP response.
*
* @param getHeader - Function to retrieve header value by name (case-insensitive)
* @param body - Optional response body for v1 compatibility
* @returns The payment required object
*/
getPaymentRequiredResponse(getHeader: (name: string) => string | null | undefined, body?: unknown): PaymentRequired;
/**
* Extracts payment settlement response from HTTP headers.
*
* @param getHeader - Function to retrieve header value by name (case-insensitive)
* @returns The settlement response object
*/
getPaymentSettleResponse(getHeader: (name: string) => string | null | undefined): SettleResponse;
/**
* Creates a payment payload for the given payment requirements.
* Delegates to the underlying x402Client.
*
* @param paymentRequired - The payment required response from the server
* @returns Promise resolving to the payment payload
*/
createPaymentPayload(paymentRequired: PaymentRequired): Promise<PaymentPayload>;
}
export { type AfterPaymentCreationHook, type BeforePaymentCreationHook, type OnPaymentCreationFailureHook, type PaymentCreatedContext, type PaymentCreationContext, type PaymentCreationFailureContext, type PaymentPolicy, type PaymentRequiredContext, type PaymentRequiredHook, type SchemeRegistration, type SelectPaymentRequirements, x402Client, type x402ClientConfig, x402HTTPClient };