# @kody/spotify — agent notes Human setup and intent live in [`README.md`](./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: ```js 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: ```js import getProfile from 'kody:@kody/spotify/get-profile' export default async function main() { return await getProfile({ integration: 'spotify-work' }) } ``` Low-level execute exploration only: ```js 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. ```js 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.