feat: persist catalog valuations + GET /api/catalogs/{catalogId}/valuations
Summary
Row 15 of chat#1889: the keystone. est_catalog_value was computed on every run and read but never persisted. This PR writes it to the new catalog_valuations history table and exposes the series via GET /api/catalogs/{catalogId}/valuations.
Merge order: docs#279 (contract) → database#52 (table — hard dependency, must merge before this) → this PR.
What it does
Persist (two sites, one helper):
lib/catalog/persistCatalogValuation.ts— best-effort (never fails the caller), optionaldedupeDailyrunValuationHandler— every valuation run writes a row (each run is a fresh measurement)getCatalogMeasurementsHandler— whole-catalog reads write at most one row per catalog per UTC day; artist-scoped reads never write (they value a slice, not the catalog)
Read:
GET /api/catalogs/{catalogId}/valuations?limit=— latest-first series, limit 1–100 default 30,limit=1= current value. Auth viavalidateAuthContext(bearer or x-api-key); unowned/missing catalog → 404; bad catalogId/limit → 400. Flat{ status, valuations }with rows{ low, mid, high, measured_song_count, total_streams, measured_at }, matching docs#279 exactly.
Supabase layer: lib/supabase/catalog_valuations/{insertCatalogValuation,selectCatalogValuations}.ts + hand-added catalog_valuations block in types/database.types.ts (regenerates identically once database#52 merges).
Tests (TDD, red→green)
18 new tests across 5 new suites + 2 wiring cases added to getCatalogMeasurementsHandler.test.ts (persists daily-deduped on whole-catalog reads; never on artist-scoped reads). All confirmed RED before implementation.
- Full suite: 791 files / 4287 tests passed
tsc --noEmit: 236 errors — the pre-existing baseline, none in touched files- eslint clean on all new/touched files
runValuationHandler has no unit harness (repo convention for that orchestrator); its persist wiring will be verified live on the preview (run a valuation → row appears in the GET).
Closes nothing on its own — tracked in chat#1889 row 15.
🤖 Generated with Claude Code
Summary by cubic
Persist catalog valuation bands to catalog_valuations and add GET /api/catalogs/{catalogId}/valuations to read the history (limit=1 returns the current value). This turns ephemeral est_catalog_value into a stored time series for charts and audits.
-
New Features
- Persists valuation rows with low/mid/high, measured_song_count, total_streams, measured_at. Writes on every valuation run; daily-deduped on whole-catalog reads; never on artist-scoped reads; best-effort (never fails the caller).
- Adds GET
/api/catalogs/{catalogId}/valuations?limit=(1–100, default 30), latest-first. Auth via bearer orx-api-key; 400 on invalid catalogId/limit; 404 if catalog is missing or not owned. Returns{ valuations: [{ low, mid, high, measured_song_count, total_streams, measured_at }] }.
-
Migration
- Ensure the
catalog_valuationstable is deployed before releasing this endpoint. No client changes required.
- Ensure the
Summary by CodeRabbit
- New Features
- Added an API for retrieving catalog valuation history, including configurable result limits.
- Valuation records are shown latest-first with valuation ranges, measurement dates, song counts, and stream totals.
- Newly calculated catalog valuations are saved to history automatically.
- Daily duplicate records are prevented for catalog-wide measurements.
- Added validation, authentication, access checks, and CORS support for valuation history requests.