spotify-ruby-kev 0.2.5

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

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Spotify
+  class SDK
+    class Connect
+      class PlaybackState < Model
+        ##
+        # Get the device the current playback is on.
+        #
+        # @example
+        #   device = @sdk.connect.devices[0]
+        #   device.playback.device
+        #
+        # @return [Spotify::SDK::Connect::Device] self Return the device object.
+        #
+        def device
+          Spotify::SDK::Connect::Device.new(super, parent)
+        end
+
+        ##
+        # Is the current user playing a track?
+        #
+        # @example
+        #   playback = @sdk.connect.playback
+        #   playback.playing?
+        #
+        # @return [FalseClass,TrueClass] is_playing True if user is currently performing playback.
+        #
+        alias_attribute :playing?, :is_playing
+
+        ##
+        # Is the current playback set to shuffle?
+        #
+        # @example
+        #   playback = @sdk.connect.playback
+        #   playback.shuffling?
+        #
+        # @return [FalseClass,TrueClass] is_shuffling True if shuffle is set.
+        #
+        alias_attribute :shuffling?, :shuffle_state
+
+        ##
+        # What repeat mode is the current playback set to?
+        #
+        # Options:
+        #   :off => This means no repeat is set.
+        #   :context => This means it will repeat within the same context.
+        #   :track => This will repeat the same track.
+        #
+        # @example
+        #   playback = @sdk.connect.playback
+        #   playback.repeat # :off, :context, or :track
+        #
+        # @return [Symbol] repeat_mode Either :off, :context, or :track
+        #
+        def repeat_mode
+          repeat_state.to_sym
+        end
+
+        ##
+        # The current timestamp of the playback state
+        #
+        # @example
+        #   playback = @sdk.connect.playback
+        #   playback.time
+        #
+        # @return [Time] time The accuracy time of the playback state.
+        #
+        def time
+          Time.at(timestamp / 1000)
+        end
+
+        ##
+        # What is the current position of the track?
+        #
+        # @example
+        #   playback = @sdk.connect.playback
+        #   playback.position
+        #
+        # @return [Integer] position_ms In milliseconds, the position of the track.
+        #
+        alias_attribute :position, :progress_ms
+
+        ##
+        # How much percentage of the track is the position currently in?
+        #
+        # @example
+        #   playback = @sdk.connect.playback
+        #   playback.position_percentage # => 7.30
+        #   playback.position_percentage(4) # => 7.3039
+        #
+        # @param [Integer] decimal_points How many decimal points to return
+        # @return [Float] percentage Completion percentage. Rounded to 2 decimal places.
+        #
+        def position_percentage(decimal_points=2)
+          return nil if position.nil?
+
+          ((position.to_f / item.duration.to_f) * 100).ceil(decimal_points)
+        end
+
+        ##
+        # Get the artists for the currently playing track.
+        #
+        # @example
+        #   @sdk.connect.playback.artists
+        #
+        # @return [Array] artists An array of artists wrapped in Spotify::SDK::Artist
+        #
+        def artists
+          item[:artists].map do |artist|
+            Spotify::SDK::Artist.new(artist, parent)
+          end
+        end
+
+        ##
+        # Get the main artist for the currently playing track.
+        #
+        # @example
+        #   @sdk.connect.playback.artist
+        #
+        # @return [Spotify::SDK::Artist] artist The main artist of the track.
+        #
+        def artist
+          artists.first
+        end
+
+        ##
+        # Get the item for the currently playing track.
+        #
+        # @example
+        #   @sdk.connect.playback.item
+        #
+        # @return [Spotify::SDK::Item] item The currently playing track, wrapped in Spotify::SDK::Item
+        #
+        def item
+          raise "Playback information is not available if user has a private session enabled" if device.private_session?
+
+          Spotify::SDK::Item.new(to_h, parent)
+        end
+      end
+    end
+  end
+end

data/lib/spotify/sdk/image.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Spotify
+  class SDK
+    class Image < Model
+      ##
+      # Get the ID of the image.
+      #
+      # @example
+      #   artist = @sdk.connect.playback.artist
+      #   artist.images[0].id # => "941223d904f006c4d998598272d43d94"
+      #
+      # @return [String] image_id The image ID generated from Spotify.
+      #
+      def id
+        url.match(/[a-z0-9]+$/i)[0]
+      end
+
+      ##
+      # Get the mobile-related link for the image. Designed for offline mobile apps.
+      #
+      # @example
+      #   artist = @sdk.connect.playback.artist
+      #   artist.images[0].spotify_uri # => "spoitfy:image:..."
+      #
+      # @return [String] spotify_uri The mobile-embeddable image for the item.
+      #
+      def spotify_uri
+        "spotify:image:%s" % id
+      end
+
+      ##
+      # Get the HTTP link for the image. Designed for web apps.
+      #
+      # @example
+      #   artist = @sdk.connect.playback.artist
+      #   artist.images[0].spotify_url # => "https://i.scdn.co/image/..."
+      #
+      # @return [String] spotify_url The web-embeddable HTTP image for the item.
+      #
+      alias_attribute :spotify_url, :url
+    end
+  end
+end

