spotify-client 1.1.2 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dab0062dc15c5a8556c3b8ecea7ad6cf26c45172a87103389c77e885009beb1a
-  data.tar.gz: 6d51094f6f0fe8be0acb6e4da39b79f5edbb8e648782b909c54fe185b5928897
+  metadata.gz: de40fcc8655fc96d463e86606cfe0caa6191fc5c4920323fa4fa6b38c89aa936
+  data.tar.gz: 6048f1d14fe1ad56d500815a498176f1e6eed4e1449a0f873ea142404878f290
 SHA512:
-  metadata.gz: fe8fe55119d744c77e70a493cd82ff8eb77fd15a5106cbdace3b81e9424201b02f42ebbeffd19cf326bd0f50f0fe3b68ab6f615e2eaa0ecf5db572396768910a
-  data.tar.gz: f4032ff231d6a624da1ed989277698ca2dcb45dad853832d24f8eec1b885bb7e76b17368ad657ac4912a643135aa0a3db9e203ea7de7dfb3320e633125b33dfe
+  metadata.gz: 7183df6b108f55a76a6e000928888b2f46dca1bcf9921c527e2150f7a5c75feceaf892539a49560d0d07efe40e8028c6fd5aa6513937d9815a38c04de12e256c
+  data.tar.gz: 24b8d34991865ea0b8d8b2c6111961cda0e5cdd8acead3105c130844075f3d6c0f283bfcdce429e58dec52f24c2572b2f41a0e0701982161be710458f8eb3c51

data/README.md

