rspotify 1.11.0 → 1.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5bb4cfacaa5e965c3790ff69e4fa1772779535c2
-  data.tar.gz: 937b66b4e61e143ea789c566618b01236d6f4739
+  metadata.gz: d9d5c7e14d9ebae07999a11a0e293ce040355f0f
+  data.tar.gz: 089a62b73d44f770ea208cb6fede0d1eb1a37351
 SHA512:
-  metadata.gz: 41e73ebfca07ffc53660f3c8e27d1172941bc092df5059206351823ad01571d9390068ca270c181dc3750c87d3fbf79ab038383731f324f12dcd9224be828551
-  data.tar.gz: 8cf584d541243c000a268c4fdc21ea87beb24fae06617298d6f69a49b22b632656939c81eb0d7542e529e7a43554b4219e2facee8e119c4fd3fb1d05fe50906e
+  metadata.gz: 25c6e98fb25ee1efe383e2c7cb92d6cafabb75c31b94e4e89a8545129f3c0b9e77291b9b8f20661ae0cd852f80242c07872e65442a4316e49c0c0853f0fab2cf
+  data.tar.gz: 000dfeb95573bdb35cdcaa9cbe1fd687f1dd86715167c453993b5d50847e496ec1ab06e4bd37cdda7ffb5bc94970605b637528d9a6cc148d73ea526235850dbf

data/README.md

@@ -27,7 +27,11 @@ Or install it yourself as:
 
 ## Usage
 
