spotify-ruby-kev 0.2.5

data/lib/spotify/accounts.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Spotify
+  ##
+  # Spotify::Accounts deals with authorization using the Spotify Accounts API.
+  #
+  class Accounts
+    ##
+    # An entire list of Spotify's OAuth scopes. Stored
+    # in the form of a symbolized array.
+    # Example: `[:scope1, :scope2]`
+    #
+    # @see https://developer.spotify.com/documentation/general/guides/scopes/
+    #
+    # Last updated: 23 June 2018
+    #
+    SCOPES = %i[
+      playlist-read-private
+      playlist-read-collaborative
+      playlist-modify-public
+      playlist-modify-private
+      ugc-image-upload
+      user-follow-modify
+      user-follow-read
+      user-library-read
+      user-library-modify
+      user-read-private
+      user-read-birthdate
+      user-read-email
+      user-top-read
+      user-read-playback-state
+      user-modify-playback-state
+      user-read-currently-playing
+      user-read-recently-played
+      streaming
+      app-remote-control
+    ].freeze
+
+    ##
+    # Initialize the Spotify Accounts object.
+    #
+    # @example
+    #   @accounts = Spotify::Accounts.new({
+    #     client_id: "[client id goes here]",
+    #     client_secret: "[client secret goes here]",
+    #     redirect_uri: "http://localhost"
+    #   })
+    #
+    #   @accounts = Spotify::Accounts.new
+    #   @accounts.client_id = "[client id goes here]"
+    #   @accounts.client_secret = "[client secret goes here]"
+    #   @accounts.redirect_uri = "http://localhost"
+    #
+    #   # with SPOTIFY_CLIENT_ID, SPOTIFY_CLIENT_SECRET, and SPOTIFY_REDIRECT_URI in ENV:
+    #   @accounts = Spotify::Accounts.new
+    #
+    # @param [Hash] config The configuration containing your Client ID, Client Secret, and your Redirect URL.
+    #
+    # @see https://developer.spotify.com/dashboard/
+    #
+    def initialize(config={})
+      @client_id = config.delete(:client_id) { ENV["SPOTIFY_CLIENT_ID"] }
+      @client_secret = config.delete(:client_secret) { ENV["SPOTIFY_CLIENT_SECRET"] }
+      @redirect_uri = config.delete(:redirect_uri) { ENV["SPOTIFY_REDIRECT_URI"] }
+    end
+
+    attr_accessor :client_id, :client_secret, :redirect_uri
+
+    ##
+    # Get a HTTP URL to send user for authorizing with Spotify.
+    #
+    # @example
+    #   @accounts = Spotify::Accounts.new({
+    #     client_id: "[client id goes here]",
+    #     client_secret: "[client secret goes here]",
+    #     redirect_uri: "http://localhost"
+    #   })
+    #
+    #   @auth.authorize_url
+    #   @auth.authorize_url({ scope: "user-read-private user-top-read" })
+    #
+    # @param [Hash] override_params Optional hash containing any overriding values for parameters.
+    # Parameters used are client_id, redirect_uri, response_type and scope.
+    # @return [String] A fully qualified Spotify authorization URL to send the user to.
+    #
+    # @see https://developer.spotify.com/documentation/general/guides/authorization-guide/
+    #
+    def authorize_url(override_params={})
+      validate_credentials!
+      params = {
+        client_id:     @client_id,
+        redirect_uri:  @redirect_uri,
+        response_type: "code",
+        scope:         SCOPES.join(" ")
+      }.merge(override_params)
+      "https://accounts.spotify.com/authorize?%s" % params.to_query
+    end
+
+    ##
+    # Start a session from your authentication code.
+    #
+    # @example
+    #   @accounts = Spotify::Accounts.new({
+    #     client_id: "[client id goes here]",
+    #     client_secret: "[client secret goes here]",
+    #     redirect_uri: "http://localhost"
+    #   })
+    #
+    #   @accounts.exchange_for_session("code")
+    #
+    # @param [String] code The code provided back to your application upon authorization.
+    # @return [Spotify::Accounts::Session] session The session object.
+    #
+    # @see https://developer.spotify.com/documentation/general/guides/authorization-guide/
+    #
+    def exchange_for_session(code)
+      validate_credentials!
+      Spotify::Accounts::Session.from_authorization_code(code)
+    end
+
+    def inspect # :nodoc:
+      "#<%s:0x00%x>" % [self.class.name, (object_id << 1)]
+    end
+
+    private
+
+    def validate_credentials! # :nodoc:
+      raise "Missing client id" if @client_id.nil?
+      raise "Missing client secret" if @client_secret.nil?
+      raise "Missing redirect uri" if @redirect_uri.nil?
+    end
+  end
+end

