@alleyboss/micropay-solana-x402-paywall 3.3.15 → 3.5.1

package/dist/fetch/index.d.ts

@@ -0,0 +1,403 @@
+import { WalletAdapter } from '@solana/wallet-adapter-base';
+import { Keypair, Connection } from '@solana/web3.js';
+
+/**
+ * @fileoverview Type definitions for x402Fetch
+ * @module @alleyboss/micropay-solana-x402-paywall/fetch
+ */
+
+/**
+ * Solana network identifier
+ */
+type SolanaNetwork = 'devnet' | 'mainnet-beta' | 'testnet';
+/**
+ * Wallet type - supports both browser wallet adapters and server-side keypairs
+ */
+type WalletLike = WalletAdapter | Keypair;
+/**
+ * Payment requirements extracted from 402 response
+ */
+interface PaymentRequirements {
+    /** Recipient wallet address */
+    readonly payTo: string;
+    /** Amount in smallest unit (lamports for SOL) */
+    readonly amount: string;
+    /** Asset identifier (e.g., 'SOL', 'USDC') */
+    readonly asset: string;
+    /** Network identifier */
+    readonly network: string;
+    /** Optional: Human-readable description */
+    readonly description?: string;
+    /** Optional: Resource identifier */
+    readonly resource?: string;
+    /** Optional: Maximum age of payment proof in seconds */
+    readonly maxAge?: number;
+}
+/**
+ * Configuration for createX402Fetch factory
+ */
+interface X402FetchConfig {
+    /**
+     * Solana wallet - WalletAdapter for browser, Keypair for server/agents
+     * @example
+     * // Browser
+     * { wallet: useWallet() }
+     * // Server/Agent
+     * { wallet: Keypair.fromSecretKey(...) }
+     */
+    readonly wallet: WalletLike;
+    /**
+     * Solana network to use
+     * @default 'mainnet-beta'
+     */
+    readonly network?: SolanaNetwork;
+    /**
+     * Solana RPC connection (optional - will create one if not provided)
+     */
+    readonly connection?: Connection;
+    /**
+     * Custom facilitator URL for verification
+     * If not provided, uses built-in verification
+     */
+    readonly facilitatorUrl?: string;
+    /**
+     * Callback when payment is required
+     * Return `true` to proceed with payment, `false` to abort
+     * If not provided, payment proceeds automatically
+     *
+     * @example
+     * onPaymentRequired: async (req) => {
+     *   return confirm(`Pay ${req.amount} ${req.asset}?`);
+     * }
+     */
+    readonly onPaymentRequired?: PaymentRequiredHook;
+    /**
+     * Callback after successful payment
+     */
+    readonly onPaymentSuccess?: PaymentSuccessHook;
+    /**
+     * Callback on payment failure
+     */
+    readonly onPaymentError?: PaymentErrorHook;
+    /**
+     * Priority fee configuration for Solana transactions
+     */
+    readonly priorityFee?: PriorityFeeConfig;
+    /**
+     * Maximum retries for transaction confirmation
+     * @default 3
+     */
+    readonly maxRetries?: number;
+    /**
+     * Timeout for payment flow in milliseconds
+     * @default 30000 (30 seconds)
+     */
+    readonly timeout?: number;
+    /**
+     * Maximum payment amount per request in lamports
+     * Prevents wallet drain from malicious 402 responses
+     * @default undefined (no limit - USE WITH CAUTION)
+     * @example 10_000_000n // Max 0.01 SOL per request
+     */
+    readonly maxPaymentPerRequest?: bigint;
+    /**
+     * Whitelist of allowed recipient addresses
+     * Payments to addresses not in this list will be rejected
+     * @default undefined (allow all - USE WITH CAUTION)
+     * @example ['7fPjN...', 'ABC123...']
+     */
+    readonly allowedRecipients?: readonly string[];
+    /**
+     * Solana commitment level for transaction confirmation
+     * - 'processed': Fastest (~100ms), optimistic, may revert
+     * - 'confirmed': Balanced (~400ms), supermajority confirmed
+     * - 'finalized': Slowest (~30s), irreversible
+     * @default 'confirmed'
+     */
+    readonly commitment?: 'processed' | 'confirmed' | 'finalized';
+    /**
+     * Rate limiting configuration to prevent infinite payment loops
+     */
+    readonly rateLimit?: RateLimitConfig;
+}
+/**
+ * Rate limiting configuration
+ */
+interface RateLimitConfig {
+    /**
+     * Maximum number of payments allowed within the time window
+     * @default 10
+     */
+    readonly maxPayments: number;
+    /**
+     * Time window in milliseconds
+     * @default 60000 (1 minute)
+     */
+    readonly windowMs: number;
+}
+/**
+ * Priority fee configuration
+ */
+interface PriorityFeeConfig {
+    /** Enable priority fees */
+    readonly enabled: boolean;
+    /** Micro-lamports per compute unit */
+    readonly microLamports?: number;
+}
+/**
+ * Hook called when payment is required
+ * @returns Promise<boolean> - true to proceed, false to abort
+ */
+type PaymentRequiredHook = (requirements: PaymentRequirements, url: string) => Promise<boolean> | boolean;
+/**
+ * Hook called after successful payment
+ */
+type PaymentSuccessHook = (signature: string, requirements: PaymentRequirements) => void | Promise<void>;
+/**
+ * Hook called on payment error
+ */
+type PaymentErrorHook = (error: Error, requirements?: PaymentRequirements) => void | Promise<void>;
+/**
+ * Extended RequestInit with x402-specific options
+ */
+interface X402RequestInit extends RequestInit {
+    /**
+     * Skip payment flow - useful for checking if resource requires payment
+     */
+    readonly skipPayment?: boolean;
+    /**
+     * Custom payment requirements override
+     */
+    readonly paymentOverride?: Partial<PaymentRequirements>;
+}
+/**
+ * x402Fetch function signature
+ */
+interface X402FetchFunction {
+    /**
+     * Fetch with automatic 402 handling
+     *
+     * @param input - URL or Request object
+     * @param init - Extended fetch options
+     * @returns Promise<Response>
+     * @throws {X402PaymentError} on payment failure
+     *
+     * @example
+     * const response = await x402Fetch('/api/premium');
+     * const data = await response.json();
+     */
+    (input: RequestInfo | URL, init?: X402RequestInit): Promise<Response>;
+}
+/**
+ * Error codes for X402PaymentError
+ */
+declare const X402ErrorCode: {
+    /** User rejected the payment */
+    readonly USER_REJECTED: "USER_REJECTED";
+    /** Insufficient wallet balance */
+    readonly INSUFFICIENT_BALANCE: "INSUFFICIENT_BALANCE";
+    /** Transaction failed on-chain */
+    readonly TRANSACTION_FAILED: "TRANSACTION_FAILED";
+    /** Payment verification failed */
+    readonly VERIFICATION_FAILED: "VERIFICATION_FAILED";
+    /** Network/RPC error */
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    /** Invalid 402 response format */
+    readonly INVALID_402_RESPONSE: "INVALID_402_RESPONSE";
+    /** Payment timeout */
+    readonly TIMEOUT: "TIMEOUT";
+    /** Wallet not connected */
+    readonly WALLET_NOT_CONNECTED: "WALLET_NOT_CONNECTED";
+    /** Payment amount exceeds maxPaymentPerRequest */
+    readonly AMOUNT_EXCEEDS_LIMIT: "AMOUNT_EXCEEDS_LIMIT";
+    /** Recipient address not in allowedRecipients whitelist */
+    readonly RECIPIENT_NOT_ALLOWED: "RECIPIENT_NOT_ALLOWED";
+    /** Rate limit exceeded */
+    readonly RATE_LIMIT_EXCEEDED: "RATE_LIMIT_EXCEEDED";
+};
+type X402ErrorCode = (typeof X402ErrorCode)[keyof typeof X402ErrorCode];
+/**
+ * Payment result from successful transaction
+ */
+interface PaymentResult {
+    /** Transaction signature */
+    readonly signature: string;
+    /** Amount paid in lamports */
+    readonly amountPaid: bigint;
+    /** Recipient address */
+    readonly recipient: string;
+    /** Timestamp of payment */
+    readonly timestamp: number;
+}
+
+/**
+ * @fileoverview x402Fetch - Drop-in fetch() replacement with automatic 402 handling
+ * @module @alleyboss/micropay-solana-x402-paywall/fetch
+ *
+ * @example
+ * ```typescript
+ * import { createX402Fetch } from '@alleyboss/micropay-solana-x402-paywall/fetch';
+ *
+ * const x402Fetch = createX402Fetch({
+ *   wallet: useWallet(),  // or Keypair for server-side
+ *   network: 'mainnet-beta',
+ * });
+ *
+ * // Use it like fetch() - automatically handles 402 responses
+ * const response = await x402Fetch('/api/premium-data');
+ * const data = await response.json();
+ * ```
+ */
+
+/**
+ * Parse payment requirements from 402 response headers
+ */
+declare function parse402Response(response: Response): PaymentRequirements;
+/**
+ * Build x402 payment proof header
+ */
+declare function buildPaymentHeader(signature: string): string;
+/**
+ * Create a configured x402Fetch instance
+ *
+ * This factory function returns a fetch-like function that automatically
+ * handles HTTP 402 responses by executing Solana payments.
+ *
+ * @param config - Configuration options
+ * @returns A fetch function that handles 402 automatically
+ *
+ * @example Browser (with Wallet Adapter)
+ * ```typescript
+ * import { useWallet } from '@solana/wallet-adapter-react';
+ *
+ * function MyComponent() {
+ *   const wallet = useWallet();
+ *   const x402Fetch = useMemo(() => createX402Fetch({
+ *     wallet,
+ *     network: 'mainnet-beta',
+ *     onPaymentRequired: async (req) => {
+ *       return confirm(`Pay ${req.amount} lamports?`);
+ *     },
+ *   }), [wallet]);
+ *
+ *   // Use it like fetch
+ *   const loadData = () => x402Fetch('/api/premium').then(r => r.json());
+ * }
+ * ```
+ *
+ * @example Server/Agent (with Keypair)
+ * ```typescript
+ * import { Keypair } from '@solana/web3.js';
+ * import bs58 from 'bs58';
+ *
+ * const agentKeypair = Keypair.fromSecretKey(
+ *   bs58.decode(process.env.AGENT_PRIVATE_KEY!)
+ * );
+ *
+ * const x402Fetch = createX402Fetch({
+ *   wallet: agentKeypair,
+ *   network: 'mainnet-beta',
+ * });
+ *
+ * // Autonomous payment
+ * const response = await x402Fetch('https://api.example.com/data');
+ * ```
+ */
+declare function createX402Fetch(config: X402FetchConfig): X402FetchFunction;
+
+/**
+ * @fileoverview Custom error classes for x402Fetch
+ * @module @alleyboss/micropay-solana-x402-paywall/fetch
+ */
+
+/**
+ * Base error for all x402 payment-related errors
+ *
+ * @example
+ * try {
+ *   await x402Fetch('/api/premium');
+ * } catch (error) {
+ *   if (error instanceof X402PaymentError) {
+ *     console.log(error.code);         // 'USER_REJECTED'
+ *     console.log(error.requirements); // { payTo: '...', amount: '...' }
+ *   }
+ * }
+ */
+declare class X402PaymentError extends Error {
+    /** Error code for programmatic handling */
+    readonly code: X402ErrorCode;
+    /** Payment requirements that triggered the error */
+    readonly requirements?: PaymentRequirements | undefined;
+    /** Original error if this wraps another error */
+    readonly cause?: Error | undefined;
+    readonly name: "X402PaymentError";
+    constructor(message: string, 
+    /** Error code for programmatic handling */
+    code: X402ErrorCode, 
+    /** Payment requirements that triggered the error */
+    requirements?: PaymentRequirements | undefined, 
+    /** Original error if this wraps another error */
+    cause?: Error | undefined);
+    /**
+     * Check if error is retryable
+     */
+    get isRetryable(): boolean;
+    /**
+     * Convert to JSON-serializable object
+     */
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Create error for user rejection
+ */
+declare function userRejectedError(requirements: PaymentRequirements): X402PaymentError;
+/**
+ * Create error for insufficient balance
+ */
+declare function insufficientBalanceError(requirements: PaymentRequirements, balance: bigint): X402PaymentError;
+/**
+ * Create error for transaction failure
+ */
+declare function transactionFailedError(requirements: PaymentRequirements, cause?: Error): X402PaymentError;
+/**
+ * Create error for verification failure
+ */
+declare function verificationFailedError(requirements: PaymentRequirements, reason?: string): X402PaymentError;
+/**
+ * Create error for network issues
+ */
+declare function networkError(cause?: Error): X402PaymentError;
+/**
+ * Create error for invalid 402 response
+ */
+declare function invalid402ResponseError(details?: string): X402PaymentError;
+/**
+ * Create error for timeout
+ */
+declare function timeoutError(requirements?: PaymentRequirements): X402PaymentError;
+/**
+ * Create error for wallet not connected
+ */
+declare function walletNotConnectedError(): X402PaymentError;
+/**
+ * Create error when payment amount exceeds configured limit
+ */
+declare function amountExceedsLimitError(requirements: PaymentRequirements, limit: bigint): X402PaymentError;
+/**
+ * Create error when recipient is not in whitelist
+ */
+declare function recipientNotAllowedError(requirements: PaymentRequirements, recipient: string): X402PaymentError;
+/**
+ * Create error when rate limit is exceeded
+ */
+declare function rateLimitExceededError(limit: number, windowMs: number): X402PaymentError;
+/**
+ * Check if an error is an X402PaymentError
+ */
+declare function isX402PaymentError(error: unknown): error is X402PaymentError;
+/**
+ * Check if error indicates user explicitly rejected
+ */
+declare function isUserRejection(error: unknown): boolean;
+
+export { type PaymentErrorHook, type PaymentRequiredHook, type PaymentRequirements, type PaymentResult, type PaymentSuccessHook, type PriorityFeeConfig, type RateLimitConfig, type SolanaNetwork, type WalletLike, X402ErrorCode, type X402FetchConfig, type X402FetchFunction, X402PaymentError, type X402RequestInit, amountExceedsLimitError, buildPaymentHeader, createX402Fetch, insufficientBalanceError, invalid402ResponseError, isUserRejection, isX402PaymentError, networkError, parse402Response as parsePaymentRequirements, rateLimitExceededError, recipientNotAllowedError, timeoutError, transactionFailedError, userRejectedError, verificationFailedError, walletNotConnectedError };