@aeon-ai-pay/aigateway 0.1.5 → 0.2.1

package/src/catalog.mjs

@@ -0,0 +1,38 @@
+/**
+ * tools-catalog client. **No caching** — every call hits the server.
+ *
+ * The server-side catalog (resources/skillboss/tools-catalog.json) is the
+ * single source of truth. Each invocation reads the current state, so model
+ * additions / schema changes take effect immediately with no stale-cache risk.
+ */
+import axios from "axios";
+
+/** Fetch catalog from server. Throws on network / HTTP failure. */
+export async function fetchCatalog(serviceUrl) {
+  if (!serviceUrl) throw new Error("serviceUrl is required");
+  const url = `${serviceUrl}/open/api/skillBoss/tools-catalog`;
+  const resp = await axios.get(url, { timeout: 15_000 });
+  return resp.data;
+}
+
+/**
+ * Find a model entry in the catalog by id.
+ * Returns { category, model, effectiveSchema } or null.
+ * effectiveSchema = model.inputsOverride ?? category.defaultInputsSchema ?? null
+ */
+export function findModel(catalog, modelId) {
+  if (!catalog || !Array.isArray(catalog.categories)) return null;
+  for (const cat of catalog.categories) {
+    if (!Array.isArray(cat.models)) continue;
+    for (const m of cat.models) {
+      if (m.id === modelId) {
+        return {
+          category: cat,
+          model: m,
+          effectiveSchema: m.inputsOverride || cat.defaultInputsSchema || null,
+        };
+      }
+    }
+  }
+  return null;
+}

package/src/commands/sb-invoke.mjs

