feat(spotify): require user API app for search (client-credentials)

Spotify rejects Web API calls made with librespot-session tokens (429 on
every endpoint; Mercury keymaster and searchview are retired), so search
now uses SPOTIFY_CLIENT_ID/SPOTIFY_CLIENT_SECRET from the user's own free
API app via the client-credentials flow, cached in-process. The search
overlay shows setup instructions when the variables are missing.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: program247365

CLAUDE.md

@@ -157,12 +157,17 @@ uses librespot:
   - `ensure_track_available()` uses librespot's `AudioItem` availability to fail
     a single unplayable track at resolve time, so `resolve_url_with_startup`
     surfaces the "track unavailable" modal instead of playing silence
-- `src/spotify/search.rs` — catalog search via the public Web API (`/v1/search`),
-  authorized with a bearer token minted from the librespot session
-  (`session.token_provider().get_token(...)` — comma-separated scopes string).
-  Returns `SearchResults { tracks, albums, playlists }` of `SearchItem`s whose
-  `uri` is a valid `resolve()` target. Playlist `items` can contain literal
-  `null`s (post-2024 API changes) — the parser filters them.
+- `src/spotify/search.rs` — catalog search via the public Web API
+  (`/v1/search`). Spotify rejects Web API calls made with librespot-session
+  tokens (429 on every endpoint; Mercury keymaster/searchview are retired), so
+  search requires the user's own API app: `SPOTIFY_CLIENT_ID` /
+  `SPOTIFY_CLIENT_SECRET` env vars feed a client-credentials token, cached
+  in-process until shortly before expiry. Missing vars produce a multi-line
+  setup-instructions error shown in the search overlay. Independent of the
+  Premium login (search works without it; playback doesn't). Returns
+  `SearchResults { tracks, albums, playlists }` of `SearchItem`s whose `uri`
+  is a valid `resolve()` target. Playlist `items` can contain literal `null`s
+  (post-2024 API changes) — the parser filters them.
 - `src/spotify/sink.rs` — the bridge. librespot's `Player` pushes decoded PCM
   into a custom `Sink`; a bounded channel carries it to a rodio `Source`. The
   sink blocks under backpressure (throttling the decoder to real time); the

README.md

@@ -46,13 +46,17 @@ looper play --url "https://open.spotify.com/album/4aawyAB9vmqN3uQ7FjRGTy"
 Press `f` for fullscreen, `space` to pause, `p` for history, `q` to quit. More
 examples and keybindings in [Usage & Keys](docs/usage.md).
 
+Want in-app Spotify search (`/` to find and loop a song, album, or playlist)?
+That takes a free Spotify API app of your own — one-time setup in
+[Spotify → Search](docs/spotify.md#search-optional).
+
 ## Documentation
 
 | Guide | What's inside |
 |-------|---------------|
 | [Installation](docs/installation.md) | Homebrew, build from source, runtime dependencies |
 | [Usage & Keys](docs/usage.md) | Every source, playlists, controls, the history panel |
-| [Spotify](docs/spotify.md) | Login, playback, and how librespot streaming works |
+| [Spotify](docs/spotify.md) | Login, playback, in-app search setup, and how librespot streaming works |
 | [Now Playing & Media Keys](docs/now-playing.md) | The OS media-session integration |
 | [How Playback Works](docs/playback.md) | The `yt-dlp` model, caching, and quirks |
 | [Cross-Device Sync](docs/sync.md) | Share history across machines via a cloud folder |

docs/spotify.md

@@ -25,6 +25,35 @@ looper play --url "https://open.spotify.com/album/4aawyAB9vmqN3uQ7FjRGTy"
 
 `spotify:` URIs work too. Spotify does **not** require `yt-dlp` or `ffmpeg`.
 
+## Search (optional)
+
+Press `/` during playback or in the history browser to search Spotify's catalog
+and play a song, album, or playlist without leaving the terminal — see
+[Usage & Keys](usage.md) for the keybindings.
+
+Search talks to Spotify's Web API, which requires **your own (free) API app**.
+Spotify blocks Web API calls made with librespot's shared client id, so the
+playback login above is not enough. One-time setup:
+
+1. Open the [Spotify developer dashboard](https://developer.spotify.com/dashboard)
+   and create an app (any name; the redirect URI is not used by looper's
+   search — enter anything valid, e.g. `http://127.0.0.1:8898/login`).
+2. Copy the app's **Client ID** and **Client Secret**.
+3. Export them in your shell profile:
+
+```shell
+export SPOTIFY_CLIENT_ID="your-client-id"
+export SPOTIFY_CLIENT_SECRET="your-client-secret"
+```
+
+looper exchanges them for a catalog-only token (client-credentials flow — no
+browser login, no account data access) and caches it in memory for its ~1 hour
+lifetime. If the variables aren't set, pressing `/` still works: the overlay
+explains this setup instead of searching.
+
+Searching needs only these variables; *playing* a result still needs the
+Premium login above.
+
 ## How Spotify playback works
 
 Spotify is fundamentally different from the `yt-dlp`-backed services. It exposes

docs/superpowers/specs/2026-07-03-spotify-search-design.md

@@ -1,7 +1,17 @@
 # Spotify Search Overlay
 
 **Date:** 2026-07-03
-**Status:** Approved
+**Status:** Approved (amended 2026-07-05)
+
+> **Amendment (2026-07-05):** the "mint a Web API token from the librespot
+> session" plan failed in live testing — Spotify's Mercury keymaster endpoint
+> is retired (403), and login5 tokens get 429 on every `api.spotify.com`
+> endpoint (with or without a `client-token` attestation header); Mercury
+> `searchview` is 404. Search instead uses the client-credentials flow with a
+> user-provided free Spotify API app (`SPOTIFY_CLIENT_ID` /
+> `SPOTIFY_CLIENT_SECRET` env vars), with the token cached in-process for its
+> ~1h lifetime. Missing credentials render setup instructions in the overlay.
+> Search is now independent of the Premium login (needed only for playback).
 
 ## Summary
 

docs/usage.md

@@ -107,8 +107,11 @@ Sort fields: time played, last played, platform, title, times played.
 ## Spotify search
 
 `/` opens a Spotify catalog search from the playback screen or the history
-browser (requires the one-time `looper spotify login`). Type a query and press
-`Enter`; results are grouped into SONGS, ALBUMS, and PLAYLISTS.
+browser. It needs a one-time setup — your own free Spotify API app in
+`SPOTIFY_CLIENT_ID` / `SPOTIFY_CLIENT_SECRET` — see
+[Spotify → Search](spotify.md#search-optional); without it the overlay shows
+the setup steps. Type a query and press `Enter`; results are grouped into
+SONGS, ALBUMS, and PLAYLISTS.
 
 | Key | Action |
 |-----|--------|

src/spotify/search.rs

@@ -1,13 +1,18 @@
 //! Spotify catalog search via the public Web API.
 //!
 //! Playback and metadata go through librespot's own protocols, but librespot
-//! exposes no search. The Web API's `/v1/search` does, and the librespot
-//! session can mint a bearer token for it — so search needs no second login
-//! and no developer app.
+//! exposes no search, and Spotify rejects Web API calls made with tokens from
+//! librespot's shared client id (every endpoint answers 429; the Mercury
+//! keymaster and searchview routes are retired outright). Search therefore
+//! needs the user's own — free — Spotify API app: `SPOTIFY_CLIENT_ID` and
+//! `SPOTIFY_CLIENT_SECRET` feed a client-credentials token (no browser flow,
+//! no user context), cached in-process for its ~1h lifetime.
+
+use std::sync::Mutex;
+use std::time::{Duration, Instant};
 
 use color_eyre::eyre::{eyre, Result, WrapErr};
 use serde::Deserialize;
-use stream_download::http::reqwest::Client as HttpClient;
 
 /// Display limits per section (spec: 8 tracks, 5 albums, 5 playlists).
 const TRACK_LIMIT: usize = 8;
@@ -32,34 +37,98 @@ pub struct SearchItem {
     pub uri: String,
 }
 
-/// Search Spotify's catalog. Blocking: runs one Web API request on the shared
-/// Spotify runtime (~300ms). Requires a prior `looper spotify login`.
+/// Shown in the search overlay when the API app env vars are missing.
+const SETUP_HELP: &str = "Spotify search needs your own (free) Spotify API app:\n  1. create an app at developer.spotify.com/dashboard\n  2. export SPOTIFY_CLIENT_ID=... and SPOTIFY_CLIENT_SECRET=...\n  3. restart looper\nPlayback is unaffected — see the README's \"Spotify search\" section.";
+
+/// Search Spotify's catalog. Blocking (~300ms), called from the TUI thread
+/// after a "searching…" frame has been drawn. Requires `SPOTIFY_CLIENT_ID` /
+/// `SPOTIFY_CLIENT_SECRET`; does NOT require the librespot Premium login.
 pub fn search(query: &str) -> Result<SearchResults> {
-    let ctx = super::ctx()?;
-    let session = super::session()?;
-    let body = ctx.runtime.block_on(async move {
-        let token = session
-            .token_provider()
-            .get_token("user-read-private,playlist-read-private")
-            .await
-            .map_err(|e| eyre!("failed to get Spotify API token: {e}"))?;
-        let response = HttpClient::new()
-            .get("https://api.spotify.com/v1/search")
-            .bearer_auth(&token.access_token)
-            .query(&[("q", query), ("type", "track,album,playlist"), ("limit", "8")])
-            .send()
-            .await
-            .map_err(|e| eyre!("Spotify search request failed: {e}"))?
-            .error_for_status()
-            .map_err(|e| eyre!("Spotify search failed: {e}"))?;
-        response
-            .text()
-            .await
-            .map_err(|e| eyre!("failed to read Spotify search response: {e}"))
-    })?;
+    let token = search_token()?;
+    let response = reqwest::blocking::Client::new()
+        .get("https://api.spotify.com/v1/search")
+        .bearer_auth(&token)
+        .query(&[("q", query), ("type", "track,album,playlist"), ("limit", "8")])
+        .send()
+        .map_err(|e| eyre!("Spotify search request failed: {e}"))?
+        .error_for_status()
+        .map_err(|e| eyre!("Spotify search failed: {e}"))?;
+    let body = response
+        .text()
+        .map_err(|e| eyre!("failed to read Spotify search response: {e}"))?;
     parse_search_response(&body)
 }
 
+struct CachedToken {
+    access_token: String,
+    expires_at: Instant,
+}
+
+static TOKEN: Mutex<Option<CachedToken>> = Mutex::new(None);
+
+/// A valid client-credentials bearer token, fetched with the user's API app
+/// and reused until shortly before expiry (~1h).
+fn search_token() -> Result<String> {
+    let mut slot = TOKEN.lock().unwrap();
+    if let Some(cached) = slot.as_ref() {
+        if Instant::now() < cached.expires_at {
+            return Ok(cached.access_token.clone());
+        }
+    }
+
+    let (client_id, client_secret) = search_app_credentials(
+        std::env::var("SPOTIFY_CLIENT_ID").ok(),
+        std::env::var("SPOTIFY_CLIENT_SECRET").ok(),
+    )?;
+
+    #[derive(Deserialize)]
+    struct TokenResponse {
+        access_token: String,
+        expires_in: u64,
+    }
+
+    let body = reqwest::blocking::Client::new()
+        .post("https://accounts.spotify.com/api/token")
+        .basic_auth(&client_id, Some(&client_secret))
+        .form(&[("grant_type", "client_credentials")])
+        .send()
+        .map_err(|e| eyre!("Spotify token request failed: {e}"))?
+        .error_for_status()
+        .map_err(|e| {
+            eyre!("Spotify rejected your API app credentials ({e}) — check SPOTIFY_CLIENT_ID / SPOTIFY_CLIENT_SECRET")
+        })?
+        .text()
+        .map_err(|e| eyre!("failed to read Spotify token response: {e}"))?;
+    let response: TokenResponse =
+        serde_json::from_str(&body).wrap_err("unexpected Spotify token response")?;
+
+    // Refresh a minute early so an in-flight search never carries a token
+    // that expires mid-request.
+    let expires_at =
+        Instant::now() + Duration::from_secs(response.expires_in.saturating_sub(60).max(60));
+    let token = response.access_token.clone();
+    *slot = Some(CachedToken {
+        access_token: response.access_token,
+        expires_at,
+    });
+    Ok(token)
+}
+
+/// Validate the env-var pair, pointing at the setup instructions when absent.
+/// Split out from `search_token` so the guidance path is testable without
+/// touching process-global env state.
+fn search_app_credentials(
+    client_id: Option<String>,
+    client_secret: Option<String>,
+) -> Result<(String, String)> {
+    match (client_id, client_secret) {
+        (Some(id), Some(secret)) if !id.trim().is_empty() && !secret.trim().is_empty() => {
+            Ok((id, secret))
+        }
+        _ => Err(eyre!("{SETUP_HELP}")),
+    }
+}
+
 #[derive(Deserialize)]
 struct ApiResponse {
     #[serde(default)]
@@ -197,7 +266,18 @@ fn parse_search_response(body: &str) -> Result<SearchResults> {
 mod tests {
     use super::*;
 
-    // Live network + login required: cargo test search_smoke -- --ignored
+    #[test]
+    fn missing_credentials_point_at_setup_docs() {
+        let err = search_app_credentials(None, None).unwrap_err();
+        assert!(err.to_string().contains("developer.spotify.com"));
+        assert!(err.to_string().contains("SPOTIFY_CLIENT_ID"));
+        // A set-but-empty variable gets the same guidance.
+        let err = search_app_credentials(Some("id".into()), Some("  ".into())).unwrap_err();
+        assert!(err.to_string().contains("developer.spotify.com"));
+    }
+
+    // Live network + SPOTIFY_CLIENT_ID/SPOTIFY_CLIENT_SECRET required:
+    // cargo test search_smoke -- --ignored
     #[test]
     #[ignore]
     fn search_smoke() {

src/tui.rs

@@ -1372,13 +1372,17 @@ pub fn draw_search_overlay(frame: &mut ratatui::Frame, panel: &SearchPanelState)
             return;
         }
         SearchStatus::Error(message) => {
-            frame.render_widget(
-                Paragraph::new(vec![Line::from(Span::styled(
-                    message.clone(),
-                    Style::default().fg(Color::Rgb(230, 130, 130)),
-                ))]),
-                chunks[2],
-            );
+            // Multi-line: the missing-credentials message carries setup steps.
+            let lines: Vec<Line> = message
+                .lines()
+                .map(|line| {
+                    Line::from(Span::styled(
+                        line.to_string(),
+                        Style::default().fg(Color::Rgb(230, 130, 130)),
+                    ))
+                })
+                .collect();
+            frame.render_widget(Paragraph::new(lines), chunks[2]);
             return;
         }
         SearchStatus::Idle => {}