@wtflabs/x402-server 0.0.1-beta.8 → 0.0.1-beta.9

package/README.md

@@ -1,313 +1,550 @@
 # @wtflabs/x402-server
 
-X402 支付协议的服务端集成包，整合 facilitator、schema 和 viem client。
+Server SDK for the x402 Payment Protocol. Handles payment verification and settlement with automatic token detection.
 
-## 安装
+## Features
+
+✅ **Simple API** - Just 2 required parameters to get started  
+✅ **Automatic Token Detection** - Built on `@wtflabs/x402-detector`  
+✅ **Payment Processing** - Verify and settle payments via `@wtflabs/x402-facilitator`  
+✅ **Dynamic Requirements** - Create payment requirements on-the-fly  
+✅ **Performance Optimized** - Built-in caching, non-blocking initialization  
+✅ **Framework Middlewares** - Ready-to-use Express and Hono middlewares  
+✅ **Zod Validation** - Runtime type safety for all data  
+✅ **Decoupled Design** - Facilitator and Server are independent
+
+## Installation
 
 ```bash
-npm install @wtflabs/x402-server @wtflabs/x402-facilitator @wtflabs/x402-schema viem
-# 或
-pnpm add @wtflabs/x402-server @wtflabs/x402-facilitator @wtflabs/x402-schema viem
+npm install @wtflabs/x402-server viem
 ```
 
-## 使用
+## Quick Start
+
+### Option 1: Using Middleware (Easiest)
 
 ```typescript
-import { X402Server } from "@wtflabs/x402-server";
+import express from "express";
+import { createExpressMiddleware, 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";
 
-// 创建 facilitator
+const app = express();
+
+// 1. Create facilitator
 const facilitator = new Facilitator({
-  recipientAddress: "0x1234...", // 商家地址 (EIP 7702)
-  relayer: "0x5678...", // 可选，内置 WTF Facilitator
-  waitUntil: "confirmed", // 可选
+  recipientAddress: "0x5D06b8145D908DDb7ca116664Fcf113ddaA4d6F3",
 });
 
-// 创建 schema
-const schema = new X402PaymentSchema({
-  scheme: "exact",
-  network: "bsc-testnet",
-  maxAmountRequired: "100000",
-  resource: "http://localhost:3000/protected-resource",
-  description: "Access to protected resource with EIP-2612 Permit",
-  mimeType: "application/json",
-  payTo: "0x1234...", // 商家地址
-  maxTimeoutSeconds: 3600,
-  asset: "0x5678...", // token address
-  paymentType: "permit", // optional
-  outputSchema: {
-    input: {
-      type: "http",
-      method: "POST",
-      discoverable: true,
-      bodyFields: {},
-    },
-    output: {
-      message: "string",
-      authorizationType: "string",
-      payer: "string",
-    },
-  },
+// 2. Create server
+const server = new X402Server({
+  client: createPublicClient({ chain: bscTestnet, transport: http() }),
+  facilitator,
+});
+
+// 3. Create middleware
+const paymentMiddleware = createExpressMiddleware({
+  server,
+  getToken: () => "0x25d066c4C68C8A6332DfDB4230263608305Ca991", // USDC
+  getAmount: () => "1000",
 });
 
-// 创建 viem public client
-const client = createPublicClient({
-  chain: bscTestnet,
-  transport: http(),
+// 4. Use middleware
+app.post("/api/resource", paymentMiddleware, (req, res) => {
+  const { payer, txHash } = req.x402!;
+  res.json({ data: "resource", payer, txHash });
+});
+```
+
+### Option 2: Manual Processing
+
+```typescript
+import { X402Server } from "@wtflabs/x402-server";
+import { Facilitator } from "@wtflabs/x402-facilitator";
+import { createPublicClient, http } from "viem";
+import { bscTestnet } from "viem/chains";
+
+// 1. Create facilitator
+const facilitator = new Facilitator({
+  recipientAddress: "0x5D06b8145D908DDb7ca116664Fcf113ddaA4d6F3",
+  waitUntil: "confirmed",
 });
 
-// 创建 X402Server
+// 2. Create server instance
 const server = new X402Server({
+  client: createPublicClient({
+    chain: bscTestnet,
+    transport: http(),
+  }),
   facilitator,
-  schema,
-  client,
 });
 
-// 初始化服务器
-const initResult = await server.initialize();
-if (!initResult.success) {
-  console.error("初始化失败:", initResult.error);
-}
+// 3. Optional: Pre-warm cache (non-blocking)
+server.initialize([
+  "0x25d066c4C68C8A6332DfDB4230263608305Ca991", // USDC
+]);
+
+// 4. Handle payment in your route
+app.post("/api/resource", async (req, res) => {
+  // Create payment requirements
+  const requirements = await server.createRequirements({
+    token: "0x25d066c4C68C8A6332DfDB4230263608305Ca991",
+    amount: "1000", // wei
+  });
 
-// 验证配置
-const verifyResult = await server.verify();
-if (!verifyResult.success) {
-  console.error("验证失败:", verifyResult.errors);
-}
+  // Process payment (parse → verify → settle)
+  const result = await server.process(
+    req.headers["x-payment"],
+    requirements
+  );
+
+  if (!result.success) {
+    return res.status(402).json(result.response);
+  }
+
+  // Payment successful!
+  res.json({
+    message: "Access granted",
+    payer: result.data.payer,
+    txHash: result.data.txHash,
+    data: "your protected resource",
+  });
+});
+```
 
