@aeon-ai-pay/aigateway 0.1.0

package/src/x402.mjs

@@ -0,0 +1,120 @@
+/**
+ * x402 协议客户端：初始化 EVM signer + x402Client
+ */
+import { x402Client, wrapAxiosWithPayment, x402HTTPClient } from "@aeon-ai-pay/axios";
+import { registerExactEvmScheme } from "@aeon-ai-pay/evm/exact/client";
+import { toClientEvmSigner } from "@aeon-ai-pay/evm";
+import { privateKeyToAccount } from "viem/accounts";
+import { createWalletClient, http, publicActions, formatUnits } from "viem";
+import { bsc } from "viem/chains";
+import { BSC_RPC_URL } from "./constants.mjs";
+import axios from "axios";
+
+/**
+ * 创建已注册 EVM 签名的 x402 axios 客户端
+ * @param {`0x${string}`} privateKey - EVM 私钥
+ * @returns {{ api: AxiosInstance, client: x402Client, address: string, getOrderNo: () => string|null }}
+ */
+export function createX402Api(privateKey) {
+  const evmAccount = privateKeyToAccount(privateKey);
+  const walletClient = createWalletClient({
+    account: evmAccount,
+    chain: bsc,
+    transport: http(BSC_RPC_URL),
+  }).extend(publicActions);
+
+  const evmSigner = toClientEvmSigner({
+    address: evmAccount.address,
+    signTypedData: (message) => evmAccount.signTypedData(message),
+    readContract: (args) =>
+      walletClient.readContract({ ...args, args: args.args || [] }),
+    sendTransaction: (args) =>
+      walletClient.sendTransaction({ to: args.to, data: args.data }),
+    waitForTransactionReceipt: (args) =>
+      walletClient.waitForTransactionReceipt(args),
+  });
+
+  const client = new x402Client();
+  registerExactEvmScheme(client, { signer: evmSigner });
+
+  const axiosInstance = axios.create();
+
+  // 在 wrapAxiosWithPayment 之前注册拦截器，
+  // 从 402 响应体中捕获 orderNo（服务端在 firstRequest 返回）
+  let capturedOrderNo = null;
+  axiosInstance.interceptors.response.use(
+    (response) => response,
+    (error) => {
+      if (error.response?.status === 402 && error.response?.data?.orderNo) {
+        capturedOrderNo = error.response.data.orderNo;
+      }
+      return Promise.reject(error);
+    }
+  );
+
+  const api = wrapAxiosWithPayment(axiosInstance, client);
+
+  return {
+    api,
+    client,
+    address: evmAccount.address,
+    getOrderNo: () => capturedOrderNo,
+  };
+}
+
+/**
+ * 第一次发起 x402 请求（不带签名），从 402 响应中提取实际付款要求。
+ * 同时保留完整的 402 响应数据和原始请求配置，供后续手动签名使用。
+ * 字段名与 x402 v2 PaymentRequirements 标准对齐：asset、payTo、amount。
+ *
+ * 兼容 GET（card 路径）和 POST（image / Skill Boss 路径）。
+ *
+ * @param {string} url
+ * @param {{ method?: "GET"|"POST", data?: any, headers?: object }} [options]
+ * @returns {Promise<{amountUsdt: number, amountWei: string, decimals: number, asset: string, payTo: string, orderNo: string|null, raw402Response: object, requestConfig: object}>}
+ */
+export async function fetchPaymentRequirements(url, options = {}) {
+  const rawClient = axios.create();
+  const method = (options.method || "GET").toUpperCase();
+  try {
+    if (method === "POST") {
+      await rawClient.post(url, options.data, { headers: options.headers });
+    } else {
+      await rawClient.get(url, { headers: options.headers });
+    }
+    throw new Error("Expected HTTP 402 but got 200");
+  } catch (err) {
+    if (err.response?.status !== 402) throw err;
+    const data = err.response.data;
+    const accept = data?.accepts?.[0];
+    if (!accept) throw new Error("No payment requirements in 402 response");
+    const decimals = accept.tokenDecimals || 18;
+    const amountWei = BigInt(accept.amount);
+    const amountUsdt = parseFloat(formatUnits(amountWei, decimals));
+    return {
+      amountUsdt,
+      amountWei: amountWei.toString(),
+      decimals,
+      asset: accept.asset,
+      payTo: accept.payTo,
+      orderNo: data.orderNo || null,
+      raw402Response: err.response,
+      requestConfig: err.config,
+    };
+  }
+}
+
+/**
+ * 从响应头中解码 PAYMENT-RESPONSE（x402 v2）
+ * @param {object} headers - axios response headers
+ * @returns {object|null}
+ */
+export function decodePaymentResponse(headers) {
+  const raw = headers["payment-response"] || headers["PAYMENT-RESPONSE"];
+  if (!raw) return null;
+  try {
+    return JSON.parse(Buffer.from(raw, "base64").toString("utf-8"));
+  } catch {
+    return { raw };
+  }
+}

