The listening profile the Spotify grant already pays for

[robert-dean]

Written: 2026-08-09, after checking every claim below against Spotify's live docs and the
February/March/May/July 2026 changelogs.
State of the tree: plugins/spotify requests user-top-read and user-library-read at
authorize time and calls neither. The capability contract has nowhere to put the answer.

---

What is already paid for

SPOTIFY_SCOPES in spotify.manifest.ts was carried
over verbatim from the previous station and asks for more than this tree uses. Two of those scopes
are live money left on the table:

Scope	Endpoint it unlocks	Called today
user-top-read	GET /me/top/tracks, GET /me/top/artists	no
user-library-read	GET /me/tracks (saved)	no

Every account that has ever connected the plugin holds a token that can read all three. There is no
re-consent, no manifest change and no new permissions.network entry: api.spotify.com is already
allowlisted.

/me/top/{type} takes time_range of short_term, medium_term or long_term, and limit 1–50.
Three time ranges times two types is six distinct views of the same account's taste, which is more
signal than the rotation pool has from any other source.

The gap

music.provider.ts gives
MusicProviderCatalog exactly four methods: searchTracks, getTrack, listPlaylists,
getPlaylistTracks. There is no shape for "top items" and nothing host-side asks for one.
ProviderTrack has no genre field either, which matters because the interesting half of this is
top artists and their genre tags, not top tracks.

Two ways in

Synthetic playlists, no SDK change. listPlaylists emits top:short_term, top:medium_term,
top:long_term and saved alongside the real ones; getPlaylistTracks routes those ids to
/me/top/tracks and /me/tracks. It rides the existing import path end to end and could land in an
afternoon. The ids are namespaced so they cannot collide with a real Spotify playlist id, and their
permissions would be ['read']. It is a small lie: these are not playlists, and a second provider
would have to invent its own namespace to tell the same one.

A profile sub-capability. An optional MusicProviderProfile carrying
getTopTracks(timeRange), getTopArtists(timeRange) and getSavedTracks, plus a 'profile'
capability string. The manifest's capability list is z.array(z.string().min(1)), deliberately open,
so adding one costs nothing structurally. This is the shape to build if top artists and their genres
are going to feed selection or patter rather than just filling a pool, because it is the only one of
the two with somewhere to put an artist.

They are not exclusive and the first does not block the second. Pick the first for rotation, the
second for taste modelling.

What February 2026 did and did not take

Checked because the same round is why getPlaylistTracks reads /items and why listPlaylists
reports permissions at all. It did not touch this:

• GET /me/top/{type} — no removal, no deprecation, user-top-read still current.
• GET /me/tracks — kept. Only the writes moved, PUT/DELETE /me/tracks to PUT/DELETE /me/library.
• external_ids — removed from Track and Album in February, reverted in the March 2026 changelog.
  So ProviderTrack.isrc, the cross-provider join key, is intact. Worth remembering that it was gone
  for a month: Spotify has shown it is willing to pull it.
• genres on the Artist object — not on any removal list.

What it took and did not give back: popularity on Track, and followers and popularity on
Artist. There is no popularity signal available from Spotify any more, so a taste model has to rank
on the ordering /me/top returns and nothing else.

Three findings from the same sweep, none of them about top listens

user-read-email and user-read-private are now dead weight. February stripped country,
email, explicit_content, followers and product from GET /me. Those two scopes exist to
unlock exactly those fields. Under the dev-mode cap of five authorized users, asking a person to
consent to their email address for a field the response no longer carries is friction that buys
nothing. Delete both from SPOTIFY_SCOPES.

Recently-played is the one that costs a re-consent. GET /me/player/recently-played survived
February and is the richest of the three signals, but user-read-recently-played is not in
SPOTIFY_SCOPES. Adding it re-authorizes every connected account, so batch it with the two removals
above rather than shipping it alone. listening-loop owns that batching and is
where the scope change is sequenced.

Everything else the sweep turned up is code the API has moved underneath, which is a different
kind of work from this file's: the search limit clamp, the SDK's removed batch overload, account_id,
and the Premium requirement on development mode. All of it is in
spotify-api-currency.

Sources

• February 2026 changelog
• February 2026 migration guide
• March 2026 changelog
• May 2026 changelog
• July 2026 changelog
• Get User's Top Items

---

Moved from docs/todo/spotify-listening-profile.md. The file as it last stood: https://github.com/robert-dean/deadair/blob/71e431d45ce7b35a189c7d226832ec4a6247e9dc/docs/todo/spotify-listening-profile.md