spotify-ruby 0.1.1 → 0.2.1

data/lib/spotify/sdk/album.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Spotify
+  class SDK
+    class Album < Model
+      ##
+      # Is this an album?
+      # Note: This is mostly to support other types of albums in the future.
+      #
+      # @example
+      #   album = @sdk.connect.playback.item.album
+      #   album.album?
+      #
+      # @return [TrueClass,FalseClass] is_album Returns true if type is an album.
+      #
+      def album?
+        type == "album"
+      end
+
+      ##
+      # Display the album's images.
+      #
+      # @example
+      #   album = @sdk.connect.playback.item.album
+      #   album.images[0] # => [#<Spotify::SDK::Image>, #<Spotify::SDK::Image>, ...]
+      #
+      # @return [Array] album_images Contains a list of images, wrapped in Spotify::SDK::Image
+      #
+      def images
+        super.map do |image|
+          Spotify::SDK::Image.new(image, parent)
+        end
+      end
+
+      ##
+      # Get the artists/creators for this album.
+      #
+      # @example
+      #   @sdk.connect.playback.item.album.artists
+      #
+      # @return [Array] artists A list of artists, wrapped in Spotify::SDK::Artist
+      #
+      def artists
+        super.map do |artist|
+          Spotify::SDK::Artist.new(artist, parent)
+        end
+      end
+
+      ##
+      # Get the primary artist/creator for this album.
+      #
+      # @example
+      #   @sdk.connect.playback.item.album.artist
+      #
+      # @return [Spotify::SDK::Artist] artist The primary artist, wrapped in Spotify::SDK::Artist
+      #
+      def artist
+        artists.first
+      end
+
+      ##
+      # Get the Spotify URI for this album.
+      # Alias to self.uri
+      #
+      # @example
+      #   @sdk.connect.playback.item.album.spotify_uri # => "spotify:track:..."
+      #
+      # @return [String] spotify_uri The direct URI to this Spotify resource.
+      #
+      alias_attribute :spotify_uri, :uri
+
+      ##
+      # Get the Spotify HTTP URL for this album.
+      # Alias to self.external_urls[:spotify]
+      #
+      # @example
+      #   @sdk.connect.playback.item.album.spotify_url # => "https://open.spotify.com/..."
+      #
+      # @return [String] spotify_url The direct HTTP URL to this Spotify resource.
+      #
+      alias_attribute :spotify_url, "external_urls.spotify"
+    end
+  end
+end

data/lib/spotify/sdk/artist.rb

@@ -0,0 +1,162 @@
+# 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

@@ -13,19 +13,19 @@ module Spotify
       # Initiate a Spotify SDK Base component.
       #
       # @example
-      #   @sdk = Spotify::SDK.new("access_token")
+      #   @sdk = Spotify::SDK.new(@session)
       #   @auth = Spotify::SDK::Base.new(@sdk)
       #
-      #   @sdk = Spotify::SDK.new("access_token_here")
+      #   @sdk = Spotify::SDK.new(@session)
       #   @sdk.to_hash # => { access_token: ..., expires_at: ... }
       #
-      # @param [Spotify::SDK] sdk An instance of Spotify::SDK as a reference point.
+      # @param [Spotify::SDK] parent An instance of Spotify::SDK as a reference point.
       #
-      def initialize(sdk)
-        @sdk = sdk
+      def initialize(parent)
+        @parent = parent
         @options = {
           headers: {
-            Authorization: "Bearer %s" % sdk.access_token
+            Authorization: "Bearer %s" % @parent.session.access_token
           }
         }
       end
@@ -38,21 +38,39 @@ module Spotify
       #   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(raw: true))
+      #   send_http_request(:get, "/v1/me/player/devices", @options.merge({http_options: { raw: true }}))
       #
-      # @param [Hash,HTTParty::Response] response The response from the HTTP request.
-      # @return
+      #   # 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 }}))
       #
-      def send_http_request(method, endpoint, opts={}, &_block)
-        sdk_opts = opts[:_sdk_opts].presence || {}
-        opts_sdk = {raw: false, expect_nil: false}.merge(sdk_opts)
-        response = self.class.send(method, endpoint, @options.merge(opts))
-        response = response.parsed_response.try(:deep_symbolize_keys) if opts_sdk[:raw] == false
-        response = true if opts_sdk[:expect_nil] == true && response.nil?
+      # @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 :sdk
+      attr_reader :parent
     end
   end
 end

data/lib/spotify/sdk/connect.rb

@@ -3,6 +3,25 @@
 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
@@ -10,10 +29,10 @@ module Spotify
       # @example
       #   @sdk.connect.devices # => [#<Spotify::SDK::Connect::Device:...>, ...]
       #
-      # @see https://developer.spotify.com/web-api/console/get-users-available-devices/
+      # @see https://developer.spotify.com/console/get-users-available-devices/
       #
       # @param [Hash] override_opts Custom options for HTTParty.
-      # @return
+      # @return [Array] devices A list of all devices.
       #
       def devices(override_opts={})
         response = send_http_request(:get, "/v1/me/player/devices", override_opts)
@@ -21,6 +40,36 @@ module Spotify
           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

@@ -4,14 +4,286 @@ 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")
+        #
+        #   # Play any Spotify URI. Albums, artists, tracks, playlists, and more.
+        #   device.play!(uri: "spotify:track:5MqkZd7a7u7N7hKMqquL2U")
+        #
+        #   # 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")
+        #
+        # @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.
+        #
+        def play!(config)
+          payload = case config.keys
+                    when %i[index context]
+                      {context_uri: config[:context], offset: {position: config[:index]}}
+                    when %i[uri]
+                      {uris: [config[:uri]]}
+                    when %i[uri context]
+                      {context_uri: config[:context], offset: {uri: config[:uri]}}
+                    else
+                      raise "Unrecognized play instructions. See documentation for details."
+                    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
+
+        ##
+        # 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.
+        # PUT /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(:put, "/v1/me/player/previous?device_id=%s" % id, http_options: {expect_nil: true})
+          self
+        end
+
+        ##
+        # Skip to next track on device.
+        # PUT /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(:put, "/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.transfer_playback!
+        #   device = @sdk.connect.devices[0]
+        #   device.transfer_playback!
         #
-        # @see https://developer.spotify.com/web-api/transfer-a-users-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.
         #
@@ -25,9 +297,10 @@ module Spotify
         # PUT /v1/me/player
         #
         # @example
-        #   device = @sdk.connect.transfer_state!
+        #   device = @sdk.connect.devices[0]
+        #   device.transfer_state!
         #
-        # @see https://developer.spotify.com/web-api/transfer-a-users-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.
         #
@@ -38,10 +311,12 @@ module Spotify
 
         private
 
-        def transfer_playback_method(playing:)
+        def transfer_playback_method(playing:) # :nodoc:
           override_opts = {
-            _sdk_opts: {expect_nil: true},
-            body:      {
+            http_options: {
+              expect_nil: true
+            },
+            body:         {
               device_ids: [id],
               play:       playing
             }.to_json