feat(songs): free tier analyzes 5 tracks a month; 402 plan_limit on POST /api/songs/analyze

SW
2mo ago
+623-36

Item "free tier: 5 analyze requests per calendar month" of recoupable/app#2061. Implements the contract in recoupable/docs#337. Merge order: docs#337, then this PR, then app and marketing show the row.

Why

Every account gets $3.33 of free credits a month; at the $0.05 base that is up to 66 GPU-backed calls we pay Modal for with no revenue, and nothing distinguished analyze from cheaper endpoints. A cap makes the free tier a taste of Music Flamingo and a reason to subscribe. Cost of the cap if fully used with cold single-preset calls: 5 × ~$0.07 = $0.36 per free account per month at the 60 s scale-down window.

What changes

  • getPlanEntitlements: analyze_limit (Free 5, Starter and Pro null). buildAccountCreditsResponse returns it beside task_limit and min_cadence_minutes.
  • countAnalyzedTracksSince (lib/supabase/usage_events/): distinct resource_url among the account's provider = modal rows since a bound. One track = one audio_url, so full_report (13 rows) counts once and repeats are free. No new table or column.
  • getCalendarMonthStart: first instant of the UTC month.
  • buildAnalyzePlanLimitBody: the documented 402 (limit: analyze_count, analyze_limit, current_analyze_count, billingUrl → /plan). PlanLimitError now carries either the task body or this one.
  • assertAnalyzeWithinPlan: resolves the plan via getAccountSubscriptionState; uncapped plans return without a query; capped plans count and throw at the cap.
  • postFlamingoGenerateHandler: validate → plan gate → credit gate → process; PlanLimitError → 402 with CORS. registerAnalyzeMusicTool: same gate before its credit check; the message comes back as the tool error.

Org-backed and enterprise accounts resolve to pro, so Seeker is uncapped.

Tests (red → green per unit)

  • getCalendarMonthStart (2), countAnalyzedTracksSince (3), buildAnalyzePlanLimitBody (1), assertAnalyzeWithinPlan (4: under cap, at cap, starter and pro never query).
  • postFlamingoGenerateHandler.planLimit.test.ts (3): 402 before the credit gate and no model call; thrown plan lookup → 500; allowed → gate → 200. registerAnalyzeMusicTool.test.ts (+1).
  • Entitlement and credits-response tests extended with analyze_limit.

Full api suite: 966 files / 5215 tests green. tsc --noEmit and eslint clean on the touched files.

Preview verification (fresh free key: tracks 1–5 → 200, track 6 → 402 plan_limit with no Modal call, a repeat of track 1 → 200, full_report counted once, Seeker's org key → 200, credits response carries analyze_limit) to follow in a comment once the deployment is Ready.

🤖 Generated with Claude Code

https://claude.ai/code/session_0194KNv9zWevLUxi84wPs2TN


Summary by cubic

Caps the previously unlimited free tier at 5 Music Flamingo track analyses per calendar month, returning a documented 402 plan_limit on POST /api/songs/analyze once the cap is reached; Starter and Pro stay uncapped. Implements recoupable/app#2061 (merge the recoupable/docs#337 contract first).

New Features

  • Counts distinct resource_url values on the account's provider = modal usage rows since the UTC month start, so a full_report (13 rows, one URL) counts once and re-analyzing a track is free.
  • The gate runs after validation and before the credit gate, so a blocked request never starts a Modal call or deducts credits.
  • analyze_limit (Free 5, Starter/Pro null) is added to plan entitlements and the GET /api/accounts/{id}/credits response.
  • The analyze_music MCP tool runs the same plan-then-credit gate order via gateAnalyzeForTool and returns the limit message as a tool error; org-backed and enterprise accounts resolve to pro and stay uncapped.

Summary by CodeRabbit

  • New Features

    • Added monthly song-analysis limits based on subscription plans.
    • Free plans include up to 5 analyses per month; Starter and Pro plans remain uncapped.
    • Reanalyzing the same track does not count as an additional analysis.
    • Account credit information now displays the applicable analysis limit.
  • Bug Fixes

    • Analysis requests consistently enforce plan limits before consuming credits.
    • Users who reach their limit receive a clear plan-limit response, while credit-related errors remain distinct.
    • Song analysis through supported tools now follows the same plan and credit checks.