feat: persist catalog valuations + GET /api/catalogs/{catalogId}/valuations

SW
4mo ago
+755-0

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), optional dedupeDaily
  • runValuationHandler — 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 via validateAuthContext (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 or x-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_valuations table is deployed before releasing this endpoint. No client changes required.

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.