@aeon-ai-pay/aigateway 0.1.3 → 0.1.5

package/src/commands/wallet-withdraw.mjs

@@ -1,5 +1,5 @@
 /**
- * withdraw 命令：将 session key 中的资金转回主钱包（USDT + BNB）
+ * wallet-withdraw: move the session key's funds (USDT + BNB) back to the main wallet.
  */
 import { createPublicClient, createWalletClient, http, parseUnits, formatUnits, encodeFunctionData } from "viem";
 import { privateKeyToAccount } from "viem/accounts";
@@ -54,7 +54,7 @@ export async function withdraw(opts) {
 
   const isWithdrawAll = !opts.amount;
 
-  // 无任何资金
+  // No funds at all
   if (balance.usdtRaw === 0n && balance.bnbRaw === 0n) {
     emitErr("wallet-withdraw", "NO_FUNDS", { message: "No funds to withdraw.", appId });
     return;
@@ -63,9 +63,9 @@ export async function withdraw(opts) {
   let usdtTxHash = null;
   let bnbTxHash = null;
 
-  // 1. 赎回 USDT（有 USDT 才执行）
+  // 1. Reclaim USDT (only when USDT balance > 0)
   if (balance.usdtRaw > 0n) {
-    // USDT 转账需要 BNB 作 gas
+    // USDT transfer needs BNB for gas
     if (balance.bnbRaw === 0n) {
       emitErr("wallet-withdraw", "INSUFFICIENT_BNB", {
         message: "No BNB for gas. Withdraw is a normal on-chain transfer and requires BNB to pay gas.",
@@ -119,7 +119,7 @@ export async function withdraw(opts) {
     }
   }
 
-  // 2. 赎回剩余 BNB（仅赎回全部时）
+  // 2. Reclaim remaining BNB (only when withdrawing everything)
   if (isWithdrawAll) {
     const freshBalance = balance.usdtRaw > 0n
       ? await getBalanceByAddress(sessionAddress)
@@ -128,7 +128,7 @@ export async function withdraw(opts) {
     if (freshBalance.bnbRaw > 0n) {
       try {
         const gasPrice = await publicClient.getGasPrice();
-        // 预留 20% buffer 应对 gas price 波动
+        // Reserve a 20% buffer to absorb gas-price fluctuations
         const gasCost = BNB_TRANSFER_GAS * (gasPrice * 120n / 100n);
         const sendable = freshBalance.bnbRaw - gasCost;
 
@@ -159,7 +159,7 @@ export async function withdraw(opts) {
     }
   }
 
-  // 查询最终余额
+  // Final balance lookup
   let finalBalance;
   try {
     finalBalance = await getBalanceByAddress(sessionAddress);

package/src/config.mjs

@@ -1,9 +1,10 @@
 /**
- * 配置管理：~/.aigateway/config.json
- * 优先级：CLI 参数 > 环境变量 > config.json
+ * Config management: ~/.aigateway/config.json
+ * Resolution priority: CLI args > env vars > config.json
  *
- * AEON AI Gateway 统一使用同一个 x402 服务端（ai-api.aeon.xyz），
- * 不同能力（虚拟卡 / Skill Boss 调用）走不同的路径前缀。
+ * AEON AI Gateway uses a single x402 service (ai-api.aeon.xyz);
+ * different capabilities (virtual card / Skill Boss calls) share the host
+ * but use distinct path prefixes.
  */
 import { readFileSync, writeFileSync, mkdirSync, chmodSync } from "fs";
 import { join } from "path";
@@ -31,7 +32,7 @@ export function saveConfig(config) {
 }
 
 /**
- * 解析配置值，优先级：cliValue > envKey > config[configKey]
+ * Resolve a value with priority: cliValue > envKey > config[configKey]
  */
 export function resolve(cliValue, envKey, configKey) {
   if (cliValue) return cliValue;

package/src/error-codes.mjs

@@ -1,16 +1,16 @@
 /**
- * 错误码常量表 —— CLI 与文档的单一事实源
+ * Error-code registry — single source of truth shared by the CLI and the docs.
  *
- * 退出码语义：
- *   0 成功
- *   1 用户错误（参数、余额、配置、用户拒绝）
- *   2 超时（轮询、WalletConnect、签名、链上）
- *   3 服务端 / 网络
- *   4 内部错误
+ * Exit-code semantics:
+ *   0  success
+ *   1  user error (bad argument, insufficient balance, configuration, user reject)
+ *   2  timeout (polling, WalletConnect, signature, on-chain wait)
+ *   3  service / network
+ *   4  internal error
  */
 
 export const ERROR_CODES = {
-  // ===== 用户错误（exit 1）=====
+  // ===== User error (exit 1) =====
   WALLET_NOT_CONFIGURED:  { exit: 1, message: "Wallet not configured. Run: aigateway wallet-init" },
   SERVICE_URL_MISSING:    { exit: 1, message: "Service URL not configured." },
   AMOUNT_INVALID:         { exit: 1, message: "Invalid amount." },
@@ -25,13 +25,13 @@ export const ERROR_CODES = {
   TOPUP_AMOUNT_TOO_SMALL: { exit: 1, message: "Top-up amount is below the minimum." },
   PAYMENT_REJECTED:       { exit: 1, message: "Payment approval was rejected. Please try again if you'd like to proceed." },
 
-  // ===== 超时（exit 2）=====
+  // ===== Timeout (exit 2) =====
   PAYMENT_TIMEOUT:        { exit: 2, message: "Payment approval timed out. Please try again." },
   WC_SESSION_EXPIRED:     { exit: 2, message: "WalletConnect session expired." },
   POLL_TIMEOUT:           { exit: 2, message: "Polling timed out. Card may still be provisioning." },
   TX_TIMEOUT:             { exit: 2, message: "On-chain transaction timed out." },
 
-  // ===== 服务/网络（exit 3）=====
+  // ===== Service / network (exit 3) =====
   SERVICE_UNAVAILABLE:    { exit: 3, message: "Service unavailable or network error." },
   PAYMENT_FETCH_FAILED:   { exit: 3, message: "Failed to fetch payment requirements." },
   BALANCE_CHECK_FAILED:   { exit: 3, message: "Failed to check balance." },
@@ -44,7 +44,7 @@ export const ERROR_CODES = {
   IMAGE_DOWNLOAD_FAILED:  { exit: 3, message: "Image download failed." },
   FUNDING_FAILED:         { exit: 3, message: "Funding flow failed." },
 
-  // ===== 内部（exit 4）=====
+  // ===== Internal (exit 4) =====
   INTERNAL_ERROR:         { exit: 4, message: "Internal error." },
   WALLET_ERROR:           { exit: 1, message: "Wallet operation failed." },
 };

package/src/output.mjs

@@ -1,12 +1,13 @@
 /**
- * 统一输出封装：envelope JSON + 分级日志
+ * Unified output envelope: JSON on stdout + tiered stderr logs.
  *
- * stdout: 一行最终 JSON（machine-readable）
- *   - 成功：{ ok: true, command, version, data }
- *   - 失败：{ ok: false, command, version, error: { code, message, ...context } }
- * stderr: 进度日志（human-readable，agent 可忽略）
+ * stdout: a single line of final JSON (machine-readable)
+ *   - success: { ok: true, command, version, data }
+ *   - failure: { ok: false, command, version, error: { code, message, ...context } }
+ * stderr: progress logs (human-readable; agents can ignore them)
  *
- * --legacy-output 模式：保留旧裸字段格式，便于已按旧 JSON 解析的脚本/agent 平滑过渡。
+ * --legacy-output mode: emit the pre-envelope shape so scripts / agents that
+ * already parse the old JSON can migrate gradually.
  */
 
 import { readFileSync } from "fs";
@@ -30,10 +31,11 @@ export function isLegacyMode() { return LEGACY_MODE; }
 export function isVerboseMode() { return VERBOSE_MODE; }
 
 /**
- * 输出成功结果。调用方应在调用后让函数自然返回（不要再 process.exit）。
- * @param {string} command - 命令名，如 "create-card" / "wallet-init"
- * @param {object} data - envelope 模式下放在 data 字段
- * @param {object} [legacyShape] - legacy 模式下直接输出的旧格式对象；省略则使用 data 本身
+ * Emit a success result. Callers should let the function return naturally
+ * (do not call process.exit afterwards).
+ * @param {string} command - command name, e.g. "create-card" / "wallet-init"
+ * @param {object} data - placed under envelope.data
+ * @param {object} [legacyShape] - the legacy-mode payload; if omitted, `data` is used
  */
 export function emitOk(command, data, legacyShape) {
   if (LEGACY_MODE) {
@@ -44,10 +46,11 @@ export function emitOk(command, data, legacyShape) {
 }
 
 /**
- * 输出错误并退出（按错误码对应的 exit 码）。
+ * Emit an error and exit with the corresponding exit code.
  * @param {string} command
- * @param {string} code - ERROR_CODES 键名
- * @param {object} [details] - 额外字段。message 字段会覆盖默认 message；legacy 字段在 legacy 模式下完全替代输出
+ * @param {string} code - key of ERROR_CODES
+ * @param {object} [details] - extra fields. `message` overrides the default message;
+ *   `legacy` fully replaces the output in legacy mode.
  */
 export function emitErr(command, code, details = {}) {
   const info = ERROR_CODES[code] || ERROR_CODES.INTERNAL_ERROR;
@@ -69,17 +72,17 @@ export function emitErr(command, code, details = {}) {
   process.exit(exit);
 }
 
-/** 进度日志（quiet 模式压制） */
+/** Progress log (suppressed in quiet mode) */
 export function logInfo(msg) {
   if (!QUIET_MODE) console.error(msg);
 }
 
-/** 详细日志（仅 verbose 模式下输出） */
+/** Verbose log (only emitted in verbose mode) */
 export function logVerbose(msg) {
   if (VERBOSE_MODE && !QUIET_MODE) console.error(msg);
 }
 
-/** 错误日志（quiet 模式下也会输出） */
+/** Error log (still emitted in quiet mode) */
 export function logError(msg) {
   console.error(msg);
 }

package/src/sanitize.mjs

@@ -1,14 +1,14 @@
 /**
- * 卡片输出脱敏：隐藏敏感卡片信息（完整卡号→末4位、移除CVV、移除有效期）
- * CLI 输出 JSON 供 Agent 解析，Agent 按产品模板展示给用户
+ * Card output sanitisation: redact sensitive card data (truncate the full PAN to its last 4 digits, drop CVV, drop expiry).
+ * The CLI emits JSON for an agent to parse; the agent then renders the product-specific template to the user.
  */
 
-// 需要替换为末4位的字段
+// Fields whose value should be replaced with the last-4 representation
 const CARD_NUMBER_KEYS = new Set([
   "cardnumber", "cardno",
 ]);
 
-// 需要完全移除的字段
+// Fields that must be removed entirely
 const REMOVE_KEYS = new Set([
   "cvv", "cvv2", "cvc", "cvc2", "securitycode",
   "expiry", "expirydate", "expiredate", "cardexpiry",
@@ -16,10 +16,10 @@ const REMOVE_KEYS = new Set([
 ]);
 
 /**
- * 递归脱敏对象：
- * - cardNumber/cardNo → 只保留末4位（"•••• 3398"）
- * - cvv/securityCode → 移除
- * - expiry/expireDate → 移除
+ * Recursively sanitise an object:
+ *   - cardNumber / cardNo → keep only the last four digits ("•••• 3398")
+ *   - cvv / securityCode → drop
+ *   - expiry / expireDate → drop
  */
 export function sanitizeOutput(obj) {
   if (obj === null || obj === undefined) return obj;
@@ -30,15 +30,15 @@ export function sanitizeOutput(obj) {
   for (const [key, value] of Object.entries(obj)) {
     const normalized = key.toLowerCase().replace(/[-_]/g, "");
 
-    // 移除 CVV、有效期等敏感字段
+    // Drop sensitive fields (CVV, expiry, etc.)
     if (REMOVE_KEYS.has(normalized)) continue;
 
-    // 卡号只保留末4位
+    // Card number: only keep the last 4 digits
     if (CARD_NUMBER_KEYS.has(normalized)) {
       if (typeof value === "string" && value.length >= 4) {
         result[key] = "•••• " + value.slice(-4);
       }
-      // value 为 null 时不输出此字段
+      // when value is null, do not emit this field
       continue;
     }
 

package/src/update-check.mjs

@@ -1,11 +1,11 @@
 /**
- * 自动版本检查 + 静默后台升级
+ * Auto version check + silent background upgrade.
  *
- * 策略：
- * 1. 同步快速检查（npm view）— 发现新版本时输出提示
- * 2. spawn 后台子进程执行 npm install -g 升级
- * 3. 升级后执行 postinstall.mjs（skills CLI 安装到所有工具）
- * 不阻塞主进程
+ * Strategy:
+ * 1. Synchronously poll the npm registry (`npm view`) — print a notice when a newer version is found.
+ * 2. Spawn a detached background process to run `npm install -g`.
+ * 3. After install, run postinstall.mjs (which re-installs the skill into every detected tool via the skills CLI).
+ * Does not block the main process.
  */
 
 import { execFileSync, spawn } from "node:child_process";
@@ -13,11 +13,11 @@ import { execFileSync, spawn } from "node:child_process";
 const PKG_NAME = "@aeon-ai-pay/aigateway";
 
 /**
- * 启动时调用：同步检查版本 + 后台升级
+ * Called at CLI startup: synchronous version probe + detached upgrade.
  * @param {string} currentVersion
  */
 export function checkForUpdates(currentVersion) {
-  // 同步快速检查最新版本（超时短，不阻塞太久）
+  // Synchronous fast probe (short timeout so it does not block too long)
   let latest;
   try {
     latest = execFileSync("npm", ["view", PKG_NAME, "version"], {
@@ -25,15 +25,15 @@ export function checkForUpdates(currentVersion) {
       stdio: ["ignore", "pipe", "ignore"],
     }).toString().trim();
   } catch {
-    return; // 网络不可用，静默跳过
+    return; // network unavailable — silently skip
   }
 
   if (!latest || latest === currentVersion) return;
 
-  // 有新版本：输出提示
+  // A newer version exists — print a notice
   console.error(`[update] ${PKG_NAME} ${currentVersion} → ${latest}, upgrading in background...`);
 
-  // 后台执行升级（结果写入日志文件）
+  // Run the upgrade in a detached child, writing the result to a log file
   const script = `
     const { execFileSync } = require("child_process");
     const { join } = require("path");