From 0be0f6dcb02033db4a46760c32d89d681169cf7a Mon Sep 17 00:00:00 2001
From: vicrodh <103399283+vicrodh@users.noreply.github.com>
Date: Sat, 14 Feb 2026 13:25:18 -0600
Subject: [PATCH] feat(qbz-qobuz): implement Phase 4 - Qobuz API client

Extracted Qobuz API client from qbz-nix to qbz-qobuz crate.

Modules:
- client.rs: Main QobuzClient with all API methods
- auth.rs: Request signing and authentication
- bundle.rs: Bundle token extraction
- endpoints.rs: API endpoint definitions
- error.rs: API error types
- performers.rs: Performers parsing

Updated qbz-models with additional types:
- Discover types (DiscoverResponse, DiscoverAlbum, etc.)
- Artist page types (PageArtistResponse, ReleasesGridResponse, etc.)
- Playlist tags (PlaylistTag, PlaylistTagsResponse)

Dependencies:
- reqwest for HTTP
- md-5 for request signing
- futures-util for concurrent requests
- anyhow for error handling
---
 crates/qbz-models/src/lib.rs       |   11 +
 crates/qbz-models/src/types.rs     |  320 +++++++
 crates/qbz-qobuz/Cargo.toml        |    2 +
 crates/qbz-qobuz/src/auth.rs       |  151 +++
 crates/qbz-qobuz/src/bundle.rs     |  199 ++++
 crates/qbz-qobuz/src/client.rs     | 1439 ++++++++++++++++++++++++++++
 crates/qbz-qobuz/src/endpoints.rs  |   68 ++
 crates/qbz-qobuz/src/error.rs      |   47 +
 crates/qbz-qobuz/src/lib.rs        |   47 +-
 crates/qbz-qobuz/src/performers.rs |  139 +++
 10 files changed, 2410 insertions(+), 13 deletions(-)
 create mode 100644 crates/qbz-qobuz/src/auth.rs
 create mode 100644 crates/qbz-qobuz/src/bundle.rs
 create mode 100644 crates/qbz-qobuz/src/client.rs
 create mode 100644 crates/qbz-qobuz/src/endpoints.rs
 create mode 100644 crates/qbz-qobuz/src/error.rs
 create mode 100644 crates/qbz-qobuz/src/performers.rs

diff --git a/crates/qbz-models/src/lib.rs b/crates/qbz-models/src/lib.rs
index a6cb3ee50..09d555fc6 100644
--- a/crates/qbz-models/src/lib.rs
+++ b/crates/qbz-models/src/lib.rs
@@ -46,4 +46,15 @@ pub use types::{
     PlaylistDuplicateResult, PlaylistGenre, PlaylistOwner, PlaylistWithTrackIds, Quality,
     SearchResults, SearchResultsPage, StreamRestriction, StreamUrl, Track, TracksContainer,
     UserSession,
+    // Discover types
+    DiscoverAlbum, DiscoverAlbumDates, DiscoverAlbumImage, DiscoverArtist, DiscoverAudioInfo,
+    DiscoverContainer, DiscoverContainers, DiscoverData, DiscoverPlaylist, DiscoverPlaylistImage,
+    DiscoverPlaylistsResponse, DiscoverResponse, PlaylistTag, PlaylistTagsResponse, RawPlaylistTag,
+    // Artist page types
+    PageArtistAward, PageArtistBiography, PageArtistImages, PageArtistName,
+    PageArtistPhysicalSupport, PageArtistPlaylist, PageArtistPlaylistImages,
+    PageArtistPlaylistOwner, PageArtistPlaylists, PageArtistPortrait, PageArtistRelease,
+    PageArtistReleaseArtist, PageArtistReleaseContributor, PageArtistReleaseGroup,
+    PageArtistResponse, PageArtistRights, PageArtistSimilar, PageArtistSimilarItem,
+    PageArtistTrack, PageArtistTrackAlbum, ReleasesGridResponse,
 };
diff --git a/crates/qbz-models/src/types.rs b/crates/qbz-models/src/types.rs
index 59f2b47a2..8ada888ea 100644
--- a/crates/qbz-models/src/types.rs
+++ b/crates/qbz-models/src/types.rs
@@ -410,3 +410,323 @@ pub struct Favorites {
     pub tracks: Option<SearchResultsPage<Track>>,
     pub artists: Option<SearchResultsPage<Artist>>,
 }
