qobuz-cli 0.0.1__py3-none-any.whl

qobuz_cli/__init__.py

@@ -0,0 +1,5 @@
+"""
+This is the main package for the qobuz-cli application.
+"""
+
+__version__ = "v0.0.1"

qobuz_cli/__main__.py

@@ -0,0 +1,48 @@
+"""
+Main entry point for the qobuz-cli application.
+This module handles top-level setup, exception handling, and CLI invocation.
+"""
+
+import asyncio
+import logging
+import os
+import sys
+
+import typer
+from rich.console import Console
+
+from qobuz_cli.cli.app import app
+from qobuz_cli.cli.formatters import format_error_with_suggestions
+from qobuz_cli.exceptions import QobuzCliError
+
+
+def main() -> None:
+    """Main entry point function."""
+    if os.name == "nt":
+        try:
+            sys.stdout.reconfigure(encoding="utf-8")
+            sys.stderr.reconfigure(encoding="utf-8")
+        except (TypeError, AttributeError):
+            pass
+
+    log = logging.getLogger("qobuz_cli")
+    console = Console()
+
+    try:
+        app()
+    except (typer.Exit, typer.Abort):
+        pass
+    except (KeyboardInterrupt, asyncio.CancelledError):
+        console.print("\n[yellow]⚠️  Operation cancelled by user.[/yellow]")
+        sys.exit(0)
+    except QobuzCliError as e:
+        console.print(f"\n{format_error_with_suggestions(e)}")
+        sys.exit(1)
+    except Exception as e:
+        console.print(f"\n{format_error_with_suggestions(e, {'type': 'Unexpected'})}")
+        log.debug("Full traceback:", exc_info=True)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

qobuz_cli/api/__init__.py

@@ -0,0 +1,11 @@
+"""
+Qobuz API Layer.
+
+This package handles all communication with the official Qobuz API.
+"""
+
+from .auth import QobuzAuthenticator
+from .client import QobuzAPIClient
+from .rate_limiter import AdaptiveRateLimiter
+
+__all__ = ["AdaptiveRateLimiter", "QobuzAPIClient", "QobuzAuthenticator"]

qobuz_cli/api/auth.py

@@ -0,0 +1,147 @@
+"""
+Handles authentication with the Qobuz API, including credential login
+and app secret validation.
+"""
+
+import asyncio
+import logging
+from typing import TYPE_CHECKING, Any
+
+import aiohttp
+
+from qobuz_cli.exceptions import (
+    AuthenticationError,
+    IneligibleAccountError,
+    InvalidAppSecretError,
+)
+
+if TYPE_CHECKING:
+    from .client import QobuzAPIClient
+
+log = logging.getLogger(__name__)
+
+
+class QobuzAuthenticator:
+    """
+    Manages the authentication flow for the Qobuz API client.
+    """
+
+    def __init__(self, api_client: "QobuzAPIClient"):
+        """
+        Initializes the authenticator.
+
+        Args:
+            api_client: A reference to the main QobuzAPIClient instance.
+        """
+        self._api_client = api_client
+        self._secrets_tested = False
+
+    async def authenticate_with_token(self, token: str) -> dict[str, Any]:
+        """
+        Authenticates the client using a pre-existing user token.
+
+        Args:
+            token: The user authentication token.
+
+        Returns:
+            The user information dictionary from the API.
+        """
+        log.info("Authenticating with token...")
+        self._api_client.user_auth_token = token
+        await self.configure_authentication()
+
+        try:
+            user_info = await self._api_client.api_call("user/get")
+            log.info(
+                "Successfully authenticated as: "
+                f"{user_info.get('email', 'Unknown User')}"
+            )
+
+            if not user_info.get("credential", {}).get("parameters"):
+                raise IneligibleAccountError(
+                    "This account is not eligible for streaming."
+                )
+            return user_info
+        except aiohttp.ClientResponseError as e:
+            if e.status == 401:
+                raise AuthenticationError(
+                    "The provided token is invalid or has expired."
+                ) from e
+            raise
+
+    async def authenticate_with_credentials(
+        self, email: str, password_md5: str
+    ) -> dict[str, Any]:
+        """
+        Authenticates using an email and an MD5-hashed password.
+
+        Args:
+            email: The user's email address.
+            password_md5: The user's password, hashed with MD5.
+
+        Returns:
+            The user information dictionary from the API.
+        """
+        log.info(f"Authenticating as: {email}")
+        await self.configure_authentication()
+
+        login_payload = {
+            "email": email,
+            "password": password_md5,
+            "app_id": self._api_client.app_id,
+        }
+
+        user_info = await self._api_client.api_call("user/login", **login_payload)
+
+        if not user_info.get("user", {}).get("credential", {}).get("parameters"):
+            raise IneligibleAccountError("This account is not eligible for streaming.")
+
+        self._api_client.user_auth_token = user_info["user_auth_token"]
+        return user_info
+
+    async def configure_authentication(self) -> None:
+        """
+        Finds and sets a valid app secret from the provided list.
+
+        Tests each secret against a known valid endpoint until one succeeds.
+        This is a crucial step before making authenticated API calls.
+        """
+        if self._api_client.app_secret:
+            return
+
+        log.debug(f"Testing {len(self._api_client.secrets)} potential app secrets...")
+
+        test_tasks = [
+            self._test_secret(secret) for secret in self._api_client.secrets if secret
+        ]
+        results = await asyncio.gather(*test_tasks)
+
+        for secret, is_valid in zip(self._api_client.secrets, results, strict=True):
+            if is_valid:
+                self._api_client.app_secret = secret
+                log.debug(f"Valid secret found: {secret[:8]}...")
+                return
+
+        raise InvalidAppSecretError(
+            "No valid app secrets found."
+            " Please run 'qobuz-cli init' to fetch new secrets."
+        )
+
+    async def _test_secret(self, secret: str) -> bool:
+        """
+        Tests if a single app secret is valid.
+
+        Args:
+            secret: The app secret to test.
+
+        Returns:
+            True if the secret is valid, False otherwise.
+        """
+        try:
+            # Use a known public and valid track ID for testing
+            await self._api_client.api_call(
+                "track/getFileUrl", id=5966783, fmt_id=5, sec=secret
+            )
+            return True
+        except (InvalidAppSecretError, aiohttp.ClientError):
+            return False

