#213 docs(admins): document credit usage rollup + events endpoints

Summary

Documentation-driven development for the per-customer credit usage view on the admin dashboard. Defines the API contract first; the api implementation follows in a separate PR.

Two new admin endpoints:

Endpoint	Purpose
GET /api/admins/credits/rollup?period=…&limit=…	Per-account rollup, sorted by total credits deducted descending. Joins accounts + account_emails for human-readable rows.
GET /api/admins/credits/events?account_id=…&period=…&limit=…	Raw usage_events rows for one account, sorted by created_at descending. Powers the drilldown subtable that expands when a rollup row is opened.

Decisions baked into this contract

• Period selector: reuses the existing admin enum all | daily | weekly | monthly (per lib/admins/adminPeriod.ts in api). daily=1d / weekly=7d / monthly=30d / all=no cutoff. Default monthly.
• Authorization: validateAdminAuth — accepts both x-api-key and Authorization: Bearer, then runs checkIsAdmin(accountId). Returns 401 (no creds) or 403 (not admin), matching every other endpoint under /api/admins/.
• Account identity in the rollup row: account_id (UUID) + account_name (from accounts) + account_email (from account_emails) so the admin table is readable without further client-side joins.
• Sort + scale: rollup sorted by total_credits_deducted_cents DESC, limit default 100 (max 500) — matches the agreed "top 100 with show more" behavior.
• Drilldown is a separate endpoint (lazy-loaded on row expand) rather than inline events in the rollup payload, so the rollup view stays snappy even with many accounts.

Follow-ups (separate PRs)

1. api repo — implement getAdminCreditsRollupHandler + getAdminCreditsEventsHandler under lib/admins/credits/, wire app/api/admins/credits/rollup/route.ts and app/api/admins/credits/events/route.ts, TDD with vitest.
2. admin repo — /credits page using @tanstack/react-table with the existing PeriodSelector, lazy-load events on row expand.

Test plan

• python3 -c "import json; json.load(open('api-reference/openapi/accounts.json'))" — OpenAPI JSON parses
• python3 -c "import json; json.load(open('docs.json'))" — navigation config parses
• Mintlify preview renders both pages with the expected request/response examples
• Nav shows the two new entries under the Admin group

🤖 Generated with Claude Code

---

Summary by cubic

Adds OpenAPI and Mintlify docs for admin credit usage: GET /api/admins/credits/rollup (per-account totals) and GET /api/admins/credits/events (per-account events) for the admin dashboard. Lets admins see top spenders and drill into event details.

Docs include page-based pagination (page query; page, limit, total_count in responses), period/limit and account_id (events), admin auth via x-api-key or Bearer; adds both pages to the Admin nav and cross-links them; API implementation will follow.

Summary by CodeRabbit

• New Features

  • Added two new admin endpoints for credit usage analytics: one for per-account rollup totals and one for detailed usage event logs with filtering.

• Documentation

  • Added API reference pages documenting the new credit tracking endpoints.