tonehaus/docs/spotify-integration.md

Spotify Integration

Credentials

• Preferred: Manage in /admin/settings (persisted in DB; no restart required)
• Env fallback: SPOTIFY_CLIENT_ID, SPOTIFY_CLIENT_SECRET

API Client

• src/Service/SpotifyClient.php
  • Client Credentials token fetch with caching
  • searchAlbums(q, limit) — album search endpoint
  • getAlbum(id) / getAlbums([ids]) — metadata fetch
  • getAlbumWithTracks(id) — metadata + hydrated tracklist
  • getAlbumTracks(id) — raw paginated tracks (when needed)

Caching & Rate Limits

• Access tokens are cached until expiry to avoid unnecessary auth calls.
• Downstream requests should be mindful of Spotify rate limits; user actions are debounced in the UI and server calls are focused on album/track data needed by the current page.

Advanced search syntax

• Fielded queries are composed as:
  • album:"...", artist:"...", year:YYYY or year:YYYY-YYYY
  • Optional free text is appended to the query
• Examples:
  • album:"in rainbows" artist:"radiohead"
  • year:1999-2004 post rock

Admin settings

• Update credentials in /admin/settings
• Settings are stored in the database; APP_ENV reload or container restart is not required