spotify-ruby-kev 0.2.5

data/lib/spotify/sdk/artist.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module Spotify
+  class SDK
+    class Artist < Model
+      ##
+      # Do we have the full information for this artist?
+      #
+      # @example
+      #   artist = @sdk.connect.playback.artist
+      #   artist.full_information? # => false
+      #
+      # @return [FalseClass,TrueClass] is_full_info Does this contain everything?
+      #
+      def full_information?
+        to_h.key?(:images)
+      end
+
+      ##
+      # Get full information for this artist by calling /v1/artists/:id
+      #
+      # @example
+      #   artist = @sdk.connect.playback.artist
+      #   artist.retrieve_full_information! unless artist.full_information?
+      #
+      # @return [TrueClass] success Always returns true.
+      #
+      def retrieve_full_information!
+        unless full_information?
+          parent.send_http_request(:get, "/v1/artists/%s" % id).map do |key, value|
+            send("%s=" % key, value)
+          end
+        end
+
+        true
+      end
+
+      ##
+      # Helper method for setting the following status.
+      # Requires the `user-follow-modify` scope.
+      # If true, PUT /v1/me/following otherwise DELETE /v1/me/following
+      #
+      # @example
+      #   @sdk.playback.item.artist.following = true
+      #   @sdk.playback.item.artist.following = false
+      #
+      def following=(should_follow)
+        raise "#following= must be true or false" unless [true, false].include?(should_follow)
+
+        should_follow ? follow! : unfollow!
+      end
+
+      ##
+      # Follow the artist.
+      # Requires the `user-follow-modify` scope.
+      # PUT /v1/me/following
+      #
+      # @example
+      #   @sdk.playback.item.artist.follow!
+      #
+      # @return [Spotify::SDK::Artist] self Return the artist object, for chaining methods.
+      #
+      def follow!
+        parent.send_http_request(:put, "/v1/me/following?type=artist&ids=%s" % id, http_options: {expect_nil: true})
+        self
+      end
+
+      ##
+      # Unfollow the artist.
+      # Requires the `user-follow-modify` scope.
+      # DELETE /v1/me/following
+      #
+      # @example
+      #   @sdk.playback.item.artist.unfollow!
+      #
+      # @return [Spotify::SDK::Artist] self Return the artist object, for chaining methods.
+      #
+      def unfollow!
+        parent.send_http_request(:delete, "/v1/me/following?type=artist&ids=%s" % id, http_options: {expect_nil: true})
+        self
+      end
+
+      ##
+      # Display the artist's images. If not obtained, request them from the API.
+      #
+      # @example
+      #   artist = @sdk.connect.playback.artist
+      #   artist.images[0] # => [#<Spotify::SDK::Image>, #<Spotify::SDK::Image>, ...]
+      #
+      # @return [Array] images Contains a list of images, wrapped in Spotify::SDK::Image
+      #
+      def images
+        retrieve_full_information! unless full_information?
+        super.map {|image| Spotify::SDK::Image.new(image, parent) }
+      end
+
+      ##
+      # Display the artist's popularity. If not obtained, request them from the API.
+      #
+      # @example
+      #   artist = @sdk.connect.playback.artist
+      #   artist.popularity # => 90
+      #
+      # @return [Integer] popularity The number of popularity, between 0-100.
+      #
+      def popularity
+        retrieve_full_information! unless full_information?
+        super
+      end
+
+      ##
+      # Display the artist's genres. If not obtained, request them from the API.
+      #
+      # @example
+      #   artist = @sdk.connect.playback.artist
+      #   artist.genres # => ["hip hop", "pop rap", "rap", ...]
+      #
+      # @return [Array] genres An array of genres, denoted in strings.
+      #
+      def genres
+        retrieve_full_information! unless full_information?
+        super
+      end
+
+      ##
+      # Return the Spotify URL for this artist.
+      #
+      # @example
+      #   artist = @sdk.connect.playback.artist
+      #   artist.spotify_url # => "https://open.spotify.com/artist/..."
+      #
+      # @return [String] spotify_url The URL to open this artist on open.spotify.com
+      #
+      def spotify_url
+        external_urls[:spotify]
+      end
+
+      ##
+      # Return the Spotify URI for this artist.
+      #
+      # @example
+      #   artist = @sdk.connect.playback.artist
+      #   artist.spotify_uri # => "spotify:uri:..."
+      #
+      # @return [String] spotify_uri The URI to open this artist in official apps.
+      #
+      alias_attribute :spotify_uri, :uri
+
+      ##
+      # Return the followers on Spotify for this artist.
+      #
+      # @example
+      #   artist = @sdk.connect.playback.artist
+      #   artist.followers # => 13913
+      #
+      # @return [Integer] followers The number of users following this artist.
+      #
+      def followers
+        super[:total]
+      end
+    end
+  end
+end

