@perkos/middleware-x402 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,320 @@
+import { Address } from 'viem';
+
+/**
+ * x402 Core Types
+ * Type definitions for x402 v2 payment protocol
+ */
+
+/**
+ * Payment envelope containing authorization and signature
+ */
+interface PaymentEnvelope {
+    network: string;
+    authorization: {
+        from: string;
+        to: string;
+        value: string;
+        nonce: string;
+        validAfter?: string;
+        validBefore: string;
+    };
+    signature: string;
+}
+/**
+ * Payment requirements for a protected resource
+ */
+interface PaymentRequirements {
+    endpoint?: string;
+    method?: string;
+    price?: string;
+    network: string;
+    payTo: string;
+    facilitator?: string;
+    maxAmountRequired?: string;
+    resource?: string;
+    scheme?: string;
+    asset?: string;
+    tokenName?: string;
+    tokenVersion?: string;
+}
+/**
+ * Payment configuration for x402 middleware
+ */
+interface PaymentConfig {
+    payTo: `0x${string}`;
+    facilitatorUrl: string;
+    network: NetworkName;
+    priceUsd: string;
+}
+/**
+ * Result of payment verification
+ */
+interface PaymentVerificationResult {
+    isValid: boolean;
+    payer?: string;
+    invalidReason?: string;
+    transactionHash?: string;
+}
+/**
+ * Result of verifyX402Payment middleware
+ */
+interface X402PaymentResult {
+    isValid: boolean;
+    response?: any;
+    payer?: string;
+    envelope?: PaymentEnvelope;
+    paymentResponseHeader?: string;
+}
+/**
+ * Supported network names
+ */
+type NetworkName = "base" | "base-sepolia" | "avalanche" | "avalanche-fuji" | "celo" | "celo-sepolia";
+/**
+ * CAIP-2 network identifier
+ */
+type CAIP2Network = "eip155:8453" | "eip155:84532" | "eip155:43114" | "eip155:43113" | "eip155:42220" | "eip155:11142220";
+/**
+ * Token information for EIP-712 domain
+ */
+interface TokenInfo {
+    address: Address;
+    name: string;
+    symbol: string;
+    decimals: number;
+    chainId: number;
+}
+/**
+ * Settlement result from facilitator
+ */
+interface SettlementResult {
+    success: boolean;
+    transactionHash?: string;
+    error?: string;
+}
+/**
+ * Payment route configuration (path → price in USD)
+ */
+type PaymentRoutes = Record<string, number>;
+/**
+ * Options for x402 middleware
+ */
+interface X402MiddlewareOptions {
+    config: PaymentConfig;
+    routes: PaymentRoutes;
+    tokenDetector?: (address: Address, network: string) => Promise<TokenInfo | null>;
+    logger?: {
+        log: (...args: any[]) => void;
+        error: (...args: any[]) => void;
+    };
+}
+
+/**
+ * x402 Core Constants
+ * Network configurations, addresses, and mappings
+ */
+
+/**
+ * USDC Contract Addresses by Network
+ */
+declare const USDC_ADDRESSES: Record<NetworkName, Address>;
+/**
+ * Chain IDs by Network
+ */
+declare const CHAIN_IDS: Record<string, number>;
+/**
+ * Network to CAIP-2 mapping
+ */
+declare const NETWORK_TO_CAIP2: Record<NetworkName, CAIP2Network>;
+/**
+ * CAIP-2 to Network mapping
+ */
+declare const CAIP2_TO_NETWORK: Record<string, NetworkName>;
+/**
+ * Default RPC URLs by Network
+ */
+declare const DEFAULT_RPC_URLS: Record<NetworkName, string>;
+/**
+ * Valid network names
+ */
+declare const VALID_NETWORKS: NetworkName[];
+/**
+ * EIP-712 TransferWithAuthorization types
+ */
+declare const TRANSFER_WITH_AUTHORIZATION_TYPES: {
+    readonly TransferWithAuthorization: readonly [{
+        readonly name: "from";
+        readonly type: "address";
+    }, {
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "value";
+        readonly type: "uint256";
+    }, {
+        readonly name: "validAfter";
+        readonly type: "uint256";
+    }, {
+        readonly name: "validBefore";
+        readonly type: "uint256";
+    }, {
+        readonly name: "nonce";
+        readonly type: "bytes32";
+    }];
+};
+
+/**
+ * x402 Core Utilities
+ * Helper functions for x402 payment processing
+ */
+
+/**
+ * Get USDC address for a network
+ */
+declare function getUSDCAddress(network: string): Address;
+/**
+ * Get chain ID for a network
+ */
+declare function getChainId(network: string): number;
+/**
+ * Get RPC URL for a network (with environment variable override support)
+ */
+declare function getRpcUrl(network: string, envOverrides?: Record<string, string | undefined>): string;
+/**
+ * Convert network name to CAIP-2 format for x402 V2
+ * e.g., "base-sepolia" → "eip155:84532"
+ */
+declare function toCAIP2Network(network: string): string;
+/**
+ * Convert CAIP-2 network format to legacy format
+ * e.g., "eip155:43114" → "avalanche"
+ */
+declare function toLegacyNetwork(network: string): string;
+/**
+ * Parse USD price string to USDC amount (6 decimals)
+ * e.g., "$0.05" → 50000n
+ */
+declare function parsePriceToUSDC(price: string): bigint;
+/**
+ * Format USDC amount to USD string
+ * e.g., 50000n → "$0.05"
+ */
+declare function formatUSDCToPrice(amount: bigint): string;
+/**
+ * Generate random nonce for payment (32 bytes)
+ */
+declare function generateNonce(): `0x${string}`;
+/**
+ * Create EIP-712 domain for token transferWithAuthorization
+ */
+declare function createEIP712Domain(network: string, tokenAddress?: Address, tokenName?: string): {
+    name: string;
+    version: string;
+    chainId: number;
+    verifyingContract: `0x${string}`;
+};
+/**
+ * Format payment payload for x402 v2 PAYMENT-SIGNATURE header
+ * Per spec: https://www.x402.org/writing/x402-v2-launch
+ */
+declare function formatPaymentSignature(envelope: PaymentEnvelope, network: string, encodeBase64?: boolean): string;
+/**
+ * Parse payment signature from header
+ */
+declare function parsePaymentSignature(header: string): PaymentEnvelope | null;
+/**
+ * Validate network name
+ */
+declare function isValidNetwork(network: string): network is NetworkName;
+/**
+ * Get valid before timestamp (default: 30 minutes from now)
+ */
+declare function getValidBefore(minutes?: number): string;
+/**
+ * Get valid after timestamp (default: now)
+ */
+declare function getValidAfter(): string;
+
+/**
+ * x402 Payment Middleware
+ * Payment verification and settlement for API routes
+ */
+
+interface MiddlewareContext {
+    config: PaymentConfig;
+    routes: PaymentRoutes;
+    tokenDetector?: (address: string, network: string) => Promise<TokenInfo | null>;
+    createResponse?: (body: any, options: {
+        status: number;
+        headers?: Record<string, string>;
+    }) => any;
+    getHeader?: (request: any, name: string) => string | null;
+}
+/**
+ * Extract payment envelope from request headers
+ */
+declare function extractPaymentEnvelope(request: any, getHeader?: (req: any, name: string) => string | null): PaymentEnvelope | null;
+/**
+ * Verify payment with facilitator
+ */
+declare function verifyPayment(envelope: PaymentEnvelope, route: string, ctx: MiddlewareContext): Promise<PaymentVerificationResult>;
+/**
+ * Settle payment with facilitator
+ */
+declare function settlePayment(envelope: PaymentEnvelope, ctx: MiddlewareContext): Promise<SettlementResult>;
+/**
+ * Create 402 Payment Required response
+ */
+declare function create402Response(route: string, ctx: MiddlewareContext): {
+    body: any;
+    status: number;
+    headers: Record<string, string>;
+};
+/**
+ * Main middleware function to verify x402 payment
+ */
+declare function verifyX402Payment$1(request: any, route: string, ctx: MiddlewareContext): Promise<X402PaymentResult>;
+
+/**
+ * x402 Next.js Integration
+ * Helper functions for Next.js API routes
+ */
+
+/**
+ * Next.js specific middleware context
+ */
+interface NextX402Options {
+    config: PaymentConfig;
+    routes: PaymentRoutes;
+    tokenDetector?: (address: string, network: string) => Promise<TokenInfo | null>;
+}
+/**
+ * Verify x402 payment in Next.js API route
+ *
+ * @example
+ * ```typescript
+ * import { verifyX402Payment } from "@perkos/x402-core/next";
+ *
+ * export async function POST(request: NextRequest) {
+ *   const result = await verifyX402Payment(request, "/api/ai/translate", {
+ *     config: x402Config,
+ *     routes: paymentRoutes,
+ *   });
+ *
+ *   if (!result.isValid) {
+ *     return result.response;
+ *   }
+ *
+ *   // Process request...
+ * }
+ * ```
+ */
+declare function verifyX402Payment(request: any, route: string, options: NextX402Options): Promise<X402PaymentResult>;
+/**
+ * Create a configured middleware instance for Next.js
+ */
+declare function createX402Middleware(options: NextX402Options): {
+    verify: (request: any, route: string) => Promise<X402PaymentResult>;
+    options: NextX402Options;
+};
+
+export { type CAIP2Network, CAIP2_TO_NETWORK, CHAIN_IDS, DEFAULT_RPC_URLS, type MiddlewareContext, NETWORK_TO_CAIP2, type NetworkName, type NextX402Options, type PaymentConfig, type PaymentEnvelope, type PaymentRequirements, type PaymentRoutes, type PaymentVerificationResult, type SettlementResult, TRANSFER_WITH_AUTHORIZATION_TYPES, type TokenInfo, USDC_ADDRESSES, VALID_NETWORKS, type X402MiddlewareOptions, type X402PaymentResult, create402Response, createEIP712Domain, createX402Middleware, extractPaymentEnvelope, formatPaymentSignature, formatUSDCToPrice, generateNonce, getChainId, getRpcUrl, getUSDCAddress, getValidAfter, getValidBefore, isValidNetwork, parsePaymentSignature, parsePriceToUSDC, settlePayment, toCAIP2Network, toLegacyNetwork, verifyPayment, verifyX402Payment$1 as verifyX402Payment, verifyX402Payment as verifyX402PaymentNext };