@@ -0,0 +1,407 @@
+/**
+ * sb-invoke: invoke any AI tool through the x402 protocol.
+ *
+ * Server endpoint: GET {serviceUrl}/open/ai/x402/skillBoss/create?body=<urlencoded-json>&appId=<merchant>
+ *   (legacy server path name; client-side abstraction is vendor-agnostic.)
+ * Body shape: { "model": "<model_id>", "inputs": { /* tool-specific *​/ } }
+ *
+ * This module exposes two surfaces:
+ *   - invoke(opts)         → core logic, returns a result object. No emit.
+ *                            Reusable from any future thin wrapper.
+ *   - sbInvokeCommand(opts) → commander action handler; runs invoke() and
+ *                            emits the universal envelope.
+ */
+import { readFileSync, existsSync } from "node:fs";
+import axios from "axios";
+import { createX402Api, decodePaymentResponse, fetchPaymentRequirements } from "../x402.mjs";
+import { resolve } from "../config.mjs";
+import { getWalletBalance, getAllowance } from "../balance.mjs";
+import {
+  fundSessionKey,
+  promptTopupAmount,
+  MIN_TOPUP_USDT,
+  TOPUP_PRESETS,
+} from "../funding.mjs";
+import { WalletConnectError } from "../walletconnect.mjs";
+import { emitOk, emitErr, logInfo } from "../output.mjs";
+import { extractOutputs, resolveOutputDir, downloadOutputs } from "../tools-download.mjs";
+import { fetchCatalog, findModel } from "../catalog.mjs";
+import { validateInputs } from "../inputs-validator.mjs";
+
+/**
+ * Parse `--inputs` value: either a JSON literal or `@path/to/file.json`.
+ * Returns the parsed object on success.
+ * Throws { code: 'INPUTS_FILE_NOT_FOUND' | 'INVALID_INPUTS_JSON', message } on failure.
+ */
+function parseInputs(raw) {
+  if (raw == null || raw === "") {
+    const err = new Error("Missing --inputs.");
+    err.code = "MISSING_INPUTS";
+    throw err;
+  }
+  if (typeof raw === "object") return raw;
+
+  let text = String(raw);
+  if (text.startsWith("@")) {
+    const path = text.slice(1);
+    if (!existsSync(path)) {
+      const err = new Error(`Inputs file not found: ${path}`);
+      err.code = "INPUTS_FILE_NOT_FOUND";
+      err.path = path;
+      throw err;
+    }
+    text = readFileSync(path, "utf-8");
+  }
+  try {
+    return JSON.parse(text);
+  } catch (e) {
+    const err = new Error(`Failed to parse --inputs as JSON: ${e.message}`);
+    err.code = "INVALID_INPUTS_JSON";
+    throw err;
+  }
+}
+
+/**
+ * Core invocation. Returns:
+ *   { ok: true, data: { model, inputs, transaction, downloaded, raw, balance, paymentResponse } }
+ *   { ok: false, code, details }   — caller decides whether to emit
+ *
+ * Never calls emitOk / emitErr / process.exit directly. Suitable for reuse from
+ * any thin wrapper that needs to remap the envelope shape.
+ */
+export async function invoke(opts) {
+  const serviceUrl = resolve(opts.serviceUrl, "AIGATEWAY_SERVICE_URL", "serviceUrl");
+  const privateKey = resolve(opts.privateKey, "EVM_PRIVATE_KEY", "privateKey");
+  const { appId, model } = opts;
+
+  if (!serviceUrl) {
+    return { ok: false, code: "SERVICE_URL_MISSING", details: { appId } };
+  }
+  if (!privateKey) {
+    return { ok: false, code: "WALLET_NOT_CONFIGURED", details: { appId } };
+  }
+  if (!model || !String(model).trim()) {
+    return { ok: false, code: "MISSING_MODEL", details: { appId } };
+  }
+
+  let inputs;
+  try {
+    inputs = parseInputs(opts.inputs);
+  } catch (e) {
+    return {
+      ok: false,
+      code: e.code || "INVALID_INPUTS_JSON",
+      details: { message: e.message, path: e.path, appId },
+    };
+  }
+
+  // ─── Phase 3.2 + 3.3 client-side validation (live catalog from server) ─────
+  //   Catches model typos & missing/invalid inputs *before* any x402 round-trip.
+  //   No cache — always fetches fresh catalog. Falls back gracefully on network
+  //   failure (warn + skip; server still validates).
+  let catalog = null;
+  try {
+    catalog = await fetchCatalog(serviceUrl);
+  } catch (e) {
+    logInfo(`Warn: catalog fetch failed (${e.message}); skipping client-side validation — server will still check.`);
+  }
+
+  if (catalog) {
+    const found = findModel(catalog, model);
+    if (!found) {
+      return {
+        ok: false,
+        code: "INVALID_MODEL_ID",
+        details: {
+          message: `Model "${model}" not found in catalog. Run \`aigateway sb tools\` to see the current list.`,
+          model,
+          appId,
+        },
+      };
+    }
+
+    if (found.effectiveSchema) {
+      const { ok: validOk, errors } = validateInputs(inputs, found.effectiveSchema);
+      if (!validOk) {
+        const missingFields = errors.filter((e) => e.kind === "missing").map((e) => e.field);
+        const code = missingFields.length > 0 ? "MISSING_INPUTS" : "INVALID_INPUTS";
+        return {
+          ok: false,
+          code,
+          details: {
+            message: `Inputs validation failed for ${model}: ${errors.map((e) => `[${e.field}] ${e.message}`).join("; ")}`,
+            errors,
+            required: found.effectiveSchema.required || [],
+            properties: Object.keys(found.effectiveSchema.properties || {}),
+            category: found.category.key,
+            model,
+            appId,
+          },
+        };
+      }
+    }
+  }
+  // ─── End client-side validation ────────────────────────────────────────────
+
+  const bodyPayload = { model, inputs };
+  const bodyParam = encodeURIComponent(JSON.stringify(bodyPayload));
+  const url = `${serviceUrl}/open/ai/x402/skillBoss/create?body=${bodyParam}&appId=${encodeURIComponent(appId)}`;
+
+  logInfo(`Invoking ${model}...`);
+  logInfo("Fetching payment requirements...");
+  let paymentReq;
+  let requiredUsdt;
+  try {
+    paymentReq = await fetchPaymentRequirements(url);
+    requiredUsdt = paymentReq.amountUsdt;
+    logInfo(`Required: ${requiredUsdt} USDT (pay to ${paymentReq.payTo})`);
+  } catch (e) {
+    // Server may return HTTP 400 with structured { code, msg } for pricing / body errors.
+    // Surface that code as-is so the agent can react (e.g. MODEL_PRICING_NOT_CONFIGURED).
+    const serverData = e.response?.data;
+    const serverCode = serverData?.code || serverData?.error;
+    const serverMsg = serverData?.msg || serverData?.message;
+    if (e.response?.status === 400 && serverCode && /^[A-Z_]+$/.test(serverCode)) {
+      return {
+        ok: false,
+        code: serverCode,
+        details: { message: serverMsg || e.message, model, appId, serverStatus: 400 },
+      };
+    }
+    return {
+      ok: false,
+      code: "PAYMENT_FETCH_FAILED",
+      details: { message: `Failed to fetch payment requirements: ${e.message}`, model, appId },
+    };
+  }
+
+  // Balance / allowance / funding decision
+  logInfo("Checking wallet...");
+  let needTopup = false;
+  let needGas = false;
+  let sessionAddress;
+  let topupAmount = null;
+  let balanceInitialUsdt = null;
+  let balanceBeforeChargeUsdt = null;
+
+  try {
+    const { address, usdt, bnb, bnbRaw } = await getWalletBalance(privateKey);
+    sessionAddress = address;
+    balanceInitialUsdt = usdt;
+    balanceBeforeChargeUsdt = usdt;
+    const usdtNum = parseFloat(usdt);
+
+    logInfo(`Wallet: ${address}`);
+    logInfo(`Balance: ${usdt} USDT, ${bnb} BNB`);
+
+    const allowance = await getAllowance(address);
+    const requiredWei = BigInt(paymentReq.amountWei);
+    if (requiredWei === 0n) {
+      return {
+        ok: false,
+        code: "INVALID_PAYMENT_AMOUNT",
+        details: { message: "Server returned invalid payment amount (0). Please retry later.", appId },
+      };
+    }
+    if (allowance >= requiredWei) {
+      logInfo("Allowance sufficient, no approve needed.");
+    } else {
+      logInfo(`Allowance ${allowance} < required ${requiredWei}; approve needed.`);
+      if (bnbRaw === 0n) {
+        needGas = true;
+        logInfo("No BNB for approve gas, will request BNB transfer.");
+      }
+    }
+
+    if (usdtNum < requiredUsdt) {
+      needTopup = true;
+      const shortfall = requiredUsdt - usdtNum;
+      const minTopup = Math.max(MIN_TOPUP_USDT, Math.ceil(shortfall));
+      logInfo(`USDT insufficient: have ${usdtNum}, need ${requiredUsdt}, shortfall ${shortfall.toFixed(6)} (top-up minimum: ${minTopup} USDT)`);
+
+      if (opts.topupAmount != null && String(opts.topupAmount).trim() !== "") {
+        const amt = Number(opts.topupAmount);
+        if (!Number.isFinite(amt) || amt <= 0) {
+          return {
+            ok: false,
+            code: "AMOUNT_INVALID",
+            details: { message: `Invalid --topup-amount: ${opts.topupAmount}`, appId },
+          };
+        }
+        if (amt < minTopup) {
+          return {
+            ok: false,
+            code: "TOPUP_AMOUNT_TOO_SMALL",
+            details: { message: `--topup-amount ${amt} USDT is below the ${minTopup} USDT minimum for this call.`, minTopup, appId },
+          };
+        }
+        topupAmount = String(opts.topupAmount);
+        logInfo(`Using --topup-amount: ${topupAmount} USDT`);
+      } else if (process.stdin.isTTY) {
+        topupAmount = await promptTopupAmount(minTopup);
+        logInfo(`Selected top-up amount: ${topupAmount} USDT`);
+      } else {
+        const presets = TOPUP_PRESETS.filter((v) => v >= minTopup);
+        return {
+          ok: false,
+          code: "TOPUP_REQUIRED",
+          details: {
+            message: `USDT balance is below the ${minTopup} USDT minimum for this call. Choose a top-up amount and rerun with --topup-amount <usdt>.`,
+            minTopup,
+            required: requiredUsdt,
+            currentBalance: balanceInitialUsdt,
+            address: sessionAddress,
+            appId,
+            presets,
+            hint: `Rerun: aigateway wallet-topup --amount <usdt> --app-id ${appId}`,
+          },
+        };
+      }
+    }
+  } catch (e) {
+    return {
+      ok: false,
+      code: "BALANCE_CHECK_FAILED",
+      details: { message: `Balance check failed: ${e.message}`, appId },
+    };
+  }
+
+  if (needTopup || needGas) {
+    logInfo("Funding flow triggered...");
+    try {
+      await fundSessionKey({
+        sessionAddress,
+        usdtAmount: needTopup ? topupAmount : null,
+        needGas,
+      });
+    } catch (e) {
+      if (e instanceof WalletConnectError) {
+        return { ok: false, code: e.code, details: { message: e.message, address: sessionAddress, appId } };
+      }
+      return { ok: false, code: "FUNDING_FAILED", details: { message: e.message, address: sessionAddress, appId } };
+    }
+
+    logInfo("Re-checking wallet balance...");
+    try {
+      const { usdt, bnbRaw } = await getWalletBalance(privateKey);
+      balanceBeforeChargeUsdt = usdt;
+      const usdtNum = parseFloat(usdt);
+      if (needGas && bnbRaw === 0n) {
+        return {
+          ok: false,
+          code: "INSUFFICIENT_BNB",
+          details: { message: "No BNB for approve transaction after funding. Run 'aigateway wallet-gas' to add BNB manually.", address: sessionAddress, appId },
+        };
+      }
+      if (usdtNum < requiredUsdt) {
+        return {
+          ok: false,
+          code: "INSUFFICIENT_USDT",
+          details: { message: "Still insufficient USDT after funding.", required: `${requiredUsdt} USDT`, available: `${usdt} USDT`, address: sessionAddress, appId },
+        };
+      }
+    } catch (e) {
+      return { ok: false, code: "BALANCE_CHECK_FAILED", details: { message: `Balance re-check failed: ${e.message}`, appId } };
+    }
+  }
+
+  // Sign x402 payment & retry the request.
+  const { client } = createX402Api(privateKey);
+  logInfo(`Submitting payment & request: ${url}`);
+
+  let response;
+  let paymentResponse;
+  try {
+    const { x402HTTPClient } = await import("@aeon-ai-pay/core/client");
+    const httpClient = new x402HTTPClient(client);
+
+    const raw402 = paymentReq.raw402Response;
+    const getHeader = (name) => {
+      const value = raw402.headers[name] ?? raw402.headers[name.toLowerCase()];
+      return typeof value === "string" ? value : undefined;
+    };
+    const paymentRequired = httpClient.getPaymentRequiredResponse(getHeader, raw402.data);
+    const paymentPayload = await client.createPaymentPayload(paymentRequired);
+    const paymentHeaders = httpClient.encodePaymentSignatureHeader(paymentPayload);
+
+    response = await axios.get(url, {
+      headers: {
+        ...paymentHeaders,
+        "Access-Control-Expose-Headers": "PAYMENT-RESPONSE",
+      },
+    });
+    paymentResponse = decodePaymentResponse(response.headers);
+  } catch (error) {
+    return {
+      ok: false,
+      code: "PAYMENT_FAILED",
+      details: {
+        message: error.message,
+        status: error.response?.status,
+        data: error.response?.data,
+        appId,
+      },
+    };
+  }
+
+  const transaction = response.data?.transaction || paymentResponse?.txHash || null;
+
+  // Detect downloadable outputs and fetch them locally (unless --raw).
+  let downloaded = [];
+  if (!opts.raw) {
+    const { kind, items } = extractOutputs(response.data);
+    if (items.length) {
+      const outputDir = resolveOutputDir(opts.output, kind);
+      downloaded = await downloadOutputs(items, outputDir);
+      for (const d of downloaded) {
+        if (d.error) {
+          logInfo(`Failed to download ${d.url}: ${d.error}`);
+        } else {
+          logInfo(`Saved: ${d.localPath} (${d.format || "?"}, ${d.width || "?"}×${d.height || "?"}, ${d.sizeHuman})`);
+        }
+      }
+    }
+  }
+
+  // Post-payment balance probe (best effort).
+  let balanceAfterUsdt = null;
+  try {
+    const after = await getWalletBalance(privateKey);
+    balanceAfterUsdt = after.usdt;
+  } catch (e) {
+    logInfo(`Post-payment balance check failed: ${e.message}`);
+  }
+
+  return {
+    ok: true,
+    data: {
+      model,
+      inputs,
+      transaction,
+      downloaded,
+      // unwrap server envelope: { payer, transaction, data: <upstream-response> } → <upstream-response>
+      raw: response.data?.data ?? response.data,
+      paymentResponse,
+      balance: {
+        initial: balanceInitialUsdt,
+        before: balanceBeforeChargeUsdt,
+        after: balanceAfterUsdt,
+        charged: requiredUsdt,
+        topup: topupAmount,
+      },
+    },
+  };
+}
+
+/**
+ * Commander action handler for `aigateway sb invoke`.
+ * Emits the universal envelope; errors are emitted via emitErr (which exits).
+ */
+export async function sbInvokeCommand(opts) {
+  const result = await invoke(opts);
+  if (result.ok) {
+    emitOk("sb-invoke", result.data, { success: true, ...result.data });
+    return;
+  }
+  emitErr("sb-invoke", result.code, result.details);
+}

