tonehaus/docs/04-spotify-integration.md

Spotify Integration

Credentials

• Prefer configuring via /admin/settings (stored in DB).
• Fallback to environment variables SPOTIFY_CLIENT_ID and SPOTIFY_CLIENT_SECRET.

API client

• src/Service/SpotifyClient.php
  • Client Credentials token fetch (cached)
  • searchAlbums(q, limit)
  • getAlbum(id) / getAlbums([ids])
  • getAlbumWithTracks(id) fetches metadata plus a hydrated tracklist
  • getAlbumTracks(id) provides the raw paginated track payload when needed

Advanced search

• The search page builds Spotify fielded queries:
  • album:"...", artist:"...", year:YYYY or year:YYYY-YYYY
  • Optional free-text added to the query