package/templates/cline/.clinerules

@@ -0,0 +1,53 @@
+# aigateway — Virtual Card via x402
+
+Trigger this rule when the user wants to create / query / manage one-time virtual debit cards funded via USDT on BSC.
+
+## Setup (run once)
+
+```bash
+aigateway wallet-init
+```
+
+`envelope.data.ready === true` means ready.
+
+## Commands
+
+```bash
+aigateway create-card --amount <USD> --poll                      # Create card, poll until ready
+aigateway create-card --amount <USD> --app-id <merchantId> --poll # With merchant app ID
+aigateway create-card-status --order-no <orderNo>                       # Single status query
+aigateway create-card-status --order-no <orderNo> --poll                # Poll until terminal
+aigateway wallet-balance                                            # Show local wallet balance
+aigateway wallet-topup --amount <USDT>                             # WalletConnect: USDT top-up
+aigateway wallet-gas --amount <BNB>                                # WalletConnect: BNB gas top-up
+aigateway wallet-withdraw [--to 0x...] [--amount <USDT>]           # Reclaim funds
+```
+
+## Envelope
+
+stdout = one line of JSON.
+
+- Success: `{ "ok": true, "command": ..., "data": { ... } }`
+- Failure: `{ "ok": false, "command": ..., "error": { "code": ..., "message": ..., ... } }`
+
+Branch on `error.code`. Exit codes: `0`/`1`/`2`/`3`/`4` = success/user/timeout/service/internal.
+
+## Hard Rules
+
+- No private keys from the user.
+- No full card numbers, CVV, or expiry in output (already sanitized).
+- WalletConnect-opening commands (`create-card` / `create-image` when underfunded / `wallet-init` / `wallet-gas`) must run in foreground.
+- No auto-retry on `PAYMENT_REJECTED` or `PAYMENT_TIMEOUT`.
+
+## Recovery Cheatsheet
+
+| Code | Action |
+| --- | --- |
+| `AMOUNT_OUT_OF_RANGE` | Show `error.min`/`error.max`; ask user. |
+| `INSUFFICIENT_USDT` | `aigateway wallet-init` then retry. |
+| `INSUFFICIENT_BNB` | `aigateway wallet-gas` then retry. |
+| `POLL_TIMEOUT` | Note `orderNo`; query later. |
+| `PAYMENT_REJECTED` / `PAYMENT_TIMEOUT` | Ask user before retrying. |
+| `SERVICE_UNAVAILABLE` | Exponential backoff retry. |
+
+Full reference: `docs/output-schema.md`, `docs/exit-codes.md`, `docs/recipes/`.

package/templates/codex/AGENTS.md

