genius-api 0.3.0

data/lib/genius/api/artists.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Genius
+  # An artist is how Genius represents the creator of one or more songs (or other documents hosted on Genius). It's
+  # usually a musician or group of musicians.
+  module Artists
+    class << self
+      # Data for a specific artist.
+      #
+      # @param [String?] token Token to access https://api.genius.com.
+      # @param [Integer?] id ID of the artist.
+      # @raise [ArgumentError] if +id+ is nil.
+      # @return [Hash, nil]
+      def artists(token: nil, id: nil)
+        Auth.authorized?(method_name: "#{Module.nesting[1].name}.#{__method__}") if token.nil?
+        Errors.validate_token(token) unless token.nil?
+        raise ArgumentError, "`id` can't be nil!" if id.nil?
+
+        response = HTTParty.get("#{Api::RESOURCE}/artists/#{id}?access_token=#{token_ext(token)}").body
+        JSON.parse(response)
+      end
+
+      # Songs for the artist specified. By default 20 items per request.
+      #
+      # @param [String?] token Token to access https://api.genius.com.
+      # @param [Integer?] id ID of the artist.
+      # @param [Hash] options Optional query params: +:sort+, +:per_page+, +:page+.
+      # @return [Hash, nil]
+      def artists_songs(token: nil, id: nil, options: {})
+        return if token.nil? && !Auth.authorized?.nil?
+
+        Errors.validate_token(token) unless token.nil?
+
+        sort_values = %w[title popularity]
+        validate(sort_values, sort: options[:sort], per_page: options[:per_page], page: options[:page])
+
+        params = options_helper(options, %i[sort per_page page])
+        response = HTTParty.get("#{Api::RESOURCE}/artists/#{id}?access_token=#{token_ext(token)}#{params}").body
+        JSON.parse(response)
+      end
+
+      private
+
+      # Validates sort, per_page, and page options for artists endpoint.
+      #
+      # @private
+      # @param [Array] sort_values Allowed sort values.
+      # @param [Object] options Options with +:sort+, +:per_page+, +:page+.
+      # @return [void]
+      def validate(sort_values, **options)
+        validate_sort(options[:sort], sort_values)
+        validate_page_per_page(options[:per_page])
+        validate_page_per_page(options[:page])
+      end
+
+      # Validates the sort option against allowed values.
+      #
+      # @private
+      # @param [String?] sort Sort value to validate.
+      # @param [Array] sort_values Allowed sort values.
+      # @raise [ArgumentError] if +sort+ is not in +sort_values+.
+      # @return [void]
+      def validate_sort(sort, sort_values)
+        return unless sort && !sort_values.include?(sort)
+
+        raise ArgumentError, "`sort` can't be #{sort}. Possible values: #{sort_values.join(', ')}."
+      end
+
+      # Validates that per_page or page is not negative.
+      #
+      # @private
+      # @param [Integer?] page_per_page Value to validate.
+      # @raise [ArgumentError] if value is negative.
+      # @return [void]
+      def validate_page_per_page(page_per_page)
+        raise ArgumentError, "`per_page` or `page` can't be negative." if page_per_page&.negative?
+      end
+
+      Genius::Errors::DynamicRescue.rescue(Module.nesting[1])
+    end
+  end
+end

data/lib/genius/api/authorization.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Genius
+  # +Genius::Auth+ module is used to authenticate users with their token. It
+  # provides initialization of token instance variable.
+  #
+  # @example
+  #     Genius::Auth.login="yuiaYqbncErCVwItjQxFspNWUZLhGpXrPbkvgbgHSEKJRAlToamzMfdOeDB"
+  module Auth
+    class << self
+      # Sets the authentication token after validation.
+      #
+      # @param [String] token Token to access https://api.genius.com.
+      # @raise [Genius::Errors::TokenError] if +token+ is invalid.
+      # @return [String]
+      def token=(token)
+        Genius::Errors.validate_token(token)
+        @token = token
+      end
+
+      # Checks if the current token is authorized. Returns +false+ on validation failure.
+      #
+      # @param [String] token Token to validate.
+      # @param [String] method_name Method name for error messages.
+      # @raise [Genius::Errors::TokenError]
+      # @return [Boolean]
+      def authorized?(token = @token, method_name: "#{Module.nesting[1].name}.#{__method__}")
+        Errors.validate_token(token, method_name: method_name)
+      rescue Genius::Errors::TokenError
+        false
+      else
+        true
+      end
+
+      # Revokes the current session by setting the token to +nil+.
+      #
+      # @return [nil]
+      def logout!
+        @token = nil unless @token.nil?
+      end
+
+      alias login= token=
+
+      Genius::Errors::DynamicRescue.rescue(Module.nesting[1])
+    end
+  end
+end

