@aeon-ai-pay/aigateway 0.2.3 → 0.2.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (21) hide show
  1. package/README.md +20 -0
  2. package/docs/env-vars.md +12 -14
  3. package/docs/exit-codes.md +25 -15
  4. package/docs/ide-setup.md +2 -2
  5. package/docs/output-schema.md +73 -58
  6. package/docs/recipes/cron-issue-cards.md +34 -16
  7. package/docs/recipes/error-recovery.md +47 -16
  8. package/docs/recipes/integrate-in-agent.md +37 -16
  9. package/docs/recipes/merchant-integration.md +61 -32
  10. package/docs/troubleshooting.md +61 -13
  11. package/package.json +11 -5
  12. package/skills/aigateway/SKILL.md +5 -2
  13. package/src/commands/sb-invoke.mjs +13 -1
  14. package/src/commands/wallet-init.mjs +27 -1
  15. package/src/config.mjs +13 -0
  16. package/src/constants.mjs +3 -0
  17. package/src/coupon.mjs +62 -0
  18. package/templates/cline/.clinerules +36 -18
  19. package/templates/codex/AGENTS.md +48 -16
  20. package/templates/cursor/.cursor/rules/aigateway.mdc +27 -14
  21. package/templates/windsurf/.windsurfrules +24 -13
package/src/coupon.mjs ADDED
@@ -0,0 +1,62 @@
1
+ /**
2
+ * Coupon client — AEON x BNB Chain AI Agent Campaign.
3
+ *
4
+ * 调用服务端 POST /open/api/coupon/claim 申请优惠券 token。
5
+ * 返回归一化结构:
6
+ * { ok: true, code: "SUCCESS", tokenAmount, tokenAddress, txHash, campaignId }
7
+ * { ok: false, code: "ALREADY_CLAIMED" | "CAMPAIGN_QUOTA_EXHAUSTED" | "MINT_FAILED" | ...,
8
+ * errorMsg, status? }
9
+ *
10
+ * 错误吞掉(网络/超时/任何异常)返回 { ok: false, code: "CLAIM_NETWORK_ERROR", errorMsg },
11
+ * 让调用方(wallet-init)继续主流程,不要因为优惠券领取失败阻塞钱包初始化。
12
+ */
13
+ import axios from "axios";
14
+
15
+ export async function claimCoupon({ serviceUrl, userAddress, deviceId, appId, campaignId }) {
16
+ if (!serviceUrl) {
17
+ return { ok: false, code: "SERVICE_URL_MISSING", errorMsg: "serviceUrl is required" };
18
+ }
19
+ if (!userAddress) {
20
+ return { ok: false, code: "INVALID_PARAM", errorMsg: "userAddress is required" };
21
+ }
22
+
23
+ const url = `${serviceUrl}/open/api/coupon/claim`;
24
+ const body = {
25
+ campaignId: campaignId || undefined,
26
+ userAddress,
27
+ deviceId: deviceId || undefined,
28
+ appId: appId || undefined,
29
+ };
30
+
31
+ try {
32
+ const resp = await axios.post(url, body, {
33
+ timeout: 60_000,
34
+ headers: { "Content-Type": "application/json" },
35
+ });
36
+ // 服务端约定:HTTP 200 + APIResponse 包装 + data 字段 = CouponClaimResult
37
+ const envelope = resp.data;
38
+ const result = envelope?.model || envelope?.data || envelope;
39
+ if (result?.ok) {
40
+ return {
41
+ ok: true,
42
+ code: result.code || "SUCCESS",
43
+ campaignId: result.campaignId,
44
+ tokenAddress: result.tokenAddress,
45
+ tokenAmount: result.tokenAmount,
46
+ txHash: result.txHash,
47
+ };
48
+ }
49
+ return {
50
+ ok: false,
51
+ code: result?.code || "UNKNOWN",
52
+ errorMsg: result?.errorMsg || "Unknown coupon error",
53
+ };
54
+ } catch (e) {
55
+ return {
56
+ ok: false,
57
+ code: "CLAIM_NETWORK_ERROR",
58
+ errorMsg: e.message,
59
+ status: e.response?.status,
60
+ };
61
+ }
62
+ }
package/templates/cline/.clinerules CHANGED
@@ -1,26 +1,36 @@
1
- # aigateway — Virtual Card via x402
1
+ # aigateway — AI Tool Invocation via x402
2
2
 
