tag/src/provider.rs

use serde::{Deserialize, Serialize};

use crate::error::TagResult;

/// A reference to a release (album) that a recording appears on.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ReleaseRef {
    pub mbid: String,
    pub title: String,
    pub date: Option<String>,
    pub track_number: Option<i32>,
}

/// A recording match from a search query.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RecordingMatch {
    pub mbid: String,
    pub title: String,
    pub artist: String,
    pub artist_mbid: Option<String>,
    pub releases: Vec<ReleaseRef>,
    /// MusicBrainz API score (0-100).
    pub score: u8,
}

/// A release (album) match from a search query.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ReleaseMatch {
    pub mbid: String,
    pub title: String,
    pub artist: String,
    pub artist_mbid: Option<String>,
    pub date: Option<String>,
    pub track_count: Option<i32>,
    pub score: u8,
}

/// Full details for a recording, retrieved by MBID.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RecordingDetails {
    pub mbid: String,
    pub title: String,
    pub artist: String,
    pub artist_mbid: Option<String>,
    pub releases: Vec<ReleaseRef>,
    pub duration_ms: Option<u64>,
    pub genres: Vec<String>,
    /// Non-featuring collaborators beyond the primary artist.
    #[serde(default)]
    pub secondary_artists: Vec<(String, String)>,
}

/// Detailed artist info from a direct MBID lookup.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ArtistInfo {
    pub name: String,
    pub disambiguation: Option<String>,
    pub country: Option<String>,
    pub artist_type: Option<String>,
    pub begin_year: Option<String>,
    pub urls: Vec<ArtistUrl>,
}

/// An external URL linked to an artist on MusicBrainz.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ArtistUrl {
    pub url: String,
    pub link_type: String,
}

/// An artist match from a search query.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ArtistSearchResult {
    pub mbid: String,
    pub name: String,
    pub disambiguation: Option<String>,
    pub country: Option<String>,
    pub artist_type: Option<String>,
    pub score: u8,
}

/// A release entry in an artist's discography.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct DiscographyEntry {
    pub mbid: String,
    pub title: String,
    pub date: Option<String>,
    pub release_type: Option<String>,
    pub track_count: Option<i32>,
}

/// Trait for metadata lookup backends. MusicBrainz is the default implementation;
/// others (Last.fm, Discogs, etc.) can be added later.
pub trait MetadataProvider: Send + Sync {
    fn search_recording(
        &self,
        artist: &str,
        title: &str,
    ) -> impl std::future::Future<Output = TagResult<Vec<RecordingMatch>>> + Send;

    fn search_release(
        &self,
        artist: &str,
        album: &str,
    ) -> impl std::future::Future<Output = TagResult<Vec<ReleaseMatch>>> + Send;

    fn get_recording(
        &self,
        mbid: &str,
    ) -> impl std::future::Future<Output = TagResult<RecordingDetails>> + Send;

    fn search_artist(
        &self,
        query: &str,
        limit: u32,
    ) -> impl std::future::Future<Output = TagResult<Vec<ArtistSearchResult>>> + Send;

    fn get_artist_releases(
        &self,
        artist_mbid: &str,
        limit: u32,
    ) -> impl std::future::Future<Output = TagResult<Vec<DiscographyEntry>>> + Send;

    fn get_release_tracks(
        &self,
        release_mbid: &str,
    ) -> impl std::future::Future<Output = TagResult<Vec<ReleaseTrack>>> + Send;

    /// Get deduplicated release groups (albums, EPs, singles) for an artist.
    fn get_artist_release_groups(
        &self,
        artist_mbid: &str,
    ) -> impl std::future::Future<Output = TagResult<Vec<ReleaseGroupEntry>>> + Send;
}

/// A release group (deduplicated album/EP/single concept).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ReleaseGroupEntry {
    pub mbid: String,
    pub title: String,
    pub primary_type: Option<String>,
    pub secondary_types: Vec<String>,
    pub first_release_date: Option<String>,
    /// MBID of the first release in this group (for fetching tracks).
    pub first_release_mbid: Option<String>,
}

/// A track within a release.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ReleaseTrack {
    pub recording_mbid: String,
    pub title: String,
    pub track_number: Option<i32>,
    pub disc_number: Option<i32>,
    pub duration_ms: Option<u64>,
}