@spec delete_user_rating(ExDisco.Auth.Authorization.t(), pos_integer(), String.t()) ::
  :ok | {:error, ExDisco.Error.t()}

Deletes the release’s rating for a given user.

Requires authentication (personal token or OAuth).

@spec get_master_release(pos_integer()) ::
  {:ok, ExDisco.Releases.MasterRelease.t()} | {:error, ExDisco.Error.t()}

Retrieves the master release given the master release ID

@spec get_master_versions(
  pos_integer(),
  keyword()
) ::
  {:ok, ExDisco.Page.t(ExDisco.Releases.MasterVersion.t())}
  | {:error, ExDisco.Error.t()}

Fetch all release versions of a master release.

Returns a paginated list of every pressing and edition of a master recording. Each item is a MasterVersion with format, country, label, and community stats.

Options

• :page — Page number to fetch (default: 1)
• :per_page — Items per page (default: 50)
• :sort — Sort field: released, title, format, label, catno, country
• :sort_order — asc or desc
• :format — Filter by format string (e.g. "Vinyl")
• :label — Filter by label name
• :released — Filter by release year (e.g. "1993")
• :country — Filter by country (e.g. "Belgium")

Examples

iex> ExDisco.Releases.get_master_versions(1000)
{:ok, %ExDisco.Page{items: [%ExDisco.Releases.MasterVersion{}, ...], total: 47, pages: 1}}

iex> ExDisco.Releases.get_master_versions(1000, page: 2, sort: "released", country: "UK")
{:ok, %ExDisco.Page{items: [...], page: 2, total: 47}}

@spec get_rating(pos_integer()) ::
  {:ok, ExDisco.Releases.Rating.t()} | {:error, ExDisco.Error.t()}

Fetch the community rating for a release.

Returns the average rating and vote count from the Discogs community.

Examples

iex> ExDisco.Releases.get_rating(249504)
{:ok, %ExDisco.Releases.Rating{average: 4.2, count: 87}}

@spec get_release(pos_integer()) ::
  {:ok, ExDisco.Releases.Release.t()} | {:error, ExDisco.Error.t()}

Fetch a release by Discogs ID.

Returns comprehensive release data including title, artists, tracklist, formats, condition notes, and community metadata.

Examples

iex> ExDisco.Releases.get_release(249504)
{:ok, %ExDisco.Releases.Release{id: 249504, title: "Never Gonna Give You Up", ...}}

iex> ExDisco.Releases.get_release(9999999)
{:error, %ExDisco.Error{type: :not_found}}

@spec get_stats(pos_integer()) ::
  {:ok, ExDisco.Releases.ReleaseStats.t()} | {:error, ExDisco.Error.t()}

Fetch statistics for a release (view counts, wants, haves).

Returns aggregate community statistics about how many users have or want the release.

Examples

iex> ExDisco.Releases.get_stats(249504)
{:ok, %ExDisco.Releases.ReleaseStats{is_offensive: false, num_want: 42, num_have: 156}}

@spec get_user_rating(pos_integer(), String.t()) ::
  {:ok, ExDisco.Releases.UserRating.t()} | {:error, ExDisco.Error.t()}

Retrieves the release's rating for a given username.

If the user hasn't rated the release, then the rating will be 0.

@spec put_user_rating(
  ExDisco.Auth.Authorization.t(),
  pos_integer(),
  String.t(),
  pos_integer()
) ::
  {:ok, ExDisco.Releases.UserRating.t()} | {:error, ExDisco.Error.t()}

Updates the release’s rating for a given user and returns the updated user rating.

Requires authentication (personal token or OAuth).

Examples

iex> auth = ExDisco.Auth.Authorization.for_user_token("my_token")
iex> ExDisco.Releases.put_user_rating(auth, 249504, "someusername", 5)
{:ok,
%ExDisco.Releases.UserRating{
  username: "someusername",
  release_id: 249504,
  rating: 5
}}