feat(songs): free tier analyzes 5 tracks a month; 402 plan_limit on POST /api/songs/analyze
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 Pronull).buildAccountCreditsResponsereturns it besidetask_limitandmin_cadence_minutes.countAnalyzedTracksSince(lib/supabase/usage_events/): distinctresource_urlamong the account'sprovider = modalrows since a bound. One track = oneaudio_url, sofull_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).PlanLimitErrornow carries either the task body or this one.assertAnalyzeWithinPlan: resolves the plan viagetAccountSubscriptionState; 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_urlvalues on the account'sprovider = modalusage rows since the UTC month start, so afull_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/Pronull) is added to plan entitlements and theGET /api/accounts/{id}/creditsresponse.- The
analyze_musicMCP tool runs the same plan-then-credit gate order viagateAnalyzeForTooland returns the limit message as a tool error; org-backed and enterprise accounts resolve toproand 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.