@aeon-ai-pay/aigateway 0.1.5 → 0.2.1

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

@@ -33,7 +33,7 @@ export function isVerboseMode() { return VERBOSE_MODE; }
 /**
  * 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 {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
  */

package/src/tools-download.mjs

@@ -0,0 +1,264 @@
+/**
+ * tools-download: shared binary download + metadata helpers used by
+ * sb-invoke (any AI tool returning image / video / audio URLs).
+ *
+ * Public API:
+ *   - extractOutputs(rawResponseData) → { kind, items }
+ *       Walks the upstream tool response and returns a normalized list of
+ *       downloadable URLs along with the inferred media kind ("image" | "video"
+ *       | "audio" | null).
+ *   - resolveOutputDir(opts.output, kind) → absolute path
+ *       Per-kind default: ~/aigateway-{kind}s/, override with `--output`.
+ *   - downloadOutputs(items, dir) → DownloadedItem[]
+ *       Downloads every item to `dir`, parses metadata for known image formats.
+ *   - DEFAULT_DIRS, downloadFile, readImageMeta, humanSize
+ *       Exposed for advanced reuse / tests.
+ */
+import { mkdirSync, createWriteStream, existsSync, unlinkSync, openSync, readSync, closeSync, statSync } from "node:fs";
+import { join, basename, extname } from "node:path";
+import { homedir } from "node:os";
+import { URL } from "node:url";
+import { get as httpsGet } from "node:https";
+import { get as httpGet } from "node:http";
+
+export const DEFAULT_DIRS = {
+  image: join(homedir(), "aigateway-images"),
+  video: join(homedir(), "aigateway-videos"),
+  audio: join(homedir(), "aigateway-audio"),
+  unknown: join(homedir(), "aigateway-downloads"),
+};
+
+const IMAGE_EXT = new Set(["png", "jpg", "jpeg", "gif", "webp", "bmp", "svg"]);
+const VIDEO_EXT = new Set(["mp4", "webm", "mov", "mkv", "avi", "m4v"]);
+const AUDIO_EXT = new Set(["mp3", "wav", "ogg", "flac", "m4a", "aac", "opus"]);
+
+function extFromUrl(url) {
+  try {
+    const p = new URL(url).pathname;
+    const e = extname(p).replace(/^\./, "").toLowerCase();
+    return e || null;
+  } catch {
+    return null;
+  }
+}
+
+function kindFromExt(ext) {
+  if (!ext) return null;
+  if (IMAGE_EXT.has(ext)) return "image";
+  if (VIDEO_EXT.has(ext)) return "video";
+  if (AUDIO_EXT.has(ext)) return "audio";
+  return null;
+}
+
+/**
+ * Normalize an upstream tool response into a list of downloadable items.
+ * Tries the common locations: data.images[], data.video.url, data.audio.url,
+ * data.url, data.output_url, plus raw top-level fallbacks.
+ */
+export function extractOutputs(responseData) {
+  const items = [];
+  let kind = null;
+
+  const inner = responseData?.data ?? responseData;
+
+  if (Array.isArray(inner?.images)) {
+    for (const img of inner.images) {
+      if (img?.url) items.push({ url: img.url });
+    }
+    if (items.length) kind = "image";
+  }
+
+  const pushSingle = (url, inferred) => {
+    if (!url || typeof url !== "string") return;
+    items.push({ url });
+    if (!kind && inferred) kind = inferred;
+  };
+
+  if (!items.length) {
+    pushSingle(inner?.video?.url, "video");
+    pushSingle(inner?.video_url, "video");
+  }
+  if (!items.length) {
+    pushSingle(inner?.audio?.url, "audio");
+    pushSingle(inner?.audio_url, "audio");
+  }
+  if (!items.length) {
+    const generic = inner?.url || inner?.output_url || inner?.file_url || inner?.image_url;
+    if (typeof generic === "string") {
+      const k = kindFromExt(extFromUrl(generic));
+      pushSingle(generic, k);
+    }
+  }
+  if (!items.length && Array.isArray(inner?.outputs)) {
+    for (const o of inner.outputs) {
+      const u = typeof o === "string" ? o : o?.url;
+      if (typeof u === "string") {
+        items.push({ url: u });
+        const k = kindFromExt(extFromUrl(u));
+        if (!kind && k) kind = k;
+      }
+    }
+  }
+
+  if (!kind && items.length) {
+    const first = items[0]?.url;
+    kind = kindFromExt(extFromUrl(first)) ?? null;
+  }
+
+  return { kind, items };
+}
+
+export function resolveOutputDir(userOverride, kind) {
+  if (userOverride) return userOverride;
+  return DEFAULT_DIRS[kind] ?? DEFAULT_DIRS.unknown;
+}
+
+/**
+ * Download every item to `dir`, parse image metadata where possible.
+ * Returns an array of { url, localPath, format?, width?, height?, sizeBytes, sizeHuman }
+ * with `error` populated on per-item failures (the loop never throws).
+ */
+export async function downloadOutputs(items, dir) {
+  if (!items.length) return [];
+  mkdirSync(dir, { recursive: true });
+  const out = [];
+  for (const item of items) {
+    if (!item?.url) continue;
+    try {
+      const localPath = await downloadFile(item.url, dir);
+      const meta = readImageMeta(localPath);
+      out.push({
+        url: item.url,
+        localPath,
+        format: meta.format,
+        width: meta.width,
+        height: meta.height,
+        sizeBytes: meta.sizeBytes,
+        sizeHuman: meta.sizeHuman,
+      });
+    } catch (e) {
+      out.push({ url: item.url, error: e.message });
+    }
+  }
+  return out;
+}
+
+export function readImageMeta(filePath) {
+  const sizeBytes = statSync(filePath).size;
+  const sizeHuman = humanSize(sizeBytes);
+  let format = null, width = null, height = null;
+  const fd = openSync(filePath, "r");
+  try {
+    const buf = Buffer.alloc(64 * 1024);
+    const len = readSync(fd, buf, 0, buf.length, 0);
+    if (len >= 24 && buf[0] === 0x89 && buf[1] === 0x50 && buf[2] === 0x4E && buf[3] === 0x47) {
+      format = "png";
+      width = buf.readUInt32BE(16);
+      height = buf.readUInt32BE(20);
+    } else if (len >= 4 && buf[0] === 0xFF && buf[1] === 0xD8 && buf[2] === 0xFF) {
+      format = "jpeg";
+      let i = 2;
+      while (i + 9 < len) {
+        if (buf[i] !== 0xFF) { i++; continue; }
+        while (i < len && buf[i] === 0xFF) i++;
+        const marker = buf[i];
+        i++;
+        if (marker === 0xD8 || marker === 0xD9) continue;
+        const segLen = buf.readUInt16BE(i);
+        if (marker >= 0xC0 && marker <= 0xCF && marker !== 0xC4 && marker !== 0xC8 && marker !== 0xCC) {
+          height = buf.readUInt16BE(i + 3);
+          width = buf.readUInt16BE(i + 5);
+          break;
+        }
+        i += segLen;
+      }
+    } else if (len >= 30 && buf.slice(0, 4).toString("ascii") === "RIFF" && buf.slice(8, 12).toString("ascii") === "WEBP") {
+      format = "webp";
+      const fourCC = buf.slice(12, 16).toString("ascii");
+      if (fourCC === "VP8 ") {
+        width = buf.readUInt16LE(26) & 0x3FFF;
+        height = buf.readUInt16LE(28) & 0x3FFF;
+      } else if (fourCC === "VP8L") {
+        const b0 = buf[21], b1 = buf[22], b2 = buf[23], b3 = buf[24];
+        width = ((b1 & 0x3F) << 8 | b0) + 1;
+        height = ((b3 & 0x0F) << 10 | b2 << 2 | (b1 & 0xC0) >> 6) + 1;
+      } else if (fourCC === "VP8X") {
+        width = (buf[24] | (buf[25] << 8) | (buf[26] << 16)) + 1;
+        height = (buf[27] | (buf[28] << 8) | (buf[29] << 16)) + 1;
+      }
+    }
+  } catch {
+    // leave null on parse failure
+  } finally {
+    closeSync(fd);
+  }
+  return { format, width, height, sizeBytes, sizeHuman };
+}
+
+export function humanSize(bytes) {
+  if (!Number.isFinite(bytes)) return "?";
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+  return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)} GB`;
+}
+
+export function downloadFile(fileUrl, outputDir, { maxRedirects = 5, timeoutMs = 60_000 } = {}) {
+  let filename;
+  try {
+    filename = basename(new URL(fileUrl).pathname) || `download-${Date.now()}`;
+  } catch {
+    filename = `download-${Date.now()}`;
+  }
+  if (!extname(filename)) filename += ".bin";
+
+  let target = join(outputDir, filename);
+  if (existsSync(target)) {
+    const ext = extname(filename);
+    const stem = filename.slice(0, filename.length - ext.length);
+    let i = 1;
+    while (existsSync(join(outputDir, `${stem}-${i}${ext}`))) i++;
+    target = join(outputDir, `${stem}-${i}${ext}`);
+  }
+
+  return new Promise((resolve, reject) => {
+    const fetchOnce = (currentUrl, redirectsLeft) => {
+      let parsed;
+      try {
+        parsed = new URL(currentUrl);
+      } catch (e) {
+        return reject(new Error(`Invalid URL: ${currentUrl}`));
+      }
+      const httpModule = parsed.protocol === "http:" ? httpGet : httpsGet;
+      const req = httpModule(currentUrl, { timeout: timeoutMs }, (res) => {
+        if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+          res.resume();
+          if (redirectsLeft <= 0) return reject(new Error("Too many redirects"));
+          const nextUrl = new URL(res.headers.location, currentUrl).toString();
+          return fetchOnce(nextUrl, redirectsLeft - 1);
+        }
+        if (res.statusCode !== 200) {
+          res.resume();
+          return reject(new Error(`HTTP ${res.statusCode} from ${currentUrl}`));
+        }
+        const file = createWriteStream(target);
+        res.pipe(file);
+        file.on("finish", () => file.close(() => resolve(target)));
+        file.on("error", (err) => {
+          try { unlinkSync(target); } catch {}
+          reject(err);
+        });
+        res.on("error", (err) => {
+          file.destroy();
+          try { unlinkSync(target); } catch {}
+          reject(err);
+        });
+      });
+      req.on("error", reject);
+      req.on("timeout", () => {
+        req.destroy(new Error(`Download timed out after ${timeoutMs}ms`));
+      });
+    };
+    fetchOnce(fileUrl, maxRedirects);
+  });
+}

package/src/update-check.mjs

@@ -1,23 +1,26 @@
 /**
- * Auto version check + silent background upgrade.
+ * Synchronous version check + foreground upgrade.
  *
- * 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.
+ * Why foreground (not background-detached): a detached `npm install -g` mid-command
+ * can leave the globally installed package in a half-replaced state — `bin/cli.mjs`
+ * may already be the new version while `src/commands/*` is still the old one (or
+ * vice versa), causing `ERR_MODULE_NOT_FOUND` on the very next invocation.
+ *
+ * Synchronous upgrade keeps the package consistent:
+ *   - upgrade succeeds → exit with UPDATE_APPLIED so the caller (or agent) reruns
+ *     the previous command on the new version
+ *   - upgrade fails    → log the failure and continue on the current version
+ *
+ * Output on upgrade: an envelope-shaped error so agents can detect / handle it
+ * uniformly via `envelope.error.code === "UPDATE_APPLIED"`.
  */