package/src/commands/sb-tools.mjs

@@ -0,0 +1,37 @@
+/**
+ * sb-tools: fetch and display the AI tool catalog from the server.
+ *
+ *   aigateway sb tools
+ *
+ * No caching — always hits the server. Server-side `tools-catalog.json` is the
+ * single source of truth. Stdout is the full envelope with `data` = catalog.
+ *
+ * Endpoint: GET {serviceUrl}/open/api/skillBoss/tools-catalog
+ *   (free, no x402; price fields are stripped server-side)
+ */
+import { resolve } from "../config.mjs";
+import { emitOk, emitErr, logInfo } from "../output.mjs";
+import { fetchCatalog } from "../catalog.mjs";
+
+export async function sbTools(opts) {
+  const serviceUrl = resolve(opts.serviceUrl, "AIGATEWAY_SERVICE_URL", "serviceUrl");
+  if (!serviceUrl) {
+    emitErr("sb-tools", "SERVICE_URL_MISSING", {});
+    return;
+  }
+
+  logInfo("Fetching tools catalog from server...");
+  let data;
+  try {
+    data = await fetchCatalog(serviceUrl);
+  } catch (e) {
+    emitErr("sb-tools", "CATALOG_FETCH_FAILED", {
+      message: `Failed to fetch tools catalog: ${e.message}`,
+      url: `${serviceUrl}/open/api/skillBoss/tools-catalog`,
+      status: e.response?.status,
+    });
+    return;
+  }
+
+  emitOk("sb-tools", data, { success: true, ...data });
+}

