feat: optional catalog_id on POST /api/emails leads the email with the value delta

SW
4mo ago
+1222-3

Summary

Row 5 of chat#1911: the weekly report leads with the value delta. Implements the contract in docs#281 - an optional catalog_id on POST /api/emails that turns any send into a delta-led report: subject prefixed $1.1M (+10.0%) · <subject>, valuation hero block above the body.

Stacked on api#795 (needs selectCatalogValuations + the catalog_valuations history), so this branch contains #795's commit until it merges. Merge order: docs#281 → database#52 → api#795 → this.

What it does

  • lib/catalog/getCatalogValuationDelta.ts: the two most recent history rows → {current, previous}; one row → baseline (previous: null); empty history but measured songs → read-time band fallback (so the first report after the table ships still leads with a number); empty catalog or any failure → null, never throws.
  • lib/emails/valuationDelta/buildValuationDeltaSubjectPrefix.ts: $1.1M (+10.0%) · / $900K (-10.0%) · / $1.1M baseline · / percent omitted when the previous mid is zero. Money via the shared formatCompactUsd (DRY with the valuation report).
  • lib/emails/valuationDelta/renderValuationDeltaHero.ts: previous → current + signed % (green/red), or the baseline note "Your baseline is set. The next report shows the change." Table-based inline-style markup like the valuation report blocks. No em dashes (asserted by test).
  • processAndSendEmail: opt-in via catalog_id; enrichment is try/caught so a delta failure never costs a delivery.
  • sendEmailHandler + validateSendEmailBody: catalog_id (uuid) accepted on the REST body and passed through only after selectAccountCatalog confirms ownership - an unowned id is dropped and the email sends unchanged (documented behavior; a caller can never lead their email with someone else's valuation).
  • MCP send_email deliberately untouched (YAGNI): the weekly-report task sends flow through the REST path, and the MCP handler has no account resolution today.

Tests (TDD, red→green)

19 new tests across 3 new suites + 7 wiring cases in processAndSendEmail.test.ts / sendEmailHandler.test.ts (subject+hero on delta, unchanged on null delta, still-sends on throw, no delta path without catalog_id, ownership pass-through/drop/skip). All confirmed RED first.

  • Full suite: 794 files / 4306 tests green
  • tsc --noEmit: exactly the 236-error baseline. Note: the one hit inside processAndSendEmail.test.ts (result.error narrowing) pre-exists on the base branch at line 129 (verified by stashing); my insertions only shifted its line number.
  • eslint clean on all touched files

Tracked in chat#1911 row 5.

🤖 Generated with Claude Code


Summary by cubic

POST /api/emails accepts an optional catalog_id to lead emails with the catalog’s valuation delta (subject prefix + hero), gated by ownership. Added persisted valuation history and a new GET /api/catalogs/{catalogId}/valuations to power the delta and reports, fulfilling chat#1911 (weekly report leads with value delta).

  • New Features

    • POST /api/emails: optional catalog_id; only applied if the caller owns the catalog; best‑effort (email sends unchanged on unowned/empty/failure).
    • Delta UX: subject prefix like "$1.1M (+10.0%) · " or "baseline" when no previous; percent omitted when previous is zero; hero block shows previous → current with signed change.
    • Persist valuations to catalog_valuations: on valuation runs (always) and on whole‑catalog measurements reads once per UTC day (deduped).
    • GET /api/catalogs/{catalogId}/valuations: auth + ownership; 404 if unowned; limit 1–100 (default 30); latest‑first rows with { low, mid, high, measured_song_count, total_streams, measured_at }.
    • Internal helpers: select/insert history, compute delta, and email enrichment wired into processAndSendEmail.
  • Migration

    • Deploy the catalog_valuations table before enabling this feature.
    • No client changes required; MCP send_email path is unchanged.