-
-import { execFileSync, spawn } from "node:child_process";
+import { execFileSync } from "node:child_process";
+import { join } from "node:path";
+import { emitErr } from "./output.mjs";
 
 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,45 +28,45 @@ export function checkForUpdates(currentVersion) {
       stdio: ["ignore", "pipe", "ignore"],
     }).toString().trim();
   } catch {
-    return; // network unavailable — silently skip
+    return; // no network / npm unavailable — silently keep going
   }
 
   if (!latest || latest === currentVersion) return;
 
-  // A newer version exists — print a notice
-  console.error(`[update] ${PKG_NAME} ${currentVersion} → ${latest}, upgrading in background...`);
+  console.error(`[update] ${PKG_NAME} ${currentVersion} → ${latest}, upgrading (foreground)...`);
+
+  try {
+    execFileSync("npm", ["install", "-g", `${PKG_NAME}@${latest}`], {
+      timeout: 120000,
+      stdio: ["ignore", "inherit", "inherit"],
+    });
+  } catch (e) {
+    console.error(`[update] Upgrade failed: ${(e && e.message) || e}. Continuing on ${currentVersion}.`);
+    return;
+  }
+
+  // Re-run the new version's postinstall so the SKILL.md copies in
+  // ~/.claude/skills/, .cursor/rules/, etc. get refreshed too.
+  try {
+    const root = execFileSync("npm", ["root", "-g"], {
+      timeout: 10000,
+      stdio: ["ignore", "pipe", "ignore"],
+    }).toString().trim();
+    const postinstall = join(root, PKG_NAME, "scripts", "postinstall.mjs");
+    execFileSync("node", [postinstall], {
+      timeout: 30000,
+      stdio: ["ignore", "inherit", "inherit"],
+    });
+  } catch (e) {
+    console.error(`[update] postinstall failed: ${(e && e.message) || e}`);
+  }
 
