@voyage_ai/v402-web-ts 0.1.0

package/README.md

@@ -0,0 +1 @@
+# v402-web-ts

package/dist/index.d.mts

@@ -0,0 +1,523 @@
+import { PaymentRequirements } from 'x402/types';
+export { ExactEvmPayload, ExactSvmPayload, PaymentRequirements, SPLTokenAmount, SettleResponse, VerifyResponse, x402Response } from 'x402/types';
+import { VersionedTransaction } from '@solana/web3.js';
+import { z } from 'zod';
+
+/**
+ * Common types for x402 SDK
+ * Framework-agnostic types that work across different wallet implementations
+ */
+
+/**
+ * Generic wallet adapter interface - works with any wallet provider
+ * Compatible with Anza wallet-adapter, Privy, and custom implementations
+ */
+interface WalletAdapter {
+    publicKey?: {
+        toString(): string;
+    };
+    address?: string;
+    signTransaction: (tx: VersionedTransaction) => Promise<VersionedTransaction>;
+}
+/**
+ * EVM wallet adapter interface
+ */
+interface EvmWalletAdapter {
+    address: string;
+    signTypedData: (domain: any, types: any, message: any) => Promise<string>;
+    switchChain?: (chainId: string) => Promise<void>;
+}
+/**
+ * Network type enum - for wallet detection
+ */
+declare enum NetworkType {
+    EVM = "evm",
+    SOLANA = "solana",
+    SVM = "svm",// Alias for Solana
+    UNKNOWN = "unknown"
+}
+
+/**
+ * SVM (Solana) specific types
+ * Uses x402 official types as base
+ */
+
+/**
+ * Solana network enum
+ */
+declare const SolanaNetworkSchema: z.ZodEnum<["solana-devnet", "solana", "solana-mainnet"]>;
+type SolanaNetwork = z.infer<typeof SolanaNetworkSchema>;
+/**
+ * Solana payment payload schema (conforms to x402 spec)
+ */
+declare const SolanaPaymentPayloadSchema: z.ZodObject<{
+    x402Version: z.ZodLiteral<1>;
+    scheme: z.ZodLiteral<"exact">;
+    network: z.ZodEnum<["solana-devnet", "solana", "solana-mainnet"]>;
+    payload: z.ZodObject<{
+        transaction: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        transaction: string;
+    }, {
+        transaction: string;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    x402Version: 1;
+    scheme: "exact";
+    network: "solana" | "solana-devnet" | "solana-mainnet";
+    payload: {
+        transaction: string;
+    };
+}, {
+    x402Version: 1;
+    scheme: "exact";
+    network: "solana" | "solana-devnet" | "solana-mainnet";
+    payload: {
+        transaction: string;
+    };
+}>;
+type SolanaPaymentPayload = z.infer<typeof SolanaPaymentPayloadSchema>;
+/**
+ * Configuration for Solana payment client
+ */
+interface SvmClientConfig {
+    wallet: WalletAdapter;
+    network: SolanaNetwork;
+    rpcUrl?: string;
+    maxPaymentAmount?: bigint;
+}
+/**
+ * Configuration for creating Solana payment header
+ */
+interface CreateSvmPaymentHeaderParams {
+    wallet: WalletAdapter;
+    paymentRequirements: PaymentRequirements;
+    x402Version: number;
+    rpcUrl: string;
+}
+
+/**
+ * EVM specific types
+ * Uses x402 official types as base
+ */
+
+/**
+ * EVM network enum (common networks)
+ */
+declare const EvmNetworkSchema: z.ZodEnum<["ethereum", "sepolia", "base", "base-sepolia", "polygon", "arbitrum", "optimism"]>;
+type EvmNetwork = z.infer<typeof EvmNetworkSchema>;
+/**
+ * EVM payment payload schema (conforms to x402 spec)
+ */
+declare const EvmPaymentPayloadSchema: z.ZodObject<{
+    x402Version: z.ZodLiteral<1>;
+    scheme: z.ZodLiteral<"exact">;
+    network: z.ZodEnum<["ethereum", "sepolia", "base", "base-sepolia", "polygon", "arbitrum", "optimism"]>;
+    payload: z.ZodObject<{
+        signature: z.ZodString;
+        authorization: z.ZodObject<{
+            from: z.ZodString;
+            to: z.ZodString;
+            value: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
+            validAfter: z.ZodEffects<z.ZodString, string, string>;
+            validBefore: z.ZodEffects<z.ZodString, string, string>;
+            nonce: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            from: string;
+            to: string;
+            value: string;
+            validAfter: string;
+            validBefore: string;
+            nonce: string;
+        }, {
+            from: string;
+            to: string;
+            value: string;
+            validAfter: string;
+            validBefore: string;
+            nonce: string;
+        }>;
+    }, "strip", z.ZodTypeAny, {
+        signature: string;
+        authorization: {
+            from: string;
+            to: string;
+            value: string;
+            validAfter: string;
+            validBefore: string;
+            nonce: string;
+        };
+    }, {
+        signature: string;
+        authorization: {
+            from: string;
+            to: string;
+            value: string;
+            validAfter: string;
+            validBefore: string;
+            nonce: string;
+        };
+    }>;
+}, "strip", z.ZodTypeAny, {
+    x402Version: 1;
+    scheme: "exact";
+    network: "ethereum" | "sepolia" | "base" | "base-sepolia" | "polygon" | "arbitrum" | "optimism";
+    payload: {
+        signature: string;
+        authorization: {
+            from: string;
+            to: string;
+            value: string;
+            validAfter: string;
+            validBefore: string;
+            nonce: string;
+        };
+    };
+}, {
+    x402Version: 1;
+    scheme: "exact";
+    network: "ethereum" | "sepolia" | "base" | "base-sepolia" | "polygon" | "arbitrum" | "optimism";
+    payload: {
+        signature: string;
+        authorization: {
+            from: string;
+            to: string;
+            value: string;
+            validAfter: string;
+            validBefore: string;
+            nonce: string;
+        };
+    };
+}>;
+type EvmPaymentPayload = z.infer<typeof EvmPaymentPayloadSchema>;
+/**
+ * Configuration for EVM payment client
+ */
+interface EvmClientConfig {
+    wallet: EvmWalletAdapter;
+    network: EvmNetwork;
+    maxPaymentAmount?: bigint;
+}
+/**
+ * Configuration for creating EVM payment header
+ */
+interface CreateEvmPaymentHeaderParams {
+    wallet: EvmWalletAdapter;
+    paymentRequirements: PaymentRequirements;
+    x402Version: number;
+    chainId: number;
+}
+/**
+ * Network configuration for EVM chains
+ */
+interface EvmNetworkConfig {
+    chainId: string;
+    chainName: string;
+    rpcUrls: string[];
+    nativeCurrency: {
+        name: string;
+        symbol: string;
+        decimals: number;
+    };
+}
+/**
+ * Common EVM network configurations
+ */
+declare const EVM_NETWORK_CONFIGS: Record<string, EvmNetworkConfig>;
+/**
+ * Get chain ID from network name
+ */
+declare function getChainId(network: string): number;
+
+/**
+ * SVM (Solana) Payment Header Builder
+ *
+ * Low-level API: Creates X-PAYMENT header for Solana transactions
+ * Use this when you want to build the payment header yourself and handle fetch separately
+ */
+
+/**
+ * Create X-PAYMENT header for Solana payment
+ *
+ * @param params - Payment header parameters
+ * @returns Base64-encoded X-PAYMENT header string
+ *
+ * @example
+ * ```typescript
+ * const paymentHeader = await createSvmPaymentHeader({
+ *   wallet: phantomWallet,
+ *   paymentRequirements: requirements,
+ *   x402Version: 1,
+ *   rpcUrl: "https://api.devnet.solana.com"
+ * });
+ *
+ * // Use the header in your own fetch
+ * const response = await fetch(endpoint, {
+ *   headers: {
+ *     "X-PAYMENT": paymentHeader
+ *   }
+ * });
+ * ```
+ */
+declare function createSvmPaymentHeader(params: CreateSvmPaymentHeaderParams): Promise<string>;
+/**
+ * Helper: Get default RPC URL for Solana network
+ */
+declare function getDefaultSolanaRpcUrl(network: string): string;
+
+/**
+ * SVM (Solana) Payment Handler
+ *
+ * High-level API: Automatically handles the full payment flow
+ * Use this for the simplest integration - just provide wallet and endpoint
+ */
+
+/**
+ * Handle SVM payment with automatic x402 flow
+ *
+ * @param endpoint - API endpoint that requires x402 payment
+ * @param config - SVM client configuration
+ * @param requestInit - Optional fetch RequestInit options
+ * @returns Response from the endpoint after successful payment
+ *
+ * @example
+ * ```typescript
+ * // Simple usage with Phantom wallet
+ * const response = await handleSvmPayment(
+ *   "https://api.example.com/protected",
+ *   {
+ *     wallet: window.solana,
+ *     network: "solana-devnet"
+ *   }
+ * );
+ * const data = await response.json();
+ * ```
+ */
+declare function handleSvmPayment(endpoint: string, config: SvmClientConfig, requestInit?: RequestInit): Promise<Response>;
+/**
+ * Create a custom fetch function that automatically handles x402 payments for SVM
+ *
+ * @example
+ * ```typescript
+ * const paymentFetch = createSvmPaymentFetch({
+ *   wallet: window.solana,
+ *   network: "solana-devnet",
+ *   maxPaymentAmount: BigInt(1_000_000) // 1 USDC max
+ * });
+ *
+ * // Use like regular fetch
+ * const response = await paymentFetch("https://api.example.com/protected");
+ * ```
+ */
+declare function createSvmPaymentFetch(config: SvmClientConfig): typeof fetch;
+
+/**
+ * EVM Payment Header Builder
+ *
+ * Low-level API: Creates X-PAYMENT header for EVM transactions
+ * Use this when you want to build the payment header yourself and handle fetch separately
+ */
+
+/**
+ * Create X-PAYMENT header for EVM payment (EIP-3009 format)
+ *
+ * @param params - Payment header parameters
+ * @returns Base64-encoded X-PAYMENT header string
+ *
+ * @example
+ * ```typescript
+ * const paymentHeader = await createEvmPaymentHeader({
+ *   wallet: metamaskWallet,
+ *   paymentRequirements: requirements,
+ *   x402Version: 1,
+ *   chainId: 84532
+ * });
+ *
+ * // Use the header in your own fetch
+ * const response = await fetch(endpoint, {
+ *   headers: {
+ *     "X-PAYMENT": paymentHeader
+ *   }
+ * });
+ * ```
+ */
+declare function createEvmPaymentHeader(params: CreateEvmPaymentHeaderParams): Promise<string>;
+/**
+ * Get chain ID from network name
+ */
+declare function getChainIdFromNetwork(network: string): number;
+
+/**
+ * EVM Payment Handler
+ *
+ * High-level API: Automatically handles the full payment flow
+ * Use this for the simplest integration - just provide wallet and endpoint
+ */
+
+/**
+ * Handle EVM payment with automatic x402 flow
+ *
+ * @param endpoint - API endpoint that requires x402 payment
+ * @param config - EVM client configuration
+ * @param requestInit - Optional fetch RequestInit options
+ * @returns Response from the endpoint after successful payment
+ *
+ * @example
+ * ```typescript
+ * // Simple usage with MetaMask
+ * const provider = new ethers.BrowserProvider(window.ethereum);
+ * const signer = await provider.getSigner();
+ *
+ * const response = await handleEvmPayment(
+ *   "https://api.example.com/protected",
+ *   {
+ *     wallet: {
+ *       address: await signer.getAddress(),
+ *       signTypedData: (domain, types, message) =>
+ *         signer.signTypedData(domain, types, message)
+ *     },
+ *     network: "base-sepolia"
+ *   }
+ * );
+ * ```
+ */
+declare function handleEvmPayment(endpoint: string, config: EvmClientConfig, requestInit?: RequestInit): Promise<Response>;
+/**
+ * Create a custom fetch function that automatically handles x402 payments for EVM
+ *
+ * @example
+ * ```typescript
+ * const paymentFetch = createEvmPaymentFetch({
+ *   wallet: myWallet,
+ *   network: "base-sepolia",
+ *   maxPaymentAmount: BigInt(1_000_000) // 1 USDC max
+ * });
+ *
+ * // Use like regular fetch
+ * const response = await paymentFetch("https://api.example.com/protected");
+ * ```
+ */
+declare function createEvmPaymentFetch(config: EvmClientConfig): typeof fetch;
+
+/**
+ * Wallet utilities
+ *
+ * Generic wallet connection and management utilities
+ * Framework-agnostic and chain-agnostic
+ */
+
+/**
+ * Check if a wallet is installed for a specific network type
+ */
+declare function isWalletInstalled(networkType: NetworkType): boolean;
+/**
+ * Get wallet provider for a network type
+ */
+declare function getWalletProvider(networkType: NetworkType): any;
+/**
+ * Format wallet address for display (show first 6 and last 4 characters)
+ */
+declare function formatAddress(address: string): string;
+/**
+ * Get wallet install URL
+ */
+declare function getWalletInstallUrl(networkType: NetworkType): string;
+/**
+ * Get wallet display name
+ */
+declare function getWalletDisplayName(networkType: NetworkType): string;
+
+/**
+ * Payment helper utilities for demo/UI
+ * Simplified payment handling with callbacks
+ */
+
+/**
+ * Make payment with automatic chain handling
+ *
+ * This function handles all the chain-specific logic internally.
+ * Business logic should be handled via callbacks.
+ *
+ * @param endpoint - API endpoint
+ * @param networkType - Network type (from useWallet)
+ * @param merchantId - @see our website to apply
+ * @returns Response from the payment
+ *
+ * @example
+ * ```tsx
+ * const response = await makePayment('/api/endpoint', networkType);
+ * const data = await response.json();
+ * ```
+ */
+declare function makePayment(networkType: NetworkType, merchantId: string, endpoint?: string): Promise<Response>;
+
+/**
+ * Network utilities
+ *
+ * Helper functions for network detection and validation
+ */
+
+/**
+ * Get network type from network name
+ */
+declare function getNetworkType(network: string): NetworkType;
+/**
+ * Check if network is EVM-based
+ */
+declare function isEvmNetwork(network: string): boolean;
+/**
+ * Check if network is Solana-based
+ */
+declare function isSolanaNetwork(network: string): boolean;
+/**
+ * Validate Solana address format (base58)
+ */
+declare function isSolanaAddress(address: string): boolean;
+/**
+ * Validate EVM address format (0x-prefixed hex)
+ */
+declare function isEvmAddress(address: string): boolean;
+/**
+ * Get network display name
+ */
+declare function getNetworkDisplayName(network: string): string;
+
+/**
+ * General helper utilities
+ *
+ * Miscellaneous helper functions for the SDK
+ */
+/**
+ * Convert human-readable amount to atomic units (smallest unit)
+ *
+ * @param amount - Human-readable amount (e.g., 2.5 for 2.5 USDC)
+ * @param decimals - Token decimals (e.g., 6 for USDC, 18 for ETH)
+ * @returns Amount in atomic units as bigint
+ *
+ * @example
+ * ```typescript
+ * // 2.5 USDC (6 decimals) = 2,500,000 micro-USDC
+ * const atomicUnits = toAtomicUnits(2.5, 6); // 2500000n
+ * ```
+ */
+declare function toAtomicUnits(amount: number, decimals: number): bigint;
+/**
+ * Convert atomic units to human-readable amount
+ *
+ * @param atomicUnits - Token amount in smallest units
+ * @param decimals - Token decimals (e.g., 6 for USDC, 18 for ETH)
+ * @returns Human-readable amount as number
+ *
+ * @example
+ * ```typescript
+ * // 2,500,000 micro-USDC = 2.5 USDC
+ * const amount = fromAtomicUnits(2500000n, 6); // 2.5
+ * ```
+ */
+declare function fromAtomicUnits(atomicUnits: bigint | number, decimals: number): number;
+/**
+ * Parse x402Response to check if it's a 402 payment required
+ */
+declare function is402Response(response: any): boolean;
+
+export { type CreateEvmPaymentHeaderParams, type CreateSvmPaymentHeaderParams, EVM_NETWORK_CONFIGS, type EvmClientConfig, type EvmNetwork, type EvmNetworkConfig, EvmNetworkSchema, type EvmPaymentPayload, EvmPaymentPayloadSchema, type EvmWalletAdapter, NetworkType, type SolanaNetwork, SolanaNetworkSchema, type SolanaPaymentPayload, SolanaPaymentPayloadSchema, type SvmClientConfig, type WalletAdapter, createEvmPaymentFetch, createEvmPaymentHeader, createSvmPaymentFetch, createSvmPaymentHeader, formatAddress, fromAtomicUnits, getChainId, getChainIdFromNetwork, getDefaultSolanaRpcUrl, getNetworkDisplayName, getNetworkType, getWalletDisplayName, getWalletInstallUrl, getWalletProvider, handleEvmPayment, handleSvmPayment, is402Response, isEvmAddress, isEvmNetwork, isSolanaAddress, isSolanaNetwork, isWalletInstalled, makePayment, toAtomicUnits };