@wtflabs/x402-server 0.0.1-beta.2

package/dist/index.d.ts

@@ -0,0 +1,221 @@
+import { Facilitator } from '@wtflabs/x402-facilitator';
+import { X402PaymentSchema } from '@wtflabs/x402-schema';
+import { PublicClient } from 'viem';
+import { PaymentPayload, PaymentRequirements } from '@wtflabs/x402/types';
+
+/**
+ * X402Server 配置选项
+ */
+interface X402ServerConfig {
+    /**
+     * Facilitator 实例
+     */
+    facilitator: Facilitator;
+    /**
+     * Payment Schema 实例
+     */
+    schema: X402PaymentSchema;
+    /**
+     * Viem Public Client 实例
+     */
+    client: PublicClient;
+}
+/**
+ * 初始化结果
+ */
+interface InitializeResult {
+    success: boolean;
+    error?: string;
+}
+/**
+ * 验证结果
+ */
+interface VerifyResult {
+    success: boolean;
+    errors?: string[];
+}
+/**
+ * 结算结果
+ */
+interface SettleResult {
+    success: boolean;
+    transactionHash?: string;
+    error?: string;
+}
+
+/**
+ * X402Server 类
+ * 集成 facilitator, schema 和 client，提供完整的服务端支付处理
+ *
+ * @example
+ * ```typescript
+ * import { X402Server } from "@wtflabs/x402-server";
+ * import { Facilitator } from "@wtflabs/x402-facilitator";
+ * import { X402PaymentSchema } from "@wtflabs/x402-schema";
+ * import { createPublicClient, http } from "viem";
+ * import { bscTestnet } from "viem/chains";
+ *
+ * const facilitator = new Facilitator({
+ *   recipientAddress: "0x1234...",
+ * });
+ *
+ * const schema = new X402PaymentSchema({
+ *   scheme: "exact",
+ *   network: "bsc-testnet",
+ *   maxAmountRequired: "100000",
+ *   resource: "http://localhost:3000/protected-resource",
+ *   description: "Access to protected resource",
+ *   mimeType: "application/json",
+ *   payTo: "0x1234...",
+ *   maxTimeoutSeconds: 3600,
+ *   asset: "0x5678...",
+ * });
+ *
+ * const client = createPublicClient({
+ *   chain: bscTestnet,
+ *   transport: http(),
+ * });
+ *
+ * const server = new X402Server({
+ *   facilitator,
+ *   schema,
+ *   client,
+ * });
+ *
+ * // 初始化和校验
+ * await server.initialize();
+ *
+ * // 验证
+ * const verifyResult = await server.verify();
+ *
+ * // 结算
+ * const settleResult = await server.settle(paymentPayload, paymentRequirements);
+ * ```
+ */
+declare class X402Server {
+    private facilitator;
+    private schema;
+    private client;
+    private initialized;
+    constructor(config: X402ServerConfig);
+    /**
+     * 初始化服务器
+     * 初始化和校验 schema 等数据，对 schema 增加 facilitator 数据 extra: {relayer}
+     * 并获取 token 的 name 和 version 信息
+     */
+    initialize(): Promise<InitializeResult>;
+    /**
+     * 验证配置
+     * 1. 验证 client network 是否和 schema 的 network 匹配
+     * 2. 验证 facilitator recipientAddress 和 schema payTo 是否一致
+     */
+    _verify(): Promise<VerifyResult>;
+    /**
+     * 结算支付
+     * @param paymentPayload 支付负载
+     * @param paymentRequirements 支付要求
+     */
+    settle(paymentPayload: any, paymentRequirements: any): Promise<SettleResult>;
+    /**
+     * 验证支付负载
+     * @param paymentPayload 支付负载
+     * @param paymentRequirements 支付要求
+     */
+    verifyPayment(paymentPayload: any, paymentRequirements: any): Promise<{
+        success: boolean;
+        data?: string;
+        error?: string;
+    }>;
+    /**
+     * 获取 facilitator
+     */
+    getFacilitator(): Facilitator;
+    /**
+     * 获取 schema
+     */
+    getSchema(): X402PaymentSchema;
+    /**
+     * 获取 client
+     */
+    getClient(): PublicClient;
+    /**
+     * 检查是否已初始化
+     */
+    isInitialized(): boolean;
+    /**
+     * 验证网络是否匹配
+     * @param schemaNetwork schema 中的 network
+     * @param clientChainId client 的 chainId
+     * @returns 是否匹配
+     */
+    private validateNetwork;
+    /**
+     * 解析支付 header
+     * @param paymentHeaderBase64 Base64 编码的支付 header
+     * @returns 解析结果，成功时返回 paymentPayload 和 paymentRequirements，失败时返回服务端的支付要求
+     */
+    parsePaymentHeader(paymentHeaderBase64: string): {
+        success: true;
+        data: {
+            paymentPayload: PaymentPayload;
+            paymentRequirements: PaymentRequirements;
+        };
+    } | {
+        success: false;
+        data: PaymentRequirements;
+        error: string;
+    };
+    /**
+     * 验证客户端的支付数据是否与服务端要求一致
+     * @param paymentPayload 客户端的支付负载
+     * @param paymentRequirements 服务端的支付要求
+     * @returns 错误信息，如果验证通过则返回 null
+     */
+    private validatePaymentPayload;
+}
+
+/**
+ * Token 信息
+ */
+interface TokenInfo {
+    name: string;
+    version: string;
+}
+/**
+ * 支持的支付方式
+ */
+type PaymentMethod = "eip3009" | "permit" | "permit2" | "permit2-witness";
+/**
+ * 检测结果
+ */
+interface TokenPaymentCapabilities {
+    address: string;
+    supportedMethods: PaymentMethod[];
+    details: {
+        hasEIP3009: boolean;
+        hasPermit: boolean;
+        hasPermit2Approval: boolean;
+    };
+}
+/**
+ * 检测代币支持的支付方式
+ * @param tokenAddress 代币地址
+ * @param client viem PublicClient
+ * @returns 检测结果
+ */
+declare function detectTokenPaymentMethods(tokenAddress: string, client: PublicClient): Promise<TokenPaymentCapabilities>;
+/**
+ * 获取推荐的支付方式（仅返回 schema 支持的类型）
+ * 按优先级排序：eip3009 > permit > permit2
+ * 注意：permit2-witness 会被映射为 permit2，因为它们在 schema 中是同一种支付类型
+ */
+declare function getRecommendedPaymentMethod(capabilities: TokenPaymentCapabilities): "eip3009" | "permit2" | "permit" | null;
+/**
+ * 获取 token 的 name 和 version 信息（用于 EIP-712 签名）
+ * @param tokenAddress 代币地址
+ * @param client viem PublicClient
+ * @returns Token 的 name 和 version
+ */
+declare function getTokenInfo(tokenAddress: string, client: PublicClient): Promise<TokenInfo>;
+
+export { type InitializeResult, type PaymentMethod, type SettleResult, type TokenInfo, type TokenPaymentCapabilities, type VerifyResult, X402Server, type X402ServerConfig, detectTokenPaymentMethods, getRecommendedPaymentMethod, getTokenInfo };