from dataclasses import dataclass, field
from typing import Protocol


@dataclass(frozen=True)
class ArtistHit:
    mbid: str
    name: str
    disambiguation: str = ""


@dataclass(frozen=True)
class ReleaseGroupInfo:
    rg_mbid: str
    title: str
    primary_type: str = ""
    secondary_types: tuple[str, ...] = ()
    first_release_date: str = ""


class MbBrowser(Protocol):
    def search_artist(self, name: str) -> list[ArtistHit]:
        """Artist name search → ranked hits (best first)."""
        ...

    def browse_release_groups(self, artist_mbid: str) -> list[ReleaseGroupInfo]:
        """All official release-groups for an artist MBID."""
        ...