3
- Trigger this rule when the user wants to create / query / manage one-time virtual debit cards funded via USDT on BSC.
3
+ Trigger this rule when the user wants to invoke any paid AI tool (image, video, TTS, STT, search, scraping, social data, email, SMS, document parsing, UI generation, embeddings, finance, news, utility) funded via USDT on BSC.
4
4
 
5
5
  ## Setup (run once)
6
6
 
7
7
  ```bash
8
- aigateway wallet-init
8
+ aigateway wallet-init # auto-creates a local session wallet
9
+ aigateway wallet-topup --amount 5 # one-time WalletConnect funding + facilitator approve (gasless from here)
9
10
  ```
10
11
 
11
- `envelope.data.ready === true` means ready.
12
+ `envelope.data.ready === true` means ready. If `envelope.data.needsTopup === true`, run `wallet-topup` next.
12
13
 
13
14
  ## Commands
14
15
 
15
16
  ```bash
16
- aigateway create-card --amount <USD> --poll # Create card, poll until ready
17
- aigateway create-card --amount <USD> --app-id <merchantId> --poll # With merchant app ID
18
- aigateway create-card-status --order-no <orderNo> # Single status query
19
- aigateway create-card-status --order-no <orderNo> --poll # Poll until terminal
20
- aigateway wallet-balance # Show local wallet balance
21
- aigateway wallet-topup --amount <USDT> # WalletConnect: USDT top-up
22
- aigateway wallet-gas --amount <BNB> # WalletConnect: BNB gas top-up
23
- aigateway wallet-withdraw [--to 0x...] [--amount <USDT>] # Reclaim funds
17
+ # Discover models (live catalog, free)
18
+ aigateway sb tools # full catalog
19
+ aigateway sb tools --category <key> # e.g. image / video / tts / stt / search / scraper / ...
20
+ aigateway sb tools --model <id> # single model + effectiveSchema
21
+ aigateway sb tools --tier <price|balanced|quality> # filter by tier
22
+
23
+ # Paid invocation (the only paid call)
24
+ aigateway sb invoke --model <id> --inputs '<json>' [--output <dir>] [--raw]
25
+
26
+ # Optional merchant app id on any command
27
+ aigateway sb invoke --model <id> --inputs '<json>' --app-id <merchantId>
28
+
29
+ # Wallet management
30
+ aigateway wallet-balance # show local USDT / BNB
31
+ aigateway wallet-topup --amount <USDT> # WalletConnect: USDT top-up
32
+ aigateway wallet-gas --amount <BNB> # WalletConnect: BNB top-up
33
+ aigateway wallet-withdraw [--to 0x...] [--amount <USDT>] # reclaim funds
24
34
  ```
25
35
 
26
36
  ## Envelope
@@ -32,22 +42,30 @@ stdout = one line of JSON.
32
42
 
33
43
  Branch on `error.code`. Exit codes: `0`/`1`/`2`/`3`/`4` = success/user/timeout/service/internal.
34
44
 
45
+ `sb invoke` success payload: `model`, `inputs`, `transaction`, `downloaded[]` (binary artifacts saved locally), `raw` (upstream JSON), `balance` (`initial`/`before`/`after`/`charged`/`topup`). Binary outputs default to `~/aigateway-{images,videos,audio}/`.
46
+
35
47
  ## Hard Rules
36
48
 
37
49
  - No private keys from the user.