-// 验证支付
-const paymentVerifyResult = await server.verifyPayment(
-  paymentPayload,
-  paymentRequirements
-);
+## API Reference
 
-if (paymentVerifyResult.success) {
-  console.log("支付验证成功！支付者:", paymentVerifyResult.payer);
-}
+### Constructor
 
-// 结算支付
-const settleResult = await server.settle(paymentPayload, paymentRequirements);
+```typescript
+const server = new X402Server(config: X402ServerConfig)
+```
 
-if (settleResult.success) {
-  console.log("支付结算成功！交易哈希:", settleResult.transactionHash);
-}
+**Required:**
+- `client: PublicClient` - Viem PublicClient
+- `facilitator: Facilitator` - Facilitator instance
+
+**Optional:**
+- `network?: string` - Network name (auto-detected from client)
+
+**Example:**
+```typescript
+import { Facilitator } from "@wtflabs/x402-facilitator";
+
+// 1. Create facilitator first
+const facilitator = new Facilitator({
+  recipientAddress: "0x...",
+  relayer: "0x...", // optional
+  waitUntil: "confirmed", // optional
+  baseUrl: "https://facilitator.example.com", // optional
+  apiKey: "your-api-key", // optional
+});
+
+// 2. Pass to server
+const server = new X402Server({
+  client: viemClient,
+  facilitator,
+  network: "bsc-testnet", // optional
+});
 ```
 
-## API
+### Methods
 
-### `X402Server`
+#### `initialize(tokens: string[]): Promise<InitResult>`
 
-#### 构造函数
+Pre-warm the token detection cache. Non-blocking, can run in background.
 
 ```typescript
-new X402Server(config: X402ServerConfig)
+// Wait for initialization
+await server.initialize([tokenAddress]);
+
+// Or run in background
+server.initialize([tokenAddress]).then(result => {
+  if (result.success) console.log("✅ Cache ready");
+});
 ```
 
-**配置选项 (`X402ServerConfig`):**
+#### `createRequirements(config): Promise<PaymentRequirements>`
 
-- `facilitator`: Facilitator 实例
-- `schema`: X402PaymentSchema 实例
-- `client`: Viem PublicClient 实例
+Create payment requirements. Supports dynamic amounts and auto-detection.
 