+
+// ============ Discover API Types ============
+
+/// Discover index response
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct DiscoverResponse {
+    pub containers: DiscoverContainers,
+}
+
+/// All discover containers
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct DiscoverContainers {
+    pub playlists: Option<DiscoverContainer<DiscoverPlaylist>>,
+    pub ideal_discography: Option<DiscoverContainer<DiscoverAlbum>>,
+    pub playlists_tags: Option<DiscoverContainer<PlaylistTag>>,
+    pub new_releases: Option<DiscoverContainer<DiscoverAlbum>>,
+    pub qobuzissims: Option<DiscoverContainer<DiscoverAlbum>>,
+    pub most_streamed: Option<DiscoverContainer<DiscoverAlbum>>,
+    pub press_awards: Option<DiscoverContainer<DiscoverAlbum>>,
+    pub album_of_the_week: Option<DiscoverContainer<DiscoverAlbum>>,
+}
+
+/// Generic discover container
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct DiscoverContainer<T> {
+    pub id: String,
+    pub data: DiscoverData<T>,
+}
+
+/// Generic discover data with items
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct DiscoverData<T> {
+    pub has_more: bool,
+    pub items: Vec<T>,
+}
+
+/// Playlist from discover endpoint
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct DiscoverPlaylist {
+    pub id: u64,
+    pub name: String,
+    pub owner: PlaylistOwner,
+    pub image: DiscoverPlaylistImage,
+    pub description: Option<String>,
+    pub duration: u32,
+    pub tracks_count: u32,
+    pub genres: Option<Vec<PlaylistGenre>>,
+    pub tags: Option<Vec<PlaylistTag>>,
+}
+
+/// Playlist image from discover
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct DiscoverPlaylistImage {
+    pub rectangle: Option<String>,
+    pub covers: Option<Vec<String>>,
+}
+
+/// Playlist tag (for filtering)
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PlaylistTag {
+    pub id: u64,
+    pub slug: String,
+    pub name: String,
+}
+
+/// Raw playlist tag from /playlist/getTags
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct RawPlaylistTag {
+    pub slug: String,
+    pub name_json: String,
+    pub position: Option<String>,
+    pub is_discover: Option<String>,
+    pub featured_tag_id: Option<String>,
+}
+
+/// Response from /playlist/getTags
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PlaylistTagsResponse {
+    pub tags: Vec<RawPlaylistTag>,
+}
+
+/// Response from discover/playlists endpoint
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct DiscoverPlaylistsResponse {
+    pub has_more: bool,
+    pub items: Vec<DiscoverPlaylist>,
+}
+
+/// Album from discover endpoint
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct DiscoverAlbum {
+    pub id: String,
+    pub title: String,
+    pub version: Option<String>,
+    pub track_count: Option<u32>,
+    pub duration: Option<u32>,
+    pub parental_warning: Option<bool>,
+    pub image: DiscoverAlbumImage,
+    pub artists: Vec<DiscoverArtist>,
+    pub label: Option<Label>,
+    pub genre: Option<Genre>,
+    pub dates: Option<DiscoverAlbumDates>,
+    pub audio_info: Option<DiscoverAudioInfo>,
+}
+
+/// Album image from discover endpoint
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct DiscoverAlbumImage {
+    pub small: Option<String>,
+    pub thumbnail: Option<String>,
+    pub large: Option<String>,
+}
+
+/// Artist in discover album
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct DiscoverArtist {
+    pub id: u64,
+    pub name: String,
+    pub roles: Option<Vec<String>>,
+}
+
+/// Album dates from discover
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct DiscoverAlbumDates {
+    pub download: Option<String>,
+    pub original: Option<String>,
+    pub stream: Option<String>,
+}
+
+/// Audio info from discover album
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct DiscoverAudioInfo {
+    pub maximum_sampling_rate: Option<f64>,
+    pub maximum_bit_depth: Option<u32>,
+    pub maximum_channel_count: Option<u32>,
+}
+
+// ============ Artist Page Types (/artist/page) ============
+
+/// Top-level response from /artist/page
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PageArtistResponse {
+    pub id: u64,
+    pub name: PageArtistName,
+    pub artist_category: Option<String>,
+    pub biography: Option<PageArtistBiography>,
+    pub images: Option<PageArtistImages>,
+    pub similar_artists: Option<PageArtistSimilar>,
+    pub top_tracks: Option<Vec<PageArtistTrack>>,
+    pub last_release: Option<serde_json::Value>,
+    pub releases: Option<Vec<PageArtistReleaseGroup>>,
+    pub tracks_appears_on: Option<Vec<PageArtistTrack>>,
+    pub playlists: Option<PageArtistPlaylists>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PageArtistName {
+    pub display: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PageArtistBiography {
+    pub content: Option<String>,
+    pub source: Option<serde_json::Value>,
+    pub language: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PageArtistImages {
+    pub portrait: Option<PageArtistPortrait>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PageArtistPortrait {
+    pub hash: String,
+    pub format: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PageArtistSimilar {
+    pub has_more: bool,
+    pub items: Vec<PageArtistSimilarItem>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PageArtistSimilarItem {
+    pub id: u64,
+    pub name: PageArtistName,
+    pub images: Option<PageArtistImages>,
+}
+
+/// A group of releases by type
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PageArtistReleaseGroup {
+    #[serde(rename = "type")]
+    pub release_type: String,
+    pub has_more: bool,
+    pub items: Vec<PageArtistRelease>,
+}
+
+/// A release item from /artist/page
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PageArtistRelease {
+    pub id: String,
+    pub title: String,
+    pub version: Option<String>,
+    pub tracks_count: Option<u32>,
+    pub artist: Option<PageArtistReleaseArtist>,
+    pub artists: Option<Vec<PageArtistReleaseContributor>>,
+    pub image: Option<ImageSet>,
+    pub label: Option<Label>,
+    pub genre: Option<Genre>,
+    pub release_type: Option<String>,
+    pub release_tags: Option<Vec<String>>,
+    pub duration: Option<u32>,
+    pub dates: Option<DiscoverAlbumDates>,
+    pub parental_warning: Option<bool>,
+    pub audio_info: Option<DiscoverAudioInfo>,
+    pub rights: Option<PageArtistRights>,
+    pub awards: Option<Vec<PageArtistAward>>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PageArtistReleaseArtist {
+    pub id: u64,
+    pub name: PageArtistName,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PageArtistReleaseContributor {
+    pub id: u64,
+    pub name: String,
+    pub roles: Option<Vec<String>>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PageArtistRights {
+    pub streamable: Option<bool>,
+    pub hires_streamable: Option<bool>,
+    pub hires_purchasable: Option<bool>,
+    pub purchasable: Option<bool>,
+    pub downloadable: Option<bool>,
+    pub previewable: Option<bool>,
+    pub sampleable: Option<bool>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PageArtistAward {
+    pub id: u64,
+    pub name: String,
+    pub awarded_at: Option<String>,
+}
+
+/// Track from /artist/page
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PageArtistTrack {
+    pub id: u64,
+    pub title: String,
+    pub version: Option<String>,
+    pub duration: Option<u32>,
+    pub isrc: Option<String>,
+    pub parental_warning: Option<bool>,
+    pub artist: Option<PageArtistReleaseArtist>,
+    pub composer: Option<serde_json::Value>,
+    pub audio_info: Option<DiscoverAudioInfo>,
+    pub rights: Option<PageArtistRights>,
+    pub physical_support: Option<PageArtistPhysicalSupport>,
+    pub album: Option<PageArtistTrackAlbum>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PageArtistPhysicalSupport {
+    pub media_number: Option<u32>,
+    pub track_number: Option<u32>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PageArtistTrackAlbum {
+    pub id: String,
+    pub title: String,
+    pub version: Option<String>,
+    pub image: Option<ImageSet>,
+    pub label: Option<Label>,
+    pub genre: Option<Genre>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PageArtistPlaylists {
+    pub has_more: bool,
+    pub items: Vec<PageArtistPlaylist>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PageArtistPlaylist {
+    pub id: u64,
+    pub title: Option<String>,
+    pub description: Option<String>,
+    pub owner: Option<PageArtistPlaylistOwner>,
+    pub tracks_count: Option<u32>,
+    pub duration: Option<u32>,
+    pub images: Option<PageArtistPlaylistImages>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PageArtistPlaylistOwner {
+    pub id: u64,
+    pub name: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PageArtistPlaylistImages {
+    pub rectangle: Option<Vec<String>>,
+}
+
+/// Response from /artist/getReleasesGrid
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ReleasesGridResponse {
+    pub has_more: bool,
+    pub items: Vec<PageArtistRelease>,
+}
diff --git a/crates/qbz-qobuz/Cargo.toml b/crates/qbz-qobuz/Cargo.toml
index 89e72c83d..61dbaaaa0 100644
--- a/crates/qbz-qobuz/Cargo.toml
+++ b/crates/qbz-qobuz/Cargo.toml
@@ -10,6 +10,7 @@ qbz-models = { path = "../qbz-models" }
 
 # Async
 tokio = { workspace = true }
+futures-util = { workspace = true }
 
 # HTTP
 reqwest = { workspace = true }
@@ -33,3 +34,4 @@ log = { workspace = true }
 
 # Error handling
 thiserror = { workspace = true }
+anyhow = { workspace = true }
diff --git a/crates/qbz-qobuz/src/auth.rs b/crates/qbz-qobuz/src/auth.rs
new file mode 100644
index 000000000..b5169c5f3
--- /dev/null
+++ b/crates/qbz-qobuz/src/auth.rs
@@ -0,0 +1,151 @@
+//! Authentication and request signing
+
+use chrono::{TimeZone, Utc};
+use md5::{Digest, Md5};
+use std::time::{SystemTime, UNIX_EPOCH};
+
+use super::error::{ApiError, Result};
+use qbz_models::UserSession;
+
+/// Generate MD5 signature for protected API endpoints
+///
+/// Signature format: MD5(method + params + timestamp + secret)
+pub fn generate_signature(method: &str, params: &str, timestamp: u64, secret: &str) -> String {
+    let sig_string = format!("{}{}{}{}", method, params, timestamp, secret);
+    let mut hasher = Md5::new();
+    hasher.update(sig_string.as_bytes());
+    format!("{:x}", hasher.finalize())
+}
+
+/// Generate signature for track/getFileUrl endpoint
+pub fn sign_get_file_url(track_id: u64, format_id: u32, timestamp: u64, secret: &str) -> String {
+    let params = format!(
+        "format_id{}intentstreamtrack_id{}",
+        format_id, track_id
+    );
+    generate_signature("trackgetFileUrl", &params, timestamp, secret)
+}
+
+/// Generate signature for favorite/getUserFavorites endpoint
+pub fn sign_get_favorites(timestamp: u64, secret: &str) -> String {
+    generate_signature("favoritegetUserFavorites", "", timestamp, secret)
+}
+
+/// Get current Unix timestamp
+pub fn get_timestamp() -> u64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .expect("Time went backwards")
+        .as_secs()
+}
+
+/// Parse user login response
+pub fn parse_login_response(response: &serde_json::Value) -> Result<UserSession> {
+    let user = response
+        .get("user")
+        .ok_or_else(|| ApiError::AuthenticationError("No user in response".to_string()))?;
+
+    let user_auth_token = response
+        .get("user_auth_token")
+        .and_then(|v| v.as_str())
+        .ok_or_else(|| ApiError::AuthenticationError("No auth token in response".to_string()))?
+        .to_string();
+
+    let user_id = user
+        .get("id")
+        .and_then(|v| v.as_u64())
+        .ok_or_else(|| ApiError::AuthenticationError("No user id".to_string()))?;
+
+    let email = user
+        .get("email")
+        .and_then(|v| v.as_str())
+        .unwrap_or("")
+        .to_string();
+
+    let display_name = user
+        .get("display_name")
+        .and_then(|v| v.as_str())
+        .or_else(|| user.get("login").and_then(|v| v.as_str()))
+        .unwrap_or("")
+        .to_string();
+
+    // Check subscription
+    let credential = user.get("credential");
+    let subscription_label = credential
+        .and_then(|c| c.get("parameters"))
+        .and_then(|p| p.get("short_label"))
+        .and_then(|v| v.as_str())
+        .unwrap_or("Unknown")
+        .to_string();
+
+    fn parse_subscription_valid_until(parameters: &serde_json::Value) -> Option<String> {
+        // Try common string fields first.
+        let string_keys = [
+            "end_date",
+            "expiration_date",
+            "valid_until",
+            "expires_at",
+            "expiry_date",
+        ];
+        for key in string_keys {
+            if let Some(s) = parameters.get(key).and_then(|v| v.as_str()) {
+                let trimmed = s.trim();
+                if !trimmed.is_empty() {
+                    return Some(trimmed.to_string());
+                }
+            }
+        }
+
+        // Try common timestamp fields (seconds).
+        let ts_keys = ["end_date_ts", "expires_at_ts", "expiration_ts", "valid_until_ts"];
+        for key in ts_keys {
+            if let Some(ts) = parameters.get(key).and_then(|v| v.as_i64()) {
+                if ts > 0 {
+                    return Some(Utc.timestamp_opt(ts, 0).single()?.date_naive().to_string());
+                }
+            }
+        }
+
+        None
+    }
+
+    let subscription_valid_until = credential
+        .and_then(|c| c.get("parameters"))
+        .and_then(parse_subscription_valid_until);
+
+    // Check if user has valid subscription
+    let has_subscription = credential
+        .and_then(|c| c.get("parameters"))
+        .map(|p| !p.is_null() && p.as_object().map(|o| !o.is_empty()).unwrap_or(false))
+        .unwrap_or(false);
+
+    if !has_subscription {
+        return Err(ApiError::IneligibleUser);
+    }
+
+    Ok(UserSession {
+        user_auth_token,
+        user_id,
+        email,
+        display_name,
+        subscription_label,
+        subscription_valid_until,
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_generate_signature() {
+        let sig = generate_signature("test", "params", 1234567890, "secret");
+        assert_eq!(sig.len(), 32); // MD5 hex is 32 chars
+    }
+
+    #[test]
+    fn test_sign_get_file_url() {
+        let sig = sign_get_file_url(123456, 27, 1234567890, "testsecret");
+        assert_eq!(sig.len(), 32);
+    }
+}
diff --git a/crates/qbz-qobuz/src/bundle.rs b/crates/qbz-qobuz/src/bundle.rs
new file mode 100644
index 000000000..e56b04e60
--- /dev/null
+++ b/crates/qbz-qobuz/src/bundle.rs
@@ -0,0 +1,199 @@
+//! Bundle token extraction from Qobuz web player
+//!
+//! Extracts app_id and secrets from the Qobuz JavaScript bundle.
+//! This is necessary because Qobuz doesn't provide a public API.
+
+use regex::Regex;
+use reqwest::Client;
+
+use super::error::{ApiError, Result};
+
+const LOGIN_PAGE_URL: &str = "https://play.qobuz.com/login";
+const BUNDLE_BASE_URL: &str = "https://play.qobuz.com";
+
+/// Extracted bundle tokens
+#[derive(Debug, Clone)]
+pub struct BundleTokens {
+    pub app_id: String,
+    pub secrets: Vec<String>,
+}
+
+/// Extract app_id and secrets from Qobuz bundle
+pub async fn extract_bundle_tokens(client: &Client) -> Result<BundleTokens> {
+    // Step 1: Get login page to find bundle URL
+    let login_page = client
+        .get(LOGIN_PAGE_URL)
+        .send()
+        .await?
+        .text()
+        .await?;
+
+    let bundle_url = extract_bundle_url(&login_page)?;
+    let full_bundle_url = format!("{}{}", BUNDLE_BASE_URL, bundle_url);
+
+    // Step 2: Fetch the bundle
+    let bundle_content = client
+        .get(&full_bundle_url)
+        .send()
+        .await?
+        .text()
+        .await?;
+
+    // Step 3: Extract app_id
+    let app_id = extract_app_id(&bundle_content)?;
+
+    // Step 4: Extract secrets
+    let secrets = extract_secrets(&bundle_content)?;
+
+    if secrets.is_empty() {
+        return Err(ApiError::BundleExtractionError(
+            "No secrets found in bundle".to_string(),
+        ));
+    }
+
+    Ok(BundleTokens { app_id, secrets })
+}
+
+fn extract_bundle_url(html: &str) -> Result<String> {
+    // Pattern: <script src="/resources/X.X.X-bXXX/bundle.js"></script>
+    let re = Regex::new(r#"<script src="(/resources/\d+\.\d+\.\d+-[a-z]\d{3}/bundle\.js)"></script>"#)
+        .expect("Invalid regex");
+
+    re.captures(html)
+        .and_then(|caps| caps.get(1))
+        .map(|m| m.as_str().to_string())
+        .ok_or_else(|| ApiError::BundleExtractionError("Bundle URL not found".to_string()))
+}
+
+fn extract_app_id(bundle: &str) -> Result<String> {
+    // Pattern: production:{api:{appId:"XXXXXXXXX"
+    let re = Regex::new(r#"production:\{api:\{appId:"(?P<app_id>\d{9})""#)
+        .expect("Invalid regex");
+
+    re.captures(bundle)
+        .and_then(|caps| caps.name("app_id"))
+        .map(|m| m.as_str().to_string())
+        .ok_or_else(|| ApiError::BundleExtractionError("App ID not found".to_string()))
+}
+
+fn extract_secrets(bundle: &str) -> Result<Vec<String>> {
+    // Extract seeds with their timezone keys
+    // Pattern: X.initialSeed("SEED",window.utimezone.TIMEZONE)
+    let seed_re = Regex::new(
+        r#"[a-z]\.initialSeed\("(?P<seed>[\w=]+)",window\.utimezone\.(?P<timezone>[a-z]+)\)"#,
+    )
+    .expect("Invalid regex");
+
+    let mut seeds: std::collections::HashMap<String, String> = std::collections::HashMap::new();
+    let mut timezones: Vec<String> = Vec::new();
+
+    for caps in seed_re.captures_iter(bundle) {
+        if let (Some(seed), Some(tz)) = (caps.name("seed"), caps.name("timezone")) {
+            let tz_str = tz.as_str().to_string();
+            seeds.insert(tz_str.clone(), seed.as_str().to_string());
+            timezones.push(tz_str);
+        }
+    }
+
+    log::debug!("Found {} seeds with timezones: {:?}", seeds.len(), timezones);
+
+    if seeds.is_empty() {
+        return Err(ApiError::BundleExtractionError("No seeds found".to_string()));
+    }
+
+    // Build dynamic regex with found timezones (capitalize first letter for matching)
+    // Pattern: name:"\w+/Timezone",info:"INFO",extras:"EXTRAS"
+    let tz_pattern: Vec<String> = timezones
+        .iter()
+        .map(|tz| {
+            // Capitalize first letter: "berlin" -> "Berlin"
+            let mut chars = tz.chars();
+            match chars.next() {
+                None => String::new(),
+                Some(c) => c.to_uppercase().collect::<String>() + chars.as_str(),
+            }
+        })
+        .collect();
+
+    let tz_alternatives = tz_pattern.join("|");
+    let info_pattern = format!(
+        r#"name:"\w+/(?P<timezone>{})",info:"(?P<info>[\w=]+)",extras:"(?P<extras>[\w=]+)""#,
+        tz_alternatives
+    );
+
+    log::debug!("Info regex pattern: {}", info_pattern);
+
+    let info_re = Regex::new(&info_pattern).expect("Invalid info regex");
+
+    let mut secrets = Vec::new();
+
+    for caps in info_re.captures_iter(bundle) {
+        if let (Some(tz), Some(info), Some(extras)) = (
+            caps.name("timezone"),
+            caps.name("info"),
+            caps.name("extras"),
+        ) {
+            // Convert capitalized timezone back to lowercase for lookup
+            let tz_lower = tz.as_str().to_lowercase();
+            if let Some(seed) = seeds.get(&tz_lower) {
+                // Concatenate seed + info + extras, remove last 44 chars, base64 decode
+                let combined = format!("{}{}{}", seed, info.as_str(), extras.as_str());
+                log::debug!("Combined length: {}, timezone: {}", combined.len(), tz_lower);
+
+                if combined.len() > 44 {
+                    let trimmed = &combined[..combined.len() - 44];
+                    match base64::Engine::decode(
+                        &base64::engine::general_purpose::STANDARD,
+                        trimmed,
+                    ) {
+                        Ok(decoded) => {
+                            if let Ok(secret) = String::from_utf8(decoded) {
+                                log::info!("Successfully extracted secret for timezone: {}", tz_lower);
+                                secrets.push(secret);
+                            }
+                        }
+                        Err(e) => {
+                            log::debug!("Base64 decode failed for {}: {}", tz_lower, e);
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    // If the complex extraction fails, try a simpler pattern
+    // that might work for some bundle versions
+    if secrets.is_empty() {
+        log::warn!("Complex extraction failed, trying simple appSecret pattern");
+        let simple_re = Regex::new(r#"appSecret:"([a-f0-9]{32})""#).expect("Invalid regex");
+        for caps in simple_re.captures_iter(bundle) {
+            if let Some(secret) = caps.get(1) {
+                secrets.push(secret.as_str().to_string());
+            }
+        }
+    }
+
+    log::info!("Extracted {} secrets", secrets.len());
+    Ok(secrets)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_extract_bundle_url() {
+        let html = r#"<script src="/resources/7.0.1-b001/bundle.js"></script>"#;
+        let result = extract_bundle_url(html);
+        assert!(result.is_ok());
+        assert_eq!(result.unwrap(), "/resources/7.0.1-b001/bundle.js");
+    }
+
+    #[test]
+    fn test_extract_app_id() {
+        let bundle = r#"production:{api:{appId:"123456789",appSecret:"abc"}"#;
+        let result = extract_app_id(bundle);
+        assert!(result.is_ok());
+        assert_eq!(result.unwrap(), "123456789");
+    }
+}
diff --git a/crates/qbz-qobuz/src/client.rs b/crates/qbz-qobuz/src/client.rs
new file mode 100644
index 000000000..7162bb821
--- /dev/null
+++ b/crates/qbz-qobuz/src/client.rs
@@ -0,0 +1,1439 @@
+//! Qobuz API client implementation
+
+use reqwest::{Client, StatusCode};
+use serde_json::Value;
+use std::sync::Arc;
+use tokio::sync::RwLock;
+
+use super::auth::{get_timestamp, parse_login_response, sign_get_favorites, sign_get_file_url};
+use super::bundle::{extract_bundle_tokens, BundleTokens};
+use super::endpoints::{self, paths};
+use super::error::{ApiError, Result};
+use qbz_models::*;
+
+const USER_AGENT: &str = "Mozilla/5.0 (X11; Linux x86_64; rv:120.0) Gecko/20100101 Firefox/120.0";
+
+/// Qobuz API client
+pub struct QobuzClient {
+    http: Client,
+    tokens: Arc<RwLock<Option<BundleTokens>>>,
+    session: Arc<RwLock<Option<UserSession>>>,
+    validated_secret: Arc<RwLock<Option<String>>>,
+    locale: Arc<RwLock<String>>,
+}
+
+impl Clone for QobuzClient {
+    fn clone(&self) -> Self {
+        Self {
+            http: self.http.clone(),
+            tokens: Arc::clone(&self.tokens),
+            session: Arc::clone(&self.session),
+            validated_secret: Arc::clone(&self.validated_secret),
+            locale: Arc::clone(&self.locale),
+        }
+    }
+}
+
+impl QobuzClient {
+    /// Create a new client
+    pub fn new() -> Result<Self> {
+        let http = Client::builder()
+            .user_agent(USER_AGENT)
+            .cookie_store(true)
+            .build()?;
+
+        Ok(Self {
+            http,
+            tokens: Arc::new(RwLock::new(None)),
+            session: Arc::new(RwLock::new(None)),
+            validated_secret: Arc::new(RwLock::new(None)),
+            locale: Arc::new(RwLock::new("en".to_string())),
+        })
+    }
+
+    /// Initialize client by extracting bundle tokens
+    pub async fn init(&self) -> Result<()> {
+        let tokens = extract_bundle_tokens(&self.http).await?;
+        *self.tokens.write().await = Some(tokens);
+        Ok(())
+    }
+
+    /// Set the locale for API requests
+    pub async fn set_locale(&self, locale: String) {
+        *self.locale.write().await = locale;
+    }
+
+    /// Get the current locale (public for cache key generation)
+    pub async fn get_locale(&self) -> String {
+        self.locale.read().await.clone()
+    }
+
+    /// Get the current locale (internal use)
+    async fn locale(&self) -> String {
+        self.locale.read().await.clone()
+    }
+
+    /// Get app ID (public for catalog search)
+    pub async fn app_id(&self) -> Result<String> {
+        self.tokens
+            .read()
+            .await
+            .as_ref()
+            .map(|t| t.app_id.clone())
+            .ok_or_else(|| ApiError::BundleExtractionError("Client not initialized".to_string()))
+    }
+
+    /// Get HTTP client reference (public for catalog search)
+    pub fn get_http(&self) -> &Client {
+        &self.http
+    }
+
+    /// Get validated secret (validates on first use)
+    async fn secret(&self) -> Result<String> {
+        // Check if we already have a validated secret
+        if let Some(secret) = self.validated_secret.read().await.clone() {
+            return Ok(secret);
+        }
+
+        // Need to validate secrets
+        let tokens = self.tokens.read().await;
+        let tokens = tokens
+            .as_ref()
+            .ok_or_else(|| ApiError::BundleExtractionError("Client not initialized".to_string()))?;
+
+        for secret in &tokens.secrets {
+            if self.test_secret(secret).await? {
+                *self.validated_secret.write().await = Some(secret.clone());
+                return Ok(secret.clone());
+            }
+        }
+
+        Err(ApiError::InvalidAppSecret)
+    }
+
+    /// Test if a secret is valid using a known track
+    async fn test_secret(&self, secret: &str) -> Result<bool> {
+        let test_track_id = 5966783u64; // Known test track
+        let timestamp = get_timestamp();
+        let signature = sign_get_file_url(test_track_id, 5, timestamp, secret);
+
+        let url = endpoints::build_url(paths::TRACK_GET_FILE_URL);
+        let response = self
+            .http
+            .get(&url)
+            .headers(self.api_headers().await?)
+            .query(&[
+                ("track_id", test_track_id.to_string()),
+                ("format_id", "5".to_string()),
+                ("intent", "stream".to_string()),
+                ("request_ts", timestamp.to_string()),
+                ("request_sig", signature),
+            ])
+            .send()
+            .await?;
+
+        Ok(response.status() != StatusCode::BAD_REQUEST)
+    }
+
+    /// Login with email and password
+    pub async fn login(&self, email: &str, password: &str) -> Result<UserSession> {
+        let url = endpoints::build_url(paths::USER_LOGIN);
+        let response = self
+            .http
+            .get(&url)
+            .headers(self.api_headers().await?)
+            .query(&[("email", email), ("password", password)])
+            .send()
+            .await?;
+
+        match response.status() {
+            StatusCode::OK => {
+                let json: Value = response.json().await?;
+                let session = parse_login_response(&json)?;
+                *self.session.write().await = Some(session.clone());
+                Ok(session)
+            }
+            StatusCode::UNAUTHORIZED => {
+                Err(ApiError::AuthenticationError("Invalid credentials".to_string()))
+            }
+            StatusCode::BAD_REQUEST => Err(ApiError::InvalidAppId),
+            status => Err(ApiError::ApiResponse(format!("Unexpected status: {}", status))),
+        }
+    }
+
+    /// Check if logged in
+    pub async fn is_logged_in(&self) -> bool {
+        self.session.read().await.is_some()
+    }
+
+    /// Logout - clear the session
+    pub async fn logout(&self) {
+        *self.session.write().await = None;
+    }
+
+    /// Get current user info (display name, subscription, and expiry if available)
+    pub async fn get_user_info(&self) -> Option<(String, String, Option<String>)> {
+        self.session.read().await.as_ref().map(|s| {
+            (
+                s.display_name.clone(),
+                s.subscription_label.clone(),
+                s.subscription_valid_until.clone(),
+            )
+        })
+    }
+
+    /// Get current user ID
+    pub async fn get_user_id(&self) -> Option<u64> {
+        self.session.read().await.as_ref().map(|s| s.user_id)
+    }
+
+    /// Get user auth token header value (public for catalog search)
+    pub async fn auth_token(&self) -> Result<String> {
+        self.session
+            .read()
+            .await
+            .as_ref()
+            .map(|s| s.user_auth_token.clone())
+            .ok_or_else(|| ApiError::AuthenticationError("Not logged in".to_string()))
+    }
+
+    // === Header helpers ===
+
+    /// Build standard API headers.
+    /// Always includes X-App-Id. Includes X-User-Auth-Token when logged in.
+    async fn api_headers(&self) -> Result<reqwest::header::HeaderMap> {
+        use reqwest::header::{HeaderMap, HeaderValue};
+        let mut headers = HeaderMap::new();
+
+        let app_id = self.app_id().await?;
+        headers.insert(
+            "X-App-Id",
+            HeaderValue::from_str(&app_id).map_err(|_| ApiError::InvalidAppId)?,
+        );
+
+        if let Ok(token) = self.auth_token().await {
+            if let Ok(val) = HeaderValue::from_str(&token) {
+                headers.insert("X-User-Auth-Token", val);
+            }
+        }
+
+        Ok(headers)
+    }
+
+    /// Build headers that REQUIRE authentication. Fails if not logged in.
+    async fn authenticated_headers(&self) -> Result<reqwest::header::HeaderMap> {
+        use reqwest::header::{HeaderMap, HeaderValue};
+        let mut headers = HeaderMap::new();
+
+        let app_id = self.app_id().await?;
+        headers.insert(
+            "X-App-Id",
+            HeaderValue::from_str(&app_id).map_err(|_| ApiError::InvalidAppId)?,
+        );
+
+        let token = self.auth_token().await?;
+        headers.insert(
+            "X-User-Auth-Token",
+            HeaderValue::from_str(&token)
+                .map_err(|_| ApiError::AuthenticationError("Invalid auth token format".into()))?,
+        );
+
+        Ok(headers)
+    }
+
+    // === Search endpoints ===
+
+    /// Search for albums
+    /// Optional search_type: "MainArtist", "Performer", "Composer", "Label", "ReleaseName"
+    pub async fn search_albums(
+        &self,
+        query: &str,
+        limit: u32,
+        offset: u32,
+        search_type: Option<&str>,
+    ) -> Result<SearchResultsPage<Album>> {
+        let url = endpoints::build_url(paths::ALBUM_SEARCH);
+        let limit_str = limit.to_string();
+        let offset_str = offset.to_string();
+
+        let mut params: Vec<(&str, &str)> = vec![
+            ("query", query),
+            ("limit", &limit_str),
+            ("offset", &offset_str),
+        ];
+
+        if let Some(st) = search_type {
+            params.push(("type", st));
+        }
+
+        let http_response = self
+            .http
+            .get(&url)
+            .headers(self.api_headers().await?)
+            .query(&params)
+            .send()
+            .await?;
+        log::debug!("[API] search_albums status={}", http_response.status());
+        let response: Value = http_response.json().await?;
+
+        let albums = response
+            .get("albums")
+            .ok_or_else(|| ApiError::ApiResponse("No albums in response".to_string()))?;
+
+        Ok(serde_json::from_value(albums.clone())?)
+    }
+
+    /// Search for tracks
+    /// Optional search_type: "MainArtist", "Performer", "Composer", "Label", "ReleaseName"
+    pub async fn search_tracks(
+        &self,
+        query: &str,
+        limit: u32,
+        offset: u32,
+        search_type: Option<&str>,
+    ) -> Result<SearchResultsPage<Track>> {
+        let url = endpoints::build_url(paths::TRACK_SEARCH);
+        let limit_str = limit.to_string();
+        let offset_str = offset.to_string();
+
+        let mut params: Vec<(&str, &str)> = vec![
+            ("query", query),
+            ("limit", &limit_str),
+            ("offset", &offset_str),
+        ];
+
+        if let Some(st) = search_type {
+            params.push(("type", st));
+        }
+
+        let http_response = self
+            .http
+            .get(&url)
+            .headers(self.api_headers().await?)
+            .query(&params)
+            .send()
+            .await?;
+        log::debug!("[API] search_tracks status={}", http_response.status());
+        let response: Value = http_response.json().await?;
+
+        let tracks = response
+            .get("tracks")
+            .ok_or_else(|| ApiError::ApiResponse("No tracks in response".to_string()))?;
+
+        Ok(serde_json::from_value(tracks.clone())?)
+    }
+
+    /// Search for artists
+    /// Optional search_type: "MainArtist", "Performer", "Composer", "Label", "ReleaseName"
+    pub async fn search_artists(
+        &self,
+        query: &str,
+        limit: u32,
+        offset: u32,
+        search_type: Option<&str>,
+    ) -> Result<SearchResultsPage<Artist>> {
+        let url = endpoints::build_url(paths::ARTIST_SEARCH);
+        let limit_str = limit.to_string();
+        let offset_str = offset.to_string();
+
+        let mut params: Vec<(&str, &str)> = vec![
+            ("query", query),
+            ("limit", &limit_str),
+            ("offset", &offset_str),
+        ];
+
+        if let Some(st) = search_type {
+            params.push(("type", st));
+        }
+
+        let http_response = self
+            .http
+            .get(&url)
+            .headers(self.api_headers().await?)
+            .query(&params)
+            .send()
+            .await?;
+        log::debug!("[API] search_artists status={}", http_response.status());
+        let response: Value = http_response.json().await?;
+
+        let artists = response
+            .get("artists")
+            .ok_or_else(|| ApiError::ApiResponse("No artists in response".to_string()))?;
+
+        Ok(serde_json::from_value(artists.clone())?)
+    }
+
+    /// Get similar artists for an artist ID
+    pub async fn get_similar_artists(&self, artist_id: u64, limit: u32, offset: u32) -> Result<SearchResultsPage<Artist>> {
+        let url = endpoints::build_url(paths::ARTIST_GET_SIMILAR);
+        let http_response = self
+            .http
+            .get(&url)
+            .headers(self.api_headers().await?)
+            .query(&[
+                ("artist_id", artist_id.to_string()),
+                ("limit", limit.to_string()),
+                ("offset", offset.to_string()),
+            ])
+            .send()
+            .await?;
+        log::debug!("[API] get_similar_artists({}) status={}", artist_id, http_response.status());
+        let response: Value = http_response.json().await?;
+
+        let artists = response
+            .get("artists")
+            .ok_or_else(|| ApiError::ApiResponse("No artists in response".to_string()))?;
+
+        Ok(serde_json::from_value(artists.clone())?)
+    }
+
+    /// Get an artist's tracks (public endpoint via artist/get?extra=tracks)
+    pub async fn get_artist_tracks(&self, artist_id: u64, limit: u32, offset: u32) -> Result<TracksContainer> {
+        let url = endpoints::build_url(paths::ARTIST_GET);
+        let locale = self.locale().await;
+
+        let http_response = self
+            .http
+            .get(&url)
+            .headers(self.api_headers().await?)
+            .query(&[
+                ("artist_id", artist_id.to_string()),
+                ("extra", "tracks".to_string()),
+                ("lang", locale),
+                ("limit", limit.to_string()),
+                ("offset", offset.to_string()),
+            ])
+            .send()
+            .await?;
+        log::debug!("[API] get_artist_tracks({}) status={}", artist_id, http_response.status());
+        let response: Value = http_response.json().await?;
+
+        let tracks = response
+            .get("tracks")
+            .ok_or_else(|| ApiError::ApiResponse("No tracks in artist response".to_string()))?;
+
+        Ok(serde_json::from_value(tracks.clone())?)
+    }
+
+    // === Get endpoints ===
+
+    /// Get album by ID
+    pub async fn get_album(&self, album_id: &str) -> Result<Album> {
+        let url = endpoints::build_url(paths::ALBUM_GET);
+        let http_response = self
+            .http
+            .get(&url)
+            .headers(self.api_headers().await?)
+            .query(&[("album_id", album_id)])
+            .send()
+            .await?;
+        let status = http_response.status();
+        log::debug!("[API] get_album({}) status={}", album_id, status);
+
+        if status == StatusCode::NOT_FOUND {
+            log::warn!("[API] get_album({}) returned 404 — album not found", album_id);
+            return Err(ApiError::ApiResponse(format!("Album {} not found (404)", album_id)));
+        }
+        if !status.is_success() {
+            log::error!("[API] get_album({}) unexpected status={}", album_id, status);
+            return Err(ApiError::ApiResponse(format!("get_album({}) status {}", album_id, status)));
+        }
+
+        let response: Value = http_response.json().await?;
+        Ok(serde_json::from_value(response)?)
+    }
+
+    /// Get featured albums by type (new-releases, press-awards, most-streamed)
+    pub async fn get_featured_albums(
+        &self,
+        featured_type: &str,
+        limit: u32,
+        offset: u32,
+        genre_id: Option<u64>,
+    ) -> Result<SearchResultsPage<Album>> {
+        let url = endpoints::build_url(paths::ALBUM_GET_FEATURED);
+        let mut query = vec![
+            ("type".to_string(), featured_type.to_string()),
+            ("limit".to_string(), limit.to_string()),
+            ("offset".to_string(), offset.to_string()),
+        ];
+
+        if let Some(gid) = genre_id {
+            query.push(("genre_id".to_string(), gid.to_string()));
+        }
+
+        let http_response = self
+            .http
+            .get(&url)
+            .headers(self.api_headers().await?)
+            .query(&query)
+            .send()
+            .await?;
+        log::debug!("[API] get_featured_albums({}) status={}", featured_type, http_response.status());
+        let response: Value = http_response.json().await?;
+
+        let albums = response
+            .get("albums")
+            .ok_or_else(|| ApiError::ApiResponse("No albums in response".to_string()))?;
+
+        Ok(serde_json::from_value(albums.clone())?)
+    }
+
+    /// Get list of genres
+    pub async fn get_genres(&self, parent_id: Option<u64>) -> Result<Vec<GenreInfo>> {
+        let url = endpoints::build_url(paths::GENRE_LIST);
+        // Force English for consistent genre names across all user regions
+        let mut query: Vec<(&str, String)> = vec![
+            ("lang", "en".to_string()),
+        ];
+
+        if let Some(pid) = parent_id {
+            query.push(("parent_id", pid.to_string()));
+        }
+
+        let http_response = self
+            .http
+            .get(&url)
+            .headers(self.api_headers().await?)
+            .query(&query)
+            .send()
+            .await?;
+        log::debug!("[API] get_genres(parent={:?}) status={}", parent_id, http_response.status());
+        let response: Value = http_response.json().await?;
+
+        let genres = response
+            .get("genres")
+            .and_then(|g| g.get("items"))
+            .ok_or_else(|| ApiError::ApiResponse("No genres in response".to_string()))?;
+
+        Ok(serde_json::from_value(genres.clone())?)
+    }
+
+    /// Get discover index (home page content: playlists, ideal discography, etc.)
+    pub async fn get_discover_index(
+        &self,
+        genre_ids: Option<Vec<u64>>,
+    ) -> Result<DiscoverResponse> {
+        let url = endpoints::build_url(paths::DISCOVER_INDEX);
+        let mut query: Vec<(&str, String)> = vec![];
+
+        // Add genre_ids as comma-separated list if provided
+        if let Some(gids) = genre_ids {
+            if !gids.is_empty() {
+                let ids_str = gids.iter().map(|id| id.to_string()).collect::<Vec<_>>().join(",");
+                query.push(("genre_ids", ids_str));
+            }
+        }
+
+        let http_response = self
+            .http
+            .get(&url)
+            .headers(self.authenticated_headers().await?)
+            .query(&query)
+            .send()
+            .await?;
+        log::info!("[API] get_discover_index status={}", http_response.status());
+        let response: Value = http_response.json().await?;
+
+        // Debug: log the response structure
+        if let Some(obj) = response.as_object() {
+            log::info!("Discover API response keys: {:?}", obj.keys().collect::<Vec<_>>());
+            if let Some(err) = obj.get("message") {
+                log::error!("Discover API error: {:?}", err);
+            }
+            if let Some(code) = obj.get("code") {
+                log::error!("Discover API error code: {:?}", code);
+            }
+        }
+
+        Ok(serde_json::from_value(response)?)
+    }
+
+    /// Get discover albums from a specific browse endpoint (newReleases, idealDiscography, mostStreamed)
+    pub async fn get_discover_albums(
+        &self,
+        endpoint: &str,
+        genre_ids: Option<Vec<u64>>,
+        offset: u32,
+        limit: u32,
+    ) -> Result<DiscoverData<DiscoverAlbum>> {
+        let url = endpoints::build_url(endpoint);
+        let mut query: Vec<(&str, String)> = vec![];
+
+        if let Some(gids) = genre_ids {
+            if !gids.is_empty() {
+                let ids_str = gids.iter().map(|id| id.to_string()).collect::<Vec<_>>().join(",");
+                query.push(("genre_ids", ids_str));
+            }
+        }
+
+        query.push(("offset", offset.to_string()));
+        query.push(("limit", limit.to_string()));
+
+        let http_response = self
+            .http
+            .get(&url)
+            .headers(self.authenticated_headers().await?)
+            .query(&query)
+            .send()
+            .await?;
+        log::info!("[API] get_discover_albums({}) status={}", endpoint, http_response.status());
+        let response: serde_json::Value = http_response.json().await?;
+
+        Ok(serde_json::from_value(response)?)
+    }
+
+    /// Get discover playlists with optional tag and genre filters
+    /// Example: tags=label, genre_ids=112,119
+    pub async fn get_discover_playlists(
+        &self,
+        tag: Option<String>,
+        genre_ids: Option<Vec<u64>>,
+        limit: Option<u32>,
+        offset: Option<u32>,
+    ) -> Result<DiscoverPlaylistsResponse> {
+        let url = endpoints::build_url(paths::DISCOVER_PLAYLISTS);
+        let mut query: Vec<(&str, String)> = vec![];
+
+        // Add tag filter if provided (e.g., "label", "partner")
+        if let Some(ref t) = tag {
+            query.push(("tags", t.clone()));
+        }
+
+        // Add genre_ids as comma-separated list if provided
+        if let Some(gids) = genre_ids {
+            if !gids.is_empty() {
+                let ids_str = gids.iter().map(|id| id.to_string()).collect::<Vec<_>>().join(",");
+                query.push(("genre_ids", ids_str));
+            }
+        }
+
+        // Add limit (default 20)
+        let lim = limit.unwrap_or(20);
+        query.push(("limit", lim.to_string()));
+
+        // Add offset (default 0)
+        let off = offset.unwrap_or(0);
+        query.push(("offset", off.to_string()));
+
+        log::debug!("[API] get_discover_playlists URL: {} query: {:?}", url, query);
+
+        // First get raw JSON to debug structure
+        let raw_response: serde_json::Value = self
+            .http
+            .get(&url)
+            .headers(self.authenticated_headers().await?)
+            .query(&query)
+            .send()
+            .await?
+            .json()
+            .await?;
+
+        log::debug!("[API] get_discover_playlists raw response keys: {:?}", raw_response.as_object().map(|o| o.keys().collect::<Vec<_>>()));
+
+        // Try to parse as expected structure
+        let response: DiscoverPlaylistsResponse = serde_json::from_value(raw_response.clone())
+            .map_err(|e| {
+                log::error!("[API] Failed to parse discover playlists response: {}", e);
+                log::error!("[API] Raw response: {}", serde_json::to_string_pretty(&raw_response).unwrap_or_default());
+                e
+            })?;
+
+        log::debug!("[API] get_discover_playlists response: {} playlists", response.items.len());
+
+        Ok(response)
+    }
+
+    /// Get playlist tags with localized names
+    pub async fn get_playlist_tags(&self) -> Result<Vec<PlaylistTag>> {
+        let url = endpoints::build_url(paths::PLAYLIST_GET_TAGS);
+
+        let http_response = self
+            .http
+            .get(&url)
+            .headers(self.authenticated_headers().await?)
+            .send()
+            .await?;
+        log::info!("[API] get_playlist_tags status={}", http_response.status());
+
+        let raw: PlaylistTagsResponse = http_response.json().await?;
+
+        // Get current locale (e.g., "en", "es", "fr", "de")
+        let locale = self.locale().await;
+        let lang = locale.split('-').next().unwrap_or("en");
+
+        // Convert raw tags to PlaylistTag with localized name
+        let tags: Vec<PlaylistTag> = raw
+            .tags
+            .into_iter()
+            .filter(|tag| tag.is_discover.as_deref() == Some("true"))
+            .filter_map(|tag| {
+                // Parse name_json to get localized name
+                let name_map: serde_json::Value =
+                    serde_json::from_str(&tag.name_json).ok()?;
+                let name = name_map
+                    .get(lang)
+                    .or_else(|| name_map.get("en"))
+                    .and_then(|v| v.as_str())
+                    .map(|s| s.to_string())?;
+                let id = tag.featured_tag_id
+                    .as_ref()
+                    .and_then(|s| s.parse::<u64>().ok())
+                    .unwrap_or(0);
+                Some(PlaylistTag { id, slug: tag.slug, name })
+            })
+            .collect();
+
+        log::debug!("[API] get_playlist_tags: {} tags", tags.len());
+        Ok(tags)
+    }
+
+    /// Get track by ID
+    pub async fn get_track(&self, track_id: u64) -> Result<Track> {
+        let url = endpoints::build_url(paths::TRACK_GET);
+        let http_response = self
+            .http
+            .get(&url)
+            .headers(self.api_headers().await?)
+            .query(&[("track_id", track_id.to_string())])
+            .send()
+            .await?;
+        let status = http_response.status();
+        log::debug!("[API] get_track({}) status={}", track_id, status);
+
+        if status == StatusCode::NOT_FOUND {
+            log::warn!("[API] get_track({}) returned 404 — track no longer available", track_id);
+            return Err(ApiError::TrackUnavailable(track_id));
+        }
+        if !status.is_success() {
+            log::error!("[API] get_track({}) unexpected status={}", track_id, status);
+            return Err(ApiError::ApiResponse(format!("get_track({}) status {}", track_id, status)));
+        }
+
+        let response: Value = http_response.json().await?;
+        Ok(serde_json::from_value(response)?)
+    }
+
+    /// Get artist by ID (basic info only - no albums, faster response)
+    pub async fn get_artist_basic(&self, artist_id: u64) -> Result<Artist> {
+        let url = endpoints::build_url(paths::ARTIST_GET);
+        let locale = self.locale().await;
+        let query = vec![
+            ("artist_id", artist_id.to_string()),
+            ("lang", locale),
+            // No "extra" parameter = only basic info (id, name, image)
+        ];
+
+        let http_response = self
+            .http
+            .get(&url)
+            .headers(self.api_headers().await?)
+            .query(&query)
+            .send()
+            .await?;
+        log::debug!("[API] get_artist_basic({}) status={}", artist_id, http_response.status());
+        let response: Value = http_response.json().await?;
+
+        Ok(serde_json::from_value(response)?)
+    }
+
+    /// Get artist by ID
+    pub async fn get_artist(
+        &self,
+        artist_id: u64,
+        with_albums: bool,
+    ) -> Result<Artist> {
+        self.get_artist_with_pagination(artist_id, with_albums, None, None).await
+    }
+
+    /// Get artist detail by ID with albums, playlists, and appears-on tracks
+    pub async fn get_artist_detail(
+        &self,
+        artist_id: u64,
+        limit: Option<u32>,
+        offset: Option<u32>,
+    ) -> Result<Artist> {
+        let url = endpoints::build_url(paths::ARTIST_GET);
+        let locale = self.locale().await;
+        let mut query = vec![
+            ("artist_id", artist_id.to_string()),
+            ("extra", "albums,tracks_appears_on,playlists".to_string()),
+            ("lang", locale),
+        ];
+        if let Some(l) = limit {
+            query.push(("limit", l.to_string()));
+        }
+        if let Some(o) = offset {
+            query.push(("offset", o.to_string()));
+        }
+
+        let http_response = self
+            .http
+            .get(&url)
+            .headers(self.api_headers().await?)
+            .query(&query)
+            .send()
+            .await?;
+        log::debug!("[API] get_artist_detail({}) status={}", artist_id, http_response.status());
+        let response: Value = http_response.json().await?;
+
+        Ok(serde_json::from_value(response)?)
+    }
+
+    /// Get artist by ID with album pagination
+    pub async fn get_artist_with_pagination(
+        &self,
+        artist_id: u64,
+        with_albums: bool,
+        limit: Option<u32>,
+        offset: Option<u32>,
+    ) -> Result<Artist> {
+        self.get_artist_with_pagination_and_locale(artist_id, with_albums, limit, offset, None).await
+    }
+
+    /// Get artist by ID with album pagination and optional locale override
+    /// Use locale_override to force a specific language (e.g., "en" for genre checking)
+    pub async fn get_artist_with_pagination_and_locale(
+        &self,
+        artist_id: u64,
+        with_albums: bool,
+        limit: Option<u32>,
+        offset: Option<u32>,
+        locale_override: Option<&str>,
+    ) -> Result<Artist> {
+        let url = endpoints::build_url(paths::ARTIST_GET);
+        let locale = match locale_override {
+            Some(l) => l.to_string(),
+            None => self.locale().await,
+        };
+        let mut query = vec![
+            ("artist_id", artist_id.to_string()),
+            ("lang", locale),
+        ];
+        if with_albums {
+            query.push(("extra", "albums".to_string()));
+        }
+        if let Some(l) = limit {
+            query.push(("limit", l.to_string()));
+        }
+        if let Some(o) = offset {
+            query.push(("offset", o.to_string()));
+        }
+
+        let http_response = self
+            .http
+            .get(&url)
+            .headers(self.api_headers().await?)
+            .query(&query)
+            .send()
+            .await?;
+        log::debug!("[API] get_artist({}, albums={}) status={}", artist_id, with_albums, http_response.status());
+        let response: Value = http_response.json().await?;
+
+        Ok(serde_json::from_value(response)?)
+    }
+
+    /// Get playlist metadata + ordered track IDs (lightweight, no full Track objects).
+    /// Uses `playlist/get?extra=track_ids` which returns the playlist with a flat
+    /// array of track IDs instead of nested Track objects.
+    pub async fn get_playlist_track_ids(&self, playlist_id: u64) -> Result<PlaylistWithTrackIds> {
+        let url = endpoints::build_url(paths::PLAYLIST_GET);
+        let http_response = self
+            .http
+            .get(&url)
+            .headers(self.api_headers().await?)
+            .query(&[
+                ("playlist_id", playlist_id.to_string()),
+                ("extra", "track_ids".to_string()),
+            ])
+            .send()
+            .await?;
+        log::debug!("[API] get_playlist_track_ids({}) status={}", playlist_id, http_response.status());
+        let response: Value = http_response.json().await?;
+        let result: PlaylistWithTrackIds = serde_json::from_value(response)?;
+        log::info!(
+            "[API] get_playlist_track_ids({}) — {} track IDs",
+            playlist_id,
+            result.track_ids.len()
+        );
+        Ok(result)
+    }
+
+    /// Fetch full Track objects for a batch of track IDs (max 50 per call).
+    /// Uses the `track/getList` endpoint.
+    ///
+    /// Tries multiple API call strategies:
+    /// POST to track/getList with JSON body {"tracks_id": [...]}
+    /// Returns full Track objects for the given IDs (max 50 per call).
+    pub async fn get_tracks_batch(&self, track_ids: &[u64]) -> Result<Vec<Track>> {
+        let url = endpoints::build_url(paths::TRACK_GET_LIST);
+        let headers = self.api_headers().await?;
+
+        let body = serde_json::json!({ "tracks_id": track_ids });
+        log::debug!("[API] get_tracks_batch POST ({} IDs)", track_ids.len());
+
+        let http_response = self
+            .http
+            .post(&url)
+            .headers(headers)
+            .json(&body)
+            .send()
+            .await?;
+
+        let status = http_response.status();
+        log::debug!("[API] get_tracks_batch POST status={}", status);
+
+        let value: Value = http_response.json().await?;
+
+        // Response: { "tracks": { "total": N, "items": [...] } }
+        let items = value
+            .get("tracks")
+            .and_then(|t| t.get("items"))
+            .ok_or_else(|| {
+                let preview = serde_json::to_string(&value)
+                    .unwrap_or_default()
+                    .chars()
+                    .take(500)
+                    .collect::<String>();
+                ApiError::ApiResponse(format!(
+                    "Missing tracks.items in getList response: {}",
+                    preview
+                ))
+            })?;
+
+        let tracks: Vec<Track> = serde_json::from_value(items.clone())?;
+        log::debug!("[API] get_tracks_batch returned {} tracks", tracks.len());
+        Ok(tracks)
+    }
+
+    /// Get playlist by ID (paginates automatically to fetch all tracks)
+    ///
+    /// After the first page, remaining pages are fetched concurrently
+    /// since we know the total track count from the first response.
+    pub async fn get_playlist(&self, playlist_id: u64) -> Result<Playlist> {
+        let url = endpoints::build_url(paths::PLAYLIST_GET);
+        const PAGE_SIZE: u32 = 500;
+
+        let start = std::time::Instant::now();
+
+        // First page — gives us metadata + total track count
+        let http_response = self
+            .http
+            .get(&url)
+            .headers(self.api_headers().await?)
+            .query(&[
+                ("playlist_id", playlist_id.to_string()),
+                ("limit", PAGE_SIZE.to_string()),
+                ("offset", "0".to_string()),
+                ("extra", "tracks".to_string()),
+            ])
+            .send()
+            .await?;
+        log::debug!("[API] get_playlist({}) status={}", playlist_id, http_response.status());
+        let response: Value = http_response.json().await?;
+        let mut playlist: Playlist = serde_json::from_value(response)?;
+
+        // Fetch remaining pages concurrently
+        if let Some(ref mut container) = playlist.tracks {
+            let total = container.total;
+            let fetched = container.items.len() as u32;
+
+            if fetched < total {
+                // Build all remaining page offsets
+                let offsets: Vec<u32> = (fetched..total).step_by(PAGE_SIZE as usize).collect();
+                log::debug!(
+                    "[API] get_playlist({}) fetching {} remaining pages concurrently ({}/{})",
+                    playlist_id, offsets.len(), fetched, total
+                );
+
+                // Prepare headers once for all concurrent requests
+                let headers = self.api_headers().await?;
+
+                // Launch all page requests concurrently
+                let futures: Vec<_> = offsets.iter().map(|&offset| {
+                    let http = &self.http;
+                    let url = &url;
+                    let headers = headers.clone();
+                    let pid = playlist_id.to_string();
+                    let limit = PAGE_SIZE.to_string();
+                    let offset_str = offset.to_string();
+                    async move {
+                        let resp = http
+                            .get(url)
+                            .headers(headers)
+                            .query(&[
+                                ("playlist_id", pid.as_str()),
+                                ("limit", limit.as_str()),
+                                ("offset", offset_str.as_str()),
+                                ("extra", "tracks"),
+                            ])
+                            .send()
+                            .await?;
+                        let value: Value = resp.json().await?;
+                        let page: Playlist = serde_json::from_value(value)?;
+                        Ok::<_, anyhow::Error>((offset, page))
+                    }
+                }).collect();
+
+                let results = futures_util::future::join_all(futures).await;
+
+                // Collect results sorted by offset to maintain track order
+                let mut pages: Vec<(u32, Playlist)> = Vec::new();
+                for result in results {
+                    match result {
+                        Ok(page) => pages.push(page),
+                        Err(e) => {
+                            log::warn!("[API] get_playlist({}) page fetch failed: {}", playlist_id, e);
+                            // Continue with what we have
+                        }
+                    }
+                }
+                pages.sort_by_key(|(offset, _)| *offset);
+
+                // Append tracks in order
+                for (_, page_playlist) in pages {
+                    if let Some(page_tracks) = page_playlist.tracks {
+                        if !page_tracks.items.is_empty() {
+                            container.items.extend(page_tracks.items);
+                        }
+                    }
+                }
+            }
+        }
+
+        let elapsed = start.elapsed();
+        log::info!(
+            "[API] get_playlist({}) complete: {} tracks in {:.2}s",
+            playlist_id,
+            playlist.tracks.as_ref().map(|t| t.items.len()).unwrap_or(0),
+            elapsed.as_secs_f64()
+        );
+
+        Ok(playlist)
+    }
+
+    /// Get label by ID with albums
+    pub async fn get_label(&self, label_id: u64, limit: u32, offset: u32) -> Result<LabelDetail> {
+        let url = endpoints::build_url(paths::LABEL_GET);
+        let locale = self.locale().await;
+
+        let http_response = self
+            .http
+            .get(&url)
+            .headers(self.api_headers().await?)
+            .query(&[
+                ("label_id", label_id.to_string()),
+                ("extra", "albums".to_string()),
+                ("limit", limit.to_string()),
+                ("offset", offset.to_string()),
+                ("lang", locale),
+            ])
+            .send()
+            .await?;
+        log::debug!("[API] get_label({}) status={}", label_id, http_response.status());
+        let response: Value = http_response.json().await?;
+
+        Ok(serde_json::from_value(response)?)
+    }
+
+    // === Authenticated endpoints ===
+
+    /// Get stream URL for a track (requires auth + signature)
+    pub async fn get_stream_url(&self, track_id: u64, quality: Quality) -> Result<StreamUrl> {
+        log::info!("Getting stream URL for track {} with quality {:?}", track_id, quality);
+        let url = endpoints::build_url(paths::TRACK_GET_FILE_URL);
+        let timestamp = get_timestamp();
+        log::debug!("Getting secret for signing...");
+        let secret = self.secret().await?;
+        log::debug!("Secret obtained, signing request...");
+        let signature = sign_get_file_url(track_id, quality.id(), timestamp, &secret);
+
+        log::debug!("Sending stream URL request...");
+        let response = self
+            .http
+            .get(&url)
+            .headers(self.authenticated_headers().await?)
+            .query(&[
+                ("track_id", track_id.to_string()),
+                ("format_id", quality.id().to_string()),
+                ("intent", "stream".to_string()),
+                ("request_ts", timestamp.to_string()),
+                ("request_sig", signature),
+            ])
+            .send()
+            .await?;
+
+        log::info!("Stream URL response status: {}", response.status());
+        match response.status() {
+            StatusCode::OK => {
+                let json: Value = response.json().await?;
+                log::debug!("Stream URL response JSON keys: {:?}", json.as_object().map(|o| o.keys().collect::<Vec<_>>()));
+
+                // Check for restrictions
+                let restrictions: Vec<StreamRestriction> = json
+                    .get("restrictions")
+                    .and_then(|v| serde_json::from_value(v.clone()).ok())
+                    .unwrap_or_default();
+
+// Validate that we got an actual URL (track may be unavailable)
+                let url = json["url"].as_str().unwrap_or("").to_string();
+                if url.is_empty() {
+                    // Log the restriction codes for debugging
+                    let restriction_codes: Vec<&str> = restrictions.iter().map(|r| r.code.as_str()).collect();
+                    log::warn!("Stream URL missing for track {} - restrictions: {:?}", track_id, restriction_codes);
+                    return Err(ApiError::TrackUnavailable(track_id));
+                }
+
+                Ok(StreamUrl {
+                    url,
+                    format_id: json["format_id"].as_u64().unwrap_or(0) as u32,
+                    mime_type: json["mime_type"].as_str().unwrap_or("").to_string(),
+                    sampling_rate: json["sampling_rate"].as_f64().unwrap_or(0.0),
+                    bit_depth: json["bit_depth"].as_u64().map(|v| v as u32),
+                    track_id,
+                    restrictions,
+                })
+            }
+            StatusCode::BAD_REQUEST => Err(ApiError::InvalidAppSecret),
+            status => Err(ApiError::ApiResponse(format!("Unexpected status: {}", status))),
+        }
+    }
+
+    /// Get stream URL with quality fallback
+    pub async fn get_stream_url_with_fallback(
+        &self,
+        track_id: u64,
+        preferred: Quality,
+    ) -> Result<StreamUrl> {
+        log::info!("Getting stream URL with fallback for track {}, preferred quality: {:?}", track_id, preferred);
+        let qualities = Quality::fallback_order();
+        let start_idx = qualities.iter().position(|q| *q == preferred).unwrap_or(0);
+
+        let mut track_unavailable = false;
+
+        for quality in &qualities[start_idx..] {
+            log::info!("Trying quality: {:?}", quality);
+            match self.get_stream_url(track_id, *quality).await {
+                Ok(url) if !url.has_restrictions() => {
+                    log::info!(
+                        "Got stream URL - requested format_id={}, got format_id={}, sample_rate={}Hz, bit_depth={:?}",
+                        quality.id(),
+                        url.format_id,
+                        url.sampling_rate,
+                        url.bit_depth
+                    );
+                    return Ok(url);
+                },
+                Ok(_) => {
+                    log::info!("Quality {:?} has restrictions, trying next", quality);
+                    continue;
+                },
+                Err(ApiError::InvalidAppSecret) => {
+                    log::error!("Invalid app secret");
+                    return Err(ApiError::InvalidAppSecret);
+                },
+                Err(ApiError::TrackUnavailable(_)) => {
+                    // Track is completely unavailable on Qobuz
+                    track_unavailable = true;
+                    continue;
+                },
+                Err(e) => {
+                    log::warn!("Quality {:?} failed: {}, trying next", quality, e);
+                    continue;
+                },
+            }
+        }
+
+        // If all quality levels reported track unavailable, return that specific error
+        if track_unavailable {
+            log::error!("Track {} is no longer available on Qobuz", track_id);
+            return Err(ApiError::TrackUnavailable(track_id));
+        }
+
+        log::error!("No quality available for track {}", track_id);
+        Err(ApiError::NoQualityAvailable)
+    }
+
+    /// Get user favorites (requires auth + signature)
+    pub async fn get_favorites(&self, fav_type: &str, limit: u32, offset: u32) -> Result<Value> {
+        let url = endpoints::build_url(paths::FAVORITE_GET_USER_FAVORITES);
+        let timestamp = get_timestamp();
+        let secret = self.secret().await?;
+        let signature = sign_get_favorites(timestamp, &secret);
+
+        let http_response = self
+            .http
+            .get(&url)
+            .headers(self.authenticated_headers().await?)
+            .query(&[
+                ("type", fav_type),
+                ("limit", &limit.to_string()),
+                ("offset", &offset.to_string()),
+                ("request_ts", &timestamp.to_string()),
+                ("request_sig", &signature),
+            ])
+            .send()
+            .await?;
+        log::debug!("[API] get_favorites({}) status={}", fav_type, http_response.status());
+        let response: Value = http_response.json().await?;
+
+        Ok(response)
+    }
+
+    /// Get user's playlists
+    pub async fn get_user_playlists(&self) -> Result<Vec<Playlist>> {
+        let url = endpoints::build_url(paths::PLAYLIST_GET_USER_PLAYLISTS);
+        let http_response = self
+            .http
+            .get(&url)
+            .headers(self.authenticated_headers().await?)
+            .send()
+            .await?;
+        log::debug!("[API] get_user_playlists status={}", http_response.status());
+        let response: Value = http_response.json().await?;
+
+        let playlists = response
+            .get("playlists")
+            .and_then(|p| p.get("items"))
+            .ok_or_else(|| ApiError::ApiResponse("No playlists in response".to_string()))?;
+
+        Ok(serde_json::from_value(playlists.clone())?)
+    }
+
+    /// Search playlists
+    pub async fn search_playlists(&self, query: &str, limit: u32, offset: u32) -> Result<SearchResultsPage<Playlist>> {
+        let url = endpoints::build_url(paths::PLAYLIST_SEARCH);
+        let http_response = self
+            .http
+            .get(&url)
+            .headers(self.api_headers().await?)
+            .query(&[
+                ("query", query),
+                ("limit", &limit.to_string()),
+                ("offset", &offset.to_string()),
+            ])
+            .send()
+            .await?;
+        log::debug!("[API] search_playlists status={}", http_response.status());
+        let response: Value = http_response.json().await?;
+
+        let playlists = response
+            .get("playlists")
+            .ok_or_else(|| ApiError::ApiResponse("No playlists in response".to_string()))?;
+
+        Ok(serde_json::from_value(playlists.clone())?)
+    }
+
+    /// Create a new playlist
+    pub async fn create_playlist(&self, name: &str, description: Option<&str>, is_public: bool) -> Result<Playlist> {
+        let url = endpoints::build_url(paths::PLAYLIST_CREATE);
+
+        let mut params = vec![
+            ("name", name.to_string()),
+            ("is_public", is_public.to_string()),
+        ];
+        if let Some(desc) = description {
+            params.push(("description", desc.to_string()));
+        }
+
+        let response: Playlist = self
+            .http
+            .get(&url)
+            .headers(self.authenticated_headers().await?)
+            .query(&params)
+            .send()
+            .await?
+            .json()
+            .await?;
+
+        Ok(response)
+    }
+
+    /// Delete a playlist
+    pub async fn delete_playlist(&self, playlist_id: u64) -> Result<()> {
+        let url = endpoints::build_url(paths::PLAYLIST_DELETE);
+
+        self.http
+            .get(&url)
+            .headers(self.authenticated_headers().await?)
+            .query(&[("playlist_id", playlist_id.to_string())])
+            .send()
+            .await?;
+
+        Ok(())
+    }
+
+    /// Add tracks to a playlist
+    pub async fn add_tracks_to_playlist(&self, playlist_id: u64, track_ids: &[u64]) -> Result<()> {
+        let url = endpoints::build_url(paths::PLAYLIST_ADD_TRACKS);
+        let track_ids_str = track_ids.iter().map(|id| id.to_string()).collect::<Vec<_>>().join(",");
+
+        self.http
+            .get(&url)
+            .headers(self.authenticated_headers().await?)
+            .query(&[
+                ("playlist_id", playlist_id.to_string()),
+                ("track_ids", track_ids_str),
+            ])
+            .send()
+            .await?;
+
+        Ok(())
+    }
+
+    /// Remove tracks from a playlist
+    pub async fn remove_tracks_from_playlist(&self, playlist_id: u64, playlist_track_ids: &[u64]) -> Result<()> {
+        let url = endpoints::build_url(paths::PLAYLIST_DELETE_TRACKS);
+        let track_ids_str = playlist_track_ids.iter().map(|id| id.to_string()).collect::<Vec<_>>().join(",");
+
+        self.http
+            .get(&url)
+            .headers(self.authenticated_headers().await?)
+            .query(&[
+                ("playlist_id", playlist_id.to_string()),
+                ("playlist_track_ids", track_ids_str),
+            ])
+            .send()
+            .await?;
+
+        Ok(())
+    }
+
+    /// Update playlist metadata
+    pub async fn update_playlist(&self, playlist_id: u64, name: Option<&str>, description: Option<&str>, is_public: Option<bool>) -> Result<Playlist> {
+        let url = endpoints::build_url(paths::PLAYLIST_UPDATE);
+
+        let mut params = vec![("playlist_id", playlist_id.to_string())];
+        if let Some(n) = name {
+            params.push(("name", n.to_string()));
+        }
+        if let Some(d) = description {
+            params.push(("description", d.to_string()));
+        }
+        if let Some(p) = is_public {
+            params.push(("is_public", p.to_string()));
+        }
+
+        let response: Playlist = self
+            .http
+            .get(&url)
+            .headers(self.authenticated_headers().await?)
+            .query(&params)
+            .send()
+            .await?
+            .json()
+            .await?;
+
+        Ok(response)
+    }
+
+    /// Add item to favorites
+    pub async fn add_favorite(&self, fav_type: &str, item_id: &str) -> Result<()> {
+        let url = endpoints::build_url(paths::FAVORITE_CREATE);
+        let type_key = format!("{}_ids", fav_type); // album_ids, track_ids, artist_ids
+
+        let response = self
+            .http
+            .get(&url)
+            .headers(self.authenticated_headers().await?)
+            .query(&[(&type_key, item_id)])
+            .send()
+            .await?;
+
+        if response.status().is_success() {
+            Ok(())
+        } else {
+            Err(ApiError::ApiResponse(format!("Failed to add favorite: {}", response.status())))
+        }
+    }
+
+    /// Remove item from favorites
+    pub async fn remove_favorite(&self, fav_type: &str, item_id: &str) -> Result<()> {
+        let url = endpoints::build_url(paths::FAVORITE_DELETE);
+        let type_key = format!("{}_ids", fav_type);
+
+        let response = self
+            .http
+            .get(&url)
+            .headers(self.authenticated_headers().await?)
+            .query(&[(&type_key, item_id)])
+            .send()
+            .await?;
+
+        if response.status().is_success() {
+            Ok(())
+        } else {
+            Err(ApiError::ApiResponse(format!("Failed to remove favorite: {}", response.status())))
+        }
+    }
+
+    // ============ Artist Page Endpoints ============
+
+    /// Get artist page (aggregated: bio, top tracks, releases, similar, playlists)
+    pub async fn get_artist_page(
+        &self,
+        artist_id: u64,
+        sort: Option<&str>,
+    ) -> Result<PageArtistResponse> {
+        let url = endpoints::build_url(paths::ARTIST_PAGE);
+        let mut query = vec![
+            ("artist_id", artist_id.to_string()),
+        ];
+        if let Some(s) = sort {
+            query.push(("sort", s.to_string()));
+        }
+
+        log::debug!("[API] get_artist_page({}) sort={:?}", artist_id, sort);
+        let response: serde_json::Value = self
+            .http
+            .get(&url)
+            .headers(self.api_headers().await?)
+            .query(&query)
+            .send()
+            .await?
+            .json()
+            .await?;
+
+        Ok(serde_json::from_value(response)?)
+    }
+
+    /// Get artist releases grid (paginated by release_type)
+    pub async fn get_releases_grid(
+        &self,
+        artist_id: u64,
+        release_type: &str,
+        limit: u32,
+        offset: u32,
+        sort: Option<&str>,
+    ) -> Result<ReleasesGridResponse> {
+        let url = endpoints::build_url(paths::ARTIST_RELEASES_GRID);
+        let mut query = vec![
+            ("artist_id", artist_id.to_string()),
+            ("release_type", release_type.to_string()),
+            ("limit", limit.to_string()),
+            ("offset", offset.to_string()),
+        ];
+        if let Some(s) = sort {
+            query.push(("sort", s.to_string()));
+        }
+
+        log::debug!("[API] get_releases_grid({}) type={} limit={} offset={}", artist_id, release_type, limit, offset);
+        let response: serde_json::Value = self
+            .http
+            .get(&url)
+            .headers(self.api_headers().await?)
+            .query(&query)
+            .send()
+            .await?
+            .json()
+            .await?;
+
+        Ok(serde_json::from_value(response)?)
+    }
+}
+
+impl Default for QobuzClient {
+    fn default() -> Self {
+        Self::new().expect("Failed to create client")
+    }
+}
diff --git a/crates/qbz-qobuz/src/endpoints.rs b/crates/qbz-qobuz/src/endpoints.rs
new file mode 100644
index 000000000..796b41a48
--- /dev/null
+++ b/crates/qbz-qobuz/src/endpoints.rs
@@ -0,0 +1,68 @@
+//! API endpoint definitions
+
+pub const BASE_URL: &str = "https://www.qobuz.com/api.json/0.2";
+
+/// Endpoint paths
+pub mod paths {
+    // User
+    pub const USER_LOGIN: &str = "/user/login";
+
+    // Track
+    pub const TRACK_GET: &str = "/track/get";
+    pub const TRACK_GET_LIST: &str = "/track/getList";
+    pub const TRACK_SEARCH: &str = "/track/search";
+    pub const TRACK_GET_FILE_URL: &str = "/track/getFileUrl";
+
+    // Album
+    pub const ALBUM_GET: &str = "/album/get";
+    pub const ALBUM_SEARCH: &str = "/album/search";
+    pub const ALBUM_GET_FEATURED: &str = "/album/getFeatured";
+
+    // Artist
+    pub const ARTIST_GET: &str = "/artist/get";
+    pub const ARTIST_SEARCH: &str = "/artist/search";
+    pub const ARTIST_GET_SIMILAR: &str = "/artist/getSimilarArtists";
+    pub const ARTIST_PAGE: &str = "/artist/page";
+    pub const ARTIST_RELEASES_GRID: &str = "/artist/getReleasesGrid";
+    pub const ARTIST_RELEASES_LIST: &str = "/artist/getReleasesList";
+
+    // Playlist
+    pub const PLAYLIST_GET: &str = "/playlist/get";
+    pub const PLAYLIST_SEARCH: &str = "/playlist/search";
+    pub const PLAYLIST_GET_USER_PLAYLISTS: &str = "/playlist/getUserPlaylists";
+    pub const PLAYLIST_CREATE: &str = "/playlist/create";
+    pub const PLAYLIST_DELETE: &str = "/playlist/delete";
+    pub const PLAYLIST_ADD_TRACKS: &str = "/playlist/addTracks";
+    pub const PLAYLIST_DELETE_TRACKS: &str = "/playlist/deleteTracks";
+    pub const PLAYLIST_UPDATE: &str = "/playlist/update";
+    pub const PLAYLIST_GET_TAGS: &str = "/playlist/getTags";
+
+    // Favorites
+    pub const FAVORITE_GET_USER_FAVORITES: &str = "/favorite/getUserFavorites";
+    pub const FAVORITE_CREATE: &str = "/favorite/create";
+    pub const FAVORITE_DELETE: &str = "/favorite/delete";
+
+    // Label
+    pub const LABEL_GET: &str = "/label/get";
+
+    // Genre
+    pub const GENRE_LIST: &str = "/genre/list";
+
+    // Catalog (combined search)
+    pub const CATALOG_SEARCH: &str = "/catalog/search";
+
+    // Discover (home page content)
+    pub const DISCOVER_INDEX: &str = "/discover/index";
+    pub const DISCOVER_PLAYLISTS: &str = "/discover/playlists";
+    pub const DISCOVER_NEW_RELEASES: &str = "/discover/newReleases";
+    pub const DISCOVER_IDEAL_DISCOGRAPHY: &str = "/discover/idealDiscography";
+    pub const DISCOVER_MOST_STREAMED: &str = "/discover/mostStreamed";
+    pub const DISCOVER_QOBUZISSIMS: &str = "/discover/qobuzissims";
+    pub const DISCOVER_ALBUM_OF_THE_WEEK: &str = "/discover/albumOfTheWeek";
+    pub const DISCOVER_PRESS_AWARD: &str = "/discover/pressAward";
+}
+
+/// Build full URL for an endpoint
+pub fn build_url(endpoint: &str) -> String {
+    format!("{}{}", BASE_URL, endpoint)
+}
diff --git a/crates/qbz-qobuz/src/error.rs b/crates/qbz-qobuz/src/error.rs
new file mode 100644
index 000000000..c11a40368
--- /dev/null
+++ b/crates/qbz-qobuz/src/error.rs
@@ -0,0 +1,47 @@
+//! API error types
+
+use thiserror::Error;
+
+#[derive(Error, Debug)]
+pub enum ApiError {
+    #[error("Authentication failed: {0}")]
+    AuthenticationError(String),
+
+    #[error("Invalid app ID")]
+    InvalidAppId,
+
+    #[error("Invalid app secret")]
+    InvalidAppSecret,
+
+    #[error("Failed to extract bundle tokens: {0}")]
+    BundleExtractionError(String),
+
+    #[error("User is not eligible (no active subscription)")]
+    IneligibleUser,
+
+    #[error("Track is not streamable")]
+    NonStreamable,
+
+    #[error("Invalid quality format: {0}")]
+    InvalidQuality(u32),
+
+    #[error("No valid quality available for this track")]
+    NoQualityAvailable,
+
+    #[error("Track {0} is no longer available on Qobuz")]
+    TrackUnavailable(u64),
+
+    #[error("Network error: {0}")]
+    NetworkError(#[from] reqwest::Error),
+
+    #[error("JSON parsing error: {0}")]
+    ParseError(#[from] serde_json::Error),
+
+    #[error("API error: {0}")]
+    ApiResponse(String),
+
+    #[error("Rate limited, retry after {0} seconds")]
+    RateLimited(u64),
+}
+
+pub type Result<T> = std::result::Result<T, ApiError>;
diff --git a/crates/qbz-qobuz/src/lib.rs b/crates/qbz-qobuz/src/lib.rs
index 25bdaad2f..dad8bed95 100644
--- a/crates/qbz-qobuz/src/lib.rs
+++ b/crates/qbz-qobuz/src/lib.rs
@@ -5,18 +5,39 @@
 //! - Authentication and token management
 //! - Search, catalog browsing, streaming URLs
 //!
-//! The client handles:
-//! - Bundle token extraction
-//! - Request signing
-//! - Session management
+//! # Architecture
+//!
+//! ```text
+//! ┌─────────────────────────────────────────────────────────────┐
+//! │                     qbz-qobuz (Tier 1)                      │
+//! │  Qobuz API client, authentication, streaming URLs          │
+//! └─────────────────────────────────────────────────────────────┘
+//!                              ↑
+//!                      ┌───────┴───────┐
+//!                      │  qbz-models   │
+//!                      │   (Tier 0)    │
+//!                      └───────────────┘
+//! ```
+//!
+//! # Usage
+//!
+//! ```rust,ignore
+//! use qbz_qobuz::QobuzClient;
+//!
+//! let client = QobuzClient::new()?;
+//! client.init().await?;
+//! let session = client.login("email", "password").await?;
+//! let stream_url = client.get_stream_url(track_id, quality).await?;
+//! ```
 
-// TODO: Phase 4 - Copy API modules from qbz-nix
-// pub mod client;
-// pub mod auth;
-// pub mod endpoints;
-// pub mod bundle;
-// pub mod performers;
-// pub mod error;
+pub mod auth;
+pub mod bundle;
+pub mod client;
+pub mod endpoints;
+pub mod error;
+pub mod performers;
 
-// pub use client::QobuzClient;
-// pub use error::ApiError;
+// Re-export main types
+pub use client::QobuzClient;
+pub use error::{ApiError, Result};
+pub use bundle::BundleTokens;
diff --git a/crates/qbz-qobuz/src/performers.rs b/crates/qbz-qobuz/src/performers.rs
new file mode 100644
index 000000000..d1141dcfb
--- /dev/null
+++ b/crates/qbz-qobuz/src/performers.rs
@@ -0,0 +1,139 @@
+//! Performers string parsing utilities
+//!
+//! Qobuz provides performer credits as a formatted string like:
+//! "John Coltrane, Saxophone, MainArtist - McCoy Tyner, Piano - Jimmy Garrison, Double Bass"
+//!
+//! This module parses that string into structured data.
+
+use serde::{Deserialize, Serialize};
+
+/// A performer with their name and roles
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct Performer {
+    pub name: String,
+    pub roles: Vec<String>,
+}
+
+impl Performer {
+    pub fn new(name: String, roles: Vec<String>) -> Self {
+        Self { name, roles }
+    }
+}
+
+/// Parse a Qobuz performers string into structured data
+///
+/// Format: "Name, Role1, Role2 - Name, Role1 - Name, Role1, Role2"
+///
+/// # Examples
+///
+/// ```
+/// use crate::api::performers::parse_performers;
+///
+/// let performers = parse_performers("John Coltrane, Saxophone, MainArtist - McCoy Tyner, Piano");
+/// assert_eq!(performers.len(), 2);
+/// assert_eq!(performers[0].name, "John Coltrane");
+/// assert_eq!(performers[0].roles, vec!["Saxophone", "MainArtist"]);
+/// ```
+pub fn parse_performers(performers_str: &str) -> Vec<Performer> {
+    if performers_str.is_empty() {
+        return Vec::new();
+    }
+
+    performers_str
+        .split(" - ")
+        .filter_map(|segment| {
+            let segment = segment.trim();
+            if segment.is_empty() {
+                return None;
+            }
+
+            let parts: Vec<&str> = segment.split(", ").collect();
+            if parts.is_empty() {
+                return None;
+            }
+
+            let name = parts[0].trim().to_string();
+            if name.is_empty() {
+                return None;
+            }
+
+            let roles: Vec<String> = parts[1..]
+                .iter()
+                .map(|r| r.trim().to_string())
+                .filter(|r| !r.is_empty())
+                .collect();
+
+            Some(Performer::new(name, roles))
+        })
+        .collect()
+}
+
+/// Group performers by their roles
+///
+/// Returns a map where keys are role names and values are lists of performer names
+pub fn group_by_role(performers: &[Performer]) -> std::collections::HashMap<String, Vec<String>> {
+    let mut grouped: std::collections::HashMap<String, Vec<String>> = std::collections::HashMap::new();
+
+    for performer in performers {
+        for role in &performer.roles {
+            grouped
+                .entry(role.clone())
+                .or_default()
+                .push(performer.name.clone());
+        }
+    }
+
+    grouped
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_parse_single_performer() {
+        let result = parse_performers("John Coltrane, Saxophone");
+        assert_eq!(result.len(), 1);
+        assert_eq!(result[0].name, "John Coltrane");
+        assert_eq!(result[0].roles, vec!["Saxophone"]);
+    }
+
+    #[test]
+    fn test_parse_multiple_performers() {
+        let result = parse_performers(
+            "John Coltrane, Saxophone, MainArtist - McCoy Tyner, Piano - Elvin Jones, Drums",
+        );
+        assert_eq!(result.len(), 3);
+        assert_eq!(result[0].name, "John Coltrane");
+        assert_eq!(result[0].roles, vec!["Saxophone", "MainArtist"]);
+        assert_eq!(result[1].name, "McCoy Tyner");
+        assert_eq!(result[1].roles, vec!["Piano"]);
+        assert_eq!(result[2].name, "Elvin Jones");
+        assert_eq!(result[2].roles, vec!["Drums"]);
+    }
+
+    #[test]
+    fn test_parse_empty_string() {
+        let result = parse_performers("");
+        assert!(result.is_empty());
+    }
+
+    #[test]
+    fn test_parse_performer_no_roles() {
+        let result = parse_performers("John Coltrane");
+        assert_eq!(result.len(), 1);
+        assert_eq!(result[0].name, "John Coltrane");
+        assert!(result[0].roles.is_empty());
+    }
+
+    #[test]
+    fn test_group_by_role() {
+        let performers = vec![
+            Performer::new("John".to_string(), vec!["Saxophone".to_string()]),
+            Performer::new("Jane".to_string(), vec!["Saxophone".to_string(), "Vocals".to_string()]),
+        ];
+        let grouped = group_by_role(&performers);
+        assert_eq!(grouped.get("Saxophone").unwrap().len(), 2);
+        assert_eq!(grouped.get("Vocals").unwrap().len(), 1);
+    }
+}