data/lib/spotify/sdk/item.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module Spotify
+  class SDK
+    class Item < Model
+      ##
+      # Let's transform the item object into better for us.
+      # Before: { track: ..., played_at: ..., context: ... }
+      # After: { track_properties..., played_at: ..., context: ... }
+      #
+      # :nodoc:
+      def initialize(payload, parent)
+        track      = payload.delete(:track) || payload.delete(:item)
+        properties = payload.except(:parent, :device, :repeat_state, :shuffle_state)
+        super(track.merge(properties: properties), parent)
+      end
+
+      ##
+      # Get the album for this item.
+      #
+      # @example
+      #   @sdk.connect.playback.item.album
+      #
+      # @return [Spotify::SDK::Album] album The album object, wrapped in Spotify::SDK::Album
+      #
+      def album
+        Spotify::SDK::Album.new(super, parent)
+      end
+
+      ##
+      # Get the artists/creators for this item.
+      #
+      # @example
+      #   @sdk.connect.playback.item.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 item.
+      #
+      # @example
+      #   @sdk.connect.playback.item.artist
+      #
+      # @return [Spotify::SDK::Artist] artist The primary artist, wrapped in Spotify::SDK::Artist
+      #
+      def artist
+        artists.first
+      end
+
+      ##
+      # Get the context.
+      #
+      # @example
+      #   @sdk.connect.playback.item.context
+      #   @sdk.me.history[0].context
+      #
+      # @return [Hash] context Information about the user's context.
+      #
+      alias_attribute :context, "properties.context"
+
+      ##
+      # Get the duration.
+      # Alias to self.duration_ms
+      #
+      # @example
+      #   @sdk.connect.playback.item.duration # => 10331
+      #
+      # @return [Integer] duration_ms In milliseconds, how long the item is.
+      #
+      alias_attribute :duration, :duration_ms
+
+      ##
+      # Is this track explicit?
+      # Alias to self.explicit
+      #
+      # @example
+      #   @sdk.connect.playback.item.explicit? # => true
+      #
+      # @return [TrueClass,FalseClass] is_explicit Returns true if item contains explicit content.
+      #
+      alias_attribute :explicit?, :explicit
+
+      ##
+      # Is this a local track, not a Spotify track?
+      # Alias to self.is_local
+      #
+      # @example
+      #   @sdk.connect.playback.item.local? # => false
+      #
+      # @return [TrueClass,FalseClass] is_local Returns true if item is local to the user.
+      #
+      alias_attribute :local?, :is_local
+
+      ##
+      # Is this a playable track?
+      # Alias to self.is_playable
+      #
+      # @example
+      #   @sdk.connect.playback.item.playable? # => false
+      #
+      # @return [TrueClass,FalseClass] is_playable Returns true if item is playable.
+      #
+      alias_attribute :playable?, :is_playable
+
+      ##
+      # Is this a track?
+      # Alias to self.type == "track"
+      #
+      # @example
+      #   @sdk.connect.playback.item.track? # => true
+      #
+      # @return [TrueClass,FalseClass] is_track Returns true if item is an music track.
+      #
+      def track?
+        type == "track"
+      end
+
+      ##
+      # Get the Spotify URI for this item.
+      # Alias to self.uri
+      #
+      # @example
+      #   @sdk.connect.playback.item.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 item.
+      # Alias to self.external_urls[:spotify]
+      #
+      # @example
+      #   @sdk.connect.playback.item.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"
+
+      ##
+      # Get the ISRC for this track.
+      #
+      # @example
+      #   @sdk.connect.playback.item.isrc # => "USUM00000000"
+      #
+      # @return [String] isrc The ISRC string for this track.
+      #
+      alias_attribute :isrc, "external_ids.isrc"
+    end
+  end
+end

