Skip to content

feat(usage): allow callers to read own usage with no-store and window resets (#513) - #568

Open
sparkysolutions10-pixel wants to merge 1 commit into
Divinity-Labs:mainfrom
sparkysolutions10-pixel:feat/caller-own-usage-513
Open

sparkysolutions10-pixel wants to merge 1 commit into
Divinity-Labs:mainfrom
sparkysolutions10-pixel:feat/caller-own-usage-513

Conversation

@sparkysolutions10-pixel

Copy link
Copy Markdown
Contributor

Description

Fixes #513.

Summary of Changes

Callers previously had no way to inspect their remaining quota or window reset timing until hitting an overage or 402 rejection.

This PR implements the caller-facing usage inspection endpoints in accordance with all acceptance criteria:

  1. Self-Service Usage Endpoint (GET /usage and GET /usage/me):
    • Callers present their own API key (Authorization: Bearer <key>) to read their own usage.
    • Strictly derives the target key from the authenticated request context (req.apiKey.id). Any query string parameters (such as ?keyId=...), URL parameters, or body parameters are completely ignored, guaranteeing zero cross-key leakage.
  2. Identical Numbers as Quota Enforcement:
    • Backed by the exact same getUsageSummaryInternal() computation and Redis counters used by checkQuota() in src/x402/metering.ts.
  3. Window Reset Diagnostics:
    • Added dailyResetsAt, monthlyResetsAt, resets: { daily, monthly }, and resetsInSeconds: { daily, monthly } countdowns to UsageSummary.
  4. Cache Invalidation (no-store):
    • Sets Cache-Control: no-store on the response so shared or intermediary caches never retain per-caller usage.
  5. OpenAPI Parity:
    • Documented /usage (alias for /usage/me) and updated UsageResponse schema in openapi.yaml and generated openapi.json.
  6. Comprehensive Test Suite:
    • Added src/__tests__/callerUsage.test.ts verifying 401 unauthenticated handling, proper usage extraction with reset countdowns and no-store, and cross-key parameter isolation.

Testing

  • npx vitest run src/__tests__/callerUsage.test.ts (3/3 passed)
  • npx vitest run src/__tests__/usage.test.ts tests/openapi.test.ts (14/14 passed)
  • MiroFish 14-Pillar Council Score: 14/14 Passed (98.91% Merge Probability Ratio)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

A caller cannot see their own usage

1 participant