chore: import upstream snapshot with attribution

2026-07-13 12:22:33 +08:00
commit fc4fcbab58
1848 changed files with 472303 additions and 0 deletions
@@ -0,0 +1,50 @@
+---
+summary: "sub2api setup for group API-key quota, subscription usage, and wallet balance."
+read_when:
+  - Configuring sub2api usage tracking
+  - Monitoring multiple sub2api groups
+  - Troubleshooting the sub2api /v1/usage integration
+---
+
+# sub2api
+
+CodexBar reads the accounting data exposed by a sub2api group API key. It calls only `GET /v1/usage`; it does not
+send model requests, read prompts, or require a dashboard JWT.
+
+## Setup
+
+Configure the deployment URL in Settings → Providers → sub2api. The URL must use HTTPS, except for loopback HTTP
+such as `http://127.0.0.1:8080` during local development.
+
+For one group, paste its key into the fallback API key field or configure environment variables:
+
+```bash
+export SUB2API_BASE_URL=https://sub2api.example.com
+export SUB2API_API_KEY=sk-...
+```
+
+For multiple groups, create one key per group in sub2api, then add each key under **Group API keys** with a descriptive
+label such as `Claude`, `Codex`, or `Gemini`. CodexBar's account switcher selects the active key; stacked account mode
+can fetch and display several group keys at once.
+
+## Display
+
+The response mode determines what CodexBar shows:
+
+- Quota-limited key: total quota plus optional 5-hour, daily, and 7-day rate-limit windows.
+- Subscription group: daily, weekly, and monthly spend against configured limits, plus expiration.
+- Wallet group: current wallet balance.
+- All modes: today and total key-scoped requests, tokens, and actual cost when sub2api returns them.
+
+Usage totals are scoped to the authenticated key. Wallet balance is scoped to the owning user, so CodexBar keeps it
+on each account card and does not sum it across keys.
+
+For subscription groups, CodexBar displays the daily, weekly, and monthly counters returned by `/v1/usage`. These
+windows follow the subscription's billing anchors; the endpoint does not expose enough boundary information to
+reconstruct them safely from the key-scoped calendar-day series. If several keys share one group, the subscription
+counters can therefore be shared even though the request and cost totals remain key-scoped.
+
+## Security
+
+Keys are stored using CodexBar's existing provider config or token-account storage. CodexBar sends a key only to the
+validated base URL using `Authorization: Bearer <key>`.