spotify-ruby 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: edad90fdfafd7b93553043d283cf717520517d94
-  data.tar.gz: 9188847f32388191255de3ed13f45a6ab272f771
+  metadata.gz: 730ba39538bd63e5fffa9a125bc0148259babed8
+  data.tar.gz: 4f1f520071fb8b1817544ea7b1ce65e221334026
 SHA512:
-  metadata.gz: 70d0432c498285d1d06306ae2132d246729948f17595bc0d921af659476dbd8f5ad1641a258bc017ae46daeaedd2b927c98636f49b324ce61f11601023a2df4c
-  data.tar.gz: 2c2abd2f27cdec8924fc3f82ada20cf5ad28a1f87d9538625a2b62b0266855d86b3a5b6a24d350cf7bbf6c84041b7d72588463e718ad167dc09577f5c763ec6a
+  metadata.gz: 9c64d621832d0eb33b11a31d8ee9eb78da4f3f8f7f0e16e953dc1bab50dd6bc184794acd6d6fec0a1169dbb6c35ad4ce9838ae7a28e6f4ec24c1fe54e8e6c06e
+  data.tar.gz: 5764f6fb72f0ef04be219d2ed7fd4d39645c69b9bcc786866c6541dca7f81e677a4b6aab6e06196403b086bbf030bd20826701ee66547b75589a6922510592d3

data/.gitignore

@@ -4,6 +4,7 @@
 /_yardoc/
 /coverage/
 /doc/
+/html/
 /pkg/
 /spec/reports/
 /tmp/
@@ -12,3 +13,4 @@
 # rspec failure tracking
 .rspec_status
 .coveralls.yml
+.DS_Store

data/COVERAGE.md