38
- - No full card numbers, CVV, or expiry in output (already sanitized).
39
- - WalletConnect-opening commands (`create-card` / `create-image` when underfunded / `wallet-init` / `wallet-gas`) must run in foreground.
50
+ - No hard-coded model ids — always pull from `aigateway sb tools` first.
51
+ - No category-as-model ids (`--model tts` is wrong; `--model minimax/speech-01-turbo` is right).
52
+ - WalletConnect-opening commands (`wallet-topup` / `wallet-gas`, plus `sb invoke` when underfunded) must run in foreground.
40
53
  - No auto-retry on `PAYMENT_REJECTED` or `PAYMENT_TIMEOUT`.
54
+ - No re-invoke on `DOWNLOAD_FAILED` — re-fetch `data.downloaded[].url`.
41
55
 
42
56
  ## Recovery Cheatsheet
43
57
 
44
58
  | Code | Action |
45
59
  | --- | --- |
46
- | `AMOUNT_OUT_OF_RANGE` | Show `error.min`/`error.max`; ask user. |
47
- | `INSUFFICIENT_USDT` | `aigateway wallet-init` then retry. |
60
+ | `MISSING_MODEL` / `INVALID_MODEL_ID` | Run `aigateway sb tools` and pick a valid id. |
61
+ | `MISSING_INPUTS` / `INVALID_INPUTS` | Read `error.errors[]` (`field` + `kind`); rebuild `--inputs` from `effectiveSchema` (re-pull via `sb tools --model <id>`). |
62
+ | `INVALID_INPUTS_JSON` | Quoting bug. Use `JSON.stringify` or `--inputs @path/to/file.json`. |
63
+ | `INSUFFICIENT_USDT` / `TOPUP_REQUIRED` | `aigateway wallet-topup --amount <n>` (use `error.presets`) or pass `--topup-amount <n>` to `sb invoke`. |
48
64
  | `INSUFFICIENT_BNB` | `aigateway wallet-gas` then retry. |
49
- | `POLL_TIMEOUT` | Note `orderNo`; query later. |
65
+ | `MODEL_PRICING_NOT_CONFIGURED` | Pick another model. |
50
66
  | `PAYMENT_REJECTED` / `PAYMENT_TIMEOUT` | Ask user before retrying. |
51
- | `SERVICE_UNAVAILABLE` | Exponential backoff retry. |
67
+ | `DOWNLOAD_FAILED` / `IMAGE_DOWNLOAD_FAILED` | Call already paid; re-fetch `data.downloaded[].url`. |
68
+ | `UPDATE_APPLIED` | CLI upgraded itself; rerun the same command verbatim. |
69
+ | `SERVICE_UNAVAILABLE` / `PAYMENT_FETCH_FAILED` / `CATALOG_FETCH_FAILED` | Exponential backoff retry. |
52
70
 
53
71
  Full reference: `docs/output-schema.md`, `docs/exit-codes.md`, `docs/recipes/`.
package/templates/codex/AGENTS.md CHANGED
@@ -1,24 +1,33 @@
1
- # aigateway — Virtual Card Agent Rules
1
+ # aigateway — AI Tool Invocation Agent Rules
2
2
 
3
- When a user asks to **create, query, or manage** a one-time virtual debit card funded with USDT on BSC, use the `aigateway` CLI as the source of truth.
3
+ When a user asks to **generate, transcribe, search, scrape, or otherwise invoke an AI tool** with pay-per-call USDT settlement on BSC, use the `aigateway` CLI as the source of truth.
4
4
 
5
5
  ## Setup (run once per environment)
6
6
 
7
7
  ```bash
8
- aigateway wallet-init
8
+ aigateway wallet-init # local session wallet check / create
9
+ aigateway wallet-topup --amount 5 # one-time WalletConnect funding + facilitator approve (gasless from here on)
9
10
  ```
10
11
 
11
- Returns an envelope on stdout; `envelope.data.ready === true` means ready.
12
+ `wallet-init` returns an envelope on stdout; `envelope.data.ready === true` means ready. If `envelope.data.needsTopup === true`, run `wallet-topup` next.
12
13
 
