uvd-x402-sdk 2.74.0 → 2.76.0

package/dist/validation-De3bessL.d.mts

@@ -0,0 +1,273 @@
+import { x as X402Header, Q as X402Version, b as ChainConfig, G as X402PayloadData, z as X402HeaderV1, H as X402PaymentOption, B as X402HeaderV2, l as PaymentTokenMetadata, y as X402HeaderName, P as PaymentHeaders } from './index-ZH10otHE.mjs';
+
+/**
+ * uvd-x402-sdk - x402 Protocol Utilities
+ *
+ * Utilities for working with x402 v1 and v2 protocols.
+ * Handles version detection, payload encoding, and CAIP-2 conversions.
+ */
+
+/**
+ * Detect x402 version from a response header or body
+ *
+ * @param data - The 402 response data (parsed JSON or header value)
+ * @returns The detected version (1 or 2)
+ */
+declare function detectX402Version(data: unknown): X402Version;
+/**
+ * Convert chain name to CAIP-2 identifier
+ *
+ * @param chainName - Chain name (e.g., 'base', 'solana')
+ * @returns CAIP-2 identifier (e.g., 'eip155:8453', 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp')
+ */
+declare function chainToCAIP2(chainName: string): string;
+/**
+ * Convert CAIP-2 identifier to chain name
+ *
+ * @param caip2 - CAIP-2 identifier
+ * @returns Chain name or null if unknown
+ */
+declare function caip2ToChain(caip2: string): string | null;
+/**
+ * Parse network identifier from either v1 or v2 format
+ *
+ * @param network - Network identifier (v1 string or v2 CAIP-2)
+ * @returns Normalized chain name
+ */
+declare function parseNetworkIdentifier(network: string): string;
+/**
+ * Encode x402 payload as base64 header value
+ *
+ * @param header - The x402 header object
+ * @returns Base64-encoded string
+ */
+declare function encodeX402Header(header: X402Header): string;
+/**
+ * Decode x402 header from base64 string
+ *
+ * @param encoded - Base64-encoded header value
+ * @returns Parsed x402 header
+ */
+declare function decodeX402Header(encoded: string): X402Header;
+/**
+ * Create x402 v1 header
+ *
+ * @param network - Chain name (e.g., 'base')
+ * @param payload - Network-specific payload
+ * @returns x402 v1 header object
+ */
+declare function createX402V1Header(network: string, payload: X402PayloadData): X402HeaderV1;
+/**
+ * Create x402 v2 header
+ *
+ * @param network - CAIP-2 network identifier
+ * @param payload - Network-specific payload
+ * @param accepts - Optional array of payment options
+ * @returns x402 v2 header object
+ */
+declare function createX402V2Header(network: string, payload: X402PayloadData, accepts?: X402PaymentOption[]): X402HeaderV2;
+/**
+ * Create x402 header with automatic version selection
+ *
+ * @param chainConfig - Chain configuration
+ * @param payload - Network-specific payload
+ * @param version - Version to use (1, 2, or 'auto')
+ * @returns x402 header object
+ */
+declare function createX402Header(chainConfig: ChainConfig, payload: X402PayloadData, version?: X402Version | 'auto'): X402Header;
+/**
+ * Generate payment options array for multi-network support
+ *
+ * @param chainConfigs - Array of chain configurations
+ * @param amount - Amount in USDC (e.g., "10.00")
+ * @param facilitator - Optional facilitator URL override
+ * @returns Array of x402 v2 payment options
+ */
+declare function generatePaymentOptions(chainConfigs: ChainConfig[], amount: string, facilitator?: string): X402PaymentOption[];
+/**
+ * Check if a network string is in CAIP-2 format
+ *
+ * @param network - Network identifier
+ * @returns True if CAIP-2 format
+ */
+declare function isCAIP2Format(network: string): boolean;
+/**
+ * Convert between x402 v1 and v2 header formats
+ *
+ * @param header - Source header
+ * @param targetVersion - Target version
+ * @returns Converted header
+ */
+declare function convertX402Header(header: X402Header, targetVersion: X402Version): X402Header;
+/**
+ * Read a 402 payment challenge from wherever the seller put it.
+ *
+ * x402 allows BOTH transports and sellers pick freely:
+ *
+ * - base64 JSON in the `PAYMENT-REQUIRED` (or `X-PAYMENT-REQUIRED`) header
+ * - JSON in the response body
+ *
+ * Measured against production on 2026-08-20: of 40 live Bazaar resources,
+ * **36 of 36 that answered 402 carried the challenge in the header, and none in
+ * the body**. Worse, sellers like Tenjin use the 402 body for a free preview of
+ * the paid content — so the body is valid JSON that simply has no `accepts`, and
+ * a body-only reader parses it happily and finds nothing.
+ *
+ * Reads the header first because that is where live sellers put it, and falls
+ * back to the body so the sellers who use it keep working.
+ *
+ * Returns `null` when neither transport carries a challenge — a real "no terms
+ * here", distinct from a challenge we failed to decode.
+ */
+declare function paymentChallengeFrom(headers: {
+    get(name: string): string | null;
+} | Record<string, string>, body?: unknown): Record<string, unknown> | null;
+
+/**
+ * uvd-x402-sdk - Token metadata for payment payloads
+ *
+ * An EIP-3009 authorization is signed against a token contract, but the encoded
+ * payload only carries the signature and the transfer fields. The token itself
+ * is implicit — the server is expected to already know which asset it asked
+ * for.
+ *
+ * That holds when a resource accepts exactly one token per chain. It breaks as
+ * soon as it accepts several: a EURC payment and a USDC payment on Base produce
+ * indistinguishable payloads, and the server cannot build the
+ * `paymentRequirements` (`asset` + `extra`) the facilitator needs to settle.
+ *
+ * So the payment can opt into carrying the token with it.
+ */
+
+/**
+ * Build the token metadata block for a payload, resolving the address against
+ * the chain registry.
+ *
+ * @param chainName - Chain the payment was signed for
+ * @param address - Token contract address from the signed payload
+ * @returns Metadata block, or undefined if the address is not in the registry
+ */
+declare function buildTokenMetadata(chainName: string, address: string): PaymentTokenMetadata | undefined;
+
+/**
+ * uvd-x402-sdk - UTF-8 safe base64
+ *
+ * `btoa()` only accepts code points 0-255. Any character above that throws
+ * `InvalidCharacterError`, and the X-PAYMENT payload is not guaranteed to be
+ * ASCII: the EIP-712 domain name of USDT on Optimism and Arbitrum is literally
+ * `USD₮0` (U+20AE). A header carrying that name crashes a plain `btoa()`.
+ *
+ * So the JSON is UTF-8 encoded to bytes first, and only then base64'd. Decoding
+ * reverses it. For ASCII-only input the output is byte-identical to
+ * `btoa(json)`, which is why swapping this in cannot change any existing header.
+ *
+ * `TextEncoder`/`TextDecoder` are available in every browser the SDK targets and
+ * in Node 11+; `btoa`/`atob` are used for the byte<->base64 step because they
+ * exist in both environments without pulling in `Buffer`.
+ */
+/**
+ * Encode a string as base64, handling non-ASCII characters correctly.
+ *
+ * @param value - Any UTF-8 string
+ * @returns Base64-encoded value
+ */
+declare function encodeBase64Utf8(value: string): string;
+/**
+ * Decode a base64 string produced by {@link encodeBase64Utf8}.
+ *
+ * @param encoded - Base64-encoded value
+ * @returns The original UTF-8 string
+ */
+declare function decodeBase64Utf8(encoded: string): string;
+/**
+ * JSON-serialize a value and encode it as UTF-8 safe base64.
+ *
+ * This is the encoder for every X-PAYMENT header the SDK emits.
+ *
+ * @param value - Value to serialize
+ * @returns Base64-encoded JSON
+ */
+declare function encodeBase64Json(value: unknown): string;
+
+/**
+ * uvd-x402-sdk - Validation and Payment Header Utilities
+ *
+ * Functions for validating payment parameters and creating
+ * payment headers for HTTP requests.
+ */
+
+/**
+ * Validate that a recipient address is present and valid
+ *
+ * This function ensures that:
+ * 1. The recipient is not null, undefined, or empty
+ * 2. The recipient is not just whitespace
+ * 3. For EVM, it's a valid checksummed or lowercase 0x address
+ *
+ * @param recipient - The recipient address to validate
+ * @param networkType - Optional network type for format validation
+ * @throws X402Error with code 'INVALID_RECIPIENT' if validation fails
+ */
+declare function validateRecipient(recipient: string | undefined | null, networkType?: 'evm' | 'svm' | 'solana' | 'stellar' | 'near' | 'xrpl'): asserts recipient is string;
+/**
+ * Validate payment amount
+ *
+ * Ensures the amount is a valid positive number string
+ *
+ * @param amount - The amount string to validate
+ * @throws X402Error with code 'INVALID_AMOUNT' if validation fails
+ */
+declare function validateAmount(amount: string | undefined | null): asserts amount is string;
+/**
+ * Create payment headers object from a base64-encoded payload
+ *
+ * Returns an object with both X-PAYMENT and PAYMENT-SIGNATURE headers,
+ * making it easy to use either header format.
+ *
+ * @param paymentHeader - Base64-encoded payment payload
+ * @returns PaymentHeaders object with both header formats
+ *
+ * @example
+ * ```ts
+ * const headers = createPaymentHeaders(paymentHeader);
+ *
+ * // Use v1 header (most compatible)
+ * fetch(url, { headers: { 'X-PAYMENT': headers['X-PAYMENT'] } });
+ *
+ * // Use v2 header
+ * fetch(url, { headers: { 'PAYMENT-SIGNATURE': headers['PAYMENT-SIGNATURE'] } });
+ * ```
+ */
+declare function createPaymentHeaders(paymentHeader: string): PaymentHeaders;
+/**
+ * Get a single payment header by name
+ *
+ * @param paymentHeader - Base64-encoded payment payload
+ * @param headerName - Header name to use ('X-PAYMENT' or 'PAYMENT-SIGNATURE')
+ * @returns Object with a single header entry
+ *
+ * @example
+ * ```ts
+ * // Use with fetch spread operator
+ * fetch(url, {
+ *   headers: {
+ *     'Content-Type': 'application/json',
+ *     ...getPaymentHeader(result.paymentHeader, 'X-PAYMENT'),
+ *   },
+ * });
+ * ```
+ */
+declare function getPaymentHeader(paymentHeader: string, headerName?: X402HeaderName): Record<X402HeaderName, string>;
+/**
+ * Default x402 payment header name
+ *
+ * Use 'X-PAYMENT' for maximum compatibility with all facilitators.
+ * Use 'PAYMENT-SIGNATURE' for x402 v2 compliance.
+ */
+declare const DEFAULT_PAYMENT_HEADER: X402HeaderName;
+/**
+ * All supported x402 payment header names
+ */
+declare const PAYMENT_HEADER_NAMES: readonly X402HeaderName[];
+
+export { DEFAULT_PAYMENT_HEADER as D, PAYMENT_HEADER_NAMES as P, chainToCAIP2 as a, buildTokenMetadata as b, caip2ToChain as c, convertX402Header as d, createPaymentHeaders as e, createX402Header as f, createX402V1Header as g, createX402V2Header as h, decodeBase64Utf8 as i, decodeX402Header as j, detectX402Version as k, encodeBase64Json as l, encodeBase64Utf8 as m, encodeX402Header as n, generatePaymentOptions as o, getPaymentHeader as p, isCAIP2Format as q, parseNetworkIdentifier as r, paymentChallengeFrom as s, validateRecipient as t, validateAmount as v };

