@aeon-ai-pay/aigateway 0.1.0

package/docs/release-process.md

@@ -0,0 +1,98 @@
+# Release Process
+
+## Versioning
+
+We follow [SemVer](https://semver.org/):
+
+- **Patch** (`0.1.0` → `0.1.1`) — bug fixes, doc edits, no breaking change.
+- **Minor** (`0.1.0` → `0.2.0`) — new commands, new flags, new error codes. Existing envelope schema preserved.
+- **Major** (`0.1.0` → `1.0.0`) — breaking envelope schema, renamed command, removed flag.
+
+## Two version numbers, kept in lock-step
+
+| File | Field |
+| --- | --- |
+| `package.json` | `version` |
+| `skills/aigateway/SKILL.md` | frontmatter `metadata.version` |
+
+**Both must move together** every release. The npm version drives `update-check.mjs`; the skill version drives `npx skills add` re-copy to IDE folders.
+
+## Release checklist
+
+1. Ensure `main` is clean and CI-green.
+
+2. Bump both versions to the same value:
+
+   ```bash
+   # 1. package.json
+   npm version patch --no-git-tag-version    # or `minor`, `major`, or explicit "0.1.1"
+
+   # 2. SKILL.md frontmatter
+   sed -i.bak -E 's/^(  version: ").*"/\1'"$(jq -r .version package.json)"'"/' skills/aigateway/SKILL.md
+   rm skills/aigateway/SKILL.md.bak
+   ```
+
+3. Update `CHANGELOG.md` with notable changes.
+
+4. Commit and tag:
+
+   ```bash
+   VERSION=$(jq -r .version package.json)
+   git add package.json skills/aigateway/SKILL.md CHANGELOG.md
+   git commit -m "release $VERSION"
+   git tag "v$VERSION"
+   git push && git push --tags
+   ```
+
+5. Publish:
+
+   ```bash
+   npm publish --access public
+   ```
+
+6. Verify:
+
+   ```bash
+   npm view @aeon-ai-pay/aigateway version       # should show the new version
+   aigateway --version                             # local still old until next call triggers auto-upgrade
+   ```
+
+## What happens for users after publish
+
+`src/update-check.mjs` runs on every CLI invocation. Within a few seconds of the next `aigateway <cmd>` call by any user, they will:
+
+1. See `[update] @aeon-ai-pay/aigateway 0.1.0 → 0.1.1, upgrading in background...` on stderr.
+2. The current command still completes normally.
+3. A detached child process runs `npm install -g @aeon-ai-pay/aigateway@0.1.1` + `node scripts/postinstall.mjs`, which calls `npx skills add ... -g -y --copy`.
+4. The new `SKILL.md` is re-installed into every detected IDE skill folder (Cursor / Claude Code / Codex / Windsurf / Cline / …).
+5. Next invocation uses the new CLI and the new agent reads the new skill.
+
+Upgrade results land in `~/.aigateway/update.log`.
+
+## Rolling back
+
+`npm` releases are immutable. If you cut a bad release:
+
+1. Publish a **new** patch with the fix (`0.1.2`), don't try to overwrite.
+2. If users are blocked, you can `npm deprecate @aeon-ai-pay/aigateway@0.1.1 "Use 0.1.2 instead"` so new installs skip it.
+
+## Pre-release (optional)
+
+For staging / beta:
+
+```bash
+npm version 0.2.0-beta.1 --no-git-tag-version
+# bump SKILL.md version manually to 0.2.0-beta.1
+npm publish --tag beta --access public
+
+# Users opt-in:
+npm install -g @aeon-ai-pay/aigateway@beta
+```
+
+`update-check.mjs` reads the `latest` tag by default, so beta users won't be silently bumped to `latest` until you mark a stable release.
+
+## When not to ship
+
+- **Breaking envelope schema change** without a major bump. Downstream agents and merchants parse the envelope; renaming `data.orderNo` to `data.id` will break them.
+- **Renaming a command** without a major bump (and at least one release of deprecation warnings).
+- **`--service-url` re-added or removed** — keep config / env-var contract stable.

package/docs/troubleshooting.md

@@ -0,0 +1,200 @@
+# Troubleshooting
+
+Common issues you (or your users) may hit, and what to do about them.
+
+## Setup / Install
+
+### `aigateway: command not found` after `npm install -g`
+
+The global `bin/` directory is not on your `PATH`. Find where npm installs:
+
+```bash
+npm bin -g
+# /Users/me/.nvm/versions/node/v25.0.0/bin
+```
+
+Add that to `~/.zshrc` or `~/.bashrc`:
+
+```bash
+export PATH="$(npm bin -g):$PATH"
+```
+
+On macOS with `nvm`, the path changes when you switch Node versions — re-install globally after switching.
+
+### `aigateway requires Node.js >= 25`
+
+`bin/cli.mjs` enforces the engine. Upgrade Node:
+
+```bash
+nvm install 25 && nvm use 25
+npm install -g @aeon-ai-pay/aigateway
+```
+
+### postinstall fails to install the skill
+
+The error usually looks like `npx skills add ...` returned non-zero, then a fallback message. The CLI still works; only the skill isn't installed to your IDE. Install manually:
+
+```bash
+npx skills add AEON-Project/aigateway -g -y
+```
+
+If the skills CLI itself isn't on `PATH`, install it once: `npm install -g skills`.
+
+For IDEs not covered by skills CLI, copy the matching `templates/<ide>/...` file — see [ide-setup.md](./ide-setup.md).
+
+## Wallet / Funding
+
+### "Wallet not configured. Run: aigateway wallet-init"
+
+The CLI couldn't find `~/.aigateway/config.json` or it has no `privateKey` field. Run:
+
+```bash
+aigateway wallet-init
+```
+
+If you're in a custodial / server context, inject the key via env var instead:
+
+```bash
+EVM_PRIVATE_KEY=0x...  aigateway wallet-balance
+```
+
+### QR window doesn't open during `wallet-topup`
+
+The CLI tries `open` (macOS) / `start` (Windows) / `xdg-open` (Linux). In headless environments, it prints the file path. Open `file:///tmp/aigateway-qr.html` manually in any browser. If you're on a remote VM, port-forward `127.0.0.1:<status-port>` (printed in stderr) and open the file locally instead.
+
+**Headless servers should never run `wallet-topup` interactively** — see [merchant-integration.md § 3.3](./recipes/merchant-integration.md) for the workstation pre-funding pattern.
+
+### `error.code: PAYMENT_TIMEOUT`
+
+The 5-minute WalletConnect approval window expired (you didn't scan / confirm in time). The session is automatically torn down. Re-run the same command from scratch. **Do not auto-retry** without user confirmation.
+
+### `error.code: PAYMENT_REJECTED`
+
+You (or the user) tapped "Reject" in the wallet app. Same as above — re-run only with explicit user re-confirmation.
+
+### `error.code: TOPUP_REQUIRED` even though I topped up
+
+Likely causes:
+1. The `wallet-topup` you ran was on a **different** session key. Verify `aigateway wallet-balance` shows the same address you funded.
+2. The on-chain tx hasn't confirmed yet. BSC normally confirms within 3 seconds; if longer, check `~/.aigateway/update.log` and the explorer.
+3. You funded in the wrong network (BSC vs. ETH). aigateway only reads USDT on **BSC** (chain id 56, contract `0x55d3...955`).
+
+### `error.code: INSUFFICIENT_BNB`
+
+`wallet-withdraw` and the one-time approve in `wallet-topup` are direct on-chain transactions and need BNB for gas. Run:
+
+```bash
+aigateway wallet-gas --amount 0.001
+```
+
+(scans QR to send 0.001 BNB from main wallet to session key.) Then retry.
+
+### `error.code: WC_SESSION_EXPIRED` mid-flow
+
+WalletConnect's relay sometimes drops the session between transactions in the same flow. Re-run the original command. If it persists, your wallet app may have been backgrounded too long — keep it foregrounded during the QR scan.
+
+### "Allowance check failed" / RPC errors
+
+BSC's public RPCs occasionally rate-limit. The CLI uses QuickNode by default. If you hit transient errors:
+
+```bash
+# retry after a couple of seconds
+sleep 3 && aigateway wallet-balance
+```
+
+If reproducible, file an issue.
+
+## Skill / Agent integration
+
+### Skill not picked up by Cursor / Windsurf / Cline / Codex
+
+`npx skills add` doesn't auto-install to every IDE. For IDEs not covered, copy the matching template manually — see [ide-setup.md](./ide-setup.md).
+
+Then restart the IDE. Some IDEs index rules files only at startup.
+
+### Agent doesn't trigger the skill even after install
+
+Check the IDE's "skill / rules registry" UI (or equivalent). The trigger description has to match the user's intent vocabulary. If you customized SKILL.md, make sure the `description:` frontmatter still matches.
+
+### `skills/aigateway/SKILL.md` version doesn't reflect my edits
+
+The skill version is locked to `metadata.version` in the frontmatter. If you edit SKILL.md but don't bump the version, the skills CLI may skip re-copying it on `skills update`. Bump it:
+
+```yaml
+metadata:
+  version: "0.1.1"   # was 0.1.0
+```
+
+Then `npx skills add AEON-Project/aigateway -g -y -f` (force) or re-run postinstall.
+
+## Auto-upgrade (`update-check.mjs`)
+
+### Auto-upgrade doesn't seem to run
+
+Check `~/.aigateway/update.log`. The upgrade is a detached background process and may take 1–2 minutes after the CLI is invoked. If the log shows a failure, the most common reasons are:
+
+- Your global npm registry needs auth and the background process can't prompt.
+- The user lacks permission to write to the global node_modules (run with sudo, or use nvm).
+
+You can force-upgrade manually:
+
+```bash
+npm install -g @aeon-ai-pay/aigateway@latest
+```
+
+### Block the auto-upgrade
+
+Currently no flag for this — but the upgrade is **non-blocking** and won't affect the current command. If you need a deterministic version (e.g. in CI), pin the install:
+
+```bash
+npm install -g @aeon-ai-pay/aigateway@0.1.0
+```
+
+The check still runs but the install is idempotent at the same version.
+
+## Subprocess / spawn issues
+
+### `JSON.parse` fails on envelope
+
+Causes:
+1. **stderr leaking into stdout**: you spawned without separating streams. Use `stdio: ["ignore", "pipe", "pipe"]` (or `"inherit"` for stderr) and read **stdout** only.
+2. **npm / nvm preamble**: tools like nvm print version banners on `npm` calls. The envelope is always the **last** line of stdout — use `stdout.trim().split("\n").pop()`.
+3. **Buffering**: pass `--quiet` to silence stderr progress logs and you'll get a single clean stdout line.
+
+### `--quiet` doesn't fully silence stderr
+
+`--quiet` suppresses progress info but **errors** still go to stderr (for human readability). That's intentional — the structured error is also in the envelope (`envelope.error`) on stdout.
+
+### Spawning hangs forever
+
+If you spawn `wallet-topup` / `create-card` / `create-image` in a context where the QR window can't be shown (CI, server, headless), the CLI waits 5 minutes for the WalletConnect signature, then exits with `PAYMENT_TIMEOUT`. **Never spawn these without pre-funded session keys** — see [merchant-integration.md § 3](./recipes/merchant-integration.md).
+
+## Service / network
+
+### `error.code: SERVICE_UNAVAILABLE`
+
+Upstream is degraded. Retry with exponential backoff (1s → 4s → 16s, max 3 attempts). If it persists for more than 5 minutes, contact AEON support with the `appId` and an example `orderNo`.
+
+### Staging vs. production
+
+The default service URL is `https://ai-api.aeon.xyz` (production). To use a staging endpoint:
+
+```bash
+AIGATEWAY_SERVICE_URL=https://staging-x402.aeon.xyz  aigateway create-card --amount 5
+```
+
+## Getting more diagnostics
+
+- `--verbose` — verbose stderr logs
+- `~/.aigateway/update.log` — auto-upgrade history
+- `~/.aigateway/config.json` — wallet state (session key is sensitive)
+- `cat /tmp/aigateway-qr.html` — last generated QR page (debug only)
+
+## Still stuck?
+
+File an issue at https://github.com/AEON-Project/aigateway/issues with:
+
+- Output of `aigateway --version`
+- Full envelope JSON from the failing command (redact `address` if sensitive)
+- Last 20 lines of `~/.aigateway/update.log` if upgrade-related
+- Node version (`node -v`) and OS

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@aeon-ai-pay/aigateway",
+  "version": "0.1.0",
+  "description": "AI Agents discover, invoke, and settle paid LLMs, APIs, and Skills — starting with Skill Boss. No manual key setup. No prepayment. Pay-per-call via x402 or Agent Card.",
+  "type": "module",
+  "bin": {
+    "aigateway": "bin/cli.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "skills",
+    "scripts",
+    "docs",
+    "templates",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/postinstall.mjs",
+    "create-card": "node bin/cli.mjs create-card",
+    "create-image": "node bin/cli.mjs create-image",
+    "wallet-init": "node bin/cli.mjs wallet-init",
+    "wallet-topup": "node bin/cli.mjs wallet-topup",
+    "wallet-balance": "node bin/cli.mjs wallet-balance",
+    "release": "node scripts/release.mjs"
+  },
+  "dependencies": {
+    "@aeon-ai-pay/axios": "2.1.2",
+    "@aeon-ai-pay/evm": "2.1.4",
+    "@walletconnect/sign-client": "^2.17.0",
+    "axios": "^1.13.2",
+    "commander": "^13.0.0",
+    "qrcode-terminal": "^0.12.0",
+    "viem": "^2.39.0"
+  },
+  "engines": {
+    "node": ">=25"
+  },
+  "keywords": [
+    "agent-os",
+    "aigateway",
+    "agent-skills",
+    "x402",
+    "virtual-card",
+    "ai-image",
+    "skill-boss",
+    "crypto-payment",
+    "evm",
+    "bsc"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AEON-Project/aigateway.git"
+  },
+  "license": "MIT"
+}

package/scripts/postinstall.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+
+/**
+ * npm install -g 后自动安装 skill 到所有已检测的 AI 编码工具
+ *
+ * 优先使用 `npx skills add` (Vercel Labs) 统一安装到所有工具
+ * 失败时 fallback 到手动复制 Claude Code skills 目录
+ */
+
+import { cpSync, existsSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const skillSrc = join(__dirname, '..', 'skills', 'aigateway');
+
+if (!existsSync(skillSrc)) {
+  process.exit(0);
+}
+
+// 尝试用 skills CLI 安装到所有工具
+try {
+  execFileSync('npx', ['skills', 'add', skillSrc, '-g', '-y', '--copy'], {
+    stdio: 'inherit',
+    timeout: 30000,
+    cwd: join(__dirname, '..'),
+  });
+  console.log('✔ aigateway skill installed via skills CLI (all detected tools)');
+  process.exit(0);
+} catch {
+  // skills CLI 不可用或失败，fallback
+}
+
+// Fallback: 手动复制到 Claude Code
+const dest = join(homedir(), '.claude', 'skills', 'aigateway');
+mkdirSync(dirname(dest), { recursive: true });
+cpSync(skillSrc, dest, { recursive: true, force: true });
+console.log(`✔ aigateway skill installed to ${dest} (fallback)`);