@@ -0,0 +1,142 @@
+potify API Coverage
+
+This covers all the Spotify API endpoints that are covered.
+
+### Albums Endpoints
+
+| Endpoint | Description | Coverage Status |
+| -------- | ----------- | --------------- |
+| GET /v1/albums | Get Several Albums | × |
+| GET /v1/albums/{id}/tracks | Get an Album's Tracks | × |
+
+### Artists Endpoints
+
+| Endpoint | Description | Coverage Status |
+| -------- | ----------- | --------------- |
+| GET /v1/artists | Get Several Artists | × |
+| GET /v1/artists/{id}/albums | Get an Artist's Albums | × |
+| GET /v1/artists/{id}/top-tracks | Get an Artist's Top Tracks | × |
+| GET /v1/artists/{id}/related-artists | Get an Artist's Related Artists | × |
+
+### Tracks Endpoints
+
+| Endpoint | Description | Coverage Status |
+| -------- | ----------- | --------------- |
+| GET /v1/tracks | Get Several Tracks | × |
+
+### Audio Features Endpoints
+
+| Endpoint | Description | Coverage Status |
+| -------- | ----------- | --------------- |
+| GET /v1/audio-features/{id} | Get Audio Features for a Track | × |
+| GET /v1/audio-features | Get Audio Features for Several Tracks | × |
+
+### Analysis Endpoints
+
+| Endpoint | Description | Coverage Status |
+| -------- | ----------- | --------------- |
+| analysis | GET /v1/audio-analysis/{id} | Get Audio Analysis for a Track | × |
+
+### Search Endpoints
+
+| Endpoint | Description | Coverage Status |
+| -------- | ----------- | --------------- |
+| search | GET /v1/search | Search for an Item | × |
+
+### Users Endpoints
+
+| Endpoint | Description | Coverage Status |
+| -------- | ----------- | --------------- |
+| users | GET /v1/users/{user_id} | Get a User's Profile | × |
+| users | GET /v1/me | Get Current User's Profile | × |
+
+### Saved Content Endpoints
+
+| Endpoint | Description | Coverage Status |
+| -------- | ----------- | --------------- |
+| GET /v1/me/tracks | Get Current User's Saved Tracks | × |
+| GET /v1/me/tracks/contains | Check Current User's Saved Tracks | × |
+| PUT /v1/me/tracks | Save Tracks for Current User | × |
+| DELETE /v1/me/tracks | Remove Tracks for Current User | × |
+| GET /v1/me/albums | Get Current User's Saved Albums | × |
+| GET /v1/me/albums/contains | Check Current User's Saved Albums | × |
+| PUT /v1/me/albums | Save Albums for Current User | × |
+| DELETE /v1/me/albums | Remove Albums for Current User | × |
+
+### Discovery Endpoints
+
+| Endpoint | Description | Coverage Status |
+| -------- | ----------- | --------------- |
+| GET /v1/browse/new-releases | Get a List of New Releases | × |
+| GET /v1/browse/featured-playlists | Get a List of Featured Playlists | × |
+
+### Categories Endpoints
+
+| Endpoint | Description | Coverage Status |
+| -------- | ----------- | --------------- |
+| GET /v1/browse/categories | Get a List of Browse Categories | × |
+| GET /v1/browse/categories/{category_id} | Get a Single Browse Category | × |
+| GET /v1/browse/categories/{category_id}/playlists | Get a Category's playlists | × |
+
+### Recommendation Endpoints
+
+| Endpoint | Description | Coverage Status |
+| -------- | ----------- | --------------- |
+| GET /v1/recommendations | Get Recommendations Based on Seeds | × |
+| GET /v1/recommendations/available-genre-seeds | Get Available Genre Seeds | × |
+
+### Follow Endpoints
+
+| Endpoint | Description | Coverage Status |
+| -------- | ----------- | --------------- |
+| GET /v1/me/following | Get Followed Artists | × |
+| GET /v1/me/following/contains | Check if Current User Follows Artists or Users | × |
+| PUT /v1/me/following | Follow Artists or Users | × |
+| DELETE /v1/me/following | Unfollow Artists or Users | × |
+| GET /v1/users/{user_id}/playlists/{playlist_id}/followers/contains | Check if Users Follow a Playlist | × |
+| PUT /v1/users/{user_id}/playlists/{playlist_id}/followers | Follow a Playlist | × |
+| DELETE /v1/users/{user_id}/playlists/{playlist_id}/followers | Unfollow a Playlist | × |
+
+### Playlists Endpoints
+
+| Endpoint | Description | Coverage Status |
+| -------- | ----------- | --------------- |
+| GET /v1/users/{user_id}/playlists | Get a List of a User's Playlists | × |
+| GET /v1/me/playlists | Get a List of Current User's Playlists | × |
+| GET /v1/users/{user_id}/playlists/{playlist_id} | Get a Playlist | × |
+| GET /v1/users/{user_id}/playlists/{playlist_id}/tracks | Get a Playlist's Tracks | × |
+| POST /v1/users/{user_id}/playlists | Create a Playlist | × |
+| POST /v1/users/{user_id}/playlists/{playlist_id}/tracks | Add Tracks to a Playlist | × |
+| DELETE /v1/users/{user_id}/playlists/{playlist_id}/tracks | Remove Tracks from a Playlist | × |
+| PUT /v1/users/{user_id}/playlists/{playlist_id}/tracks | Reorder or replace a Playlist's Tracks | × |
+| PUT /v1/users/{user_id}/playlists/{playlist_id} | Change a Playlist's Details | × |
+
+### History Endpoints
+
+| Endpoint | Description | Coverage Status |
+| -------- | ----------- | --------------- |
+| GET /v1/me/top/{type} | Get User's Top Artists and Tracks | × |
+| GET /v1/me/player/recently-played | Get the Current User's Recently Played Tracks | × |
+
+### Connect Endpoints
+
+| Endpoint | Description | Coverage Status |
+| -------- | ----------- | --------------- |
+| GET /v1/me/player | Get Information About The User's Current Playback | × |
+| GET /v1/me/player/devices | Get a User's Available Devices | [✔](/lib/spotify/sdk/connect.rb) |
+| PUT /v1/me/player | Transfer a User's Playback | [✔](/lib/spotify/sdk/connect/device.rb) |
+
+### Player Endpoints
+
+| Endpoint | Description | Coverage Status |
+| -------- | ----------- | --------------- |
+| GET /v1/me/player/currently-playing | Get the User's Currently Playing Track | × |
+| PUT /v1/me/player/play | Start/Resume a User's Playback | × |
+| PUT /v1/me/player/pause | Pause a User's Playback | × |
+| POST /v1/me/player/next | Skip User's Playback To Next Track | × |
+| POST /v1/me/player/previous | Skip User's Playback To Previous Track | × |
+| PUT /v1/me/player/seek | Seek To Position In Currently Playing Track | × |
+| PUT /v1/me/player/repeat | Set Repeat Mode On User's Playback | × |
+| PUT /v1/me/player/volume | Set Volume For User's Playback | × |
+| PUT /v1/me/player/shuffle | Toggle Shuffle For User's Playback | × |
+