qobuz_cli/api/client.py

@@ -0,0 +1,259 @@
+"""
+Enhanced API client with compression for metadata and circuit breaker protection.
+"""
+
+import hashlib
+import logging
+import time
+from collections.abc import AsyncGenerator
+from typing import Any
+
+import aiohttp
+
+from qobuz_cli.exceptions import (
+    AuthenticationError,
+    InvalidAppIdError,
+    InvalidAppSecretError,
+    InvalidQualityError,
+)
+from qobuz_cli.utils.circuit_breaker import CircuitBreaker, CircuitBreakerError
+
+from .auth import QobuzAuthenticator
+from .rate_limiter import AdaptiveRateLimiter
+
+log = logging.getLogger(__name__)
+
+
+class QobuzAPIClient:
+    """
+    Optimized async client for the Qobuz JSON API (v0.2).
+
+    Features:
+    - Compression for JSON/metadata responses (not audio files)
+    - Circuit breaker for API resilience
+    - Adaptive rate limiting
+    - Connection pooling
+    """
+
+    BASE_URL = "https://www.qobuz.com/api.json/0.2/"
+
+    def __init__(self, app_id: str, secrets: list[str], max_workers: int = 8):
+        """
+        Initializes the API client.
+
+        Args:
+            app_id: 9-digit Qobuz application ID from the web player.
+            secrets: List of potential app secrets scraped from the web player.
+            max_workers: The number of concurrent workers, used to tune the
+            connection pool.
+        """
+        self.app_id: str = str(app_id)
+        self.secrets: list[str] = secrets
+        self.max_workers = max_workers
+
+        # State set by the authenticator
+        self.app_secret: str | None = None
+        self.user_auth_token: str | None = None
+
+        self._session: aiohttp.ClientSession | None = None
+        self._rate_limiter = AdaptiveRateLimiter()
+        self._authenticator = QobuzAuthenticator(self)
+
+        # Circuit breaker for API resilience
+        self._circuit_breaker = CircuitBreaker(
+            failure_threshold=5,
+            recovery_timeout=60,
+            success_threshold=2,
+        )
+
+    @property
+    def authenticator(self) -> QobuzAuthenticator:
+        """Provides access to the authentication helper."""
+        return self._authenticator
+
+    async def _initialize_session(self) -> None:
+        """Ensures an active aiohttp session is available with compression enabled."""
+        if self._session is None or self._session.closed:
+            connector = aiohttp.TCPConnector(
+                limit=self.max_workers * 2,
+                limit_per_host=self.max_workers,
+                ttl_dns_cache=300,
+                enable_cleanup_closed=True,
+            )
+            self._session = aiohttp.ClientSession(
+                connector=connector,
+                headers={
+                    "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:121.0)"
+                    " Gecko/20100101 Firefox/121.0",
+                    "X-App-Id": self.app_id,
+                    # Enable compression for JSON metadata responses
+                    "Accept-Encoding": "gzip, deflate, br",
+                },
+                timeout=aiohttp.ClientTimeout(total=60, connect=15, sock_read=30),
+            )
+
+    async def close(self) -> None:
+        """Gracefully closes the aiohttp session."""
+        if self._session and not self._session.closed:
+            await self._session.close()
+
+    def _prepare_get_file_url_params(
+        self, track_id: str, format_id: int, secret_override: str | None = None
+    ) -> dict[str, Any]:
+        """
+        Builds the signed parameter dictionary for the 'track/getFileUrl' endpoint.
+        """
+        if format_id not in (5, 6, 7, 27):
+            raise InvalidQualityError(
+                f"Invalid format_id: {format_id}. Must be one of 5, 6, 7, or 27."
+            )
+
+        unix_ts = int(time.time())
+        secret = secret_override or self.app_secret
+        if not secret:
+            raise InvalidAppSecretError(
+                "App secret has not been configured. Cannot sign request."
+            )
+
+        sig_str = (
+            f"trackgetFileUrlformat_id{format_id}intentstreamtrack_id"
+            f"{track_id}{unix_ts}{secret}"
+        )
+        request_sig = hashlib.md5(sig_str.encode("utf-8")).hexdigest()  # noqa: S324
+
+        return {
+            "request_ts": unix_ts,
+            "request_sig": request_sig,
+            "track_id": track_id,
+            "format_id": format_id,
+            "intent": "stream",
+        }
+
+    async def api_call(self, endpoint: str, **kwargs: Any) -> dict[str, Any]:
+        """
+        Makes an authenticated API call with rate limiting, retry logic, and
+        circuit breaker.
+
+        Compression is automatically applied to JSON responses by aiohttp when
+        the server sends Content-Encoding header.
+        """
+        await self._initialize_session()
+
+        # Check circuit breaker before making request
+        try:
+            async with self._circuit_breaker:
+                await self._rate_limiter.acquire()
+
+                params = kwargs.copy()
+
+                if endpoint == "track/getFileUrl":
+                    params = self._prepare_get_file_url_params(
+                        track_id=params.pop("id"),
+                        format_id=params.pop("fmt_id"),
+                        secret_override=params.pop("sec", None),
+                    )
+
+                if self.user_auth_token:
+                    params["user_auth_token"] = self.user_auth_token
+
+                async with self._session.get(
+                    self.BASE_URL + endpoint, params=params
+                ) as r:
+                    # Check if response was compressed (for logging)
+                    was_compressed = r.headers.get("Content-Encoding") in (
+                        "gzip",
+                        "deflate",
+                        "br",
+                    )
+                    if was_compressed:
+                        log.debug(
+                            f"API response for {endpoint} was compressed "
+                            f"({r.headers.get('Content-Encoding')})"
+                        )
+
+                    if r.status == 429:
+                        await self._rate_limiter.on_429()
+                        r.raise_for_status()
+
+                    if endpoint == "user/login":
+                        if r.status == 401:
+                            raise AuthenticationError("Invalid email or password.")
+                        if r.status == 400 and "Invalid application" in await r.text():
+                            raise InvalidAppIdError("The provided App ID is invalid.")
+
+                    if endpoint == "track/getFileUrl" and r.status == 400:
+                        raise InvalidAppSecretError(
+                            "The app secret is invalid or has expired."
+                        )
+
+                    r.raise_for_status()
+                    return await r.json()
+
+        except CircuitBreakerError as e:
+            log.error(f"[red]Circuit breaker is open for API calls: {e}[/red]")
+            raise
+        except Exception as e:
+            log.debug(f"API call to {endpoint} failed: {e}")
+            raise
+
+    async def _yield_paginated(
+        self, endpoint: str, item_key: str, **kwargs: Any
+    ) -> AsyncGenerator[dict[str, Any], None]:
+        """
+        Generator for handling paginated API endpoints.
+        """
+        offset = 0
+        limit = 200
+        total_items = 0
+
+        while True:
+            response = await self.api_call(
+                endpoint, offset=offset, limit=limit, **kwargs
+            )
+
+            if offset == 0:
+                total_items = response.get(f"{item_key}_count", 0)
+
+            items_in_response = len(response.get(item_key, {}).get("items", []))
+            if not items_in_response:
+                break
+
+            yield response
+
+            offset += items_in_response
+            if offset >= total_items:
+                break
+
+    # Public API Methods
+    async def fetch_album_metadata(self, album_id: str) -> dict[str, Any]:
+        return await self.api_call("album/get", album_id=album_id)
+
+    async def fetch_track_metadata(self, track_id: str) -> dict[str, Any]:
+        return await self.api_call("track/get", track_id=track_id)
+
+    async def fetch_track_url(self, track_id: str, format_id: int) -> dict[str, Any]:
+        return await self.api_call("track/getFileUrl", id=track_id, fmt_id=format_id)
+
+    def fetch_artist_discography(
+        self, artist_id: str
+    ) -> AsyncGenerator[dict[str, Any], None]:
+        return self._yield_paginated(
+            "artist/get", item_key="albums", artist_id=artist_id, extra="albums"
+        )
+
+    def fetch_playlist_tracks(
+        self, playlist_id: str
+    ) -> AsyncGenerator[dict[str, Any], None]:
+        return self._yield_paginated(
+            "playlist/get", item_key="tracks", playlist_id=playlist_id, extra="tracks"
+        )
+
+    def fetch_label_discography(
+        self, label_id: str
+    ) -> AsyncGenerator[dict[str, Any], None]:
+        return self._yield_paginated(
+            "label/get", item_key="albums", label_id=label_id, extra="albums"
+        )
+
+    async def search_tracks(self, query: str, limit: int = 50) -> dict[str, Any]:
+        return await self.api_call("track/search", query=query, limit=limit)