package/dist/validation-DsbfDAtV.d.ts

@@ -0,0 +1,273 @@
+import { x as X402Header, Q as X402Version, b as ChainConfig, G as X402PayloadData, z as X402HeaderV1, H as X402PaymentOption, B as X402HeaderV2, l as PaymentTokenMetadata, y as X402HeaderName, P as PaymentHeaders } from './index-ZH10otHE.js';
+
+/**
+ * uvd-x402-sdk - x402 Protocol Utilities
+ *
+ * Utilities for working with x402 v1 and v2 protocols.
+ * Handles version detection, payload encoding, and CAIP-2 conversions.
+ */
+
+/**
+ * Detect x402 version from a response header or body
+ *
+ * @param data - The 402 response data (parsed JSON or header value)
+ * @returns The detected version (1 or 2)
+ */
+declare function detectX402Version(data: unknown): X402Version;
+/**
+ * Convert chain name to CAIP-2 identifier
+ *
+ * @param chainName - Chain name (e.g., 'base', 'solana')
+ * @returns CAIP-2 identifier (e.g., 'eip155:8453', 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp')
+ */
+declare function chainToCAIP2(chainName: string): string;
+/**
+ * Convert CAIP-2 identifier to chain name
+ *
+ * @param caip2 - CAIP-2 identifier
+ * @returns Chain name or null if unknown
+ */
+declare function caip2ToChain(caip2: string): string | null;
+/**
+ * Parse network identifier from either v1 or v2 format
+ *
+ * @param network - Network identifier (v1 string or v2 CAIP-2)
+ * @returns Normalized chain name
+ */
+declare function parseNetworkIdentifier(network: string): string;
+/**
+ * Encode x402 payload as base64 header value
+ *
+ * @param header - The x402 header object
+ * @returns Base64-encoded string
+ */
+declare function encodeX402Header(header: X402Header): string;
+/**
+ * Decode x402 header from base64 string
+ *
+ * @param encoded - Base64-encoded header value
+ * @returns Parsed x402 header
+ */
+declare function decodeX402Header(encoded: string): X402Header;
+/**
+ * Create x402 v1 header
+ *
+ * @param network - Chain name (e.g., 'base')
+ * @param payload - Network-specific payload
+ * @returns x402 v1 header object
+ */
+declare function createX402V1Header(network: string, payload: X402PayloadData): X402HeaderV1;
+/**
+ * Create x402 v2 header
+ *
+ * @param network - CAIP-2 network identifier
+ * @param payload - Network-specific payload
+ * @param accepts - Optional array of payment options
+ * @returns x402 v2 header object
+ */
+declare function createX402V2Header(network: string, payload: X402PayloadData, accepts?: X402PaymentOption[]): X402HeaderV2;
+/**
+ * Create x402 header with automatic version selection
+ *
+ * @param chainConfig - Chain configuration
+ * @param payload - Network-specific payload
+ * @param version - Version to use (1, 2, or 'auto')
+ * @returns x402 header object
+ */
+declare function createX402Header(chainConfig: ChainConfig, payload: X402PayloadData, version?: X402Version | 'auto'): X402Header;
+/**
+ * Generate payment options array for multi-network support
+ *
+ * @param chainConfigs - Array of chain configurations
+ * @param amount - Amount in USDC (e.g., "10.00")
+ * @param facilitator - Optional facilitator URL override
+ * @returns Array of x402 v2 payment options
+ */
+declare function generatePaymentOptions(chainConfigs: ChainConfig[], amount: string, facilitator?: string): X402PaymentOption[];
+/**
+ * Check if a network string is in CAIP-2 format
+ *
+ * @param network - Network identifier
+ * @returns True if CAIP-2 format
+ */
+declare function isCAIP2Format(network: string): boolean;
+/**
+ * Convert between x402 v1 and v2 header formats
+ *
+ * @param header - Source header
+ * @param targetVersion - Target version
+ * @returns Converted header
+ */
+declare function convertX402Header(header: X402Header, targetVersion: X402Version): X402Header;
+/**
+ * Read a 402 payment challenge from wherever the seller put it.
+ *
+ * x402 allows BOTH transports and sellers pick freely:
+ *
+ * - base64 JSON in the `PAYMENT-REQUIRED` (or `X-PAYMENT-REQUIRED`) header
+ * - JSON in the response body
+ *
+ * Measured against production on 2026-08-20: of 40 live Bazaar resources,
+ * **36 of 36 that answered 402 carried the challenge in the header, and none in
+ * the body**. Worse, sellers like Tenjin use the 402 body for a free preview of
+ * the paid content — so the body is valid JSON that simply has no `accepts`, and
+ * a body-only reader parses it happily and finds nothing.
+ *
+ * Reads the header first because that is where live sellers put it, and falls
+ * back to the body so the sellers who use it keep working.
+ *
+ * Returns `null` when neither transport carries a challenge — a real "no terms
+ * here", distinct from a challenge we failed to decode.
+ */
+declare function paymentChallengeFrom(headers: {
+    get(name: string): string | null;
+} | Record<string, string>, body?: unknown): Record<string, unknown> | null;
+
+/**
+ * uvd-x402-sdk - Token metadata for payment payloads
+ *
+ * An EIP-3009 authorization is signed against a token contract, but the encoded
+ * payload only carries the signature and the transfer fields. The token itself
+ * is implicit — the server is expected to already know which asset it asked
+ * for.
+ *
+ * That holds when a resource accepts exactly one token per chain. It breaks as
+ * soon as it accepts several: a EURC payment and a USDC payment on Base produce
+ * indistinguishable payloads, and the server cannot build the
+ * `paymentRequirements` (`asset` + `extra`) the facilitator needs to settle.
+ *
+ * So the payment can opt into carrying the token with it.
+ */
+
+/**
+ * Build the token metadata block for a payload, resolving the address against
+ * the chain registry.
+ *
+ * @param chainName - Chain the payment was signed for
+ * @param address - Token contract address from the signed payload
+ * @returns Metadata block, or undefined if the address is not in the registry
+ */
+declare function buildTokenMetadata(chainName: string, address: string): PaymentTokenMetadata | undefined;
+
+/**
+ * uvd-x402-sdk - UTF-8 safe base64
+ *
+ * `btoa()` only accepts code points 0-255. Any character above that throws
+ * `InvalidCharacterError`, and the X-PAYMENT payload is not guaranteed to be
+ * ASCII: the EIP-712 domain name of USDT on Optimism and Arbitrum is literally
+ * `USD₮0` (U+20AE). A header carrying that name crashes a plain `btoa()`.
+ *
+ * So the JSON is UTF-8 encoded to bytes first, and only then base64'd. Decoding
+ * reverses it. For ASCII-only input the output is byte-identical to
+ * `btoa(json)`, which is why swapping this in cannot change any existing header.
+ *
+ * `TextEncoder`/`TextDecoder` are available in every browser the SDK targets and
+ * in Node 11+; `btoa`/`atob` are used for the byte<->base64 step because they
+ * exist in both environments without pulling in `Buffer`.
+ */
+/**
+ * Encode a string as base64, handling non-ASCII characters correctly.
+ *
+ * @param value - Any UTF-8 string
+ * @returns Base64-encoded value
+ */
+declare function encodeBase64Utf8(value: string): string;
+/**
+ * Decode a base64 string produced by {@link encodeBase64Utf8}.
+ *
+ * @param encoded - Base64-encoded value
+ * @returns The original UTF-8 string
+ */
+declare function decodeBase64Utf8(encoded: string): string;
+/**
+ * JSON-serialize a value and encode it as UTF-8 safe base64.
+ *
+ * This is the encoder for every X-PAYMENT header the SDK emits.
+ *
+ * @param value - Value to serialize
+ * @returns Base64-encoded JSON
+ */
+declare function encodeBase64Json(value: unknown): string;
+
+/**
+ * uvd-x402-sdk - Validation and Payment Header Utilities
+ *
+ * Functions for validating payment parameters and creating
+ * payment headers for HTTP requests.
+ */
+
+/**
+ * Validate that a recipient address is present and valid
+ *
+ * This function ensures that:
+ * 1. The recipient is not null, undefined, or empty
+ * 2. The recipient is not just whitespace
+ * 3. For EVM, it's a valid checksummed or lowercase 0x address
+ *
+ * @param recipient - The recipient address to validate
+ * @param networkType - Optional network type for format validation
+ * @throws X402Error with code 'INVALID_RECIPIENT' if validation fails
+ */
+declare function validateRecipient(recipient: string | undefined | null, networkType?: 'evm' | 'svm' | 'solana' | 'stellar' | 'near' | 'xrpl'): asserts recipient is string;
+/**
+ * Validate payment amount
+ *
+ * Ensures the amount is a valid positive number string
+ *
+ * @param amount - The amount string to validate
+ * @throws X402Error with code 'INVALID_AMOUNT' if validation fails
+ */
+declare function validateAmount(amount: string | undefined | null): asserts amount is string;
+/**
+ * Create payment headers object from a base64-encoded payload
+ *
+ * Returns an object with both X-PAYMENT and PAYMENT-SIGNATURE headers,
+ * making it easy to use either header format.
+ *
+ * @param paymentHeader - Base64-encoded payment payload
+ * @returns PaymentHeaders object with both header formats
+ *
+ * @example
+ * ```ts
+ * const headers = createPaymentHeaders(paymentHeader);
+ *
+ * // Use v1 header (most compatible)
+ * fetch(url, { headers: { 'X-PAYMENT': headers['X-PAYMENT'] } });
+ *
+ * // Use v2 header
+ * fetch(url, { headers: { 'PAYMENT-SIGNATURE': headers['PAYMENT-SIGNATURE'] } });
+ * ```
+ */
+declare function createPaymentHeaders(paymentHeader: string): PaymentHeaders;
+/**
+ * Get a single payment header by name
+ *
+ * @param paymentHeader - Base64-encoded payment payload
+ * @param headerName - Header name to use ('X-PAYMENT' or 'PAYMENT-SIGNATURE')
+ * @returns Object with a single header entry
+ *
+ * @example
+ * ```ts
+ * // Use with fetch spread operator
+ * fetch(url, {
+ *   headers: {
+ *     'Content-Type': 'application/json',
+ *     ...getPaymentHeader(result.paymentHeader, 'X-PAYMENT'),
+ *   },
+ * });
+ * ```
+ */
+declare function getPaymentHeader(paymentHeader: string, headerName?: X402HeaderName): Record<X402HeaderName, string>;
+/**
+ * Default x402 payment header name
+ *
+ * Use 'X-PAYMENT' for maximum compatibility with all facilitators.
+ * Use 'PAYMENT-SIGNATURE' for x402 v2 compliance.
+ */
+declare const DEFAULT_PAYMENT_HEADER: X402HeaderName;
+/**
+ * All supported x402 payment header names
+ */
+declare const PAYMENT_HEADER_NAMES: readonly X402HeaderName[];
+
+export { DEFAULT_PAYMENT_HEADER as D, PAYMENT_HEADER_NAMES as P, chainToCAIP2 as a, buildTokenMetadata as b, caip2ToChain as c, convertX402Header as d, createPaymentHeaders as e, createX402Header as f, createX402V1Header as g, createX402V2Header as h, decodeBase64Utf8 as i, decodeX402Header as j, detectX402Version as k, encodeBase64Json as l, encodeBase64Utf8 as m, encodeX402Header as n, generatePaymentOptions as o, getPaymentHeader as p, isCAIP2Format as q, parseNetworkIdentifier as r, paymentChallengeFrom as s, validateRecipient as t, validateAmount as v };