-#### 方法
+```typescript
+const requirements = await server.createRequirements({
+  // Required
+  token: "0x...",
+  amount: "1000", // wei
+
+  // Optional - override global config
+  recipient?: "0x...",
+  network?: "bsc-testnet",
+  paymentType?: "permit" | "eip3009" | "permit2" | "auto",
+  relayer?: "0x...",
+
+  // Optional - resource description
+  resource?: "https://api.example.com/data",
+  description?: "Premium API access",
+  mimeType?: "application/json",
+  timeout?: 300,
+
+  // Optional - performance
+  autoDetect?: true, // false for fast mode
+});
+```
 
-##### `initialize()`
+#### `process(paymentHeader, requirements): Promise<ProcessResult>`
 
-初始化服务器，验证 schema 并添加 facilitator 数据到 schema 的 extra 字段。
+Complete payment processing (parse → verify → settle).
 
-- **返回:** `Promise<InitializeResult>`
+```typescript
+const result = await server.process(
+  request.headers["x-payment"],
+  requirements
+);
 
-##### `verify()`
+if (result.success) {
+  console.log("Payer:", result.data.payer);
+  console.log("TxHash:", result.data.txHash);
+} else {
+  console.log("Error:", result.response.error);
+  // Return 402 with result.response
+}
+```
 
-验证配置是否正确：
+#### Advanced: Step-by-Step Processing
 
-1. **自动检测 token 支持的支付方式** - 检测 token 是否支持 permit、eip3009 或 permit2
-2. **验证 facilitator 支持** - 检查 facilitator 的 `/supported` 接口是否包含该代币和链
-3. **验证链支持** - 检查当前配置的链是否在 facilitator 支持列表中
-4. 检查 client network 是否和 schema 的 network 匹配
-5. 检查 facilitator recipientAddress 是否和 schema payTo 一致
+```typescript
+// 1. Parse payment header
+const parsed = server.parse(paymentHeader, requirements);
+if (!parsed.success) {
+  return res.status(402).json(parsed.response402);
+}
 
-该方法会自动检测代币合约的字节码，判断是否支持以下支付方式：
-- **EIP-2612 Permit** - 通过检查 `permit(address,address,uint256,uint256,uint8,bytes32,bytes32)` 方法
-- **EIP-3009** - 通过检查 `transferWithAuthorization` 方法
-- **Permit2** - 通过检查 Permit2 合约是否部署在当前链上
+// 2. Verify payment
+const verified = await server.verify(parsed.data);
+if (!verified.success) {
+  return res.status(402).json(
+    server.get402Response(requirements, verified.error)
+  );
+}
+console.log("Payer:", verified.payer);
+
+// 3. Settle payment (optional - you can skip this for verify-only mode)
+const settled = await server.settle(parsed.data);
+if (!settled.success) {
+  return res.status(402).json(
+    server.get402Response(requirements, settled.error)
+  );
+}
+console.log("TxHash:", settled.txHash);
+```
+
+### Utility Methods
 
-- **返回:** `Promise<VerifyResult>`
+```typescript
+// Generate 402 response
+const response402 = server.get402Response(requirements, error?);
 
-##### `verifyPayment(paymentPayload, paymentRequirements)`
+// Clear token cache
+await server.clearCache(tokenAddress?); // specific or all
 
-验证支付负载。
+// Get cache stats
+const stats = server.getCacheStats();
+console.log(stats.size, stats.keys);
+```
 
-- **参数:**
-  - `paymentPayload`: 支付负载
-  - `paymentRequirements`: 支付要求
-- **返回:** `Promise<{ success: boolean; payer?: string; error?: string }>`
+## Usage Examples
 
-##### `settle(paymentPayload, paymentRequirements)`
+### Example 1: Fixed Amount
 
