Add Spotify Web API (OAuth PKCE) support: auth, token caching, resilient client, playlist/liked-songs downloads

[TheRealAlexV]

Summary

This PR introduces a complete Spotify Web API integration (Authorization Code + PKCE) so HARMONI can load tracks directly from a user’s Spotify account (Playlists + Liked Songs) and reuse the existing per-playlist selection + download pipeline.

Key deliverables:

• New spotify_api/ package (PKCE auth, token cache, API client with retries/paging, data normalization)
• Downloads menu integration with a dedicated Spotify submenu and guided OAuth flow
• New config keys + README docs for Spotify setup
• Basic tests for PKCE helpers, token manager, and data-loader paging limits

Motivation

File-based workflows (Exportify CSV / Spotify export JSON) remain supported, but direct Web API access is the most reliable and user-friendly source of up-to-date playlist + liked-song data.

What’s Included

1) OAuth PKCE implementation (no client secret)

• Implements the Authorization Code + PKCE flow in SpotifyPKCEAuth
• PKCE verifier/challenge generation via SpotifyPKCEAuth.generate_pkce_pair() and code_challenge_from_verifier()
• Redirect parsing helper: extract_code_from_redirect_url()
• Token exchange + refresh via SpotifyPKCEAuth.exchange_code_for_token() and SpotifyPKCEAuth.refresh_access_token()

Dependency note:

• Token exchange/refresh uses httpx (import guarded with a clear runtime error when missing) in spotify_api/auth.py
• httpx is included in requirements.txt

2) Token caching + expiry

• Token persistence and expiry handling implemented in TokenManager
• Default cache file: DEFAULT_TOKEN_CACHE_PATH (data/spotify_tokens.json)
• Expiry check with skew buffer: TokenManager.is_expired()

Config controls:

• spotify_cache_tokens: enable/disable disk cache (checked in TokenManager.should_cache())
• spotify_auto_refresh: enable/disable refresh-token flow (enforced in SpotifyClient.get_token())

3) Resilient Spotify Web API client (stdlib networking)

• API wrapper in SpotifyClient
• Core request method with retry logic: SpotifyClient.request_json()
  • 429 rate-limit handling honoring Retry-After
  • exponential backoff retries on 5xx
  • one refresh attempt on 401 if possible
  • actionable diagnostics for 401/403 including scope mismatch hints
• Fully paged helpers:
  • SpotifyClient.get_user_playlists()
  • SpotifyClient.get_playlist_tracks()
  • SpotifyClient.get_liked_songs()

Tunable retry keys (optional):

• spotify_max_retries, spotify_backoff_base, spotify_retry_jitter (read in SpotifyClient.request_json() and SpotifyClient._sleep_with_jitter())

4) High-level data loader + normalization compatible with existing workflows

• High-level extraction helpers: SpotifyDataLoader
  • playlists: SpotifyDataLoader.list_all_playlists()
  • playlist tracks: SpotifyDataLoader.load_playlist_tracks()
  • liked songs: SpotifyDataLoader.load_liked_songs()
• Track normalization produces dicts compatible with HARMONI’s existing download pipeline (must include artist + track): SpotifyDataLoader._normalize_track()
  • filters local tracks
  • preserves optional fields like album, release_date, uri, isrc, etc.

5) CLI menu integration (auth + download UI)

• Adds Spotify submenu entry in Downloads menu: downloads_menu()
• Spotify submenu loop: _spotify_api_menu()
  • Authenticate
  • Download from my playlists
  • Download from liked songs
  • Setup help
  • Log out (clear token cache)

OAuth UX improvements:

• Interactive auth flow with loopback callback server (auto-capture) + paste fallback: _spotify_authenticate()
• Docker-aware callback binding (bind 0.0.0.0 inside container when redirect is 127.0.0.1): _spotify_authenticate()

Download workflow integration:

• Playlist selection via checkbox UI + guidance: _spotify_download_from_playlists()
• Liked songs loading + selection: _spotify_download_liked_songs()
• Reuses existing per-playlist song selection UI: select_songs_for_playlist()
• Final download path reuses playlist downloader: download_playlist()

6) Configuration + docs

• Adds Spotify Web API defaults + validation schema keys in DEFAULT_CONFIG and CONFIG_SCHEMA
  • spotify_client_id, spotify_redirect_uri, spotify_scopes, spotify_cache_tokens, spotify_auto_refresh
• README includes end-to-end setup and usage for Spotify Web API workflow: readme.md

Client ID behavior:

• If spotify_client_id is not set, falls back to Exportify’s public client id via get_effective_spotify_client_id() (with warnings + guidance from check_spotify_credentials())

Testing

• PKCE + token manager + normalization tests: test_spotify_api_basic.py
• Data loader max-track/max-playlist limit tests with a fake client: test_spotify_data_loader_limits.py

Security / Privacy notes

• Uses PKCE (no client secret stored).
• Tokens are cached only when spotify_cache_tokens is enabled (see TokenManager.should_cache()).
• Client avoids leaking secrets in diagnostics (see logging logic in SpotifyClient.request_json()).

User-facing workflow

1. Configure redirect + client id (recommended) per docs in readme.md
2. Authenticate via the Downloads → Spotify menu (auth auto-captures loopback redirect when possible): _spotify_authenticate()
3. Choose playlists / liked songs to load and download, then select tracks per playlist via select_songs_for_playlist()

[Ssenseii]

I'm encountering a problem when I try to authenticate.
INVALID_CLIENT: Invalid redirect URI
either that or I configured it wrong cause I kept the Spotify client ID empty, as I didn't create a Spotify app in their developer platform.

You mind explaining how to setup the Spotify API integration so I can add it to the docs? @TheRealAlexV
Also, I'm not using the dockerized version if that makes any difference.