data/README.md

@@ -5,6 +5,9 @@ A modern, opinionated and *unofficial* Ruby SDK for the [Spotify Web API][spotif
 This is a work in progress. **Currently in pre-alpha.**
 
 [![Build Status](https://travis-ci.org/bih/spotify-ruby.svg?branch=master)](https://travis-ci.org/bih/spotify-ruby)
+[![Coverage Status](https://coveralls.io/repos/github/bih/spotify-ruby/badge.svg)](https://coveralls.io/github/bih/spotify-ruby)
+[![Gem Version](https://badge.fury.io/rb/spotify-ruby.svg)](https://badge.fury.io/rb/spotify-ruby)
+[![Code Triagers Badge](https://www.codetriage.com/bih/spotify-ruby/badges/users.svg)](https://www.codetriage.com/bih/spotify-ruby)
 
 ## Installation
 
@@ -30,23 +33,74 @@ Configure with your client credentials and redirect URL. Get it [for free here][
 require "spotify"
 
 @auth = Spotify::Auth.new({
-  client_id: ENV["SPOTIFY_CLIENT_ID"],
+  client_id:     ENV["SPOTIFY_CLIENT_ID"],
   client_secret: ENV["SPOTIFY_CLIENT_SECRET"],
-  redirect_uri: ENV["SPOTIFY_REDIRECT_URI"]
+  redirect_uri:  ENV["SPOTIFY_REDIRECT_URI"]
 })
 ```
 
 ## Authentication
 
-With our `@auth` instance, we can initiate an authentication URL for `https://accounts.spotify.com`. By default, this will have all the values needed to get a user setup.
+With our `@auth` instance, we have access to multiple forms of authentication. Below are our ones that we make available through the Spotify Platform: Authorization Code, Implicit Grant and Client Credentials. [Learn more here][spotify-authorization-guide].
+
+### Authorization Code
+
+**Recommended.** Generate the URL for the user to grant permissions for your application:
+
+```ruby
+@auth.authorize_url(response_type: "code")
+```
+
+Once they return back to your application with a `code`:
+
+```ruby
+@access_token = @auth.auth_code.get_token(params[:code])
+```
+
+You can save their information in the database under `access_token`, `expires_in` and `refresh_token`
+```ruby
+@sdk = Spotify::SDK.new(@access_token)
+@sdk.to_hash # => { access_token: "...", expires_in: 1234567890, refresh_token: "..." }
+```
+
+And you can also re-instantiate a SDK instance again later:
+```ruby
+@sdk = Spotify::SDK.new({
+  access_token:  "[insert access_token]",
+  expires_in:    "[insert expires_in]",
+  refresh_token: "[insert refresh_token]"
+})
+```
+
+And when their access token expires, you can just run `refresh!`:
+
+```ruby
+@access_token = @access_token.refresh!
+```
+
+### Implicit Grant
+
+```ruby
+@auth.authorize_url(response_type: "token")
+```
+
+Once they return back to your application with a `token`:
+
+```ruby
+@sdk = Spotify::SDK.new(params[:token])
+```
+
+### Client Credentials
+
+Generate an access token based from your client credentials. Note this has limited access.
 
 ```ruby
-@auth.authorize_url # => https://accounts.spotify.com/oauth/authorize?client_id=...&redirect_uri=...
+@access_token = @auth.client_credentials.get_token
 ```
 
 ## Usage
 
-TODO: Write more detailed usage instructions here
+TODO: Write more detailed usage instructions here. [Spotify API endpoint coverage can be found in COVERAGE.md](COVERAGE.md)
 
 ## Development
 
@@ -67,6 +121,7 @@ The gem is available as open source under the terms of the [MIT License](http://
 Everyone interacting in the `spotify-ruby` project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/bih/spotify-ruby/blob/master/CODE_OF_CONDUCT.md).
 
 [spotify]: https://spotify.com
+[spotify-authorization-guide]: https://developer.spotify.com/web-api/authorization-guide/
 [spotify-web-api]: https://developer.spotify.com/documentation/web-api/reference/
 [spotify-developer-dashboard]: https://developer.spotify.com/my-applications/
 [rubyinfo-docs]: http://www.rubydoc.info/github/bih/spotify-ruby

data/lib/spotify.rb

@@ -1,7 +1,14 @@
 # frozen_string_literal: true
 
+require "httparty"
+require "oauth2"
+
+require "active_support"
+require "active_support/core_ext"
+
 require "spotify/version"
 require "spotify/auth"
+require "spotify/sdk"
 
 ##
 # The declaration for the Spotify namespace.

data/lib/spotify/auth.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "oauth2"
-
 module Spotify
   ##
   # Spotify::Auth inherits from OAuth2::Client based on the "oauth-2" gem.
@@ -39,7 +37,6 @@ module Spotify
     # Initialize the Spotify Auth object.
     #
     # @example
-    #
     #   @auth = Spotify::Auth.new({
     #     client_id: "[client id goes here]",
     #     client_secret: "[client secret goes here]",
@@ -47,25 +44,25 @@ module Spotify
     #   })
     #
     # @param [Hash] config OAuth configuration containing the Client ID, secret and redirect URL.
-    # The redirect URL can be overriden later.
     #
     # @see https://developer.spotify.com/my-applications/
     #
     def initialize(config)
+      validate_initialized_input(config)
+      client_id = config.delete(:client_id)
+      client_secret = config.delete(:client_secret)
       opts = {
         site:          "https://api.spotify.com",
-        authorize_url: "https://accounts.spotify.com/oauth/authorize"
-      }
-      validate_initialized_input(config)
-      @redirect_uri = config[:redirect_uri]
-      super(config[:client_id], config[:client_secret], opts)
+        authorize_url: "https://accounts.spotify.com/oauth/authorize",
+        token_url:     "https://accounts.spotify.com/api/token"
+      }.merge(config)
+      super(client_id, client_secret, opts)
     end
 
     ##
     # Get a HTTP URL to send user for authorizing with Spotify.
     #
     # @example
-    #
     #   @auth = Spotify::Auth.new({
     #     client_id: "[client id goes here]",
     #     client_secret: "[client secret goes here]",
@@ -76,13 +73,13 @@ module Spotify
     #
     # @param [Hash] override_params Optional hash containing any overriding values for parameters.
     # Parameters used are client_id, redirect_uri, response_type and scope.
+    # @return [String] A fully qualified Spotify authorization URL to send the user to.
     #
     # @see https://developer.spotify.com/web-api/authorization-guide/
     #
     def authorize_url(override_params={})
       super({
         client_id:     id,
-        redirect_uri:  redirect_uri,
         response_type: "code",
         scope:         SCOPES.join(" ")
       }.merge(override_params))
@@ -90,21 +87,16 @@ module Spotify
 
     private
 
-    ##
-    # OAuth2::Client does not support redirect_uri at initialization, so we store
-    # it in the instance and call it later. We think it makes things clearer.
-    #
-    attr_accessor :redirect_uri
-
     ##
     # Validate initialization configuration and raise errors.
     #
     # @param [Hash] config OAuth configuration containing the Client ID, secret and redirect URL.
+    # @return [nil]
     #
     def validate_initialized_input(config)
       raise Errors::AuthClientCredentialsError.new(OAUTH_I18N[:must_be_hash]) unless config.is_a?(Hash)
 
-      %i[client_id client_secret redirect_uri].each do |key|
+      %i[client_id client_secret].each do |key|
         raise Errors::AuthClientCredentialsError.new(OAUTH_I18N[:require_attr] % key) unless config.has_key?(key)
       end
     end

data/lib/spotify/sdk.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "spotify/sdk/initialization"
+require "spotify/sdk/initialization/base"
+require "spotify/sdk/initialization/oauth_access_token"
+require "spotify/sdk/initialization/plain_string"
+require "spotify/sdk/initialization/query_hash"
+require "spotify/sdk/initialization/query_string"
+require "spotify/sdk/initialization/url_string"
+require "spotify/sdk/base"
+require "spotify/sdk/model"
+require "spotify/sdk/connect"
+require "spotify/sdk/connect/device"
+
+module Spotify
+  ##
+  # Spotify::SDK contains the complete Ruby DSL to interact with the Spotify Platform.
+  #
+  class SDK
+    ##
+    # Initialize the Spotify SDK object.
+    #
+    # @example
+    #   # Example 1: Load it in from an access token value.
+    #   @sdk = Spotify::SDK.new("access_token_here")
+    #
+    #   # Example 2: Load it in with values from your database.
+    #   @sdk = Spotify::SDK.new({
+    #     access_token: "access_token_here",
+    #     expires_in: 3_000_000,
+    #     refresh_token: "refresh_token_here"
+    #   })
+    #
+    #   # Example 4: Load it in from an OAuth2::AccessToken object.
+    #   @sdk = Spotify::SDK.new(@auth.auth_code.get_token("auth code"))
+    #
+    #   # Example 5: Load it from a query string or a fully qualified URL.
+    #   @sdk = Spotify::SDK.new("https://localhost:8080/#token=...&expires_in=...")
+    #   @sdk = Spotify::SDK.new("token=...&expires_in=...")
+    #
+    # @param [String, Hash, OAuth2::AccessToken] obj Any supported object which contains an access token. See examples.
+    #
+    def initialize(obj)
+      @payload = Spotify::SDK::Initialization.detect(obj)
+      @access_token  = @payload[:access_token]
+      @expires_in    = @payload[:expires_in]
+      @refresh_token = @payload[:refresh_token]
+
+      mount_sdk_components
+    end
+
+    ##
+    # Helper method to a fully qualified OAuth2::AccessToken instance.
+    #
+    # @example
+    #   @auth = Spotify::Auth.new({
+    #     client_id: "[client id goes here]",
+    #     client_secret: "[client secret goes here]",
+    #     redirect_uri: "http://localhost"
+    #   })
+    #
+    #   @sdk = Spotify::SDK.new("access_token_here")
+    #   @sdk.oauth2_access_token(@auth) # => #<OAuth2::AccessToken:...>
+    #
+    # @param [Spotify::Auth] client An instance of Spotify::Auth. See example.
+    # @return [OAuth2::AccessToken] An fully qualified instance of OAuth2::AccessToken.
+    #
+    def oauth2_access_token(client)
+      OAuth2::AccessToken.new(client, @access_token, expires_in:    @expires_in,
+                                                     refresh_token: @refresh_token)
+    end
+
+    ##
+    # Obtain a hash containing all of the user's authorization details.
+    #
+    # @example
+    #   @auth = Spotify::Auth.new({
+    #     client_id: "[client id goes here]",
+    #     client_secret: "[client secret goes here]",
+    #     redirect_uri: "http://localhost"
+    #   })
+    #
+    #   @sdk = Spotify::SDK.new("access_token_here")
+    #   @sdk.to_hash # => { access_token: ..., expires_in: ... }
+    #
+    # @return [Hash] Containing access_token, expires_in and refresh_token
+    #
+    def to_hash
+      @payload.with_indifferent_access.symbolize_keys
+    end
+
+    attr_reader :access_token, :expires_in, :refresh_token
+    attr_reader :connect
+
+    private
+
+    ##
+    # This is where we mount all SDK components to the SDK object.
+    # When mounting a new component, you'll need to do the following:
+    # - Be sure to add a `attr_reader` for it. Developers can't access it otherwise.
+    # - Add a test for it in spec/lib/spotify/sdk_spec.rb (see how we did it for others)
+    #
+    # @return [nil]
+    #
+    def mount_sdk_components
+      @connect = Spotify::SDK::Connect.new(self)
+    end
+  end
+end