feat: optional catalog_id on POST /api/emails leads the email with the value delta
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 sharedformatCompactUsd(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 viacatalog_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 afterselectAccountCatalogconfirms 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_emaildeliberately 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 insideprocessAndSendEmail.test.ts(result.errornarrowing) 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: optionalcatalog_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;limit1–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.
- POST
-
Migration
- Deploy the
catalog_valuationstable before enabling this feature. - No client changes required; MCP
send_emailpath is unchanged.
- Deploy the