x402-mantle-sdk 0.1.0

package/dist/client/index.d.ts

@@ -0,0 +1,322 @@
+/**
+ * Constants and Configuration
+ *
+ * Centralized configuration for networks and tokens
+ * Supports both preset networks (mainnet/testnet) and custom configurations
+ */
+/** Supported network identifiers */
+type NetworkId = 'mantle' | 'mantle-sepolia' | 'mantle-testnet';
+/** Network environment */
+type NetworkEnvironment = 'mainnet' | 'testnet';
+/** Network configuration */
+interface NetworkConfig {
+    chainId: number;
+    rpcUrl: string;
+    name: string;
+    environment: NetworkEnvironment;
+    nativeCurrency: {
+        name: string;
+        symbol: string;
+        decimals: number;
+    };
+    blockExplorer: string;
+}
+/** Token configuration */
+interface TokenConfig {
+    address: string;
+    decimals: number;
+    symbol: string;
+}
+/** Custom network configuration (user-provided) */
+interface CustomNetworkConfig {
+    chainId: number;
+    rpcUrl: string;
+    name?: string;
+    environment?: NetworkEnvironment;
+    blockExplorer?: string;
+}
+/** Custom token configuration (user-provided) */
+interface CustomTokenConfig {
+    [symbol: string]: {
+        address: string;
+        decimals: number;
+    };
+}
+/** Network configurations */
+declare const NETWORKS: Record<NetworkId, NetworkConfig>;
+/** Token addresses by network */
+declare const TOKENS: Record<NetworkId, Record<string, TokenConfig>>;
+/** Treasury contract address (collects 0.5% platform fee) */
+declare const TREASURY_ADDRESS = "0xB27705342ACE73736AE490540Ea031cc06C3eF49";
+/** Platform fee in basis points (50 = 0.5%) */
+declare const PLATFORM_FEE_BPS = 50n;
+/** Treasury admin address */
+declare const TREASURY_ADMIN = "0xDacCF30F8BB2aEb8D76E68E03033629809ed08E1";
+/**
+ * Register a custom network configuration
+ *
+ * @example
+ * ```typescript
+ * registerCustomNetwork('my-network', {
+ *   chainId: 12345,
+ *   rpcUrl: 'https://my-rpc.example.com',
+ *   name: 'My Custom Network',
+ *   environment: 'testnet'
+ * })
+ * ```
+ */
+declare function registerCustomNetwork(networkId: string, config: CustomNetworkConfig): void;
+/**
+ * Register custom tokens for a network
+ *
+ * @example
+ * ```typescript
+ * registerCustomTokens('mantle', {
+ *   'MYTOKEN': { address: '0x...', decimals: 18 }
+ * })
+ * ```
+ */
+declare function registerCustomTokens(networkId: string, tokens: CustomTokenConfig): void;
+/**
+ * Check if network is testnet
+ */
+declare function isTestnet(network: string): boolean;
+/**
+ * Check if network is mainnet
+ */
+declare function isMainnet(network: string): boolean;
+/**
+ * Get network configuration (supports preset and custom networks)
+ */
+declare function getNetworkConfig(network: string): NetworkConfig;
+/**
+ * Get token configuration (supports preset and custom tokens)
+ */
+declare function getTokenConfig(token: string, network: string): TokenConfig | null;
+/**
+ * Get chain ID for network
+ */
+declare function getChainId(network: string): number;
+/**
+ * Get all available networks (preset + custom)
+ */
+declare function getAvailableNetworks(): string[];
+/**
+ * Get networks by environment
+ */
+declare function getNetworksByEnvironment(env: NetworkEnvironment): string[];
+
+/**
+ * Type definitions for x402 client SDK
+ */
+
+/** Payment request from HTTP 402 response */
+interface PaymentRequest {
+    amount: string;
+    token: string;
+    network: string;
+    chainId?: number;
+    recipient: string;
+}
+/** Payment response after successful payment */
+interface PaymentResponse {
+    transactionHash: string;
+    timestamp?: string;
+}
+/** x402 Client options */
+interface X402ClientOptions {
+    /** Wallet provider (MetaMask, WalletConnect, etc.) */
+    walletProvider?: WalletProvider;
+    /** Use testnet (mantle-sepolia) */
+    testnet?: boolean;
+    /** Network identifier (e.g., 'mantle', 'mantle-sepolia') */
+    network?: string;
+    /** Custom network configuration */
+    customNetwork?: CustomNetworkConfig;
+    /** Custom token configurations */
+    customTokens?: CustomTokenConfig;
+    /** Custom payment modal handler */
+    paymentModal?: (request: PaymentRequest) => Promise<PaymentResponse | null>;
+    /** Auto-retry after payment (default: true) */
+    autoRetry?: boolean;
+    /** Auto-switch network if needed (default: true) */
+    autoSwitchNetwork?: boolean;
+}
+/** EIP-1193 provider request arguments */
+interface EIP1193RequestArgs {
+    method: string;
+    params?: readonly unknown[] | object;
+}
+/** EIP-1193 compatible provider */
+interface EIP1193Provider {
+    request(args: EIP1193RequestArgs): Promise<unknown>;
+    on?(event: string, listener: (...args: unknown[]) => void): void;
+    removeListener?(event: string, listener: (...args: unknown[]) => void): void;
+    isMetaMask?: boolean;
+}
+/** Network parameters for wallet_addEthereumChain */
+interface AddEthereumChainParameter {
+    chainId: string;
+    chainName: string;
+    nativeCurrency: {
+        name: string;
+        symbol: string;
+        decimals: number;
+    };
+    rpcUrls: string[];
+    blockExplorerUrls?: string[];
+}
+/** Wallet provider interface */
+interface WalletProvider {
+    /** Check if wallet is available */
+    isAvailable(): boolean;
+    /** Connect wallet and return address */
+    connect(): Promise<string>;
+    /** Get current account */
+    getAccount(): Promise<string | null>;
+    /** Get current chain ID */
+    getChainId(): Promise<number | null>;
+    /** Switch network */
+    switchNetwork(chainId: number): Promise<void>;
+    /** Add and switch to network */
+    addNetwork(params: AddEthereumChainParameter): Promise<void>;
+    /** Send transaction */
+    sendTransaction(tx: TransactionRequest): Promise<string>;
+    /** Sign message (optional) */
+    signMessage?(message: string): Promise<string>;
+}
+/** Transaction request */
+interface TransactionRequest {
+    to: string;
+    value?: string;
+    data?: string;
+    gasLimit?: string;
+    gasPrice?: string;
+}
+
+/**
+ * x402 Client
+ *
+ * Main client that intercepts HTTP 402 responses and handles payment flow
+ */
+
+/**
+ * x402 Client class
+ *
+ * Provides automatic HTTP 402 handling for fetch requests
+ */
+declare class X402Client {
+    private options;
+    private wallet;
+    constructor(options?: X402ClientOptions);
+    /**
+     * Initialize wallet connection
+     */
+    initialize(): Promise<void>;
+    /**
+     * Fetch with automatic 402 handling
+     */
+    fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+}
+/**
+ * Create x402 client instance
+ */
+declare function x402Client(options?: X402ClientOptions): X402Client;
+/**
+ * Enhanced fetch with automatic 402 handling
+ *
+ * @example
+ * ```typescript
+ * const response = await x402Fetch('https://api.example.com/data')
+ * ```
+ */
+declare function x402Fetch(input: RequestInfo | URL, init?: RequestInit, options?: X402ClientOptions): Promise<Response>;
+
+/**
+ * Payment Modal
+ *
+ * Default payment modal implementation using vanilla JS
+ */
+
+/**
+ * Create payment modal
+ *
+ * Uses vanilla JS modal that works in any browser environment
+ */
+declare function createPaymentModal(request: PaymentRequest): Promise<PaymentResponse | null>;
+
+/**
+ * Vanilla JS Payment Modal
+ *
+ * Creates a payment modal using vanilla JS/DOM
+ */
+
+/**
+ * Create vanilla JS payment modal
+ */
+declare function createVanillaPaymentModal(request: PaymentRequest): Promise<PaymentResponse | null>;
+
+/**
+ * Wallet Connection & Management
+ *
+ * Handles web3 wallet connections (MetaMask, WalletConnect, etc.)
+ * Supports network switching and custom network addition
+ */
+
+/**
+ * MetaMask/EIP-1193 wallet provider
+ */
+declare class MetaMaskProvider implements WalletProvider {
+    private ethereum;
+    constructor();
+    isAvailable(): boolean;
+    connect(): Promise<string>;
+    getAccount(): Promise<string | null>;
+    getChainId(): Promise<number | null>;
+    switchNetwork(chainId: number): Promise<void>;
+    addNetwork(params: AddEthereumChainParameter): Promise<void>;
+    sendTransaction(tx: TransactionRequest): Promise<string>;
+    signMessage(message: string): Promise<string>;
+}
+/**
+ * Auto-detect wallet provider
+ */
+declare function detectWalletProvider(): WalletProvider | null;
+/**
+ * Connect wallet (auto-detect or use provided)
+ */
+declare function connectWallet(provider?: WalletProvider): Promise<string>;
+/**
+ * Ensure wallet is on the correct network
+ *
+ * @param wallet - Wallet provider
+ * @param network - Network identifier (e.g., 'mantle', 'mantle-sepolia')
+ * @param autoAdd - Auto-add network if not found (default: true)
+ */
+declare function ensureNetwork(wallet: WalletProvider, network: string, autoAdd?: boolean): Promise<void>;
+/**
+ * Get network config for adding to wallet
+ */
+declare function getAddNetworkParams(network: string): AddEthereumChainParameter;
+
+/**
+ * Payment Processing
+ *
+ * Handles direct blockchain payments with automatic fee splitting
+ * Automatically splits 0.5% platform fee to Treasury
+ */
+
+/**
+ * Process payment for an x402 request
+ *
+ * Automatically splits payment:
+ * - 99.5% to merchant
+ * - 0.5% to Treasury
+ *
+ * @param request - Payment request from HTTP 402 response
+ * @param wallet - Wallet provider to use for transaction
+ * @returns Payment response with transaction hash
+ */
+declare function processPayment(request: PaymentRequest, wallet: WalletProvider): Promise<PaymentResponse>;
+
+export { type AddEthereumChainParameter, type CustomNetworkConfig, type CustomTokenConfig, type EIP1193Provider, MetaMaskProvider, NETWORKS, type NetworkConfig, type NetworkEnvironment, type NetworkId, PLATFORM_FEE_BPS, type PaymentRequest, type PaymentResponse, TOKENS, TREASURY_ADDRESS, TREASURY_ADMIN, type TokenConfig, type TransactionRequest, type WalletProvider, X402Client, type X402ClientOptions, connectWallet, createPaymentModal, createVanillaPaymentModal, detectWalletProvider, ensureNetwork, getAddNetworkParams, getAvailableNetworks, getChainId, getNetworkConfig, getNetworksByEnvironment, getTokenConfig, isMainnet, isTestnet, processPayment, registerCustomNetwork, registerCustomTokens, x402Client, x402Fetch };