13
14
  ## Command Surface
14
15
 
15
16
  ```bash
16
- aigateway create-card --amount <USD> [--app-id <merchantId>] --poll # Create card
17
- aigateway create-card-status --order-no <orderNo> [--poll] # Query status
18
- aigateway wallet-balance # Local balance
19
- aigateway wallet-topup --amount <USDT> # USDT top-up via WalletConnect
20
- aigateway wallet-gas --amount <BNB> # BNB top-up via WalletConnect
21
- aigateway wallet-withdraw [--to 0x...] [--amount <USDT>] # Reclaim funds
17
+ # Discover models (live catalog, no x402)
18
+ aigateway sb tools # full catalog
19
+ aigateway sb tools --category <key> # e.g. image / video / tts / stt / search / scraper / ...
20
+ aigateway sb tools --model <id> # single model + effectiveSchema
21
+ aigateway sb tools --tier <price|balanced|quality> # filter by tier
22
+
23
+ # Paid invocation (x402)
24
+ aigateway sb invoke --model <id> --inputs '<json>' [--output <dir>] [--raw] # unified paid entry point
25
+
26
+ # Wallet management
27
+ aigateway wallet-balance # local USDT / BNB
28
+ aigateway wallet-topup --amount <USDT> # USDT top-up via WalletConnect
29
+ aigateway wallet-gas --amount <BNB> # BNB top-up via WalletConnect (for withdraw / re-approve)
30
+ aigateway wallet-withdraw [--to 0x...] [--amount <USDT>] # reclaim funds to main wallet
22
31
  ```
23
32
 
24
33
  `--app-id` defaults to `TEST000001`. `--quiet` suppresses stderr noise. `--legacy-output` swaps the envelope for the old pre-envelope JSON shape.