data/lib/spotify/sdk/me.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module Spotify
+  class SDK
+    class Me < Base
+      ##
+      # Get the current user's information.
+      # Respective information requires the `user-read-private user-read-email user-read-birthdate` scopes.
+      # GET /v1/me
+      #
+      # @example
+      #   me = @sdk.me.info
+      #
+      # @see https://developer.spotify.com/console/get-current-user/
+      # @see https://developer.spotify.com/documentation/web-api/reference/users-profile/get-current-users-profile/
+      #
+      # @param [Hash] override_opts Custom options for HTTParty.
+      # @return [Spotify::SDK::Me::Info] user_info Return the user's information.
+      #
+      def info(override_opts={})
+        me_info = send_http_request(:get, "/v1/me", override_opts)
+        Spotify::SDK::Me::Info.new(me_info, self)
+      end
+
+      ##
+      # Check what tracks a user has recently played.
+      #
+      # @example
+      #   @sdk.me.history
+      #   @sdk.me.history(20)
+      #
+      # @param [Integer] limit How many results to request. Defaults to 10.
+      # @param [Hash] override_opts Custom options for HTTParty.
+      # @return [Array] response List of recently played tracked, in chronological order.
+      #
+      def history(limit=10, override_opts={})
+        request = {
+          method:    :get,
+          http_path: "/v1/me/player/recently-played",
+          keys:      %i[items],
+          limit:     limit
+        }
+
+        send_multiple_http_requests(request, override_opts).map do |item|
+          Spotify::SDK::Item.new(item, self)
+        end
+      end
+
+      ##
+      # Check if the current user is following N users.
+      #
+      # @example
+      #   artists = %w(3q7HBObVc0L8jNeTe5Gofh 0NbfKEOTQCcwd6o7wSDOHI 3TVXtAsR1Inumwj472S9r4)
+      #   @sdk.me.following?(artists, :artist)
+      #     # => {"3q7HBObVc0L8jNeTe5Gofh" => false, "0NbfKEOTQCcwd6o7wSDOHI" => false, ...}
+      #
+      #   users = %w(3q7HBObVc0L8jNeTe5Gofh 0NbfKEOTQCcwd6o7wSDOHI 3TVXtAsR1Inumwj472S9r4)
+      #   @sdk.me.following?(users, :user)
+      #     # => {"3q7HBObVc0L8jNeTe5Gofh" => false, "0NbfKEOTQCcwd6o7wSDOHI" => false, ...}
+      #
+      # @param [Array] list List of Spotify user/artist IDs. Cannot mix user and artist IDs in single request.
+      # @param [Symbol] type Either :user or :artist. Checks if follows respective type of account.
+      # @param [Hash] override_opts Custom options for HTTParty.
+      # @return [Hash] hash A hash containing a key with the ID, and a value that equals is_following (boolean).
+      #
+      def following?(list, type=:artist, override_opts={})
+        raise "Must contain an array" unless list.is_a?(Array)
+        raise "Must contain an array of String or Spotify::SDK::Artist" if any_of?(list, [String, Spotify::SDK::Artist])
+        raise "type must be either 'artist' or 'user'" unless %i[artist user].include?(type)
+
+        send_is_following_http_requests(list.map {|id| id.try(:id) || id }, type, override_opts)
+      end
+
+      def following_artists?(list, override_opts={})
+        following?(list, :artist, override_opts)
+      end
+
+      def following_users?(list, override_opts={})
+        following?(list, :user, override_opts)
+      end
+
+      ##
+      # Get the current user's followed artists. Requires the `user-read-follow` scope.
+      # GET /v1/me/following
+      #
+      # @example
+      #   @sdk.me.following
+      #
+      # @param [Integer] n Number of results to return.
+      # @param [Hash] override_opts Custom options for HTTParty.
+      # @return [Array] artists A list of followed artists, wrapped in Spotify::SDK::Artist
+      #
+      def following(limit=50, override_opts={})
+        request = {
+          method:    :get,
+          # TODO: Spotify API bug - `limit={n}` returns n-1 artists.
+          # ^ Example: `limit=5` returns 4 artists.
+          # TODO: Support `type=users` as well as `type=artists`.
+          http_path: "/v1/me/following?type=artist&limit=#{[limit, 50].min}",
+          keys:      %i[artists items],
+          limit:     limit
+        }
+
+        send_multiple_http_requests(request, override_opts).map do |artist|
+          Spotify::SDK::Artist.new(artist, self)
+        end
+      end
+
+      private
+
+      def any_of?(array, klasses) # :nodoc:
+        (array.map(&:class) - klasses).any?
+      end
+
+      def send_multiple_http_requests(opts, override_opts) # :nodoc:
+        response = send_http_request(opts[:method], opts[:http_path], override_opts)
+        responses, next_request = hash_deep_lookup(response, opts[:keys].dup)
+        if next_request && responses.size < opts[:limit]
+          responses += send_multiple_http_requests(opts.merge(http_path: next_request), override_opts)
+        end
+        responses.first(opts[:limit])
+      end
+
+      def hash_deep_lookup(response, keys) # :nodoc:
+        error_message = "Cannot find '%s' key in Spotify::SDK::Me#hash_deep_lookup"
+        while keys.any?
+          next_request ||= response[:next]
+          next_key = keys.shift
+          response = next_key ? response[next_key] : raise(error_message % next_key)
+        end
+        [response, next_request ? next_request[23..-1] : nil]
+      end
+
+      # TODO: Migrate this into the abstracted send_multiple_http_requests
+      def send_is_following_http_requests(list, type, override_opts) # :nodoc:
+        max_ids = list.first(50)
+        remaining_ids = list - max_ids
+
+        ids = max_ids.map {|id| {id.strip => nil} }.inject(&:merge)
+        following = send_http_request(
+          :get,
+          "/v1/me/following/contains?type=%s&ids=%s" % [type, ids.keys.join(",")],
+          override_opts
+        )
+        ids.each_key {|id| ids[id] = following.shift }
+
+        # rubocop:disable Style/IfUnlessModifier
+        if remaining_ids.any?
+          ids.merge(send_is_following_http_requests(remaining_ids, type, override_opts))
+        end || ids
+        # rubocop:enable Style/IfUnlessModifier
+      end
+    end
+  end
+end