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

Query user profile and identity information from Discogs.

Users represent Discogs community members. You can retrieve basic identity
information about yourself (when authenticated) or public profile information
about any user.

## Authentication

Functions that require authentication take an `ExDisco.Auth.Authorization`
as their first argument for easy piping:

    ExDisco.Config.user_token()
    |> ExDisco.Auth.Authorization.for_user_token()
    |> ExDisco.Users.get_identity()

## Examples

Get your identity (requires authentication):

    auth = ExDisco.Auth.Authorization.for_user_token(ExDisco.Config.user_token())
    {:ok, me} = ExDisco.Users.get_identity(auth)
    IO.inspect(me.username)

Get a user's public profile:

    {:ok, user} = ExDisco.Users.get_profile("someuser")
    IO.inspect(user.location)

See `ExDisco.Users.Identity` and `ExDisco.Users.Profile` for data structures.

# `get_identity`

```elixir
@spec get_identity(ExDisco.Auth.Authorization.t()) ::
  {:ok, ExDisco.Users.Identity.t()} | {:error, ExDisco.Error.t()}
```

Get the authenticated user's identity.

Returns basic information about the currently authenticated user. This is a
good sanity check to verify you're authenticated correctly. For more detailed
information, use `get_profile/2`.

Requires authentication (personal token or OAuth).

## Examples

    iex> auth = ExDisco.Auth.Authorization.for_user_token("my_token")
    iex> ExDisco.Users.get_identity(auth)
    {:ok, %ExDisco.Users.Identity{username: "myself", ...}}

# `get_profile`

```elixir
@spec get_profile(String.t()) ::
  {:ok, ExDisco.Users.Profile.t()} | {:error, ExDisco.Error.t()}
```

Get a user's profile by username. Username must be a non-empty string.

Returns public profile information about a Discogs user including location,
collection and wantlist details, and ratings. If authenticated as the user,
additional private information like email may be visible.

## Examples

    iex> ExDisco.Users.get_profile("someuser")
    {:ok, %ExDisco.Users.Profile{username: "someuser", location: "...", ...}}

# `get_profile`

```elixir
@spec get_profile(ExDisco.Auth.Authorization.t(), String.t()) ::
  {:ok, ExDisco.Users.Profile.t()} | {:error, ExDisco.Error.t()}
```

# `update_profile`

```elixir
@spec update_profile(
  ExDisco.Auth.Authorization.t(),
  String.t(),
  ExDisco.Users.Profile.update()
) ::
  {:ok, ExDisco.Users.Profile.t()} | {:error, ExDisco.Error.t()}
```

Update the authenticated user's profile. Username must be a non-empty string.

Pass a map with only the fields you want to change.
Unset fields are omitted from the request and left unchanged on Discogs.

Requires authentication as the user being updated.

## Examples

    iex> auth = ExDisco.Auth.Authorization.for_user_token("my_token")
    iex> ExDisco.Users.update_profile(auth, "vreon", %{location: "Portland", curr_abbr: "USD"})
    {:ok, %ExDisco.Users.Profile{location: "Portland", ...}}

    iex> ExDisco.Users.update_profile(auth, "vreon", %{curr_abbr: "FAKE"})
    {:error, %ExDisco.Error{type: :invalid_argument, ...}}

---

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