data/lib/spotify/accounts/session.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+module Spotify
+  class Accounts
+    ##
+    # A class representing an access token, with the ability to refresh.
+    #
+    class Session
+      class << self
+        ##
+        # Parse the response we collect from the authorization code.
+        #
+        # @example
+        #   @session = Spotify::Accounts.from_authorization_code(@accounts, "authorization code here")
+        #
+        # @param [Spotify::Accounts] accounts A valid instance of Spotify::Accounts.
+        # @param [String] code The code provided in the Redirect URI from the Spotify Accounts API.
+        # @return [Spotify::Accounts::Session] access_token An instance of Spotify::Accounts::Session
+        # @see lib/spotify/accounts.rb
+        #
+        def from_authorization_code(accounts, code)
+          params = {
+            client_id:     @accounts.instance_variable_get(:@client_id),
+            client_secret: @accounts.instance_variable_get(:@client_secret),
+            redirect_uri:  @accounts.instance_variable_get(:@redirect_uri),
+            grant_type:    "authorization_code",
+            code:          code
+          }
+          request = HTTParty.post("https://accounts.spotify.com/api/token", body: params)
+          response = request.parsed_response.with_indifferent_access
+          raise response[:error_description] if response[:error]
+
+          new(accounts, response[:access_token], response[:expires_in], response[:refresh_token], response[:scope])
+        end
+
+        ##
+        # Set up an instance of Access Token with just a refresh_token.
+        #
+        # @example
+        #   @access_token = Spotify::Accounts::Session.from_refresh_token(@accounts, "refresh token here")
+        #   @access_token.force_refresh!
+        #
+        # @param [Spotify::Accounts] accounts A valid instance of Spotify::Accounts.
+        # @param [String] refresh_token A valid refresh token. You'll want to store the refresh_token in your database.
+        # @return [Spotify::Accounts::Session] access_token An instance of Spotify::Accounts::Session
+        #
+        def from_refresh_token(accounts, refresh_token)
+          new(accounts, nil, nil, refresh_token, nil)
+        end
+      end
+
+      def initialize(accounts, access_token, expires_in, refresh_token, scopes)
+        unless accounts.instance_of?(Spotify::Accounts)
+          raise "You need a valid Spotify::Accounts instance in order to use Spotify authentication."
+        end
+
+        @accounts = accounts
+        @access_token = access_token
+        @expires_in = expires_in
+        @expires_at = expires_in + Time.now.to_i unless expires_in.nil?
+        @refresh_token = refresh_token
+        @scopes = scopes
+      end
+
+      attr_reader :accounts, :access_token, :expires_in, :refresh_token
+
+      ##
+      # Converts the space-delimited scope list to a symbolized array.
+      #
+      # @example
+      #   @access_token.scopes # => [:"user-read-private", :"user-top-read", ...]
+      #
+      # @return [Array] scopes A symbolized list of scopes.
+      #
+      def scopes
+        return [] if @scopes.nil?
+
+        @scopes.split(" ").map(&:to_sym)
+      end
+
+      ##
+      # Checks if a specific scope has been granted by the user.
+      #
+      # @example
+      #   @access_token.contains_scope?("user-read-top")
+      #   @access_token.contains_scope?(:"user-read-top")
+      #
+      # @param [String,Symbol] scope The name of the scope you'd like to check. For example, "user-read-private".
+      # @return [TrueClass,FalseClass] scope_included A true/false boolean if the scope is included.
+      #
+      def contains_scope?(scope)
+        scopes.include?(scope.downcase.to_sym)
+      end
+
+      ##
+      # When will the access token expire? Returns nil if no expires_in is defined.
+      #
+      # @example
+      #   @session.expires_at
+      #
+      # @return [Time] time When the access token will expire.
+      #
+      def expires_at
+        return nil if @expires_in.nil?
+
+        Time.at(@expires_at)
+      end
+
+      ##
+      # Check if the access token has expired. Returns nil if no expires_in is defined.
+      #
+      # @example
+      #   @session.expired?
+      #
+      # @return [TrueClass,FalseClass,NilClass] has_expired Has the access token expired?
+      #
+      def expired?
+        return nil if expires_at.nil?
+
+        Time.now > expires_at
+      end
+
+      ##
+      # Refresh the access token.
+      #
+      # @example
+      #   @session.refresh!
+      #
+      # @return [TrueClass,FalseClass] success Have we been able to refresh the access token?
+      #
+      # rubocop:disable AbcSize
+      def refresh!
+        raise "You cannot refresh without a valid refresh_token." if @refresh_token.nil?
+
+        params = {
+          client_id:     @accounts.instance_variable_get(:@client_id),
+          client_secret: @accounts.instance_variable_get(:@client_secret),
+          grant_type:    "refresh_token",
+          refresh_token: @refresh_token
+        }
+        request = HTTParty.post("https://accounts.spotify.com/api/token", body: params)
+        response = request.parsed_response.with_indifferent_access
+
+        @access_token = response[:access_token]
+        @expires_in = response[:expires_in]
+        @expires_at = response[:expires_in] + Time.now.to_i
+        @scopes = response[:scope]
+
+        true
+      rescue HTTParty::Error
+        false
+      end
+      # rubocop:enable AbcSize
+
+      ##
+      # Export to JSON. Designed mostly for iOS, Android, or external use cases.
+      #
+      # @example
+      #   @session.to_json
+      #
+      # @return [String] json The JSON output of the session instance.
+      #
+      def to_json(*_args)
+        {
+          access_token:  @access_token.presence,
+          expires_at:    @expires_at.presence,
+          refresh_token: @refresh_token.presence,
+          scopes:        scopes
+        }.to_json
+      end
+
+      def inspect # :nodoc:
+        "#<%s:0x00%x>" % [self.class.name, (object_id << 1)]
+      end
+    end
+  end
+end