qobuz_cli/api/rate_limiter.py

@@ -0,0 +1,65 @@
+"""
+Provides an adaptive rate limiter to avoid 429 "Too Many Requests" errors from the API.
+"""
+
+import asyncio
+import logging
+import time
+
+log = logging.getLogger(__name__)
+
+
+class AdaptiveRateLimiter:
+    """
+    Dynamically adjusts call rate based on API feedback (429 errors).
+    """
+
+    def __init__(
+        self, initial_calls_per_second: float = 8.0, max_calls_per_second: float = 12.0
+    ):
+        """
+        Initializes the rate limiter.
+
+        Args:
+            initial_calls_per_second: The starting rate of calls per second.
+            max_calls_per_second: The maximum rate to recover to.
+        """
+        self._rate = initial_calls_per_second
+        self._max_rate = max_calls_per_second
+        self._min_interval = 1.0 / self._rate
+        self._last_call_time = 0.0
+        self._last_429_time = 0.0
+        self._lock = asyncio.Lock()
+
+    async def on_429(self) -> None:
+        """
+        Called when a 429 error is received. Halves the current request rate.
+        """
+        async with self._lock:
+            self._rate = max(
+                1.0, self._rate * 0.5
+            )  # Halve the rate, minimum 1 call/sec
+            self._min_interval = 1.0 / self._rate
+            self._last_429_time = time.monotonic()
+            log.warning(
+                f"[yellow]Rate limit hit. New rate: {self._rate:.1f} calls/s[/yellow]"
+            )
+
+    async def acquire(self) -> None:
+        """
+        Waits if necessary to respect the current rate limit before allowing a call
+        to proceed.
+        """
+        async with self._lock:
+            # Gradually recover the rate if no 429 errors have occurred recently
+            if time.monotonic() - self._last_429_time > 300:  # 5 minutes
+                self._rate = min(self._max_rate, self._rate * 1.005)  # Slow recovery
+                self._min_interval = 1.0 / self._rate
+
+            now = asyncio.get_event_loop().time()
+            time_since_last = now - self._last_call_time
+
+            if time_since_last < self._min_interval:
+                await asyncio.sleep(self._min_interval - time_since_last)
+
+            self._last_call_time = asyncio.get_event_loop().time()

qobuz_cli/cli/__init__.py

@@ -0,0 +1,6 @@
+"""
+Command-Line Interface Layer.
+
+This package defines the user-facing commands and their presentation using Typer
+and Rich.
+"""