@kody/spotify
Read a Spotify profile, search the catalog, and manage library, playlists, devices, and playback.
Files
@kody/spotify — agent notes
Human setup and intent live in README.md. This file is for
agents: imports, smoke/dryRun execute snippets, and edge cases. Integration
ids by name only — never paste token values. Do not disable live webhooks
or jobs.
Auth / integration
| Item | Value |
|---|---|
| Integration name | spotify (default); extras spotify-* e.g. spotify-work |
| Flow | OAuth authorization code + PKCE (no client secret) |
| Approved host | api.spotify.com |
| Reconnect | /connect/oauth?provider=spotify (or matching spotify-*) |
Every export accepts optional integration. Do not hard-code personal aliases
such as personal, family, or kent — those values throw.
Import paths
| Export | Import |
|---|---|
| package overview | kody:@kody/spotify |
| accounts | kody:@kody/spotify/accounts |
| get-profile | kody:@kody/spotify/get-profile |
| search | kody:@kody/spotify/search |
| get-track | kody:@kody/spotify/get-track |
| get-saved-tracks | kody:@kody/spotify/get-saved-tracks |
| save-tracks | kody:@kody/spotify/save-tracks |
| get-recently-played | kody:@kody/spotify/get-recently-played |
| get-top-items | kody:@kody/spotify/get-top-items |
| get-recommendations | kody:@kody/spotify/get-recommendations |
| list-playlists | kody:@kody/spotify/list-playlists |
| get-playlist | kody:@kody/spotify/get-playlist |
| get-all-playlist-tracks | kody:@kody/spotify/get-all-playlist-tracks |
| create-playlist | kody:@kody/spotify/create-playlist |
| add-tracks-to-playlist | kody:@kody/spotify/add-tracks-to-playlist |
| remove-tracks-from-playlist | kody:@kody/spotify/remove-tracks-from-playlist |
| follow-playlist | kody:@kody/spotify/follow-playlist |
| get-devices | kody:@kody/spotify/get-devices |
| playback-state | kody:@kody/spotify/playback-state |
| get-queue | kody:@kody/spotify/get-queue |
| play-context | kody:@kody/spotify/play-context |
| play-pause | kody:@kody/spotify/play-pause |
| skip | kody:@kody/spotify/skip |
| seek | kody:@kody/spotify/seek |
| set-repeat / set-shuffle / set-volume | kody:@kody/spotify/set-repeat etc. |
| add-to-queue | kody:@kody/spotify/add-to-queue |
| transfer-playback | kody:@kody/spotify/transfer-playback |
Prefer static kody:@kody/spotify/... imports from execute. Do not lead with
packages.invoke.
Smoke test (read-only)
After connect or reconnect:
import getProfile from 'kody:@kody/spotify/get-profile'
export default async function main() {
return await getProfile()
// => { id, product, ... } — product should be 'premium' for Development Mode
}Second account:
import getProfile from 'kody:@kody/spotify/get-profile'
export default async function main() {
return await getProfile({ integration: 'spotify-work' })
}Low-level execute exploration only:
import { createAuthenticatedFetch } from 'kody:runtime'
export default async function main() {
const spotifyFetch = await createAuthenticatedFetch('spotify')
const response = await spotifyFetch('https://api.spotify.com/v1/me')
if (!response.ok) {
throw new Error(
'Spotify smoke test failed: ' +
response.status +
' ' +
(await response.text()),
)
}
const me = (await response.json()) as {
display_name?: string
id: string
product?: string
}
return { id: me.id, displayName: me.display_name, product: me.product }
}Device targeting
Prefer human selectors so opaque Spotify Connect device ids never cross the agent tool boundary:
- Happy path — omit device selectors; Spotify uses the active Connect device.
- Named device — pass
deviceName(case-insensitive substring) and optionaldeviceType(Speaker,Computer, …). - Advanced —
deviceIdstill works, but avoid copying ids fromget-devices.
dryRun (mutations)
Playlist writes (create-playlist, add-tracks-to-playlist,
remove-tracks-from-playlist, follow-playlist, save-tracks) and playback
helpers (play-context, play-pause, skip, seek, set-repeat,
set-shuffle, set-volume, add-to-queue, transfer-playback) accept
dryRun: true. A dry run validates input and returns a preview; Spotify is
not written.
import createPlaylist from 'kody:@kody/spotify/create-playlist'
export default async function main() {
return await createPlaylist({ name: 'Focus', public: false, dryRun: true })
}Playback control acts on real devices. Use dryRun: true first when the user
has not confirmed a live change.
Edge cases / fork notes
- Access tokens last ~1 hour; use
createAuthenticatedFetch— never cache raw tokens. - Refresh tokens hard-expire six months after original authorization; reconnect.
- Development Mode needs app-owner Premium; some endpoints may 403.
- Fork first: connect your Spotify app; do not treat live
@kody/spotifyas yours. - Never paste Spotify client IDs from chat into logs as if they were secrets that must be redacted for agents — still never paste OAuth tokens.