pmomusic/pmoqobuz/src/lib.rs

//! # pmoqobuz - Client Qobuz pour PMOMusic
//!
//! Cette crate fournit un client Rust pour l'API Qobuz, inspiré de l'implémentation Python d'upmpdcli,
//! avec un système de cache en mémoire et une intégration avec les autres modules PMOMusic.
//!
//! ## Vue d'ensemble
//!
//! `pmoqobuz` permet d'accéder aux fonctionnalités de Qobuz :
//! - Authentification avec les credentials configurés
//! - Navigation dans le catalogue (albums, artistes, playlists, tracks)
//! - Recherche dans le catalogue
//! - Accès aux favoris de l'utilisateur
//! - Cache en mémoire pour minimiser les requêtes API
//! - Export des objets en format DIDL-Lite (via `pmodidl`)
//! - Cache des images d'albums (via `pmocovers`)
//!
//! ## Architecture
//!
//! La crate suit le pattern d'extension des autres crates PMO :
//! - `QobuzClient` : Client principal avec authentification et cache
//! - `models` : Structures de données (Album, Track, Artist, etc.)
//! - `api` : Couche d'accès à l'API REST Qobuz
//! - `cache` : Système de cache en mémoire avec TTL
//! - `didl` : Export des objets en format DIDL-Lite
//!
//! ## Structure des modules
//!
//! ```text
//! pmoqobuz/
//! ├── src/
//! │   ├── lib.rs              # Module principal (ce fichier)
//! │   ├── client.rs           # Client Qobuz principal
//! │   ├── models.rs           # Structures de données
//! │   ├── api/
//! │   │   ├── mod.rs          # API client
//! │   │   ├── auth.rs         # Authentification
//! │   │   ├── catalog.rs      # Accès au catalogue
//! │   │   └── user.rs         # API utilisateur (favoris)
//! │   ├── cache.rs            # Cache en mémoire
//! │   ├── didl.rs             # Export DIDL-Lite
//! │   └── error.rs            # Gestion des erreurs
//! ```
//!
//! ## Utilisation
//!
//! ### Exemple basique avec configuration automatique
//!
//! ```rust,no_run
//! use pmoqobuz::QobuzClient;
//!
//! #[tokio::main]
//! async fn main() -> anyhow::Result<()> {
//!     // Utilise automatiquement la config depuis pmoconfig
//!     let client = QobuzClient::from_config().await?;
//!
//!     // Rechercher des albums
//!     let results = client.search_albums("Miles Davis").await?;
//!     for album in results {
//!         println!("{} - {}", album.artist.name, album.title);
//!     }
//!
//!     Ok(())
//! }
//! ```
//!
//! ### Exemple avec credentials personnalisés
//!
//! ```rust,no_run
//! use pmoqobuz::QobuzClient;
//!
//! #[tokio::main]
//! async fn main() -> anyhow::Result<()> {
//!     let client = QobuzClient::new("user@example.com", "password").await?;
//!
//!     // Obtenir les albums favoris
//!     let favorites = client.get_favorite_albums().await?;
//!
//!     Ok(())
//! }
//! ```
//!
//! ### Export DIDL-Lite
//!
//! ```rust,no_run
//! use pmoqobuz::QobuzClient;
//!
//! #[tokio::main]
//! async fn main() -> anyhow::Result<()> {
//!     let client = QobuzClient::from_config().await?;
//!
//!     let album = client.get_album("12345").await?;
//!     let didl_container = album.to_didl_container("parent_id")?;
//!
//!     Ok(())
//! }
//! ```
//!
//! ## Cache
//!
//! Le client utilise un cache en mémoire avec TTL pour minimiser les requêtes à l'API Qobuz :
//! - Albums : 1 heure
//! - Tracks : 1 heure
//! - Artistes : 1 heure
//! - Playlists : 30 minutes
//! - Résultats de recherche : 15 minutes
//! - URLs de streaming : 5 minutes
//!
//! ## Intégration pmocovers
//!
//! Les images d'albums sont automatiquement cachées via `pmocovers` (feature `covers`) :
//!
//! ```rust,ignore
//! let album = client.get_album("12345").await?;
//! // L'image est automatiquement ajoutée au cache pmocovers
//! let cover_url = album.cover_url_cached; // URL vers le cache local
//! ```
//!
//! ## Formats audio supportés
//!
//! Qobuz propose plusieurs formats :
//! - Format 5 : MP3 320 kbps
//! - Format 6 : FLAC 16 bit / 44.1 kHz (CD Quality)
//! - Format 7 : FLAC 24 bit / jusqu'à 96 kHz (Hi-Res)
//! - Format 27 : FLAC 24 bit / jusqu'à 192 kHz (Hi-Res+)
//!
//! ## Gestion des erreurs
//!
//! La crate utilise `thiserror` pour définir des erreurs typées :
//!
//! ```rust,ignore
//! use pmoqobuz::{QobuzClient, QobuzError};
//!
//! match client.get_album("invalid").await {
//!     Ok(album) => println!("Album: {}", album.title),
//!     Err(QobuzError::NotFound) => println!("Album not found"),
//!     Err(QobuzError::Unauthorized) => println!("Authentication failed"),
//!     Err(e) => println!("Error: {}", e),
//! }
//! ```
//!
//! ## Voir aussi
//!
//! - [`pmodidl`] : Format DIDL-Lite
//! - [`pmocovers`] : Cache d'images
//! - [`pmoconfig`] : Configuration
//! - [`pmoserver`] : Serveur HTTP

pub mod api;
pub mod cache;
pub mod client;
pub mod didl;
pub mod error;
pub mod models;
pub mod source;

// Extension pmoserver (feature-gated)
#[cfg(feature = "pmoserver")]
pub mod api_rest;

#[cfg(feature = "pmoserver")]
pub mod pmoserver_ext;

#[cfg(feature = "pmoserver")]
mod pmoserver_impl;

pub use client::QobuzClient;
pub use error::{QobuzError, Result};
pub use models::{Album, Artist, AudioFormat, Genre, Playlist, SearchResult, Track};
pub use source::QobuzSource;

/// Ré-exporte les types DIDL pour faciliter l'utilisation
pub use didl::ToDIDL;

/// Ré-exporte le trait d'extension pmoserver
#[cfg(feature = "pmoserver")]
pub use pmoserver_ext::QobuzServerExt;