Skip to content
← Public packages

@kentcdodds/spotify

Spotify playback, playlist, search, library, and device helpers.

README.md

52 lines · 2.2 KB · Markdown

@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.

What it does

  • Control Spotify Connect playback (play, pause, skip, seek, volume, shuffle, repeat, queue, transfer)
  • Read playback state, devices, queue, recently played, top items, and tracks
  • Create or edit playlists, follow playlists, and save tracks
  • Search the catalog and fetch recommendations
  • Target whole-home Sonos via the family account for household playlists
  • Hosted package app at /packages/spotify (owner UI surface)

Prerequisites / setup

  1. Connect OAuth integrations spotify (personal, default) and spotify-family (family/kids) as needed.
  2. Reconnect at /connect/oauth?provider=spotify or /connect/oauth?provider=spotify-family when tokens expire.
  3. Approve host api.spotify.com on those integrations.
  4. The family account has no default fallback device or collection URI — playback needs an active device or an explicit selector (deviceName preferred).
  5. Agents: see AGENTS.md for import paths and smoke checks.
Device targeting

Prefer human selectors so opaque Spotify Connect device ids never cross the agent tool boundary (some hosts mis-classify those ids as credentials):

  1. Omit device selectors → active Connect device
  2. Pass deviceName (case-insensitive substring) and optional deviceType
  3. Advanced escape hatch: deviceId / device_id (agents should avoid copying ids from get-devices)

Done when

  • OAuth spotify (and spotify-family if used) connected; api.spotify.com approved
  • Read-only checks (playback-state, get-devices, or list-playlists) succeed for the intended account
  • Playback helpers target devices by name when not using the active device