spotify-client 0.0.10 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: c75a6ce45367e553fa26b5070f41ddc5c527c85d
-  data.tar.gz: 225d5c91e9d3266da417ea439f017e5bbe23de70
+SHA256:
+  metadata.gz: 4a361b913ec9f98ccc159ec5c23a0f504905fa0d3f9ac991529f59bdb814ccbc
+  data.tar.gz: 499d48ce76d1999d5c7fa4d866927c3b7d0297c6cdb89a3d782a48b454c28e21
 SHA512:
-  metadata.gz: 956ebdff4a1729457581cb3462e9897a06cf7c5d430c825f7754ad49e615d3f43437345afdf51d022ebad2e47b4b67d2d787960314df7a6404e3bbacebb96a0c
-  data.tar.gz: d2558fbad05c8a1625c5cf58903cf954c5d7a372322a5fff53e735e6fd9733ba39e7d032b1b0a6be505bcb96b827ffa54f0eeaae272b3bcb55571e77e437183f
+  metadata.gz: 279fdba53d86dc07c61d38e3be2bc2e5874c13eaedea567fa93418c0e5c27d000b0623cd2f3d828b941f606440b4fbd1d51217efadfd36203e446872431db272
+  data.tar.gz: 542ede4f6390e03c99dfe175b78861201e7f119b597e1b525d69d85710ffd4c6fa21eb45ceb73ea7ea0285c261eb546d22916a00ab2732ae6cd837d4db444864

data/LICENSE

