Uh oh!
There was an error while loading. Please reload this page.
feat(research): add GET /api/research/track/stats — per-track Songstats stats - #653
Conversation
…ts stats Implements recoupable/app#1789 (api step, against the docs#236 contract). Thin passthrough to Songstats enterprise/v1/tracks/stats: resolves a track by isrc / songstats_track_id / spotify_track_id / apple_music_track_id, forwards source + optional toggles 1:1, returns the same stats[].data envelope as /api/research/metrics (per-track streams_total). Reuses fetchSongstats + the research validate→handler→successResponse shape; auth + 5-credit deduction mirror the artist-level metrics endpoint. No database change. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Warning Review limit reached
More reviews will be available in 14 minutes and 20 seconds. Learn how PR review limits work. Your organization has run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After more reviews become available, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available. Please see our Fair Usage Limits Policy for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Run ID: ⛔ Files ignored due to path filters (3)
📒 Files selected for processing (4)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
5 issues found across 7 files
Confidence score: 3/5
- There is a concrete behavior gap in
lib/research/validateGetResearchTrackStatsRequest.ts: it allows requests with multiple track identifiers, even though the contract requires exactly one, which creates real user-facing/request-routing risk. - Most other findings are moderate-to-low risk and mainly about robustness/consistency (missing exception-path and error-body assertions in
lib/research/__tests__/getResearchTrackStatsHandler.test.ts, and error-message drift inlib/research/getResearchTrackStatsHandler.ts). - The dead catch noted in
lib/research/getResearchTrackStats.tsis low severity and cleanup-focused, so it does not materially increase merge risk by itself. - Pay close attention to
lib/research/validateGetResearchTrackStatsRequest.tsandlib/research/getResearchTrackStatsHandler.ts- enforce single-identifier validation and keep 500-response behavior/message consistent.
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="lib/research/getResearchTrackStatsHandler.ts">
<violation number="1" location="lib/research/getResearchTrackStatsHandler.ts:34">
P3: 500 error responses should use the repository-standard hardcoded message `"Internal server error"` instead of `"Internal error"` to keep error contracts consistent and avoid drift.
(Based on your team's feedback about standardized 500 error response wording and non-leaky error handling.) [FEEDBACK_USED].</violation>
</file>
<file name="lib/research/__tests__/getResearchTrackStatsHandler.test.ts">
<violation number="1" location="lib/research/__tests__/getResearchTrackStatsHandler.test.ts:64">
P2: No test covers the handler's catch/exception block. The handler logs and returns a 500 response on unexpected exceptions, but this error-recovery path is untested. Consider adding a test where `getResearchTrackStats` rejects/throws to verify the 500 fallback.</violation>
<violation number="2" location="lib/research/__tests__/getResearchTrackStatsHandler.test.ts:64">
P2: Test 3 asserts HTTP status but does not verify the error response body, making it weaker than analogous tests in the same test directory. Add a body assertion (e.g., `expect(body.error).toBe("Request failed with status 404")`) to verify the error envelope is returned correctly.</violation>
</file>
<file name="lib/research/getResearchTrackStats.ts">
<violation number="1" location="lib/research/getResearchTrackStats.ts:28">
P3: The `try/catch` around `recordCreditDeduction` is unreachable dead error-handling code because `recordCreditDeduction` already catches errors and returns `{ success: false }`.</violation>
</file>
Architecture diagram
sequenceDiagram
participant Client as External Client
participant Route as route.ts (GET)
participant Handler as getResearchTrackStatsHandler
participant Validator as validateGetResearchTrackStatsRequest
participant Auth as validateAuthContext
participant Credits as ensureResearchCredits
participant Fetcher as getResearchTrackStats
participant Songstats as fetchSongstats
participant Deduct as recordCreditDeduction
Client->>Route: GET /api/research/track/stats?isrc=...&source=spotify&with_playlists=true
Route->>Handler: Delegates request
Handler->>Validator: Validate request
Validator->>Auth: validateAuthContext(request)
alt 401 Unauthorized
Auth-->>Validator: NextResponse (401)
Validator-->>Handler: Return 401 response
Handler-->>Route: Unauthorized
else Auth OK
Auth-->>Validator: { accountId }
Validator->>Validator: Check required identifier (isrc/songstats_track_id/spotify_track_id/apple_music_track_id)
alt Missing identifier
Validator-->>Handler: Return 400 "identifier required"
else Identifier present
Validator->>Validator: Check required source param
alt Missing source
Validator-->>Handler: Return 400 "source is required"
else Source present
Validator->>Credits: ensureResearchCredits(accountId)
alt Insufficient credits
Credits-->>Validator: NextResponse (short-circuit)
Validator-->>Handler: Return credit-issue response
else Sufficient credits
Credits-->>Validator: null
Validator->>Validator: Build params (source + identifier + optional passthroughs)
Validator-->>Handler: { accountId, params }
Handler->>Fetcher: getResearchTrackStats({ accountId, params })
Fetcher->>Songstats: fetchSongstats("tracks/stats", params)
alt Songstats 200 OK
Songstats-->>Fetcher: { data: statsPayload, status: 200 }
Fetcher->>Deduct: recordCreditDeduction({ accountId, creditsToDeduct: 5, source: "api" })
Deduct-->>Fetcher: OK
Fetcher-->>Handler: { data: statsPayload }
Handler->>Handler: Wrap in successResponse
Handler-->>Route: 200 { status:"success", stats:[{source,data}], track_info }
else Songstats non-200
Songstats-->>Fetcher: { data: errorPayload, status: 404/500 }
Fetcher-->>Handler: { error: "Request failed with status N", status: N }
Handler->>Handler: Create errorResponse
Handler-->>Route: N error response
end
end
end
end
end
Route-->>Client: JSON response with CORS headers
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
Uh oh!
There was an error while loading. Please reload this page.
| status: 404, | ||
| }); | ||
| const res = await getResearchTrackStatsHandler(req()); | ||
| expect(res.status).toBe(404); |
There was a problem hiding this comment.
P2: Test 3 asserts HTTP status but does not verify the error response body, making it weaker than analogous tests in the same test directory. Add a body assertion (e.g., expect(body.error).toBe("Request failed with status 404")) to verify the error envelope is returned correctly.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At lib/research/__tests__/getResearchTrackStatsHandler.test.ts, line 64:
<comment>Test 3 asserts HTTP status but does not verify the error response body, making it weaker than analogous tests in the same test directory. Add a body assertion (e.g., `expect(body.error).toBe("Request failed with status 404")`) to verify the error envelope is returned correctly.</comment>
<file context>
@@ -0,0 +1,66 @@
+ status: 404,
+ });
+ const res = await getResearchTrackStatsHandler(req());
+ expect(res.status).toBe(404);
+ });
+});
</file context>
| @@ -0,0 +1,66 @@ | |||
| import { describe, it, expect, vi, beforeEach } from "vitest"; | |||
There was a problem hiding this comment.
P2: No test covers the handler's catch/exception block. The handler logs and returns a 500 response on unexpected exceptions, but this error-recovery path is untested. Consider adding a test where getResearchTrackStats rejects/throws to verify the 500 fallback.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At lib/research/__tests__/getResearchTrackStatsHandler.test.ts, line 64:
<comment>No test covers the handler's catch/exception block. The handler logs and returns a 500 response on unexpected exceptions, but this error-recovery path is untested. Consider adding a test where `getResearchTrackStats` rejects/throws to verify the 500 fallback.</comment>
<file context>
@@ -0,0 +1,66 @@
+ status: 404,
+ });
+ const res = await getResearchTrackStatsHandler(req());
+ expect(res.status).toBe(404);
+ });
+});
</file context>
| return successResponse(body); | ||
| } catch (error) { | ||
| console.error("[ERROR] getResearchTrackStatsHandler:", error); | ||
| return errorResponse("Internal error", 500); |
There was a problem hiding this comment.
P3: 500 error responses should use the repository-standard hardcoded message "Internal server error" instead of "Internal error" to keep error contracts consistent and avoid drift.
(Based on your team's feedback about standardized 500 error response wording and non-leaky error handling.) .
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At lib/research/getResearchTrackStatsHandler.ts, line 34:
<comment>500 error responses should use the repository-standard hardcoded message `"Internal server error"` instead of `"Internal error"` to keep error contracts consistent and avoid drift.
(Based on your team's feedback about standardized 500 error response wording and non-leaky error handling.) .</comment>
<file context>
@@ -0,0 +1,36 @@
+ return successResponse(body);
+ } catch (error) {
+ console.error("[ERROR] getResearchTrackStatsHandler:", error);
+ return errorResponse("Internal error", 500);
+ }
+}
</file context>
| try { | ||
| await recordCreditDeduction({ accountId: params.accountId, creditsToDeduct: 5, source: "api" }); | ||
| } catch (error) { |
There was a problem hiding this comment.
P3: The try/catch around recordCreditDeduction is unreachable dead error-handling code because recordCreditDeduction already catches errors and returns { success: false }.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At lib/research/getResearchTrackStats.ts, line 28:
<comment>The `try/catch` around `recordCreditDeduction` is unreachable dead error-handling code because `recordCreditDeduction` already catches errors and returns `{ success: false }`.</comment>
<file context>
@@ -0,0 +1,33 @@
+
+ try {
+ await recordCreditDeduction({ accountId: params.accountId, creditsToDeduct: 5, source: "api" });
+ } catch (error) {
+ console.error("[research] credit deduction failed:", error);
+ }
</file context>
Match the merged docs#236 contract ('provide exactly one track identifier')
and address cubic P1: the validator accepted multiple identifiers and forwarded
them all to Songstats. Now rejects !== 1 with a 400. TDD: added the >1 case.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>There was a problem hiding this comment.
0 issues found across 2 files (changes from recent commits).
Requires human review: Auto-approval blocked by 4 unresolved issues from previous reviews.
Re-trigger cubic
sweetmantech
commented
Jun 9, 2026
Preview verification — matches the deployed docs contractTested the preview for the latest commit ( Preview:
ResultLive behavior is 1:1 with the merged docs contract — params, response envelope (incl. Note: |
Uh oh!
There was an error while loading. Please reload this page.
release: test → main — GET /api/research/track/stats (#653)
Implements recoupable/app#1789 (api step) against the docs#236 contract. Pairs with recoupable/docs#236 (merge docs first).
Adds
GET /api/research/track/stats— per-track, per-source current stats (incl. absolutestreams_total) so agents can attribute streams to specific recordings. Today/api/research/metricsis artist-level only and/api/research/track(s)return metadata without stream counts.Design — thin passthrough, not new infra
isrc(orsongstats_track_id/spotify_track_id/apple_music_track_id);sourcerequired (comma list orall); optionalwith_playlists/charts/stations/videos/links,only_current,limit,offsetforwarded 1:1 to Songstatsenterprise/v1/tracks/stats.fetchSongstatsclient (enterpriseapikeyserver-side viaSONGSTATS_API_KEY, never echoed) and the researchvalidate → handler → successResponseshape. Response mirrors/api/research/metrics({ status, result, message, stats:[{source,data}], track_info })./api/research/*endpoints:validateAuthContext(401),ensureResearchCreditsgate, 5-credit deduction on a successful read. No database change.Files
app/api/research/track/stats/route.ts(GET + OPTIONS)lib/research/validateGetResearchTrackStatsRequest.ts·getResearchTrackStats.ts·getResearchTrackStatsHandler.tsTests (TDD, red→green)
validate(5),getResearchTrackStats(2), handler (3) — 10 new, all green; fulllib/researchsuite 151/151 (no regressions); tsc + lint clean.Test plan (preview, per #1789 Done-when)
?isrc=USQY51771120&source=spotify→ 200 withstats[0].data.streams_totalinteger (Mac Miller — K.I.D.S.).source=all→ onestats[]per source; resolving bysongstats_track_id/spotify_track_idworks equivalently.SONGSTATS_API_KEYnever echoed.streams_total≪ artist-levelstreams_total(~19.9B).🤖 Generated with Claude Code
Summary by cubic
Adds
GET /api/research/track/statsto return per-track, per-source Songstats current stats, includingstreams_total, so agents can attribute streams to specific recordings. This is a thin passthrough and reuses existing auth and credit rules.New Features
isrc,songstats_track_id,spotify_track_id, orapple_music_track_id;sourceis required. Optionalwith_*,only_current,limit, andoffsetare forwarded 1:1./api/research/metrics({ status, result, message, stats:[{ source, data }], track_info }); includes CORSOPTIONS.fetchSongstats; same auth and credits as other research endpoints with a 5-credit deduction on successful 200. No database changes.Bug Fixes
Written for commit 2279d12. Summary will update on new commits.