@@ -0,0 +1,56 @@
+# aigateway — Virtual Card Agent Rules
+
+When a user asks to **create, query, or manage** a one-time virtual debit card funded with USDT on BSC, use the `aigateway` CLI as the source of truth.
+
+## Setup (run once per environment)
+
+```bash
+aigateway wallet-init
+```
+
+Returns an envelope on stdout; `envelope.data.ready === true` means ready.
+
+## Command Surface
+
+```bash
+aigateway create-card --amount <USD> [--app-id <merchantId>] --poll  # Create card
+aigateway create-card-status --order-no <orderNo> [--poll]                  # Query status
+aigateway wallet-balance                                                # Local balance
+aigateway wallet-topup --amount <USDT>                                 # USDT top-up via WalletConnect
+aigateway wallet-gas --amount <BNB>                                    # BNB top-up via WalletConnect
+aigateway wallet-withdraw [--to 0x...] [--amount <USDT>]               # Reclaim funds
+```
+
+`--app-id` defaults to `TEST000001`. `--quiet` suppresses stderr noise. `--legacy-output` swaps the envelope for the old pre-envelope JSON shape.
+
+## Output Contract
+
+Every command emits **one line of JSON** to stdout (the envelope):
+
+- `{ "ok": true, "command": "...", "data": { ... } }`
+- `{ "ok": false, "command": "...", "error": { "code": "...", "message": "...", ... } }`
+
+Stderr is human-readable progress. Match on `error.code` (stable), not on `error.message`.
+
+Exit codes: `0` success · `1` user · `2` timeout · `3` service/network · `4` internal.
+
+## Hard Rules
+
+- **Never** prompt for private keys. The CLI auto-generates a local session wallet.
+- **Never** display full card numbers, CVV, or expiry. The CLI already redacts these to `•••• 1234`.
+- **Never** run `create-card` / `create-image` / `wallet-init` / `wallet-gas` in the background — they open a WalletConnect QR window.
+- **Never** auto-retry `PAYMENT_REJECTED` or `PAYMENT_TIMEOUT`. Ask the user.
+
+## Error Recovery (high-frequency cases)
+
+| `error.code` | Action |
+| ------------ | ------ |
+| `AMOUNT_OUT_OF_RANGE` | Show `error.min` / `error.max`; re-prompt user. |
+| `INSUFFICIENT_USDT` | Run `aigateway wallet-init`, then re-run create. |
+| `INSUFFICIENT_BNB` | Run `aigateway wallet-gas`, then re-run the failing op. |
+| `POLL_TIMEOUT` | Card may still be provisioning. Note `error.orderNo`. |
+| `PAYMENT_REJECTED` | User cancelled. Ask before retrying. |
+| `PAYMENT_TIMEOUT` | 5-minute approval window expired. Ask before retrying. |
+| `SERVICE_UNAVAILABLE` | Retry with exponential backoff (1s → 4s → 16s, max 3). |
+
+Full schema and recipes: see `docs/output-schema.md`, `docs/exit-codes.md`, and `docs/recipes/`.

package/templates/cursor/.cursor/rules/aigateway.mdc

@@ -0,0 +1,60 @@
+---
+description: Use the aigateway CLI to create and manage one-time virtual debit cards via the x402 payment protocol on BSC. Trigger on intents like "create a card", "buy a virtual card", "card status", "top up", "withdraw funds".
+alwaysApply: false
+---
+
+# aigateway — Virtual Card via x402
+
+Use this rule when the user wants to **create, query, or manage** one-time-use virtual debit cards funded via USDT on BSC.
+
+## First-time setup (always run once)
+
+```bash
+aigateway wallet-init
+```
+
+Auto-creates a local session wallet if missing. Returns an envelope; `envelope.data.ready === true` means ready.
+
+## Commands
+
+| Intent | Command |
+| --- | --- |
+| Create a $N card and poll until ready | `aigateway create-card --amount <N> --poll` |
+| Specify merchant app ID (optional) | `aigateway create-card --amount <N> --app-id <merchantId> --poll` |
+| Check status of an existing order | `aigateway create-card-status --order-no <orderNo>` |
+| Show local wallet balance | `aigateway wallet-balance` |
+| Top up USDT from main wallet (interactive WalletConnect) | `aigateway wallet-topup --amount <USDT>` |
+| Top up BNB for gas (interactive WalletConnect) | `aigateway wallet-gas --amount <BNB>` |
+| Withdraw funds back to main wallet | `aigateway wallet-withdraw [--to 0x...] [--amount <USDT>]` |
+
+## Output Contract
+
+Every command writes **one line of JSON** to stdout: the envelope.
+
+- Success: `{ "ok": true, "command": "...", "data": { ... } }`
+- Failure: `{ "ok": false, "command": "...", "error": { "code": "...", "message": "...", ... } }`
+
+Stderr is human-readable progress; pass `--quiet` if you want it suppressed.
+
+## Error Handling
+
+Branch on `error.code` (stable). Common cases:
+
+- `AMOUNT_OUT_OF_RANGE` — Show valid range from `error.min` / `error.max`, ask user.
+- `INSUFFICIENT_USDT` / `INSUFFICIENT_BNB` — Run `aigateway wallet-init` / `aigateway wallet-gas` then retry.
+- `PAYMENT_REJECTED` / `PAYMENT_TIMEOUT` — User cancelled or didn't respond. **Do not auto-retry**; ask first.
+- `POLL_TIMEOUT` — Card may still be provisioning. Note the `orderNo`, query later.
+- Exit codes: `0` success, `1` user error, `2` timeout, `3` service/network, `4` internal.
+
+## Hard Rules
+
+- **Never** ask the user for a private key — the local wallet is auto-generated.
+- **Never** display the full card number, CVV, or expiry. Output already redacts these to `•••• 1234`.
+- **Never** run `create-card` / `create-image` / `wallet-init` / `wallet-gas` in the background — they may open a WalletConnect QR window that needs user attention.
+- **Never** auto-retry rejected / timed-out signatures.
+
+## Full Reference
+
+- Envelope schema: `docs/output-schema.md`
+- Exit / error codes: `docs/exit-codes.md`
+- Integration recipes: `docs/recipes/`

