rspotify 1.9.1 → 1.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0e1815c6ec7f721220d003f5f6d9008a40d7f727
-  data.tar.gz: d622ad7f253308753c81cad880116d39863d6b83
+  metadata.gz: 5468375f8403d6bbbceb4c409783c60938eeddf5
+  data.tar.gz: 57ff23567b2a528f62487f06ebaaa869eb37c5bf
 SHA512:
-  metadata.gz: c55bb95033ed25c0de7a22da0016c07a2409173e0f9303e959a7ddc23d75bf1ced45285af3953f0d49678d5fb7a9506d92301dd70aa789be2f86fc310ee3f7cc
-  data.tar.gz: 0c37346ee7bc3e07e8a05411a8481d6ae73a9da222dd698bfee8a981c44f5325fb6f29ac241aecc84c0e216b3556bdd788f59bcbdce31719177d4dcaecb30e34
+  metadata.gz: 0cba7bfcfdd1a430e76e0204515246373a8e47f32f1fc2caf6cac254c0d46e4a6d5137cce0d9e09a2cdce36eee420d1704d9c25f14d45e986add1706d33f2b1f
+  data.tar.gz: ebf800d7a4317423ce2e1960359c4e3a59439063f7ee504cba3f74c831378d06b17821c0ab2b151b24388a5afbfdbcf23798d268a88c2014c5ee5a347377b25c

data/README.md

