spotify-client 1.0.1 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aa7eb1f393af143301f5f029d8b707c20c314752c8095c069e85980650dcde29
-  data.tar.gz: 23e2e9669afae1cc5af7459493c14880028b963e11f8689a2d26502f15c852ef
+  metadata.gz: 8531ff35eb3c2054c9d4d99b6e97c5e22848e3805dae010d4be01841e3d535a6
+  data.tar.gz: f4775af30bd3ad47662b06ba8ebaefdef6b0d30378773e2ec520c54a4c672a36
 SHA512:
-  metadata.gz: 6e5ee46bee109d75e9fc34898d711f171d0ef2f2c5bf87bf0a1f07480eb1d14d6ff5edd4dc3d6e82e635fad778c595b501c3165ab5df339351fc444141b18bf4
-  data.tar.gz: 2296b443e46a7a481a3dfd264909722b9848145f7c21aba107fccd421089ce77cf231b55adcdb1c1beb2539c01b6a660a1370d2dbb50e05fc49d35f4e9a5023c
+  metadata.gz: 1892e985e4eff8f8f635e9438fc081832a65a6ac8717d73edaa17ee165219bdfcf29838e33b86ea6f06cf77489bedf418a90d06c2f114f1c5fc343e16615560a
+  data.tar.gz: 2ff791f2c9c431305935f27345f1aa4e0001c59eaa132a7d4f1d839b3030ee8d8090aa4ee5be0b8aa75492ec113a243e996b6bd119b81340892e2c593c7cc106

data/README.md

@@ -33,6 +33,7 @@ The CI matrix runs this gem against Ruby `3.2`, `3.3`, `3.4`, `4.0`, and `ruby-h
 ```ruby
 config = {
   access_token: 'tk',
+  app_mode: :development, # optional; use :development to fail fast on dev-mode restricted endpoints
   raise_errors: true,
   retries: 0,
   read_timeout: 10,
@@ -80,11 +81,12 @@ client.request!(:post, '/v1/some-endpoint', [201], payload, false)
 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.
+- `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.
 
-- 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)
+- February 2026 changes: [Spotify Web API Changes](https://developer.spotify.com/documentation/web-api/references/changes/february-2026)
 
 ## Development
 

data/lib/spotify/exceptions.rb

@@ -1,5 +1,6 @@
 module Spotify
   class ImplementationError < StandardError; end
+  class EndpointUnavailableInDevelopmentMode < ImplementationError; end
   class Error < StandardError; end
   class AuthenticationError < Error; end
   class HTTPError < Error; end

data/lib/spotify/version.rb

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

data/lib/spotify_client.rb

@@ -21,6 +21,7 @@ module Spotify
       @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
 
@@ -53,6 +54,10 @@ module Spotify
     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
 
@@ -66,7 +71,7 @@ module Spotify
 
     def user_playlist_tracks(_user_id, playlist_id, params = {})
       tracks = { 'items' => [] }
-      path = "/v1/playlists/#{playlist_id}/tracks"
+      path = "/v1/playlists/#{playlist_id}/items"
 
       while path
         response = run(:get, path, [200], params)
@@ -107,7 +112,7 @@ module Spotify
     #   '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))
+      run(:delete, "/v1/playlists/#{playlist_id}/items", [200], JSON.dump(items: tracks))
     end
 
     # Replaces all occurrences of tracks with what's in the playlist
@@ -116,7 +121,7 @@ module Spotify
     #   '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))
+      run(:put, "/v1/playlists/#{playlist_id}/items", [200, 201], JSON.dump(uris: tracks))
     end
 
     # Removes all tracks in playlist
@@ -135,8 +140,7 @@ module Spotify
     end
 
     def albums(album_ids)
-      params = { ids: Array(album_ids).join(',') }
-      run(:get, '/v1/albums', [200], params)
+      { 'albums' => Array(album_ids).map { |album_id| album(album_id) } }
     end
 
     def track(track_id)
@@ -144,8 +148,7 @@ module Spotify
     end
 
     def tracks(track_ids)
-      params = { ids: Array(track_ids).join(',') }
-      run(:get, '/v1/tracks', [200], params)
+      { 'tracks' => Array(track_ids).map { |track_id| track(track_id) } }
     end
 
     def artist(artist_id)
@@ -153,8 +156,7 @@ module Spotify
     end
 
     def artists(artist_ids)
-      params = { ids: Array(artist_ids).join(',') }
-      run(:get, '/v1/artists', [200], params)
+      { 'artists' => Array(artist_ids).map { |artist_id| artist(artist_id) } }
     end
 
     def artist_albums(artist_id)
@@ -166,6 +168,9 @@ module Spotify
         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
@@ -177,7 +182,8 @@ module Spotify
     #
     # +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-songs", [200], market: 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)
@@ -188,16 +194,24 @@ module Spotify
     #
     # client.follow('artist', ['0BvkDsjIUla7X0k6CSWh1I'])
     def follow(type, ids)
-      _type = type # kept for backward-compatible signature
-      params = { ids: Array(ids).join(',') }
-      run(:put, '/v1/me/library', [200, 204], params)
+      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
+      run(:put, '/v1/me/library', [200, 204], JSON.dump(uris: uris), false)
     end
 
     # Follow a playlist
     #
     # client.follow_playlist('lukebryan', '0obRj9nNySESpFelMCLSya')
     def follow_playlist(_user_id, playlist_id, is_public = true)
-      run(:put, "/v1/playlists/#{playlist_id}/followers", [200, 204], { public: is_public })
+      _is_public = is_public # kept for backward-compatible signature
+      run(:put, '/v1/me/library', [200, 204], JSON.dump(uris: ["spotify:playlist:#{playlist_id}"]), false)
     end
 
     # Generic API helper for forward compatibility with newly added endpoints.
@@ -212,6 +226,18 @@ module Spotify
 
     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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: spotify-client
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.2
 platform: ruby
 authors:
 - Claudio Poli