# @kody/spotify Official Spotify icon (green circle with three sound waves) from Spotify brand assets. ## Intent Provide reusable, account-agnostic Spotify helpers so Kody can read a connected profile, search the catalog, manage library and playlists, list devices, and control playback. This listing is meant to be forked. After you fork, connect **your** Spotify developer app and run `./get-profile` on **your** copy. Do not treat the live `@kody/spotify` integration as yours. There are no hard-coded personal playlists or account aliases. ## What it does - Read the connected user's profile, recently played tracks, top items, or liked songs - Search tracks, albums, artists, or playlists - List playlists and devices, then start or transfer playback - Preview playlist writes and playback changes with `dryRun: true` Do not use this package as a Spotify app that other people log into. Spotify Development Mode is for the app owner (and up to five registered users). ## Prerequisites / setup Spotify has **no built-in Kody platform app**. You create a personal app in the [Spotify developer dashboard](https://developer.spotify.com/dashboard) and connect it with authorization code + PKCE. PKCE is a public-client flow, so **no client secret** is stored. ### Costs and limits (since February 2026) - Development Mode requires the **app owner to hold Spotify Premium**. If Premium lapses, the app stops working until it is restored. - Developers can create up to 25 client IDs; all Development Mode apps share one API quota budget. - Refresh tokens expire **six months** after the original authorization (refreshing an access token does not extend this). Reconnect about twice a year. - Some Web API endpoints are unavailable in Development Mode. See the [February 2026 migration guide](https://developer.spotify.com/documentation/web-api/tutorials/february-2026-migration-guide). - Extended Quota Mode is only for organizations with at least 250k monthly active users. Personal use stays in Development Mode. ### Create the Spotify app 1. Open the [Spotify developer dashboard](https://developer.spotify.com/dashboard) and click **Create app**. 2. Set the redirect URI to exactly `https://kody.codes/connect/oauth`. Spotify requires HTTPS and rejects `localhost`. 3. Select **Web API**, accept the developer terms, and copy the **client ID**. With PKCE you do not need the client secret. 4. Only if someone other than the app owner will authorize: add them under **User Management** (max 5). ### Connect to Kody `flow=pkce` is Kody's default, so the link needs no flow parameter and no client secret. Open this URL while signed in to Kody, paste the client ID into the setup form, then authorize. Guide starter (read-mostly): ```text https://kody.codes/connect/oauth?provider=spotify&authorizeUrl=https%3A%2F%2Faccounts.spotify.com%2Fauthorize&tokenUrl=https%3A%2F%2Faccounts.spotify.com%2Fapi%2Ftoken&scopes=user-read-recently-played%20user-read-playback-state%20user-library-read&allowedHosts=api.spotify.com ``` Decoded: authorize `https://accounts.spotify.com/authorize`, token `https://accounts.spotify.com/api/token`, scopes `user-read-recently-played user-read-playback-state user-library-read`, host `api.spotify.com`. Recommended for this package (adds profile/top/playlist reads plus playback and library/playlist writes): ```text https://kody.codes/connect/oauth?provider=spotify&authorizeUrl=https%3A%2F%2Faccounts.spotify.com%2Fauthorize&tokenUrl=https%3A%2F%2Faccounts.spotify.com%2Fapi%2Ftoken&scopes=user-read-recently-played%20user-read-playback-state%20user-read-currently-playing%20user-library-read%20playlist-read-private%20user-top-read%20user-modify-playback-state%20playlist-read-collaborative%20playlist-modify-public%20playlist-modify-private%20user-library-modify&allowedHosts=api.spotify.com ``` Changing scopes means reconnecting. Reconnect later at `https://kody.codes/connect/oauth?provider=spotify` (or `?provider=spotify-work`). Access tokens last one hour. Use `createAuthenticatedFetch` — do not cache raw tokens. Refresh tokens hard-expire six months after the original authorization. Agents: see [`AGENTS.md`](./AGENTS.md) for import paths, multi-account / device targeting, dryRun snippets, and edge cases. ## Done when - Spotify developer app redirect URI is exactly `https://kody.codes/connect/oauth` - `spotify` (or `spotify-*`) OAuth is connected; host `api.spotify.com` approved - `./get-profile` returns `id` and `product` (`premium` expected for Development Mode) - Mutations preview with `dryRun: true` before live playlist or playback changes ## Branding The community icon is Spotify's official green circle with three sound waves from Spotify brand assets. Paths are unmodified. Spotify® is a trademark of Spotify AB. This package is not affiliated with or endorsed by Spotify. ## Troubleshooting - `INVALID_CLIENT: Invalid redirect URI`: the dashboard redirect URI must be exactly `https://kody.codes/connect/oauth`. - `403 User not registered in the Developer Dashboard`: add the user under **User Management**, or have them create their own app. - `403` on a specific endpoint: that endpoint may be unavailable in Development Mode. - App failing across the board: check that the app owner's Premium subscription is active. - `401` after about an hour: access tokens expire hourly. Use `createAuthenticatedFetch`. - `invalid_grant` about six months after connecting: reconnect at `/connect/oauth?provider=spotify`.