@kentcdodds/spotify

@kentcdodds/spotify

Intent

Account-aware Spotify playback, playlist, search, library, and device helpers for Kody workflows. Supports Kent's personal account (default) and the family "Dodds Kids" account via an optional account param on every export.

Low-level REST calls come from an OpenAPI-scaffolded client (sonallux Spotify Web API spec) authenticated with createAuthenticatedFetch against the spotify / spotify-family integrations. Public exports still return parsed/normalized JSON.

When To Use

• Control Spotify Connect playback (play, pause, skip, volume, queue) from an agent or automation.
• Read playback state, devices, queue, or listening history without opening the Spotify app.
• Create or edit playlists and save tracks on personal or family accounts.
• Search the catalog or fetch recommendations for music-discovery workflows.
• Target whole-home Sonos playback via the family account for household playlists.

Required setup

• OAuth integrations: spotify (personal, default) and spotify-family (family/kids account).
• Reconnect at /connect/oauth?provider=spotify or /connect/oauth?provider=spotify-family when tokens expire.
• Host approval for api.spotify.com on those integrations.
• The family account has no default fallback device or collection URI; playback exports need an active device or explicit deviceId.

Exports

• ./accounts — list and resolve personal vs family account metadata.
• ./add-to-queue — queue a track or episode URI.
• ./add-tracks-to-playlist — add track URIs to a playlist.
• ./create-playlist — create a new playlist.
• ./follow-playlist — follow a playlist (PUT /playlists/{id}/followers).
• ./get-all-playlist-tracks — paginate all tracks in a playlist.
• ./get-devices — list Spotify Connect devices.
• ./get-playlist — read playlist metadata and track previews.
• ./get-queue — read the current playback queue.
• ./get-recently-played — recently played tracks.
• ./get-recommendations — track recommendations from seeds.
• ./get-top-items — top tracks or artists for a time range.
• ./get-track — track details by ID (uses several-tracks when multiple ids).
• ./list-playlists — list the user's playlists.
• ./play-context — start album/playlist/artist context playback.
• ./play-pause — toggle play or pause.
• ./playback-state — current playback snapshot.
• ./remove-tracks-from-playlist — remove tracks from a playlist.
• ./save-tracks — save tracks to liked songs / library.
• ./search — search tracks, albums, artists, or playlists.
• ./seek — seek within the current track.
• ./set-repeat — set repeat mode (off, track, context).
• ./set-shuffle — enable or disable shuffle.
• ./set-volume — set device volume (0–100).
• ./skip — skip to the next or previous track (direction, default next).
• ./transfer-playback — move playback to another device.

Example

import createPlaylist from 'kody:@kentcdodds/spotify/create-playlist'
import playbackState from 'kody:@kentcdodds/spotify/playback-state'

await createPlaylist({ account: 'family', name: 'Road Trip' })
const state = await playbackState({ account: 'personal' })