-  // 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");
-    const { appendFileSync, mkdirSync } = require("fs");
-    const { homedir } = require("os");
-    const pkg = ${JSON.stringify(PKG_NAME)};
-    const ver = ${JSON.stringify(latest)};
-    const logDir = join(homedir(), ".aigateway");
-    const logFile = join(logDir, "update.log");
-    function log(msg) {
-      try {
-        mkdirSync(logDir, { recursive: true });
-        appendFileSync(logFile, new Date().toISOString() + " " + msg + "\\n");
-      } catch {}
-    }
-    try {
-      log("Upgrading " + pkg + " to " + ver + "...");
-      execFileSync("npm", ["install", "-g", pkg + "@" + ver], { timeout: 120000 });
-      const root = execFileSync("npm", ["root", "-g"], { timeout: 10000 }).toString().trim();
-      const postinstall = join(root, pkg, "scripts", "postinstall.mjs");
-      execFileSync("node", [postinstall], { timeout: 30000 });
-      log("Upgrade to " + ver + " succeeded.");
-    } catch (e) {
-      log("Upgrade to " + ver + " failed: " + (e.message || e));
-    }
-  `;
+  console.error(`[update] Upgraded to ${latest}. Please rerun the previous command on the new version.`);
 
-  const child = spawn("node", ["-e", script], {
-    stdio: "ignore",
-    detached: true,
+  // Emit the envelope so agents can detect it programmatically, then exit.
+  emitErr("update-check", "UPDATE_APPLIED", {
+    message: `Upgraded ${PKG_NAME} ${currentVersion} → ${latest}. Rerun the previous command.`,
+    from: currentVersion,
+    to: latest,
   });
-  child.unref();
 }

package/src/x402.mjs

@@ -70,7 +70,7 @@ export function createX402Api(privateKey) {
  * sign manually later.
  * Field names follow the x402 v2 PaymentRequirements standard: asset, payTo, amount.
  *
- * Supports both GET (card path) and POST (image / Skill Boss path).
+ * Supports both GET and POST entry points.
  *
  * @param {string} url
  * @param {{ method?: "GET"|"POST", data?: any, headers?: object }} [options]

package/skills/aigateway/references/check-status.md

@@ -1,68 +0,0 @@
-# Check Card Status
-
-## Command
-
-```bash
-# Single query
-npx @aeon-ai-pay/aigateway create-card-status --order-no <orderNo>
-
-# Poll until terminal status (SUCCESS or FAIL)
-npx @aeon-ai-pay/aigateway create-card-status --order-no <orderNo> --poll
-```
-
-## Response Format
-
-```json
-{
-  "code": "0",
-  "msg": "success",
-  "model": {
-    "orderNo": "300217748668047431791",
-    "orderStatus": "SUCCESS",
-    "channelStatus": "COMPLETED",
-    "orderAmount": 0.6,
-    "txHash": "0xabc...def",
-    "cardLastFour": "4321",
-    "cardBin": "485932",
-    "cardScheme": "VISA",
-    "cardBalance": 0.6,
-    "cardStatus": "ACTIVE"
-  }
-}
-```
-
-## Status Values
-
-### orderStatus (Order Status)
-
-| Status | Meaning | Action |
-|------|------|------|
-| `INIT` | Order created, not yet paid | Wait |
-| `PENDING` | Payment submitted, awaiting on-chain confirmation | Continue polling |
-| `SUCCESS` | Card created successfully | Show card details |
-| `FAIL` | Failed | Show error, suggest retry |
-
-### channelStatus (Channel Status)
-
-| Status | Meaning |
-|------|------|
-| `INIT` | Not yet sent to card provider |
-| `PROCESSING` | Provider is creating the card |
-| `COMPLETED` | Card is ready |
-| `FAILED` | Card creation failed |
-
-### cardStatus (Card Status)
-
-| Status | Meaning |
-|------|------|
-| `PENDING` | Being provisioned |
-| `ACTIVE` | Ready to use |
-| `FROZEN` | Frozen |
-| `CANCELLED` | Cancelled |
-
-## Polling Behavior
-
-With `--poll`:
-- Up to **42 attempts** (first 5 at **2-second** intervals, then every **5 seconds**)
-- Stops on `SUCCESS`, `FAIL`, or `cardStatus=ACTIVE`
-- If timed out, notify user and provide manual query command