@aeon-ai-pay/aigateway 0.1.4 → 0.1.6

package/src/commands/wallet-topup.mjs

@@ -1,15 +1,15 @@
 /**
- * topup：充值 + 一次性 approve facilitator
+ * wallet-topup: top up the session wallet and run the one-time facilitator approve.
  *
- * 流程：
- *   1. 校验 session key 已存在（来自 aigateway wallet-init）
- *   2. 检查 USDT 余额 + facilitator allowance
- *   3. 如果 USDT < LOW_BALANCE_THRESHOLD（1 USDT）或 allowance == 0，触发 WalletConnect 充值
- *      - 充值 amount: TTY 模式交互选择 presets [5, 10, 20, 50] 或自定义；
- *                    非 TTY 模式需要传 --amount <usdt>，否则报 TOPUP_REQUIRED
- *      - 同时按需转 0.0003 BNB 用作 approve gas
- *   4. session key 自己广播 ERC20.approve(facilitator, MaxUint256)
- *   5. 重新查余额 / allowance，返回最终状态
+ * Flow:
+ *   1. Verify the session key exists (created earlier by `aigateway wallet-init`).
+ *   2. Check USDT balance + facilitator allowance.
+ *   3. If USDT < LOW_BALANCE_THRESHOLD (1 USDT) or allowance == 0, open WalletConnect to fund:
+ *      - Top-up amount: TTY mode picks interactively from presets [5, 10, 20, 50] or a custom value;
+ *                       non-TTY mode requires `--amount <usdt>`, otherwise TOPUP_REQUIRED is emitted.
+ *      - 0.0003 BNB is transferred too when an approve transaction is needed.
+ *   4. The session key broadcasts ERC20.approve(facilitator, MaxUint256) once.
+ *   5. Re-query balance / allowance and return the final state.
  */
 import { resolve } from "../config.mjs";
 import { getWalletBalance, getAllowance } from "../balance.mjs";
@@ -71,7 +71,7 @@ export async function topup(opts) {
   const needApprove = allowance === 0n;
   const needGas = needApprove && bnbRaw === 0n;
 
-  // 已就绪：余额够 + 已 approve
+  // Already prepared: balance is sufficient and facilitator is approved
   if (!needTopup && !needApprove) {
     logInfo("Wallet already prepared (balance ≥ minimum, facilitator approved).");
     const data = {
@@ -89,7 +89,7 @@ export async function topup(opts) {
     return;
   }
 
-  // 决定充值金额
+  // Decide the top-up amount
   let topupAmount = null;
   if (needTopup) {
     if (balanceLow) {
@@ -134,7 +134,7 @@ export async function topup(opts) {
     }
   }
 
-  // WalletConnect 充值（USDT + 按需 BNB gas）
+  // WalletConnect top-up (USDT + optional BNB for approve gas)
   if (needTopup || needGas) {
     const willTransfer = [];
     if (needTopup) willTransfer.push(`${topupAmount} USDT`);
@@ -161,7 +161,7 @@ export async function topup(opts) {
     }
   }
 
-  // session key 一次性 approve facilitator
+  // Session key broadcasts the one-time facilitator approve
   let approveTx = null;
   if (needApprove) {
     let postBnbRaw = bnbRaw;
@@ -193,7 +193,7 @@ export async function topup(opts) {
     }
   }
 
-  // 最终查余额 + allowance
+  // Final balance + allowance re-check
   let finalUsdt = usdt;
   let finalBnb = bnb;
   let finalAllowance = allowance;

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,50 +1,50 @@
 /**
- * 配置管理：~/.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).
  */
-import { readFileSync, writeFileSync, mkdirSync, chmodSync } from "fs";
-import { join } from "path";
-import { homedir } from "os";
+import {readFileSync, writeFileSync, mkdirSync, chmodSync} from "fs";
+import {join} from "path";
+import {homedir} from "os";
 
 const CONFIG_DIR = join(homedir(), ".aigateway");
 const CONFIG_FILE = join(CONFIG_DIR, "config.json");
 
 const DEFAULTS = {
-  serviceUrl: "https://ai-api.aeon.xyz",
+    serviceUrl: "https://ai-api-dev.aeon.xyz",
+    // serviceUrl: "https://ai-api.aeon.xyz",
 };
 
 export function loadConfig() {
-  try {
-    return { ...DEFAULTS, ...JSON.parse(readFileSync(CONFIG_FILE, "utf-8")) };
-  } catch {
-    return { ...DEFAULTS };
-  }
+    try {
+        return {...DEFAULTS, ...JSON.parse(readFileSync(CONFIG_FILE, "utf-8"))};
+    } catch {
+        return {...DEFAULTS};
+    }
 }
 
 export function saveConfig(config) {
-  mkdirSync(CONFIG_DIR, { recursive: true });
-  writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), { mode: 0o600 });
-  chmodSync(CONFIG_FILE, 0o600);
+    mkdirSync(CONFIG_DIR, {recursive: true});
+    writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), {mode: 0o600});
+    chmodSync(CONFIG_FILE, 0o600);
 }
 
 /**
- * 解析配置值，优先级：cliValue > envKey > config[configKey]
+ * Resolve a value with priority: cliValue > envKey > config[configKey]
  */
 export function resolve(cliValue, envKey, configKey) {
-  if (cliValue) return cliValue;
-  if (process.env[envKey]) return process.env[envKey];
-  const cfg = loadConfig();
-  return cfg[configKey] || undefined;
+    if (cliValue) return cliValue;
+    if (process.env[envKey]) return process.env[envKey];
+    const cfg = loadConfig();
+    return cfg[configKey] || undefined;
 }
 
 export function getConfigPath() {
-  return CONFIG_FILE;
+    return CONFIG_FILE;
 }
 
 export function isSessionKeyMode() {
-  const config = loadConfig();
-  return config.mode === "session-key";
+    const config = loadConfig();
+    return config.mode === "session-key";
 }