-结算支付。
+```typescript
+const server = new X402Server({ client, recipient });
 
-- **参数:**
-  - `paymentPayload`: 支付负载
-  - `paymentRequirements`: 支付要求
-- **返回:** `Promise<SettleResult>`
+// Pre-warm cache (optional)
+await server.initialize(["0xUSDC"]);
 
-##### `getFacilitator()`
+// Fixed requirements
+const requirements = await server.createRequirements({
+  token: "0xUSDC",
+  amount: "1000",
+  description: "Access to premium API",
+});
 
-获取 facilitator 实例。
+app.post("/premium-api", async (req, res) => {
+  const result = await server.process(req.headers["x-payment"], requirements);
+  
+  if (!result.success) {
+    return res.status(402).json(result.response);
+  }
+  
+  res.json({ data: "premium content" });
+});
+```
 
-- **返回:** `Facilitator`
+### Example 2: Dynamic Pricing
 
-##### `getSchema()`
+```typescript
+app.post("/api/compute", async (req, res) => {
+  const { complexity } = req.body;
+  
+  // Calculate price based on complexity
+  const price = calculatePrice(complexity);
+  
+  // Dynamic requirements
+  const requirements = await server.createRequirements({
+    token: "0xUSDC",
+    amount: price,
+    description: `Compute task (${complexity})`,
+  });
+  
+  const result = await server.process(req.headers["x-payment"], requirements);
+  
+  if (!result.success) {
+    return res.status(402).json(result.response);
+  }
+  
+  // Execute computation
+  const computeResult = await performComputation(complexity);
+  res.json({ result: computeResult, paid: price });
+});
+```
 
-获取 schema 实例。
+### Example 3: Multiple Tokens
 
-- **返回:** `X402PaymentSchema`
+```typescript
+const server = new X402Server({ client, recipient });
+
+// Pre-warm multiple tokens
+await server.initialize(["0xUSDC", "0xDAI", "0xUSDT"]);
+
+app.get("/premium-api", async (req, res) => {
+  // Return multiple payment options
+  const accepts = await Promise.all([
+    server.createRequirements({ token: "0xUSDC", amount: "1000" }),
+    server.createRequirements({ token: "0xDAI", amount: "1000" }),
+    server.createRequirements({ token: "0xUSDT", amount: "1000" }),
+  ]);
+  
+  res.status(402).json({
+    x402Version: 1,
+    accepts,
+  });
+});
 
-##### `getClient()`
+app.post("/premium-api", async (req, res) => {
+  // User pays with their chosen token
+  const parsed = server.parse(req.headers["x-payment"], accepts[0]);
+  if (!parsed.success) {
+    return res.status(402).json(parsed.response402);
+  }
+  
+  // Detect which token was used
+  const tokenUsed = parsed.data.payload.payload.authorization.token;
+  
+  // Create matching requirements
+  const requirements = await server.createRequirements({
+    token: tokenUsed,
+    amount: "1000",
+  });
+  
+  const result = await server.process(req.headers["x-payment"], requirements);
+  // ...
+});
+```
 
-获取 viem client 实例。
+### Example 4: Fast Mode (Skip Detection)
 
-- **返回:** `PublicClient`
+```typescript
+// For maximum performance, skip auto-detection
+const requirements = await server.createRequirements({
+  token: "0xUSDC",
+  amount: "1000",
+  paymentType: "permit", // Manually specify
+  autoDetect: false, // Skip detection (<1ms)
+});
+```
 
-##### `isInitialized()`
+## Framework Integration
 
-检查服务器是否已初始化。
+### Express
 
-- **返回:** `boolean`
+```typescript
+import express from "express";
+import { X402Server } from "@wtflabs/x402-server";
 
-### Token 检测工具
+const app = express();
+const server = new X402Server({ client, recipient });
 
-#### `detectTokenPaymentMethods(tokenAddress, client)`
+app.post("/api/resource", async (req, res) => {
+  const requirements = await server.createRequirements({
+    token: "0xUSDC",
+    amount: "1000",
+  });
+  
+  const result = await server.process(req.headers["x-payment"], requirements);
+  
+  if (!result.success) {
+    return res.status(402).json(result.response);
+  }
+  
+  res.json({ data: "resource" });
+});
+```
 
-独立的 token 支付方式检测工具函数，可以在不创建完整 server 实例的情况下使用。
+### Hono
 
 ```typescript
-import { detectTokenPaymentMethods } from "@wtflabs/x402-server";
-import { createPublicClient, http } from "viem";
-import { bscTestnet } from "viem/chains";
+import { Hono } from "hono";
+import { X402Server } from "@wtflabs/x402-server";
 
-const client = createPublicClient({
-  chain: bscTestnet,
-  transport: http(),
+const app = new Hono();
+const server = new X402Server({ client, recipient });
+
+app.post("/api/resource", async (c) => {
+  const requirements = await server.createRequirements({
+    token: "0xUSDC",
+    amount: "1000",
+  });
+  
+  const result = await server.process(c.req.header("x-payment"), requirements);
+  
+  if (!result.success) {
+    return c.json(result.response, 402);
+  }
+  
+  return c.json({ data: "resource" });
 });
+```
 
-const capabilities = await detectTokenPaymentMethods(
-  "0x25d066c4C68C8A6332DfDB4230263608305Ca991",
-  client
-);
+### Next.js API Route
 
-console.log("支持的支付方式:", capabilities.supportedMethods);
-// 输出: ['permit'] 或 ['eip3009'] 或 ['permit2', 'permit2-witness']
+```typescript
+import { X402Server } from "@wtflabs/x402-server";
+import { NextRequest } from "next/server";
 
-console.log("检测详情:", capabilities.details);
-// {
-//   hasEIP3009: false,
-//   hasPermit: true,
-//   hasPermit2Approval: true
-// }
+const server = new X402Server({ client, recipient });
+
+export async function POST(req: NextRequest) {
+  const requirements = await server.createRequirements({
+    token: "0xUSDC",
+    amount: "1000",
+  });
+  
+  const result = await server.process(
+    req.headers.get("x-payment") || undefined,
+    requirements
+  );
+  
+  if (!result.success) {
+    return Response.json(result.response, { status: 402 });
+  }
+  
+  return Response.json({ data: "resource" });
+}
 ```
 
-- **参数:**
-  - `tokenAddress`: token 合约地址
-  - `client`: Viem PublicClient 实例
-- **返回:** `Promise<TokenPaymentCapabilities>`
+## Performance
+
+| Operation | First Call | Cached Call |
+|-----------|-----------|-------------|
+| `createRequirements(autoDetect: true)` | 2-5s | <1ms |
+| `createRequirements(autoDetect: false)` | <1ms | <1ms |
+| `process()` | 2-5s + network | <1ms + network |
 
-#### `getRecommendedPaymentMethod(capabilities)`
+**Tips:**
+- Use `initialize()` on startup to pre-warm cache
+- Set `autoDetect: false` for maximum speed (requires manual `paymentType`)
+- Cache persists for the lifetime of the server instance
 
-根据检测结果获取推荐的支付方式（按优先级：permit2 > eip3009 > permit）。
+## Error Handling
 
 ```typescript
-import { getRecommendedPaymentMethod } from "@wtflabs/x402-server";
+const result = await server.process(paymentHeader, requirements);
 
-const recommended = getRecommendedPaymentMethod(capabilities);
-console.log("推荐使用:", recommended); // 'permit2' | 'eip3009' | 'permit' | null
+if (!result.success) {
+  // 402 response with error details
+  console.log(result.response.error);
+  return res.status(402).json(result.response);
+}
+
+// Success!
+console.log(result.data.payer);
+console.log(result.data.txHash);
 ```
 
-- **参数:**
-  - `capabilities`: 从 `detectTokenPaymentMethods` 返回的检测结果
-- **返回:** `PaymentMethod | null`
+## TypeScript Support
 