@@ -34,23 +43,46 @@ Stderr is human-readable progress. Match on `error.code` (stable), not on `error
34
43
 
35
44
  Exit codes: `0` success · `1` user · `2` timeout · `3` service/network · `4` internal.
36
45
 
46
+ ### `sb invoke` success payload
47
+
48
+ ```json
49
+ {
50
+ "model": "<model_id>",
51
+ "inputs": { /* echo of what was sent */ },
52
+ "transaction": "0x..." | null,
53
+ "downloaded": [
54
+ { "url": "...", "localPath": "...", "format": "png", "width": 1024, "height": 1024, "sizeBytes": 412345, "sizeHuman": "402.7 KB" }
55
+ ],
56
+ "raw": { /* upstream vendor response */ },
57
+ "balance": { "initial": "...", "before": "...", "after": "...", "charged": 0.01, "topup": null }
58
+ }
59
+ ```
60
+
61
+ Binary outputs (image / video / audio) populate `downloaded[]`. JSON-only outputs (search, scrape, social_data, email, embeddings, …) live under `raw`.
62
+
37
63
  ## Hard Rules
38
64
 
39
65
  - **Never** prompt for private keys. The CLI auto-generates a local session wallet.
40
- - **Never** display full card numbers, CVV, or expiry. The CLI already redacts these to `•••• 1234`.
41
- - **Never** run `create-card` / `create-image` / `wallet-init` / `wallet-gas` in the background — they open a WalletConnect QR window.
66
+ - **Never** hard-code model ids in prompts — vendors rename. Always pull from `aigateway sb tools` first.
67
+ - **Never** use a category name as a model id (`--model tts` is wrong; `--model minimax/speech-01-turbo` is right).
68
+ - **Never** run `wallet-topup` / `wallet-gas` / `sb invoke` (with empty wallet) in the background — they open a WalletConnect QR window.
42
69
  - **Never** auto-retry `PAYMENT_REJECTED` or `PAYMENT_TIMEOUT`. Ask the user.
70
+ - **Never** re-invoke a model on `DOWNLOAD_FAILED` / `IMAGE_DOWNLOAD_FAILED` — the call settled, re-fetch the URL from `data.downloaded[].url`.
43
71
 
44
72
  ## Error Recovery (high-frequency cases)
45
73
 
46
74
  | `error.code` | Action |
47
75
  | ------------ | ------ |
48
- | `AMOUNT_OUT_OF_RANGE` | Show `error.min` / `error.max`; re-prompt user. |
49
- | `INSUFFICIENT_USDT` | Run `aigateway wallet-init`, then re-run create. |
76
+ | `MISSING_MODEL` / `INVALID_MODEL_ID` | Run `aigateway sb tools` to pick a valid id. |
77
+ | `MISSING_INPUTS` / `INVALID_INPUTS` | Inspect `error.errors[]` (each `{ field, kind, message }`); rebuild `--inputs` from the model's `effectiveSchema` (re-pull via `sb tools --model <id>`). |
78
+ | `INVALID_INPUTS_JSON` | Quoting / escaping bug in the caller. Use `JSON.stringify` or `--inputs @path/to/file.json`. |
79
+ | `INSUFFICIENT_USDT` / `TOPUP_REQUIRED` | Top up via `aigateway wallet-topup --amount <n>` (use `error.presets`), or pass `--topup-amount <n>` to `sb invoke`. |
50
80
  | `INSUFFICIENT_BNB` | Run `aigateway wallet-gas`, then re-run the failing op. |
51
- | `POLL_TIMEOUT` | Card may still be provisioning. Note `error.orderNo`. |
81
+ | `MODEL_PRICING_NOT_CONFIGURED` | The model is in the catalog but not priced yet. Pick another. |
52
82
  | `PAYMENT_REJECTED` | User cancelled. Ask before retrying. |
53
83
  | `PAYMENT_TIMEOUT` | 5-minute approval window expired. Ask before retrying. |
54
- | `SERVICE_UNAVAILABLE` | Retry with exponential backoff (1s → 4s → 16s, max 3). |
84
+ | `DOWNLOAD_FAILED` / `IMAGE_DOWNLOAD_FAILED` | The call succeeded and was paid. Re-fetch the URL from `data.downloaded[].url`. Do not re-invoke. |
85
+ | `UPDATE_APPLIED` | CLI just upgraded itself. Rerun the same command verbatim on the new version. |
86
+ | `SERVICE_UNAVAILABLE` / `PAYMENT_FETCH_FAILED` / `CATALOG_FETCH_FAILED` | Retry with exponential backoff (1s → 4s → 16s, max 3). |
55
87
 
56
88
  Full schema and recipes: see `docs/output-schema.md`, `docs/exit-codes.md`, and `docs/recipes/`.
package/templates/cursor/.cursor/rules/aigateway.mdc CHANGED
@@ -1,27 +1,31 @@
1
1
  ---
2
- description: Use the aigateway CLI to create and manage one-time virtual debit cards via the x402 payment protocol on BSC. Trigger on intents like "create a card", "buy a virtual card", "card status", "top up", "withdraw funds".
2
+ description: Use the aigateway CLI to invoke 200+ paid AI tools (image, video, TTS, STT, search, scraping, email, document, social data, UI generation, embeddings, finance, utility) via the x402 protocol on BSC. Trigger on intents like "generate an image", "make a video", "transcribe this audio", "search the web", "scrape this page", "send an email", "parse this PDF", "top up wallet", "check balance".
3
3
  alwaysApply: false
4
4
  ---
5
5
 
6
- # aigateway — Virtual Card via x402
6
+ # aigateway — AI Tool Invocation via x402
7
7
 
8
- Use this rule when the user wants to **create, query, or manage** one-time-use virtual debit cards funded via USDT on BSC.
8
+ Use this rule when the user wants to invoke any paid AI tool (image generation, video, TTS, STT, web search, scraping, social data, email, SMS, document parsing, UI generation, embeddings, finance, news, utility) funded via USDT on BSC.
9
9
 
10
10
  ## First-time setup (always run once)
11
11
 
12
12
  ```bash