-Directly access Spotify public data such as albums, tracks, artists, playlists and users:
+RSpotify was designed with usability as its primary goal, so that you can forget the API and intuitively interact with your playlists, favorite artists, users and so on.
+
+You can write things like `playlist.tracks.sort_by(&:popularity).last.album` without having to think which API calls must be done. RSpotify fills the gaps for you.
+
+Below are some basic usage examples. Check the [documentation](http://rdoc.info/github/guilhermesad/rspotify/master/frames) for the complete reference.
 
 ```ruby
 require 'rspotify'
@@ -93,29 +97,28 @@ Then just copy and paste them like so:
 ```ruby
 RSpotify.authenticate("<your_client_id>", "<your_client_secret>")
 
-# Now you can access any public playlist in detail and much more
+# Now you can access playlists in detail, browse featured content and more
+
+wizzler = RSpotify::User.find('wizzler')
+wizzler.playlists #=> (Playlist array)
 
+# Find by id
 playlist = RSpotify::Playlist.find('wizzler', '00wHcTN0zQiun4xri9pmvX')
 playlist.name               #=> "Movie Soundtrack Masterpieces"
 playlist.description        #=> "Iconic soundtracks featured..."
 playlist.followers['total'] #=> 13
 playlist.tracks             #=> (Track array)
 
-# Get user's playlist
-my_user = RSpotify::User.find("my_user")
-my_playlists = my_user.playlists #=> (Playlist array)
+# Search by category
+party = RSpotify::Category.find('party')
+party.playlists #=> (Playlist array)
+categories = RSpotify::Category.list # See all available categories
 
 # Access featured content from Spotify's Browse tab
 featured_playlists = RSpotify::Playlist.browse_featured(country: 'US')
 new_releases = RSpotify::Album.new_releases(country: 'ES')
 ```
 
-RSpotify focuses on objects behaviour so you can forget the API and worry about your tracks, artists and so on.
-
-It is possible to write things like `playlist.tracks.sort_by(&:popularity).last.album` without having to think what API calls must be done. RSpotify fills the gaps for you.
-
-Check the [documentation](http://rdoc.info/github/guilhermesad/rspotify/master/frames) for all attributes and methods of albums, artists, etc.
-
 ## Rails + OAuth
 
 You'll may want your application to access an user's Spotify account.

data/lib/rspotify.rb

@@ -6,6 +6,7 @@ module RSpotify
   autoload :Album,    'rspotify/album'
   autoload :Artist,   'rspotify/artist'
   autoload :Base,     'rspotify/base'
+  autoload :Category, 'rspotify/category'
   autoload :Playlist, 'rspotify/playlist'
   autoload :Track,    'rspotify/track'
   autoload :User,     'rspotify/user'

data/lib/rspotify/base.rb

@@ -83,7 +83,7 @@ module RSpotify
     #
     #           RSpotify::Base.search('Arctic', 'album,artist,playlist').total #=> 2142
     def self.search(query, types, limit: 20, offset: 0, market: nil)
-      query = URI::encode query
+      query = CGI.escape query
       types.gsub!(/\s+/, '')
 
       url = "search?q=#{query}&type=#{types}"\

data/lib/rspotify/category.rb

@@ -0,0 +1,98 @@
+module RSpotify
+
+  # @attr [NilClass] external_urls Inexistent for Category.
+  # @attr [String]   href          A link to the Spotify Web API endpoint returning full details of the category.
+  # @attr [Array]    icons         An array of image objects. The category icons, in various sizes.
+  # @attr [String]   id            The {https://developer.spotify.com/web-api/user-guide/#spotify-uris-and-ids Spotify ID} of the category
+  # @attr [String]   name          The name of the category.
+  # @attr [NilClass] type          Inexistent for Category.
+  # @attr [NilClass] uri           Inexistent for Category.
+  class Category < Base
+
+    # Returns Category object with id provided
+    #
+    # @param id      [String] The {https://developer.spotify.com/web-api/user-guide/#spotify-uris-and-ids Spotify ID} of the category
+    # @param country [String] Optional. A country: an {http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 ISO 3166-1 alpha-2 country code}. Provide this parameter to ensure that the category exists for a particular country.
+    # @param locale  [String] Optional. The desired language, consisting of a lowercase {http://en.wikipedia.org/wiki/ISO_639 ISO 639 language code} and an uppercase {http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 ISO 3166-1 alpha-2 country code}, joined by an underscore. For details access {https://developer.spotify.com/web-api/get-category/ here} and look for the locale parameter description.
+    # @return [Category]
+    #
+    # @example
+    #           category = RSpotify::Category.find('party')
+    #           category = RSpotify::Category.find('party', country: 'US')
+    #           category = RSpotify::Category.find('party', locale: 'es_MX')
+    def self.find(id, **options)
+      url = "browse/categories/#{id}"
+      url << '?' if options.any?
+
+      options.each_with_index do |option, index|
+        url << "#{option[0]}=#{option[1]}"
+        url << '&' unless index == options.size-1
+      end
+
+      json = RSpotify.auth_get(url)
+      Category.new json
+    end
+
+    # Get a list of categories used to tag items in Spotify
+    #
+    # @param limit  [Integer] Optional. Maximum number of categories to return. Maximum: 50. Default: 20.
+    # @param offset [Integer] Optional. The index of the first category to return. Use with limit to get the next set of categories. Default: 0.
+    # @param country [String] Optional. A country: an {http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 ISO 3166-1 alpha-2 country code}. Provide this parameter if you want to narrow the list of returned categories to those relevant to a particular country. If omitted, the returned categories will be globally relevant.
+    # @param locale  [String] Optional. The desired language, consisting of a lowercase {http://en.wikipedia.org/wiki/ISO_639 ISO 639 language code} and an uppercase {http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 ISO 3166-1 alpha-2 country code}, joined by an underscore. For details access {https://developer.spotify.com/web-api/get-category/ here} and look for the locale parameter description.
+    # @return [Array<Category>]
+    #
+    # @example
+    #           categories = RSpotify::Category.list
+    #           categories = RSpotify::Category.list(country: 'US')
+    #           categories = RSpotify::Category.list(locale: 'es_MX', limit: 10)
+    def self.list(limit: 20, offset: 0, **options)
+      url = "browse/categories?limit=#{limit}&offset=#{offset}"
+      options.each do |option, value|
+        url << "&#{option}=#{value}"
+      end
+      json = RSpotify.auth_get(url)
+      json['categories']['items'].map { |i| Category.new i }
+    end
+
+    # Spotify does not support search for categories.
+    def self.search(*)
+      warn 'Spotify API does not support search for categories'
+      false
+    end
+
+    def initialize(options = {})
+      @icons = options['icons']
+      @name  = options['name']
+
+      super(options)
+    end
+
+    # See {Base#complete!}
+    def complete!
+      initialize RSpotify.auth_get("browse/categories/#{@id}")
+    end
+
+    # Get a list of Spotify playlists tagged with a particular category.
+    #
+    # @param limit  [Integer] Maximum number of playlists to return. Maximum: 50. 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.
+    # @param country [String] Optional. A country: an {http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 ISO 3166-1 alpha-2 country code}. Provide this parameter if you want to narrow the list of returned playlists to those relevant to a particular country. If omitted, the returned playlists will be globally relevant.
+    # @return [Array<Playlist>]
+    #
+    # @example
+    #           playlists = category.playlists
+    #           playlists = category.playlists(country: 'BR')
+    #           playlists = category.playlists(limit: 10, offset: 20)
+    def playlists(limit: 20, offset: 0, **options)
+      url = "browse/categories/#{@id}/playlists"\
+            "?limit=#{limit}&offset=#{offset}"
+
+      options.each do |option, value|
+        url << "&#{option}=#{value}"
+      end
+
+      json = RSpotify.auth_get(url)
+      json['playlists']['items'].map { |i| Playlist.new i }
+    end
+  end
+end

data/lib/rspotify/playlist.rb

@@ -3,7 +3,7 @@ module RSpotify
   # @attr [Boolean]     collaborative   true if the owner allows other users to modify the playlist
   # @attr [String]      description     The playlist description
   # @attr [Hash]        followers       Information about the followers of the playlist
-  # @attr [Array<Hash>] images          The playlist images
+  # @attr [Array<Hash>] images          Images for the playlist. The array may be empty or contain up to three images. The images are returned by size in descending order. If returned, the source URL for the image is temporary and will expire in less than one day.
   # @attr [String]      name            The name of the playlist
   # @attr [User]        owner           The user who owns the playlist
   # @attr [Boolean]     public          true if the playlist is not marked as secret
@@ -17,8 +17,8 @@ module RSpotify
     #
     # @param limit    [Integer] Maximum number of playlists to return. Maximum: 50. 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.
-    # @param locale    [String] Optional. The desired language, consisting of a lowercase {http://en.wikipedia.org/wiki/ISO_639 ISO 639 language code} and an uppercase {http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 ISO 3166-1 alpha-2 country code}, joined by an underscore. For details access {https://developer.spotify.com/web-api/get-list-featured-playlists/ here} and look for the locale parameter description.
     # @param country   [String] Optional. A country: an {http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 ISO 3166-1 alpha-2 country code}. Provide this parameter if you want the list of returned playlists to be relevant to a particular country. If omitted, the returned playlists will be relevant to all countries.
+    # @param locale    [String] Optional. The desired language, consisting of a lowercase {http://en.wikipedia.org/wiki/ISO_639 ISO 639 language code} and an uppercase {http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 ISO 3166-1 alpha-2 country code}, joined by an underscore. For details access {https://developer.spotify.com/web-api/get-list-featured-playlists/ here} and look for the locale parameter description.
     # @param timestamp [String] Optional. A timestamp in {http://en.wikipedia.org/wiki/ISO_8601 ISO 8601} format: yyyy-MM-ddTHH:mm:ss. Use this parameter to specify the user's local time to get results tailored for that specific date and time in the day. If not provided, the response defaults to the current UTC time. Example: "2014-10-23T09:00:00" for a user whose local time is 9AM.
     # @return [Array<Playlist>]
     #

data/lib/rspotify/user.rb

@@ -1,5 +1,6 @@
 module RSpotify
 
+  # @attr [String] birthdate       The user's date-of-birth. This field is only available when the current user has granted access to the *user-read-birthdate* 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.
@@ -23,7 +24,7 @@ module RSpotify
       super(id, 'user')
     end
 
-    # Spotify does not support search for users. Prints warning and returns false
+    # Spotify does not support search for users.
     def self.search(*)
       warn 'Spotify API does not support search for users'
       false
@@ -69,6 +70,7 @@ module RSpotify
       credentials = options['credentials']
       options     = options['info'] if options['info']
 
+      @birthdate    ||= options['birthdate']
       @country      ||= options['country']
       @display_name ||= options['display_name']
       @email        ||= options['email']

data/lib/rspotify/version.rb

@@ -1,3 +1,3 @@
 module RSpotify
-  VERSION = '1.11.0'
+  VERSION = '1.12.0'
 end

data/spec/lib/rspotify/category_spec.rb

@@ -0,0 +1,111 @@
+describe RSpotify::Category do
+
+  # Keys generated specifically for the tests. Should be removed in the future
+  let(:client_id) { '5ac1cda2ad354aeaa1ad2693d33bb98c' }
+  let(:client_secret) { '155fc038a85840679b55a1822ef36b9b' }
+
+  before do
+    VCR.use_cassette('authenticate:client') do
+      RSpotify.authenticate(client_id, client_secret)
+    end
+  end
+
+  describe 'Category::find' do
+    it 'should find right category' do
+      category = VCR.use_cassette('category:find:party') do
+        RSpotify::Category.find('party')
+      end
+
+      expect(category.href)               .to eq 'https://api.spotify.com/v1/browse/categories/party'
+      expect(category.icons.first['url']) .to eq 'https://datsnxq1rwndn.cloudfront.net/media/derived/party-274x274_73d1907a7371c3bb96a288390a96ee27_0_0_274_274.jpg'
+      expect(category.id)                 .to eq 'party'
+      expect(category.name)               .to eq 'Party'
+    end
+
+    it 'should find right category with additional attributes' do
+      category = VCR.use_cassette('category:find:party:country:BR') do
+        RSpotify::Category.find('party', country: 'BR')
+      end
+      expect(category.href)               .to eq 'https://api.spotify.com/v1/browse/categories/party'
+      expect(category.name)               .to eq 'Party'
+
+      category = VCR.use_cassette('category:find:party:locale:es_MX') do
+        RSpotify::Category.find('party', locale: 'es_MX')
+      end
+      expect(category.href)               .to eq 'https://api.spotify.com/v1/browse/categories/party'
+      expect(category.name)               .to eq 'Party'
+    end
+  end
+
+  describe 'Category::list' do
+    it 'should get the right categories' do
+      categories = VCR.use_cassette('category:list') do
+        RSpotify::Category.list
+      end
+
+      expect(categories.size)        .to eq 20
+      expect(categories.map(&:name)) .to include('Top Lists', 'Country', 'Decades')
+    end
+
+    it 'should get the right categories with additional attributes' do
+      categories = VCR.use_cassette('category:list:locale:es_MX:limit:10') do
+        RSpotify::Category.list(locale: 'es_MX', limit: 10)
+      end
+      expect(categories.size)        .to eq 10
+      expect(categories.map(&:name)) .to include('Mood', 'Pop', 'Chill')
+
+      categories = VCR.use_cassette('category:list:country:BR') do
+        RSpotify::Category.list(country: 'BR')
+      end
+      expect(categories.map(&:name)) .to include('Mood', 'Pop', 'Chill')
+    end
+  end
+
+  describe 'Category#complete!' do
+    let(:category) do
+      RSpotify::Category.new({'id' => 'party'})
+    end
+
+    it 'should fetch the complete information correctly' do
+      VCR.use_cassette('category:find:party') do
+        category.complete!
+      end
+      expect(category.href)               .to eq 'https://api.spotify.com/v1/browse/categories/party'
+      expect(category.icons.first['url']) .to eq 'https://datsnxq1rwndn.cloudfront.net/media/derived/party-274x274_73d1907a7371c3bb96a288390a96ee27_0_0_274_274.jpg'
+      expect(category.name)               .to eq 'Party'
+    end
+  end
+
+  describe 'Category#playlists' do
+    let(:category) do
+      # Get party category as a testing sample
+      VCR.use_cassette('category:find:party') do
+        RSpotify::Category.find('party')
+      end
+    end
+
+    it 'should get correct playlists' do
+      playlists = VCR.use_cassette('category:party:playlists') do
+        category.playlists
+      end
+
+      expect(playlists)             .to be_an Array
+      expect(playlists.size)        .to eq 20
+      expect(playlists.first)       .to be_an RSpotify::Playlist
+      expect(playlists.map(&:name)) .to include('Teen Party', 'Weekend Hangouts', 'Dance Party')
+    end
+
+    it 'should get correct playlists with additional options' do
+      playlists = VCR.use_cassette('category:party:playlists:limit:10:offset:20') do
+        category.playlists(limit: 10, offset: 20)
+      end
+      expect(playlists.size)        .to eq 10
+      expect(playlists.map(&:name)) .to include('Indie Brunch', 'Hipster Funk', 'Party Hits')
+
+      playlists = VCR.use_cassette('category:party:playlists:country:BR') do
+        category.playlists(country: 'BR')
+      end
+      expect(playlists.map(&:name)) .to include('Festa Indie', 'Esquenta Sertanejo', 'Cura Ressaca')
+    end
+  end
+end

data/spec/lib/rspotify/track_spec.rb

@@ -70,7 +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.total)       .to eq 3647
       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
@@ -86,13 +86,13 @@ describe RSpotify::Track do
         RSpotify::Track.search('Wanna Know', offset: 10)
       end
       expect(tracks.size)        .to eq 20
-      expect(tracks.map(&:name)) .to include('They Wanna Know', 'Say I Wanna Know')
+      expect(tracks.map(&:name)) .to include('They Wanna Know', 'You Wanna Know')
 
       tracks = VCR.use_cassette('track:search:Wanna Know:limit:10:offset:10') do 
         RSpotify::Track.search('Wanna Know', limit: 10, offset: 10)
       end
       expect(tracks.size)        .to eq 10
-      expect(tracks.map(&:name)) .to include('They Wanna Know')
+      expect(tracks.map(&:name)) .to include('You Wanna Know')
 
       tracks = VCR.use_cassette('track:search:Wanna Know:market:ES') do
         RSpotify::Track.search('Wanna Know', market: 'ES')

data/spec/vcr_cassettes/category_find_party.yml

@@ -0,0 +1,64 @@
+---
+http_interactions:
+- request:
+    method: get
+    uri: https://api.spotify.com/v1/browse/categories/party
+    body:
+      encoding: US-ASCII
+      string: ''
+    headers:
+      accept:
+      - "*/*; q=0.5, application/xml"
+      accept-encoding:
+      - gzip, deflate
+      authorization:
+      - Bearer BQAZNHzH_x3pHOISyXRF0LUn9MpDRXoXhYwISe5wlkgnYLQTSCRUDL3rlbwnpFehqlRgZOFIkNil9D8bzYu8ZQ
+      user-agent:
+      - Ruby
+  response:
+    status:
+      code: 200
+      message: OK
+    headers:
+      server:
+      - nginx
+      date:
+      - Fri, 13 Feb 2015 20:56:57 GMT
+      content-type:
+      - application/json; charset=utf-8
+      transfer-encoding:
+      - chunked
+      connection:
+      - keep-alive
+      keep-alive:
+      - timeout=600
+      cache-control:
+      - private, max-age=0
+      access-control-allow-headers:
+      - Accept, Authorization, Origin, Content-Type
+      access-control-allow-origin:
+      - "*"
+      access-control-max-age:
+      - '604800'
+      access-control-allow-methods:
+      - GET, POST, OPTIONS, PUT, DELETE
+      access-control-allow-credentials:
+      - 'true'
+      content-encoding:
+      - gzip
+      x-content-type-options:
+      - nosniff
+      strict-transport-security:
+      - max-age=31536000;
+    body:
+      encoding: ASCII-8BIT
+      string: !binary |-
+        H4sIAAAAAAAAAFSP3W7CMAyF73mKqNeQ9GcilKfY/TShNHbbTDTJEkNBiHcn
+        abnYZFmyP1nnHD82jBVjwL5gxzQQ+XgUQnnDo3dk+jvXbhLXSnTBzRGFVoSD
+        Cwaj8CrQvdhmAaOdjVnhiz3SniXRDCNlVMuP7cou4fzPBRRFe/utwmzBcn12
+        F+iDs8QtkpgQjBKAwVwRVq9dkrqlPskGqraUSjay0k3XtXtVHw5NW6p2j1jL
+        U5kqH6bmP34o3gFmAzS+MyXyZN9relhi/fnHqgkX9rmwzfMFAAD//wMAvTrQ
+        3icBAAA=
+    http_version: '1.1'
+  recorded_at: Fri, 13 Feb 2015 20:56:57 GMT
+recorded_with: VCR 2.9.3

data/spec/vcr_cassettes/category_find_party_country_BR.yml

@@ -0,0 +1,64 @@
+---
+http_interactions:
+- request:
+    method: get
+    uri: https://api.spotify.com/v1/browse/categories/party?country=BR
+    body:
+      encoding: US-ASCII
+      string: ''
+    headers:
+      accept:
+      - "*/*; q=0.5, application/xml"
+      accept-encoding:
+      - gzip, deflate
+      authorization:
+      - Bearer BQAZNHzH_x3pHOISyXRF0LUn9MpDRXoXhYwISe5wlkgnYLQTSCRUDL3rlbwnpFehqlRgZOFIkNil9D8bzYu8ZQ
+      user-agent:
+      - Ruby
+  response:
+    status:
+      code: 200
+      message: OK
+    headers:
+      server:
+      - nginx
+      date:
+      - Fri, 13 Feb 2015 20:56:58 GMT
+      content-type:
+      - application/json; charset=utf-8
+      transfer-encoding:
+      - chunked
+      connection:
+      - keep-alive
+      keep-alive:
+      - timeout=600
+      cache-control:
+      - private, max-age=0
+      access-control-allow-headers:
+      - Accept, Authorization, Origin, Content-Type
+      access-control-allow-origin:
+      - "*"
+      access-control-max-age:
+      - '604800'
+      access-control-allow-methods:
+      - GET, POST, OPTIONS, PUT, DELETE
+      access-control-allow-credentials:
+      - 'true'
+      content-encoding:
+      - gzip
+      x-content-type-options:
+      - nosniff
+      strict-transport-security:
+      - max-age=31536000;
+    body:
+      encoding: ASCII-8BIT
+      string: !binary |-
+        H4sIAAAAAAAAAFSP3W7CMAyF73mKqNeQ9GcilKfY/TShNHbbTDTJEkNBiHcn
+        abnYZFmyP1nnHD82jBVjwL5gxzQQ+XgUQnnDo3dk+jvXbhLXSnTBzRGFVoSD
+        Cwaj8CrQvdhmAaOdjVnhiz3SniXRDCNlVMuP7cou4fzPBRRFe/utwmzBcn12
+        F+iDs8QtkpgQjBKAwVwRVq9dkrqlPskGqraUSjay0k3XtXtVHw5NW6p2j1jL
+        U5kqH6bmP34o3gFmAzS+MyXyZN9relhi/fnHqgkX9rmwzfMFAAD//wMAvTrQ
+        3icBAAA=
+    http_version: '1.1'
+  recorded_at: Fri, 13 Feb 2015 20:56:58 GMT
+recorded_with: VCR 2.9.3