data/lib/spotify/sdk/base.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Spotify
+  class SDK
+    ##
+    # For each SDK component, we have a Base class. We're using HTTParty.
+    #
+    class Base
+      include HTTParty
+      base_uri "api.spotify.com:443"
+
+      ##
+      # Initiate a Spotify SDK Base component.
+      #
+      # @example
+      #   @sdk = Spotify::SDK.new(@session)
+      #   @auth = Spotify::SDK::Base.new(@sdk)
+      #
+      #   @sdk = Spotify::SDK.new(@session)
+      #   @sdk.to_hash # => { access_token: ..., expires_at: ... }
+      #
+      # @param [Spotify::SDK] parent An instance of Spotify::SDK as a reference point.
+      #
+      def initialize(parent)
+        @parent = parent
+        @options = {
+          headers: {
+            Authorization: "Bearer %s" % @parent.session.access_token
+          }
+        }
+      end
+
+      ##
+      # Handle HTTParty responses.
+      #
+      # @example
+      #   # Return the Hash from the JSON response.
+      #   send_http_request(:get, "/v1/me/player/devices", @options)
+      #
+      #   # Return the raw HTTParty::Response object.
+      #   send_http_request(:get, "/v1/me/player/devices", @options.merge({http_options: { raw: true }}))
+      #
+      #   # Return true for HTTP requests that return a 200 OK with an empty response.
+      #   send_http_request(:put, "/v1/me/player/pause", @options.merge({http_options: { expect_nil: true }}))
+      #
+      # @param [Symbol] method The HTTP method you want to perform. Examples are :get, :post, :put, :delete
+      # @param [String] endpoint The HTTP endpoint you'd like to call. Example: /v1/me
+      # @param [Hash] override_opts Any headers, HTTParty config or application-specific config (see `http_options`)
+      # @return [Hash,HTTParty::Response,TrueClass] response The response from the HTTP request.
+      #
+      # TODO: Address and fix cyclomatic & code complexity issues by Rubocop.
+      # rubocop:disable CyclomaticComplexity, PerceivedComplexity, AbcSize
+      def send_http_request(method, endpoint, override_opts={})
+        opts = {
+          raw:        false,
+          expect_nil: false
+        }.merge(override_opts[:http_options].presence || {})
+
+        httparty = self.class.send(method, endpoint, @options.merge(override_opts))
+        response = httparty.parsed_response
+        response = response.try(:deep_symbolize_keys) || response
+        raise response[:error][:message] if response.is_a?(Hash) && response[:error].present?
+        return httparty if opts[:raw] == true
+
+        response = opts[:expect_nil] ? true : raise("No response returned") if response.nil?
+        response
+      end
+      # rubocop:enable CyclomaticComplexity, PerceivedComplexity, AbcSize
+
+      def inspect # :nodoc:
+        "#<%s:0x00%x>" % [self.class.name, (object_id << 1)]
+      end
+
+      attr_reader :parent
+    end
+  end
+end

