OmniRoute/changelog.d/features/11190-usage-command-json.md at b1fdfd5ea4e0729388e987cae82bde109e3581e5

mirror of https://github.com/diegosouzapw/OmniRoute.git synced 2026-08-25 16:42:16 +03:00

Files

Diego Rodrigues de Sa e Souza eb9fa33ee7 feat(api): structured ?format=json for the self-service usage endpoint (#11190 )

* feat(api): structured ?format=json for the self-service usage endpoint

GET /api/usage/om-usage already let any key read its own usage — personal
daily/weekly USD limits and the provider quota snapshot — but only as
text/plain, which a UI cannot parse safely. OmniCopilot issue #8 asks exactly
for this surface.

Adds ?format=json, returning the ApiKeyUsageLimitStatus + UsageSnapshot the
text is rendered from. Text and JSON share the same collectors
(collectUsageSnapshots, getApiKeyUsageLimitStatus), so the two can never
disagree about a number. The response is a discriminated union: a key without
allowUsageCommand (403) or an invalid key (401) returns
{ allowed:false, error:{message} }, distinct from allowed:true with empty
sections — the state a panel must render as "nothing learned yet", not a
refusal. Text form unchanged; without ?format the contract is untouched.

The endpoint was previously missing from API_REFERENCE.md; it now has a
section documenting both forms, the allowUsageCommand gate, and the
self-service auth model (caller's own key, not requireManagementAuth).

Regression guards in tests/unit/usage-command-json-format.test.ts (4 tests:
json shape, text default preserved, structured 403, sanitized 401 with no
stack trace). Existing internal-usage-command suite still 12/12.

* chore(changelog): correct the fragment to the real PR number (#11190)

---------

Co-authored-by: Xiangzhe <bakryun0718@proton.me>

2026-08-22 22:23:17 -03:00

711 B

Raw Blame History

feat(api): /api/usage/om-usage gains a structured form — ?format=json returns the key's own usage as ApiKeyUsageLimitStatus + UsageSnapshot instead of text/plain. This is the surface a UI (the OmniCopilot panel) consumes to show a key holder their daily/weekly spend and quota reset. The route is self-service (the caller's own key, gated by allowUsageCommand), not the management surface; refusals come back as a discriminated { "allowed": false, "error": … } so a UI can tell "not allowed" apart from "allowed but nothing cached yet". The endpoint was previously undocumented in API_REFERENCE.md; it now has a section (#11190)

711 B Raw Blame History

711 B

Raw Blame History