-#### 类型定义
+Full TypeScript support with comprehensive type definitions:
 
 ```typescript
-type PaymentMethod = "eip3009" | "permit" | "permit2" | "permit2-witness";
-
-interface TokenPaymentCapabilities {
-  address: string;
-  supportedMethods: PaymentMethod[];
-  details: {
-    hasEIP3009: boolean;
-    hasPermit: boolean;
-    hasPermit2Approval: boolean;
-  };
-}
+import type {
+  X402ServerConfig,
+  CreateRequirementsConfig,
+  PaymentRequirements,
+  ProcessResult,
+  InitResult,
+} from "@wtflabs/x402-server";
 ```
 
-## 完整示例
+## Middlewares
 
-```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";
+### Express Middleware
 
-async function main() {
-  // 1. 创建 facilitator
-  const facilitator = new Facilitator({
-    recipientAddress: "0x1234567890123456789012345678901234567890",
-    waitUntil: "confirmed",
-  });
+```typescript
+import { createExpressMiddleware } from "@wtflabs/x402-server";
+
+const middleware = createExpressMiddleware({
+  server,
+  getToken: (req) => req.body.token,
+  getAmount: (req) => calculatePrice(req.body),
+  onPaymentSuccess: async (req, payer, txHash) => {
+    console.log(`Payment from ${payer}: ${txHash}`);
+  },
+});
 
-  // 2. 创建 schema
-  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: "0x1234567890123456789012345678901234567890",
-    maxTimeoutSeconds: 3600,
-    asset: "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
-    paymentType: "permit",
-  });
+app.post("/api", middleware, (req, res) => {
+  const { payer, txHash } = req.x402!;
+  res.json({ data: "resource", payer, txHash });
+});
+```
 
-  // 3. 创建 viem client
-  const client = createPublicClient({
-    chain: bscTestnet,
-    transport: http(),
-  });
+### Hono Middleware
 
-  // 4. 创建服务器
-  const server = new X402Server({
-    facilitator,
-    schema,
-    client,
-  });
+```typescript
+import { createHonoMiddleware } from "@wtflabs/x402-server";
+
+const middleware = createHonoMiddleware({
+  server,
+  getToken: async (c) => (await c.req.json()).token,
+  getAmount: async (c) => calculatePrice(await c.req.json()),
+  onPaymentSuccess: async (c, payer, txHash) => {
+    console.log(`Payment from ${payer}: ${txHash}`);
+  },
+});
 
-  // 5. 初始化
-  await server.initialize();
+app.post("/api", middleware, (c) => {
+  const x402 = c.get("x402")!;
+  return c.json({ data: "resource", payer: x402.payer });
+});
+```
 
-  // 6. 验证配置
-  const verifyResult = await server.verify();
-  console.log("验证结果:", verifyResult);
+**See [MIDDLEWARES.md](./MIDDLEWARES.md) for detailed guide.**
 
-  // 7. 处理支付
-  // const settleResult = await server.settle(
-  //   paymentPayload,
-  //   paymentRequirements
-  // );
-}
+## Documentation
 
-main();
-```
+- **[README.md](./README.md)** - This file
+- **[QUICK-START.md](./QUICK-START.md)** - 5-minute quick start guide
+- **[USAGE.md](./USAGE.md)** - Detailed usage documentation
+- **[MIDDLEWARES.md](./MIDDLEWARES.md)** - Express and Hono middleware guide
+- **[ZOD-VALIDATION.md](./ZOD-VALIDATION.md)** - Zod validation explained
+- **[ARCHITECTURE.md](./ARCHITECTURE.md)** - Architecture and design
+- **[examples/](./examples/)** - Complete examples
 
 ## License
 
 Apache-2.0
 
+## Related Packages
+
+- `@wtflabs/x402-detector` - Token detection (used internally)
+- `@wtflabs/x402-facilitator` - Payment processing (used internally)
+- `@wtflabs/x402-fetch` - Client SDK
+- `@wtflabs/x402` - Core protocol types