data/lib/genius/api/errors.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+module Genius
+  # +Genius::Errors+ module includes custom exception classes and methods to
+  # handle all errors during requests to https://api.genius.com or during
+  # the work with library methods.
+  #
+  # @example
+  #     module Genius
+  #       module Foo
+  #         include Genius::Errors
+  #         class << self
+  #           def bar(params)
+  #             # body
+  #           rescue TokenError => e
+  #             puts "Error description: #{e.msg}"            #=> Invalid token!....
+  #             puts "Error description: #{e.exception_type}" #=> token_error
+  #           end
+  #         end
+  #       end
+  #     end
+  #
+  # Exception classes fields provide custom message and error types
+  # (+connection_error+, +token_error+, +auth_required+, etc.)
+  #
+  # @example
+  #     begin
+  #       raise TokenError.new(msg: "Message", error_type: "error_type")
+  #     rescue TokenError => e
+  #       puts e.message        #=> Message
+  #       puts e.exception_type #=> error_type
+  #     end
+  #
+  # There will be a standard output of each exception if there will be no
+  # params provided.
+  #
+  # @example
+  #     begin
+  #       raise TokenError
+  #     rescue TokenError => e
+  #       puts e.message        #=> Invalid token!....
+  #       puts e.exception_type #=> token_error
+  #     end
+  module Errors
+    # Endpoint for resource.
+    ENDPOINT = "#{Api::RESOURCE}/account/?access_token".freeze
+
+    # Abstract class to store all exception classes in a single object.
+    class GeniusExceptionSuperClass < StandardError
+    end
+
+    # A +TokenError+ object provides handling error during token validation.
+    # It throws error when +token+ is invalid - expired, revoked or something
+    # else. To generate new token you should go to
+    # https://genius.com/signup_or_login and login, then you need to create
+    # new client via the link below: https://genius.com/api-clients and
+    # generate new access token. Fields to create new api client can
+    # be filled in as you like - there is no restrictions and standards.
+    class TokenError < GeniusExceptionSuperClass
+      attr_reader :msg, :exception_type, :method_name
+
+      # Initializes a token validation error with optional method name hint.
+      #
+      # @param [String] msg Error message.
+      # @param [String] exception_type Error type identifier.
+      # @param [String?] method_name Optional method name for user hint.
+      # @return [void]
+      def initialize(msg: 'Invalid token. The access token provided is expired, revoked, malformed or invalid for ' \
+                          'other reasons.', exception_type: 'token_error', method_name: nil)
+        @msg = if method_name.nil?
+                 msg
+               else
+                 "#{msg} or type #{method_name}(token: \"YOUR_TOKEN\")"
+               end
+        @exception_type = exception_type
+        super(msg)
+      end
+    end
+
+    # A +LyricsNotFoundError+ object handles an exception where JSON with
+    # lyrics is not found.
+    class LyricsNotFoundError < GeniusExceptionSuperClass
+      attr_reader :msg, :exception_type
+
+      # Initializes a lyrics-not-found error.
+      #
+      # @param [String] msg Error message.
+      # @param [String] exception_type Error type identifier.
+      # @return [void]
+      def initialize(msg: 'Lyrics not found in current session. Retrying...', exception_type: 'invalid_lyrics')
+        @msg = msg
+        @exception_type = exception_type
+        super(msg)
+      end
+    end
+
+    # A +PageNotFound+ object handles an exception where response payload is
+    # invalid and Genius itself or its related service returns not found.
+    class PageNotFound < GeniusExceptionSuperClass
+      attr_reader :msg, :exception_type
+
+      # Initializes a page-not-found error.
+      #
+      # @param [String] msg Error message.
+      # @param [String] exception_type Error type identifier.
+      # @return [void]
+      def initialize(msg: 'Page not found. Try again with another response', exception_type: 'page_not_found')
+        @msg = msg
+        @exception_type = exception_type
+        super(msg)
+      end
+
+      # Checks if the HTML response indicates a page-not-found error.
+      #
+      # @param [Object] html Parsed HTML document.
+      # @return [Boolean]
+      def self.page_not_found?(html)
+        html.text.include?('Page not found')
+      end
+    end
+
+    # +Genius::Errors::DynamicRescue+ module is used to call dynamically
+    # exceptions to each method in module or class, defined in
+    # +Genius::Errors+ scope.
+    module DynamicRescue
+      class << self
+        # Wraps singleton methods of +klass+ with exception handling via {DynamicRescue.rescue_from}.
+        #
+        # @param [Module] klass Module whose singleton methods to wrap.
+        # @return [Array]
+        def rescue(klass)
+          DynamicRescue.rescue_from klass.singleton_methods, klass, GeniusExceptionSuperClass do |e|
+            puts "Error description: #{e.msg}\nException type: #{e.exception_type}"
+            # @todo make raise ExceptionKlass
+          end
+        end
+
+        # Redefines each method in +meths+ on +klass+ to rescue +exception+ and yield to the block.
+        #
+        # @param [Array] meths Method names to wrap.
+        # @param [Module] klass Module to redefine methods on.
+        # @param [Module] exception Exception class to rescue.
+        # @raise [StandardError]
+        # @return [Array]
+        def rescue_from(meths, klass, exception, &)
+          meths.each do |meth|
+            old = klass.singleton_method(meth)
+            klass.define_singleton_method(meth) do |*args, **kwargs|
+              old.unbind.bind(klass).call(*args, **kwargs) # steep:ignore
+            rescue exception => e
+              yield(e)
+            end
+          end
+        end
+      end
+    end
+
+    class << self
+      # Validates the access token by checking length and making a test request to the API.
+      #
+      # @param [String?] token Token to validate.
+      # @param [String?] method_name Optional method name for error hints.
+      # @raise [StandardError] if +token+ is nil, wrong length, or invalid.
+      # @return [void]
+      def validate_token(token, method_name: nil)
+        raise TokenError.new(method_name: method_name) if token.nil? || token.size != 64
+
+        response = HTTParty.get("#{ENDPOINT}=#{token}").body
+        status = JSON.parse(response).dig('meta', 'status')
+        raise TokenError.new(method_name: method_name) unless status == 200
+      end
+
+      # Validates token and raises on failure. Returns +true+ if valid.
+      #
+      # @deprecated Use {.validate_token} instead.
+      # @param [String?] token Token to validate.
+      # @param [String?] method_name Optional method name for error hints.
+      # @raise [StandardError] if token is invalid.
+      # @return [Boolean]
+      def error_handle?(token, method_name: nil)
+        if token.nil?
+          raise TokenError.new(msg: 'Token is required for this method. Please, add token via ' \
+                                    "`Genius::Auth.login=``token''` method and continue",
+                               method_name: method_name)
+        elsif token.size != 64 || check_status?(token) == false
+          raise TokenError.new(method_name: method_name)
+        end
+        true
+      end
+
+      private
+
+      # Checks if the token returns a 200 status from the API.
+      #
+      # @deprecated Use {.validate_token} instead.
+      # @private
+      # @param [String] token Token to check.
+      # @raise [TokenError] if the response status is not 200.
+      # @return [Boolean]
+      def check_status?(token)
+        return false if token.size != 64 || token.nil?
+
+        response = HTTParty.get("#{ENDPOINT}=#{token}").body
+        raise TokenError unless JSON.parse(response).dig('meta', 'status')
+
+        status = JSON.parse(response).dig('meta', 'status')
+        status == 200
+      end
+    end
+  end
+end

