spotify-ruby 0.1.1 → 0.2.1

data/Rakefile

@@ -3,28 +3,21 @@
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 require "rubocop/rake_task"
-require "coveralls/rake/task"
-require "rdoc/task"
+require "yard"
 
 # RSpec
 # For testing the Spotify Ruby project.
 RSpec::Core::RakeTask.new(:spec)
 
-# Coveralls
-# Making sure we have complete code coverage.
-Coveralls::RakeTask.new
-task test_with_coveralls: [:spec, :features, "coveralls:push"]
-
 # Rubocop
 # Making sure our code is linted.
 RuboCop::RakeTask.new
 
-# RDoc
+# YARD
 # Making all of the code documentable.
-RDoc::Task.new do |rdoc|
-  rdoc.main = "README.md"
-  rdoc.rdoc_files.include("README.md", "lib/**/*.rb")
+YARD::Rake::YardocTask.new do |t|
+  t.files = ["lib/**/*.rb"]
 end
 
 task default: :spec
-task ci: [:spec, "coveralls:push", :rubocop]
+task ci: %i[spec rubocop]

data/lib/spotify.rb

@@ -1,13 +1,13 @@
 # frozen_string_literal: true
 
 require "httparty"
-require "oauth2"
 
 require "active_support"
 require "active_support/core_ext"
 
 require "spotify/version"
-require "spotify/auth"
+require "spotify/accounts"
+require "spotify/accounts/session"
 require "spotify/sdk"
 
 ##

data/lib/spotify/accounts.rb

@@ -0,0 +1,130 @@
+# 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"
+    #
+    # @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)
+      @client_secret = config.delete(:client_secret)
+      @redirect_uri = config.delete(: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/oauth/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,173 @@
+# 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
+        {
+          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

@@ -1,16 +1,21 @@
 # frozen_string_literal: true
 
-require "spotify/sdk/initialization"
-require "spotify/sdk/initialization/base"
-require "spotify/sdk/initialization/oauth_access_token"
-require "spotify/sdk/initialization/plain_string"
-require "spotify/sdk/initialization/query_hash"
-require "spotify/sdk/initialization/query_string"
-require "spotify/sdk/initialization/url_string"
+# 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
   ##
@@ -38,72 +43,50 @@ module Spotify
     #   @sdk = Spotify::SDK.new("https://localhost:8080/#token=...&expires_in=...")
     #   @sdk = Spotify::SDK.new("token=...&expires_in=...")
     #
-    # @param [String, Hash, OAuth2::AccessToken] obj Any supported object which contains an access token. See examples.
+    # @param [String,Hash,OAuth2::AccessToken] session Any supported object containing an access token.
     #
-    def initialize(obj)
-      @payload = Spotify::SDK::Initialization.detect(obj)
-      @access_token  = @payload[:access_token]
-      @expires_in    = @payload[:expires_in]
-      @refresh_token = @payload[:refresh_token]
-
+    def initialize(session)
+      raise "Invalid Spotify::Accounts::Session object" unless session.instance_of?(Spotify::Accounts::Session)
+      @session = session
       mount_sdk_components
     end
 
-    ##
-    # Helper method to a fully qualified OAuth2::AccessToken instance.
-    #
-    # @example
-    #   @auth = Spotify::Auth.new({
-    #     client_id: "[client id goes here]",
-    #     client_secret: "[client secret goes here]",
-    #     redirect_uri: "http://localhost"
-    #   })
-    #
-    #   @sdk = Spotify::SDK.new("access_token_here")
-    #   @sdk.oauth2_access_token(@auth) # => #<OAuth2::AccessToken:...>
-    #
-    # @param [Spotify::Auth] client An instance of Spotify::Auth. See example.
-    # @return [OAuth2::AccessToken] An fully qualified instance of OAuth2::AccessToken.
-    #
-    def oauth2_access_token(client)
-      OAuth2::AccessToken.new(client, @access_token, expires_in:    @expires_in,
-                                                     refresh_token: @refresh_token)
+    attr_reader :session
+
+    def inspect # :nodoc:
+      "#<%s:0x00%x>" % [self.class.name, (object_id << 1)]
     end
 
     ##
-    # Obtain a hash containing all of the user's authorization details.
-    #
-    # @example
-    #   @auth = Spotify::Auth.new({
-    #     client_id: "[client id goes here]",
-    #     client_secret: "[client secret goes here]",
-    #     redirect_uri: "http://localhost"
-    #   })
-    #
-    #   @sdk = Spotify::SDK.new("access_token_here")
-    #   @sdk.to_hash # => { access_token: ..., expires_in: ... }
-    #
-    # @return [Hash] Containing access_token, expires_in and refresh_token
-    #
-    def to_hash
-      @payload.with_indifferent_access.symbolize_keys
-    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
 
-    attr_reader :access_token, :expires_in, :refresh_token
-    attr_reader :connect
+    SDK_COMPONENTS.each_key do |component|
+      attr_reader(component)
+    end
 
     private
 
     ##
-    # This is where we mount all SDK components to the SDK object.
-    # When mounting a new component, you'll need to do the following:
-    # - Be sure to add a `attr_reader` for it. Developers can't access it otherwise.
-    # - Add a test for it in spec/lib/spotify/sdk_spec.rb (see how we did it for others)
-    #
-    # @return [nil]
+    # This is where we map the SDK component classes to the SDK component vairables.
     #
-    def mount_sdk_components
-      @connect = Spotify::SDK::Connect.new(self)
+    def mount_sdk_components # :nodoc:
+      SDK_COMPONENTS.map do |key, klass|
+        instance_variable_set "@#{key}".to_sym, klass.new(self)
+      end
     end
   end
 end