feat(admin): add credits rollup + events endpoints

Merged
SW
5mo ago
+808-28

Summary

Adds two admin-only endpoints powering the admin credits dashboard. Contract was defined first in recoupable/docs#213 (merged).

  • GET /api/admins/credits/rollup — per-account credit usage totals over the selected period. Sorted by total credits DESC. Joined with account names + emails for human-readable rows. Page-based pagination with total_count.
  • GET /api/admins/credits/events — raw usage_events rows for one account in the selected period. Powers the drilldown subtable lazy-loaded when an admin expands a rollup row.

Design notes

  • Period selector: follows existing admin convention — all | daily | weekly | monthly (default monthly).
  • Aggregation: rollup aggregates events by account_id in JS, not SQL. Acceptable at admin scale; documented in code as a future Postgres-function migration target.
  • Auth: both endpoints require validateAdminAuth (x-api-key OR Bearer token + checkIsAdmin).
  • Pagination: page-based with separate COUNT query for total_count; no has_more (per docs PR review).

Files

  • app/api/admins/credits/{rollup,events}/route.ts — thin route delegators
  • lib/admins/credits/getAdminCredits{Rollup,Events}Handler.ts — business logic
  • lib/admins/credits/validateGetAdminCredits{Rollup,Events}Query.ts — Zod validators
  • lib/admins/credits/getCutoffMs.ts — period → UTC midnight cutoff helper
  • lib/supabase/usage_events/selectAdminCredits{Rollup,Events}.ts — DB queries
  • lib/admins/credits/__tests__/ — 15 vitest cases covering auth, validation, aggregation, sort, pagination, period cutoff

Test plan

  • pnpm test lib/admins/credits/__tests__/ — 15/15 pass
  • pnpm test (full suite) — 491 files / 2872 tests pass
  • pnpm format clean
  • pnpm lint clean
  • Test against preview deployment with admin API key (rollup + events for sweetman Pro account)
  • Verify period filter behavior (monthly vs all)
  • Verify pagination (page=2, limit=2)

🤖 Generated with Claude Code

Summary by cubic

Adds admin credits rollup and events endpoints for the dashboard with period filters and pagination. Centralizes cutoff utils in lib/admins/ and makes reads deterministic; rollup fetches all matching rows to avoid Supabase caps.

  • New Features

    • GET /api/admins/credits/rollup — per-account totals for the selected period, sorted by total credits desc; joins account name and email; page-based pagination with total_count.
    • GET /api/admins/credits/events — paginated usage_events for one account over the selected period, sorted by created_at desc.

  • Refactors

    • Moved getCutoffMs and PERIOD_DAYS to lib/admins/; getCutoffMs now returns number | null (null for all); updated privy and slack.
    • Data access: range-based selectUsageEvents with deterministic ordering (created_at + id desc) and countUsageEvents; rollup uses lib/admins/credits/selectAllUsageEvents to fetch all batches, breaks ties by account_id asc, and picks the most-recent account_emails.email.

Summary by CodeRabbit

  • New Features
    • Added admin API endpoints to retrieve detailed credit usage events with pagination support.
    • Added admin API endpoint to view aggregated credit usage rollup by account with sorting and pagination.

Review Change Stack