@zauthx402/sdk 0.1.1

package/dist/index-CzB2rK59.d.ts

@@ -0,0 +1,1114 @@
+import { Request, RequestHandler } from 'express';
+
+/**
+ * Implementation-agnostic x402 types
+ * These types are designed to work with any x402 implementation
+ * (coinbase/@x402, custom implementations, etc.)
+ */
+/**
+ * Supported blockchain networks
+ */
+type X402Network = 'base' | 'base-sepolia' | 'solana' | 'solana-devnet' | 'solana-testnet' | string;
+/**
+ * Payment scheme type
+ */
+type X402Scheme = 'exact' | string;
+/**
+ * x402 Version
+ */
+type X402Version = 1 | 2;
+/**
+ * Payment requirement from a 402 response
+ */
+interface X402PaymentRequirement {
+    scheme: X402Scheme;
+    network: X402Network;
+    payTo: string;
+    asset: string;
+    amount?: string;
+    maxAmountRequired?: string;
+    resource?: string;
+    description?: string;
+    extra?: Record<string, unknown>;
+}
+/**
+ * 402 response body structure (V1)
+ */
+interface X402ResponseV1 {
+    x402Version: 1;
+    accepts: X402PaymentRequirement[];
+    resource?: string;
+}
+/**
+ * 402 response body structure (V2)
+ */
+interface X402ResponseV2 {
+    x402Version: 2;
+    paymentRequirements: X402PaymentRequirement[];
+}
+/**
+ * Union of all 402 response formats
+ */
+type X402Response = X402ResponseV1 | X402ResponseV2;
+/**
+ * Payment payload sent in X-PAYMENT header
+ */
+interface X402PaymentPayload {
+    x402Version: X402Version;
+    scheme: X402Scheme;
+    network: X402Network;
+    payload: unknown;
+}
+/**
+ * Payment response header structure
+ */
+interface X402PaymentResponse {
+    success: boolean;
+    transaction?: string;
+    txSignature?: string;
+    signature?: string;
+    amount?: string;
+    paidAmount?: string;
+    network?: X402Network;
+    payer?: string;
+    from?: string;
+    error?: string;
+}
+/**
+ * Normalized payment info extracted from various x402 implementations
+ */
+interface X402PaymentInfo {
+    transactionHash: string | null;
+    amountPaid: string | null;
+    amountPaidUsdc: string | null;
+    network: X402Network | null;
+    payTo: string | null;
+    asset: string | null;
+}
+/**
+ * Helper to parse 402 response (works with V1 and V2)
+ */
+declare function parseX402Response(body: unknown): X402Response | null;
+/**
+ * Extract payment requirements from any x402 response format
+ */
+declare function getPaymentRequirements(response: X402Response): X402PaymentRequirement[];
+/**
+ * Extract price in USDC (6 decimals) from payment requirement
+ */
+declare function getPriceUsdc(requirement: X402PaymentRequirement): string | null;
+/**
+ * Decode X-PAYMENT-RESPONSE header
+ */
+declare function decodePaymentResponse(header: string): X402PaymentResponse | null;
+/**
+ * Encode payment payload for X-PAYMENT header
+ */
+declare function encodePaymentPayload(payload: X402PaymentPayload): string;
+
+/**
+ * Event types for monitoring and telemetry
+ */
+
+/**
+ * Status of an endpoint based on monitoring
+ */
+type EndpointStatus = 'UNTESTED' | 'WORKING' | 'FAILING' | 'FLAKY' | 'OVER_BUDGET';
+/**
+ * Base event structure
+ */
+interface ZauthEventBase {
+    /** Unique event ID */
+    eventId: string;
+    /** ISO timestamp */
+    timestamp: string;
+    /** Event type */
+    type: string;
+    /** API key used */
+    apiKey: string;
+    /** SDK version */
+    sdkVersion: string;
+}
+/**
+ * Request event - sent when a request is received (provider) or made (client)
+ */
+interface RequestEvent extends ZauthEventBase {
+    type: 'request';
+    /** Full URL of the endpoint */
+    url: string;
+    /** Base URL without query params */
+    baseUrl: string;
+    /** HTTP method */
+    method: string;
+    /** Request headers (sensitive ones redacted) */
+    headers: Record<string, string>;
+    /** Query parameters */
+    queryParams: Record<string, string>;
+    /** Request body (if JSON) */
+    body: unknown;
+    /** Size of request in bytes */
+    requestSize: number;
+    /** Source IP (for providers) */
+    sourceIp?: string;
+    /** User agent */
+    userAgent?: string;
+    /** Payment header if present */
+    paymentHeader?: string;
+}
+/**
+ * Response event - sent after response is generated/received
+ */
+interface ResponseEvent extends ZauthEventBase {
+    type: 'response';
+    /** Request event ID this responds to */
+    requestEventId: string;
+    /** Full URL of the endpoint */
+    url: string;
+    /** HTTP status code */
+    statusCode: number;
+    /** Response headers */
+    headers: Record<string, string>;
+    /** Response body (if JSON, truncated if large) */
+    body: unknown;
+    /** Size of response in bytes */
+    responseSize: number;
+    /** Time to generate/receive response in ms */
+    responseTimeMs: number;
+    /** Whether response was successful (2xx and meaningful) */
+    success: boolean;
+    /** Was response meaningful according to validator */
+    meaningful: boolean;
+    /** Validation result details */
+    validationResult?: ValidationResult;
+    /** Payment response info */
+    paymentResponse?: X402PaymentInfo;
+    /** Error message if failed */
+    errorMessage?: string;
+    /** Expected response shape (from provider config) for server-side AI validation */
+    expectedResponse?: string;
+}
+/**
+ * Payment event - sent when a payment is made or received
+ */
+interface PaymentEvent extends ZauthEventBase {
+    type: 'payment';
+    /** Request event ID this payment is for */
+    requestEventId: string;
+    /** Endpoint URL */
+    url: string;
+    /** Payment network */
+    network: X402Network;
+    /** Transaction hash/signature */
+    transactionHash: string;
+    /** Amount paid in base units */
+    amountPaid: string;
+    /** Amount paid in USDC */
+    amountPaidUsdc: string;
+    /** Recipient address */
+    payTo: string;
+    /** Asset address/identifier */
+    asset: string;
+    /** Payer address */
+    payer: string;
+    /** Payment scheme used */
+    scheme: string;
+}
+/**
+ * Refund event - sent when a refund is triggered
+ */
+interface RefundEvent extends ZauthEventBase {
+    type: 'refund';
+    /** Original request event ID */
+    requestEventId: string;
+    /** Original payment event ID */
+    paymentEventId: string;
+    /** Endpoint URL */
+    url: string;
+    /** Refund transaction hash */
+    refundTransactionHash: string;
+    /** Amount refunded in base units */
+    amountRefunded: string;
+    /** Amount refunded in USDC */
+    amountRefundedUsdc: string;
+    /** Recipient of refund */
+    refundTo: string;
+    /** Reason for refund */
+    reason: RefundReason;
+    /** Additional details */
+    details?: string;
+}
+/**
+ * Refund reasons
+ */
+type RefundReason = 'empty_response' | 'invalid_response' | 'schema_validation_failed' | 'timeout' | 'server_error' | 'custom';
+/**
+ * Error event - sent when an error occurs
+ */
+interface ErrorEvent extends ZauthEventBase {
+    type: 'error';
+    /** Request event ID if applicable */
+    requestEventId?: string;
+    /** Endpoint URL */
+    url: string;
+    /** Error code */
+    errorCode: string;
+    /** Error message */
+    errorMessage: string;
+    /** Stack trace (in development mode only) */
+    stackTrace?: string;
+    /** Whether this was a provider failure (5xx) vs client error (4xx) */
+    isProviderFailure: boolean;
+}
+/**
+ * Health check event - periodic health status
+ */
+interface HealthCheckEvent extends ZauthEventBase {
+    type: 'health_check';
+    /** Endpoint URL */
+    url: string;
+    /** Whether endpoint responded */
+    responsive: boolean;
+    /** Whether 402 payment requirements are valid */
+    paymentRequirementsValid: boolean;
+    /** Payment requirements if valid */
+    paymentRequirements?: X402PaymentRequirement[];
+    /** Response time in ms */
+    responseTimeMs: number;
+    /** Error if not responsive */
+    error?: string;
+}
+/**
+ * Validation result from response validator
+ */
+interface ValidationResult {
+    /** Overall validation passed */
+    valid: boolean;
+    /** Individual check results */
+    checks: ValidationCheck[];
+    /** Computed meaningfulness score (0-1) */
+    meaningfulnessScore: number;
+    /** Reason if not meaningful */
+    reason?: string;
+}
+/**
+ * Individual validation check
+ */
+interface ValidationCheck {
+    name: string;
+    passed: boolean;
+    message?: string;
+}
+/**
+ * Union of all event types
+ */
+type ZauthEvent = RequestEvent | ResponseEvent | PaymentEvent | RefundEvent | ErrorEvent | HealthCheckEvent;
+/**
+ * Batch of events to send
+ */
+interface EventBatch {
+    events: ZauthEvent[];
+    batchId: string;
+    sentAt: string;
+}
+/**
+ * Response from event submission
+ */
+interface EventSubmitResponse {
+    success: boolean;
+    batchId: string;
+    accepted: number;
+    rejected: number;
+    errors?: Array<{
+        eventId: string;
+        error: string;
+    }>;
+}
+/**
+ * Pending refund from the server
+ */
+interface PendingRefund {
+    /** Unique refund request ID */
+    id: string;
+    /** Endpoint URL */
+    url: string;
+    /** HTTP method */
+    method: string;
+    /** Network for refund (base, solana, etc.) */
+    network: X402Network;
+    /** Amount to refund in cents */
+    amountCents: number;
+    /** Amount to refund in USD */
+    amountUsd: number;
+    /** Recipient wallet address */
+    recipientAddress: string;
+    /** Why the refund was approved */
+    reason: RefundReason;
+    /** HTTP status code of failed response */
+    statusCode?: number;
+    /** Meaningfulness score of failed response */
+    meaningfulnessScore?: number;
+    /** Original payment transaction hash */
+    paymentTxHash?: string;
+    /** SDK event IDs for tracing */
+    sdkRequestEventId?: string;
+    sdkResponseEventId?: string;
+    sdkPaymentEventId?: string;
+    /** When the refund was requested */
+    requestedAt: string;
+    /** When the refund expires if not processed */
+    expiresAt?: string;
+}
+/**
+ * Response from getPendingRefunds
+ */
+interface PendingRefundsResponse {
+    refunds: PendingRefund[];
+    /** Total pending refunds (may be more than returned) */
+    total: number;
+    /** Provider's refund stats */
+    stats: {
+        todayRefundedCents: number;
+        monthRefundedCents: number;
+        dailyCapCents?: number;
+        monthlyCapCents?: number;
+        remainingDailyCents?: number;
+        remainingMonthlyCents?: number;
+    };
+}
+/**
+ * Request to confirm a refund was executed
+ */
+interface ConfirmRefundRequest {
+    /** Refund request ID */
+    refundId: string;
+    /** Transaction hash of the refund */
+    txHash: string;
+    /** Network where refund was sent */
+    network: X402Network;
+    /** Actual amount refunded in token base units */
+    amountRaw: string;
+    /** Token address/identifier */
+    token?: string;
+    /** Gas cost in cents (for tracking) */
+    gasCostCents?: number;
+}
+/**
+ * Response from confirmRefund
+ */
+interface ConfirmRefundResponse {
+    success: boolean;
+    refundId: string;
+    status: 'CONFIRMED' | 'ALREADY_CONFIRMED' | 'NOT_FOUND' | 'ERROR';
+    message?: string;
+}
+/**
+ * Request to reject/skip a refund
+ */
+interface RejectRefundRequest {
+    refundId: string;
+    reason: 'EXCEEDED_CAP' | 'INVALID_RECIPIENT' | 'MANUAL_REVIEW' | 'OTHER';
+    note?: string;
+}
+/**
+ * Response from rejectRefund
+ */
+interface RejectRefundResponse {
+    success: boolean;
+    refundId: string;
+    status: 'REJECTED' | 'NOT_FOUND' | 'ERROR';
+}
+
+/**
+ * Configuration types for the zauthSDK
+ */
+
+/**
+ * Main SDK configuration
+ */
+interface ZauthConfig {
+    /**
+     * Your zauthx402 API key
+     * Get this from https://zauthx402.com/dashboard
+     */
+    apiKey: string;
+    /**
+     * API endpoint for zauthx402 service
+     * @default 'https://back.zauthx402.com'
+     */
+    apiEndpoint?: string;
+    /**
+     * SDK mode: provider (hosting x402 endpoints)
+     */
+    mode: 'provider';
+    /**
+     * Enable debug logging
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * Environment name for grouping events
+     * @default process.env.NODE_ENV || 'development'
+     */
+    environment?: string;
+    /**
+     * Event batching configuration
+     */
+    batching?: BatchingConfig;
+    /**
+     * Response validation configuration (provider mode)
+     */
+    validation?: ValidationConfig;
+    /**
+     * Refund configuration (provider mode)
+     */
+    refund?: RefundConfig;
+    /**
+     * Telemetry configuration
+     */
+    telemetry?: TelemetryConfig;
+}
+/**
+ * Event batching configuration
+ */
+interface BatchingConfig {
+    /**
+     * Maximum events to batch before sending
+     * @default 10
+     */
+    maxBatchSize?: number;
+    /**
+     * Maximum time to wait before sending batch (ms)
+     * @default 5000
+     */
+    maxBatchWaitMs?: number;
+    /**
+     * Retry failed batches
+     * @default true
+     */
+    retry?: boolean;
+    /**
+     * Max retry attempts
+     * @default 3
+     */
+    maxRetries?: number;
+}
+/**
+ * Response validation configuration
+ */
+interface ValidationConfig {
+    /**
+     * JSON schema for valid responses
+     * If provided, responses will be validated against this schema
+     */
+    responseSchema?: Record<string, unknown>;
+    /**
+     * Custom validator function
+     * Return ValidationResult with valid=true if response is meaningful
+     */
+    customValidator?: (response: unknown, statusCode: number) => ValidationResult;
+    /**
+     * Minimum response size to consider meaningful (bytes)
+     * @default 2 (i.e., not empty "{}" or "[]")
+     */
+    minResponseSize?: number;
+    /**
+     * Fields that must be present in response
+     */
+    requiredFields?: string[];
+    /**
+     * Fields that must NOT be present (error indicators)
+     */
+    errorFields?: string[];
+    /**
+     * Consider empty arrays/objects as invalid
+     * @default true
+     */
+    rejectEmptyCollections?: boolean;
+}
+/**
+ * Refund configuration (provider mode)
+ * Supports global settings and per-endpoint overrides
+ */
+interface RefundConfig {
+    /**
+     * Enable automatic refunds (master switch)
+     * @default false
+     */
+    enabled?: boolean;
+    /**
+     * Signer for refund transactions (viem Account or private key string)
+     * Should be a hot wallet with limited funds
+     * Can also be set via ZAUTH_REFUND_PRIVATE_KEY env var
+     */
+    signer?: RefundSigner;
+    /**
+     * Private key for refund transactions (deprecated, use signer)
+     * @deprecated Use signer instead
+     */
+    privateKey?: string;
+    /**
+     * Default network for refunds (can be overridden per-endpoint)
+     * @default 'base'
+     */
+    network?: X402Network;
+    /**
+     * Global refund triggers
+     */
+    triggers?: RefundTriggers;
+    /**
+     * Maximum refund amount in USD per transaction (global default)
+     * @default 1.00
+     */
+    maxRefundUsd?: number;
+    /**
+     * Daily refund cap in USD (optional safety limit)
+     */
+    dailyCapUsd?: number;
+    /**
+     * Monthly refund cap in USD (optional safety limit)
+     */
+    monthlyCapUsd?: number;
+    /**
+     * Per-endpoint refund configuration overrides
+     * Key is URL pattern (supports * wildcard)
+     */
+    endpoints?: Record<string, EndpointRefundConfig>;
+    /**
+     * Polling configuration for checking pending refunds
+     */
+    polling?: RefundPollingConfig;
+    /**
+     * Callback when a refund is executed
+     */
+    onRefund?: (refund: ExecutedRefund) => void | Promise<void>;
+    /**
+     * Callback when a refund fails
+     */
+    onRefundError?: (error: RefundError) => void | Promise<void>;
+}
+/**
+ * Signer type - can be a viem Account or private key string
+ */
+type RefundSigner = string | {
+    address: string;
+    signTransaction: (tx: unknown) => Promise<string>;
+};
+/**
+ * What triggers an automatic refund
+ */
+interface RefundTriggers {
+    /** Refund on 5xx server errors */
+    serverError?: boolean;
+    /** Refund on request timeout */
+    timeout?: boolean;
+    /** Refund on empty/meaningless response */
+    emptyResponse?: boolean;
+    /** Refund when response doesn't match expected schema */
+    schemaValidation?: boolean;
+    /** Minimum meaningfulness score - refund if below this */
+    minMeaningfulness?: number;
+}
+/**
+ * Per-endpoint refund configuration
+ */
+interface EndpointRefundConfig {
+    /** Override enabled for this endpoint (null = use global) */
+    enabled?: boolean;
+    /** Override max refund for this endpoint */
+    maxRefundUsd?: number;
+    /** Override triggers for this endpoint */
+    triggers?: Partial<RefundTriggers>;
+    /** Custom matcher for this endpoint */
+    shouldRefund?: (response: unknown, statusCode: number, validationResult: ValidationResult) => boolean;
+    /** Plain text description of expected response shape for AI validation */
+    expectedResponse?: string;
+}
+/**
+ * Polling configuration for checking pending refunds
+ */
+interface RefundPollingConfig {
+    /** Enable polling (defaults to true if refunds enabled) */
+    enabled?: boolean;
+    /** Polling interval in milliseconds @default 30000 */
+    intervalMs?: number;
+    /** Max refunds to process per poll @default 10 */
+    batchSize?: number;
+}
+/**
+ * Successfully executed refund
+ */
+interface ExecutedRefund {
+    refundId: string;
+    requestId: string;
+    url: string;
+    amountUsd: number;
+    amountRaw: string;
+    txHash: string;
+    network: X402Network;
+    recipient: string;
+    reason: RefundReason;
+    executedAt: string;
+}
+/**
+ * Refund execution error
+ */
+interface RefundError {
+    refundId: string;
+    url: string;
+    amountUsd: number;
+    error: string;
+    retryable: boolean;
+}
+/**
+ * Condition that triggers a refund (legacy - use RefundTriggers)
+ * @deprecated Use RefundTriggers instead
+ */
+interface RefundCondition {
+    reason: RefundReason;
+    enabled: boolean;
+    /** Additional matcher for this condition */
+    matcher?: (response: unknown, statusCode: number) => boolean;
+}
+/**
+ * Telemetry configuration
+ */
+interface TelemetryConfig {
+    /**
+     * Include request body in events
+     * @default true
+     */
+    includeRequestBody?: boolean;
+    /**
+     * Include response body in events
+     * @default true
+     */
+    includeResponseBody?: boolean;
+    /**
+     * Maximum body size to include (bytes)
+     * Bodies larger than this will be truncated
+     * @default 10000
+     */
+    maxBodySize?: number;
+    /**
+     * Headers to redact from events
+     * @default ['authorization', 'cookie', 'x-api-key']
+     */
+    redactHeaders?: string[];
+    /**
+     * Fields to redact from request/response bodies
+     * Supports dot notation (e.g., 'user.password')
+     */
+    redactFields?: string[];
+    /**
+     * Sample rate for events (0-1)
+     * 1 = send all events, 0.1 = send 10% of events
+     * @default 1
+     */
+    sampleRate?: number;
+}
+/**
+ * Provider middleware configuration
+ */
+interface ProviderMiddlewareConfig extends ZauthConfig {
+    mode: 'provider';
+    /**
+     * URL patterns to monitor
+     * If not specified, monitors all routes
+     */
+    includeRoutes?: string[];
+    /**
+     * URL patterns to exclude from monitoring
+     */
+    excludeRoutes?: string[];
+    /**
+     * Skip monitoring for health check endpoints
+     * @default true
+     */
+    skipHealthChecks?: boolean;
+}
+/**
+ * Resolved configuration with all defaults applied
+ */
+/** Resolved validation config - some fields remain optional */
+type ResolvedValidationConfig = {
+    responseSchema?: Record<string, unknown>;
+    customValidator?: (response: unknown, statusCode: number) => ValidationResult;
+    minResponseSize: number;
+    requiredFields: string[];
+    errorFields: string[];
+    rejectEmptyCollections: boolean;
+};
+/** Resolved refund config */
+interface ResolvedRefundConfig {
+    enabled: boolean;
+    signer?: RefundSigner;
+    privateKey?: string;
+    network: X402Network;
+    triggers: Required<RefundTriggers>;
+    maxRefundUsd: number;
+    dailyCapUsd?: number;
+    monthlyCapUsd?: number;
+    endpoints: Record<string, EndpointRefundConfig>;
+    polling: Required<RefundPollingConfig>;
+    onRefund?: (refund: ExecutedRefund) => void | Promise<void>;
+    onRefundError?: (error: RefundError) => void | Promise<void>;
+}
+interface ResolvedConfig {
+    apiKey: string;
+    apiEndpoint: string;
+    mode: 'provider';
+    debug: boolean;
+    environment: string;
+    batching: Required<BatchingConfig>;
+    validation: ResolvedValidationConfig;
+    refund: ResolvedRefundConfig;
+    telemetry: Required<TelemetryConfig>;
+}
+/**
+ * Default configuration values
+ */
+declare const DEFAULT_CONFIG: Omit<ResolvedConfig, 'apiKey' | 'mode'>;
+/**
+ * Resolve configuration by merging with defaults
+ */
+declare function resolveConfig(config: ZauthConfig): ResolvedConfig;
+
+/**
+ * ZauthClient - API client for zauthx402 service
+ * Handles event batching and submission
+ */
+
+/**
+ * ZauthClient handles communication with the zauthx402 API
+ */
+declare class ZauthClient {
+    private config;
+    private eventQueue;
+    private flushTimer;
+    private isFlushing;
+    constructor(config: ZauthConfig);
+    /**
+     * Debug logger
+     */
+    private log;
+    /**
+     * Create base event with common fields
+     */
+    createEventBase<T extends ZauthEvent['type']>(type: T): {
+        eventId: string;
+        timestamp: string;
+        type: T;
+        apiKey: string;
+        sdkVersion: string;
+    };
+    /**
+     * Queue an event for batched submission
+     */
+    queueEvent(event: ZauthEvent): void;
+    /**
+     * Send an event immediately (bypasses batching)
+     */
+    sendEvent(event: ZauthEvent): Promise<EventSubmitResponse>;
+    /**
+     * Flush queued events
+     */
+    flush(): Promise<void>;
+    /**
+     * Submit a batch of events to the API
+     */
+    private submitBatch;
+    /**
+     * Check endpoint status from zauthx402 registry
+     */
+    checkEndpoint(url: string): Promise<{
+        verified: boolean;
+        working: boolean;
+        meaningful: boolean;
+        lastChecked?: string;
+        uptime?: number;
+    }>;
+    /**
+     * Request a refund for a bad response
+     */
+    requestRefund(params: {
+        url: string;
+        requestEventId: string;
+        paymentEventId: string;
+        reason: string;
+        details?: string;
+    }): Promise<{
+        approved: boolean;
+        refundId?: string;
+        message?: string;
+    }>;
+    /**
+     * Get resolved configuration
+     */
+    getConfig(): ResolvedConfig;
+    /**
+     * Get pending refunds that need to be executed
+     * These are refunds that the server has approved based on bad response detection
+     */
+    getPendingRefunds(limit?: number): Promise<PendingRefundsResponse>;
+    /**
+     * Confirm that a refund was successfully executed
+     */
+    confirmRefund(request: ConfirmRefundRequest): Promise<ConfirmRefundResponse>;
+    /**
+     * Reject/skip a pending refund
+     */
+    rejectRefund(request: RejectRefundRequest): Promise<RejectRefundResponse>;
+    /**
+     * Update provider's refund configuration on the server
+     */
+    updateRefundConfig(config: {
+        enabled?: boolean;
+        maxRefundUsdCents?: number;
+        dailyCapCents?: number;
+        monthlyCapCents?: number;
+        triggers?: {
+            serverError?: boolean;
+            timeout?: boolean;
+            emptyResponse?: boolean;
+            schemaValidation?: boolean;
+            minMeaningfulness?: number;
+        };
+    }): Promise<{
+        success: boolean;
+        message?: string;
+    }>;
+    /**
+     * Get refund history/stats
+     */
+    getRefundStats(days?: number): Promise<{
+        totalRefunds: number;
+        totalAmountCents: number;
+        byReason: Record<string, number>;
+        byEndpoint: Record<string, {
+            count: number;
+            amountCents: number;
+        }>;
+        dailyTotals: Array<{
+            date: string;
+            count: number;
+            amountCents: number;
+        }>;
+    }>;
+    /**
+     * Shutdown client gracefully
+     */
+    shutdown(): Promise<void>;
+}
+/**
+ * Create a new ZauthClient instance
+ */
+declare function createClient(config: ZauthConfig): ZauthClient;
+
+/**
+ * Refund handler for automatic refunds on bad responses
+ *
+ * This is an OPTIONAL feature that requires:
+ * 1. viem package installed
+ * 2. Provider's hot wallet private key configured
+ *
+ * The refund flow:
+ * 1. SDK detects bad response (via validator)
+ * 2. SDK reports to zauthx402 service
+ * 3. If service approves, SDK triggers refund using provider's hot wallet
+ */
+
+/**
+ * Refund request parameters
+ */
+interface RefundRequest {
+    /** Original payment transaction hash */
+    paymentTxHash: string;
+    /** Amount to refund (in base units) */
+    amount: string;
+    /** Recipient address (original payer) */
+    refundTo: string;
+    /** Asset address (e.g., USDC contract) */
+    asset: string;
+    /** Network */
+    network: X402Network;
+    /** Reason for refund */
+    reason: RefundReason;
+    /** Additional details */
+    details?: string;
+    /** Request event ID for tracking */
+    requestEventId: string;
+    /** Payment event ID for tracking */
+    paymentEventId: string;
+    /** Endpoint URL */
+    url: string;
+}
+/**
+ * Refund result
+ */
+interface RefundResult {
+    success: boolean;
+    transactionHash?: string;
+    error?: string;
+}
+/**
+ * RefundHandler manages automatic refunds for providers
+ */
+declare class RefundHandler {
+    private config;
+    private client;
+    private viemAvailable;
+    constructor(config: RefundConfig, client: ZauthClient);
+    private checkViemAvailability;
+    /**
+     * Check if refunds are available
+     */
+    isAvailable(): boolean;
+    /**
+     * Get private key from config or env
+     */
+    private getPrivateKey;
+    /**
+     * Check if a response should trigger a refund
+     */
+    shouldRefund(validationResult: ValidationResult, statusCode: number): RefundReason | null;
+    /**
+     * Process a refund
+     */
+    processRefund(request: RefundRequest): Promise<RefundResult>;
+    /**
+     * Execute the actual refund transaction
+     */
+    private executeRefund;
+}
+/**
+ * Create a refund handler
+ */
+declare function createRefundHandler(config: RefundConfig, client: ZauthClient): RefundHandler;
+
+/**
+ * RefundExecutor handles real-time refund notifications via WebSocket
+ * This is the bulletproof refund system where:
+ * 1. SDK sends events to backend
+ * 2. Backend analyzes, creates refund requests, stores in Redis
+ * 3. Backend pushes refunds to SDK via WebSocket in real-time
+ * 4. SDK executes refunds and confirms via WebSocket
+ * 5. If SDK disconnects, pending refunds are resent on reconnect
+ */
+declare class RefundExecutor {
+    private client;
+    private config;
+    private debug;
+    private ws;
+    private reconnectTimer;
+    private reconnectAttempts;
+    private baseReconnectDelay;
+    private persistentRetryDelay;
+    private fastPhaseAttempts;
+    private isShuttingDown;
+    private pingInterval;
+    private todayRefundedCents;
+    private monthRefundedCents;
+    private lastCapResetDate;
+    private lastCapResetMonth;
+    constructor(client: ZauthClient, config: ResolvedRefundConfig, debug?: boolean);
+    /**
+     * Start the WebSocket connection for refund notifications
+     */
+    start(): void;
+    /**
+     * Connect to the WebSocket server
+     */
+    private connect;
+    /**
+     * Handle incoming WebSocket messages
+     */
+    private handleMessage;
+    /**
+     * Process a single pending refund
+     */
+    private processSingleRefund;
+    /**
+     * Send message via WebSocket
+     */
+    private sendMessage;
+    /**
+     * Schedule reconnection with two-phase strategy:
+     * - Fast phase: exponential backoff (1s, 2s, 4s, 8s, 16s) for quick recovery
+     * - Persistent phase: fixed 60s interval, retries indefinitely until reconnected
+     */
+    private scheduleReconnect;
+    /**
+     * Cleanup resources
+     */
+    private cleanup;
+    /**
+     * Stop the WebSocket connection
+     */
+    stop(): void;
+    /**
+     * Execute a refund transaction on-chain
+     */
+    private executeRefundTx;
+    /**
+     * Execute EVM refund (Base, Ethereum, etc.)
+     */
+    private executeEvmRefund;
+    /**
+     * Execute Solana refund
+     */
+    private executeSolanaRefund;
+    /**
+     * Get endpoint-specific config by matching URL patterns
+     */
+    private getEndpointConfig;
+    /**
+     * Debug logger
+     */
+    private log;
+}
+
+/**
+ * Express middleware for x402 providers
+ *
+ * This middleware observes requests and responses without interfering
+ * with your existing x402 implementation (coinbase/@x402, custom, etc.)
+ *
+ * Usage:
+ *   import { createZauthMiddleware } from '@zauthx402/sdk/middleware';
+ *
+ *   app.use(createZauthMiddleware({
+ *     apiKey: 'your-api-key',
+ *     mode: 'provider'
+ *   }));
+ *
+ *   // Your existing x402 middleware and routes continue to work unchanged
+ *   app.use(x402Middleware(...));
+ *   app.get('/api/paid', ...);
+ */
+
+/**
+ * Middleware options
+ */
+interface ZauthMiddlewareOptions extends ProviderMiddlewareConfig {
+    /**
+     * Custom function to determine if a route should be monitored
+     */
+    shouldMonitor?: (req: Request) => boolean;
+}
+/**
+ * Create zauth monitoring middleware for Express
+ * Returns both the middleware and a cleanup function
+ */
+declare function createZauthMiddleware(options: ZauthMiddlewareOptions): RequestHandler & {
+    shutdown: () => Promise<void>;
+    refundExecutor?: RefundExecutor;
+};
+/**
+ * Create middleware with simpler configuration
+ */
+declare function zauthProvider(apiKey: string, options?: Partial<Omit<ZauthMiddlewareOptions, 'apiKey' | 'mode'>>): RequestHandler & {
+    shutdown: () => Promise<void>;
+    refundExecutor?: RefundExecutor;
+};
+
+export { type RefundError as $, type RefundReason as A, type ErrorEvent as B, type ValidationCheck as C, type ZauthEvent as D, type EndpointStatus as E, type EventBatch as F, type EventSubmitResponse as G, type HealthCheckEvent as H, type PendingRefund as I, type PendingRefundsResponse as J, type ConfirmRefundRequest as K, type ConfirmRefundResponse as L, type RejectRefundRequest as M, type RejectRefundResponse as N, type ZauthConfig as O, type PaymentEvent as P, type BatchingConfig as Q, RefundHandler as R, type RefundConfig as S, type RefundSigner as T, type RefundTriggers as U, type ValidationConfig as V, type EndpointRefundConfig as W, type X402Network as X, type RefundPollingConfig as Y, ZauthClient as Z, type ExecutedRefund as _, type ValidationResult as a, type RefundCondition as a0, type TelemetryConfig as a1, type ProviderMiddlewareConfig as a2, type ResolvedValidationConfig as a3, type ResolvedRefundConfig as a4, type ResolvedConfig as a5, DEFAULT_CONFIG as a6, resolveConfig as a7, createZauthMiddleware as b, createClient as c, type ZauthMiddlewareOptions as d, createRefundHandler as e, type RefundRequest as f, type RefundResult as g, type X402Scheme as h, type X402Version as i, type X402PaymentRequirement as j, type X402ResponseV1 as k, type X402ResponseV2 as l, type X402Response as m, type X402PaymentPayload as n, type X402PaymentResponse as o, type X402PaymentInfo as p, parseX402Response as q, getPaymentRequirements as r, getPriceUsdc as s, decodePaymentResponse as t, encodePaymentPayload as u, type ZauthEventBase as v, type RequestEvent as w, type ResponseEvent as x, type RefundEvent as y, zauthProvider as z };