uvd-x402-sdk 2.0.1

package/dist/index-D6Sr4ARD.d.ts

@@ -0,0 +1,429 @@
+/**
+ * uvd-x402-sdk - Type Definitions
+ *
+ * Core TypeScript interfaces for the x402 payment SDK.
+ * These types define the contract between the SDK and consuming applications.
+ */
+/**
+ * Network type categorization
+ * - 'evm': Ethereum Virtual Machine compatible chains (use EIP-712)
+ * - 'svm': Solana Virtual Machine chains (Solana, Fogo) (use SPL tokens)
+ * - 'stellar': Stellar network (use Soroban)
+ * - 'near': NEAR Protocol (use NEP-366)
+ *
+ * @deprecated 'solana' type is deprecated, use 'svm' instead
+ */
+type NetworkType = 'evm' | 'svm' | 'solana' | 'stellar' | 'near';
+/**
+ * USDC token configuration for a specific chain
+ */
+interface USDCConfig {
+    /** Contract/mint address */
+    address: string;
+    /** Token decimals (6 for most chains, 7 for Stellar, 18 for BSC) */
+    decimals: number;
+    /** Token name for EIP-712 domain (e.g., "USD Coin" or "USDC") */
+    name: string;
+    /** Token version for EIP-712 domain */
+    version: string;
+}
+/**
+ * Native currency configuration
+ */
+interface NativeCurrency {
+    name: string;
+    symbol: string;
+    decimals: number;
+}
+/**
+ * Complete chain configuration
+ */
+interface ChainConfig {
+    /** Numeric chain ID (0 for non-EVM chains) */
+    chainId: number;
+    /** Hex-encoded chain ID for wallet_switchEthereumChain */
+    chainIdHex: string;
+    /** Internal chain identifier (e.g., 'base', 'solana') */
+    name: string;
+    /** Human-readable display name */
+    displayName: string;
+    /** Network type for routing */
+    networkType: NetworkType;
+    /** Primary RPC endpoint URL */
+    rpcUrl: string;
+    /** Block explorer base URL */
+    explorerUrl: string;
+    /** Native currency info */
+    nativeCurrency: NativeCurrency;
+    /** USDC token configuration */
+    usdc: USDCConfig;
+    /** x402 facilitator configuration */
+    x402: {
+        facilitatorUrl: string;
+        enabled: boolean;
+    };
+}
+/**
+ * Current wallet connection state
+ */
+interface WalletState {
+    /** Whether a wallet is currently connected */
+    connected: boolean;
+    /** Connected wallet address (null if not connected) */
+    address: string | null;
+    /** Current chain ID (null for non-EVM or disconnected) */
+    chainId: number | null;
+    /** Current network name */
+    network: string | null;
+    /** Network type of connected wallet */
+    networkType: NetworkType | null;
+    /** USDC balance on current chain (null if unknown) */
+    balance: string | null;
+}
+/**
+ * Wallet adapter interface for different wallet types
+ */
+interface WalletAdapter {
+    /** Unique identifier for this wallet type */
+    readonly id: string;
+    /** Display name */
+    readonly name: string;
+    /** Network type this adapter supports */
+    readonly networkType: NetworkType;
+    /** Check if this wallet is available/installed */
+    isAvailable(): boolean;
+    /** Connect to the wallet */
+    connect(chainName?: string): Promise<string>;
+    /** Disconnect from the wallet */
+    disconnect(): Promise<void>;
+    /** Switch to a different chain (EVM only) */
+    switchChain?(chainName: string): Promise<void>;
+    /** Sign a payment payload */
+    signPayment(paymentInfo: PaymentInfo, chainConfig: ChainConfig): Promise<string>;
+    /** Check USDC balance */
+    getBalance(chainConfig: ChainConfig): Promise<string>;
+    /** Get current address */
+    getAddress(): string | null;
+    /** Get current chain ID (EVM only) */
+    getChainId?(): number | null;
+}
+/**
+ * EIP-712 domain for typed data signing
+ */
+interface EIP712Domain {
+    name: string;
+    version: string;
+    chainId: number;
+    verifyingContract: string;
+}
+/**
+ * EIP-712 type definitions
+ */
+interface EIP712Types {
+    [typeName: string]: Array<{
+        name: string;
+        type: string;
+    }>;
+}
+/**
+ * Payment information returned by backend on 402 response
+ */
+interface PaymentInfo {
+    /** Default recipient address */
+    recipient: string;
+    /** Network-specific recipient addresses */
+    recipients?: {
+        evm?: string;
+        solana?: string;
+        near?: string;
+        stellar?: string;
+    };
+    /** Facilitator address (for Solana fee payer) */
+    facilitator?: string;
+    /** Amount in USD (e.g., "10.00") */
+    amount: string;
+    /** Token symbol (usually "USDC") */
+    token?: string;
+    /** Network hint from backend */
+    network?: string;
+    /** Supported chain IDs */
+    supportedChains?: number[];
+}
+/**
+ * Simple payment request from application
+ */
+interface PaymentRequest {
+    /** Amount in USDC (e.g., "10.00") */
+    amount: string;
+    /** Override recipient address (optional) */
+    recipient?: string;
+    /** Application-specific metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Result of a payment operation
+ */
+interface PaymentResult {
+    /** Whether payment was successful */
+    success: boolean;
+    /** Base64-encoded X-PAYMENT header value */
+    paymentHeader: string;
+    /** Transaction hash (if available) */
+    transactionHash?: string;
+    /** Network where payment was made */
+    network: string;
+    /** Payer address */
+    payer?: string;
+    /** Error message (if success is false) */
+    error?: string;
+}
+/**
+ * EVM payment payload (ERC-3009 TransferWithAuthorization)
+ */
+interface EVMPaymentPayload {
+    from: string;
+    to: string;
+    value: string;
+    validAfter: number;
+    validBefore: number;
+    nonce: string;
+    v: number;
+    r: string;
+    s: string;
+    chainId: number;
+    token: string;
+}
+/**
+ * Solana payment payload (partially-signed transaction)
+ */
+interface SolanaPaymentPayload {
+    /** Base64-encoded serialized transaction */
+    transaction: string;
+}
+/**
+ * Stellar payment payload (Soroban authorization)
+ */
+interface StellarPaymentPayload {
+    /** Sender G... public key */
+    from: string;
+    /** Recipient G... public key */
+    to: string;
+    /** Amount in stroops (7 decimals) */
+    amount: string;
+    /** USDC SAC contract address */
+    tokenContract: string;
+    /** Base64 XDR-encoded SorobanAuthorizationEntry */
+    authorizationEntryXdr: string;
+    /** Random 64-bit nonce */
+    nonce: number;
+    /** Ledger when authorization expires */
+    signatureExpirationLedger: number;
+}
+/**
+ * NEAR payment payload (NEP-366 meta-transaction)
+ */
+interface NEARPaymentPayload {
+    /** Base64 Borsh-encoded SignedDelegateAction */
+    signedDelegateAction: string;
+    network: 'near';
+}
+/**
+ * Union type for all payment payloads
+ */
+type PaymentPayload = EVMPaymentPayload | SolanaPaymentPayload | StellarPaymentPayload | NEARPaymentPayload;
+/**
+ * x402 protocol version
+ */
+type X402Version = 1 | 2;
+/**
+ * CAIP-2 chain identifiers for x402 v2
+ * @see https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-2.md
+ */
+declare const CAIP2_IDENTIFIERS: Record<string, string>;
+/**
+ * Reverse mapping from CAIP-2 to chain name
+ */
+declare const CAIP2_TO_CHAIN: Record<string, string>;
+/**
+ * x402 v1 header structure (network as string)
+ */
+interface X402HeaderV1 {
+    x402Version: 1;
+    scheme: 'exact';
+    network: string;
+    payload: X402PayloadData;
+}
+/**
+ * x402 v2 payment option
+ */
+interface X402PaymentOption {
+    network: string;
+    asset: string;
+    amount: string;
+    facilitator?: string;
+}
+/**
+ * x402 v2 header structure (CAIP-2 network, accepts array)
+ */
+interface X402HeaderV2 {
+    x402Version: 2;
+    scheme: 'exact';
+    network: string;
+    payload: X402PayloadData;
+    accepts?: X402PaymentOption[];
+}
+/**
+ * Union type for both v1 and v2 headers
+ */
+type X402Header = X402HeaderV1 | X402HeaderV2;
+/**
+ * EVM-specific payload in x402 header
+ */
+interface X402EVMPayload {
+    signature: string;
+    authorization: {
+        from: string;
+        to: string;
+        value: string;
+        validAfter: string;
+        validBefore: string;
+        nonce: string;
+    };
+}
+/**
+ * Solana-specific payload in x402 header
+ */
+interface X402SolanaPayload {
+    transaction: string;
+}
+/**
+ * Stellar-specific payload in x402 header
+ */
+interface X402StellarPayload {
+    from: string;
+    to: string;
+    amount: string;
+    tokenContract: string;
+    authorizationEntryXdr: string;
+    nonce: number;
+    signatureExpirationLedger: number;
+}
+/**
+ * NEAR-specific payload in x402 header
+ */
+interface X402NEARPayload {
+    signedDelegateAction: string;
+}
+/**
+ * Union of all x402 payload types
+ */
+type X402PayloadData = X402EVMPayload | X402SolanaPayload | X402StellarPayload | X402NEARPayload;
+/**
+ * Multi-payment configuration for supporting multiple networks
+ */
+interface MultiPaymentConfig {
+    /** Networks to support (e.g., ['base', 'solana', 'stellar', 'near']) */
+    networks: string[];
+    /** Default network if user hasn't selected one */
+    defaultNetwork?: string;
+    /** Whether to auto-detect user's preferred network based on wallet */
+    autoDetect?: boolean;
+}
+/**
+ * SDK client configuration options
+ */
+interface X402ClientConfig {
+    /** Facilitator URL (default: https://facilitator.ultravioletadao.xyz) */
+    facilitatorUrl?: string;
+    /** Default chain to connect to */
+    defaultChain?: string;
+    /** Auto-connect on initialization */
+    autoConnect?: boolean;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Custom chain configurations (override defaults) */
+    customChains?: Record<string, Partial<ChainConfig>>;
+    /** Wallet preference order */
+    walletPreference?: string[];
+    /** Custom RPC URLs (override defaults) */
+    rpcOverrides?: Record<string, string>;
+    /**
+     * x402 protocol version to use
+     * - 1: Classic format with network as string (e.g., "base")
+     * - 2: CAIP-2 format with accepts array (e.g., "eip155:8453")
+     * - 'auto': Auto-detect from 402 response (default)
+     */
+    x402Version?: X402Version | 'auto';
+    /** Multi-payment configuration for supporting multiple networks */
+    multiPayment?: MultiPaymentConfig;
+}
+/**
+ * Default configuration values
+ */
+declare const DEFAULT_CONFIG: Required<Pick<X402ClientConfig, 'facilitatorUrl' | 'defaultChain' | 'autoConnect' | 'debug' | 'x402Version'>>;
+/**
+ * Balance information for a single network
+ */
+interface NetworkBalance {
+    /** Chain name */
+    chainName: string;
+    /** Human-readable display name */
+    displayName: string;
+    /** Formatted balance (e.g., "15.50") or null if loading/error */
+    balance: string | null;
+    /** Whether balance is currently being fetched */
+    isLoading: boolean;
+    /** Error message if fetch failed */
+    error: string | null;
+}
+/**
+ * Events emitted by the SDK client
+ */
+type X402Event = 'connect' | 'disconnect' | 'chainChanged' | 'accountChanged' | 'balanceChanged' | 'paymentStarted' | 'paymentSigned' | 'paymentCompleted' | 'paymentFailed';
+/**
+ * Event data types
+ */
+interface X402EventData {
+    connect: WalletState;
+    disconnect: void;
+    chainChanged: {
+        chainId: number;
+        chainName: string;
+    };
+    accountChanged: {
+        address: string;
+    };
+    balanceChanged: {
+        balance: string;
+    };
+    paymentStarted: {
+        amount: string;
+        network: string;
+    };
+    paymentSigned: {
+        paymentHeader: string;
+    };
+    paymentCompleted: PaymentResult;
+    paymentFailed: {
+        error: string;
+        code: X402ErrorCode;
+    };
+}
+/**
+ * Event handler type
+ */
+type X402EventHandler<E extends X402Event> = (data: X402EventData[E]) => void;
+/**
+ * Error codes for categorizing errors
+ */
+type X402ErrorCode = 'WALLET_NOT_FOUND' | 'WALLET_NOT_CONNECTED' | 'WALLET_CONNECTION_REJECTED' | 'WALLET_CONNECTION_TIMEOUT' | 'CHAIN_NOT_SUPPORTED' | 'CHAIN_SWITCH_REJECTED' | 'INSUFFICIENT_BALANCE' | 'SIGNATURE_REJECTED' | 'PAYMENT_FAILED' | 'PAYMENT_TIMEOUT' | 'NETWORK_ERROR' | 'INVALID_CONFIG' | 'INVALID_AMOUNT' | 'INVALID_RECIPIENT' | 'UNKNOWN_ERROR';
+/**
+ * SDK-specific error class
+ */
+declare class X402Error extends Error {
+    readonly code: X402ErrorCode;
+    readonly details?: unknown;
+    constructor(message: string, code: X402ErrorCode, details?: unknown);
+}
+
+export { CAIP2_TO_CHAIN as A, type ChainConfig as C, DEFAULT_CONFIG as D, type EIP712Domain as E, type MultiPaymentConfig as M, type NativeCurrency as N, type PaymentInfo as P, type SolanaPaymentPayload as S, type USDCConfig as U, type WalletState as W, type X402Version as X, type NetworkType as a, type WalletAdapter as b, type EIP712Types as c, type PaymentRequest as d, type PaymentResult as e, type PaymentPayload as f, type EVMPaymentPayload as g, type StellarPaymentPayload as h, type NEARPaymentPayload as i, type X402Header as j, type X402HeaderV1 as k, type X402HeaderV2 as l, type X402PaymentOption as m, type X402PayloadData as n, type X402EVMPayload as o, type X402SolanaPayload as p, type X402StellarPayload as q, type X402NEARPayload as r, type X402ClientConfig as s, type NetworkBalance as t, type X402Event as u, type X402EventData as v, type X402EventHandler as w, type X402ErrorCode as x, X402Error as y, CAIP2_IDENTIFIERS as z };

package/dist/index-DJ4Cvrev.d.mts

@@ -0,0 +1,199 @@
+import { s as X402ClientConfig, P as PaymentInfo, e as PaymentResult, W as WalletState, C as ChainConfig, u as X402Event, w as X402EventHandler, a as NetworkType } from './index-D6Sr4ARD.mjs';
+
+/**
+ * uvd-x402-sdk - Main Client
+ *
+ * The X402Client is the primary entry point for the SDK.
+ * It manages wallet connections, chain switching, and payment creation.
+ */
+
+/**
+ * X402Client - Main SDK client for x402 payments
+ *
+ * @example
+ * ```ts
+ * import { X402Client } from 'uvd-x402-sdk';
+ *
+ * const client = new X402Client({ defaultChain: 'base' });
+ *
+ * // Connect wallet
+ * await client.connect('base');
+ *
+ * // Create payment
+ * const result = await client.createPayment({
+ *   recipient: '0x...',
+ *   amount: '10.00',
+ * });
+ *
+ * // Use result.paymentHeader in your API request
+ * ```
+ */
+declare class X402Client {
+    private readonly config;
+    private provider;
+    private signer;
+    private connectedAddress;
+    private currentChainId;
+    private currentNetwork;
+    private currentChainName;
+    private eventHandlers;
+    constructor(config?: X402ClientConfig);
+    /**
+     * Connect to a wallet on the specified chain
+     */
+    connect(chainName?: string): Promise<string>;
+    /**
+     * Disconnect the current wallet
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Switch to a different chain (EVM only)
+     */
+    switchChain(chainName: string): Promise<void>;
+    /**
+     * Create a payment authorization
+     *
+     * @param paymentInfo - Payment information from 402 response
+     * @returns Payment result with encoded X-PAYMENT header
+     */
+    createPayment(paymentInfo: PaymentInfo): Promise<PaymentResult>;
+    /**
+     * Check USDC balance on current chain
+     */
+    getBalance(): Promise<string>;
+    /**
+     * Get current wallet state
+     */
+    getState(): WalletState;
+    /**
+     * Get connected wallet address
+     */
+    getAddress(): string | null;
+    /**
+     * Get current chain ID
+     */
+    getChainId(): number | null;
+    /**
+     * Get current chain name
+     */
+    getChainName(): string | null;
+    /**
+     * Get current chain display name
+     */
+    getChainDisplayName(): string | null;
+    /**
+     * Check if wallet is connected
+     */
+    isConnected(): boolean;
+    /**
+     * Get list of enabled chains
+     */
+    getEnabledChains(): ChainConfig[];
+    /**
+     * Get chain config by name
+     */
+    getChain(name: string): ChainConfig | undefined;
+    /**
+     * Subscribe to an event
+     */
+    on<E extends X402Event>(event: E, handler: X402EventHandler<E>): () => void;
+    /**
+     * Unsubscribe from an event
+     */
+    off<E extends X402Event>(event: E, handler: X402EventHandler<E>): void;
+    private connectEVMWallet;
+    private switchEVMChain;
+    private setupEVMEventListeners;
+    private createEVMPayment;
+    private encodeEVMPaymentHeader;
+    private getEVMBalance;
+    private getRecipientForNetwork;
+    private emit;
+    private log;
+}
+declare global {
+    interface Window {
+        ethereum?: {
+            request: (args: {
+                method: string;
+                params?: unknown[];
+            }) => Promise<unknown>;
+            on?: (event: string, handler: (...args: unknown[]) => void) => void;
+            removeListener?: (event: string, handler: (...args: unknown[]) => void) => void;
+        };
+    }
+}
+
+/**
+ * uvd-x402-sdk - Chain Registry
+ *
+ * Complete configuration for all 15 supported blockchain networks.
+ * EVM chains (11): Use ERC-3009 TransferWithAuthorization
+ * SVM chains (2): Solana and Fogo - Use SPL tokens with partially-signed transactions
+ * Stellar (1): Uses Soroban authorization entries
+ * NEAR (1): Uses NEP-366 meta-transactions
+ */
+
+/**
+ * Default facilitator URL for x402 payments
+ */
+declare const DEFAULT_FACILITATOR_URL = "https://facilitator.ultravioletadao.xyz";
+/**
+ * All supported chains configuration
+ *
+ * To add a new chain:
+ * 1. Add chain config below with all required fields
+ * 2. Verify USDC contract supports ERC-3009 (transferWithAuthorization) for EVM chains
+ * 3. Test on testnet first before enabling
+ */
+declare const SUPPORTED_CHAINS: Record<string, ChainConfig>;
+/**
+ * Default chain for new users
+ */
+declare const DEFAULT_CHAIN = "base";
+/**
+ * Get chain config by chain ID
+ */
+declare function getChainById(chainId: number): ChainConfig | undefined;
+/**
+ * Get chain config by name (case-insensitive)
+ */
+declare function getChainByName(name: string): ChainConfig | undefined;
+/**
+ * Check if a chain is supported
+ */
+declare function isChainSupported(chainIdOrName: number | string): boolean;
+/**
+ * Get list of enabled chains
+ */
+declare function getEnabledChains(): ChainConfig[];
+/**
+ * Get list of chains by network type
+ */
+declare function getChainsByNetworkType(networkType: NetworkType): ChainConfig[];
+/**
+ * Get all EVM chain IDs (for wallet_switchEthereumChain)
+ */
+declare function getEVMChainIds(): number[];
+/**
+ * Get list of SVM chains (Solana, Fogo)
+ */
+declare function getSVMChains(): ChainConfig[];
+/**
+ * Check if a chain is SVM-based (Solana Virtual Machine)
+ */
+declare function isSVMChain(chainName: string): boolean;
+/**
+ * Get network type from chain name
+ */
+declare function getNetworkType(chainName: string): NetworkType | undefined;
+/**
+ * Format transaction URL for block explorer
+ */
+declare function getExplorerTxUrl(chainName: string, txHash: string): string | null;
+/**
+ * Format address URL for block explorer
+ */
+declare function getExplorerAddressUrl(chainName: string, address: string): string | null;
+
+export { DEFAULT_CHAIN as D, SUPPORTED_CHAINS as S, X402Client as X, DEFAULT_FACILITATOR_URL as a, getChainByName as b, getEnabledChains as c, getChainsByNetworkType as d, getEVMChainIds as e, getSVMChains as f, getChainById as g, isSVMChain as h, isChainSupported as i, getNetworkType as j, getExplorerTxUrl as k, getExplorerAddressUrl as l };

package/dist/index.d.mts

@@ -0,0 +1,3 @@
+export { D as DEFAULT_CHAIN, a as DEFAULT_FACILITATOR_URL, S as SUPPORTED_CHAINS, X as X402Client, g as getChainById, b as getChainByName, d as getChainsByNetworkType, e as getEVMChainIds, c as getEnabledChains, l as getExplorerAddressUrl, k as getExplorerTxUrl, j as getNetworkType, f as getSVMChains, i as isChainSupported, h as isSVMChain } from './index-DJ4Cvrev.mjs';
+export { caip2ToChain, chainToCAIP2, convertX402Header, createX402Header, createX402V1Header, createX402V2Header, decodeX402Header, detectX402Version, encodeX402Header, generatePaymentOptions, isCAIP2Format, parseNetworkIdentifier } from './utils/index.mjs';
+export { z as CAIP2_IDENTIFIERS, A as CAIP2_TO_CHAIN, C as ChainConfig, D as DEFAULT_CONFIG, E as EIP712Domain, c as EIP712Types, g as EVMPaymentPayload, M as MultiPaymentConfig, i as NEARPaymentPayload, N as NativeCurrency, t as NetworkBalance, a as NetworkType, P as PaymentInfo, f as PaymentPayload, d as PaymentRequest, e as PaymentResult, S as SolanaPaymentPayload, h as StellarPaymentPayload, U as USDCConfig, b as WalletAdapter, W as WalletState, s as X402ClientConfig, o as X402EVMPayload, y as X402Error, x as X402ErrorCode, u as X402Event, v as X402EventData, w as X402EventHandler, j as X402Header, k as X402HeaderV1, l as X402HeaderV2, r as X402NEARPayload, n as X402PayloadData, m as X402PaymentOption, p as X402SolanaPayload, q as X402StellarPayload, X as X402Version } from './index-D6Sr4ARD.mjs';

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { D as DEFAULT_CHAIN, a as DEFAULT_FACILITATOR_URL, S as SUPPORTED_CHAINS, X as X402Client, g as getChainById, b as getChainByName, d as getChainsByNetworkType, e as getEVMChainIds, c as getEnabledChains, l as getExplorerAddressUrl, k as getExplorerTxUrl, j as getNetworkType, f as getSVMChains, i as isChainSupported, h as isSVMChain } from './index-BrBqP1I8.js';
+export { caip2ToChain, chainToCAIP2, convertX402Header, createX402Header, createX402V1Header, createX402V2Header, decodeX402Header, detectX402Version, encodeX402Header, generatePaymentOptions, isCAIP2Format, parseNetworkIdentifier } from './utils/index.js';
+export { z as CAIP2_IDENTIFIERS, A as CAIP2_TO_CHAIN, C as ChainConfig, D as DEFAULT_CONFIG, E as EIP712Domain, c as EIP712Types, g as EVMPaymentPayload, M as MultiPaymentConfig, i as NEARPaymentPayload, N as NativeCurrency, t as NetworkBalance, a as NetworkType, P as PaymentInfo, f as PaymentPayload, d as PaymentRequest, e as PaymentResult, S as SolanaPaymentPayload, h as StellarPaymentPayload, U as USDCConfig, b as WalletAdapter, W as WalletState, s as X402ClientConfig, o as X402EVMPayload, y as X402Error, x as X402ErrorCode, u as X402Event, v as X402EventData, w as X402EventHandler, j as X402Header, k as X402HeaderV1, l as X402HeaderV2, r as X402NEARPayload, n as X402PayloadData, m as X402PaymentOption, p as X402SolanaPayload, q as X402StellarPayload, X as X402Version } from './index-D6Sr4ARD.js';