@@ -7,7 +7,7 @@ This is a ruby wrapper for the [new Spotify Web API](https://developer.spotify.c
 
 ## Features
 
-* [Full documentation](http://rdoc.info/github/guilhermesad/rspotify/master/frames)
+* [Full documentation](http://www.rubydoc.info/github/guilhermesad/rspotify/master)
 * Full API Endpoint coverage
 * OAuth and other authorization flows
 

data/lib/rspotify/album.rb

@@ -48,7 +48,7 @@ module RSpotify
       json['albums']['items'].map { |i| Album.new i }
     end
 
-    # Returns array of Album objects matching the query, ordered by popularity
+    # Returns array of Album objects matching the query, ordered by popularity. It's also possible to find the total number of search results for the query
     #
     # @param query  [String]       The search query's keywords. For details access {https://developer.spotify.com/web-api/search-item here} and look for the q parameter description.
     # @param limit  [Integer]      Maximum number of albums to return. Maximum: 50. Default: 20.
@@ -60,6 +60,8 @@ module RSpotify
     #           albums = RSpotify::Album.search('AM')
     #           albums = RSpotify::Album.search('AM', limit: 10, market: 'US')
     #           albums = RSpotify::Album.search('AM', market: { from: user })
+    #
+    #           RSpotify::Album.search('AM').total #=> 9374
     def self.search(query, limit: 20, offset: 0, market: nil)
       super(query, 'album', limit: limit, offset: offset, market: market)
     end

data/lib/rspotify/artist.rb

@@ -25,7 +25,7 @@ module RSpotify
       super(ids, 'artist')
     end
 
-    # Returns array of Artist objects matching the query, ordered by popularity
+    # Returns array of Artist objects matching the query, ordered by popularity. It's also possible to find the total number of search results for the query
     #
     # @param query  [String]       The search query's keywords. For details access {https://developer.spotify.com/web-api/search-item here} and look for the q parameter description.
     # @param limit  [Integer]      Maximum number of artists to return. Maximum: 50. Default: 20.
@@ -37,6 +37,8 @@ module RSpotify
     #           artists = RSpotify::Artist.search('Arctic')
     #           artists = RSpotify::Artist.search('Arctic', limit: 10, market: 'US')
     #           artists = RSpotify::Artist.search('Arctic', market: { from: user })
+    #
+    #           RSpotify::Artist.search('Arctic').total #=> 86
     def self.search(query, limit: 20, offset: 0, market: nil)
       super(query, 'artist', limit: limit, offset: offset, market: market)
     end

data/lib/rspotify/base.rb

@@ -53,7 +53,20 @@ module RSpotify
     end
     private_class_method :find_one
 
-    # Returns array of RSpotify objects matching the query, ordered by popularity
+    def self.insert_total(result, types, json)
+      result.instance_eval do
+        @total = types.map do |type|
+          json["#{type}s"]['total']
+        end.reduce(:+)
+
+        define_singleton_method :total do
+          @total
+        end
+      end
+    end
+    private_class_method :insert_total
+
+    # Returns array of RSpotify objects matching the query, ordered by popularity. It's also possible to find the total number of search results for the query
     #
     # @param query  [String]       The search query's keywords. For details access {https://developer.spotify.com/web-api/search-item here} and look for the q parameter description.
     # @param types  [String]       Valid types are: album, artist, track and playlist. Separate multiple types with commas.
@@ -67,6 +80,8 @@ module RSpotify
     #           albums  = RSpotify::Base.search('AM', 'album', limit: 10, market: 'US')
     #           mixed   = RSpotify::Base.search('Arctic', 'artist, album, track')
     #           albums  = RSpotify::Base.search('AM', 'album', market: { from: user })
+    #
+    #           RSpotify::Base.search('Arctic', 'album,artist,playlist').total #=> 2142
     def self.search(query, types, limit: 20, offset: 0, market: nil)
       query = URI::encode query
       types.gsub!(/\s+/, '')
@@ -82,10 +97,14 @@ module RSpotify
         RSpotify.get(url)
       end
 
-      types.split(',').flat_map do |type|
+      types = types.split(',')
+      result = types.flat_map do |type|
         type_class = RSpotify.const_get(type.capitalize)
         json["#{type}s"]['items'].map { |i| type_class.new i }
       end
+
+      insert_total(result, types, json)
+      result
     end
 
     def initialize(options = {})
@@ -137,5 +156,17 @@ module RSpotify
       return true if instance_variable_defined? attr
       super
     end
+    
+    protected
+    
+    def hash_for(tracks, field)
+      return nil unless tracks
+      pairs = tracks.map do |track|
+        key = track['track']['id']
+        value = yield track[field] if track[field]
+        [key, value]
+      end
+      Hash[pairs]
+    end
   end
 end

data/lib/rspotify/playlist.rb

@@ -8,8 +8,9 @@ module RSpotify
   # @attr [User]        owner           The user who owns the playlist
   # @attr [Boolean]     public          true if the playlist is not marked as secret
   # @attr [String]      snapshot_id     The version identifier for the current playlist. Can be supplied in other requests to target a specific playlist version
-  # @attr [Hash]        tracks_added_at A hash containing the date and time each track was added to the playlist. Note: whenever {#tracks} is used the hash is updated with the correspondent tracks' values.
-  # @attr [Hash]        tracks_added_by A hash containing the user that added each track to the playlist. Note: whenever {#tracks} is used the hash is updated with the correspondent tracks' values.
+  # @attr [Integer]     total           The total number of tracks in the playlist
+  # @attr [Hash]        tracks_added_at A hash containing the date and time each track was added to the playlist. Note: the hash is updated only when {#tracks} is used.
+  # @attr [Hash]        tracks_added_by A hash containing the user that added each track to the playlist. Note: the hash is updated only when {#tracks} is used.
   class Playlist < Base
 
     # Get a list of Spotify featured playlists (shown, for example, on a Spotify player’s “Browse” tab).
@@ -54,7 +55,7 @@ module RSpotify
       Playlist.new json
     end
 
-    # Returns array of Playlist objects matching the query
+    # Returns array of Playlist objects matching the query. It's also possible to find the total number of search results for the query
     #
     # @param query  [String]  The search query's keywords. See the q description in {https://developer.spotify.com/web-api/search-item here} for details.
     # @param limit  [Integer] Maximum number of playlists to return. Maximum: 50. Default: 20.
@@ -63,12 +64,9 @@ module RSpotify
     #
     # @example
     #           playlists = RSpotify::Playlist.search('Indie')
-    #           playlists.size        #=> 20
-    #           playlists.first.class #=> RSpotify::Playlist
-    #           playlists.first.name  #=> "The Indie Mix"
-    #
     #           playlists = RSpotify::Playlist.search('Indie', limit: 10)
-    #           playlists.size #=> 10
+    #
+    #           RSpotify::Playlist.search('Indie').total #=> 14653
     def self.search(query, limit: 20, offset: 0)
       super(query, 'playlist', limit: limit, offset: offset)
     end
@@ -81,6 +79,7 @@ module RSpotify
       @name          = options['name']
       @public        = options['public']
       @snapshot_id   = options['snapshot_id']
+      @total         = options['tracks']['total']
 
       @owner = if options['owner']
         User.new options['owner']
@@ -127,7 +126,9 @@ module RSpotify
       url << "&position=#{position}" if position
 
       User.oauth_post(@owner.id, url, {})
+      @total += tracks.size
       @tracks_cache = nil
+
       tracks
     end
 
@@ -214,21 +215,13 @@ module RSpotify
     def replace_tracks!(tracks)
       track_uris = tracks.map(&:uri).join(',')
       url = @href + "/tracks?uris=#{track_uris}"
+
       User.oauth_put(@owner.id, url, {})
+      @total = tracks.size
       @tracks_cache = nil
+
       tracks
     end
 
-    private
-
-    def hash_for(tracks, field)
-      return nil unless tracks
-      pairs = tracks.map do |track|
-        key = track['track']['id']
-        value = yield track[field] if track[field]
-        [key, value]
-      end
-      Hash[pairs]
-    end
   end
 end

data/lib/rspotify/track.rb

@@ -31,7 +31,7 @@ module RSpotify
       super(ids, 'track')
     end
 
-    # Returns array of Track objects matching the query, ordered by popularity
+    # Returns array of Track objects matching the query, ordered by popularity. It's also possible to find the total number of search results for the query
     #
     # @param query  [String]       The search query's keywords. For details access {https://developer.spotify.com/web-api/search-item here} and look for the q parameter description.
     # @param limit  [Integer]      Maximum number of tracks to return. Maximum: 50. Default: 20.
@@ -43,6 +43,8 @@ module RSpotify
     #           tracks = RSpotify::Track.search('Wanna Know')
     #           tracks = RSpotify::Track.search('Wanna Know', limit: 10, market: 'US')
     #           tracks = RSpotify::Track.search('Wanna Know', market: { from: user })
+    #
+    #           RSpotify::Track.search('Wanna Know').total #=> 3686
     def self.search(query, limit: 20, offset: 0, market: nil)
       super(query, 'track', limit: limit, offset: offset, market: market)
     end

data/lib/rspotify/user.rb

@@ -1,12 +1,13 @@
 module RSpotify
 
-  # @attr [String] country      The country of the user, as set in the user's account profile. An {http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 ISO 3166-1 alpha-2 country code}. This field is only available when the current user has granted access to the *user-read-private* scope.
-  # @attr [Hash]   credentials  The credentials generated for the user with OAuth. Includes access token, token type, token expiration time and refresh token. This field is only available when the current user has granted access to any scope.
-  # @attr [String] display_name The name displayed on the user's profile. This field is only available when the current user has granted access to the *user-read-private* scope.
-  # @attr [String] email        The user's email address. This field is only available when the current user has granted access to the *user-read-email* scope.
-  # @attr [Hash]   followers    Information about the followers of the user
-  # @attr [Array]  images       The user's profile image. This field is only available when the current user has granted access to the *user-read-private* scope.
-  # @attr [String] product      The user's Spotify subscription level: "premium", "free", etc. This field is only available when the current user has granted access to the *user-read-private* scope.
+  # @attr [String] country         The country of the user, as set in the user's account profile. An {http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 ISO 3166-1 alpha-2 country code}. This field is only available when the current user has granted access to the *user-read-private* scope.
+  # @attr [Hash]   credentials     The credentials generated for the user with OAuth. Includes access token, token type, token expiration time and refresh token. This field is only available when the current user has granted access to any scope.
+  # @attr [String] display_name    The name displayed on the user's profile. This field is only available when the current user has granted access to the *user-read-private* scope.
+  # @attr [String] email           The user's email address. This field is only available when the current user has granted access to the *user-read-email* scope.
+  # @attr [Hash]   followers       Information about the followers of the user
+  # @attr [Array]  images          The user's profile image. This field is only available when the current user has granted access to the *user-read-private* scope.
+  # @attr [String] product         The user's Spotify subscription level: "premium", "free", etc. This field is only available when the current user has granted access to the *user-read-private* scope.
+  # @attr [Hash]   tracks_added_at A hash containing the date and time each track was saved by the user. Note: the hash is filled and updated only when {#saved_tracks} is used.
   class User < Base
 
     # Returns User object with id provided
@@ -105,9 +106,44 @@ module RSpotify
       Playlist.new User.oauth_post(@id, url, request_data)
     end
 
+    # Add the current user as a follower of one or more artists or other Spotify users. This method
+    # is only available when the current user has granted access to the *user-follow-modify* scope.
+    #
+    # @param followed [Array<User>, Array<Artist>] The users or artists to follow
+    # @return [Array<User>, Array<Artist>]
+    #
+    # @example
+    #           artists = RSpotify::Artist.search('John')
+    #           user.follow(artists)
+    def follow(followed)
+      type = followed.first.type
+      ids  = followed.map(&:id).join(',')
+      url = "me/following?type=#{type}&ids=#{ids}"
+
+      User.oauth_put(@id, url, {})
+      followed
+    end
+
+    # Check to see if the current user is following one or more artists or other Spotify users. This method
+    # is only available when the current user has granted access to the *user-follow-read* scope.
+    #
+    # @param followed [Array<User>, Array<Artist>] The users or artists to check
+    # @return [Array<Boolean>]
+    #
+    # @example
+    #           artists = RSpotify::Artist.search('John')
+    #           user.follows?(artists) #=> [true, false, true...]
+    def follows?(followed)
+      type = followed.first.type
+      ids  = followed.map(&:id).join(',')
+      url = "me/following/contains?type=#{type}&ids=#{ids}"
+
+      User.oauth_get(@id, url)
+    end
+
     # Returns all playlists from user
     #
-    # @param limit  [Integer] Maximum number of playlists to return. Maximum: 50. Default: 20.
+    # @param limit  [Integer] Maximum number of playlists to return. Maximum: 50. Minimum: 1. Default: 20.
     # @param offset [Integer] The index of the first playlist to return. Use with limit to get the next set of playlists. Default: 0.
     # @return [Array<Playlist>]
     #
@@ -161,7 +197,7 @@ module RSpotify
 
     # Returns the tracks saved in the Spotify user’s “Your Music” library
     #
-    # @param limit  [Integer] Maximum number of tracks to return. Maximum: 50. Default: 20.
+    # @param limit  [Integer] Maximum number of tracks to return. Maximum: 50. Minimum: 1. Default: 20.
     # @param offset [Integer] The index of the first track to return. Use with limit to get the next set of tracks. Default: 0.
     # @return [Array<Track>]
     #
@@ -172,7 +208,13 @@ module RSpotify
     def saved_tracks(limit: 20, offset: 0)
       url = "me/tracks?limit=#{limit}&offset=#{offset}"
       json = User.oauth_get(@id, url)
-      json['items'].map { |i| Track.new i['track'] }
+      
+      tracks = json['items'].select { |i| i['track'] }
+      @tracks_added_at = hash_for(tracks, 'added_at') do |added_at|
+        Time.parse added_at
+      end
+
+      tracks.map { |t| Track.new t['track'] }
     end
 
     # Check if tracks are already saved in the Spotify user’s “Your Music” library
@@ -196,5 +238,23 @@ module RSpotify
       end
       Hash[pairs]
     end
+
+    # Remove the current user as a follower of one or more artists or other Spotify users. This method
+    # is only available when the current user has granted access to the *user-follow-modify* scope.
+    #
+    # @param followed [Array<User>, Array<Artist>] The users or artists to unfollow
+    # @return [Array<User>, Array<Artist>]
+    #
+    # @example
+    #           artists = RSpotify::Artist.search('John')
+    #           user.unfollow(artists)
+    def unfollow(unfollowed)
+      type = unfollowed.first.type
+      ids  = unfollowed.map(&:id).join(',')
+      url = "me/following?type=#{type}&ids=#{ids}"
+
+      User.oauth_delete(@id, url)
+      unfollowed
+    end
   end
 end

data/lib/rspotify/version.rb

@@ -1,3 +1,3 @@
 module RSpotify
-  VERSION = '1.9.1'
+  VERSION = '1.10.0'
 end

data/spec/lib/rspotify/album_spec.rb

@@ -106,6 +106,7 @@ describe RSpotify::Album do
       end
       expect(albums)             .to be_an Array
       expect(albums.size)        .to eq 20
+      expect(albums.total)       .to eq 8672
       expect(albums.first)       .to be_an RSpotify::Album
       expect(albums.map(&:name)) .to include('AM', 'Am I Wrong', 'A.M.', 'Melody AM')
     end

data/spec/lib/rspotify/artist_spec.rb

@@ -81,6 +81,7 @@ describe RSpotify::Artist do
       end
       expect(artists)             .to be_an Array
       expect(artists.size)        .to eq 20
+      expect(artists.total)       .to eq 81
       expect(artists.first)       .to be_an RSpotify::Artist
       expect(artists.map(&:name)) .to include('Arctic Monkeys', 'Arctic', 'Arctic Warbler', 'Arctic Express')
     end

data/spec/lib/rspotify/playlist_spec.rb

@@ -17,7 +17,7 @@ describe RSpotify::Playlist do
 
   describe 'Playlist::browse_featured' do
     it 'should find the appropriate featured playlists' do
-      playlists = VCR.use_cassette('playlist:browse_featured') do 
+      playlists = VCR.use_cassette('playlist:browse_featured') do
         RSpotify::Playlist.browse_featured
       end
       expect(playlists.size)        .to eq 13
@@ -25,19 +25,19 @@ describe RSpotify::Playlist do
     end
 
     it 'should accept additional options' do
-      playlists = VCR.use_cassette('playlist:browse_featured:limit:10:offset:10') do 
+      playlists = VCR.use_cassette('playlist:browse_featured:limit:10:offset:10') do
         RSpotify::Playlist.browse_featured(limit: 10, offset: 10)
       end
       expect(playlists.size)        .to eq 3
       expect(playlists.map(&:name)) .to include('Sleep', 'Late Night R&B')
 
-      playlists = VCR.use_cassette('playlist:browse_featured:locale:es_MX') do 
+      playlists = VCR.use_cassette('playlist:browse_featured:locale:es_MX') do
         RSpotify::Playlist.browse_featured(locale: 'es_MX')
       end
       expect(playlists.size)        .to eq 13
       expect(playlists.map(&:name)) .to include('Dance Mega Mix', 'Peaceful Piano', 'Sleep')
 
-      playlists = VCR.use_cassette('playlist:browse_featured:country:ES:timestamp:2014-10-23T09:00:00') do 
+      playlists = VCR.use_cassette('playlist:browse_featured:country:ES:timestamp:2014-10-23T09:00:00') do
         RSpotify::Playlist.browse_featured(country: 'ES', timestamp: '2014-10-23T09:00:00')
       end
       expect(playlists.size)        .to eq 17
@@ -65,6 +65,7 @@ describe RSpotify::Playlist do
       expect(playlist.name)                     .to eq    'Movie Soundtrack Masterpieces'
       expect(playlist.public)                   .to eq    true
       expect(playlist.snapshot_id)              .to eq    'ViCZCcnhRtzkGq09wO4OPxvC/UBP/ZqMjrmTYoNurZ706SIXyMJiKb/zj27NYjiP'
+      expect(playlist.total)                    .to eq    53
       expect(playlist.type)                     .to eq    'playlist'
       expect(playlist.uri)                      .to eq    'spotify:user:wizzler:playlist:00wHcTN0zQiun4xri9pmvX'
     end
@@ -104,37 +105,39 @@ describe RSpotify::Playlist do
 
     context 'starred playlist' do
       it "should support starred playlists" do
-        expect(starred_playlist.name).to eq 'Starred'
-        expect(starred_playlist.href).to eq 'https://api.spotify.com/v1/users/118430647/starred'
+        expect(starred_playlist.name) .to eq 'Starred'
+        expect(starred_playlist.href) .to eq 'https://api.spotify.com/v1/users/118430647/starred'
+        expect(starred_playlist.total).to eq 185
       end
     end
   end
 
   describe 'Playlist::search' do
     it 'should search for the right playlists' do
-      playlists = VCR.use_cassette('playlist:search:Indie') do 
+      playlists = VCR.use_cassette('playlist:search:Indie') do
         RSpotify::Playlist.search('Indie')
       end
       expect(playlists)             .to be_an Array
       expect(playlists.size)        .to eq 20
+      expect(playlists.total)       .to eq 14027
       expect(playlists.first)       .to be_an RSpotify::Playlist
       expect(playlists.map(&:name)) .to include('The Indie Mix', 'Indie Folk', 'Alt/Indie')
     end
 
     it 'should accept additional options' do
-      playlists = VCR.use_cassette('playlist:search:Indie:limit:10') do 
+      playlists = VCR.use_cassette('playlist:search:Indie:limit:10') do
         RSpotify::Playlist.search('Indie', limit: 10)
       end
       expect(playlists.size)        .to eq 10
       expect(playlists.map(&:name)) .to include('The Indie Mix', 'Indie Folk')
 
-      playlists = VCR.use_cassette('playlist:search:Indie:offset:10') do 
+      playlists = VCR.use_cassette('playlist:search:Indie:offset:10') do
         RSpotify::Playlist.search('Indie', offset: 10)
       end
       expect(playlists.size)        .to eq 20
       expect(playlists.map(&:name)) .to include('Indie Workout', 'Indie Brunch')
 
-      playlists = VCR.use_cassette('playlist:search:Indie:offset:10:limit:10') do 
+      playlists = VCR.use_cassette('playlist:search:Indie:offset:10:limit:10') do
         RSpotify::Playlist.search('Indie', limit: 10, offset: 10)
       end
       expect(playlists.size)        .to eq 10
@@ -143,19 +146,27 @@ describe RSpotify::Playlist do
   end
 
   describe 'Playlist#tracks' do
+    use_vcr_cassette 'playlist:tracks:118430647:starred'
+
+    before { @tracks = starred_playlist.tracks(offset: 100, limit: 100) }
+
     it 'should fetch more tracks correctly' do
-      tracks = VCR.use_cassette('playlist:tracks:118430647:starred') do
-        starred_playlist.tracks(offset: 100, limit: 100)
-      end
-      expect(tracks)           .to be_an Array
-      expect(tracks.size)      .to eq 85
-      expect(tracks.last.name) .to eq 'On The Streets - Kollectiv Turmstrasse Let Freedom Ring Remix'
+      expect(@tracks)           .to be_an Array
+      expect(@tracks.size)      .to eq 85
+      expect(@tracks.last.name) .to eq 'On The Streets - Kollectiv Turmstrasse Let Freedom Ring Remix'
     end
   end
 
   describe 'Playlist#complete!' do
     let(:href) { 'https://api.spotify.com/v1/users/wizzler/playlists/00wHcTN0zQiun4xri9pmvX' }
-    let(:playlist) { RSpotify::Playlist.new('href' => href, 'owner' => {'id' => 'wizzler'}) }
+    let(:playlist) do
+      min_attrs = {
+        'href'   => href,
+        'owner'  => {'id' => 'wizzler'},
+        'tracks' => {'total' => 53 }
+      }
+      RSpotify::Playlist.new(min_attrs)
+    end
 
     it 'should fetch the complete information correctly' do
       VCR.use_cassette('playlist:find:wizzler:00wHcTN0zQiun4xri9pmvX') do

data/spec/lib/rspotify/track_spec.rb

@@ -70,6 +70,7 @@ describe RSpotify::Track do
       end
       expect(tracks)             .to be_an Array
       expect(tracks.size)        .to eq 20
+      expect(tracks.total)       .to eq 3565
       expect(tracks.first)       .to be_an RSpotify::Track
       expect(tracks.map(&:name)) .to include('Do I Wanna Know?', 'I Wanna Know', 'Never Wanna Know')
     end

data/spec/spec_helper.rb

@@ -30,4 +30,6 @@ RSpec.configure do |config|
 
     mocks.verify_partial_doubles = true
   end
+
+  config.extend VCR::RSpec::Macros
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rspotify
 version: !ruby/object:Gem::Version
-  version: 1.9.1
+  version: 1.10.0
 platform: ruby
 authors:
 - Guilherme Sad
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-12-14 00:00:00.000000000 Z
+date: 2015-01-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: omniauth-oauth2