apiblaze 0.21.14 → 0.21.15

package/README.md

@@ -1,5 +1,7 @@
 # apiblaze
 
+> **Superseded 2026-09-24** for throttling, quota and credits by `specs/TQC/final_throttling_quota_credits.MD`. Upstash is gone; anything below about Redis keys, Lua gates, leases-on-Upstash or the reclaim/reconcile crons is historical.
+
 CLI for [APIblaze](https://apiblaze.com) — chat with your APIs, run them as serverless proxies, and let your customers self-serve keys, users & groups from your own site.
 
 ---
@@ -25,7 +27,7 @@ The easiest way is to just chat with it:
 npx apiblaze agent
 ```
 
-> Talk in plain English — "make an API for httpbin.org", "rate-limit it to 50/sec",
+> Talk in plain English — "make an API for httpbin.org", "set its rate limit to 50/sec",
 > "give me a key". It does the work and shows what each step costs.
 
 Prefer commands? A few one-liners:
@@ -156,7 +158,7 @@ calls it makes — as copy-pasteable `curl` you could run yourself with your own
 login token, plus the underlying admin-api leaf each one drives:
 
 ```bash
-apiblaze throttle myapi --rate 50 --verbose
+apiblaze limits set myapi --rate 50 --verbose
 ```
 
 ## Commands
@@ -218,11 +220,46 @@ Every chat turn shows its cost.
 | Command | What it does |
 |---|---|
 | `apiblaze target <project> --url <url> [--env <e>]` | Change where it forwards requests |
-| `apiblaze throttle <project> [--rate n] [--quota n] [--period daily\|weekly\|monthly]` | Set rate limits and quotas |
 | `apiblaze rename <project> --display-name <name>` | Rename it |
 | `apiblaze spec get <project>` | Print its OpenAPI spec |
 | `apiblaze spec set <project> --file <path>` | Replace its OpenAPI spec from a file |
 
+### Producer — limits
+
+Three names, fixed: **rate limit** (requests per second — Standard mode is approximate per
+location and free, Strict is exact per consumer), **quota** (an exact count per fixed UTC
+window) and **spend cap** (exact dollars per month). Every rate is shown with its 10-second
+figure beside it (`50/s (500 per 10 s)`), because that is the window the Standard limiter counts.
+
+| Command | What it does |
+|---|---|
+| `apiblaze limits get <project> [--version v]` | Show mode, rate limits, ceiling, quota, spend cap, credential quota |
+| `apiblaze limits set <project> [--rate n] [--end-user-rate n] [--mode strict\|standard] [--quota n --period daily\|weekly\|monthly] [--spend-cap usd] [--credential-quota n]` | Change any subset (`--quota none` / `--spend-cap none` clear). A rate above the self-serve ceiling is refused and the output prints the exact `limits request-max` command |
+| `apiblaze limits request-max <project> --rps n [--use-case "…"]` | Ask for a higher ceiling (instant to 1,000/s for a proven wallet; an operator approves above) |
+| `apiblaze limits usage <project> [--watch]` | The team quota meter: used / in use / limit / resets in. Per-project usage is not exposed by the API yet — the output says so |
+| `apiblaze config <project> limits.<key> [value]` | The same settings by key: `limits.mode`, `limits.consumerRps`, `limits.endUserRps`, `limits.ceilingRps` (read-only), `limits.quota.limit`, `limits.quota.period`, `limits.spendCapCents`. The old `throttling.*` keys still work for one release |
+
+> `apiblaze throttle <project> --rate n --quota n --period p` still works for one release: it
+> prints a deprecation line and runs `limits set` with the same numbers.
+
+### Producer — billing
+
+| Command | What it does |
+|---|---|
+| `apiblaze billing balance [--team]` | Available, in use (pre-paid to live requests), grace owed, status, auto-rebuy, last top-up. Numbers are shown only to the wallet owner |
+| `apiblaze billing topup <usd> [--team] [--open]` | Prints (or opens) the dashboard wallet page for that amount — card checkout runs in your browser session |
+| `apiblaze billing history [--since d] [--until d] [--project p] [--format table\|json\|csv] [--raw]` | Usage and exact cost as daily rollups, per consumer key; `--raw` = hourly |
+| `apiblaze billing rebuy on\|off\|status [--amount usd] [--threshold usd]` | Auto-rebuy: add `--amount` whenever available drops under `--threshold` |
+
+When a call is refused for money or limits, every command prints the same thing for the same
+refusal (`application/problem+json`): `service-paused` shows the producer's contact and status
+page (and, if it is your wallet, the `billing topup` hint), `trial-exhausted` the claim URL,
+`quota-exceeded` when it resets, `spend-cap-reached` the `limits set` command, and
+`platform-degraded` when to retry.
+
+Exit codes for every command: `0` ok, `1` your input (flags, not found, forbidden), `2` the
+server could not answer (5xx) — retry on 2.
+
 > Every command in these two sections accepts `--verbose` (see the equivalent API
 > calls), plus `--team`, `--apiversion`, and `--json`.