@aeon-ai-pay/aigateway 0.2.2 → 0.2.4

package/docs/output-schema.md

@@ -1,6 +1,6 @@
 # Output Schema
 
-Every `aigateway` command emits **exactly one line of JSON** to **stdout** —— the *envelope*. Human-readable progress logs go to **stderr** and can be safely ignored by programmatic consumers.
+Every `aigateway` command emits **exactly one line of JSON** to **stdout** — the *envelope*. Human-readable progress logs go to **stderr** and can be safely ignored by programmatic consumers.
 
 > Pass `--quiet` to suppress non-error stderr. Pass `--legacy-output` to fall back to the pre-envelope shape (see [Legacy mode](#legacy-mode)).
 
@@ -11,8 +11,8 @@ Every `aigateway` command emits **exactly one line of JSON** to **stdout** —
 ```json
 {
   "ok": true,
-  "command": "create",
-  "version": "0.9.0",
+  "command": "sb-invoke",
+  "version": "x.y.z",
   "data": { /* command-specific payload */ }
 }
 ```
@@ -22,20 +22,21 @@ Every `aigateway` command emits **exactly one line of JSON** to **stdout** —
 ```json
 {
   "ok": false,
-  "command": "create",
-  "version": "0.9.0",
+  "command": "sb-invoke",
+  "version": "x.y.z",
   "error": {
-    "code": "AMOUNT_OUT_OF_RANGE",
-    "message": "Amount must be at least $0.6. Allowed range: $0.6 ~ $800 USD.",
-    "min": 0.6,
-    "max": 800
+    "code": "MISSING_INPUTS",
+    "message": "Inputs validation failed for ...",
+    "errors": [{ "field": "prompt", "kind": "missing", "message": "..." }],
+    "required": ["prompt"],
+    "properties": ["prompt", "aspect_ratio", "num_outputs"]
   }
 }
 ```
 
 - `error.code` is a stable identifier from [`src/error-codes.mjs`](../src/error-codes.mjs) — see [exit-codes.md](./exit-codes.md) for the full list.
 - `error.message` is human-readable and may change between versions; **do not** match on it for control flow.
-- Additional fields under `error` are command-specific context (e.g. `min` / `max` / `address` / `required` / `available`).
+- Additional fields under `error` are command-specific context (e.g. `min` / `max` / `address` / `required` / `available` / `errors[]` / `presets`).
 
 ## Per-Command `data` Payloads
 
@@ -49,8 +50,14 @@ Every `aigateway` command emits **exactly one line of JSON** to **stdout** —
   "mode": "private-key",
   "address": "0x...",
   "mainWallet": "0x..." | null,
-  "serviceUrl": "https://...",
-  "amountLimits": { "min": 0.6, "max": 800 }
+  "usdt": "5.0",
+  "bnb": "0.0003",
+  "allowance": "115792...max" | "0",
+  "needsTopup": false,
+  "topupReason": null | "first_time" | "low_balance" | "no_approve" | "chain_check_failed",
+  "minTopup": 5,
+  "presets": [5, 10, 20, 50],
+  "serviceUrl": "https://..."
 }
 ```
 
@@ -70,72 +77,80 @@ Every `aigateway` command emits **exactly one line of JSON** to **stdout** —
 }
 ```
 
-### `create-card`
+### `sb invoke`
 
 ```json
 {
-  "appId": "TEST000001",
-  "orderNo": "...",
-  "data": { /* sanitized server response */ },
-  "paymentResponse": { /* decoded PAYMENT-RESPONSE header */ },
-  "pollResult": { /* present when --poll succeeds */ }
+  "model": "replicate/black-forest-labs/flux-schnell",
+  "inputs": { "prompt": "...", "aspect_ratio": "1:1" },
+  "transaction": "0x..." | null,
+  "downloaded": [
+    {
+      "url": "https://...",
+      "localPath": "/home/.../aigateway-images/...png",
+      "format": "png",
+      "width": 1024,
+      "height": 1024,
+      "sizeBytes": 412345,
+      "sizeHuman": "402.7 KB"
+    }
+  ],
+  "raw": { /* upstream vendor response, unwrapped from { payer, transaction, data } */ },
+  "paymentResponse": { "txHash": "0x...", "payer": "0x...", "...": "..." },
+  "balance": {
+    "initial": "5.0",
+    "before": "5.0",
+    "after": "4.99",
+    "charged": 0.01,
+    "topup": null | "5"
+  }
 }
 ```
 
-### `create-image`
+- **Binary outputs** (image / video / audio) populate `downloaded[]`. With `--raw` the auto-download is skipped and `downloaded[]` stays empty; the URLs live in `raw`.
+- **JSON-only outputs** (search, scraper, social_data, email, etc.) leave `downloaded` empty; consumers read `raw`.
+- `balance.charged` is the live USDT amount taken for this call (computed server-side as `priceUnit × inputs usage`).
+
+Failure shapes carry extra fields per code, e.g.:
 
 ```json
 {
-  "appId": "TEST000001",
-  "prompt": "...",
-  "aspectRatio": "16:9",
-  "outputFormat": "png",
-  "model": "...",
-  "transaction": "0x...",
-  "images": [
-    { "url": "https://...", "localPath": "/.../...png", "format": "png", "width": 1024, "height": 576, "sizeBytes": 123456, "sizeHuman": "120.6 KB" }
-  ],
-  "balance": { "initial": "5", "before": "5", "after": "4.99", "charged": 0.01, "topup": null }
+  "ok": false,
+  "command": "sb-invoke",
+  "error": {
+    "code": "TOPUP_REQUIRED",
+    "message": "USDT balance is below the 5 USDT minimum...",
+    "minTopup": 5,
+    "required": 0.01,
+    "currentBalance": "0",
+    "address": "0x...",
+    "presets": [5, 10, 20, 50],
+    "hint": "Rerun: aigateway wallet-topup --amount <usdt> --app-id ..."
+  }
 }
 ```
 
-**Dry-run (`--dry-run`)** — preflight checks complete but no signing/transaction occurs:
+### `sb tools`
 
-```json
-{
-  "dryRun": true,
-  "url": "...",
-  "paymentRequirements": { "amountUsdt": 0.66, "amountWei": "660000000000000000", "asset": "0x...", "payTo": "0x...", "orderNo": "..." },
-  "wallet": { "address": "0x..." },
-  "decision": { "needTopup": true, "needGas": false, "topupAmount": "0.660000" },
-  "will": ["fund_usdt_via_walletconnect", "approve_or_skip", "sign_payment_eip712", "submit_to_facilitator", "poll_status"]
-}
-```
+`data` shape depends on the filters supplied:
 
-### `create-card-status`
+| Invocation | `data.mode` | Shape |
+| --- | --- | --- |
+| `sb tools` | (absent) | Full catalog: `{ categories: [{ key, agentTrigger, defaultInputsSchema, models: [...] }], version, ... }` |
+| `sb tools --model <id>` | `"single-model"` | `{ category: "<key>", model: { id, vendor, useCase, price, priceUnit, tier, inputsOverride? }, effectiveSchema: { ... } }` |
+| `sb tools --category <key>` | `"single-category"` | `{ category: { key, agentTrigger, defaultInputsSchema, models: [...] } }` |
+| `sb tools --tier <t>` (alone) | `"tier-filtered"` | Full catalog with each category's `models[]` filtered to `tier === t`, plus `tier: "<t>"` |
 
-```json
-{
-  "success": true,
-  "model": {
-    "orderNo": "...",
-    "orderStatus": "SUCCESS" | "FAIL" | "PROCESSING" | "...",
-    "channelStatus": "...",
-    "cardStatus": "ACTIVE" | "PENDING" | "...",
-    "cardScheme": "VISA" | "MASTERCARD",
-    "cardNumber": "•••• 1234",
-    "...": "(sensitive fields like CVV / expiry are stripped)"
-  }
-}
-```
+`effectiveSchema` = `model.inputsOverride ?? category.defaultInputsSchema` — the JSON-schema-shaped object that `sb invoke` validates against client-side.
 
-### `wallet`
+### `wallet-balance`
 
 ```json
 {
   "mode": "private-key",
   "address": "0x...",
   "usdt": "12.34",
+  "bnb": "0.0003",
   "network": "BSC Mainnet (Chain ID: 56)",
   "mainWallet": { "address": "0x...", "usdt": "..." }
 }
@@ -182,7 +197,7 @@ Every `aigateway` command emits **exactly one line of JSON** to **stdout** —
 For consumers still parsing the pre-envelope JSON shape, pass `--legacy-output` to get the old format on stdout (and errors on **stderr** as before):
 
 ```bash
-aigateway --legacy-output create-card --amount 5
+aigateway --legacy-output wallet-balance
 ```
 
-Legacy mode is kept for one or two minor releases as a migration aid. New integrations should use the envelope.
+Legacy mode is kept as a migration aid. New integrations should use the envelope.

package/docs/recipes/cron-issue-cards.md

@@ -1,31 +1,38 @@
-# Recipe — Schedule Recurring Card Issuance
+# Recipe — Schedule Recurring Paid Invocations
 
-Use this when an agent needs to issue cards on a schedule — for example, "create a $5 card every Monday at 09:00 to seed an autonomous shopping flow."
+> Filename kept for backwards compatibility. The earlier "issue card" workflow has been folded into the unified `aigateway sb invoke` entry point; this recipe now covers any scheduled paid call.
+
+Use this when an agent or automation needs to invoke a paid AI tool on a schedule — for example, "generate a marketing image every Monday at 09:00", "transcribe yesterday's recordings nightly", "run a search summarisation every hour".
 
 ## Prerequisites
 
 1. **Pre-funded session wallet.** WalletConnect requires a browser; cron jobs run headless. Top up the local wallet manually first:
    ```bash
-   aigateway wallet-topup --amount 50    # adds USDT + a tiny amount of BNB for approve gas
+   aigateway wallet-topup --amount 50    # adds USDT + a tiny amount of BNB for the one-time approve
    ```
-2. **One-time `approve`.** Run `aigateway create-card --amount 0.6 --poll` once interactively so the approve transaction is on-chain. Subsequent creates won't need WalletConnect again until USDT is depleted.
+2. **Approve already broadcast.** `wallet-topup` performs the one-time `ERC20.approve(facilitator, MaxUint256)`. After it succeeds, all subsequent `sb invoke` calls are gasless EIP-712 signing — no WalletConnect needed until USDT is depleted.
+3. **Catalog sanity-check.** Before scheduling, run `aigateway sb tools --model <id>` once to confirm the model id is valid and to learn its `effectiveSchema` (so your wrapper builds the correct `--inputs`).
 
 ## A Minimal Wrapper Script
 
-`~/bin/issue-card.sh`:
+`~/bin/invoke-tool.sh`:
 
 ```bash
 #!/usr/bin/env bash
 set -euo pipefail
 
-AMOUNT="${1:-5}"
+MODEL="${1:?model id required}"
+INPUTS_FILE="${2:?path to inputs JSON required}"     # e.g. ~/aigateway/jobs/daily-image.json
 LOG_DIR="${HOME}/.aigateway/logs"
 mkdir -p "$LOG_DIR"
 TS=$(date -u +"%Y-%m-%dT%H-%M-%SZ")
-LOG="$LOG_DIR/issue-${TS}.log"
+LOG="$LOG_DIR/invoke-${TS}.log"
 
 # Capture envelope on stdout; quiet stderr noise
-ENVELOPE=$(aigateway --quiet create-card --amount "$AMOUNT" --poll 2>"$LOG")
+ENVELOPE=$(aigateway --quiet sb invoke \
+  --model "$MODEL" \
+  --inputs "@${INPUTS_FILE}" \
+  2>"$LOG")
 EXIT=$?
 
 echo "$ENVELOPE" > "${LOG%.log}.json"
@@ -37,19 +44,26 @@ if [ "$EXIT" -ne 0 ]; then
   exit "$EXIT"
 fi
 
-ORDER=$(echo "$ENVELOPE" | jq -r '.data.orderNo')
-echo "[$(date -u)] OK orderNo=$ORDER amount=$AMOUNT"
+TX=$(echo "$ENVELOPE" | jq -r '.data.transaction // "—"')
+FIRST=$(echo "$ENVELOPE" | jq -r '.data.downloaded[0].localPath // empty')
+echo "[$(date -u)] OK tx=$TX file=${FIRST:-n/a} model=$MODEL"
 ```
 
 ```bash
-chmod +x ~/bin/issue-card.sh
+chmod +x ~/bin/invoke-tool.sh
 ```
 
 ## Cron Entry
 
 ```cron
 # minute hour dom mon dow  command
-  0      9    *   *   1   /Users/me/bin/issue-card.sh 5 >> /Users/me/.aigateway/logs/cron.log 2>&1
+  0      9    *   *   1   /Users/me/bin/invoke-tool.sh replicate/black-forest-labs/flux-schnell /Users/me/aigateway/jobs/weekly-image.json >> /Users/me/.aigateway/logs/cron.log 2>&1
+```
+
+Example `weekly-image.json`:
+
+```json
+{ "prompt": "neon city skyline at dusk, hyper-detailed", "aspect_ratio": "16:9" }
 ```
 
 > ⚠️ On macOS, `cron` may lack PATH access to `aigateway`. Use an absolute path (`/Users/me/.nvm/versions/node/v25/bin/aigateway`) or source your shell rc inside the wrapper.
@@ -58,12 +72,16 @@ chmod +x ~/bin/issue-card.sh
 
 | Code | Likely cause in cron context | Fix |
 | ---- | ---------------------------- | --- |
-| `INSUFFICIENT_USDT` | Wallet ran dry. | Top up via `aigateway wallet-init` on a workstation. |
-| `INSUFFICIENT_BNB` | Approve allowance expired or BNB depleted by retries. | Run `aigateway wallet-gas` to add a small amount. |
-| `PAYMENT_TIMEOUT` | WalletConnect was triggered (unexpected — should be fully approved). | Run an interactive `aigateway wallet-init` once to refresh allowance. |
-| `SERVICE_UNAVAILABLE` | Upstream outage. | Cron will retry next tick. Alert if 3+ consecutive failures. |
+| `INSUFFICIENT_USDT` / `TOPUP_REQUIRED` | Wallet ran dry. Headless cron cannot scan a QR. | Top up via `aigateway wallet-topup --amount <n>` on a workstation. |
+| `INSUFFICIENT_BNB` | BNB depleted (only matters for `wallet-withdraw` / re-approve). | Run `aigateway wallet-gas` interactively on a workstation. |
+| `INVALID_MODEL_ID` | The model id was renamed or removed upstream. | Run `aigateway sb tools` and update the wrapper's `--model`. |
+| `MISSING_INPUTS` / `INVALID_INPUTS` | Inputs file drifted from the schema (e.g. missing `duration_seconds` for video / `duration_minutes` for STT). | Re-pull `sb tools --model <id>` and fix the JSON. |
+| `MODEL_PRICING_NOT_CONFIGURED` | Upstream removed the model from the pricing config. | Pick another model. |
+| `SERVICE_UNAVAILABLE` / `PAYMENT_FETCH_FAILED` | Upstream outage. | Cron will retry next tick. Alert if 3+ consecutive failures. |
+| `PAYMENT_TIMEOUT` | WalletConnect was unexpectedly triggered (should not happen once approve is on-chain). | Run an interactive `aigateway wallet-topup` once to re-fund / re-approve. |
 
 ## See Also
 
 - [integrate-in-agent.md](./integrate-in-agent.md) — Node.js / Python subprocess wrapper.
 - [error-recovery.md](./error-recovery.md) — Full code-by-code recovery table.
+- [../output-schema.md](../output-schema.md) — `sb invoke` envelope fields used above (`transaction`, `downloaded[]`, `balance`).

package/docs/recipes/error-recovery.md

@@ -6,25 +6,40 @@ Map each `error.code` returned by the envelope to a concrete recovery action. Us
 | ------------ | :--: | -------------------- |
 | `WALLET_NOT_CONFIGURED` | 1 | Run `aigateway wallet-init` once (auto-creates a local session wallet). |
 | `SERVICE_URL_MISSING` | 1 | Override via env `AIGATEWAY_SERVICE_URL`. The default service URL is wired into the CLI for production; this should never trigger in normal use. |
-| `AMOUNT_INVALID` | 1 | Caller bug — input must be a numeric string. |
-| `AMOUNT_OUT_OF_RANGE` | 1 | Re-prompt user with `error.min` ~ `error.max`. Do **not** silently clamp. |
-| `AMOUNT_EXCEEDS_BALANCE` | 1 | Use the smaller of requested vs. `error.available`. |
-| `INSUFFICIENT_USDT` | 1 | Top-up failed or partial. Surface `error.required` / `error.available` to user, ask whether to retry with a new amount. |
-| `INSUFFICIENT_BNB` | 1 | Run `aigateway wallet-gas` to top up a small amount of BNB via WalletConnect, then retry. |
-| `NO_FUNDS` | 1 | Nothing to withdraw. Inform the user, possibly suggest `wallet-topup`. |
-| `NO_MAIN_WALLET` | 1 | Caller must pass `--to <address>`. |
+| `AMOUNT_INVALID` | 1 | Caller bug — input must be a positive numeric string (used by `wallet-topup`, `wallet-gas`, `wallet-withdraw`, `--topup-amount`). |
+| `AMOUNT_EXCEEDS_BALANCE` | 1 | `wallet-withdraw --amount` exceeded available USDT. Use the smaller of requested vs. `error.available`. |
+| `INSUFFICIENT_USDT` | 1 | Top-up failed or the chosen `--topup-amount` was still below the call's required USDT. Surface `error.required` / `error.available`; ask the user to retry with a larger top-up. |
+| `INSUFFICIENT_BNB` | 1 | Approve / withdraw needs BNB for gas. Run `aigateway wallet-gas` (WalletConnect, must be interactive), then retry. |
+| `NO_FUNDS` | 1 | Nothing to withdraw. Inform the user; suggest `wallet-topup` if relevant. |
+| `NO_MAIN_WALLET` | 1 | `wallet-withdraw` invoked with no `mainWallet` saved. Re-run with `--to <address>`. |
+| `MISSING_MODEL` | 1 | `sb invoke --model` is required. Run `aigateway sb tools` to pick one. |
+| `MISSING_INPUTS` | 1 | `sb invoke --inputs` is required, or the JSON is missing required fields. `error.errors[]` lists which fields are missing; `error.required[]` lists all required keys for the model. |
+| `INVALID_INPUTS` | 1 | Inputs failed schema validation. `error.errors[]` items carry `{ field, kind, message }` where `kind ∈ {enum, type, range}`. Fix and retry. |
+| `INVALID_INPUTS_JSON` | 1 | `--inputs` could not be parsed as JSON. Check quoting / escaping; on shells use `JSON.stringify(...)` from your wrapper. |
+| `INPUTS_FILE_NOT_FOUND` | 1 | `--inputs @path` file does not exist. Resolve to an absolute path or correct the caller. |
+| `INVALID_MODEL_ID` | 1 | Server / catalog rejected the model id. Run `aigateway sb tools --category <key>` to find a valid one. |
+| `CATEGORY_NOT_FOUND` | 1 | `sb tools --category` argument is not in the live catalog. Run `aigateway sb tools` (no filter) to list categories. |
+| `MODEL_PRICING_NOT_CONFIGURED` | 1 | The catalog lists the model but the gateway has no price entry yet. Pick another model or ask the operator to add it. |
+| `INVALID_BODY` | 1 | Server rejected the request body shape. Usually a CLI / catalog drift; file a bug. |
+| `TOPUP_REQUIRED` | 1 | Non-TTY context, USDT below the per-call minimum. Choose from `error.presets` (filtered to ≥ `error.minTopup`) and rerun the failing command with `--topup-amount <n>`. |
+| `TOPUP_AMOUNT_TOO_SMALL` | 1 | `--topup-amount` (or `topup --amount`) below `error.minTopup`. Rerun with a larger value. |
 | `PAYMENT_REJECTED` | 1 | User cancelled in their wallet. **Do not auto-retry** — ask user first. |
-| `PAYMENT_TIMEOUT` | 2 | WalletConnect approval expired (5 min). Ask user whether to retry. **Do not auto-retry.** |
-| `WC_SESSION_EXPIRED` | 2 | Reconnect required. Re-run the original command. |
-| `POLL_TIMEOUT` | 2 | Card may still provision. Surface `error.orderNo` and query later with `aigateway create-card-status --order-no <n>`. |
-| `TX_TIMEOUT` | 2 | The on-chain transfer is likely still pending — query the chain or retry the status command. |
+| `PAYMENT_TIMEOUT` | 2 | WalletConnect approval window expired (5 min). Ask user whether to retry. **Do not auto-retry.** |
+| `WC_SESSION_EXPIRED` | 2 | WalletConnect relay dropped the session. Re-run the original command. |
+| `TX_TIMEOUT` | 2 | The on-chain transfer is likely still pending. Wait, then re-check with `wallet-balance`. |
+| `UPDATE_APPLIED` | 2 | CLI just upgraded itself synchronously. The previous command was **not executed**. Surface `error.from` → `error.to` and **rerun the same command verbatim** on the new version. |
 | `SERVICE_UNAVAILABLE` | 3 | Exponential backoff: 1 s → 4 s → 16 s, max 3 attempts. |
-| `PAYMENT_FETCH_FAILED` | 3 | Same as above. Check network connectivity. |
+| `PAYMENT_FETCH_FAILED` | 3 | First 402 probe failed. Backoff + retry; check network connectivity. |
+| `CATALOG_FETCH_FAILED` | 3 | `sb tools` could not reach the server. Retry once; if it persists, `sb invoke` still runs (server-side validation is the safety net). |
 | `BALANCE_CHECK_FAILED` | 3 | BSC RPC hiccup. Retry once after 2 s. |
+| `ALLOWANCE_CHECK_FAILED` | 3 | BSC RPC hiccup. Retry once after 2 s. |
 | `TX_REVERTED` | 3 | On-chain failure. Capture `error.message` for diagnosis; do not retry blindly. |
 | `WITHDRAW_FAILED` | 3 | Withdraw transaction failed. Check `aigateway wallet-balance` and retry. |
+| `APPROVE_FAILED` | 3 | One-time facilitator approve failed during `wallet-topup`. Inspect the tx; retry the top-up. |
 | `INVALID_PAYMENT_AMOUNT` | 3 | Server-side issue (returned amount = 0). Retry after a short delay. |
-| `PAYMENT_FAILED` | 3 | Service rejected the signed request. Surface `error.data` to the user / log. |
+| `PAYMENT_FAILED` | 3 | Service rejected the signed payment request. Surface `error.data` / `error.status` to the user / log. On 5xx, retry once. |
+| `IMAGE_DOWNLOAD_FAILED` / `DOWNLOAD_FAILED` | 3 | The paid call succeeded but the local download failed. The original URL is still in the upstream response — surface it from `data.downloaded[].url` (when available) or re-fetch via `--raw`. **Do not re-invoke the model** (you'd pay again). |
+| `FUNDING_FAILED` | 3 | Non-timeout / non-reject failure in the WalletConnect funding flow. Re-run `wallet-topup`. |
 | `INTERNAL_ERROR` | 4 | File a bug. Don't retry. |
 | `WALLET_ERROR` | 1 | Generic wallet failure. Surface to user, ask whether to retry. |
 
@@ -41,13 +56,29 @@ async function withRetry(fn, { codes, attempts = 3, baseDelayMs = 1000 } = {}) {
 }
 
 // Only retry transient service/network errors
-await withRetry(() => runAEON AI Gateway(["create", "--amount", "5", "--poll"]), {
-  codes: ["SERVICE_UNAVAILABLE", "PAYMENT_FETCH_FAILED", "BALANCE_CHECK_FAILED", "INVALID_PAYMENT_AMOUNT"],
-});
+await withRetry(
+  () => runAigateway([
+    "sb", "invoke",
+    "--model", "replicate/black-forest-labs/flux-schnell",
+    "--inputs", JSON.stringify({ prompt: "a cyberpunk fox" }),
+  ]),
+  {
+    codes: [
+      "SERVICE_UNAVAILABLE",
+      "PAYMENT_FETCH_FAILED",
+      "CATALOG_FETCH_FAILED",
+      "BALANCE_CHECK_FAILED",
+      "ALLOWANCE_CHECK_FAILED",
+      "INVALID_PAYMENT_AMOUNT",
+    ],
+  },
+);
 ```
 
 ## Anti-patterns
 
 - ❌ Don't retry `PAYMENT_REJECTED` or `PAYMENT_TIMEOUT` automatically — the user actively cancelled or walked away.
+- ❌ Don't retry `IMAGE_DOWNLOAD_FAILED` / `DOWNLOAD_FAILED` by re-invoking the model — the paid call already settled, you'd be charged again. Re-fetch the URL or re-run with `--raw`.
 - ❌ Don't match on `error.message` text — messages may change between versions. Match on `error.code`.
 - ❌ Don't ignore exit code in favour of envelope. Stack-level proxies sometimes mangle stdout; the exit code is a redundant safety net.
+- ❌ Don't paper over `UPDATE_APPLIED` by treating it as a generic timeout — it's a "new binary; rerun me" signal, not a failure.

package/docs/recipes/integrate-in-agent.md

@@ -6,15 +6,16 @@ This recipe shows how to invoke `aigateway` from inside an agent product (Node.j
 
 - `@aeon-ai-pay/aigateway` installed (globally for system-wide use, or as a dependency in your project).
 - A working session wallet — run `aigateway wallet-init` once on the host.
+- First-time funding done with `aigateway wallet-topup --amount 5` (one-time WalletConnect flow + facilitator `approve`). After this, all `sb invoke` calls are gasless and headless-friendly.
 
-> ⚠️ The CLI uses **WalletConnect for funding**, which opens a browser window with a QR code. If your agent runs headless or in containers without a display, fund the session wallet ahead of time (`aigateway wallet-init`) on a workstation, then ship the `~/.aigateway/config.json` to the runtime host. Agents should never embed user main-wallet private keys.
+> ⚠️ `wallet-topup` opens a browser window with a WalletConnect QR code. If your agent runs headless or in containers without a display, fund the session wallet ahead of time on a workstation, then ship the `~/.aigateway/config.json` (or its `privateKey`) to the runtime host. Agents should never embed user main-wallet private keys.
 
 ## Node.js — Spawn & Parse Envelope
 
 ```js
 import { spawn } from "node:child_process";
 
-function runAEON AI Gateway(args) {
+function runAigateway(args) {
   return new Promise((resolve, reject) => {
     const child = spawn("aigateway", args, { stdio: ["ignore", "pipe", "pipe"] });
     let stdout = "";
@@ -33,18 +34,20 @@ function runAEON AI Gateway(args) {
   });
 }
 
-// Example: create a $5 card and poll until terminal
-const { envelope, exitCode } = await runAEON AI Gateway([
+// Example: invoke an AI tool (image generation) via the x402 paid entry point
+const { envelope, exitCode } = await runAigateway([
   "--quiet",
-  "create",
-  "--amount", "5",
+  "sb", "invoke",
+  "--model", "replicate/black-forest-labs/flux-schnell",
+  "--inputs", JSON.stringify({ prompt: "a cyberpunk fox", aspect_ratio: "1:1" }),
   "--app-id", "MY_AGENT_001",
-  "--poll",
 ]);
 
 if (envelope.ok) {
-  const { orderNo, data } = envelope.data;
-  console.log("Card ready:", data.model?.cardNumber, "order:", orderNo);
+  const { model, transaction, downloaded, balance } = envelope.data;
+  console.log(`Done (${model}) tx=${transaction}`);
+  for (const d of downloaded) console.log(`Saved: ${d.localPath} (${d.sizeHuman})`);
+  console.log(`Charged ${balance.charged} USDT, remaining ${balance.after}`);
 } else {
   // See docs/recipes/error-recovery.md for code-by-code guidance
   console.error(`Failed [${envelope.error.code}] (exit ${exitCode}):`, envelope.error.message);
@@ -74,22 +77,40 @@ def run_aigateway(args):
     envelope = json.loads(result.stdout.strip().splitlines()[-1])
     return result.returncode, envelope
 
-exit_code, env = run_aigateway(["create", "--amount", "5", "--poll"])
+exit_code, env = run_aigateway([
+    "sb", "invoke",
+    "--model", "replicate/black-forest-labs/flux-schnell",
+    "--inputs", json.dumps({"prompt": "a cyberpunk fox"}),
+])
 if env["ok"]:
-    print("Card ready:", env["data"]["data"]["model"]["cardNumber"])
+    for d in env["data"]["downloaded"]:
+        print("Saved:", d["localPath"])
 else:
     print(f"Failed [{env['error']['code']}] exit={exit_code}: {env['error']['message']}")
 ```
 
-## Probing Without Cost — `--dry-run`
+## Discovering Models — `sb tools`
 
-To validate inputs, balances, and allowance **without** signing or transacting, use `--dry-run` on `create-card`:
+Before calling `sb invoke`, fetch the live catalog with `sb tools` to pick a valid `model` and learn the expected `inputs` schema:
 
 ```bash
-aigateway --quiet create-card --amount 5 --dry-run | jq '.data.will, .data.decision'
+# Single model + effectiveSchema (most useful for agents)
+aigateway --quiet sb tools --model replicate/black-forest-labs/flux-schnell | jq '.data'
+
+# All models in a category
+aigateway --quiet sb tools --category image | jq '.data.categories[0].models[].id'
+
+# Cheapest tier across all categories
+aigateway --quiet sb tools --tier price
 ```
 
-This is ideal for integration tests, configuration smoke checks, and "is everything ready?" probes.
+The catalog is fetched live from the server each call (no local cache). Each model carries `price`, `priceUnit`, `tier`, and an optional `inputsOverride`; each category carries `defaultInputsSchema`.
+
+## Probing Without Cost
+
+`sb invoke` performs client-side validation of `--model` and `--inputs` against the live catalog **before** any x402 round-trip. Invalid model ids and missing/invalid fields return `INVALID_MODEL_ID` / `MISSING_INPUTS` / `INVALID_INPUTS` locally, with zero USDT spent.
+
+For wallet-only smoke tests, `aigateway wallet-balance` is read-only and never signs anything.
 
 ## Exit Code Strategy
 
@@ -99,7 +120,7 @@ Treat exit codes as a fast filter, then branch on `error.code` for nuance:
 switch (exitCode) {
   case 0: /* success */ break;
   case 1: /* user / config — surface to caller for correction */ break;
-  case 2: /* timeout — safe to retry; card may still be provisioning */ break;
+  case 2: /* timeout — safe to retry the same command */ break;
   case 3: /* network / service — exponential backoff retry */ break;
   case 4: /* internal — log + fail loud */ break;
 }