data/lib/genius/api/referents.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Genius
+  # Referents are the sections of a piece of content to which annotations are
+  # attached. Each referent is associated with a web page or a song and may
+  # have one or more annotations. Referents can be searched by the document
+  # they are attached to or by the user that created them. When a new
+  # annotation is created either a referent is created with it or that
+  # annotation is attached to an existing referent.
+  module Referents
+    class << self
+      # Endpoint of the resource
+      ENDPOINT = "#{Api::RESOURCE}/referents".freeze
+      # Referents by content item or user. Pass only one of +:song_id+ and +:web_page+.
+      #
+      # @param [String?] token Token to access https://api.genius.com.
+      # @param [Hash] options Options: +:created_by_id+, +:text_format+, +:web_page_id+,
+      #   +:song_id+, +:per_page+, +:page+.
+      # @raise [ArgumentError] if both +:song_id+ and +:web_page+ are present.
+      # @return [Hash, nil]
+      def referents(token: nil, options: {})
+        return if token.nil? && !Auth.authorized?.nil?
+
+        Errors.validate_token(token) unless token.nil?
+        if options.key?(:web_page) && options.key?(:song_id)
+          raise ArgumentError, 'You may pass only one of song_id and web_page_id, not both!'
+        end
+
+        params = options_helper(options, %i[created_by_id text_format per_page page])
+
+        response = HTTParty.get("#{ENDPOINT}?access_token=#{token_ext(token)}#{params}").body
+        JSON.parse(response)
+      end
+
+      Genius::Errors::DynamicRescue.rescue(Module.nesting[1])
+    end
+  end
+end