package/dist/{wallet-w7BnImDG.d.mts → wallet-0cX9Pw2F.d.mts}

@@ -133,4 +133,4 @@ interface SigningWalletAdapter {
     signTransaction(unsignedTx: string): Promise<string>;
 }
 
-export type { EIP3009Params as E, SigningWalletAdapter as S, EIP3009Authorization as a };
+export type { EIP3009Authorization as E, SigningWalletAdapter as S, EIP3009Params as a };

package/dist/{wallet-w7BnImDG.d.ts → wallet-0cX9Pw2F.d.ts}

@@ -133,4 +133,4 @@ interface SigningWalletAdapter {
     signTransaction(unsignedTx: string): Promise<string>;
 }
 
-export type { EIP3009Params as E, SigningWalletAdapter as S, EIP3009Authorization as a };
+export type { EIP3009Authorization as E, SigningWalletAdapter as S, EIP3009Params as a };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uvd-x402-sdk",
-  "version": "2.74.0",
+  "version": "2.76.0",
   "description": "x402 Payment SDK - Gasless crypto payments across 25 blockchains via Ultravioleta facilitator. Supports EVM (including Scroll, SKALE Base, Robinhood Chain), Solana, Fogo, Stellar, NEAR, Algorand, Sui, and XRP Ledger. Features: ERC-8004 Trustless Agents, Escrow/Refunds, multi-stablecoin (USDC, EURC, AUSD, PYUSD, USDT, USDG).",
   "author": "Ultravioleta DAO <ultravioletadao@gmail.com>",
   "license": "MIT",