spotify-client 1.1.0 → 1.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1a6a776c3c8bbec1fba9afe39bf5d91da04789a313496873bd256b41564b0180
-  data.tar.gz: '09b9987a2dc0f5dbb7437701d4edc69d58abae3f11b2a3f9cb7ab2c330a88be2'
+  metadata.gz: dab0062dc15c5a8556c3b8ecea7ad6cf26c45172a87103389c77e885009beb1a
+  data.tar.gz: 6d51094f6f0fe8be0acb6e4da39b79f5edbb8e648782b909c54fe185b5928897
 SHA512:
-  metadata.gz: bd4aa7ea96354bdbb0d0dd5b9f9fc93840e67005419bc1ed8c5dada3405798db188c945a56b08e16872b3ab04829a87cdd163e987c72bb1b688c1ee1e77083fe
-  data.tar.gz: ae3a9d60e844e7677131c0c3425001d2495fd63c56f28b5d20d4bbc6d364734bb90804a6cd21a41f868460469895b17865de5ac79342d818fa3dc9f5c1f33489
+  metadata.gz: fe8fe55119d744c77e70a493cd82ff8eb77fd15a5106cbdace3b81e9424201b02f42ebbeffd19cf326bd0f50f0fe3b68ab6f615e2eaa0ecf5db572396768910a
+  data.tar.gz: f4032ff231d6a624da1ed989277698ca2dcb45dad853832d24f8eec1b885bb7e76b17368ad657ac4912a643135aa0a3db9e203ea7de7dfb3320e633125b33dfe

data/README.md

@@ -124,8 +124,8 @@ client.follow(type, ids)
 client.follow_playlist(user_id, playlist_id, is_public = true)
 
 # Generic helpers for forward compatibility
