spotify-ruby 0.2.2 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0b63f5681311753e57dd0f3465c03c92b2f075a0
-  data.tar.gz: 1388c3f85c842cf7521360af71a62b7ac20e2620
+  metadata.gz: 118af1b2f6ab08785aa78c8028bf7927003154a1
+  data.tar.gz: 2d655193db96272b01a9f90aef9964c5a482e324
 SHA512:
-  metadata.gz: db844e007c167f743d38434c9a94ab16992730a75b62dd47a28f0d161a609c96205975b6c6b03e3765769b2062cfda2068c19bc40bad8da9b25b35e5e0d7ff4d
-  data.tar.gz: c205c712540fd6f205f902912765049112b4cf052554043562a2c431b3bbf6fed90c4cf3e99e08b4c107e1539de93d061ae90997607591a4ed4ec7e982665e75
+  metadata.gz: b6f4a4f4018790a020e3ebd1b926b6ceda2ce0fe8a5fc3d807cd2da87b81489ae19a68d1b3236eb59cb9bf1ecdbb74b51fe1a71900486b93719eaa490df63714
+  data.tar.gz: b2e0da362c7786da52a7eee27f1a1277f5f953fa499c82b7d615b97745f27e9aaf043229cbdfea02ba3d91c896e06caa4375e75b9049aff2cbb385084b27fe10

data/.travis.yml

@@ -4,6 +4,7 @@ rvm:
   - 2.4.0
   - 2.4.1
   - 2.5.0
+  - 2.5.1
 before_install: >
   gem install bundler -v 1.15.1
 before_script:

data/COVERAGE.md

@@ -87,15 +87,15 @@ This covers all the Spotify API endpoints that are covered.
 
 ### Follow Endpoints
 