package/templates/windsurf/.windsurfrules

@@ -0,0 +1,48 @@
+# aigateway — Virtual Card via x402
+
+When the user wants to create / query / manage a one-time virtual debit card funded with USDT on BSC, use the `aigateway` CLI.
+
+## First-time setup (always run once)
+
+```bash
+aigateway wallet-init
+```
+
+`envelope.data.ready === true` means ready.
+
+## Commands
+
+| Intent | Command |
+| --- | --- |
+| Create a $N card and poll until ready | `aigateway create-card --amount <N> --poll` |
+| Specify merchant app ID | `aigateway create-card --amount <N> --app-id <merchantId> --poll` |
+| Check status of an existing order | `aigateway create-card-status --order-no <orderNo>` |
+| Show local wallet balance | `aigateway wallet-balance` |
+| Top up USDT (interactive WalletConnect) | `aigateway wallet-topup --amount <USDT>` |
+| Top up BNB for gas (interactive WalletConnect) | `aigateway wallet-gas --amount <BNB>` |
+| Withdraw funds back to main wallet | `aigateway wallet-withdraw [--to 0x...] [--amount <USDT>]` |
+
+## Output Contract
+
+Every command emits one line of JSON to stdout (the envelope):
+
+- Success: `{ "ok": true, "command": "...", "data": { ... } }`
+- Failure: `{ "ok": false, "command": "...", "error": { "code": "...", "message": "...", ... } }`
+
+Branch on `error.code` (stable). Exit codes: `0` success, `1` user, `2` timeout, `3` service/network, `4` internal.
+
+## Hard Rules
+
+- Never ask for a private key. The local wallet is auto-generated.
+- Never display full card numbers, CVV, or expiry — output is already sanitized.
+- Never run `create-card` / `create-image` / `wallet-init` / `wallet-gas` in the background; they open a QR window requiring user attention.
+- Never auto-retry `PAYMENT_REJECTED` / `PAYMENT_TIMEOUT`.
+
+## Common Recovery
+
+- `AMOUNT_OUT_OF_RANGE` → Show `error.min` / `error.max`, ask for a new amount.
+- `INSUFFICIENT_USDT` → Run `aigateway wallet-init`, then retry create.
+- `INSUFFICIENT_BNB` → Run `aigateway wallet-gas`, then retry the failing op.
+- `POLL_TIMEOUT` → Note `orderNo`, ask user to query later with `aigateway create-card-status --order-no <orderNo>`.
+
+Full reference: `docs/output-schema.md`, `docs/exit-codes.md`, `docs/recipes/`.