@t402/core 2.0.0

package/dist/esm/t402HTTPClient-C285YGCp.d.mts

@@ -0,0 +1,243 @@
+import { c as PaymentRequired, P as PaymentRequirements, a as PaymentPayload, N as Network, d as SchemeNetworkClient, S as SettleResponse } from './mechanisms-CmrqNl1M.mjs';
+
+/**
+ * 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 = (t402Version: 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 t402Version - The t402 protocol version
+ * @param paymentRequirements - Array of payment requirements to filter/transform
+ * @returns Filtered array of payment requirements
+ */
+type PaymentPolicy = (t402Version: 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 t402 protocol version to use for this scheme
+     *
+     * @default 2
+     */
+    t402Version?: number;
+}
+/**
+ * Configuration options for the fetch wrapper
+ */
+interface t402ClientConfig {
+    /**
+     * 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 t402 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 t402Client {
+    private readonly paymentRequirementsSelector;
+    private readonly registeredClientSchemes;
+    private readonly policies;
+    private beforePaymentCreationHooks;
+    private afterPaymentCreationHooks;
+    private onPaymentCreationFailureHooks;
+    /**
+     * Creates a new t402Client instance.
+     *
+     * @param paymentRequirementsSelector - Function to select payment requirements from available options
+     */
+    constructor(paymentRequirementsSelector?: SelectPaymentRequirements);
+    /**
+     * Creates a new t402Client instance from a configuration object.
+     *
+     * @param config - The client configuration including schemes, policies, and payment requirements selector
+     * @returns A configured t402Client instance
+     */
+    static fromConfig(config: t402ClientConfig): t402Client;
+    /**
+     * Registers a scheme client for the current t402 version.
+     *
+     * @param network - The network to register the client for
+     * @param client - The scheme network client to register
+     * @returns The t402Client instance for chaining
+     */
+    register(network: Network, client: SchemeNetworkClient): t402Client;
+    /**
+     * Registers a scheme client for t402 version 1.
+     *
+     * @param network - The v1 network identifier (e.g., 'base-sepolia', 'solana-devnet')
+     * @param client - The scheme network client to register
+     * @returns The t402Client instance for chaining
+     */
+    registerV1(network: string, client: SchemeNetworkClient): t402Client;
+    /**
+     * 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 t402Client 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): t402Client;
+    /**
+     * 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 t402Client instance for chaining
+     */
+    onBeforePaymentCreation(hook: BeforePaymentCreationHook): t402Client;
+    /**
+     * Register a hook to execute after successful payment payload creation.
+     *
+     * @param hook - The hook function to register
+     * @returns The t402Client instance for chaining
+     */
+    onAfterPaymentCreation(hook: AfterPaymentCreationHook): t402Client;
+    /**
+     * 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 t402Client instance for chaining
+     */
+    onPaymentCreationFailure(hook: OnPaymentCreationFailureHook): t402Client;
+    /**
+     * Creates a payment payload based on a PaymentRequired response.
+     *
+     * Automatically extracts t402Version, 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 t402Version - The t402 protocol version
+     * @param paymentRequirements - Array of available payment requirements
+     * @returns The selected payment requirements
+     */
+    private selectPaymentRequirements;
+    /**
+     * Internal method to register a scheme client.
+     *
+     * @param t402Version - The t402 protocol version
+     * @param network - The network to register the client for
+     * @param client - The scheme network client to register
+     * @returns The t402Client instance for chaining
+     */
+    private _registerScheme;
+}
+
+/**
+ * HTTP-specific client for handling t402 payment protocol over HTTP.
+ *
+ * Wraps a t402Client to provide HTTP-specific encoding/decoding functionality
+ * for payment headers and responses while maintaining the builder pattern.
+ */
+declare class t402HTTPClient {
+    private readonly client;
+    /**
+     * Creates a new t402HTTPClient instance.
+     *
+     * @param client - The underlying t402Client for payment logic
+     */
+    constructor(client: t402Client);
+    /**
+     * 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 t402Client.
+     *
+     * @param paymentRequired - The payment required response from the server
+     * @returns Promise resolving to the payment payload
+     */
+    createPaymentPayload(paymentRequired: PaymentRequired): Promise<PaymentPayload>;
+}
+
+export { type AfterPaymentCreationHook as A, type BeforePaymentCreationHook as B, type OnPaymentCreationFailureHook as O, type PaymentCreationContext as P, type SelectPaymentRequirements as S, type PaymentCreatedContext as a, type PaymentCreationFailureContext as b, type PaymentPolicy as c, type SchemeRegistration as d, t402Client as e, t402HTTPClient as f, type t402ClientConfig as t };