Skip to content

feat: add Command Code quota dashboard - #8

Merged
peach0x33a merged 3 commits into
peach0x33a:masterfrom
xnqycs:master
Sep 12, 2026
Merged

peach0x33a merged 3 commits into
peach0x33a:masterfrom
xnqycs:master

Conversation

@xnqycs

@xnqycs xnqycs commented Sep 12, 2026

Copy link
Copy Markdown
Collaborator

Summary

Adds a per-account Command Code quota dashboard — 5-hour / weekly / estimated
monthly quota, credit balances, plan and billing period — rendered in the WebUI
and cached in usage.json.

Data is read from the undocumented /alpha/* endpoints of api.commandcode.ai
with each account's existing API key. Endpoint shapes and the plan mapping
follow the community
commandcode-usage project.

What's included

Backend (internal/app/quota.go)

  • QuotaSnapshot / QuotaWindow / QuotaPlan / QuotaUsage plus the four
    upstream queries: whoami, billing/credits, billing/subscriptions
    (?orgId= from whoami), usage/summary.
  • Defensive parsing: camelCase or snake_case keys, epoch seconds /
    milliseconds / ISO timestamps, flat or data-wrapped responses. Unknown
    plans show balances only; the monthly bar is derived from the plan mapping
    (used = cap − remaining) and labelled as estimated.
  • Partial failures keep the successful parts; a fully failed query keeps the
    last snapshot and only updates last_error / last_checked. A 401/403 on
    whoami short-circuits without hitting the remaining endpoints.
  • QuotaService refreshes once at startup and every 5 minutes, at most 4
    accounts in flight, and stops with the server's shutdown context.

Persistence

  • Per-account snapshots live in usage.json behind a dedicated
    persistedUsage shape, so quota data never reaches the unauthenticated
    /usage endpoint.
  • Deleting an account clears its snapshot; replacing a key drops the old
    credential's snapshot and refreshes the new one.

Admin API

  • GET /admin/api/accounts gains a nested quota object per account.
  • POST /admin/api/accounts/{id}/quota/refresh — refresh one account.
  • POST /admin/api/quotas/refresh — refresh all, or one via {"id": "..."}.
  • GET /admin/api/overview gains a quotas summary (synced, exceeded,
    low_balance, last_checked_at).
  • Adding an account (including OAuth) or replacing a key triggers a background
    refresh for the new credential.

WebUI

  • Overview: a "quota sync" card and exceeded / low-balance counters.
  • Accounts: 5-hour / weekly / estimated-monthly progress bars with the
    reference color grading (≥50% amber, ≥75% heavier, ≥90% red), credit
    balances, plan, billing period, last check time and quota errors.
  • Per-account "refresh quota" plus a "refresh all" button; reset countdowns
    include days, and resetAt = 0 shows as "no reset point".
  • Each account row and its quota block render as a single visual unit.

Testing

  • go vet ./... and go test -race -count=1 ./... pass locally — the same
    checks CI runs.
  • 20 new tests in internal/app/quota_test.go cover: parsing variants
    (nesting, key casing, timestamp formats, plan prefix matching, missing
    fields), the four upstream requests with their Bearer header and orgId
    query, 401/403 / non-JSON / partial failures, snapshot retention on failure,
    usage.json round-trip, deletion and key-change behavior, and all admin
    endpoints.
  • Manual smoke test against a mock upstream: WebUI login, quota rendering,
    per-account refresh and refresh-all.

Notes

  • The /alpha/* endpoints are unofficial. The parser tolerates field drift,
    and when a query fails the UI keeps showing the last cached snapshot
    alongside the error.
  • The monthly cap comes from a community plan mapping rather than an official
    monthly window, so it is labelled as an estimate and hidden for unknown
    plans.

Fetch each account's Command Code quota from the undocumented /alpha/*
endpoints (whoami, billing/credits, billing/subscriptions, usage/summary)
using the account's existing API key, and surface it in the WebUI.

- Parse defensively: camelCase or snake_case keys, epoch seconds,
  milliseconds or ISO timestamps, and flat or `data`-wrapped responses.
  Unknown plans fall back to balance-only display; the monthly bar is
  derived from the community CLI plan mapping and labelled as estimated.
- Cache per-account snapshots in usage.json behind a dedicated
  persistedUsage shape so they never reach the unauthenticated /usage
  endpoint. A failed query keeps the last successful snapshot and only
  records the error and check time.
- Refresh once at startup and every 5 minutes, at most four accounts in
  flight, stopping with the server's shutdown context.
- Expose `quota` on GET /admin/api/accounts, add
  POST /admin/api/accounts/{id}/quota/refresh and POST /admin/api/quotas/refresh,
  and add a quota summary to GET /admin/api/overview. Adding an account or
  replacing its key triggers a refresh for the new credential.
- WebUI: quota sync card on the overview, 5-hour / weekly / estimated
  monthly bars with the reference color grading, credit balances, plan and
  billing period, per-account and refresh-all buttons. Reset countdowns
  include days, and resetAt=0 is shown as "no reset point".
- Accounts tab renders each account and its quota as one block, with the
  bars width-bounded so the metadata never overflows.

Tests cover parsing variants, the four upstream requests and their auth,
partial / rejected / non-JSON failures, snapshot retention, persistence,
and the admin endpoints.
@xnqycs xnqycs self-assigned this Sep 12, 2026
@xnqycs xnqycs added the enhancement New feature or request label Sep 12, 2026
countersFor took the counter map by value, so AccountUsage / ClientKeyUsage
read the u.accounts / u.clientKeys field at the call site, before accMu was
acquired. The quota service now initializes those maps from a background
goroutine (SetQuota -> ensureMapsLocked after an account is added), so a
concurrent GET /admin/api/accounts raced with that write.

Pass the map by pointer and dereference it under accMu.

CI reproduced this with `go test -race -count=1 ./...` failing in
TestAdminAccountLifecycle.
@peach0x33a
peach0x33a merged commit 0909635 into peach0x33a:master Sep 12, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants