docs(artists): profile v2 — per-catalog songs with plays, ISRC, artwork and $ estimates

Merged
SW
2mo ago
+78-2

Row 1 of recoupable/chat#1968. Approved design: Artist Profile V2 canvas.

Extends GET /api/artists/{id}/profile additively:

  • ArtistPublicProfileCatalog gains songs[] — new ArtistPublicProfileSong schema: isrc, name, album (nullable), artwork_url (nullable, Apple Music), plays (latest capture, staleness documented), est_value_usd (mid of the published Recoup valuation model). Sorted by plays desc, capped at the top 50; song_count documented as possibly exceeding songs.length.
  • The response gains nullable valuation {low, mid, high} (new ArtistPublicProfileValuation schema) — the band across all credited songs.

No v1 field changes; both new response fields are additive. releases.json parses after anchored additive edits.

Merge order

First of the chat#1968 fleet: docs → database → api → chat.

Summary by cubic

Extends GET /api/artists/{id}/profile to power Artist Profile V2: each catalog now returns its top songs and the response includes a nullable catalog valuation band. Previously catalogs exposed counts only and no valuation; now each catalog includes up to 50 songs sorted by plays and the response includes low/mid/high valuation.

  • Review notes:
    • OpenAPI: adds songs[] to ArtistPublicProfileCatalog (ArtistPublicProfileSong: isrc, name, album nullable, artwork_url nullable, plays, est_value_usd) and adds valuation (ArtistPublicProfileValuation: low, mid, high; nullable) to the root profile.
    • Behavior: songs sorted by plays desc and capped at 50; song_count may exceed songs.length; valuation null when no measured songs exist.
    • Compatibility/migration: additive only; no v1 field changes. Clients must not assume songs.length equals song_count.

Summary by CodeRabbit

  • Documentation
    • Updated the public artist profile API specification to include valuation details with low, mid, and high estimates.
    • Added song-level information to artist catalogs, including identifiers, titles, albums, artwork, play counts, and estimated values.
    • Documented the new song and valuation response structures, including nullable valuation data.