13
- aigateway wallet-init
13
+ aigateway wallet-init # auto-creates a local session wallet
14
+ aigateway wallet-topup --amount 5 # one-time WalletConnect funding + facilitator approve (gasless from here)
14
15
  ```
15
16
 
16
- Auto-creates a local session wallet if missing. Returns an envelope; `envelope.data.ready === true` means ready.
17
+ `wallet-init` returns an envelope; `envelope.data.ready === true` means ready. If `envelope.data.needsTopup === true`, run `wallet-topup` next.
17
18
 
18
19
  ## Commands
19
20
 
20
21
  | Intent | Command |
21
22
  | --- | --- |
22
- | Create a $N card and poll until ready | `aigateway create-card --amount <N> --poll` |
23
- | Specify merchant app ID (optional) | `aigateway create-card --amount <N> --app-id <merchantId> --poll` |
24
- | Check status of an existing order | `aigateway create-card-status --order-no <orderNo>` |
23
+ | List all available tool models | `aigateway sb tools` |
24
+ | Narrow by category | `aigateway sb tools --category image` (or `video` / `tts` / `stt` / `search` / `scraper` / `social_data` / `email` / `sms` / `document` / `ui_generation` / `embeddings` / `financial` / `news` / `utility`) |
25
+ | Inspect a single model + its `effectiveSchema` | `aigateway sb tools --model <id>` |
26
+ | Filter by price tier | `aigateway sb tools --tier price` (or `balanced` / `quality`) |
27
+ | Invoke a tool (the only paid call) | `aigateway sb invoke --model <id> --inputs '<json>' [--output <dir>] [--raw]` |
28
+ | Optional merchant app id | append `--app-id <merchantId>` to any command |
25
29
  | Show local wallet balance | `aigateway wallet-balance` |
26
30
  | Top up USDT from main wallet (interactive WalletConnect) | `aigateway wallet-topup --amount <USDT>` |
27
31
  | Top up BNB for gas (interactive WalletConnect) | `aigateway wallet-gas --amount <BNB>` |
@@ -36,22 +40,31 @@ Every command writes **one line of JSON** to stdout: the envelope.
36
40
 
37
41
  Stderr is human-readable progress; pass `--quiet` if you want it suppressed.
38
42
 
43
+ `sb invoke` success payload includes `model`, `inputs`, `transaction`, `downloaded[]` (binary artifacts saved locally), `raw` (upstream JSON), and `balance` (`initial`/`before`/`after`/`charged`/`topup`). Binary outputs default to `~/aigateway-{images,videos,audio}/`.
44
+
39
45
  ## Error Handling
40
46
 
41
47
  Branch on `error.code` (stable). Common cases:
42
48
 
43
- - `AMOUNT_OUT_OF_RANGE` — Show valid range from `error.min` / `error.max`, ask user.
44
- - `INSUFFICIENT_USDT` / `INSUFFICIENT_BNB` — Run `aigateway wallet-init` / `aigateway wallet-gas` then retry.
49
+ - `MISSING_MODEL` / `INVALID_MODEL_ID` — Run `aigateway sb tools` to pick a valid id; don't guess from memory.
50
+ - `MISSING_INPUTS` / `INVALID_INPUTS` — `error.errors[]` lists `{ field, kind, message }` items; rebuild `--inputs` from the model's `effectiveSchema` (re-pull via `sb tools --model <id>`).
51
+ - `INVALID_INPUTS_JSON` — Quoting bug in the caller. Use `JSON.stringify` or `--inputs @path/to/file.json`.
52
+ - `INSUFFICIENT_USDT` / `TOPUP_REQUIRED` — Top up via `aigateway wallet-topup --amount <n>` (use `error.presets`) or pass `--topup-amount <n>` to `sb invoke`.
53
+ - `INSUFFICIENT_BNB` — Run `aigateway wallet-gas` then retry.
54
+ - `MODEL_PRICING_NOT_CONFIGURED` — Model exists in catalog but isn't priced yet. Pick another.
45
55
  - `PAYMENT_REJECTED` / `PAYMENT_TIMEOUT` — User cancelled or didn't respond. **Do not auto-retry**; ask first.
46
- - `POLL_TIMEOUT` — Card may still be provisioning. Note the `orderNo`, query later.
56
+ - `DOWNLOAD_FAILED` / `IMAGE_DOWNLOAD_FAILED` — Call succeeded and was paid. Re-fetch `data.downloaded[].url`; do **not** re-invoke (you'd pay twice).
57
+ - `UPDATE_APPLIED` — CLI just upgraded itself. Rerun the same command verbatim.
47
58
  - Exit codes: `0` success, `1` user error, `2` timeout, `3` service/network, `4` internal.
48
59
 
49
60
  ## Hard Rules
50
61
 
51
- - **Never** ask the user for a private key — the local wallet is auto-generated.
52
- - **Never** display the full card number, CVV, or expiry. Output already redacts these to `•••• 1234`.
53
- - **Never** run `create-card` / `create-image` / `wallet-init` / `wallet-gas` in the background — they may open a WalletConnect QR window that needs user attention.
62
+ - **Never** ask the user for a private key — the local session wallet is auto-generated.
63
+ - **Never** hard-code model ids — vendors rename, always pull from `aigateway sb tools` first.
64
+ - **Never** use a category key as a model id (`--model tts` is wrong; `--model minimax/speech-01-turbo` is right).
65
+ - **Never** run `wallet-topup` / `wallet-gas` / `sb invoke` (with an underfunded wallet) in the background — they may open a WalletConnect QR window that needs user attention.
54
66
  - **Never** auto-retry rejected / timed-out signatures.
67
+ - **Never** re-invoke on `DOWNLOAD_FAILED` — the URL is still in `data.downloaded[].url`.
55
68
 
56
69
  ## Full Reference
57
70
 
package/templates/windsurf/.windsurfrules CHANGED
@@ -1,22 +1,26 @@
1
- # aigateway — Virtual Card via x402
1
+ # aigateway — AI Tool Invocation via x402
2
2
 
3
- When the user wants to create / query / manage a one-time virtual debit card funded with USDT on BSC, use the `aigateway` CLI.
3
+ When the user wants to invoke any paid AI tool (image, video, TTS, STT, search, scraping, social data, email, SMS, document parsing, UI generation, embeddings, finance, news, utility) funded with USDT on BSC, use the `aigateway` CLI.
4
4
 
5
5
  ## First-time setup (always run once)
6
6
 
7
7
  ```bash