package/src/error-codes.mjs

@@ -1,39 +1,46 @@
 /**
- * 错误码常量表 —— 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." },
-  AMOUNT_OUT_OF_RANGE:    { exit: 1, message: "Amount is outside the allowed range." },
   AMOUNT_EXCEEDS_BALANCE: { exit: 1, message: "Requested amount exceeds available balance." },
   INSUFFICIENT_USDT:      { exit: 1, message: "Insufficient USDT balance." },
   INSUFFICIENT_BNB:       { exit: 1, message: "Insufficient BNB for gas." },
   NO_FUNDS:               { exit: 1, message: "No funds available." },
   NO_MAIN_WALLET:         { exit: 1, message: "No main wallet address configured. Use --to <address>." },
-  MISSING_PROMPT:         { exit: 1, message: "Missing --prompt. Provide a non-empty image prompt." },
+  MISSING_MODEL:          { exit: 1, message: "Missing --model. Provide a tool model id (see references/tools.md)." },
+  MISSING_INPUTS:         { exit: 1, message: "Missing --inputs. Provide a JSON object or @path/to/file.json." },
+  INVALID_INPUTS_JSON:    { exit: 1, message: "Failed to parse --inputs as JSON." },
+  INVALID_INPUTS:         { exit: 1, message: "Inputs failed schema validation." },
+  INPUTS_FILE_NOT_FOUND:  { exit: 1, message: "Inputs file (passed via --inputs @path) not found." },
+  INVALID_MODEL_ID:       { exit: 1, message: "Server rejected the model id." },
+  MODEL_PRICING_NOT_CONFIGURED: { exit: 1, message: "This model is not yet priced on the gateway. Ask the operator to add it to skillboss-pricing.json." },
+  INVALID_BODY:           { exit: 1, message: "Server rejected the request body." },
   TOPUP_REQUIRED:         { exit: 1, message: "Wallet top-up required. Choose an amount and rerun with --topup-amount <usdt>." },
   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." },
+  UPDATE_APPLIED:         { exit: 2, message: "Package was just upgraded. Rerun the previous command on the new version." },
 
-  // ===== 服务/网络（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." },
+  CATALOG_FETCH_FAILED:   { exit: 3, message: "Failed to fetch tools catalog from the server." },
   BALANCE_CHECK_FAILED:   { exit: 3, message: "Failed to check balance." },
   ALLOWANCE_CHECK_FAILED: { exit: 3, message: "Failed to check allowance." },
   TX_REVERTED:            { exit: 3, message: "On-chain transaction reverted." },
@@ -42,9 +49,10 @@ export const ERROR_CODES = {
   INVALID_PAYMENT_AMOUNT: { exit: 3, message: "Server returned invalid payment amount." },
   PAYMENT_FAILED:         { exit: 3, message: "Payment request failed." },
   IMAGE_DOWNLOAD_FAILED:  { exit: 3, message: "Image download failed." },
+  DOWNLOAD_FAILED:        { exit: 3, message: "Output file 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/funding.mjs

@@ -2,8 +2,8 @@
  * Funding flow: WalletConnect-based USDT/BNB transfer to session key,
  * plus on-chain pre-authorization (ERC20.approve facilitator).
  *
- * Shared by: create-image (lazy top-up when balance is short),
- *            prepare      (proactive pre-flight before any image work).
+ * Shared by: sb-invoke (lazy top-up when balance is short),
+ *            wallet-topup (proactive pre-flight).
  */
 import {
   withWallet,

package/src/inputs-validator.mjs

@@ -0,0 +1,125 @@
+/**
+ * Minimal JSON Schema validator for tools-catalog inputs schemas.
+ *
+ * Supports the subset of JSON Schema actually used in tools-catalog.json:
+ *   - type: object | string | number | integer | boolean | array
+ *   - required: string[]
+ *   - properties: { fieldName: <fieldSchema> }
+ *   - enum: any[]
+ *   - minimum / maximum (number, integer)
+ *   - items (for arrays)
+ *   - oneOf: [schema, ...]   (treated as "any-of" — passes if any branch matches)
+ *
+ * We intentionally avoid pulling in ajv to keep the CLI dep tree small.
+ *
+ * @returns {{ ok: boolean, errors: Array<{ field: string, message: string, kind: "missing"|"type"|"enum"|"range"|"other" }> }}
+ */
+export function validateInputs(inputs, schema) {
+  const errors = [];
+  if (!schema) return { ok: true, errors };
+
+  // root must be an object
+  if (schema.type === "object" || schema.properties || schema.required) {
+    if (typeof inputs !== "object" || inputs === null || Array.isArray(inputs)) {
+      errors.push({ field: "(root)", kind: "type", message: "inputs must be a JSON object" });
+      return { ok: false, errors };
+    }
+  }
+
+  // Required fields
+  if (Array.isArray(schema.required)) {
+    for (const field of schema.required) {
+      const v = inputs[field];
+      if (v === undefined || v === null || (typeof v === "string" && v.trim() === "")) {
+        errors.push({ field, kind: "missing", message: `required field "${field}" is missing` });
+      }
+    }
+  }
+
+  // Per-field validation
+  if (schema.properties) {
+    for (const [field, fieldSchema] of Object.entries(schema.properties)) {
+      if (inputs[field] === undefined || inputs[field] === null) continue;
+      errors.push(...validateField(field, inputs[field], fieldSchema));
+    }
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+function validateField(field, value, schema) {
+  const errors = [];
+
+  // oneOf: pass if any branch accepts (no errors).
+  if (Array.isArray(schema.oneOf)) {
+    const branchErrors = schema.oneOf.map((sub) => validateField(field, value, sub));
+    const anyPass = branchErrors.some((errs) => errs.length === 0);
+    if (!anyPass) {
+      errors.push({
+        field,
+        kind: "type",
+        message: `value does not match any of oneOf schemas (tried ${schema.oneOf.length} branches)`,
+      });
+    }
+    return errors;
+  }
+
+  // Type check
+  if (schema.type) {
+    if (!checkType(value, schema.type)) {
+      errors.push({
+        field,
+        kind: "type",
+        message: `expected type "${schema.type}", got "${actualType(value)}"`,
+      });
+      return errors; // bail out on type mismatch
+    }
+  }
+
+  // Enum
+  if (Array.isArray(schema.enum) && !schema.enum.includes(value)) {
+    errors.push({
+      field,
+      kind: "enum",
+      message: `value ${JSON.stringify(value)} must be one of [${schema.enum.map((v) => JSON.stringify(v)).join(", ")}]`,
+    });
+  }
+
+  // Number range
+  if ((schema.type === "number" || schema.type === "integer") && typeof value === "number") {
+    if (schema.minimum != null && value < schema.minimum) {
+      errors.push({ field, kind: "range", message: `value ${value} is below minimum ${schema.minimum}` });
+    }
+    if (schema.maximum != null && value > schema.maximum) {
+      errors.push({ field, kind: "range", message: `value ${value} is above maximum ${schema.maximum}` });
+    }
+  }
+
+  // Array items
+  if (schema.type === "array" && Array.isArray(value) && schema.items) {
+    value.forEach((item, i) => {
+      errors.push(...validateField(`${field}[${i}]`, item, schema.items));
+    });
+  }
+
+  return errors;
+}
+
+function checkType(value, type) {
+  switch (type) {
+    case "object":  return typeof value === "object" && value !== null && !Array.isArray(value);
+    case "array":   return Array.isArray(value);
+    case "string":  return typeof value === "string";
+    case "number":  return typeof value === "number" && !Number.isNaN(value);
+    case "integer": return typeof value === "number" && Number.isInteger(value);
+    case "boolean": return typeof value === "boolean";
+    case "null":    return value === null;
+    default:        return true;
+  }
+}
+
+function actualType(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}

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. "sb-invoke" / "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);
 }