data/lib/spotify/sdk/connect.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Spotify
+  class SDK
+    class Connect < Base
+      ##
+      # Get the current playback.
+      # GET /v1/me/player
+      #
+      # @example
+      #   playback = @sdk.connect.playback
+      #
+      # @see https://developer.spotify.com/console/get-user-player/
+      # @see https://developer.spotify.com/documentation/web-api/reference/player/get-information-about-the-users-current-playback/
+      #
+      # @param [String] market The market you'd like to request.
+      # @param [Hash] override_opts Custom options for HTTParty.
+      # @return [Spotify::SDK::Connect::PlaybackState] playback_state Return the playback state object.
+      #
+      def playback(market="from_token", override_opts={})
+        playback_state = send_http_request(:get, "/v1/me/player?market=%s" % market, override_opts)
+        Spotify::SDK::Connect::PlaybackState.new(playback_state, self)
+      end
+
+      ##
+      # Collect all the user's available devices.
+      # GET /v1/me/player/devices
+      #
+      # @example
+      #   @sdk.connect.devices # => [#<Spotify::SDK::Connect::Device:...>, ...]
+      #
+      # @see https://developer.spotify.com/console/get-users-available-devices/
+      #
+      # @param [Hash] override_opts Custom options for HTTParty.
+      # @return [Array] devices A list of all devices.
+      #
+      def devices(override_opts={})
+        response = send_http_request(:get, "/v1/me/player/devices", override_opts)
+        response[:devices].map do |device|
+          Spotify::SDK::Connect::Device.new(device, self)
+        end
+      end
+
+      ##
+      # Collect all the active devices.
+      #
+      # @example
+      #   @sdk.connect.active_devices # => [#<Spotify::SDK::Connect::Device:...>, ...]
+      #
+      # @see https://developer.spotify.com/console/get-users-available-devices/
+      #
+      # @param [Hash] override_opts Custom options for HTTParty.
+      # @return [Array] devices A list of all devices that are marked as `is_active`.
+      #
+      def active_devices(override_opts={})
+        devices(override_opts).select(&:active?)
+      end
+
+      ##
+      # Collect the first active device.
+      #
+      # @example
+      #   @sdk.connect.active_device # => #<Spotify::SDK::Connect::Device:...>
+      #
+      # @see https://developer.spotify.com/console/get-users-available-devices/
+      #
+      # @param [Hash] override_opts Custom options for HTTParty.
+      # @return [Array,NilClass] device The first device with `is_active`. If no device found, returns `nil`.
+      #
+      def active_device(override_opts={})
+        devices(override_opts).find(&:active?)
+      end
+    end
+  end
+end

data/lib/spotify/sdk/connect/device.rb