8
- aigateway wallet-init
8
+ aigateway wallet-init # auto-creates a local session wallet
9
+ aigateway wallet-topup --amount 5 # one-time WalletConnect funding + facilitator approve (gasless from here)
9
10
  ```
10
11
 
11
- `envelope.data.ready === true` means ready.
12
+ `envelope.data.ready === true` means ready. If `envelope.data.needsTopup === true`, run `wallet-topup` next.
12
13
 
13
14
  ## Commands
14
15
 
15
16
  | Intent | Command |
16
17
  | --- | --- |
17
- | Create a $N card and poll until ready | `aigateway create-card --amount <N> --poll` |
18
- | Specify merchant app ID | `aigateway create-card --amount <N> --app-id <merchantId> --poll` |
19
- | Check status of an existing order | `aigateway create-card-status --order-no <orderNo>` |
18
+ | List all available tool models | `aigateway sb tools` |
19
+ | Narrow by category | `aigateway sb tools --category <image\|video\|tts\|stt\|search\|scraper\|social_data\|email\|sms\|document\|ui_generation\|embeddings\|financial\|news\|utility>` |
20
+ | Inspect a single model + `effectiveSchema` | `aigateway sb tools --model <id>` |
21
+ | Filter by price tier | `aigateway sb tools --tier <price\|balanced\|quality>` |
22
+ | Invoke a tool (the only paid call) | `aigateway sb invoke --model <id> --inputs '<json>' [--output <dir>] [--raw]` |
23
+ | Optional merchant app id | append `--app-id <merchantId>` to any command |
20
24
  | Show local wallet balance | `aigateway wallet-balance` |
21
25
  | Top up USDT (interactive WalletConnect) | `aigateway wallet-topup --amount <USDT>` |
22
26
  | Top up BNB for gas (interactive WalletConnect) | `aigateway wallet-gas --amount <BNB>` |
@@ -31,18 +35,25 @@ Every command emits one line of JSON to stdout (the envelope):
31
35
 
32
36
  Branch on `error.code` (stable). Exit codes: `0` success, `1` user, `2` timeout, `3` service/network, `4` internal.
33
37
 
38
+ `sb invoke` success payload: `model`, `inputs`, `transaction`, `downloaded[]` (binary artifacts), `raw` (upstream JSON), `balance` (`initial`/`before`/`after`/`charged`/`topup`). Binary outputs default to `~/aigateway-{images,videos,audio}/`.
39
+
34
40
  ## Hard Rules
35
41
 
36
- - Never ask for a private key. The local wallet is auto-generated.
37
- - Never display full card numbers, CVV, or expiry — output is already sanitized.
38
- - Never run `create-card` / `create-image` / `wallet-init` / `wallet-gas` in the background; they open a QR window requiring user attention.
42
+ - Never ask for a private key. The local session wallet is auto-generated.
43
+ - Never hard-code model ids — vendors rename, always pull `aigateway sb tools` first.
44
+ - Never use a category key as a model id (e.g. `--model tts` is wrong; `--model minimax/speech-01-turbo` is right).
45
+ - Never run `wallet-topup` / `wallet-gas` / `sb invoke` (when underfunded) in the background; they open a QR window requiring user attention.
39
46
  - Never auto-retry `PAYMENT_REJECTED` / `PAYMENT_TIMEOUT`.
47
+ - Never re-invoke a model on `DOWNLOAD_FAILED` — the URL is still in `data.downloaded[].url`.
40
48
 
41
49
  ## Common Recovery
42
50
 
43
- - `AMOUNT_OUT_OF_RANGE` → Show `error.min` / `error.max`, ask for a new amount.
44
- - `INSUFFICIENT_USDT` → Run `aigateway wallet-init`, then retry create.
51
+ - `MISSING_MODEL` / `INVALID_MODEL_ID` → Run `aigateway sb tools` to pick a valid id.
52
+ - `MISSING_INPUTS` / `INVALID_INPUTS` → Read `error.errors[]` (`field` + `kind`), rebuild `--inputs` from the model's `effectiveSchema` (re-pull via `sb tools --model <id>`).
53
+ - `INSUFFICIENT_USDT` / `TOPUP_REQUIRED` → Use `error.presets`; run `aigateway wallet-topup --amount <n>` or pass `--topup-amount <n>` to `sb invoke`.
45
54
  - `INSUFFICIENT_BNB` → Run `aigateway wallet-gas`, then retry the failing op.
46
- - `POLL_TIMEOUT` → Note `orderNo`, ask user to query later with `aigateway create-card-status --order-no <orderNo>`.
55
+ - `MODEL_PRICING_NOT_CONFIGURED` → Pick another model.
56
+ - `DOWNLOAD_FAILED` / `IMAGE_DOWNLOAD_FAILED` → Re-fetch `data.downloaded[].url`; do not re-invoke.
57
+ - `UPDATE_APPLIED` → CLI upgraded itself; rerun the same command verbatim.
47
58
 
48
59
  Full reference: `docs/output-schema.md`, `docs/exit-codes.md`, `docs/recipes/`.