@@ -0,0 +1,21 @@
+MIT LICENSE
+
+Copyright (c) 2014 Claudio Poli <claudio@icorete.ch>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,104 @@
+# spotify-client
+
+Ruby client for the [Spotify Web API](https://developer.spotify.com/documentation/web-api).
+
+[![Gem Version](https://badge.fury.io/rb/spotify-client.svg)](https://rubygems.org/gems/spotify-client)
+
+## Installation
+
+Add this line to your application's `Gemfile`:
+
+```ruby
+gem 'spotify-client'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install spotify-client
+```
+
+## Supported Ruby Versions
+
+The CI matrix runs this gem against Ruby `3.2`, `3.3`, `3.4`, `4.0`, and `ruby-head`.
+
+## Usage
+
+```ruby
+config = {
+  access_token: 'tk',
+  raise_errors: true,
+  retries: 0,
+  read_timeout: 10,
+  write_timeout: 10,
+  persistent: false
+}
+
+client = Spotify::Client.new(config)
+```
+
+## Public API
+
+```ruby
+client.me
+client.me_tracks
+client.me_following
+client.user(user_id)
+client.user_playlists(user_id) # user_id kept for backward compatibility; requests /v1/me/playlists
+client.user_playlist(user_id, playlist_id)
+client.user_playlist_tracks(user_id, playlist_id, params = {})
+client.create_user_playlist(user_id, name, is_public = true)
+client.add_user_tracks_to_playlist(user_id, playlist_id, uris = [], position = nil)
+client.remove_user_tracks_from_playlist(user_id, playlist_id, tracks)
+client.replace_user_tracks_in_playlist(user_id, playlist_id, tracks)
+client.truncate_user_playlist(user_id, playlist_id)
+client.album(album_id)
+client.album_tracks(album_id)
+client.albums(album_ids)
+client.track(track_id)
+client.tracks(track_ids)
+client.artist(artist_id)
+client.artists(artist_ids)
+client.artist_albums(artist_id)
+client.search(entity, term, options = {})
+client.artist_top_tracks(artist_id, country_id)
+client.related_artists(artist_id)
+client.follow(type, ids)
+client.follow_playlist(user_id, playlist_id, is_public = true)
+client.request(:get, '/v1/me') # generic helper for newer endpoints
+client.request!(:post, '/v1/some-endpoint', [201], payload, false)
+```
+
+## Spotify API Migration Notes
+
+Spotify's Web API changed and removed several legacy endpoints in 2026. This gem now uses current routes while keeping backward-compatible method signatures:
+
+- Playlist reads/writes use `/v1/me/playlists` and `/v1/playlists/{playlist_id}/*`.
+- `follow(type, ids)` keeps the same signature but now targets `/v1/me/library` (the `type` argument is ignored for compatibility).
+- `artist_top_tracks` now uses the top-songs route.
+
+- Changelog: [Spotify Web API Changelog](https://developer.spotify.com/documentation/web-api/concepts/changelog)
+- Migration guide: [Spotify Web API Migration Guide](https://developer.spotify.com/documentation/web-api/concepts/migration-guide)
+
+## Development
+
+Install dependencies and run checks:
+
+```bash
+bundle install
+bundle exec rake
+```
+
+## Release
+
+Pushing a tag matching `v*` triggers the release workflow that builds and publishes the gem.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/lib/spotify/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Spotify
-  VERSION = '0.0.9'
+  VERSION = '1.0.0'
 end

data/lib/spotify-client.rb

@@ -1 +1 @@
-require File.dirname(__FILE__) + '/spotify_client'
+require "#{File.dirname(__FILE__)}/spotify_client"

data/lib/spotify_client.rb

@@ -1,8 +1,7 @@
 require 'excon'
 require 'json'
 
-require File.dirname(__FILE__) + '/spotify/utils'
-require File.dirname(__FILE__) + '/spotify/exceptions'
+require "#{File.dirname(__FILE__)}/spotify/exceptions"
 
 module Spotify
   class Client
@@ -44,32 +43,37 @@ module Spotify
       run(:get, '/v1/me/tracks', [200])
     end
 
+    # params:
+    # - type: Required, The ID type, currently only 'artist' is supported
+    # - limit: Optional. The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50.
+    # - after: Optional. The last artist ID retrieved from the previous request.
+    def me_following(params = {})
+      params = params.merge(type: 'artist')
+      run(:get, '/v1/me/following', [200], params)
+    end
+
     def user(user_id)
       run(:get, "/v1/users/#{user_id}", [200])
     end
 
-    def user_playlists(user_id)
-      run(:get, "/v1/users/#{user_id}/playlists", [200])
+    def user_playlists(_user_id = nil)
+      run(:get, '/v1/me/playlists', [200])
     end
 
-    def user_playlist(user_id, playlist_id)
-      run(:get, "/v1/users/#{user_id}/playlists/#{playlist_id}", [200])
+    def user_playlist(_user_id, playlist_id)
+      run(:get, "/v1/playlists/#{playlist_id}", [200])
     end
 
-    def user_playlist_tracks(user_id, playlist_id, params = {})
+    def user_playlist_tracks(_user_id, playlist_id, params = {})
       tracks = { 'items' => [] }
-      path = "/v1/users/#{user_id}/playlists/#{playlist_id}/tracks"
+      path = "/v1/playlists/#{playlist_id}/tracks"
 
       while path
         response = run(:get, path, [200], params)
         tracks['items'].concat(response.delete('items'))
         tracks.merge!(response)
 
-        path = if response['next']
-          response['next'].gsub(BASE_URI, '')
-        else
-          nil
-        end
+        path = response['next']&.gsub(BASE_URI, '')
       end
 
       tracks
@@ -79,8 +83,8 @@ module Spotify
     #
     # Requires playlist-modify-public for a public playlist.
     # Requires playlist-modify-private for a private playlist.
-    def create_user_playlist(user_id, name, is_public = true)
-      run(:post, "/v1/users/#{user_id}/playlists", [201], JSON.dump(name: name, public: is_public), false)
+    def create_user_playlist(_user_id, name, is_public = true)
+      run(:post, '/v1/me/playlists', [201], JSON.dump(name: name, public: is_public), false)
     end
 
     # Add an Array of track uris to an existing playlist.
@@ -88,27 +92,31 @@ module Spotify
     # Adding tracks to a user's public playlist requires authorization of the playlist-modify-public scope;
     # adding tracks to a private playlist requires the playlist-modify-private scope.
     #
-    # client.add_user_tracks_to_playlist('1181346016', '7i3thJWDtmX04dJhFwYb0x', %w(spotify:track:4iV5W9uYEdYUVa79Axb7Rh spotify:track:2lzEz3A3XIFyhMDqzMdcss))
-    def add_user_tracks_to_playlist(user_id, playlist_id, uris = [], position = nil)
-      params = { uris: Array.wrap(uris)[0..99].join(',') }
-      if position
-        params.merge!(position: position)
-      end
-      run(:post, "/v1/users/#{user_id}/playlists/#{playlist_id}/tracks", [201], params, false)
+    # client.add_user_tracks_to_playlist(
+    #   '1181346016', '7i3thJWDtmX04dJhFwYb0x', %w(spotify:track:... spotify:track:...)
+    # )
+    def add_user_tracks_to_playlist(_user_id, playlist_id, uris = [], position = nil)
+      params = { uris: Array(uris)[0..99].join(',') }
+      params.merge!(position: position) if position
+      run(:post, "/v1/playlists/#{playlist_id}/items", [200, 201], JSON.dump(params), false)
     end
 
     # Removes tracks from playlist
     #
-    # client.remove_user_tracks_from_playlist('1181346016', '7i3thJWDtmX04dJhFwYb0x', [{ uri: spotify:track:4iV5W9uYEdYUVa79Axb7Rh, positions: [0]}])
-    def remove_user_tracks_from_playlist(user_id, playlist_id, tracks)
-      run(:delete, "/v1/users/#{user_id}/playlists/#{playlist_id}/tracks", [200], JSON.dump(tracks: tracks))
+    # client.remove_user_tracks_from_playlist(
+    #   '1181346016', '7i3thJWDtmX04dJhFwYb0x', [{ uri: 'spotify:track:...', positions: [0] }]
+    # )
+    def remove_user_tracks_from_playlist(_user_id, playlist_id, tracks)
+      run(:delete, "/v1/playlists/#{playlist_id}/tracks", [200], JSON.dump(tracks: tracks))
     end
 
     # Replaces all occurrences of tracks with what's in the playlist
     #
-    # client.replace_user_tracks_in_playlist('1181346016', '7i3thJWDtmX04dJhFwYb0x', %w(spotify:track:4iV5W9uYEdYUVa79Axb7Rh spotify:track:2lzEz3A3XIFyhMDqzMdcss))
-    def replace_user_tracks_in_playlist(user_id, playlist_id, tracks)
-      run(:put, "/v1/users/#{user_id}/playlists/#{playlist_id}/tracks", [201], JSON.dump(uris: tracks))
+    # client.replace_user_tracks_in_playlist(
+    #   '1181346016', '7i3thJWDtmX04dJhFwYb0x', %w(spotify:track:... spotify:track:...)
+    # )
+    def replace_user_tracks_in_playlist(_user_id, playlist_id, tracks)
+      run(:put, "/v1/playlists/#{playlist_id}/tracks", [200, 201], JSON.dump(uris: tracks))
     end
 
     # Removes all tracks in playlist
@@ -127,7 +135,7 @@ module Spotify
     end
 
     def albums(album_ids)
-      params = { ids: Array.wrap(album_ids).join(',') }
+      params = { ids: Array(album_ids).join(',') }
       run(:get, '/v1/albums', [200], params)
     end
 
@@ -136,7 +144,7 @@ module Spotify
     end
 
     def tracks(track_ids)
-      params = { ids: Array.wrap(track_ids).join(',') }
+      params = { ids: Array(track_ids).join(',') }
       run(:get, '/v1/tracks', [200], params)
     end
 
@@ -145,7 +153,7 @@ module Spotify
     end
 
     def artists(artist_ids)
-      params = { ids: Array.wrap(artist_ids).join(',') }
+      params = { ids: Array(artist_ids).join(',') }
       run(:get, '/v1/artists', [200], params)
     end
 
@@ -153,18 +161,23 @@ module Spotify
       run(:get, "/v1/artists/#{artist_id}/albums", [200])
     end
 
-    def search(entity, term)
-      unless [:artist, :album, :track].include?(entity.to_sym)
-        fail(ImplementationError, "entity needs to be either artist, album or track, got: #{entity}")
+    def search(entity, term, options = {})
+      unless %i[artist album track].include?(entity.to_sym)
+        raise(ImplementationError, "entity needs to be either artist, album or track, got: #{entity}")
       end
-      run(:get, '/v1/search', [200], q: term.to_s, type: entity)
+
+      params = {
+        q: term.to_s,
+        type: entity
+      }.merge(options)
+      run(:get, '/v1/search', [200], params)
     end
 
     # Get Spotify catalog information about an artist's top 10 tracks by country.
     #
     # +country_id+ is required. An ISO 3166-1 alpha-2 country code.
     def artist_top_tracks(artist_id, country_id)
-      run(:get, "/v1/artists/#{artist_id}/top-tracks", [200], country: country_id)
+      run(:get, "/v1/artists/#{artist_id}/top-songs", [200], market: country_id)
     end
 
     def related_artists(artist_id)
@@ -175,15 +188,26 @@ module Spotify
     #
     # client.follow('artist', ['0BvkDsjIUla7X0k6CSWh1I'])
     def follow(type, ids)
-      params = { type: type, ids: Array.wrap(ids).join(',') }
-      run(:put, "/v1/me/following", [204], params)
+      _type = type # kept for backward-compatible signature
+      params = { ids: Array(ids).join(',') }
+      run(:put, '/v1/me/library', [200, 204], params)
     end
 
     # Follow a playlist
     #
     # client.follow_playlist('lukebryan', '0obRj9nNySESpFelMCLSya')
-    def follow_playlist(user_id, playlist_id, is_public = true)
-      run(:put, "/v1/users/#{user_id}/playlists/#{playlist_id}/followers", [200], { public: is_public })
+    def follow_playlist(_user_id, playlist_id, is_public = true)
+      run(:put, "/v1/playlists/#{playlist_id}/followers", [200, 204], { public: is_public })
+    end
+
+    # Generic API helper for forward compatibility with newly added endpoints.
+    def request(verb, path, expected_status_codes = [200], params_or_body = {}, idempotent = true)
+      run(verb.to_sym, path, Array(expected_status_codes), params_or_body, idempotent)
+    end
+
+    # Bang variant that propagates mapped API errors.
+    def request!(verb, path, expected_status_codes = [200], params_or_body = {}, idempotent = true)
+      run!(verb.to_sym, path, Array(expected_status_codes), params_or_body, idempotent)
     end
 
     protected
@@ -191,11 +215,9 @@ module Spotify
     def run(verb, path, expected_status_codes, params = {}, idempotent = true)
       run!(verb, path, expected_status_codes, params, idempotent)
     rescue Error => e
-      if @raise_errors
-        raise e
-      else
-        false
-      end
+      raise e if @raise_errors
+
+      false
     end
 
     def run!(verb, path, expected_status_codes, params_or_body = nil, idempotent = true)
@@ -209,7 +231,7 @@ module Spotify
         retry_limit: @retries,
         headers: {
           'Content-Type' => 'application/json',
-          'User-Agent'   => 'Spotify Ruby Client'
+          'User-Agent' => 'Spotify Ruby Client'
         }
       }
       if params_or_body.is_a?(Hash)
@@ -218,30 +240,29 @@ module Spotify
         packet.merge!(body: params_or_body)
       end
 
-      if !@access_token.nil? && @access_token != ''
-        packet[:headers].merge!('Authorization' => "Bearer #{@access_token}")
-      end
+      packet[:headers].merge!('Authorization' => "Bearer #{@access_token}") if !@access_token.nil? && @access_token != ''
 
       # puts "\033[31m [Spotify] HTTP Request: #{verb.upcase} #{BASE_URI}#{path} #{packet[:headers].inspect} \e[0m"
       response = @connection.request(packet)
-      ::JSON.load(response.body)
-
-    rescue Excon::Errors::NotFound => exception
-      raise(ResourceNotFound, "Error: #{exception.message}")
-    rescue Excon::Errors::BadRequest => exception
-      raise(BadRequest, "Error: #{exception.message}")
-    rescue Excon::Errors::Forbidden => exception
-      raise(InsufficientClientScopeError, "Error: #{exception.message}")
-    rescue Excon::Errors::Unauthorized => exception
-      raise(AuthenticationError, "Error: #{exception.message}")
-    rescue Excon::Errors::Error => exception
+      return {} if response.body.nil? || response.body.empty?
+
+      ::JSON.parse(response.body)
+    rescue Excon::Errors::NotFound => e
+      raise(ResourceNotFound, "Error: #{e.message}")
+    rescue Excon::Errors::BadRequest => e
+      raise(BadRequest, "Error: #{e.message}")
+    rescue Excon::Errors::Forbidden => e
+      raise(InsufficientClientScopeError, "Error: #{e.message}")
+    rescue Excon::Errors::Unauthorized => e
+      raise(AuthenticationError, "Error: #{e.message}")
+    rescue Excon::Errors::Error => e
       # Catch all others errors. Samples:
       #
       # <Excon::Errors::SocketError: Connection refused - connect(2) (Errno::ECONNREFUSED)>
       # <Excon::Errors::InternalServerError: Expected([200, 204, 404]) <=> Actual(500 InternalServerError)>
       # <Excon::Errors::Timeout: read timeout reached>
       # <Excon::Errors::BadGateway: Expected([200]) <=> Actual(502 Bad Gateway)>
-      raise(HTTPError, "Error: #{exception.message}")
+      raise(HTTPError, "Error: #{e.message}")
     end
   end
 end

data/spotify-client.gemspec

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+version_file = File.expand_path('lib/spotify/version.rb', __dir__)
+version = File.read(version_file).match(/VERSION = '([^']+)'/)&.captures&.first
+raise 'Could not determine gem version' unless version
+
+Gem::Specification.new do |spec|
+  spec.name = 'spotify-client'
+  spec.version = version
+  spec.authors = ['Claudio Poli']
+  spec.email = ['masterkain@gmail.com']
+
+  spec.summary = 'Ruby client for the Spotify Web API'
+  spec.description = 'Lightweight Ruby client for the Spotify Web API with playlist and catalog helpers.'
+  spec.homepage = 'https://github.com/icoretech/spotify-client'
+  spec.license = 'MIT'
+  spec.required_ruby_version = '>= 3.2'
+
+  spec.metadata['source_code_uri'] = 'https://github.com/icoretech/spotify-client'
+  spec.metadata['bug_tracker_uri'] = 'https://github.com/icoretech/spotify-client/issues'
+  spec.metadata['changelog_uri'] = 'https://github.com/icoretech/spotify-client/releases'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir[
+    'lib/**/*.rb',
+    'README*',
+    'LICENSE*',
+    '*.gemspec'
+  ]
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'excon', '>= 0.112', '< 2.0'
+  spec.add_dependency 'logger', '>= 1.7'
+end

metadata

@@ -1,74 +1,71 @@
 --- !ruby/object:Gem::Specification
 name: spotify-client
 version: !ruby/object:Gem::Version
-  version: 0.0.10
+  version: 1.0.0
 platform: ruby
 authors:
 - Claudio Poli
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-10-08 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: excon
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.112'
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '0.37'
+        version: '2.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.37'
-- !ruby/object:Gem::Dependency
-  name: rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '3.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
+        version: '0.112'
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '2.0'
 - !ruby/object:Gem::Dependency
-  name: guard-rspec
+  name: logger
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
+        version: '1.7'
+  type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
-description: Ruby client for the Spotify Web API
+        version: '1.7'
+description: Lightweight Ruby client for the Spotify Web API with playlist and catalog
+  helpers.
 email:
-- claudio@icorete.ch
+- masterkain@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- LICENSE
+- README.md
 - lib/spotify-client.rb
 - lib/spotify/exceptions.rb
-- lib/spotify/utils.rb
 - lib/spotify/version.rb
 - lib/spotify_client.rb
-- lib/spotify_client/version.rb
+- spotify-client.gemspec
 homepage: https://github.com/icoretech/spotify-client
-licenses: []
-metadata: {}
-post_install_message: 
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/icoretech/spotify-client
+  bug_tracker_uri: https://github.com/icoretech/spotify-client/issues
+  changelog_uri: https://github.com/icoretech/spotify-client/releases
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -76,16 +73,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: "[none]"
-rubygems_version: 2.4.8
-signing_key: 
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Ruby client for the Spotify Web API
 test_files: []

data/lib/spotify/utils.rb

@@ -1,11 +0,0 @@
-class Array
-  def self.wrap(object)
-    if object.nil?
-      []
-    elsif object.respond_to?(:to_ary)
-      object.to_ary || [object]
-    else
-      [object]
-    end
-  end
-end

data/lib/spotify_client/version.rb

@@ -1,3 +0,0 @@
-module Spotify
-  VERSION = '0.0.10'
-end