Recently played tracks: Implement @sdk.me.history (#57)

- Implemented `Spotify::SDK::Me#history` which calls `GET /v1/me/player/recently-played`
- Made non-breaking changes to `Spotify::SDK::Item` which transforms payloads to insert other-relevant information in `properties` such as `context` and `played_at`.
- Added a `Spotify::SDK::Item#context` alias to `Spotify::SDK::Item#properties[:context]`

Author: bih

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
 

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
@@ -182,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:
 
@@ -227,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
@@ -266,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].

lib/spotify/sdk/connect/playback_state.rb

@@ -133,7 +133,7 @@ def artist
         #
         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

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 @@ def artist
         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

lib/spotify/sdk/me.rb

@@ -22,39 +22,115 @@ def info(override_opts={})
         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])
         raise "type must be either 'artist' or 'user'" unless %i[artist user].include?(type)
         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
       #
       # @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 @@ def send_is_following_http_requests(list, type, override_opts) # :nodoc:
           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

spec/lib/spotify/sdk/connect/playback_state_spec.rb

@@ -131,7 +131,11 @@
       end
 
       it "sends the correct information" do
-        expect(subject.item.to_h).to eq raw_data[:item]
+        item_data  = raw_data.dup
+        track      = item_data.delete(:track) || item_data.delete(:item)
+        properties = item_data.except(:parent, :device, :repeat_state, :shuffle_state)
+
+        expect(subject.item.to_h).to eq track.merge(properties: properties)
       end
     end
   end