@@ -0,0 +1,362 @@
+# frozen_string_literal: true
+
+module Spotify
+  class SDK
+    class Connect
+      class Device < Model
+        ##
+        # Get the device's volume.
+        #
+        # @example
+        #   device = @sdk.connect.devices[0]
+        #   device.volume
+        #
+        # @return [Integer] volume Get the volume. Between 0 and 100.
+        #
+        alias_attribute :volume, :volume_percent
+
+        ##
+        # Is the device active?
+        #
+        # @example
+        #   device = @sdk.connect.devices[0]
+        #   device.active?
+        #
+        # @return [Boolean] is_active Bool of whether device is active.
+        #
+        alias_attribute :active?, :is_active
+
+        ##
+        # Is the device's session private?
+        #
+        # @example
+        #   device = @sdk.connect.devices[0]
+        #   device.private_session?
+        #
+        # @return [Boolean] is_private_session Bool of whether device has a private session.
+        #
+        alias_attribute :private_session?, :is_private_session
+
+        ##
+        # Is the device restricted?
+        #
+        # @example
+        #   device = @sdk.connect.devices[0]
+        #   device.restricted?
+        #
+        # @return [Boolean] is_restricted Bool of whether device is restricted.
+        #
+        alias_attribute :restricted?, :is_restricted
+
+        ##
+        # Get the currently playing track.
+        # Alias to Spotify::SDK::Connect#playback
+        #
+        # @example
+        #   device = @sdk.connect.devices[0]
+        #   device.playback
+        #
+        #   # Same as calling the following:
+        #   @sdk.connect.playback
+        #
+        # @see lib/spotify/sdk/connect.rb
+        #
+        # @return [Spotify::SDK::Connect::PlaybackState] self Return the playback state object.
+        #
+        def playback
+          parent.playback
+        end
+
+        ##
+        # Play the currently playing track on device.
+        # PUT /v1/me/player/play
+        #
+        # @example
+        #   device = @sdk.connect.devices[0]
+        #
+        #   # Play from a playlist, album from a specific index in that list.
+        #   # For example, play the 9th item on X playlist.
+        #   device.play!(
+        #     index: 5,
+        #     context: "spotify:album:5ht7ItJgpBH7W6vJ5BqpPr",
+        #     position_ms: 0
+        #   )
+        #
+        #   # Play any Spotify URI. Albums, artists, tracks, playlists, and more.
+        #   device.play!(
+        #     uri: "spotify:track:5MqkZd7a7u7N7hKMqquL2U",
+        #     position_ms: 0
+        #   )
+        #
+        #   # Similar to just uri, but you can define the context.
+        #   # Useful for playing a track that is part of a playlist, and you want the next
+        #   # songs to play from that particular context.
+        #   device.play!(
+        #     uri: "spotify:track:5MqkZd7a7u7N7hKMqquL2U",
+        #     context: "spotify:album:5ht7ItJgpBH7W6vJ5BqpPr",
+        #     position_ms: 0
+        #   )
+        #
+        #   # Play a track, and immediately seek to 60 seconds.
+        #   device.play!(
+        #     index: 5,
+        #     context: "spotify:album:5ht7ItJgpBH7W6vJ5BqpPr",
+        #     position_ms: 60 * 1000
+        #   )
+        #
+        # @see https://developer.spotify.com/console/put-play/
+        #
+        # @param [Hash] config The play config you'd like to set. See code examples.
+        # @return [Spotify::SDK::Connect::Device] self Return itself, so chained methods can be supported.
+        #
+        # rubocop:disable AbcSize
+        def play!(config)
+          payload = case config.keys
+                    when %i[index context position_ms]
+                      {context_uri: config[:context],
+                       offset:      {position: config[:index]},
+                       position_ms: config[:position_ms]}
+                    when %i[uri position_ms]
+                      {uris:        [config[:uri]],
+                       position_ms: config[:position_ms]}
+                    when %i[uri context position_ms]
+                      {context_uri: config[:context],
+                       offset:      {uri: config[:uri]},
+                       position_ms: config[:position_ms]}
+                    else
+                      raise <<-ERROR.strip_heredoc.strip
+                        Unrecognized play instructions.
+                        See https://www.rubydoc.info/github/bih/spotify-ruby/Spotify/SDK/Connect/Device#play!-instance_method for details.
+                      ERROR
+                    end
+
+          parent.send_http_request(:put, "/v1/me/player/play?device_id=%s" % id, http_options: {expect_nil: true},
+                                                                                 body:         payload.to_json)
+          self
+        end
+        # rubocop:enable AbcSize
+
+        ##
+        # Resume the currently playing track on device.
+        # PUT /v1/me/player/play
+        #
+        # @example
+        #   device = @sdk.connect.devices[0]
+        #   device.resume!
+        #
+        # @see https://developer.spotify.com/console/put-play/
+        #
+        # @return [Spotify::SDK::Connect::Device] self Return itself, so chained methods can be supported.
+        #
+        def resume!
+          parent.send_http_request(:put, "/v1/me/player/play?device_id=%s" % id, http_options: {expect_nil: true})
+          self
+        end
+
+        ##
+        # Pause the currently playing track on device.
+        # PUT /v1/me/player/pause
+        #
+        # @example
+        #   device = @sdk.connect.devices[0]
+        #   device.pause!
+        #
+        # @see https://developer.spotify.com/console/put-pause/
+        #
+        # @return [Spotify::SDK::Connect::Device] self Return itself, so chained methods can be supported.
+        #
+        def pause!
+          parent.send_http_request(:put, "/v1/me/player/pause?device_id=%s" % id, http_options: {expect_nil: true})
+          self
+        end
+
+        ##
+        # Skip to previous track on device.
+        # POST /v1/me/player/previous
+        #
+        # @example
+        #   device = @sdk.connect.devices[0]
+        #   device.previous!
+        #
+        # @see https://developer.spotify.com/console/put-previous/
+        #
+        # @return [Spotify::SDK::Connect::Device] self Return itself, so chained methods can be supported.
+        #
+        def previous!
+          parent.send_http_request(:post, "/v1/me/player/previous?device_id=%s" % id, http_options: {expect_nil: true})
+          self
+        end
+
+        ##
+        # Skip to next track on device.
+        # POST /v1/me/player/next
+        #
+        # @example
+        #   device = @sdk.connect.devices[0]
+        #   device.next!
+        #
+        # @see https://developer.spotify.com/console/put-next/
+        #
+        # @return [Spotify::SDK::Connect::Device] self Return itself, so chained methods can be supported.
+        #
+        def next!
+          parent.send_http_request(:post, "/v1/me/player/next?device_id=%s" % id, http_options: {expect_nil: true})
+          self
+        end
+
+        ##
+        # Set volume for current device.
+        # PUT /v1/me/player/volume
+        #
+        # @example
+        #   device = @sdk.connect.devices[0]
+        #   device.change_volume!(30)
+        #
+        #   # or
+        #
+        #   device = @sdk.connect.devices[0]
+        #   device.volume = 30
+        #
+        # @see https://developer.spotify.com/console/put-volume/
+        #
+        # @param [Integer] volume_percent The 0-100 value to change the volume to. 100 is maximum.
+        # @return [Spotify::SDK::Connect::Device] self Return itself, so chained methods can be supported.
+        #
+        def change_volume!(volume_percent)
+          raise "Must be an integer" unless volume_percent.is_a?(Integer)
+
+          endpoint = "/v1/me/player/volume?volume_percent=%i&device_id=%s" % [volume_percent, id]
+          opts = {http_options: {expect_nil: true}}
+          parent.send_http_request(:put, endpoint, opts)
+          self
+        end
+
+        alias_method :volume=, :change_volume!
+
+        ##
+        # Seek position (in milliseconds) for the currently playing track on the device.
+        # PUT /v1/me/player/seek
+        #
+        # @example
+        #   device = @sdk.connect.devices[0]
+        #   device.seek_ms!(4000)
+        #
+        # @see https://developer.spotify.com/console/put-seek/
+        #
+        # @param [Integer] position_ms In milliseconds, where to seek in the current track on device.
+        # @return [Spotify::SDK::Connect::Device] self Return itself, so chained methods can be supported.
+        #
+        def seek_ms!(position_ms)
+          raise "Must be an integer" unless position_ms.is_a?(Integer)
+
+          endpoint = "/v1/me/player/seek?position_ms=%i&device_id=%s" % [position_ms, id]
+          opts = {http_options: {expect_nil: true}}
+          parent.send_http_request(:put, endpoint, opts)
+          self
+        end
+
+        alias_method :position_ms=, :seek_ms!
+
+        ##
+        # Set repeat mode for current device.
+        # PUT /v1/me/player/repeat
+        #
+        # @example
+        #   device = @sdk.connect.devices[0]
+        #   device.repeat!(:track)
+        #   device.repeat!(:context)
+        #   device.repeat!(:off)
+        #
+        # @see https://developer.spotify.com/console/put-repeat/
+        #
+        # @param [Boolean] state What to set the repeat state to - :track, :context, or :off
+        # @return [Spotify::SDK::Connect::Device] self Return itself, so chained methods can be supported.
+        #
+        def repeat!(state)
+          raise "Must be :track, :context, or :off" unless %i[track context off].include?(state)
+
+          endpoint = "/v1/me/player/repeat?state=%s&device_id=%s" % [state, id]
+          opts = {http_options: {expect_nil: true}}
+          parent.send_http_request(:put, endpoint, opts)
+          self
+        end
+
+        alias_method :repeat=, :repeat!
+
+        ##
+        # Set shuffle for current device.
+        # PUT /v1/me/player/shuffle
+        #
+        # @example
+        #   device = @sdk.connect.devices[0]
+        #   device.shuffle!(true)
+        #
+        # @see https://developer.spotify.com/console/put-shuffle/
+        #
+        # @param [Boolean] state The true/false of if you'd like to set shuffle on.
+        # @return [Spotify::SDK::Connect::Device] self Return itself, so chained methods can be supported.
+        #
+        def shuffle!(state)
+          raise "Must be true or false" unless [true, false].include?(state)
+
+          endpoint = "/v1/me/player/shuffle?state=%s&device_id=%s" % [state, id]
+          opts = {http_options: {expect_nil: true}}
+          parent.send_http_request(:put, endpoint, opts)
+          self
+        end
+
+        alias_method :shuffle=, :shuffle!
+
+        ##
+        # Transfer a user's playback to another device, and continue playing.
+        # PUT /v1/me/player
+        #
+        # @example
+        #   device = @sdk.connect.devices[0]
+        #   device.transfer_playback!
+        #
+        # @see https://developer.spotify.com/console/transfer-a-users-playback/
+        #
+        # @return [Spotify::SDK::Connect::Device] self Return itself, so chained methods can be supported.
+        #
+        def transfer_playback!
+          transfer_playback_method(playing: true)
+          self
+        end
+
+        ##
+        # Transfer a user's playback to another device, and pause.
+        # PUT /v1/me/player
+        #
+        # @example
+        #   device = @sdk.connect.devices[0]
+        #   device.transfer_state!
+        #
+        # @see https://developer.spotify.com/console/transfer-a-users-playback/
+        #
+        # @return [Spotify::SDK::Connect::Device] self Return itself, so chained methods can be supported.
+        #
+        def transfer_state!
+          transfer_playback_method(playing: false)
+          self
+        end
+
+        private
+
+        def transfer_playback_method(playing:) # :nodoc:
+          override_opts = {
+            http_options: {
+              expect_nil: true
+            },
+            body:         {
+              device_ids: [id],
+              play:       playing
+            }.to_json
+          }
+
+          parent.send_http_request(:put, "/v1/me/player", override_opts)
+        end
+      end
+    end
+  end
+end