-| Endpoint                                                           | Description                                    | Coverage Status                                                        |
-| ------------------------------------------------------------------ | ---------------------------------------------- | ---------------------------------------------------------------------- |
-| GET /v1/me/following                                               | Get Followed Artists                           | [me.rb]                                                                |
-| GET /v1/me/following/contains                                      | Check if Current User Follows Artists or Users | [me.rb]                                                                |
-| PUT /v1/me/following                                               | Follow Artists or Users                        | [🔘 Partial Support][artist.rb] (Following multiple isn't supported)   |
-| DELETE /v1/me/following                                            | Unfollow Artists or Users                      | [🔘 Partial Support][artist.rb] (Unfollowing multiple isn't supported) |
-| GET /v1/users/{user_id}/playlists/{playlist_id}/followers/contains | Check if Users Follow a Playlist               | × Not Started                                                          |
-| PUT /v1/users/{user_id}/playlists/{playlist_id}/followers          | Follow a Playlist                              | × Not Started                                                          |
-| DELETE /v1/users/{user_id}/playlists/{playlist_id}/followers       | Unfollow a Playlist                            | × Not Started                                                          |
+| Endpoint                                                           | Description                                    | Coverage Status                                                      |
+| ------------------------------------------------------------------ | ---------------------------------------------- | -------------------------------------------------------------------- |
+| GET /v1/me/following                                               | Get Followed Artists                           | [me.rb]                                                              |
+| GET /v1/me/following/contains                                      | Check if Current User Follows Artists or Users | [me.rb]                                                              |
+| PUT /v1/me/following                                               | Follow Artists or Users                        | [🔘 Partial Support][artist.rb] (Following multiple not supported)   |
+| DELETE /v1/me/following                                            | Unfollow Artists or Users                      | [🔘 Partial Support][artist.rb] (Unfollowing multiple not supported) |
+| GET /v1/users/{user_id}/playlists/{playlist_id}/followers/contains | Check if Users Follow a Playlist               | × Not Started                                                        |
+| PUT /v1/users/{user_id}/playlists/{playlist_id}/followers          | Follow a Playlist                              | × Not Started                                                        |
+| DELETE /v1/users/{user_id}/playlists/{playlist_id}/followers       | Unfollow a Playlist                            | × Not Started                                                        |
 
 ### Playlists Endpoints
 
@@ -113,10 +113,10 @@ This covers all the Spotify API endpoints that are covered.
 
 ### History Endpoints
 
-| Endpoint                          | Description                                   | Coverage Status |
-| --------------------------------- | --------------------------------------------- | --------------- |
-| GET /v1/me/top/{type}             | Get User's Top Artists and Tracks             | × Not Started   |
-| GET /v1/me/player/recently-played | Get the Current User's Recently Played Tracks | × Not Started   |
+| Endpoint                          | Description                                   | Coverage Status         |
+| --------------------------------- | --------------------------------------------- | ----------------------- |
+| GET /v1/me/top/{type}             | Get User's Top Artists and Tracks             | × Not Started           |
+| GET /v1/me/player/recently-played | Get the Current User's Recently Played Tracks | [Full support ✔][me.rb] |
 
 ### Connect Endpoints
 

data/README.md

@@ -23,13 +23,15 @@ The developer-friendly, opinionated Ruby SDK for [Spotify]. Works on Ruby 2.4+
   - [Creating a Session](#creating-a-session)
   - [Recreating a Session](#recreating-a-session)
 - [Using the SDK](#using-the-sdk)
-  - [Spotify Connect](#spotify-connect)
+  - [Spotify Connect API](#spotify-connect-api)
+  - [Me API](#me-api)
+  - [Listening History API](#listening-history-api)
+  - [Following API](#following-api)
 - [Contributing](#contributing)
   - [Community Guidelines](#community-guidelines)
   - [Code of Conduct](#code-of-conduct)
   - [Getting Started](#getting-started)
   - [Releasing a Change](#releasing-a-change)
-  - [Changelog](#changelog)
 - [License](#license)
 
 ## Introduction
@@ -95,11 +97,25 @@ To define your app credentials, you'll need to create an instance of `Spotify::A
 
 ```ruby
 @accounts = Spotify::Accounts.new
-@accounts.client_id = ENV["SPOTIFY_CLIENT_ID"]
-@accounts.client_secret = ENV["SPOTIFY_CLIENT_SECRET"]
-@accounts.redirect_uri = ENV["SPOTIFY_REDIRECT_URI"]
+@accounts.client_id = "spotify client ID"
+@accounts.client_secret = "spotify client secret"
+@accounts.redirect_uri = "redirect URI"
 ```
 
+Alternatively, these credentials can be supplied as environment variables when running your application:
+
+```ruby
+@accounts = Spotify::Accounts.new # fetches configuration from ENV
+```
+
+The respective environment variables you'll need to set are:
+
+| Environment Variable     | Description                               | Required?     |
+| ------------------------ | ----------------------------------------- | ------------- |
+| `SPOTIFY_CLIENT_ID`      | Your Spotify Client ID                    | **Yes**       |
+| `SPOTIFY_CLIENT_SECRET`  | Your Spotify Client Secret                | **Yes**       |
+| `SPOTIFY_REDIRECT_URI`   | Your Spotify Redirect URI (must be exact) | **Yes**       |
+
 ### Authorization
 
 In order to use Spotify's APIs on a user's behalf, you'll need to use the Spotify [Accounts API] to redirect them to `https://accounts.spotify.com`. They will then need to explicitly approve your application and what data you're asking for (technically referred to as authorization scopes).
@@ -168,7 +184,7 @@ To create an instance of the Spotify SDK, you'll need the `@session` from above
 @sdk = Spotify::SDK.new(@session)
 ```
 
-### Spotify Connect
+### Spotify Connect API
 
 With [Spotify Connect], you can take your music experience anywhere on over 300 devices. And you can read and control most devices programmatically through the SDK:
 
@@ -213,6 +229,98 @@ With [Spotify Connect], you can take your music experience anywhere on over 300
 @sdk.connect.devices[0].repeat_mode = :context
 ```
 
+#### Transfer playback\*
+
+This will transfer state, and start playback.
+
+```ruby
+@sdk.connect.devices[0].transfer_playback!
+```
+
+#### Transfer state\*
+
+This will transfer state, and pause playback.
+
+```ruby
+@sdk.connect.devices[0].transfer_state!
+```
+
+### Me API
+
+This allows you to perform specific actions on behalf of a user.
+
+#### My information\*
+
+```ruby
+@sdk.me.info
+@sdk.me.info.free? # => false
+@sdk.me.info.premium? # => true
+@sdk.me.info.birthdate # => 1980-01-01
+@sdk.me.info.display_name? # => true
+@sdk.me.info.display_name # => "ABC Smith"
+@sdk.me.info.images[0].url # => "https://profile-images.scdn.co/userprofile/default/..."
+@sdk.me.info.followers # => 4913313
+@sdk.me.info.spotify_uri # => "spotify:user:abcsmith"
+@sdk.me.info.spotify_url # => "https://open.spotify.com/user/abcsmith"
+```
+
+### Listening History API
+
+#### My recently played tracks (up to last 50)\*
+
+```ruby
+@sdk.me.history(10) # => [#<Spotify::SDK::Item...>, ...]
+@sdk.me.history(10).size # => 10
+@sdk.me.history(50) # => [#<Spotify::SDK::Item...>, ...]
+@sdk.me.history(50).size # => 50
+```
+
+### Following API
+
+#### Follow an artist\*
+
+```ruby
+@sdk.playback.item.artist.follow!
+```
+
+#### Unfollow an artist\*
+
+```ruby
+@sdk.playback.item.artist.unfollow!
+```
+
+#### Check if following Spotify artists?\*
+
+```ruby
+@sdk.me.following_artists?(%w(3TVXtAsR1Inumwj472S9r4 6LuN9FCkKOj5PcnpouEgny 69GGBxA162lTqCwzJG5jLp))
+# => {
+#   "3TVXtAsR1Inumwj472S9r4" => false,
+#   "6LuN9FCkKOj5PcnpouEgny" => true,
+#   "69GGBxA162lTqCwzJG5jLp" => false
+# }
+```
+
+#### Check if following Spotify users?\*
+
+```ruby
+@sdk.me.following_users?(%w(3TVXtAsR1Inumwj472S9r4 6LuN9FCkKOj5PcnpouEgny 69GGBxA162lTqCwzJG5jLp))
+# => {
+#   "3TVXtAsR1Inumwj472S9r4" => false,
+#   "6LuN9FCkKOj5PcnpouEgny" => true,
+#   "69GGBxA162lTqCwzJG5jLp" => false
+# }
+```
+
+#### See all followed artists\*
+
+```ruby
+@sdk.me.following(5) # => [#<Spotify::SDK::Artist...>, ...]
+@sdk.me.following(5).size # => 5
+@sdk.me.following(50) # => [#<Spotify::SDK::Artist...>, ...]
+@sdk.me.following(50).size # => 50
+```
+
+
 <small><i>\* Requires specific user permissions/scopes. See [Authorization Scopes] for more information.</i></small>
 
 ## Contributing
@@ -252,16 +360,6 @@ For local development, you can run `bin/console` for an interactive prompt for e
   - Push git commits and tags
   - Push the `.gem` file to [rubygems.org].
 
-### Changelog
-
-```
-[2018-07-21] (0.2.1) First major release.
-- Support for Connect and User API endpoints.
-- Transitioned to YARD for documentation.
-- Website built using Jekyll with Contributing guide.
-- Removed Coveralls in favour for CodeClimate
-```
-
 ## License
 
 The gem is available as open source under the terms of the [MIT License].

data/lib/spotify/accounts.rb

@@ -51,14 +51,17 @@ module Spotify
     #   @accounts.client_secret = "[client secret goes here]"
     #   @accounts.redirect_uri = "http://localhost"
     #
+    #   # with SPOTIFY_CLIENT_ID, SPOTIFY_CLIENT_SECRET, and SPOTIFY_REDIRECT_URI in ENV:
+    #   @accounts = Spotify::Accounts.new
+    #
     # @param [Hash] config The configuration containing your Client ID, Client Secret, and your Redirect URL.
     #
     # @see https://developer.spotify.com/dashboard/
     #
     def initialize(config={})
-      @client_id = config.delete(:client_id)
-      @client_secret = config.delete(:client_secret)
-      @redirect_uri = config.delete(:redirect_uri)
+      @client_id = config.delete(:client_id) { ENV["SPOTIFY_CLIENT_ID"] }
+      @client_secret = config.delete(:client_secret) { ENV["SPOTIFY_CLIENT_SECRET"] }
+      @redirect_uri = config.delete(:redirect_uri) { ENV["SPOTIFY_REDIRECT_URI"] }
     end
 
     attr_accessor :client_id, :client_secret, :redirect_uri

data/lib/spotify/sdk/connect/playback_state.rb

@@ -133,7 +133,7 @@ module Spotify
         #
         def item
           raise "Playback information is not available if user has a private session enabled" if device.private_session?
-          Spotify::SDK::Item.new(super, parent)
+          Spotify::SDK::Item.new(to_h, parent)
         end
       end
     end

data/lib/spotify/sdk/item.rb

@@ -3,6 +3,18 @@
 module Spotify
   class SDK
     class Item < Model
+      ##
+      # Let's transform the item object into better for us.
+      # Before: { track: ..., played_at: ..., context: ... }
+      # After: { track_properties..., played_at: ..., context: ... }
+      #
+      # :nodoc:
+      def initialize(payload, parent)
+        track      = payload.delete(:track) || payload.delete(:item)
+        properties = payload.except(:parent, :device, :repeat_state, :shuffle_state)
+        super(track.merge(properties: properties), parent)
+      end
+
       ##
       # Get the album for this item.
       #
@@ -41,6 +53,17 @@ module Spotify
         artists.first
       end
 
+      ##
+      # Get the context.
+      #
+      # @example
+      #   @sdk.connect.playback.item.context
+      #   @sdk.me.history[0].context
+      #
+      # @return [Hash] context Information about the user's context.
+      #
+      alias_attribute :context, "properties.context"
+
       ##
       # Get the duration.
       # Alias to self.duration_ms

data/lib/spotify/sdk/me.rb

@@ -22,9 +22,47 @@ module Spotify
         Spotify::SDK::Me::Info.new(me_info, self)
       end
 
+      ##
+      # Check what tracks a user has recently played.
+      #
+      # @example
+      #   @sdk.me.history
+      #   @sdk.me.history(20)
+      #
+      # @param [Integer] limit How many results to request. Defaults to 10.
+      # @param [Hash] override_opts Custom options for HTTParty.
+      # @return [Array] response List of recently played tracked, in chronological order.
+      #
+      def history(n=10, override_opts={})
+        request = {
+          method:    :get,
+          http_path: "/v1/me/player/recently-played",
+          keys:      %i[items],
+          limit:     n
+        }
+
+        send_multiple_http_requests(request, override_opts).map do |item|
+          Spotify::SDK::Item.new(item, self)
+        end
+      end
+
       ##
       # Check if the current user is following N users.
       #
+      # @example
+      #   artists = %w(3q7HBObVc0L8jNeTe5Gofh 0NbfKEOTQCcwd6o7wSDOHI 3TVXtAsR1Inumwj472S9r4)
+      #   @sdk.me.following?(artists, :artist)
+      #     # => {"3q7HBObVc0L8jNeTe5Gofh" => false, "0NbfKEOTQCcwd6o7wSDOHI" => false, ...}
+      #
+      #   users = %w(3q7HBObVc0L8jNeTe5Gofh 0NbfKEOTQCcwd6o7wSDOHI 3TVXtAsR1Inumwj472S9r4)
+      #   @sdk.me.following?(users, :user)
+      #     # => {"3q7HBObVc0L8jNeTe5Gofh" => false, "0NbfKEOTQCcwd6o7wSDOHI" => false, ...}
+      #
+      # @param [Array] list List of Spotify user/artist IDs. Cannot mix user and artist IDs in single request.
+      # @param [Symbol] type Either :user or :artist. Checks if follows respective type of account.
+      # @param [Hash] override_opts Custom options for HTTParty.
+      # @return [Hash] hash A hash containing a key with the ID, and a value that equals is_following (boolean).
+      #
       def following?(list, type=:artist, override_opts={})
         raise "Must contain an array" unless list.is_a?(Array)
         raise "Must contain an array of String or Spotify::SDK::Artist" if any_of?(list, [String, Spotify::SDK::Artist])
@@ -32,6 +70,14 @@ module Spotify
         send_is_following_http_requests(list.map {|id| id.try(:id) || id }, type, override_opts)
       end
 
+      def following_artists?(list, override_opts={})
+        following?(list, :artist, override_opts)
+      end
+
+      def following_users?(list, override_opts={})
+        following?(list, :user, override_opts)
+      end
+
       ##
       # Get the current user's followed artists. Requires the `user-read-follow` scope.
       # GET /v1/me/following
@@ -39,22 +85,52 @@ module Spotify
       # @example
       #   @sdk.me.following
       #
+      # @param [Integer] n Number of results to return.
       # @param [Hash] override_opts Custom options for HTTParty.
       # @return [Array] artists A list of followed artists, wrapped in Spotify::SDK::Artist
       #
-      def following(override_opts={})
-        artists = send_following_http_requests("/v1/me/following?type=artist&limit=50", override_opts)
-        artists.map do |artist|
+      def following(n=50, override_opts={})
+        request = {
+          method:    :get,
+          # TODO: Spotify API bug - `limit={n}` returns n-1 artists.
+          # ^ Example: `limit=5` returns 4 artists.
+          # TODO: Support `type=users` as well as `type=artists`.
+          http_path: "/v1/me/following?type=artist&limit=#{[n, 50].min}",
+          keys:      %i[artists items],
+          limit:     n
+        }
+
+        send_multiple_http_requests(request, override_opts).map do |artist|
           Spotify::SDK::Artist.new(artist, self)
         end
       end
 
       private
 
-      def any_of?(array, klasses)
+      def any_of?(array, klasses) # :nodoc:
         (array.map(&:class) - klasses).any?
       end
 
+      def send_multiple_http_requests(opts, override_opts) # :nodoc:
+        response = send_http_request(opts[:method], opts[:http_path], override_opts)
+        responses, next_request = hash_deep_lookup(response, opts[:keys].dup)
+        if next_request && responses.size < opts[:limit]
+          responses += send_multiple_http_requests(opts.merge(http_path: next_request), override_opts)
+        end
+        responses.first(opts[:limit])
+      end
+
+      def hash_deep_lookup(response, keys) # :nodoc:
+        error_message = "Cannot find '%s' key in Spotify::SDK::Me#hash_deep_lookup"
+        while keys.any?
+          next_request ||= response[:next]
+          next_key = keys.shift
+          response = next_key ? response[next_key] : raise(error_message % next_key)
+        end
+        [response, next_request ? next_request[23..-1] : nil]
+      end
+
+      # TODO: Migrate this into the abstracted send_multiple_http_requests
       def send_is_following_http_requests(list, type, override_opts) # :nodoc:
         max_ids = list.first(50)
         remaining_ids = list - max_ids
@@ -71,13 +147,6 @@ module Spotify
           ids.merge(send_is_following_http_requests(remaining_ids, type, override_opts))
         end || ids
       end
-
-      def send_following_http_requests(http_path, override_opts) # :nodoc:
-        request = send_http_request(:get, http_path, override_opts)[:artists]
-        artists = request[:items]
-        artists << send_following_http_requests(request[:next][23..-1], override_opts) if request[:next]
-        artists.flatten
-      end
     end
   end
 end

data/lib/spotify/version.rb

@@ -12,5 +12,5 @@ module Spotify
   # MINOR version when you add functionality in a backwards-compatible manner, and
   # PATCH version when you make backwards-compatible bug fixes.
   #
-  VERSION = "0.2.2"
+  VERSION = "0.2.3"
 end

data/spotify-ruby.gemspec

@@ -35,6 +35,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "rake", "~> 12.1"
 
   # Testing
+  spec.add_development_dependency "climate_control", "~> 0.2"
   spec.add_development_dependency "factory_bot", "~> 1.0.0.alpha"
   spec.add_development_dependency "rspec", "~> 3.7"
   spec.add_development_dependency "rspec-collection_matchers", "~> 1.1", ">= 1.1.2"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: spotify-ruby
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.2.3
 platform: ruby
 authors:
 - Bilawal Hameed
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-07-25 00:00:00.000000000 Z
+date: 2018-08-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -44,6 +44,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '12.1'
+- !ruby/object:Gem::Dependency
+  name: climate_control
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
 - !ruby/object:Gem::Dependency
   name: factory_bot
   requirement: !ruby/object:Gem::Requirement