Tweaks for version 1.0.0 release

README.md

@@ -10,7 +10,7 @@
   1. Add spotify_ex to your list of dependencies in `mix.exs`:
 
         def deps do
-           [{:spotify_ex, "~> 0.1.4"}]
+           [{:spotify_ex, "~> 1.0.0"}]
         end
 
   2. Ensure spotify_ex is started before your application:
@@ -19,24 +19,29 @@
           [applications: [:spotify_ex]]
         end
 
-## This package is under active development and will change frequently.
-APIs covered so far:
-- OAuth
-- Playlists
-- Personalization
-- Profile
-- Albums
-- Tracks
-- Artists
-
-APIs In Progress:
-- Browse
-- Follow
-- Library
 
 [Documentation](https://hexdocs.pm/spotify_ex/0.1.3/api-reference.html)
 
-Breaking changes will occur until 1.0!
+## What does this wrapper cover?
+
+This wrapper covers the [Spotify Web
+API](https://developer.spotify.com/web-api/endpoint-reference/).
+
+Follow that link, on the left you'll notice they have the API broken into
+sections, such as Artists, Albums, Playlists, etc. This wrapper does its best
+to keep endpoints in modules mapped to their corresponding section, however
+Spotify duplicates many of its endpoints. For example, there's an endpoint to
+get an artist's albums that's listed under both Artists and Albums. The endpoints
+are not duplicated in this wrapper, so if you don't see an endpoint, it's a
+module that's also related to that endpoint i.e, if you don't see that endpoint
+in the `Artist` module, check `Albums`.
+
+Example: All of the endpoints in the "Follow" section are in other modules, but
+they're all about following Playlists, Artists, etc. The `follow_playlist`
+endpoint will be in the `Playlist` module.
+
+These duplicate endpoints may get aliased in the future to have a 1-1 mapping
+with the docs.
 
 ## Usage
 
@@ -150,3 +155,8 @@ end
 
 The authentication module will set refresh and access tokens in a cookie. The access token expires every hour, and you'll need to check your reponses for 401 errors. Call `Spotify.Authentication.refresh`, if there is a refresh token present.  If not, you'll need to redirect back to authorization.
 
+## Contributing
+
+All contributions are more than Welcome! I will not accept a PR without tests if it
+looks like something that should be tested, which is pretty much everything.
+All public API must be documented.

lib/spotify/album.ex

@@ -96,7 +96,8 @@ defmodule Spotify.Album do
   end
 
   @doc"""
-  Foo
+  Get Spotify catalog information about an album’s tracks.
+
       iex> Spotify.Album.get_album_tracks_url("4")
       "https://api.spotify.com/v1/albums/4/tracks"
   """

lib/spotify/categories.ex

@@ -4,34 +4,73 @@ defmodule Spotify.Category do
   use Responder
   @behaviour Responder
   import Helpers
-  alias Spotify.{Category, Client}
+  alias Spotify.{Category, Client, Seed}
 
   defstruct ~w[href icons id name]a
 
-  def get_categories do
+  @doc """
+  Get a list of categories used to tag items in Spotify
+  [Spotify Documentation](https://developer.spotify.com/web-api/get-list-categories/)
 
-  end
+  **Method**: `GET`
 
-  def get_categories_url do
+  **Optional Params**: `country`, `locale`, `limit`, `offset`
 
+      Spotify.Category.get_categories(conn, params)
+      # => { :ok, %Paging{items: [%Category{}, ...]} }
+  """
+  def get_categories(conn, params \\ []) do
+    url = get_categories_url(params)
+    conn |> Client.get(url) |> handle_response
   end
 
-  def get_category do
+  @doc """
+  Get a list of categories used to tag items in Spotify
 
+    iex> Spotify.Category.get_categories_url(country: "US")
+    "https://api.spotify.com/v1/browse/categories?country=US"
+  """
+  def get_categories_url(params \\ []) do
+    "https://api.spotify.com/v1/browse/categories" <> query_string(params)
   end
 
-  def get_category_url do
-  end
+  @doc """
+  Get a single category used to tag items in Spotify
+  [Spotify Documentation](https://developer.spotify.com/web-api/get-category/)
+
+  **Method**: `GET`
 
-  def get_recommendations do
+  **Optional Params**: `country`, `locale`
 
+      Spotify.Category.get_category(conn, id)
+      # => {:ok, %Category{}}
+  """
+  def get_category(conn, id, params \\ []) do
+    url = get_category_url(id, params)
+    conn |> Client.get(url) |> handle_response
   end
 
-  def get_recommendations_url do
+  @doc """
+  Get a single category used to tag items in Spotify
+
+    iex> Spotify.Category.get_category_url("4")
+    "https://api.spotify.com/v1/browse/categories/4"
+  """
+  def get_category_url(id, params \\ []) do
+    "https://api.spotify.com/v1/browse/categories/#{id}" <> query_string(params)
   end
 
+
   def build_response(body) do
+    case body do
+      %{ "categories" => categories } -> build_categories(body, categories["items"])
+      category -> to_struct(Category, category)
+    end
+  end
 
+  def build_categories(body, categories) do
+    categories = Enum.map(categories, &to_struct(Category, &1))
+    Paging.response(body, categories)
   end
 
 end

mix.exs

@@ -3,7 +3,7 @@ defmodule Spotify.Mixfile do
 
   def project do
     [app: :spotify_ex,
-     version: "0.1.4",
+     version: "1.0.0",
      elixir: "~> 1.3",
      description: description,
      package: package,

test/doc_test.exs

@@ -3,7 +3,9 @@ defmodule DocTest do
 
   doctest Spotify.Album
   doctest Spotify.Artist
+  doctest Spotify.Category
   doctest Spotify.Personalization
+  doctest Spotify.Recommendation
   doctest Spotify.Playlist
   doctest Spotify.Profile
   doctest Spotify.Search