spotify-client 1.0.2 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8531ff35eb3c2054c9d4d99b6e97c5e22848e3805dae010d4be01841e3d535a6
-  data.tar.gz: f4775af30bd3ad47662b06ba8ebaefdef6b0d30378773e2ec520c54a4c672a36
+  metadata.gz: 1a6a776c3c8bbec1fba9afe39bf5d91da04789a313496873bd256b41564b0180
+  data.tar.gz: '09b9987a2dc0f5dbb7437701d4edc69d58abae3f11b2a3f9cb7ab2c330a88be2'
 SHA512:
-  metadata.gz: 1892e985e4eff8f8f635e9438fc081832a65a6ac8717d73edaa17ee165219bdfcf29838e33b86ea6f06cf77489bedf418a90d06c2f114f1c5fc343e16615560a
-  data.tar.gz: 2ff791f2c9c431305935f27345f1aa4e0001c59eaa132a7d4f1d839b3030ee8d8090aa4ee5be0b8aa75492ec113a243e996b6bd119b81340892e2c593c7cc106
+  metadata.gz: bd4aa7ea96354bdbb0d0dd5b9f9fc93840e67005419bc1ed8c5dada3405798db188c945a56b08e16872b3ab04829a87cdd163e987c72bb1b688c1ee1e77083fe
+  data.tar.gz: ae3a9d60e844e7677131c0c3425001d2495fd63c56f28b5d20d4bbc6d364734bb90804a6cd21a41f868460469895b17865de5ac79342d818fa3dc9f5c1f33489

data/README.md

@@ -2,7 +2,8 @@
 
 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)
+[![Test](https://github.com/icoretech/spotify-client/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/icoretech/spotify-client/actions/workflows/test.yml?query=branch%3Amain)
+[![Gem Version](https://badge.fury.io/rb/spotify-client.svg)](https://badge.fury.io/rb/spotify-client)
 
 ## Installation
 
@@ -47,31 +48,82 @@ client = Spotify::Client.new(config)
 ## Public API
 
 ```ruby
+# User
 client.me
-client.me_tracks
+
+# Library
+client.me_albums(params = {})
+client.me_audiobooks(params = {})
+client.me_episodes(params = {})
 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.me_shows(params = {})
+client.me_tracks
+client.add_to_library(uris)
+client.remove_from_library(uris)
+client.user_playlists(user_id = nil) # backward-compatible signature; requests /v1/me/playlists
 client.create_user_playlist(user_id, name, is_public = true)
+client.change_playlist_details(user_id, playlist_id, attributes = {})
+
+# Playlist
+client.playlist(playlist_id)
+client.playlist_cover_image(playlist_id)
+client.upload_playlist_cover_image(playlist_id, image_base64_jpeg)
+
+# Backward-compatible playlist helpers
+client.user_playlist(user_id, playlist_id) # delegates to playlist(playlist_id)
+client.user_playlist_tracks(user_id, playlist_id, params = {})
 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)
+
+# Metadata
 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.audiobook(audiobook_id, params = {})
+client.audiobook_chapters(audiobook_id, params = {})
+client.chapter(chapter_id, params = {})
+client.episode(episode_id, params = {})
+client.show(show_id, params = {})
+client.show_episodes(show_id, params = {})
+client.track(track_id)
+client.tracks(track_ids)
+
+# Personalisation
+client.me_top(type, params = {}) # type: "artists" or "tracks"
+
+# Player
+client.currently_playing(params = {})
+client.recently_played(params = {})
+client.playback_state(params = {})
+client.available_devices
+client.transfer_playback(device_ids, play = nil)
+client.start_or_resume_playback(payload = {})
+client.pause_playback(params = {})
+client.skip_to_next(params = {})
+client.skip_to_previous(params = {})
+client.seek_to_position(position_ms, params = {})
+client.set_repeat_mode(state, params = {})
+client.set_playback_volume(volume_percent, params = {})
+client.set_shuffle(state, params = {})
+client.playback_queue(params = {})
+client.add_to_playback_queue(uri, params = {})
+
+# Search
+client.search(entity, term, options = {}) # entity: :artist, :album, :track
+
+# Legacy helpers kept for compatibility
+client.user(user_id)
 client.related_artists(artist_id)
 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)
 ```

data/lib/spotify/version.rb

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

data/lib/spotify_client.rb

@@ -44,6 +44,22 @@ module Spotify
       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.
@@ -66,7 +82,7 @@ module Spotify
     end
 
     def user_playlist(_user_id, playlist_id)
-      run(:get, "/v1/playlists/#{playlist_id}", [200])
+      playlist(playlist_id)
     end
 
     def user_playlist_tracks(_user_id, playlist_id, params = {})
@@ -92,6 +108,10 @@ module Spotify
       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;
@@ -131,6 +151,18 @@ module Spotify
       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
@@ -163,6 +195,30 @@ module Spotify
       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}")
@@ -190,6 +246,86 @@ module Spotify
       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'])
@@ -203,7 +339,7 @@ module Spotify
 
         "spotify:#{entity_type}:#{raw}"
       end
-      run(:put, '/v1/me/library', [200, 204], JSON.dump(uris: uris), false)
+      add_to_library(uris)
     end
 
     # Follow a playlist
@@ -211,7 +347,7 @@ module Spotify
     # client.follow_playlist('lukebryan', '0obRj9nNySESpFelMCLSya')
     def follow_playlist(_user_id, playlist_id, is_public = true)
       _is_public = is_public # kept for backward-compatible signature
-      run(:put, '/v1/me/library', [200, 204], JSON.dump(uris: ["spotify:playlist:#{playlist_id}"]), false)
+      add_to_library(["spotify:playlist:#{playlist_id}"])
     end
 
     # Generic API helper for forward compatibility with newly added endpoints.

metadata

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