@agentokratia/x402-escrow 2.0.0

package/dist/session-wrapper-Cf7U8ObX.d.cts

@@ -0,0 +1,372 @@
+import { Address, WalletClient } from 'viem';
+import { x402Client } from '@x402/core/client';
+
+/**
+ * x402 Protocol Types for @agentokratia/x402-escrow
+ *
+ * Subset of types needed for the escrow scheme.
+ */
+/** Current x402 protocol version */
+declare const X402_VERSION = 2;
+/** Network identifier in CAIP-2 format (e.g., "eip155:8453" for Base) */
+type Network = `${string}:${string}`;
+/**
+ * PaymentRequirements - defines a single payment option
+ * Base interface that each scheme extends
+ */
+interface PaymentRequirements {
+    scheme: string;
+    network: Network;
+    amount: string;
+    asset: string;
+    payTo: string;
+    maxTimeoutSeconds: number;
+    extra: Record<string, unknown>;
+}
+/**
+ * x402 Facilitator settle response (JSON body)
+ */
+interface SettleResponse {
+    success: boolean;
+    errorReason?: string;
+    payer?: string;
+    transaction: string;
+    network: string;
+    session?: {
+        id: string;
+        balance: string;
+        token?: string;
+        expiresAt?: number;
+    };
+}
+/** Header name constants (x402 v2) */
+declare const X402_HEADERS: {
+    /** Server → Client: Payment options (402 response) - base64 JSON */
+    readonly PAYMENT_REQUIRED: "PAYMENT-REQUIRED";
+    /** Client → Server: Payment payload - base64 JSON */
+    readonly PAYMENT_SIGNATURE: "PAYMENT-SIGNATURE";
+    /** Server → Client: Settlement result - base64 JSON (includes session data) */
+    readonly PAYMENT_RESPONSE: "PAYMENT-RESPONSE";
+};
+/** PAYMENT-RESPONSE header data (all schemes) */
+interface PaymentResponseData {
+    success: boolean;
+    transaction: string;
+    network: string;
+    payer?: string;
+    receiver?: string;
+    errorReason?: string;
+    session?: {
+        id: string;
+        balance: string;
+        token?: string;
+        expiresAt?: number;
+    };
+    requirements?: PaymentRequirements;
+}
+/**
+ * Parse PAYMENT-RESPONSE header.
+ */
+declare function parsePaymentResponseHeader(header: string): PaymentResponseData | null;
+
+/**
+ * Session Storage for x402 Escrow Scheme
+ *
+ * Provides session persistence with two implementations:
+ * - InMemoryStorage: For server-side or ephemeral usage
+ * - LocalStorage: For browser persistence across page loads
+ */
+
+interface StoredSession {
+    sessionId: string;
+    sessionToken: string;
+    network: string;
+    payer: Address;
+    receiver: Address;
+    balance: string;
+    authorizationExpiry: number;
+    createdAt: number;
+}
+interface SessionStorage {
+    get(network: string, receiver: Address): StoredSession | null;
+    findBest(network: string, receiver: Address, minAmount: bigint): StoredSession | null;
+    set(session: StoredSession): void;
+    update(sessionId: string, balance: string): void;
+    list(): StoredSession[];
+    remove(sessionId: string): void;
+}
+declare abstract class BaseStorage implements SessionStorage {
+    protected sessions: Map<string, StoredSession>;
+    get(network: string, receiver: Address): StoredSession | null;
+    findBest(network: string, receiver: Address, minAmount: bigint): StoredSession | null;
+    set(session: StoredSession): void;
+    update(sessionId: string, balance: string): void;
+    list(): StoredSession[];
+    remove(sessionId: string): void;
+    /** Override in subclasses for persistence */
+    protected onUpdate(): void;
+}
+declare class InMemoryStorage extends BaseStorage {
+}
+declare class BrowserLocalStorage extends BaseStorage {
+    private key;
+    constructor(key?: string);
+    protected onUpdate(): void;
+    private load;
+    private save;
+}
+declare function createStorage(type: 'memory' | 'localStorage', storageKey?: string): SessionStorage;
+
+/**
+ * Session Manager for x402 Escrow Scheme
+ *
+ * Handles session lifecycle: lookup, storage, and validation.
+ * Uses the SessionStorage interface for persistence.
+ */
+
+interface SessionManagerOptions {
+    /** Storage type: 'memory' (default) or 'localStorage' */
+    storage?: 'memory' | 'localStorage';
+    /** localStorage key (default: 'x402-sessions') */
+    storageKey?: string;
+}
+/**
+ * Manages session lifecycle for the escrow scheme.
+ *
+ * Responsibilities:
+ * - Store sessions from escrow settlement responses
+ * - Find best session for a receiver/amount
+ * - Update session balances after debits
+ * - Validate session expiry
+ */
+declare class SessionManager {
+    private readonly storage;
+    private readonly network;
+    constructor(network: Network, options?: SessionManagerOptions);
+    /**
+     * Store a session from escrow settlement response.
+     */
+    store(session: Omit<StoredSession, 'createdAt'>): void;
+    /**
+     * Get session for a specific receiver.
+     */
+    getForReceiver(receiver: Address): StoredSession | null;
+    /**
+     * Find best session for receiver with minimum balance.
+     */
+    findBest(receiver: Address, minAmount: bigint): StoredSession | null;
+    /**
+     * Check if valid session exists for receiver.
+     */
+    hasValid(receiver: Address, minAmount?: string): boolean;
+    /**
+     * Update session balance after debit.
+     */
+    updateBalance(sessionId: string, newBalance: string): void;
+    /**
+     * Get all stored sessions.
+     */
+    getAll(): StoredSession[];
+    /**
+     * Remove a specific session.
+     */
+    remove(sessionId: string): void;
+    /**
+     * Clear all sessions.
+     */
+    clear(): void;
+}
+
+/**
+ * Escrow Client Scheme (Unified)
+ *
+ * Thin orchestrator that delegates to:
+ * - SessionManager: Session lifecycle management
+ * - Signer (eip712.ts): EIP-712 signing for session creation
+ *
+ * Handles both session CREATION and session USAGE in a single scheme.
+ * - First call: Creates session with wallet signature (EIP-712)
+ * - Subsequent calls: Uses stored session token (no signature needed)
+ */
+
+interface PaymentPayload {
+    x402Version: number;
+    resource?: {
+        url: string;
+        description?: string;
+        mimeType?: string;
+    };
+    accepted?: PaymentRequirements;
+    payload: Record<string, unknown>;
+    extensions?: Record<string, unknown>;
+}
+interface SchemeNetworkClient {
+    readonly scheme: string;
+    createPaymentPayload(x402Version: number, paymentRequirements: PaymentRequirements): Promise<Pick<PaymentPayload, 'x402Version' | 'payload'>>;
+}
+interface EscrowSchemeOptions {
+    /** Session duration in seconds (default: 1 hour) */
+    sessionDuration?: number;
+    /** Refund window after session expires (default: 24 hours) */
+    refundWindow?: number;
+    /** Storage type: 'memory' (default) or 'localStorage' */
+    storage?: 'memory' | 'localStorage';
+    /** localStorage key (default: 'x402-sessions') */
+    storageKey?: string;
+    /**
+     * Custom deposit amount in atomic units (e.g., "10000000" for $10 USDC).
+     * Must be between minDeposit and maxDeposit from the 402 response.
+     * If not specified, defaults to maxDeposit for maximum flexibility.
+     */
+    depositAmount?: string;
+}
+/**
+ * Escrow payment scheme for x402 (Unified).
+ *
+ * Orchestrates:
+ * - SessionManager for session lookup and storage
+ * - EIP-712 signer for session creation signatures
+ *
+ * Auto-preference: If a valid session exists for the receiver,
+ * it will be used automatically (no wallet interaction required).
+ */
+declare class EscrowScheme implements SchemeNetworkClient {
+    readonly scheme = "escrow";
+    /** Session manager - use directly for session operations */
+    readonly sessions: SessionManager;
+    private readonly wallet;
+    private readonly chainId;
+    readonly network: Network;
+    private readonly sessionDuration;
+    private readonly refundWindow;
+    private readonly customDepositAmount?;
+    constructor(walletClient: WalletClient, options?: EscrowSchemeOptions);
+    get address(): Address;
+    /**
+     * Creates payment payload for escrow scheme.
+     * Auto-detects whether to create new session or use existing one.
+     */
+    createPaymentPayload(x402Version: number, paymentRequirements: PaymentRequirements): Promise<Pick<PaymentPayload, 'x402Version' | 'payload'>>;
+    /**
+     * Session USAGE payload - uses existing session (no signature).
+     */
+    private createUsagePayload;
+    /**
+     * Session CREATION payload - requires wallet signature.
+     */
+    private createCreationPayload;
+    private generateSalt;
+}
+
+/**
+ * Session Extraction Wrappers
+ *
+ * Thin wrappers that extract sessions from x402 responses and store them.
+ *
+ * @example Simple (recommended)
+ * ```typescript
+ * const { fetch: escrowFetch, scheme, x402 } = createEscrowFetch(walletClient);
+ * const response = await escrowFetch('https://api.example.com/premium');
+ *
+ * // Add hooks (user has control)
+ * x402.onAfterPaymentCreation(async (ctx) => {
+ *   console.log('Payment created:', ctx.paymentPayload);
+ * });
+ * ```
+ *
+ * @example With custom fetch
+ * ```typescript
+ * const { fetch: escrowFetch } = createEscrowFetch(walletClient, {
+ *   fetch: ky,  // Use ky, undici, node-fetch, etc.
+ * });
+ * ```
+ *
+ * @example Fully composable (manual setup)
+ * ```typescript
+ * const escrowScheme = new EscrowScheme(walletClient);
+ * const x402 = new x402Client().register('eip155:84532', escrowScheme);
+ * const paidFetch = wrapFetchWithPayment(fetch, x402);
+ * const escrowFetch = withSessionExtraction(paidFetch, escrowScheme);
+ * ```
+ */
+
+type FetchLike = typeof globalThis.fetch;
+/** Options for createEscrowFetch */
+interface CreateEscrowFetchOptions extends EscrowSchemeOptions {
+    /** Custom fetch implementation (default: globalThis.fetch) */
+    fetch?: FetchLike;
+}
+/** Result from createEscrowFetch */
+interface EscrowFetchResult {
+    /** Fetch function with automatic payment + session handling */
+    fetch: FetchLike;
+    /** Access to underlying scheme for session management */
+    scheme: EscrowScheme;
+    /** Access to x402Client for adding hooks (onBeforePaymentCreation, etc.) */
+    x402: x402Client;
+}
+/**
+ * Creates a fetch function with automatic escrow payment and session handling.
+ * This is the simplest way to integrate x402 escrow payments.
+ *
+ * @example Simple usage
+ * ```typescript
+ * const { fetch: escrowFetch, scheme, x402 } = createEscrowFetch(walletClient);
+ * const response = await escrowFetch('https://api.example.com/premium');
+ *
+ * // Access sessions
+ * scheme.sessions.getAll();
+ * scheme.sessions.hasValid(receiverAddress, '10000');
+ * ```
+ *
+ * @example With custom fetch and hooks
+ * ```typescript
+ * const { fetch: escrowFetch, x402 } = createEscrowFetch(walletClient, {
+ *   fetch: customFetch, // Use ky, undici, node-fetch, etc.
+ * });
+ *
+ * // Add hooks for user control
+ * x402.onBeforePaymentCreation(async (ctx) => {
+ *   console.log('About to pay:', ctx.paymentRequirements);
+ * });
+ * ```
+ */
+declare function createEscrowFetch(walletClient: WalletClient, options?: CreateEscrowFetchOptions): EscrowFetchResult;
+/**
+ * Wraps a paid fetch to automatically extract and store sessions.
+ * Use with wrapFetchWithPayment from @x402/fetch.
+ *
+ * @example
+ * ```typescript
+ * const escrowScheme = new EscrowScheme(walletClient);
+ * const x402 = new x402Client().register('eip155:84532', escrowScheme);
+ * const paidFetch = wrapFetchWithPayment(fetch, x402);
+ * const escrowFetch = withSessionExtraction(paidFetch, escrowScheme);
+ *
+ * const response = await escrowFetch('https://api.example.com/premium');
+ * // Session automatically stored if present in response
+ * ```
+ */
+declare function withSessionExtraction(paidFetch: FetchLike, escrowScheme: EscrowScheme): FetchLike;
+interface AxiosResponseLike {
+    headers: Record<string, string | undefined>;
+    [key: string]: unknown;
+}
+/**
+ * Returns an Axios response interceptor that extracts and stores sessions.
+ * Use with wrapAxiosWithPayment from @x402/axios.
+ *
+ * @example
+ * ```typescript
+ * const escrowScheme = new EscrowScheme(walletClient);
+ * const x402 = new x402Client().register('eip155:84532', escrowScheme);
+ * const paidAxios = wrapAxiosWithPayment(axios.create(), x402);
+ * paidAxios.interceptors.response.use(withAxiosSessionExtraction(escrowScheme));
+ *
+ * const response = await paidAxios.get('https://api.example.com/premium');
+ * // Session automatically stored if present in response
+ * ```
+ */
+declare function withAxiosSessionExtraction(escrowScheme: EscrowScheme): <T extends AxiosResponseLike>(response: T) => T;
+
+export { BrowserLocalStorage as B, type CreateEscrowFetchOptions as C, type EscrowFetchResult as E, InMemoryStorage as I, type PaymentResponseData as P, type StoredSession as S, X402_HEADERS as X, EscrowScheme as a, type EscrowSchemeOptions as b, createEscrowFetch as c, withAxiosSessionExtraction as d, type SettleResponse as e, SessionManager as f, type SessionManagerOptions as g, type SessionStorage as h, createStorage as i, X402_VERSION as j, parsePaymentResponseHeader as p, withSessionExtraction as w };