@wazabiai/x402 0.1.0

package/dist/types/index.d.cts

@@ -0,0 +1,408 @@
+import { z } from 'zod';
+
+/**
+ * x402 Protocol Version
+ */
+declare const X402_VERSION: "2.0.0";
+/**
+ * EIP-712 Domain name for x402 protocol
+ */
+declare const X402_DOMAIN_NAME: "x402";
+/**
+ * HTTP Header names used in x402 protocol
+ */
+declare const X402_HEADERS: {
+    readonly PAYMENT_REQUIRED: "x-payment-required";
+    readonly PAYMENT_SIGNATURE: "x-payment-signature";
+    readonly PAYMENT_PAYLOAD: "x-payment-payload";
+};
+/**
+ * Supported token symbol types
+ */
+type TokenSymbol = 'USDT' | 'USDC' | 'BNB' | 'BUSD';
+/**
+ * Token configuration for a specific blockchain
+ */
+interface TokenConfig {
+    /** Token contract address (0x...) */
+    address: `0x${string}`;
+    /** Token symbol */
+    symbol: TokenSymbol;
+    /** Token decimals (typically 18 for most tokens) */
+    decimals: number;
+    /** Human-readable token name */
+    name: string;
+}
+/**
+ * Network configuration for a specific blockchain
+ */
+interface NetworkConfig {
+    /** CAIP-2 chain identifier (e.g., 'eip155:56' for BSC) */
+    caipId: string;
+    /** Numeric chain ID */
+    chainId: number;
+    /** Human-readable network name */
+    name: string;
+    /** Default RPC URL */
+    rpcUrl: string;
+    /** Native currency symbol */
+    nativeCurrency: {
+        name: string;
+        symbol: string;
+        decimals: number;
+    };
+    /** Block explorer URL */
+    blockExplorer: string;
+    /** Supported tokens on this network */
+    tokens: Record<string, TokenConfig>;
+}
+/**
+ * Zod schema for PaymentRequirement validation
+ */
+declare const PaymentRequirementSchema: z.ZodObject<{
+    /** Payment amount in smallest token unit (wei/satoshi) as string */
+    amount: z.ZodString;
+    /** Token contract address */
+    token: z.ZodString;
+    /** CAIP-2 network identifier */
+    network_id: z.ZodString;
+    /** Recipient address for payment */
+    pay_to: z.ZodString;
+    /** Optional: Payment description */
+    description: z.ZodOptional<z.ZodString>;
+    /** Optional: Resource identifier being accessed */
+    resource: z.ZodOptional<z.ZodString>;
+    /** Optional: Expiration timestamp (Unix epoch seconds) */
+    expires_at: z.ZodOptional<z.ZodNumber>;
+    /** Optional: Unique nonce to prevent replay attacks */
+    nonce: z.ZodOptional<z.ZodString>;
+    /** Protocol version */
+    version: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    amount: string;
+    token: string;
+    network_id: string;
+    pay_to: string;
+    description?: string | undefined;
+    resource?: string | undefined;
+    expires_at?: number | undefined;
+    nonce?: string | undefined;
+    version?: string | undefined;
+}, {
+    amount: string;
+    token: string;
+    network_id: string;
+    pay_to: string;
+    description?: string | undefined;
+    resource?: string | undefined;
+    expires_at?: number | undefined;
+    nonce?: string | undefined;
+    version?: string | undefined;
+}>;
+/**
+ * Payment requirement structure returned in 402 response header
+ */
+type PaymentRequirement = z.infer<typeof PaymentRequirementSchema>;
+/**
+ * EIP-712 Domain structure for x402 protocol
+ */
+interface X402Domain {
+    name: typeof X402_DOMAIN_NAME;
+    version: string;
+    chainId: number;
+    verifyingContract?: `0x${string}`;
+}
+/**
+ * Zod schema for PaymentPayload validation
+ */
+declare const PaymentPayloadSchema: z.ZodObject<{
+    /** Payment amount in smallest token unit */
+    amount: z.ZodString;
+    /** Token contract address */
+    token: z.ZodString;
+    /** Chain ID (numeric) */
+    chainId: z.ZodNumber;
+    /** Recipient address */
+    payTo: z.ZodString;
+    /** Payer address (signer) */
+    payer: z.ZodString;
+    /** Unix timestamp when payment expires */
+    deadline: z.ZodNumber;
+    /** Unique nonce to prevent replay attacks */
+    nonce: z.ZodString;
+    /** Optional: Resource being accessed */
+    resource: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    amount: string;
+    token: string;
+    nonce: string;
+    chainId: number;
+    payTo: string;
+    payer: string;
+    deadline: number;
+    resource?: string | undefined;
+}, {
+    amount: string;
+    token: string;
+    nonce: string;
+    chainId: number;
+    payTo: string;
+    payer: string;
+    deadline: number;
+    resource?: string | undefined;
+}>;
+/**
+ * EIP-712 typed data payload for signing
+ */
+type PaymentPayload = z.infer<typeof PaymentPayloadSchema>;
+/**
+ * EIP-712 type definitions for Payment message
+ */
+declare const PAYMENT_TYPES: {
+    readonly Payment: readonly [{
+        readonly name: "amount";
+        readonly type: "uint256";
+    }, {
+        readonly name: "token";
+        readonly type: "address";
+    }, {
+        readonly name: "chainId";
+        readonly type: "uint256";
+    }, {
+        readonly name: "payTo";
+        readonly type: "address";
+    }, {
+        readonly name: "payer";
+        readonly type: "address";
+    }, {
+        readonly name: "deadline";
+        readonly type: "uint256";
+    }, {
+        readonly name: "nonce";
+        readonly type: "string";
+    }, {
+        readonly name: "resource";
+        readonly type: "string";
+    }];
+};
+/**
+ * Complete signed payment ready to be sent as header
+ */
+interface SignedPayment {
+    /** The payment payload that was signed */
+    payload: PaymentPayload;
+    /** EIP-712 signature (0x prefixed) */
+    signature: `0x${string}`;
+    /** Address of the signer */
+    signer: `0x${string}`;
+}
+/**
+ * Zod schema for SignedPayment validation
+ */
+declare const SignedPaymentSchema: z.ZodObject<{
+    payload: z.ZodObject<{
+        /** Payment amount in smallest token unit */
+        amount: z.ZodString;
+        /** Token contract address */
+        token: z.ZodString;
+        /** Chain ID (numeric) */
+        chainId: z.ZodNumber;
+        /** Recipient address */
+        payTo: z.ZodString;
+        /** Payer address (signer) */
+        payer: z.ZodString;
+        /** Unix timestamp when payment expires */
+        deadline: z.ZodNumber;
+        /** Unique nonce to prevent replay attacks */
+        nonce: z.ZodString;
+        /** Optional: Resource being accessed */
+        resource: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        amount: string;
+        token: string;
+        nonce: string;
+        chainId: number;
+        payTo: string;
+        payer: string;
+        deadline: number;
+        resource?: string | undefined;
+    }, {
+        amount: string;
+        token: string;
+        nonce: string;
+        chainId: number;
+        payTo: string;
+        payer: string;
+        deadline: number;
+        resource?: string | undefined;
+    }>;
+    signature: z.ZodString;
+    signer: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    payload: {
+        amount: string;
+        token: string;
+        nonce: string;
+        chainId: number;
+        payTo: string;
+        payer: string;
+        deadline: number;
+        resource?: string | undefined;
+    };
+    signature: string;
+    signer: string;
+}, {
+    payload: {
+        amount: string;
+        token: string;
+        nonce: string;
+        chainId: number;
+        payTo: string;
+        payer: string;
+        deadline: number;
+        resource?: string | undefined;
+    };
+    signature: string;
+    signer: string;
+}>;
+/**
+ * Configuration options for X402Client
+ */
+interface X402ClientConfig {
+    /** Private key for signing (hex string with or without 0x prefix) */
+    privateKey?: string;
+    /** Custom RPC URL to use instead of default */
+    rpcUrl?: string;
+    /** Supported network IDs (defaults to ['eip155:56']) */
+    supportedNetworks?: string[];
+    /** Default deadline duration in seconds (default: 300 = 5 minutes) */
+    defaultDeadline?: number;
+    /** Auto-retry on 402 response (default: true) */
+    autoRetry?: boolean;
+    /** Maximum retries for payment (default: 1) */
+    maxRetries?: number;
+    /** Custom axios instance configuration */
+    axiosConfig?: Record<string, unknown>;
+    /** Callback when payment is required */
+    onPaymentRequired?: (requirement: PaymentRequirement) => void | Promise<void>;
+    /** Callback when payment is signed */
+    onPaymentSigned?: (payment: SignedPayment) => void | Promise<void>;
+}
+/**
+ * Payment verification result
+ */
+interface PaymentVerificationResult {
+    /** Whether the payment signature is valid */
+    valid: boolean;
+    /** Recovered signer address if valid */
+    signer?: `0x${string}`;
+    /** Error message if invalid */
+    error?: string;
+    /** The verified payment payload */
+    payload?: PaymentPayload;
+}
+/**
+ * Facilitator verification request
+ */
+interface FacilitatorVerifyRequest {
+    signature: string;
+    payload: PaymentPayload;
+    networkId: string;
+}
+/**
+ * Facilitator verification response
+ */
+interface FacilitatorVerifyResponse {
+    valid: boolean;
+    signer?: string;
+    error?: string;
+    balanceSufficient?: boolean;
+    allowanceSufficient?: boolean;
+}
+/**
+ * Configuration options for x402 server middleware
+ */
+interface X402MiddlewareConfig {
+    /** Recipient address for payments */
+    recipientAddress: `0x${string}`;
+    /** Payment amount in smallest token unit */
+    amount: string;
+    /** Token contract address (defaults to BSC-USDT) */
+    tokenAddress?: `0x${string}`;
+    /** Optional facilitator URL for offloading verification */
+    facilitatorUrl?: string;
+    /** Custom payment description */
+    description?: string;
+    /** Network ID (defaults to 'eip155:56') */
+    networkId?: string;
+    /** Deadline duration in seconds (default: 300) */
+    deadlineDuration?: number;
+    /** Custom nonce generator */
+    nonceGenerator?: () => string;
+    /** Callback to verify payment against custom logic (e.g., database) */
+    verifyPayment?: (payment: SignedPayment, req: unknown) => Promise<boolean>;
+    /** Routes to exclude from payment requirement */
+    excludeRoutes?: string[];
+    /** Custom error handler */
+    onError?: (error: Error, req: unknown, res: unknown) => void;
+}
+/**
+ * Base error class for x402 protocol errors
+ */
+declare class X402Error extends Error {
+    code: string;
+    details?: Record<string, unknown> | undefined;
+    constructor(message: string, code: string, details?: Record<string, unknown> | undefined);
+}
+/**
+ * Error thrown when payment is required but not provided
+ */
+declare class PaymentRequiredError extends X402Error {
+    requirement: PaymentRequirement;
+    constructor(requirement: PaymentRequirement, message?: string);
+}
+/**
+ * Error thrown when payment signature verification fails
+ */
+declare class PaymentVerificationError extends X402Error {
+    details?: Record<string, unknown> | undefined;
+    constructor(message: string, details?: Record<string, unknown> | undefined);
+}
+/**
+ * Error thrown when network is not supported
+ */
+declare class UnsupportedNetworkError extends X402Error {
+    constructor(networkId: string, supportedNetworks: string[]);
+}
+/**
+ * Error thrown when payment has expired
+ */
+declare class PaymentExpiredError extends X402Error {
+    constructor(deadline: number);
+}
+/**
+ * Hex string type (0x prefixed)
+ */
+type HexString = `0x${string}`;
+/**
+ * Address type (0x prefixed, 40 hex chars)
+ */
+type Address = `0x${string}`;
+/**
+ * Extract chain ID from CAIP-2 identifier
+ */
+declare function extractChainId(caipId: string): number;
+/**
+ * Create CAIP-2 identifier from chain ID
+ */
+declare function createCaipId(chainId: number): string;
+/**
+ * Generate a random nonce
+ */
+declare function generateNonce(): string;
+/**
+ * Calculate deadline from duration
+ */
+declare function calculateDeadline(durationSeconds?: number): number;
+
+export { type Address, type FacilitatorVerifyRequest, type FacilitatorVerifyResponse, type HexString, type NetworkConfig, PAYMENT_TYPES, PaymentExpiredError, type PaymentPayload, PaymentPayloadSchema, PaymentRequiredError, type PaymentRequirement, PaymentRequirementSchema, PaymentVerificationError, type PaymentVerificationResult, type SignedPayment, SignedPaymentSchema, type TokenConfig, type TokenSymbol, UnsupportedNetworkError, type X402ClientConfig, type X402Domain, X402Error, type X402MiddlewareConfig, X402_DOMAIN_NAME, X402_HEADERS, X402_VERSION, calculateDeadline, createCaipId, extractChainId, generateNonce };