release: play-count write path (test → main)

Merged
SW
4mo ago
+1589-0

Promotes exactly one change: #662 — POST /api/research/snapshots + playcountSnapshotWorkflow, the budget-gated songstatsBackfillWorkflow over the database#33 claim RPC, and the daily /api/internal/playcount-maintenance cron.

Preview-verified twice with real data (results tables on #662): all three input-resolution paths, write→read integration, pricing behavior (snapshots uncharged, reads 5 credits), claim-RPC SKIP LOCKED semantics. The first prod cron run (07:00 UTC) live-fires the backfill drain — queue primed.

Release scope checked: 35ebe415 is the only commit on test not on main. Completes the api surface of recoupable/chat#1791.

🤖 Generated with Claude Code

Summary by cubic

Adds the play-count write path: POST /api/research/snapshots with a durable snapshot workflow, plus a budget-gated Songstats backfill worker triggered by a daily cron.

  • New Features

    • POST /api/research/snapshots: resolves catalog/album IDs/ISRCs to album IDs, enforces a per-org monthly cap, returns 202 with a cost estimate, and starts playcountSnapshotWorkflow.
    • playcountSnapshotWorkflow: captures albums in chunks (100/step), writes measurements with run and snapshot lineage, and marks state transitions.
    • songstatsBackfillWorkflow: drains the queue within a rolling 30‑day budget, claims via claim_songstats_backfill_rows RPC (SKIP LOCKED), records quota spend, and writes Songstats historic series as permanent measurements.
    • /api/internal/playcount-maintenance: cron-protected (CRON_SECRET) endpoint that starts the backfill drain and re-runs due monthly snapshots; scheduled at 07:00 UTC in vercel.json.

  • Migration

    • Set CRON_SECRET in environment for the cron route.
    • Ensure the claim_songstats_backfill_rows database RPC is deployed.
    • Optionally tune caps: SNAPSHOT_MONTHLY_CAP_USD (default 25), SONGSTATS_QUOTA_LIMIT (default 1000), SONGSTATS_QUOTA_RESERVE (default 100).

Summary by CodeRabbit

  • New Features
    • Added playcount snapshot API with cost tracking and monthly spending limits
    • Introduced automated monthly playcount snapshot generation for recurring analysis
    • Implemented Songstats data backfill system with quota management and rate limiting
    • Added internal maintenance endpoint for automated data processing tasks