Skip to content
← Public packages

@kody/spotify

Read a Spotify profile, search the catalog, and manage library, playlists, devices, and playback.

FollowFork

Files

AGENTS.md

141 lines · 5.0 KB · Markdown

@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

ItemValue
Integration namespotify (default); extras spotify-* e.g. spotify-work
FlowOAuth authorization code + PKCE (no client secret)
Approved hostapi.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

ExportImport
package overviewkody:@kody/spotify
accountskody:@kody/spotify/accounts
get-profilekody:@kody/spotify/get-profile
searchkody:@kody/spotify/search
get-trackkody:@kody/spotify/get-track
get-saved-trackskody:@kody/spotify/get-saved-tracks
save-trackskody:@kody/spotify/save-tracks
get-recently-playedkody:@kody/spotify/get-recently-played
get-top-itemskody:@kody/spotify/get-top-items
get-recommendationskody:@kody/spotify/get-recommendations
list-playlistskody:@kody/spotify/list-playlists
get-playlistkody:@kody/spotify/get-playlist
get-all-playlist-trackskody:@kody/spotify/get-all-playlist-tracks
create-playlistkody:@kody/spotify/create-playlist
add-tracks-to-playlistkody:@kody/spotify/add-tracks-to-playlist
remove-tracks-from-playlistkody:@kody/spotify/remove-tracks-from-playlist
follow-playlistkody:@kody/spotify/follow-playlist
get-deviceskody:@kody/spotify/get-devices
playback-statekody:@kody/spotify/playback-state
get-queuekody:@kody/spotify/get-queue
play-contextkody:@kody/spotify/play-context
play-pausekody:@kody/spotify/play-pause
skipkody:@kody/spotify/skip
seekkody:@kody/spotify/seek
set-repeat / set-shuffle / set-volumekody:@kody/spotify/set-repeat etc.
add-to-queuekody:@kody/spotify/add-to-queue
transfer-playbackkody:@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:

  1. Happy path — omit device selectors; Spotify uses the active Connect device.
  2. Named device — pass deviceName (case-insensitive substring) and optional deviceType (Speaker, Computer, …).
  3. Advanced — deviceId still works, but avoid copying ids from get-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/spotify as 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.