uvd-x402-sdk 2.5.0 → 2.10.0

package/src/types/index.ts

@@ -15,10 +15,11 @@
  * - 'svm': Solana Virtual Machine chains (Solana, Fogo) (use SPL tokens)
  * - 'stellar': Stellar network (use Soroban)
  * - 'near': NEAR Protocol (use NEP-366)
+ * - 'algorand': Algorand network (use ASA transfers with atomic transactions)
  *
  * @deprecated 'solana' type is deprecated, use 'svm' instead
  */
-export type NetworkType = 'evm' | 'svm' | 'solana' | 'stellar' | 'near';
+export type NetworkType = 'evm' | 'svm' | 'solana' | 'stellar' | 'near' | 'algorand';
 
 /**
  * Supported stablecoin token types
@@ -200,6 +201,7 @@ export interface PaymentInfo {
     solana?: string;
     near?: string;
     stellar?: string;
+    algorand?: string;
   };
   /** Facilitator address (for Solana fee payer) */
   facilitator?: string;
@@ -230,6 +232,27 @@ export interface PaymentRequest {
   metadata?: Record<string, unknown>;
 }
 
+/**
+ * x402 payment header names
+ *
+ * - 'X-PAYMENT': v1 header name (default, most compatible)
+ * - 'PAYMENT-SIGNATURE': v2 header name (newer standard)
+ *
+ * Both headers use the same base64-encoded JSON payload format.
+ * The facilitator accepts both headers.
+ */
+export type X402HeaderName = 'X-PAYMENT' | 'PAYMENT-SIGNATURE';
+
+/**
+ * Payment headers object containing both v1 and v2 header formats
+ */
+export interface PaymentHeaders {
+  /** v1 header: X-PAYMENT */
+  'X-PAYMENT': string;
+  /** v2 header: PAYMENT-SIGNATURE (same value, different header name) */
+  'PAYMENT-SIGNATURE': string;
+}
+
 /**
  * Result of a payment operation
  */
@@ -238,6 +261,19 @@ export interface PaymentResult {
   success: boolean;
   /** Base64-encoded X-PAYMENT header value */
   paymentHeader: string;
+  /**
+   * Payment headers object for easy use with fetch/axios
+   *
+   * @example
+   * ```ts
+   * // Use v1 header
+   * fetch(url, { headers: { 'X-PAYMENT': result.headers['X-PAYMENT'] } });
+   *
+   * // Use v2 header
+   * fetch(url, { headers: { 'PAYMENT-SIGNATURE': result.headers['PAYMENT-SIGNATURE'] } });
+   * ```
+   */
+  headers: PaymentHeaders;
   /** Transaction hash (if available) */
   transactionHash?: string;
   /** Network where payment was made */
@@ -306,6 +342,28 @@ export interface NEARPaymentPayload {
   network: 'near';
 }
 
+/**
+ * Algorand payment payload (atomic transaction group)
+ *
+ * Algorand uses a unique payment model where the facilitator creates and signs
+ * an atomic transaction group. The user signs their portion (the ASA transfer)
+ * and the facilitator submits the complete group.
+ */
+export interface AlgorandPaymentPayload {
+  /** Sender's Algorand address (58-character base32) */
+  from: string;
+  /** Recipient's Algorand address */
+  to: string;
+  /** Amount in base units (microAlgos for ALGO, or base units for ASA) */
+  amount: string;
+  /** USDC ASA ID (31566704 for mainnet, 10458941 for testnet) */
+  assetId: number;
+  /** Base64-encoded signed transaction bytes */
+  signedTxn: string;
+  /** Optional note field */
+  note?: string;
+}
+
 /**
  * Union type for all payment payloads
  */
@@ -313,7 +371,8 @@ export type PaymentPayload =
   | EVMPaymentPayload
   | SolanaPaymentPayload
   | StellarPaymentPayload
-  | NEARPaymentPayload;
+  | NEARPaymentPayload
+  | AlgorandPaymentPayload;
 
 // ============================================================================
 // X402 HEADER TYPES (v1 and v2)
@@ -347,6 +406,9 @@ export const CAIP2_IDENTIFIERS: Record<string, string> = {
   stellar: 'stellar:pubnet',
   // NEAR
   near: 'near:mainnet',
+  // Algorand
+  algorand: 'algorand:mainnet',
+  'algorand-testnet': 'algorand:testnet',
 };
 
 /**
@@ -434,6 +496,18 @@ export interface X402NEARPayload {
   signedDelegateAction: string;
 }
 
+/**
+ * Algorand-specific payload in x402 header
+ */
+export interface X402AlgorandPayload {
+  from: string;
+  to: string;
+  amount: string;
+  assetId: number;
+  signedTxn: string;
+  note?: string;
+}
+
 /**
  * Union of all x402 payload types
  */
@@ -441,7 +515,8 @@ export type X402PayloadData =
   | X402EVMPayload
   | X402SolanaPayload
   | X402StellarPayload
-  | X402NEARPayload;
+  | X402NEARPayload
+  | X402AlgorandPayload;
 
 // ============================================================================
 // CLIENT CONFIGURATION

package/src/utils/index.ts

@@ -22,4 +22,8 @@ export {
 export {
   validateRecipient,
   validateAmount,
+  createPaymentHeaders,
+  getPaymentHeader,
+  DEFAULT_PAYMENT_HEADER,
+  PAYMENT_HEADER_NAMES,
 } from './validation';

package/src/utils/validation.ts

@@ -1,10 +1,11 @@
 /**
- * uvd-x402-sdk - Validation Utilities
+ * uvd-x402-sdk - Validation and Payment Header Utilities
  *
- * Functions for validating payment parameters to prevent
- * invalid or empty values from being processed.
+ * Functions for validating payment parameters and creating
+ * payment headers for HTTP requests.
  */
 
+import type { X402HeaderName, PaymentHeaders } from '../types';
 import { X402Error } from '../types';
 
 /**
@@ -149,3 +150,75 @@ export function validateAmount(amount: string | undefined | null): asserts amoun
     );
   }
 }
+
+// ============================================================================
+// PAYMENT HEADER UTILITIES
+// ============================================================================
+
+/**
+ * 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'] } });
+ * ```
+ */
+export function createPaymentHeaders(paymentHeader: string): PaymentHeaders {
+  return {
+    'X-PAYMENT': paymentHeader,
+    'PAYMENT-SIGNATURE': paymentHeader,
+  };
+}
+
+/**
+ * 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'),
+ *   },
+ * });
+ * ```
+ */
+export function getPaymentHeader(
+  paymentHeader: string,
+  headerName: X402HeaderName = 'X-PAYMENT'
+): Record<X402HeaderName, string> {
+  return { [headerName]: paymentHeader } as Record<X402HeaderName, string>;
+}
+
+/**
+ * Default x402 payment header name
+ *
+ * Use 'X-PAYMENT' for maximum compatibility with all facilitators.
+ * Use 'PAYMENT-SIGNATURE' for x402 v2 compliance.
+ */
+export const DEFAULT_PAYMENT_HEADER: X402HeaderName = 'X-PAYMENT';
+
+/**
+ * All supported x402 payment header names
+ */
+export const PAYMENT_HEADER_NAMES: readonly X402HeaderName[] = [
+  'X-PAYMENT',
+  'PAYMENT-SIGNATURE',
+] as const;