-client.request(:get, '/v1/me') # generic helper for newer endpoints
-client.request!(:post, '/v1/some-endpoint', [201], payload, false)
+client.request(:get, '/v1/me', [200], { market: 'IT' }) # GET-style hash payloads become query params
+client.request!(:post, '/v1/some-endpoint', [201], payload, false) # non-GET hash payloads are JSON encoded
 ```
 
 ## Spotify API Migration Notes

data/lib/spotify/client/compatibility_api.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Spotify
+  class Client
+    module CompatibilityAPI
+      def user(user_id)
+        raise_endpoint_unavailable_in_development_mode!(
+          endpoint: 'GET /v1/users/{id}',
+          replacement: 'GET /v1/me'
+        )
+        run(:get, "/v1/users/#{user_id}", [200])
+      end
+
+      def user_playlists(_user_id = nil)
+        run(:get, '/v1/me/playlists', [200])
+      end
+
+      def user_playlist(_user_id, playlist_id)
+        playlist(playlist_id)
+      end
+
+      def user_playlist_tracks(_user_id, playlist_id, params = {})
+        tracks = { 'items' => [] }
+        path = "/v1/playlists/#{playlist_id}/items"
+        query_params = params.dup
+
+        while path
+          response = run(:get, path, [200], query_params)
+          return false unless response
+
+          tracks['items'].concat(response.fetch('items', []))
+          tracks.merge!(response.reject { |key, _value| key == 'items' })
+          path, query_params = next_page_request(response['next'])
+        end
+
+        tracks
+      end
+
+      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
+
+      def change_playlist_details(_user_id, playlist_id, attributes = {})
+        run(:put, "/v1/playlists/#{playlist_id}", [200, 204], JSON.dump(attributes), false)
+      end
+
+      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
+
+      def remove_user_tracks_from_playlist(_user_id, playlist_id, tracks)
+        run(:delete, "/v1/playlists/#{playlist_id}/items", [200], JSON.dump(items: tracks))
+      end
+
+      def replace_user_tracks_in_playlist(_user_id, playlist_id, tracks)
+        run(:put, "/v1/playlists/#{playlist_id}/items", [200, 201], JSON.dump(uris: tracks))
+      end
+
+      def truncate_user_playlist(user_id, playlist_id)
+        replace_user_tracks_in_playlist(user_id, playlist_id, [])
+      end
+
+      def follow(type, ids)
+        entity_type = type.to_s.strip
+        uris = Array(ids).map do |id|
+          raw = id.to_s
+          next raw if raw.start_with?('spotify:')
+
+          raise(ImplementationError, 'type is required when ids are not full Spotify URIs') if entity_type.empty?
+
+          "spotify:#{entity_type}:#{raw}"
+        end
+        add_to_library(uris)
+      end
+
+      def follow_playlist(_user_id, playlist_id, _is_public = true)
+        add_to_library(["spotify:playlist:#{playlist_id}"])
+      end
+    end
+  end
+end

data/lib/spotify/client/transport.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+module Spotify
+  class Client
+    module Transport
+      EXCON_ERROR_MAP = {
+        Excon::Errors::NotFound => ResourceNotFound,
+        Excon::Errors::BadRequest => BadRequest,
+        Excon::Errors::Forbidden => InsufficientClientScopeError,
+        Excon::Errors::Unauthorized => AuthenticationError
+      }.freeze
+
+      protected
+
+      def run(verb, path, expected_status_codes, params = {}, idempotent = true)
+        run!(verb, path, expected_status_codes, params, idempotent)
+      rescue Error => e
+        handle_nonbang_error(e)
+      end
+
+      def run!(verb, path, expected_status_codes, params_or_body = nil, idempotent = true)
+        response = @connection.request(
+          build_request_packet(
+            verb: verb,
+            path: path,
+            expected_status_codes: expected_status_codes,
+            params_or_body: params_or_body,
+            idempotent: idempotent
+          )
+        )
+        parse_response_body(response)
+      rescue Excon::Errors::Error => e
+        raise map_transport_error(e)
+      end
+
+      def build_request_packet(verb:, path:, expected_status_codes:, params_or_body:, idempotent:)
+        packet = {
+          idempotent: idempotent,
+          expects: expected_status_codes,
+          method: verb,
+          path: path,
+          read_timeout: @read_timeout,
+          write_timeout: @write_timeout,
+          retry_limit: @retries,
+          headers: {
+            'Content-Type' => 'application/json',
+            'User-Agent' => "spotify-client/#{Spotify::VERSION} (Ruby)"
+          }
+        }
+        apply_request_payload(packet, params_or_body)
+
+        packet[:headers].merge!('Authorization' => "Bearer #{@access_token}") if !@access_token.nil? && @access_token != ''
+        packet
+      end
+
+      def apply_request_payload(packet, params_or_body)
+        if params_or_body.is_a?(Hash)
+          packet[:query] = params_or_body
+        else
+          packet[:body] = params_or_body
+        end
+      end
+
+      def parse_response_body(response)
+        return {} if response.body.nil? || response.body.empty?
+
+        ::JSON.parse(response.body)
+      rescue JSON::ParserError => e
+        raise(HTTPError, "Error: #{e.message}")
+      end
+
+      def next_page_request(next_url)
+        return [nil, {}] if next_url.nil? || next_url.empty?
+
+        uri = URI.parse(next_url)
+        [uri.query ? "#{uri.path}?#{uri.query}" : uri.path, {}]
+      end
+
+      def handle_nonbang_error(error)
+        raise error if @raise_errors
+
+        false
+      end
+
+      def map_transport_error(error)
+        error_class = EXCON_ERROR_MAP.find do |transport_error, _client_error|
+          error.is_a?(transport_error)
+        end&.last || HTTPError
+
+        error_class.new("Error: #{error.message}")
+      end
+    end
+  end
+end

data/lib/spotify/client.rb

@@ -0,0 +1,300 @@
+# frozen_string_literal: true
+
+require 'excon'
+require 'json'
+
+require 'spotify/exceptions'
+require 'spotify/version'
+require 'spotify/client/compatibility_api'
+require 'spotify/client/transport'
+
+module Spotify
+  class Client
+    include CompatibilityAPI
+    include Transport
+
+    BASE_URI = 'https://api.spotify.com'
+
+    attr_accessor :access_token
+
+    # Initialize the client.
+    #
+    # @example
+    #   client = Spotify::Client.new(:access_token => 'longtoken', retries: 0, raise_errors: true)
+    #
+    # @param [Hash] configuration.
+    def initialize(config = {})
+      @access_token = config[:access_token]
+      @raise_errors = config[:raise_errors] || false
+      @retries = config[:retries] || 0
+      @read_timeout = config[:read_timeout] || 10
+      @write_timeout = config[:write_timeout] || 10
+      @app_mode = config[:app_mode].to_s.strip.downcase
+      @connection = Excon.new(BASE_URI, persistent: config[:persistent] || false)
+    end
+
+    def inspect
+      vars = instance_variables.map { |v| "#{v}=#{instance_variable_get(v).inspect}" }.join(', ')
+      "<#{self.class}: #{vars}>"
+    end
+
+    # Closes the connection underlying socket.
+    # Use when you employ persistent connections and are done with your requests.
+    def close_connection
+      @connection.reset
+    end
+
+    def me
+      run(:get, '/v1/me', [200])
+    end
+
+    def me_tracks
+      run(:get, '/v1/me/tracks', [200])
+    end
+
+    def me_albums(params = {})
+      run(:get, '/v1/me/albums', [200], params)
+    end
+
+    def me_audiobooks(params = {})
+      run(:get, '/v1/me/audiobooks', [200], params)
+    end
+
+    def me_episodes(params = {})
+      run(:get, '/v1/me/episodes', [200], params)
+    end
+
+    def me_shows(params = {})
+      run(:get, '/v1/me/shows', [200], params)
+    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 playlist(playlist_id)
+      run(:get, "/v1/playlists/#{playlist_id}", [200])
+    end
+
+    def playlist_cover_image(playlist_id)
+      run(:get, "/v1/playlists/#{playlist_id}/images", [200], {})
+    end
+
+    def upload_playlist_cover_image(playlist_id, image_base64_jpeg)
+      run(:put, "/v1/playlists/#{playlist_id}/images", [200, 202, 204], image_base64_jpeg.to_s, false)
+    end
+
+    def album(album_id)
+      run(:get, "/v1/albums/#{album_id}", [200])
+    end
+
+    def album_tracks(album_id)
+      run(:get, "/v1/albums/#{album_id}/tracks", [200])
+    end
+
+    def albums(album_ids)
+      { 'albums' => Array(album_ids).map { |album_id| album(album_id) } }
+    end
+
+    def track(track_id)
+      run(:get, "/v1/tracks/#{track_id}", [200])
+    end
+
+    def tracks(track_ids)
+      { 'tracks' => Array(track_ids).map { |track_id| track(track_id) } }
+    end
+
+    def artist(artist_id)
+      run(:get, "/v1/artists/#{artist_id}", [200])
+    end
+
+    def artists(artist_ids)
+      { 'artists' => Array(artist_ids).map { |artist_id| artist(artist_id) } }
+    end
+
+    def artist_albums(artist_id)
+      run(:get, "/v1/artists/#{artist_id}/albums", [200])
+    end
+
+    def audiobook(audiobook_id, params = {})
+      run(:get, "/v1/audiobooks/#{audiobook_id}", [200], params)
+    end
+
+    def audiobook_chapters(audiobook_id, params = {})
+      run(:get, "/v1/audiobooks/#{audiobook_id}/chapters", [200], params)
+    end
+
+    def chapter(chapter_id, params = {})
+      run(:get, "/v1/chapters/#{chapter_id}", [200], params)
+    end
+
+    def episode(episode_id, params = {})
+      run(:get, "/v1/episodes/#{episode_id}", [200], params)
+    end
+
+    def show(show_id, params = {})
+      run(:get, "/v1/shows/#{show_id}", [200], params)
+    end
+
+    def show_episodes(show_id, params = {})
+      run(:get, "/v1/shows/#{show_id}/episodes", [200], params)
+    end
+
+    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
+
+      options = options.dup
+      options[:limit] = [options[:limit].to_i, 10].min if options.key?(:limit)
+
+      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)
+      raise_endpoint_unavailable_in_development_mode!(endpoint: 'GET /v1/artists/{id}/top-tracks')
+      run(:get, "/v1/artists/#{artist_id}/top-tracks", [200], country: country_id)
+    end
+
+    def related_artists(artist_id)
+      run(:get, "/v1/artists/#{artist_id}/related-artists", [200])
+    end
+
+    def me_top(type, params = {})
+      valid_types = %w[artists tracks]
+      normalized_type = type.to_s
+      unless valid_types.include?(normalized_type)
+        raise(ImplementationError, "type needs to be one of #{valid_types.join(', ')}, got: #{type}")
+      end
+
+      run(:get, "/v1/me/top/#{normalized_type}", [200], params)
+    end
+
+    def currently_playing(params = {})
+      run(:get, '/v1/me/player/currently-playing', [200], params)
+    end
+
+    def recently_played(params = {})
+      run(:get, '/v1/me/player/recently-played', [200], params)
+    end
+
+    def playback_state(params = {})
+      run(:get, '/v1/me/player', [200], params)
+    end
+
+    def available_devices
+      run(:get, '/v1/me/player/devices', [200], {})
+    end
+
+    def transfer_playback(device_ids, play = nil)
+      body = { device_ids: Array(device_ids) }
+      body[:play] = play unless play.nil?
+      run(:put, '/v1/me/player', [200, 204], JSON.dump(body), false)
+    end
+
+    def start_or_resume_playback(payload = {})
+      run(:put, '/v1/me/player/play', [200, 204], JSON.dump(payload), false)
+    end
+
+    def pause_playback(params = {})
+      run(:put, '/v1/me/player/pause', [200, 204], params, false)
+    end
+
+    def skip_to_next(params = {})
+      run(:post, '/v1/me/player/next', [200, 204], params, false)
+    end
+
+    def skip_to_previous(params = {})
+      run(:post, '/v1/me/player/previous', [200, 204], params, false)
+    end
+
+    def seek_to_position(position_ms, params = {})
+      run(:put, '/v1/me/player/seek', [200, 204], params.merge(position_ms: position_ms), false)
+    end
+
+    def set_repeat_mode(state, params = {})
+      run(:put, '/v1/me/player/repeat', [200, 204], params.merge(state: state), false)
+    end
+
+    def set_playback_volume(volume_percent, params = {})
+      run(:put, '/v1/me/player/volume', [200, 204], params.merge(volume_percent: volume_percent), false)
+    end
+
+    def set_shuffle(state, params = {})
+      run(:put, '/v1/me/player/shuffle', [200, 204], params.merge(state: state), false)
+    end
+
+    def playback_queue(params = {})
+      run(:get, '/v1/me/player/queue', [200], params)
+    end
+
+    def add_to_playback_queue(uri, params = {})
+      run(:post, '/v1/me/player/queue', [200, 204], params.merge(uri: uri), false)
+    end
+
+    def add_to_library(uris)
+      run(:put, '/v1/me/library', [200, 204], JSON.dump(uris: Array(uris)), false)
+    end
+
+    def remove_from_library(uris)
+      run(:delete, '/v1/me/library', [200, 204], JSON.dump(uris: Array(uris)), false)
+    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),
+        normalize_generic_request_payload(verb, 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),
+        normalize_generic_request_payload(verb, params_or_body),
+        idempotent
+      )
+    end
+
+    protected
+
+    def raise_endpoint_unavailable_in_development_mode!(endpoint:, replacement: nil)
+      return unless development_mode?
+
+      message = "#{endpoint} is unavailable for Spotify Development Mode apps as of March 9, 2026."
+      message += " Use #{replacement} instead." if replacement
+      raise(EndpointUnavailableInDevelopmentMode, message)
+    end
+
+    def development_mode?
+      @app_mode == 'development' || @app_mode == 'development_mode'
+    end
+
+    def normalize_generic_request_payload(verb, params_or_body)
+      return params_or_body unless params_or_body.is_a?(Hash)
+
+      query_verbs = %i[get head options]
+      return params_or_body if query_verbs.include?(verb.to_sym)
+
+      JSON.dump(params_or_body)
+    end
+  end
+end

data/lib/spotify/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Spotify
-  VERSION = '1.1.0'
+  VERSION = '1.1.2'
 end

data/lib/spotify-client.rb

@@ -1 +1,4 @@
-require "#{File.dirname(__FILE__)}/spotify_client"
+lib_dir = __dir__
+$LOAD_PATH.unshift(lib_dir) unless $LOAD_PATH.include?(lib_dir)
+
+require 'spotify/client'

data/lib/spotify_client.rb

@@ -1,430 +1,6 @@
-require 'excon'
-require 'json'
+# frozen_string_literal: true
 
-require "#{File.dirname(__FILE__)}/spotify/exceptions"
+lib_dir = __dir__
+$LOAD_PATH.unshift(lib_dir) unless $LOAD_PATH.include?(lib_dir)
 
-module Spotify
-  class Client
-    BASE_URI = 'https://api.spotify.com'.freeze
-
-    attr_accessor :access_token
-
-    # Initialize the client.
-    #
-    # @example
-    #   client = Spotify::Client.new(:access_token => 'longtoken', retries: 0, raise_errors: true)
-    #
-    # @param [Hash] configuration.
-    def initialize(config = {})
-      @access_token  = config[:access_token]
-      @raise_errors  = config[:raise_errors] || false
-      @retries       = config[:retries] || 0
-      @read_timeout  = config[:read_timeout] || 10
-      @write_timeout = config[:write_timeout] || 10
-      @app_mode      = config[:app_mode].to_s.strip.downcase
-      @connection    = Excon.new(BASE_URI, persistent: config[:persistent] || false)
-    end
-
-    def inspect
-      vars = instance_variables.map { |v| "#{v}=#{instance_variable_get(v).inspect}" }.join(', ')
-      "<#{self.class}: #{vars}>"
-    end
-
-    # Closes the connection underlying socket.
-    # Use when you employ persistent connections and are done with your requests.
-    def close_connection
-      @connection.reset
-    end
-
-    def me
-      run(:get, '/v1/me', [200])
-    end
-
-    def me_tracks
-      run(:get, '/v1/me/tracks', [200])
-    end
-
-    def me_albums(params = {})
-      run(:get, '/v1/me/albums', [200], params)
-    end
-
-    def me_audiobooks(params = {})
-      run(:get, '/v1/me/audiobooks', [200], params)
-    end
-
-    def me_episodes(params = {})
-      run(:get, '/v1/me/episodes', [200], params)
-    end
-
-    def me_shows(params = {})
-      run(:get, '/v1/me/shows', [200], params)
-    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)
-      raise_endpoint_unavailable_in_development_mode!(
-        endpoint: 'GET /v1/users/{id}',
-        replacement: 'GET /v1/me'
-      )
-      run(:get, "/v1/users/#{user_id}", [200])
-    end
-
-    def user_playlists(_user_id = nil)
-      run(:get, '/v1/me/playlists', [200])
-    end
-
-    def user_playlist(_user_id, playlist_id)
-      playlist(playlist_id)
-    end
-
-    def user_playlist_tracks(_user_id, playlist_id, params = {})
-      tracks = { 'items' => [] }
-      path = "/v1/playlists/#{playlist_id}/items"
-
-      while path
-        response = run(:get, path, [200], params)
-        tracks['items'].concat(response.delete('items'))
-        tracks.merge!(response)
-
-        path = response['next']&.gsub(BASE_URI, '')
-      end
-
-      tracks
-    end
-
-    # Create a playlist for a Spotify user. The playlist will be empty until you add tracks.
-    #
-    # 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/me/playlists', [201], JSON.dump(name: name, public: is_public), false)
-    end
-
-    def change_playlist_details(_user_id, playlist_id, attributes = {})
-      run(:put, "/v1/playlists/#{playlist_id}", [200, 204], JSON.dump(attributes), false)
-    end
-
-    # Add an Array of track uris to an existing playlist.
-    #
-    # 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:... 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:...', positions: [0] }]
-    # )
-    def remove_user_tracks_from_playlist(_user_id, playlist_id, tracks)
-      run(:delete, "/v1/playlists/#{playlist_id}/items", [200], JSON.dump(items: tracks))
-    end
-
-    # Replaces all occurrences of tracks with what's in the playlist
-    #
-    # 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}/items", [200, 201], JSON.dump(uris: tracks))
-    end
-
-    # Removes all tracks in playlist
-    #
-    # client.truncate_user_playlist('1181346016', '7i3thJWDtmX04dJhFwYb0x')
-    def truncate_user_playlist(user_id, playlist_id)
-      replace_user_tracks_in_playlist(user_id, playlist_id, [])
-    end
-
-    def playlist(playlist_id)
-      run(:get, "/v1/playlists/#{playlist_id}", [200])
-    end
-
-    def playlist_cover_image(playlist_id)
-      run(:get, "/v1/playlists/#{playlist_id}/images", [200], {})
-    end
-
-    def upload_playlist_cover_image(playlist_id, image_base64_jpeg)
-      run(:put, "/v1/playlists/#{playlist_id}/images", [200, 202, 204], image_base64_jpeg.to_s, false)
-    end
-
-    def album(album_id)
-      run(:get, "/v1/albums/#{album_id}", [200])
-    end
-
-    def album_tracks(album_id)
-      run(:get, "/v1/albums/#{album_id}/tracks", [200])
-    end
-
-    def albums(album_ids)
-      { 'albums' => Array(album_ids).map { |album_id| album(album_id) } }
-    end
-
-    def track(track_id)
-      run(:get, "/v1/tracks/#{track_id}", [200])
-    end
-
-    def tracks(track_ids)
-      { 'tracks' => Array(track_ids).map { |track_id| track(track_id) } }
-    end
-
-    def artist(artist_id)
-      run(:get, "/v1/artists/#{artist_id}", [200])
-    end
-
-    def artists(artist_ids)
-      { 'artists' => Array(artist_ids).map { |artist_id| artist(artist_id) } }
-    end
-
-    def artist_albums(artist_id)
-      run(:get, "/v1/artists/#{artist_id}/albums", [200])
-    end
-
-    def audiobook(audiobook_id, params = {})
-      run(:get, "/v1/audiobooks/#{audiobook_id}", [200], params)
-    end
-
-    def audiobook_chapters(audiobook_id, params = {})
-      run(:get, "/v1/audiobooks/#{audiobook_id}/chapters", [200], params)
-    end
-
-    def chapter(chapter_id, params = {})
-      run(:get, "/v1/chapters/#{chapter_id}", [200], params)
-    end
-
-    def episode(episode_id, params = {})
-      run(:get, "/v1/episodes/#{episode_id}", [200], params)
-    end
-
-    def show(show_id, params = {})
-      run(:get, "/v1/shows/#{show_id}", [200], params)
-    end
-
-    def show_episodes(show_id, params = {})
-      run(:get, "/v1/shows/#{show_id}/episodes", [200], params)
-    end
-
-    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
-
-      options = options.dup
-      options[:limit] = [options[:limit].to_i, 10].min if options.key?(:limit)
-
-      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)
-      raise_endpoint_unavailable_in_development_mode!(endpoint: 'GET /v1/artists/{id}/top-tracks')
-      run(:get, "/v1/artists/#{artist_id}/top-tracks", [200], country: country_id)
-    end
-
-    def related_artists(artist_id)
-      run(:get, "/v1/artists/#{artist_id}/related-artists", [200])
-    end
-
-    def me_top(type, params = {})
-      valid_types = %w[artists tracks]
-      normalized_type = type.to_s
-      unless valid_types.include?(normalized_type)
-        raise(ImplementationError, "type needs to be one of #{valid_types.join(', ')}, got: #{type}")
-      end
-
-      run(:get, "/v1/me/top/#{normalized_type}", [200], params)
-    end
-
-    def currently_playing(params = {})
-      run(:get, '/v1/me/player/currently-playing', [200], params)
-    end
-
-    def recently_played(params = {})
-      run(:get, '/v1/me/player/recently-played', [200], params)
-    end
-
-    def playback_state(params = {})
-      run(:get, '/v1/me/player', [200], params)
-    end
-
-    def available_devices
-      run(:get, '/v1/me/player/devices', [200], {})
-    end
-
-    def transfer_playback(device_ids, play = nil)
-      body = { device_ids: Array(device_ids) }
-      body[:play] = play unless play.nil?
-      run(:put, '/v1/me/player', [200, 204], JSON.dump(body), false)
-    end
-
-    def start_or_resume_playback(payload = {})
-      run(:put, '/v1/me/player/play', [200, 204], JSON.dump(payload), false)
-    end
-
-    def pause_playback(params = {})
-      run(:put, '/v1/me/player/pause', [200, 204], params, false)
-    end
-
-    def skip_to_next(params = {})
-      run(:post, '/v1/me/player/next', [200, 204], params, false)
-    end
-
-    def skip_to_previous(params = {})
-      run(:post, '/v1/me/player/previous', [200, 204], params, false)
-    end
-
-    def seek_to_position(position_ms, params = {})
-      run(:put, '/v1/me/player/seek', [200, 204], params.merge(position_ms: position_ms), false)
-    end
-
-    def set_repeat_mode(state, params = {})
-      run(:put, '/v1/me/player/repeat', [200, 204], params.merge(state: state), false)
-    end
-
-    def set_playback_volume(volume_percent, params = {})
-      run(:put, '/v1/me/player/volume', [200, 204], params.merge(volume_percent: volume_percent), false)
-    end
-
-    def set_shuffle(state, params = {})
-      run(:put, '/v1/me/player/shuffle', [200, 204], params.merge(state: state), false)
-    end
-
-    def playback_queue(params = {})
-      run(:get, '/v1/me/player/queue', [200], params)
-    end
-
-    def add_to_playback_queue(uri, params = {})
-      run(:post, '/v1/me/player/queue', [200, 204], params.merge(uri: uri), false)
-    end
-
-    def add_to_library(uris)
-      run(:put, '/v1/me/library', [200, 204], JSON.dump(uris: Array(uris)), false)
-    end
-
-    def remove_from_library(uris)
-      run(:delete, '/v1/me/library', [200, 204], JSON.dump(uris: Array(uris)), false)
-    end
-
-    # Follow artists or users
-    #
-    # client.follow('artist', ['0BvkDsjIUla7X0k6CSWh1I'])
-    def follow(type, ids)
-      entity_type = type.to_s.strip
-      uris = Array(ids).map do |id|
-        raw = id.to_s
-        next raw if raw.start_with?('spotify:')
-
-        raise(ImplementationError, 'type is required when ids are not full Spotify URIs') if entity_type.empty?
-
-        "spotify:#{entity_type}:#{raw}"
-      end
-      add_to_library(uris)
-    end
-
-    # Follow a playlist
-    #
-    # client.follow_playlist('lukebryan', '0obRj9nNySESpFelMCLSya')
-    def follow_playlist(_user_id, playlist_id, is_public = true)
-      _is_public = is_public # kept for backward-compatible signature
-      add_to_library(["spotify:playlist:#{playlist_id}"])
-    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
-
-    def raise_endpoint_unavailable_in_development_mode!(endpoint:, replacement: nil)
-      return unless development_mode?
-
-      message = "#{endpoint} is unavailable for Spotify Development Mode apps as of March 9, 2026."
-      message += " Use #{replacement} instead." if replacement
-      raise(EndpointUnavailableInDevelopmentMode, message)
-    end
-
-    def development_mode?
-      @app_mode == 'development' || @app_mode == 'development_mode'
-    end
-
-    def run(verb, path, expected_status_codes, params = {}, idempotent = true)
-      run!(verb, path, expected_status_codes, params, idempotent)
-    rescue Error => e
-      raise e if @raise_errors
-
-      false
-    end
-
-    def run!(verb, path, expected_status_codes, params_or_body = nil, idempotent = true)
-      packet = {
-        idempotent: idempotent,
-        expects: expected_status_codes,
-        method: verb,
-        path: path,
-        read_timeout: @read_timeout,
-        write_timeout: @write_timeout,
-        retry_limit: @retries,
-        headers: {
-          'Content-Type' => 'application/json',
-          'User-Agent' => 'Spotify Ruby Client'
-        }
-      }
-      if params_or_body.is_a?(Hash)
-        packet.merge!(query: params_or_body)
-      else
-        packet.merge!(body: params_or_body)
-      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)
-      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: #{e.message}")
-    end
-  end
-end
+require 'spotify/client'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: spotify-client
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.1.2
 platform: ruby
 authors:
 - Claudio Poli
@@ -40,6 +40,9 @@ files:
 - LICENSE
 - README.md
 - lib/spotify-client.rb
+- lib/spotify/client.rb
+- lib/spotify/client/compatibility_api.rb
+- lib/spotify/client/transport.rb
 - lib/spotify/exceptions.rb
 - lib/spotify/version.rb
 - lib/spotify_client.rb