data/lib/genius/api/search.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Genius
+  # +Genius::Search+ module provides methods to work with Genius search database
+  module Search
+    class << self
+      # Searches Genius for songs, artists, and other content. Optionally filters results by key using +deep_find+.
+      #
+      # @param [String?] token Token to access https://api.genius.com.
+      # @param [String?] query Search query.
+      # @param [String?] search_by Key to filter results with {Hash#deep_find}.
+      # @return [Hash, String, nil]
+      def search(token: nil, query: nil, search_by: nil)
+        return if token.nil? && !Auth.authorized?.nil?
+
+        Errors.validate_token(token) unless token.nil?
+
+        response = HTTParty.get("#{Api::RESOURCE}/search?q=#{query}&access_token=#{token_ext(token)}").body
+        search = JSON.parse(response)
+        search_by ? search.deep_find(search_by) : search
+      end
+
+      Genius::Errors::DynamicRescue.rescue(Module.nesting[1])
+    end
+  end
+end

data/lib/genius/api/songs.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Genius
+  # +Genius::Songs+ module provides methods to work with songs (lyrics/descriptions/etc.)
+  module Songs
+    class << self
+      include Genius::Errors
+
+      # Returns song data by ID. Optionally merges lyrics from the Genius page when +combine+ is +true+.
+      #
+      # @param [String?] token Token to access https://api.genius.com.
+      # @param [Integer?] song_id ID of the song.
+      # @param [Boolean] combine If +true+, fetches and merges lyrics into the response.
+      # @return [Hash, String, nil]
+      def songs(token: nil, song_id: nil, combine: false)
+        return if token.nil? && !Auth.authorized?.nil?
+
+        Errors.validate_token(token) unless token.nil?
+
+        response = HTTParty.get("#{Api::RESOURCE}/songs/#{song_id}?access_token=#{token_ext(token)}").body
+        response = JSON.parse response
+        combine && song_id ? merge_lyrics(song_id, response) : response
+      end
+
+      private
+
+      # Fetches the Genius HTML page for a song and merges lyrics into the API response.
+      #
+      # @private
+      # @param [Integer] song_id ID of the song.
+      # @param [Hash] response Original API response hash.
+      # @raise [Errors::PageNotFound] if the song page is not found.
+      # @raise [Errors::LyricsNotFoundError] if lyrics cannot be parsed.
+      # @return [Hash, String]
+      def merge_lyrics(song_id, response)
+        output_html = Nokogiri::HTML(HTTParty.get("https://genius.com/songs/#{song_id}"))
+        raise Errors::PageNotFound if Errors::PageNotFound.page_not_found?(output_html)
+
+        response['lyrics'] = parse_preloaded_state(output_html)
+        response
+      rescue Errors::LyricsNotFoundError
+        retry
+      rescue Errors::PageNotFound => e
+        "Error description: #{e.msg}\nException type: #{e.exception_type}"
+      end
+
+      # Extracts the preloaded state JSON from the Genius page HTML.
+      #
+      # @private
+      # @param [Object] output_html Parsed Nokogiri HTML document.
+      # @raise [Errors::LyricsNotFoundError] if the preloaded state script is not found.
+      # @return [Hash]
+      def parse_preloaded_state(output_html)
+        unformed_json = output_html.css('script')[17]
+                                   .text.match(/window\.__PRELOADED_STATE__\s=\sJSON.parse\('(?<json>(?:.+?))'\);/)
+        raise Errors::LyricsNotFoundError if unformed_json.nil?
+
+        JSON.parse(unformed_json[:json].unescape)
+      end
+
+      public
+
+      # Extracts lyrics as plain text from the Genius song page.
+      #
+      # @param [Integer] song_id ID of the song.
+      # @raise [ArgumentError] if +song_id+ is nil.
+      # @raise [NoMethodError]
+      # @return [String]
+      def get_lyrics(song_id)
+        raise ArgumentError, '`song_id` should be not blank!' if song_id.nil?
+
+        response = HTTParty.get("https://genius.com/songs/#{song_id}")
+        document = Nokogiri::HTML(response)
+        # @todo: something wrong with lyrics attribute value
+        lyrics_path = document.xpath("//*[@class='Lyrics__Container-sc-1ynbvzw-6 YYrds']")
+        lyrics_path.at_css('p').content
+      rescue NoMethodError
+        retry
+      end
+
+      Genius::Errors::DynamicRescue.rescue(Module.nesting[1])
+    end
+  end
+end

