# `ExDisco.Releases`
[🔗](https://github.com/bo1ta/ex_disco/blob/main/lib/ex_disco/releases.ex#L1)

Query release (album) information from Discogs.

## Examples

Fetch full release details:

    {:ok, release} = ExDisco.Releases.get_release(249504)
    IO.inspect(release.title)

Get community rating:

    {:ok, rating} = ExDisco.Releases.get_rating(249504)
    IO.inspect(rating.average)

See `ExDisco.Releases.Release` for the complete data structure.

# `delete_user_rating`

```elixir
@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).

# `get_master_release`

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

Retrieves the master release given the master release ID

# `get_master_versions`

```elixir
@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}}

# `get_rating`

```elixir
@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}}

# `get_release`

```elixir
@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}}

# `get_stats`

```elixir
@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}}

# `get_user_rating`

```elixir
@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.

# `put_user_rating`

```elixir
@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
    }}

---

*Consult [api-reference.md](api-reference.md) for complete listing*