lastex

defmodule Lastex.User do
  @moduledoc """
  Functions for the Last.fm User API methods.

  Functions returning a user's top items accept a `period` option — one of
  `"overall"`, `"7day"`, `"1month"`, `"3month"`, `"6month"`, or `"12month"`.
  """

  @doc """
  Fetches a user's friends (`user.getFriends`).

  Returns a `Lastex.Page`. Supports `limit`, `page`, and `recenttracks: 1` to
  include each friend's latest scrobble.

      Lastex.User.friends("rj", limit: 50)

  """
  def friends(user, opts \\ []) do
    opts
    |> Map.new()
    |> Map.put(:user, user)
    |> then(&Lastex.Client.get("user.getFriends", &1))
    |> Lastex.Page.from_response({"friends", "user"})
  end

  @doc """
  Fetches a user's profile (`user.getInfo`).

      Lastex.User.info("rj")

  """
  def info(user) do
    Lastex.Client.get("user.getInfo", %{user: user})
  end

  @doc """
  Fetches the tracks a user has loved (`user.getLovedTracks`).

  Returns a `Lastex.Page`. Supports `limit` and `page`.

      Lastex.User.loved_tracks("rj", limit: 50)

  """
  def loved_tracks(user, opts \\ []) do
    opts
    |> Map.new()
    |> Map.put(:user, user)
    |> then(&Lastex.Client.get("user.getLovedTracks", &1))
    |> Lastex.Page.from_response({"lovedtracks", "track"})
  end

  @doc """
  Fetches the items a user has tagged with a given tag (`user.getPersonalTags`).

  `taggingtype` is one of `"artist"`, `"album"`, or `"track"`, and determines the
  shape of the returned data. Returns a `Lastex.Page`.

      Lastex.User.personal_tags("rj", "progressive metal", "artist")

  """
  def personal_tags(user, tag, taggingtype, opts \\ []) do
    opts
    |> Map.new()
    |> Map.merge(%{user: user, tag: tag, taggingtype: taggingtype})
    |> then(&Lastex.Client.get("user.getPersonalTags", &1))
    |> Lastex.Page.from_response({"taggings", [taggingtype <> "s", taggingtype]})
  end

  @doc """
  Fetches a user's recent scrobbles (`user.getRecentTracks`).

  Returns a `Lastex.Page`. Supports `limit` (up to 200), `page`, and `from`/`to`
  Unix timestamps to bound the range. A currently playing track, if any, is
  included with a `"@attr" => %{"nowplaying" => "true"}` marker.

      Lastex.User.recent_tracks("rj", limit: 200)

  """
  def recent_tracks(user, opts \\ []) do
    opts
    |> Map.new()
    |> Map.put(:user, user)
    |> then(&Lastex.Client.get("user.getRecentTracks", &1))
    |> Lastex.Page.from_response({"recenttracks", "track"})
  end

  @doc """
  Fetches a user's most listened-to albums (`user.getTopAlbums`).

  Returns a `Lastex.Page`. Supports `period`, `limit`, and `page`.

      Lastex.User.top_albums("rj", period: "6month", limit: 10)

  """
  def top_albums(user, opts \\ []) do
    opts
    |> Map.new()
    |> Map.put(:user, user)
    |> then(&Lastex.Client.get("user.getTopAlbums", &1))
    |> Lastex.Page.from_response({"topalbums", "album"})
  end

  @doc """
  Fetches a user's most listened-to artists (`user.getTopArtists`).

  Returns a `Lastex.Page`. Supports `period`, `limit`, and `page`.

      Lastex.User.top_artists("rj", period: "overall", limit: 10)

  """
  def top_artists(user, opts \\ []) do
    opts
    |> Map.new()
    |> Map.put(:user, user)
    |> then(&Lastex.Client.get("user.getTopArtists", &1))
    |> Lastex.Page.from_response({"topartists", "artist"})
  end

  @doc """
  Fetches a user's most used tags (`user.getTopTags`).

  Returns a `Lastex.Page`. Supports `limit`.

      Lastex.User.top_tags("rj", limit: 10)

  """
  def top_tags(user, opts \\ []) do
    opts
    |> Map.new()
    |> Map.put(:user, user)
    |> then(&Lastex.Client.get("user.getTopTags", &1))
    |> Lastex.Page.from_response({"toptags", "tag"})
  end

  @doc """
  Fetches a user's most listened-to tracks (`user.getTopTracks`).

  Returns a `Lastex.Page`. Supports `period`, `limit`, and `page`.

      Lastex.User.top_tracks("rj", period: "1month", limit: 10)

  """
  def top_tracks(user, opts \\ []) do
    opts
    |> Map.new()
    |> Map.put(:user, user)
    |> then(&Lastex.Client.get("user.getTopTracks", &1))
    |> Lastex.Page.from_response({"toptracks", "track"})
  end

  @doc """
  Fetches a user's album chart for a week (`user.getWeeklyAlbumChart`).

  Returns a `Lastex.Page`. Pass `from` and `to` Unix timestamps from
  `weekly_chart_list/1`; the most recent week is used when omitted.

      Lastex.User.weekly_album_chart("rj")

  """
  def weekly_album_chart(user, opts \\ []) do
    opts
    |> Map.new()
    |> Map.put(:user, user)
    |> then(&Lastex.Client.get("user.getWeeklyAlbumChart", &1))
    |> Lastex.Page.from_response({"weeklyalbumchart", "album"})
  end

  @doc """
  Fetches a user's artist chart for a week (`user.getWeeklyArtistChart`).

  Returns a `Lastex.Page`. Pass `from` and `to` Unix timestamps from
  `weekly_chart_list/1`; the most recent week is used when omitted.

      Lastex.User.weekly_artist_chart("rj")

  """
  def weekly_artist_chart(user, opts \\ []) do
    opts
    |> Map.new()
    |> Map.put(:user, user)
    |> then(&Lastex.Client.get("user.getWeeklyArtistChart", &1))
    |> Lastex.Page.from_response({"weeklyartistchart", "artist"})
  end

  @doc """
  Fetches the weekly chart periods available for a user (`user.getWeeklyChartList`).

  Each entry carries the `from` and `to` Unix timestamps accepted by the
  `weekly_*_chart` functions.

      Lastex.User.weekly_chart_list("rj")

  """
  def weekly_chart_list(user) do
    Lastex.Client.get("user.getWeeklyChartList", %{user: user})
  end

  @doc """
  Fetches a user's track chart for a week (`user.getWeeklyTrackChart`).

  Returns a `Lastex.Page`. Pass `from` and `to` Unix timestamps from
  `weekly_chart_list/1`; the most recent week is used when omitted.

      Lastex.User.weekly_track_chart("rj")

  """
  def weekly_track_chart(user, opts \\ []) do
    opts
    |> Map.new()
    |> Map.put(:user, user)
    |> then(&Lastex.Client.get("user.getWeeklyTrackChart", &1))
    |> Lastex.Page.from_response({"weeklytrackchart", "track"})
  end
end