# 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