@keelcodes/x402-gate 0.1.0 → 0.1.2

package/README.md

@@ -53,7 +53,7 @@ export const GET = withX402(gateOptions, async () => Response.json({ price: 42 }
 | `paymentsUrl` | 支付引擎地址（自建或 `https://keel.codes/v1/payment`） |
 | `paymentsKey` | 支付引擎 Bearer key |
 | `payTo` | 收款地址（B 端自己的钱包；资金直达，不经平台） |
-| `amount` | 单次价格（最小单位）；也可用 `amountFor(path)` 动态定价 |
+| `amount` | 单次价格（最小单位）；也可用 `amountFor(path, req)` 动态定价（A7.9.3：`req.query` 可取 `limit` 做阶梯）。不填时从第一个带 `amount` 的 accept 取价（`0.1.1` 起；再没有就**直接报错**，不会静默免费放行） |
 | `accepts` | 多链多资产；每项二选一：`eip3009: { name, version }` 或 `permit2: true` |
 | `exempt` | 免费路径前缀（默认已含 `/health`、`/metrics`） |
 | `passthroughHeaders` | 额外视为「已有平台凭证」的头（如 `x-tenant-id`） |
@@ -100,10 +100,55 @@ const gate = createX402Gate({
 > `X-PAYMENT-RESPONSE`。`PAYMENT-REQUIRED` 头始终是 v2。
 
 ```ts
-const keel = new KeelClient({
-  x402: { address, signTypedData, signPermit2TypedData },
+import { Keel } from '@keelcodes/sdk'
+
+const keel = new Keel({
+  baseUrl: 'https://api.example', // 收费服务端（不是支付引擎）
+  x402: {
+    address: wallet.account.address, // viem WalletClient
+    signTypedData: (typed) => wallet.signTypedData(typed),
+    maxAmount: '2000', // 单笔上限（最小单位），超过直接拒付
+  },
 })
-await keel.get('https://api.example/quote') // 402 → 签名 → 重试 → 200
+await keel.request('GET', '/quote') // 402 → 签名 → 重试 → 200
+```
+
+### 可运行 demo（agent 自付，零资金）
+
+`projects/keel-sdk/examples/agent-autopay-demo.mjs` 把上面这条链路跑通，默认**全本地、离线、不上链**：
+
+```bash
+cd projects/x402-gate && npm run build
+cd ../keel-sdk && npm run build && node examples/agent-autopay-demo.mjs
+```
+
+输出依次覆盖：免费路径放行 → 未付款拿 `402`（v1 体 + v2 `PAYMENT-REQUIRED` 头 + `links`） →
+Keel 自动签名重试 `200` → 超出 `maxAmount` 时拒付。demo 内置 mock facilitator，
+只验 EIP-712 签名并回一个假 `transaction`，所以**不需要真钱包余额、也不需要 gas**。
+
+接真环境时换成真收款地址/真付款私钥/真支付引擎（此时不再起本地服务）：
+
+```bash
+PAYMENTS_URL=https://keel.codes/v1/payment \
+GATE_URL=https://your-service.example \
+PAYER_PRIVATE_KEY=0x... PAY_TO=0x... \
+node examples/agent-autopay-demo.mjs
+```
+
+demo 只演示 EIP-3009 轨（Base USDC）；BSC USDT/USDC 走 Permit2 时，同一份代码由 SDK
+自动改签 Permit2（`extra.assetTransferMethod=permit2`），首次使用需先按
+「Permit2 预算」授权一次（见下）。
+
+### Permit2 预算（授权上限）
+
+Permit2 轨下，付款人要先给 **canonical Permit2 合约**（不是 proxy）一笔 ERC-20 allowance，
+这笔额度就是链上硬上限；`approve` 是覆盖写，撤销 = `approve(Permit2, 0)`：
+
+```bash
+cd projects/payment/payments
+npx tsx scripts/permit2-budget.ts --chain bsc --budget 5        # dry-run，只打印 calldata
+npx tsx scripts/permit2-budget.ts --chain bsc --budget 5 --broadcast   # 真广播
+npx tsx scripts/permit2-budget.ts --chain bsc --revoke --broadcast     # 撤销
 ```
 
 ## 状态码

package/dist/index.d.ts

@@ -121,8 +121,8 @@ export interface X402GateOptions {
     accepts?: X402GateAccept[];
     /** 命中这些路径前缀的请求不收费（探针/文档） */
     exempt?: string[];
-    /** 按请求覆盖价格（最小单位）；返回 null 表示不收费 */
-    amountFor?: (path: string) => string | null;
+    /** 按请求覆盖价格（最小单位）；返回 null 表示不收费。A7.9.3：第二参可读 query 做 limit 阶梯 */
+    amountFor?: (path: string, req: GateRequest) => string | null;
     /** 额外视为「已有平台凭证」的请求头（如 x-tenant-id） */
     passthroughHeaders?: string[];
     /** 资源元数据（写进 402 的 resource；B13.1 目录展示用） */
@@ -145,6 +145,8 @@ export interface GateRequest {
     path: string;
     url: string;
     header: (name: string) => string | null;
+    /** 查询串（A7.9.3：`amountFor` 按 `limit` 阶梯计价用） */
+    query?: URLSearchParams;
     /** 调用方地址（免费额度分桶用；缺省视为同一桶） */
     ip?: string;
 }

package/dist/index.js

@@ -59,10 +59,13 @@ function buildAccepts(opts, amount) {
             const target = a.payTo ?? opts.payTo;
             if (!target)
                 throw new Error('x402 gate: payTo is required (top-level or per accept)');
+            const priced = a.amount ?? amount;
+            if (!priced)
+                throw new Error('x402 gate: every accept needs an `amount` (or a top-level amount)');
             const base = {
                 scheme: 'exact',
                 network: a.network,
-                amount: a.amount ?? amount,
+                amount: priced,
                 asset: a.asset,
                 payTo: target,
                 maxTimeoutSeconds: a.maxTimeoutSeconds ?? 300,
@@ -206,6 +209,15 @@ function hasPlatformCredential(req, extra) {
         return typeof v === 'string' && v.trim().length > 0;
     });
 }
+/**
+ * 本次调用的价格（最小单位）。
+ * 优先级：`amountFor(path, req)` > 顶层 `amount` > 第一个带价格的 accept。
+ * 只配 `accepts`（多币种）而不写顶层 `amount` 是文档里的标准用法，必须从 accept 取价，
+ * 否则 `amount` 为 undefined 会命中下面的「不收费」分支，等于整站免费。
+ */
+function resolveAmount(opts) {
+    return opts.amount ?? opts.accepts?.find((a) => a.amount)?.amount;
+}
 /**
  * 网关核心：返回「放行」或「402 挑战」，与框架无关。
  * 结算失败一律 402（携带原因），避免把上游错误变成 500。
@@ -216,9 +228,13 @@ async function authorizeX402(opts, req) {
         return { action: 'pass' };
     if (hasPlatformCredential(req, opts.passthroughHeaders ?? []))
         return { action: 'pass' };
-    const amount = opts.amountFor ? opts.amountFor(req.path) : opts.amount;
-    if (!amount)
+    const amount = opts.amountFor ? opts.amountFor(req.path, req) : resolveAmount(opts);
+    // `amountFor` 返回 null = 该路径明确免费；但「压根没配价格」必须报错，
+    // 不能静默放行（否则漏配一个 amount 就等于整站免费）。
+    if (amount === null)
         return { action: 'pass' };
+    if (!amount)
+        throw new Error('x402 gate: no price configured (set `amount` or a priced accept)');
     const signature = paymentSignature(req);
     // 免费额度：只对「本来要收费、且没带付款凭证」的请求计数；已付款的正常走结算。
     if (opts.freeQuota && !signature) {
@@ -346,6 +362,7 @@ function withX402(opts, handler) {
         const result = await authorizeX402(opts, {
             path: parsed.pathname,
             url,
+            query: parsed.searchParams,
             ip: request.headers.get('x-forwarded-for')?.split(',')[0]?.trim() || undefined,
             header: (name) => request.headers.get(name),
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keelcodes/x402-gate",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Keel x402 v2 resource gate — Express / Fetch / Next.js adapters (no keys, no chain access)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -8,7 +8,8 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "dist"