data/lib/spotify/sdk.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+# Scaffolding
+require "spotify/sdk/base"
+require "spotify/sdk/model"
+
+# Components
+require "spotify/sdk/connect"
+require "spotify/sdk/me"
+
+# Models
+require "spotify/sdk/connect/device"
+require "spotify/sdk/connect/playback_state"
+require "spotify/sdk/me/info"
+require "spotify/sdk/artist"
+require "spotify/sdk/album"
+require "spotify/sdk/image"
+require "spotify/sdk/item"
+
+module Spotify
+  ##
+  # Spotify::SDK contains the complete Ruby DSL to interact with the Spotify Platform.
+  #
+  class SDK
+    ##
+    # Initialize the Spotify SDK object.
+    #
+    # @example
+    #   # Example 1: Load it in from an access token value.
+    #   @sdk = Spotify::SDK.new("access_token_here")
+    #
+    #   # Example 2: Load it in with values from your database.
+    #   @sdk = Spotify::SDK.new({
+    #     access_token: "access_token_here",
+    #     expires_in: 3_000_000,
+    #     refresh_token: "refresh_token_here"
+    #   })
+    #
+    #   # Example 4: Load it in from an OAuth2::AccessToken object.
+    #   @sdk = Spotify::SDK.new(@auth.auth_code.get_token("auth code"))
+    #
+    #   # Example 5: Load it from a query string or a fully qualified URL.
+    #   @sdk = Spotify::SDK.new("https://localhost:8080/#token=...&expires_in=...")
+    #   @sdk = Spotify::SDK.new("token=...&expires_in=...")
+    #
+    # @param [String,Hash,OAuth2::AccessToken] session Any supported object containing an access token.
+    #
+    def initialize(session)
+      raise "Invalid Spotify::Accounts::Session object" unless session.instance_of?(Spotify::Accounts::Session)
+
+      @session = session
+      mount_sdk_components
+    end
+
+    attr_reader :session
+
+    def inspect # :nodoc:
+      "#<%s:0x00%x>" % [self.class.name, (object_id << 1)]
+    end
+
+    ##
+    # This is where we mount new SDK components to the Spotify::SDK object.
+    # Simply add a key (this is your identifier) with the value being the object.
+    #
+    # Notes:
+    # - Make sure your SDK component is being loaded at the top of this page.
+    # - You can name your identifier whatever you want:
+    #   - This will be what people will use to call your code
+    #   - For example: it would be the `connect` in `Spotify::SDK.new(@session).connect`
+    # - We'll call .new on your class, providing one parameter being the instance of this SDK (aka self).
+    # - Make sure to a test for it in spec/lib/spotify/sdk_spec.rb (see how we did it for others)
+    #
+    SDK_COMPONENTS = {
+      connect: Spotify::SDK::Connect,
+      me:      Spotify::SDK::Me
+    }.freeze
+
+    SDK_COMPONENTS.each_key do |component|
+      attr_reader(component)
+    end
+
+    private
+
+    ##
+    # This is where we map the SDK component classes to the SDK component vairables.
+    #
+    def mount_sdk_components # :nodoc:
+      SDK_COMPONENTS.map do |key, klass|
+        instance_variable_set "@#{key}".to_sym, klass.new(self)
+      end
+    end
+  end
+end

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