package/src/commands/wallet-init.mjs

@@ -10,10 +10,9 @@
  * Design intent: with a single wallet-init call, the agent gets every decision input it needs:
  *   - data.ready=true → the session private key is usable
  *   - data.needsTopup=true → wallet-topup must run first (the envelope includes presets / minTopup / reason)
- *   - data.needsTopup=false → can proceed directly to create-card / create-image
+ *   - data.needsTopup=false → can proceed directly to sb invoke
  */
 import { loadConfig, saveConfig } from "../config.mjs";
-import { MIN_AMOUNT, MAX_AMOUNT } from "../constants.mjs";
 import { getWalletBalance, getAllowance } from "../balance.mjs";
 import {
   LOW_BALANCE_THRESHOLD,
@@ -106,7 +105,6 @@ export async function initWallet(opts) {
     topupReason,            // "first_time" | "low_balance" | "no_approve" | "chain_check_failed" | null
     minTopup: MIN_TOPUP_USDT,
     presets: TOPUP_PRESETS,
-    amountLimits: { min: MIN_AMOUNT, max: MAX_AMOUNT },
     chainCheck: chainCheckOk ? "ok" : { error: chainCheckError },
   };
   emitOk("wallet-init", data, data);

package/src/config.mjs

@@ -2,50 +2,49 @@
  * Config management: ~/.aigateway/config.json
  * Resolution priority: CLI args > env vars > config.json
  *
- * 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.
+ * 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);
 }
 
 /**
  * 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

@@ -14,13 +14,19 @@ export const ERROR_CODES = {
   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." },
@@ -28,12 +34,13 @@ export const ERROR_CODES = {
   // ===== 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." },
 
   // ===== 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,6 +49,7 @@ 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." },
 
   // ===== Internal (exit 4) =====

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,