uvd-x402-sdk 2.5.0 → 2.10.0

package/dist/backend/index.d.ts

@@ -0,0 +1,1036 @@
+import { l as X402Version, m as X402Header } from '../index-D-dO_FoP.js';
+
+/**
+ * uvd-x402-sdk - Backend Utilities
+ *
+ * Server-side utilities for building x402 payment APIs.
+ * These utilities help backend developers:
+ * - Build verify/settle requests for the facilitator
+ * - Parse X-PAYMENT headers from incoming requests
+ * - Configure CORS for x402 payment flows
+ * - Create atomic payment handlers
+ * - Discover and register resources via Bazaar Discovery API
+ * - Manage escrow payments with refund and dispute resolution
+ *
+ * @example Basic payment flow
+ * ```ts
+ * import {
+ *   parsePaymentHeader,
+ *   FacilitatorClient,
+ *   X402_CORS_HEADERS,
+ * } from 'uvd-x402-sdk/backend';
+ *
+ * // Parse payment from request header
+ * const payment = parsePaymentHeader(req.headers['x-payment']);
+ *
+ * // Verify with facilitator
+ * const client = new FacilitatorClient();
+ * const verifyResult = await client.verify(payment, paymentRequirements);
+ *
+ * // If valid, provide service then settle
+ * const settleResult = await client.settle(payment, paymentRequirements);
+ * ```
+ *
+ * @example Escrow payment with refund support
+ * ```ts
+ * import { EscrowClient } from 'uvd-x402-sdk/backend';
+ *
+ * const escrow = new EscrowClient();
+ *
+ * // Hold payment in escrow
+ * const escrowPayment = await escrow.createEscrow({
+ *   paymentHeader: req.headers['x-payment'],
+ *   requirements: paymentRequirements,
+ *   escrowDuration: 86400, // 24 hours
+ * });
+ *
+ * // After service delivered, release to recipient
+ * await escrow.release(escrowPayment.id);
+ *
+ * // Or if service failed, request refund
+ * await escrow.requestRefund({
+ *   escrowId: escrowPayment.id,
+ *   reason: 'Service not delivered',
+ * });
+ * ```
+ *
+ * @example Resource discovery
+ * ```ts
+ * import { BazaarClient } from 'uvd-x402-sdk/backend';
+ *
+ * const bazaar = new BazaarClient();
+ * const resources = await bazaar.discover({
+ *   category: 'ai',
+ *   network: 'base',
+ *   maxPrice: '0.10',
+ * });
+ * ```
+ */
+
+/**
+ * Payment requirements sent to the facilitator
+ */
+interface PaymentRequirements {
+    /** Payment scheme (always "exact") */
+    scheme: 'exact';
+    /** Network name (v1) or CAIP-2 identifier (v2) */
+    network: string;
+    /** Maximum amount required in atomic units (e.g., "1000000" for 1 USDC) */
+    maxAmountRequired: string;
+    /** Resource URL being paid for */
+    resource: string;
+    /** Description of what's being paid for */
+    description: string;
+    /** MIME type of the resource */
+    mimeType: string;
+    /** Recipient address for payment */
+    payTo: string;
+    /** Maximum timeout in seconds */
+    maxTimeoutSeconds: number;
+    /** Token contract address */
+    asset: string;
+    /** Optional output schema for the resource */
+    outputSchema?: unknown;
+    /** Optional extra data */
+    extra?: unknown;
+}
+/**
+ * Verify request body for the facilitator /verify endpoint
+ */
+interface VerifyRequest {
+    x402Version: X402Version;
+    paymentPayload: X402Header;
+    paymentRequirements: PaymentRequirements;
+}
+/**
+ * Settle request body for the facilitator /settle endpoint
+ */
+interface SettleRequest {
+    x402Version: X402Version;
+    paymentPayload: X402Header;
+    paymentRequirements: PaymentRequirements;
+}
+/**
+ * Verify response from the facilitator
+ */
+interface VerifyResponse {
+    isValid: boolean;
+    invalidReason?: string;
+    payer?: string;
+    network?: string;
+}
+/**
+ * Settle response from the facilitator
+ */
+interface SettleResponse {
+    success: boolean;
+    transactionHash?: string;
+    network?: string;
+    error?: string;
+}
+/**
+ * Options for building payment requirements
+ */
+interface PaymentRequirementsOptions {
+    /** Amount in human-readable format (e.g., "1.00") */
+    amount: string;
+    /** Recipient address */
+    recipient: string;
+    /** Resource URL being protected */
+    resource: string;
+    /** Chain name (e.g., "base") */
+    chainName?: string;
+    /** Description of the resource */
+    description?: string;
+    /** MIME type of the resource */
+    mimeType?: string;
+    /** Timeout in seconds (default: 300) */
+    timeoutSeconds?: number;
+    /** x402 version to use */
+    x402Version?: X402Version;
+}
+/**
+ * Parse X-PAYMENT or PAYMENT-SIGNATURE header value
+ *
+ * @param headerValue - Base64-encoded header value (or undefined/null)
+ * @returns Parsed x402 header object, or null if invalid
+ *
+ * @example
+ * ```ts
+ * // Express.js
+ * const payment = parsePaymentHeader(req.headers['x-payment']);
+ * if (!payment) {
+ *   return res.status(400).json({ error: 'Invalid payment header' });
+ * }
+ * ```
+ */
+declare function parsePaymentHeader(headerValue: string | undefined | null): X402Header | null;
+/**
+ * Extract payment header from request headers object
+ *
+ * Checks both X-PAYMENT and PAYMENT-SIGNATURE headers.
+ *
+ * @param headers - Request headers object (case-insensitive)
+ * @returns Parsed x402 header object, or null if not found/invalid
+ *
+ * @example
+ * ```ts
+ * const payment = extractPaymentFromHeaders(req.headers);
+ * ```
+ */
+declare function extractPaymentFromHeaders(headers: Record<string, string | string[] | undefined>): X402Header | null;
+/**
+ * Build payment requirements for the facilitator
+ *
+ * @param options - Payment requirements options
+ * @returns PaymentRequirements object ready for verify/settle
+ *
+ * @example
+ * ```ts
+ * const requirements = buildPaymentRequirements({
+ *   amount: '1.00',
+ *   recipient: '0x1234...',
+ *   resource: 'https://api.example.com/premium-data',
+ *   chainName: 'base',
+ * });
+ * ```
+ */
+declare function buildPaymentRequirements(options: PaymentRequirementsOptions): PaymentRequirements;
+/**
+ * Build a verify request for the facilitator /verify endpoint
+ *
+ * @param paymentHeader - Parsed x402 payment header
+ * @param requirements - Payment requirements
+ * @returns VerifyRequest body ready for fetch/axios
+ *
+ * @example
+ * ```ts
+ * const payment = parsePaymentHeader(req.headers['x-payment']);
+ * const verifyBody = buildVerifyRequest(payment, requirements);
+ *
+ * const response = await fetch('https://facilitator.uvd.xyz/verify', {
+ *   method: 'POST',
+ *   headers: { 'Content-Type': 'application/json' },
+ *   body: JSON.stringify(verifyBody),
+ * });
+ * ```
+ */
+declare function buildVerifyRequest(paymentHeader: X402Header, requirements: PaymentRequirements): VerifyRequest;
+/**
+ * Build a settle request for the facilitator /settle endpoint
+ *
+ * @param paymentHeader - Parsed x402 payment header
+ * @param requirements - Payment requirements
+ * @returns SettleRequest body ready for fetch/axios
+ */
+declare function buildSettleRequest(paymentHeader: X402Header, requirements: PaymentRequirements): SettleRequest;
+/**
+ * Recommended CORS headers for x402 payment APIs
+ *
+ * These headers allow browsers to send payment headers in cross-origin requests.
+ */
+declare const X402_CORS_HEADERS: {
+    readonly 'Access-Control-Allow-Headers': "Content-Type, X-PAYMENT, PAYMENT-SIGNATURE, Authorization";
+    readonly 'Access-Control-Expose-Headers': "X-PAYMENT-RESPONSE, PAYMENT-RESPONSE, PAYMENT-REQUIRED";
+    readonly 'Access-Control-Allow-Methods': "GET, POST, OPTIONS";
+};
+/**
+ * All x402 custom header names that should be allowed in CORS
+ */
+declare const X402_HEADER_NAMES: readonly ["X-PAYMENT", "PAYMENT-SIGNATURE", "X-PAYMENT-RESPONSE", "PAYMENT-RESPONSE", "PAYMENT-REQUIRED"];
+/**
+ * Get CORS headers with custom origin
+ *
+ * @param origin - Allowed origin (use '*' for any, or specific domain)
+ * @returns Complete CORS headers object
+ *
+ * @example
+ * ```ts
+ * // Express.js middleware
+ * app.use((req, res, next) => {
+ *   const corsHeaders = getCorsHeaders('https://myapp.com');
+ *   Object.entries(corsHeaders).forEach(([key, value]) => {
+ *     res.setHeader(key, value);
+ *   });
+ *   if (req.method === 'OPTIONS') {
+ *     return res.status(204).end();
+ *   }
+ *   next();
+ * });
+ * ```
+ */
+declare function getCorsHeaders(origin?: string): Record<string, string>;
+/**
+ * Options for the FacilitatorClient
+ */
+interface FacilitatorClientOptions {
+    /** Base URL of the facilitator (default: https://facilitator.ultravioletadao.xyz) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+}
+/**
+ * Client for interacting with the x402 facilitator API
+ *
+ * @example
+ * ```ts
+ * const client = new FacilitatorClient();
+ *
+ * // Verify a payment
+ * const verifyResult = await client.verify(paymentHeader, requirements);
+ * if (!verifyResult.isValid) {
+ *   return res.status(402).json({ error: verifyResult.invalidReason });
+ * }
+ *
+ * // Provide the service, then settle
+ * const settleResult = await client.settle(paymentHeader, requirements);
+ * if (!settleResult.success) {
+ *   // Handle settlement failure (maybe refund or retry)
+ * }
+ * ```
+ */
+declare class FacilitatorClient {
+    private readonly baseUrl;
+    private readonly timeout;
+    constructor(options?: FacilitatorClientOptions);
+    /**
+     * Verify a payment with the facilitator
+     *
+     * Call this before providing the paid resource to validate the payment.
+     *
+     * @param paymentHeader - Parsed x402 payment header
+     * @param requirements - Payment requirements
+     * @returns Verification result
+     */
+    verify(paymentHeader: X402Header, requirements: PaymentRequirements): Promise<VerifyResponse>;
+    /**
+     * Settle a payment with the facilitator
+     *
+     * Call this after providing the paid resource to execute the on-chain transfer.
+     *
+     * @param paymentHeader - Parsed x402 payment header
+     * @param requirements - Payment requirements
+     * @returns Settlement result with transaction hash
+     */
+    settle(paymentHeader: X402Header, requirements: PaymentRequirements): Promise<SettleResponse>;
+    /**
+     * Verify and settle atomically
+     *
+     * Convenience method that verifies first, then settles if valid.
+     * Use this for simple payment flows where you don't need custom logic between verify and settle.
+     *
+     * @param paymentHeader - Parsed x402 payment header
+     * @param requirements - Payment requirements
+     * @returns Combined result with verify and settle status
+     */
+    verifyAndSettle(paymentHeader: X402Header, requirements: PaymentRequirements): Promise<{
+        verified: boolean;
+        settled: boolean;
+        transactionHash?: string;
+        error?: string;
+    }>;
+    /**
+     * Check if the facilitator is healthy
+     *
+     * @returns True if the facilitator is responding
+     */
+    healthCheck(): Promise<boolean>;
+}
+/**
+ * Create a 402 Payment Required response
+ *
+ * @param requirements - Payment requirements
+ * @param options - Additional response options
+ * @returns Object with status code, headers, and body for the 402 response
+ *
+ * @example
+ * ```ts
+ * // Express.js
+ * app.get('/premium-data', (req, res) => {
+ *   const payment = extractPaymentFromHeaders(req.headers);
+ *
+ *   if (!payment) {
+ *     const { status, headers, body } = create402Response({
+ *       amount: '1.00',
+ *       recipient: '0x...',
+ *       resource: 'https://api.example.com/premium-data',
+ *     });
+ *     return res.status(status).set(headers).json(body);
+ *   }
+ *
+ *   // Verify and serve...
+ * });
+ * ```
+ */
+declare function create402Response(requirements: PaymentRequirementsOptions, options?: {
+    accepts?: Array<{
+        network: string;
+        asset: string;
+        amount: string;
+    }>;
+}): {
+    status: 402;
+    headers: Record<string, string>;
+    body: Record<string, unknown>;
+};
+/**
+ * Create an Express-compatible middleware for x402 payments
+ *
+ * @param getRequirements - Function to get payment requirements for a request
+ * @param options - Middleware options
+ * @returns Express middleware function
+ *
+ * @example
+ * ```ts
+ * const paymentMiddleware = createPaymentMiddleware(
+ *   (req) => ({
+ *     amount: '1.00',
+ *     recipient: process.env.PAYMENT_RECIPIENT,
+ *     resource: `${req.protocol}://${req.get('host')}${req.originalUrl}`,
+ *   }),
+ *   { facilitatorUrl: 'https://facilitator.uvd.xyz' }
+ * );
+ *
+ * app.get('/premium/*', paymentMiddleware, (req, res) => {
+ *   res.json({ premium: 'data' });
+ * });
+ * ```
+ */
+declare function createPaymentMiddleware(getRequirements: (req: {
+    headers: Record<string, string | string[] | undefined>;
+}) => PaymentRequirementsOptions, options?: FacilitatorClientOptions): (req: {
+    headers: Record<string, string | string[] | undefined>;
+}, res: {
+    status: (code: number) => {
+        json: (body: unknown) => void;
+        set: (headers: Record<string, string>) => {
+            json: (body: unknown) => void;
+        };
+    };
+}, next: () => void) => Promise<void>;
+/**
+ * Resource category for discovery
+ */
+type BazaarCategory = 'api' | 'data' | 'ai' | 'media' | 'compute' | 'storage' | 'other';
+/**
+ * Network/chain filter for discovery
+ */
+type BazaarNetwork = 'base' | 'ethereum' | 'polygon' | 'arbitrum' | 'optimism' | 'avalanche' | 'celo' | 'hyperevm' | 'unichain' | 'monad' | 'solana' | 'fogo' | 'stellar' | 'near';
+/**
+ * Token/asset filter for discovery
+ */
+type BazaarToken = 'USDC' | 'EURC' | 'AUSD' | 'PYUSD' | 'USDT';
+/**
+ * Resource registered in the Bazaar
+ */
+interface BazaarResource {
+    /** Unique resource ID */
+    id: string;
+    /** Resource URL */
+    url: string;
+    /** Human-readable name */
+    name: string;
+    /** Description of the resource */
+    description: string;
+    /** Category of the resource */
+    category: BazaarCategory;
+    /** Supported networks for payment */
+    networks: BazaarNetwork[];
+    /** Supported tokens for payment */
+    tokens: BazaarToken[];
+    /** Price per request in atomic units */
+    pricePerRequest: string;
+    /** Price currency (e.g., "USDC") */
+    priceCurrency: BazaarToken;
+    /** Recipient address for payments */
+    payTo: string;
+    /** MIME type of the resource */
+    mimeType: string;
+    /** Optional output schema */
+    outputSchema?: unknown;
+    /** Resource owner/provider */
+    provider?: string;
+    /** Resource tags for search */
+    tags?: string[];
+    /** Whether the resource is active */
+    isActive: boolean;
+    /** ISO timestamp of creation */
+    createdAt: string;
+    /** ISO timestamp of last update */
+    updatedAt: string;
+}
+/**
+ * Options for registering a resource
+ */
+interface BazaarRegisterOptions {
+    /** Resource URL (must be unique) */
+    url: string;
+    /** Human-readable name */
+    name: string;
+    /** Description of the resource */
+    description: string;
+    /** Category of the resource */
+    category: BazaarCategory;
+    /** Supported networks for payment */
+    networks: BazaarNetwork[];
+    /** Supported tokens for payment */
+    tokens?: BazaarToken[];
+    /** Price per request (e.g., "0.01") */
+    price: string;
+    /** Price currency (default: USDC) */
+    priceCurrency?: BazaarToken;
+    /** Recipient address for payments */
+    payTo: string;
+    /** MIME type of the resource (default: application/json) */
+    mimeType?: string;
+    /** Optional output schema */
+    outputSchema?: unknown;
+    /** Resource tags for search */
+    tags?: string[];
+}
+/**
+ * Options for discovering resources
+ */
+interface BazaarDiscoverOptions {
+    /** Filter by category */
+    category?: BazaarCategory;
+    /** Filter by network */
+    network?: BazaarNetwork;
+    /** Filter by token */
+    token?: BazaarToken;
+    /** Filter by provider address */
+    provider?: string;
+    /** Filter by tags (match any) */
+    tags?: string[];
+    /** Search query (name, description) */
+    query?: string;
+    /** Maximum price filter (e.g., "0.10") */
+    maxPrice?: string;
+    /** Page number (1-indexed) */
+    page?: number;
+    /** Results per page (default: 20, max: 100) */
+    limit?: number;
+    /** Sort order */
+    sortBy?: 'price' | 'createdAt' | 'name';
+    /** Sort direction */
+    sortOrder?: 'asc' | 'desc';
+}
+/**
+ * Paginated discovery response
+ */
+interface BazaarDiscoverResponse {
+    /** List of resources matching the query */
+    resources: BazaarResource[];
+    /** Total number of matching resources */
+    total: number;
+    /** Current page number */
+    page: number;
+    /** Results per page */
+    limit: number;
+    /** Total number of pages */
+    totalPages: number;
+    /** Whether there are more pages */
+    hasMore: boolean;
+}
+/**
+ * Options for the BazaarClient
+ */
+interface BazaarClientOptions {
+    /** Base URL of the Bazaar API (default: https://bazaar.ultravioletadao.xyz) */
+    baseUrl?: string;
+    /** API key for authenticated operations (required for register/update/delete) */
+    apiKey?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+}
+/**
+ * Client for interacting with the x402 Bazaar Discovery API
+ *
+ * The Bazaar is a discovery service for x402-enabled resources.
+ * Providers can register their APIs and consumers can discover them.
+ *
+ * @example
+ * ```ts
+ * // Discover resources (no auth required)
+ * const bazaar = new BazaarClient();
+ * const results = await bazaar.discover({
+ *   category: 'ai',
+ *   network: 'base',
+ *   maxPrice: '0.10',
+ * });
+ *
+ * // Register a resource (requires API key)
+ * const authBazaar = new BazaarClient({ apiKey: 'your-api-key' });
+ * const resource = await authBazaar.register({
+ *   url: 'https://api.example.com/v1/chat',
+ *   name: 'AI Chat API',
+ *   description: 'Pay-per-message AI chat',
+ *   category: 'ai',
+ *   networks: ['base', 'ethereum'],
+ *   price: '0.01',
+ *   payTo: '0x...',
+ * });
+ * ```
+ */
+declare class BazaarClient {
+    private readonly baseUrl;
+    private readonly apiKey?;
+    private readonly timeout;
+    constructor(options?: BazaarClientOptions);
+    /**
+     * Discover x402-enabled resources
+     *
+     * @param options - Discovery filters
+     * @returns Paginated list of matching resources
+     *
+     * @example
+     * ```ts
+     * // Find AI APIs on Base with USDC under $0.10
+     * const results = await bazaar.discover({
+     *   category: 'ai',
+     *   network: 'base',
+     *   token: 'USDC',
+     *   maxPrice: '0.10',
+     * });
+     *
+     * for (const resource of results.resources) {
+     *   console.log(`${resource.name}: ${resource.url}`);
+     * }
+     * ```
+     */
+    discover(options?: BazaarDiscoverOptions): Promise<BazaarDiscoverResponse>;
+    /**
+     * Get a specific resource by ID
+     *
+     * @param resourceId - Resource ID
+     * @returns Resource details
+     */
+    getResource(resourceId: string): Promise<BazaarResource>;
+    /**
+     * Get a resource by its URL
+     *
+     * @param resourceUrl - Resource URL
+     * @returns Resource details
+     */
+    getResourceByUrl(resourceUrl: string): Promise<BazaarResource>;
+    /**
+     * Register a new resource in the Bazaar
+     *
+     * Requires API key authentication.
+     *
+     * @param options - Resource registration options
+     * @returns Registered resource
+     *
+     * @example
+     * ```ts
+     * const resource = await bazaar.register({
+     *   url: 'https://api.example.com/v1/generate',
+     *   name: 'Image Generator API',
+     *   description: 'Generate images with AI',
+     *   category: 'ai',
+     *   networks: ['base', 'ethereum', 'polygon'],
+     *   price: '0.05',
+     *   payTo: '0x1234...',
+     *   tags: ['ai', 'image', 'generator'],
+     * });
+     * ```
+     */
+    register(options: BazaarRegisterOptions): Promise<BazaarResource>;
+    /**
+     * Update an existing resource
+     *
+     * Requires API key authentication. Only the owner can update.
+     *
+     * @param resourceId - Resource ID to update
+     * @param updates - Partial update options
+     * @returns Updated resource
+     */
+    update(resourceId: string, updates: Partial<BazaarRegisterOptions>): Promise<BazaarResource>;
+    /**
+     * Delete a resource from the Bazaar
+     *
+     * Requires API key authentication. Only the owner can delete.
+     *
+     * @param resourceId - Resource ID to delete
+     */
+    delete(resourceId: string): Promise<void>;
+    /**
+     * Deactivate a resource (soft delete)
+     *
+     * Requires API key authentication. Only the owner can deactivate.
+     *
+     * @param resourceId - Resource ID to deactivate
+     * @returns Updated resource with isActive: false
+     */
+    deactivate(resourceId: string): Promise<BazaarResource>;
+    /**
+     * Reactivate a deactivated resource
+     *
+     * Requires API key authentication. Only the owner can reactivate.
+     *
+     * @param resourceId - Resource ID to reactivate
+     * @returns Updated resource with isActive: true
+     */
+    reactivate(resourceId: string): Promise<BazaarResource>;
+    /**
+     * List all resources owned by the authenticated user
+     *
+     * Requires API key authentication.
+     *
+     * @param options - Pagination options
+     * @returns Paginated list of owned resources
+     */
+    listMyResources(options?: {
+        page?: number;
+        limit?: number;
+        includeInactive?: boolean;
+    }): Promise<BazaarDiscoverResponse>;
+    /**
+     * Get Bazaar API health status
+     *
+     * @returns True if the Bazaar API is healthy
+     */
+    healthCheck(): Promise<boolean>;
+    /**
+     * Get Bazaar statistics
+     *
+     * @returns Global statistics about the Bazaar
+     */
+    getStats(): Promise<{
+        totalResources: number;
+        activeResources: number;
+        totalProviders: number;
+        categoryCounts: Record<BazaarCategory, number>;
+        networkCounts: Record<BazaarNetwork, number>;
+    }>;
+}
+/**
+ * Escrow payment status
+ */
+type EscrowStatus = 'pending' | 'held' | 'released' | 'refunded' | 'disputed' | 'expired';
+/**
+ * Refund request status
+ */
+type RefundStatus = 'pending' | 'approved' | 'rejected' | 'processed' | 'disputed';
+/**
+ * Dispute resolution outcome
+ */
+type DisputeOutcome = 'pending' | 'payer_wins' | 'recipient_wins' | 'split';
+/**
+ * Escrow payment record
+ */
+interface EscrowPayment {
+    /** Unique escrow ID */
+    id: string;
+    /** Original payment header (base64 encoded) */
+    paymentHeader: string;
+    /** Current status */
+    status: EscrowStatus;
+    /** Network where payment was made */
+    network: string;
+    /** Payer address */
+    payer: string;
+    /** Recipient address */
+    recipient: string;
+    /** Amount in atomic units */
+    amount: string;
+    /** Token/asset contract */
+    asset: string;
+    /** Resource URL being paid for */
+    resource: string;
+    /** Escrow expiration timestamp (ISO) */
+    expiresAt: string;
+    /** Release conditions (optional) */
+    releaseConditions?: {
+        /** Minimum time before release (seconds) */
+        minHoldTime?: number;
+        /** Required confirmations */
+        confirmations?: number;
+        /** Custom condition metadata */
+        custom?: unknown;
+    };
+    /** Transaction hash if released/refunded */
+    transactionHash?: string;
+    /** Creation timestamp (ISO) */
+    createdAt: string;
+    /** Last update timestamp (ISO) */
+    updatedAt: string;
+}
+/**
+ * Refund request record
+ */
+interface RefundRequest {
+    /** Unique refund request ID */
+    id: string;
+    /** Related escrow ID */
+    escrowId: string;
+    /** Current status */
+    status: RefundStatus;
+    /** Reason for refund request */
+    reason: string;
+    /** Additional evidence/details */
+    evidence?: string;
+    /** Amount requested (may be partial) */
+    amountRequested: string;
+    /** Amount approved (if any) */
+    amountApproved?: string;
+    /** Requester (payer) address */
+    requester: string;
+    /** Transaction hash if processed */
+    transactionHash?: string;
+    /** Response from recipient/facilitator */
+    response?: {
+        status: 'approved' | 'rejected';
+        reason?: string;
+        respondedAt: string;
+    };
+    /** Creation timestamp (ISO) */
+    createdAt: string;
+    /** Last update timestamp (ISO) */
+    updatedAt: string;
+}
+/**
+ * Dispute record
+ */
+interface Dispute {
+    /** Unique dispute ID */
+    id: string;
+    /** Related escrow ID */
+    escrowId: string;
+    /** Related refund request ID (if any) */
+    refundRequestId?: string;
+    /** Dispute outcome */
+    outcome: DisputeOutcome;
+    /** Initiator (payer or recipient) */
+    initiator: 'payer' | 'recipient';
+    /** Reason for dispute */
+    reason: string;
+    /** Evidence from payer */
+    payerEvidence?: string;
+    /** Evidence from recipient */
+    recipientEvidence?: string;
+    /** Arbitration notes */
+    arbitrationNotes?: string;
+    /** Amount resolved to payer */
+    payerAmount?: string;
+    /** Amount resolved to recipient */
+    recipientAmount?: string;
+    /** Transaction hash(es) for resolution */
+    transactionHashes?: string[];
+    /** Creation timestamp (ISO) */
+    createdAt: string;
+    /** Resolution timestamp (ISO) */
+    resolvedAt?: string;
+}
+/**
+ * Options for creating an escrow payment
+ */
+interface CreateEscrowOptions {
+    /** Payment header (from client SDK) */
+    paymentHeader: string;
+    /** Payment requirements */
+    requirements: PaymentRequirements;
+    /** Escrow duration in seconds (default: 86400 = 24h) */
+    escrowDuration?: number;
+    /** Release conditions */
+    releaseConditions?: {
+        minHoldTime?: number;
+        confirmations?: number;
+        custom?: unknown;
+    };
+}
+/**
+ * Options for requesting a refund
+ */
+interface RequestRefundOptions {
+    /** Escrow ID to refund */
+    escrowId: string;
+    /** Reason for refund */
+    reason: string;
+    /** Amount to refund (full amount if not specified) */
+    amount?: string;
+    /** Supporting evidence */
+    evidence?: string;
+}
+/**
+ * Options for the EscrowClient
+ */
+interface EscrowClientOptions {
+    /** Base URL of the Escrow API (default: https://escrow.ultravioletadao.xyz) */
+    baseUrl?: string;
+    /** API key for authenticated operations */
+    apiKey?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+}
+/**
+ * Client for x402 Escrow & Refund operations
+ *
+ * The Escrow system holds payments until service is verified,
+ * enabling refunds and dispute resolution.
+ *
+ * @example
+ * ```ts
+ * // Create escrow payment (backend)
+ * const escrow = new EscrowClient();
+ * const escrowPayment = await escrow.createEscrow({
+ *   paymentHeader: req.headers['x-payment'],
+ *   requirements: paymentRequirements,
+ *   escrowDuration: 86400, // 24 hours
+ * });
+ *
+ * // After service is provided, release the escrow
+ * await escrow.release(escrowPayment.id);
+ *
+ * // If service not provided, payer can request refund
+ * await escrow.requestRefund({
+ *   escrowId: escrowPayment.id,
+ *   reason: 'Service not delivered within expected timeframe',
+ * });
+ * ```
+ */
+declare class EscrowClient {
+    private readonly baseUrl;
+    private readonly apiKey?;
+    private readonly timeout;
+    constructor(options?: EscrowClientOptions);
+    private getHeaders;
+    /**
+     * Create an escrow payment
+     *
+     * Holds the payment in escrow until released or refunded.
+     *
+     * @param options - Escrow creation options
+     * @returns Created escrow payment
+     */
+    createEscrow(options: CreateEscrowOptions): Promise<EscrowPayment>;
+    /**
+     * Get escrow payment by ID
+     *
+     * @param escrowId - Escrow payment ID
+     * @returns Escrow payment details
+     */
+    getEscrow(escrowId: string): Promise<EscrowPayment>;
+    /**
+     * Release escrow funds to recipient
+     *
+     * Call this after service has been successfully provided.
+     *
+     * @param escrowId - Escrow payment ID
+     * @returns Updated escrow payment with transaction hash
+     */
+    release(escrowId: string): Promise<EscrowPayment>;
+    /**
+     * Request a refund for an escrow payment
+     *
+     * Initiates a refund request that must be approved.
+     *
+     * @param options - Refund request options
+     * @returns Created refund request
+     */
+    requestRefund(options: RequestRefundOptions): Promise<RefundRequest>;
+    /**
+     * Approve a refund request (for recipients)
+     *
+     * @param refundId - Refund request ID
+     * @param amount - Amount to approve (may be less than requested)
+     * @returns Updated refund request
+     */
+    approveRefund(refundId: string, amount?: string): Promise<RefundRequest>;
+    /**
+     * Reject a refund request (for recipients)
+     *
+     * @param refundId - Refund request ID
+     * @param reason - Reason for rejection
+     * @returns Updated refund request
+     */
+    rejectRefund(refundId: string, reason: string): Promise<RefundRequest>;
+    /**
+     * Get refund request by ID
+     *
+     * @param refundId - Refund request ID
+     * @returns Refund request details
+     */
+    getRefund(refundId: string): Promise<RefundRequest>;
+    /**
+     * Open a dispute for an escrow payment
+     *
+     * Initiates arbitration when payer and recipient disagree.
+     *
+     * @param escrowId - Escrow payment ID
+     * @param reason - Reason for dispute
+     * @param evidence - Supporting evidence
+     * @returns Created dispute
+     */
+    openDispute(escrowId: string, reason: string, evidence?: string): Promise<Dispute>;
+    /**
+     * Submit evidence to a dispute
+     *
+     * @param disputeId - Dispute ID
+     * @param evidence - Evidence to submit
+     * @returns Updated dispute
+     */
+    submitEvidence(disputeId: string, evidence: string): Promise<Dispute>;
+    /**
+     * Get dispute by ID
+     *
+     * @param disputeId - Dispute ID
+     * @returns Dispute details
+     */
+    getDispute(disputeId: string): Promise<Dispute>;
+    /**
+     * List escrow payments (with filters)
+     *
+     * @param options - Filter and pagination options
+     * @returns Paginated list of escrow payments
+     */
+    listEscrows(options?: {
+        status?: EscrowStatus;
+        payer?: string;
+        recipient?: string;
+        page?: number;
+        limit?: number;
+    }): Promise<{
+        escrows: EscrowPayment[];
+        total: number;
+        page: number;
+        limit: number;
+        hasMore: boolean;
+    }>;
+    /**
+     * Check Escrow API health
+     *
+     * @returns True if healthy
+     */
+    healthCheck(): Promise<boolean>;
+}
+/**
+ * Check if an escrow can be released
+ *
+ * @param escrow - Escrow payment to check
+ * @returns True if the escrow can be released
+ */
+declare function canReleaseEscrow(escrow: EscrowPayment): boolean;
+/**
+ * Check if an escrow can be refunded
+ *
+ * @param escrow - Escrow payment to check
+ * @returns True if the escrow can be refunded
+ */
+declare function canRefundEscrow(escrow: EscrowPayment): boolean;
+/**
+ * Check if an escrow is expired
+ *
+ * @param escrow - Escrow payment to check
+ * @returns True if the escrow is expired
+ */
+declare function isEscrowExpired(escrow: EscrowPayment): boolean;
+/**
+ * Calculate time remaining until escrow expires
+ *
+ * @param escrow - Escrow payment to check
+ * @returns Milliseconds until expiration (negative if expired)
+ */
+declare function escrowTimeRemaining(escrow: EscrowPayment): number;
+
+export { type BazaarCategory, BazaarClient, type BazaarClientOptions, type BazaarDiscoverOptions, type BazaarDiscoverResponse, type BazaarNetwork, type BazaarRegisterOptions, type BazaarResource, type BazaarToken, type CreateEscrowOptions, type Dispute, type DisputeOutcome, EscrowClient, type EscrowClientOptions, type EscrowPayment, type EscrowStatus, FacilitatorClient, type FacilitatorClientOptions, type PaymentRequirements, type PaymentRequirementsOptions, type RefundRequest, type RefundStatus, type RequestRefundOptions, type SettleRequest, type SettleResponse, type VerifyRequest, type VerifyResponse, X402_CORS_HEADERS, X402_HEADER_NAMES, buildPaymentRequirements, buildSettleRequest, buildVerifyRequest, canRefundEscrow, canReleaseEscrow, create402Response, createPaymentMiddleware, escrowTimeRemaining, extractPaymentFromHeaders, getCorsHeaders, isEscrowExpired, parsePaymentHeader };