@@ -27,14 +27,14 @@ 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`.
+Ruby `3.3` or newer is required. The CI matrix runs against Ruby `3.3`, `3.4`, `4.0`, and `ruby-head`, with both released Excon and its development branch.
 
 ## Usage
 
 ```ruby
 config = {
   access_token: 'tk',
-  app_mode: :development, # optional; use :development to fail fast on dev-mode restricted endpoints
+  app_mode: :development, # optional; opt into guards for restricted Development Mode endpoints
   raise_errors: true,
   retries: 0,
   read_timeout: 10,
@@ -128,30 +128,53 @@ client.request(:get, '/v1/me', [200], { market: 'IT' }) # GET-style hash payload
 client.request!(:post, '/v1/some-endpoint', [201], payload, false) # non-GET hash payloads are JSON encoded
 ```
 
-## Spotify API Migration Notes
+## Spotify API Compatibility
 
-Spotify's Web API changed and removed several legacy endpoints in 2026. This gem now uses current routes while keeping backward-compatible method signatures:
+The API contracts were checked against Spotify's official documentation on November 15, 2026. The latest listed Web API changelog is July 2026.
 
-- Playlist reads/writes use `/v1/me/playlists` and `/v1/playlists/{playlist_id}/*`.
-- `follow(type, ids)` now targets `/v1/me/library` using Spotify URIs (`spotify:{type}:{id}`), while still accepting prebuilt URIs.
-- `artist_top_tracks` uses `/v1/artists/{id}/top-tracks`.
-- `user(user_id)` and `artist_top_tracks` rely on endpoints that Spotify marks unavailable for Development Mode apps (still usable for Extended Quota Mode apps).
-- If initialized with `app_mode: :development`, `user(user_id)` and `artist_top_tracks` raise `Spotify::EndpointUnavailableInDevelopmentMode` before making the HTTP request.
+| Change | Client behavior |
+| --- | --- |
+| [February: Development Mode migration](https://developer.spotify.com/documentation/web-api/references/changes/february-2026) | Playlist helpers use `/v1/me/playlists` and `/v1/playlists/{id}/items`. Library helpers and legacy follow helpers use `/v1/me/library`. |
+| [March: restored external IDs](https://developer.spotify.com/documentation/web-api/references/changes/march-2026) | Album and track responses retain `external_ids` unchanged. |
+| [May: stable account identifier](https://developer.spotify.com/documentation/web-api/references/changes/may-2026) | `me` retains `account_id`. Use this immutable identifier when linking accounts to your service. |
+| [June: refresh-token expiration](https://developer.spotify.com/blog/2026-06-18-refresh-token-expiration) | OAuth remains the caller's responsibility. Refresh tokens expire six months after the original authorization; refreshing does not extend their lifetime. Handle `invalid_grant` by asking the user to authorize again. The change applied to existing apps from July 20, 2026. |
+| [July: shared development quotas](https://developer.spotify.com/documentation/web-api/references/changes/july-2026) | HTTP 429 raises `Spotify::RateLimitError` when errors are enabled, exposing `reason` and `retry_after`. Development Mode Client IDs share their developer account's quota. |
 
-- February 2026 changes: [Spotify Web API Changes](https://developer.spotify.com/documentation/web-api/references/changes/february-2026)
+Response JSON is returned without filtering fields. Account permissions, quota mode, scopes, and playlist ownership still determine which data Spotify returns.
+
+`app_mode: :development` opts into the restricted endpoint contract: `user`, `artist_top_tracks`, and `related_artists` fail before sending a request. Omit this option for integrations that retain access to those endpoints. Spotify [postponed the endpoint-access migration for existing Development Mode integrations](https://developer.spotify.com/blog/2026-02-06-update-on-developer-access-and-platform-security); the February changes do not apply to Extended Quota Mode. `related_artists` is deprecated and only remains usable by eligible integrations.
+
+Library save/remove calls follow the [current endpoint reference](https://developer.spotify.com/documentation/web-api/reference/save-library-items): comma-separated `uris` in the query, with at most 40 items per call. Spotify's February migration guide also shows a JSON-body example. Playlist additions accept at most 100 URI strings as a JSON array. Oversized batches raise `Spotify::ImplementationError`; split them into multiple calls.
+
+### Rate and quota errors
+
+Enable `raise_errors: true` or use `request!` to inspect errors. With the default `raise_errors: false`, non-bang methods continue to return `false` on HTTP errors.
+
+```ruby
+begin
+  client.request!(:get, '/v1/me')
+rescue Spotify::RateLimitError => error
+  error.reason      # "QUOTA_EXCEEDED" for the July quota response, otherwise nil
+  error.retry_after # Spotify's Retry-After header as a string, or nil
+end
+```
+
+`RateLimitError` inherits from `HTTPError`, so existing rescues still work. With the default `retries: 0`, a 429 response is returned immediately. Configured Excon retries can retry idempotent requests before exposing the final error. The client does not schedule retries from `Retry-After`; callers decide how to handle the supplied reason and retry interval.
 
 ## Development
 
-Install dependencies and run checks:
+Use the Ruby version in `.ruby-version`, install dependencies, and run checks:
 
 ```bash
 bundle install
 bundle exec rake
 ```
 
+The suite enables Ruby warnings and requires 100% line coverage overall and per file.
+
 ## Release
 
-Pushing a tag matching `v*` triggers the release workflow that builds and publishes the gem.
+The gem version is defined in `lib/spotify/version.rb`. Push a matching `v`-prefixed tag to trigger the release workflow and publish the gem.
 
 ## License
 

data/lib/spotify/client/compatibility_api.rb

@@ -45,7 +45,10 @@ module Spotify
       end
 
       def add_user_tracks_to_playlist(_user_id, playlist_id, uris = [], position = nil)
-        params = { uris: Array(uris)[0..99].join(',') }
+        items = Array(uris)
+        raise(ImplementationError, 'playlist additions accept at most 100 URIs') if items.length > 100
+
+        params = { uris: items }
         params.merge!(position: position) if position
         run(:post, "/v1/playlists/#{playlist_id}/items", [200, 201], JSON.dump(params), false)
       end

data/lib/spotify/client/transport.rb

@@ -14,20 +14,21 @@ module Spotify
 
       protected
 
-      def run(verb, path, expected_status_codes, params = {}, idempotent = true)
-        run!(verb, path, expected_status_codes, params, idempotent)
+      def run(verb, path, expected_status_codes, params = {}, idempotent = true, headers: {})
+        run!(verb, path, expected_status_codes, params, idempotent, headers: headers)
       rescue Error => e
         handle_nonbang_error(e)
       end
 
-      def run!(verb, path, expected_status_codes, params_or_body = nil, idempotent = true)
+      def run!(verb, path, expected_status_codes, params_or_body = nil, idempotent = true, headers: {})
         response = @connection.request(
           build_request_packet(
             verb: verb,
             path: path,
             expected_status_codes: expected_status_codes,
             params_or_body: params_or_body,
-            idempotent: idempotent
+            idempotent: idempotent,
+            headers: headers
           )
         )
         parse_response_body(response)
@@ -35,7 +36,7 @@ module Spotify
         raise map_transport_error(e)
       end
 
-      def build_request_packet(verb:, path:, expected_status_codes:, params_or_body:, idempotent:)
+      def build_request_packet(verb:, path:, expected_status_codes:, params_or_body:, idempotent:, headers: {})
         packet = {
           idempotent: idempotent,
           expects: expected_status_codes,
@@ -47,7 +48,7 @@ module Spotify
           headers: {
             'Content-Type' => 'application/json',
             'User-Agent' => "spotify-client/#{Spotify::VERSION} (Ruby)"
-          }
+          }.merge(headers)
         }
         apply_request_payload(packet, params_or_body)
 
@@ -85,12 +86,29 @@ module Spotify
       end
 
       def map_transport_error(error)
+        if error.is_a?(Excon::Errors::TooManyRequests)
+          return RateLimitError.new("Error: #{error.message}",
+                                    reason: rate_limit_reason(error.response.body),
+                                    retry_after: error.response.headers['Retry-After'])
+        end
+
         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
+
+      def rate_limit_reason(body)
+        case JSON.parse(body.to_s, symbolize_names: true)
+        in { error: { reason: String => reason } }
+          reason
+        else
+          nil
+        end
+      rescue JSON::ParserError
+        nil
+      end
     end
   end
 end

data/lib/spotify/client.rb

@@ -86,7 +86,8 @@ module Spotify
     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)
+      run(:put, "/v1/playlists/#{playlist_id}/images", [200, 202, 204], image_base64_jpeg.to_s, false,
+          headers: { 'Content-Type' => 'image/jpeg' })
     end
 
     def album(album_id)
@@ -165,10 +166,11 @@ module Spotify
     # +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)
+      run(:get, "/v1/artists/#{artist_id}/top-tracks", [200], { market: country_id })
     end
 
     def related_artists(artist_id)
+      raise_endpoint_unavailable_in_development_mode!(endpoint: 'GET /v1/artists/{id}/related-artists')
       run(:get, "/v1/artists/#{artist_id}/related-artists", [200])
     end
 
@@ -191,7 +193,7 @@ module Spotify
     end
 
     def playback_state(params = {})
-      run(:get, '/v1/me/player', [200], params)
+      run(:get, '/v1/me/player', [200, 204], params)
     end
 
     def available_devices
@@ -245,11 +247,11 @@ module Spotify
     end
 
     def add_to_library(uris)
-      run(:put, '/v1/me/library', [200, 204], JSON.dump(uris: Array(uris)), false)
+      run(:put, '/v1/me/library', [200, 204], library_query(uris), false)
     end
 
     def remove_from_library(uris)
-      run(:delete, '/v1/me/library', [200, 204], JSON.dump(uris: Array(uris)), false)
+      run(:delete, '/v1/me/library', [200, 204], library_query(uris), false)
     end
 
     # Generic API helper for forward compatibility with newly added endpoints.
@@ -276,10 +278,17 @@ module Spotify
 
     protected
 
+    def library_query(uris)
+      items = Array(uris)
+      raise(ImplementationError, 'library requests accept at most 40 URIs') if items.length > 40
+
+      { uris: items.join(',') }
+    end
+
     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 = "#{endpoint} is unavailable under the configured Spotify Development Mode restrictions."
       message += " Use #{replacement} instead." if replacement
       raise(EndpointUnavailableInDevelopmentMode, message)
     end

data/lib/spotify/exceptions.rb

@@ -4,6 +4,17 @@ module Spotify
   class Error < StandardError; end
   class AuthenticationError < Error; end
   class HTTPError < Error; end
+
+  class RateLimitError < HTTPError
+    attr_reader :reason, :retry_after
+
+    def initialize(message, reason: nil, retry_after: nil)
+      super(message)
+      @reason = reason
+      @retry_after = retry_after
+    end
+  end
+
   class InsufficientClientScopeError < Error; end
   class BadRequest < Error; end
   class ResourceNotFound < Error; end

data/lib/spotify/version.rb

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

data/spotify-client.gemspec

@@ -16,7 +16,7 @@ Gem::Specification.new do |spec|
   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.required_ruby_version = '>= 3.3'
 
   spec.metadata['source_code_uri'] = 'https://github.com/icoretech/spotify-client'
   spec.metadata['bug_tracker_uri'] = 'https://github.com/icoretech/spotify-client/issues'
@@ -31,5 +31,5 @@ Gem::Specification.new do |spec|
   ]
   spec.require_paths = ['lib']
 
-  spec.add_dependency 'excon', '>= 1.4', '< 2.0'
+  spec.add_dependency 'excon', '>= 1.12', '< 2.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: spotify-client
 version: !ruby/object:Gem::Version
-  version: 1.1.2
+  version: 2.0.0
 platform: ruby
 authors:
 - Claudio Poli
@@ -15,7 +15,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '1.4'
+        version: '1.12'
     - - "<"
       - !ruby/object:Gem::Version
         version: '2.0'
@@ -25,7 +25,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '1.4'
+        version: '1.12'
     - - "<"
       - !ruby/object:Gem::Version
         version: '2.0'
@@ -62,14 +62,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Ruby client for the Spotify Web API
 test_files: []