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

Elixir client for the Discogs API.

Discogs is the world's largest crowdsourced music database. ExDisco provides
a type-safe, ergonomic Elixir interface to query artists, releases, labels,
and users, with support for both personal token and OAuth 1.0a authentication.

## Getting Started

Start by configuring a user-agent (required by Discogs):

    config :ex_disco, ExDisco,
      user_agent: "my_app/1.0.0 (+https://github.com/me/my_app)"

Then fetch data:

    {:ok, artist} = ExDisco.Artists.get(1)
    IO.inspect(artist.name)

See the resource modules for specific data types:
- `ExDisco.Artists` — Query artists
- `ExDisco.Releases` — Query releases (albums, EPs, etc.)
- `ExDisco.Labels` — Query record labels
- `ExDisco.Users` — Query user profiles
- `ExDisco.Search` — Global search

## Configuration

### Required: User Agent

Discogs requires all applications identify themselves with a user agent:

    config :ex_disco, ExDisco,
      user_agent: "my_app/1.0.0 (+https://github.com/me/my_app)"

### Optional: Authentication

Choose one of two approaches:

#### Personal Token (Simple)

For personal scripts, CLIs, and single-user applications. Get a token at
https://www.discogs.com/settings/developers, then configure it:

    config :ex_disco, ExDisco,
      user_token: "your_token"

Use it in requests:

    token = ExDisco.Auth.user_token("your_token")
    Request.get("/users/me")
    |> Request.put_auth(token)
    |> Request.execute(&User.Identity.from_api/1)

#### OAuth 1.0a (Multi-User)

For applications acting on behalf of multiple users. Register your app at
https://www.discogs.com/settings/developers to obtain consumer credentials:

    config :ex_disco, ExDisco,
      consumer_key: "your_consumer_key",
      consumer_secret: "your_consumer_secret"

Each user goes through the OAuth flow to obtain their own access token and
secret. Store these per-user and pass them to authenticated requests:

    credentials = ExDisco.Auth.oauth_credentials(
      consumer_key,
      consumer_secret,
      user.discogs_token,
      user.discogs_token_secret
    )

    Request.get("/users/me")
    |> Request.put_auth(credentials)
    |> Request.execute(&User.Identity.from_api/1)

See `ExDisco.Auth` for the complete OAuth flow documentation.

## Examples

Fetch an artist:

    {:ok, artist} = ExDisco.Artists.get(1)

Fetch release information:

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

Search the database:

    {:ok, page} = ExDisco.Search.query([q: "Thriller", type: :release])
    IO.inspect(page.items)

Handle errors:

    case ExDisco.Artists.get(9999999) do
      {:ok, artist} -> IO.inspect(artist)
      {:error, error} -> IO.inspect("Error: #{error.message}")
    end

See the request builder for advanced usage:

    {:ok, releases} = ExDisco.Request.get("/artists/1/releases")
    |> ExDisco.Request.put_query(per_page: 25)
    |> ExDisco.Request.execute_collection("releases", &ReleaseSummary.from_api/1)

---

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