data/lib/genius/api/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Genius
+  module Api
+    # Version of the gem.
+    VERSION = '0.3.0'
+  end
+end

data/lib/genius/api/web_pages.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Genius
+  # A web page is a single, publicly accessible page to which annotations may
+  # be attached. Web pages map 1-to-1 with unique, canonical URLs.
+  module WebPages
+    class << self
+      # Looks up a web page by URL variants and returns Genius metadata.
+      #
+      # @param [String?] token Token to access https://api.genius.com.
+      # @param [Hash] options URL variants: +:raw_annotatable_url+, +:canonical_url+, +:og_url+.
+      # @return [Hash, nil]
+      def lookup(token: nil, options: {})
+        return if token.nil? && !Auth.authorized?.nil?
+
+        Errors.validate_token(token) unless token.nil?
+
+        params = options_helper(options, %i[raw_annotatable_url canonical_url og_url])
+        response = HTTParty.get("#{Api::RESOURCE}/?access_token=#{token_ext(token)}#{params}").body
+        JSON.parse(response)
+      end
+
+      Genius::Errors::DynamicRescue.rescue(Module.nesting[1])
+    end
+  end
+end

data/lib/genius/api.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# Base module which contains all of other methods/classes/etc.
+module Genius
+  # +Genius::Api+ is a base module with different constants.
+  module Api
+    # +Genius::Api::RESOURCE+ constant contains reference to
+    # {Genius API}[https://api.genius.com] resource.
+    RESOURCE = 'https://api.genius.com'
+  end
+end
+
+require 'extensions/extensions'
+require_relative 'api/errors'
+require_relative 'api/version'
+require_relative 'api/authorization'
+require_relative 'api/account'
+require_relative 'api/search'
+require_relative 'api/songs'
+require_relative 'api/annotations'
+require_relative 'api/referents'
+require_relative 'api/artists'
+require_relative 'api/web_pages'