genius-api 0.3.0

data/README.md

@@ -0,0 +1,288 @@
+# Genius API
+
+![Alt](https://repobeats.axiom.co/api/embed/0163add5bf43300944ef69ad09cf68f1a0176bf6.svg "Project stats")
+
+Welcome to the unofficial [Genius API](https://docs.genius.com) representation. This repo reflects all of the service
+API and much more!
+
+## Documentation content
+
+1. [Overview][1]
+2. [Installation][2]
+    1. [Build from source][2.1]
+        1. [Manual installation][2.1.1]
+        2. [Automatic installation][2.1.2]
+    2. [Build via bundler][2.2]
+3. [Usage][3]
+4. [Requirements][4]
+    1. [Common usage][4.1]
+    2. [Development purposes][4.2]
+5. [Development][5]
+6. [Type checking][6]
+    1. [RBS][6.1]
+    2. [Steep][6.2]
+7. [Documentation][7]
+    1. [YARD][7.1]
+    2. [Docscribe][7.2]
+8. [Project style guide][8]
+9. [Contributing][9]
+10. [License][10]
+11. [Code of Conduct][11]
+
+## Overview
+
+As noted above, this gem fully represents Genius service API. The projects source tree is pretty simple. All of the
+resources are stored in theirs separate module, so it does code readability much cleaner.
+
+## Installation
+
+Genius API gem is quite simple to use and install. There are two options to install it — for those who is going to
+contribute into the project and for those who is going to embed gem to theirs project. See below for each step.
+
+### Build from source
+
+#### Manual installation
+
+The manual installation includes installation via command line interface. it is practically no different from what
+happens during the automatic build of the project:
+
+```shell
+git clone https://github.com/unurgunite/genius-api.git && \
+cd genius-api && \
+bundle install && \
+gem build genius-api.gemspec && \
+gem install genius-api-0.2.1.gem
+```
+
+Now everything should work fine. Just type `irb` and `require "genius/api"` to start working with the library
+
+#### Automatic installation
+
+The automatic installation is simpler but it has at least same steps as manual installation:
+
+```shell
+git clone https://github.com/unurgunite/genius-api.git && \
+cd genius-api && \
+bin/setup
+```
+
+If you see `irb` interface, then everything works fine. The main goal of automatic installation is that you do not need
+to create your own script to simplify project build and clean up the shell history. Note: you do not need to require
+projects file after the automatic installation. See `bin/setup` file for clarity of the statement
+
+### Build via bundler
+
+This documentation point is close to those who need to embed the library in their project. Just place this gem to your
+Gemfile or create it manually via `bundle init`:
+
+```ruby
+# Your Gemfile
+gem 'genius-api'
+```
+
+And then execute:
+
+```shell
+bundle install
+```
+
+Or install it yourself for non bundled projects as:
+
+```shell
+gem install genius-api
+```
+
+## Usage
+
+All docs are available at the separate page: https://unurgunite.github.io/genius-api_docs/
+
+## Requirements
+
+This section will show dependencies which are used in the project. This section splits in two other sections —
+requirements for common use and requirements for the development purposes.
+
+### Common use
+
+The `genius-api` gem requires Ruby >= 3.2 and is built on top of two other gems:
+
+| Dependencies    | Description                                                                                 |
+|-----------------|---------------------------------------------------------------------------------------------|
+| [HTTParty][101] | The HTTParty gem is used to send requests to the REST client of the https://api.genius.com/ |
+| [Nokogiri][102] | The Nokogiri gem is used to represent XML objects as Ruby structures.                       |
+
+### Development purposes
+
+For the development purposes `genius-api` gem uses:
+
+| Dependencies     | Description                                                                              |
+|------------------|------------------------------------------------------------------------------------------|
+| [RSpec][201]     | The RSpec gem is used for test which are located in a separate folder under `spec` name. |
+| [RuboCop][202]   | The RuboCop gem is used for code formatting.                                             |
+| [Rake][203]      | The Rake gem is used for building tasks as generating documentation.                     |
+| [Dotenv][204]    | The Dotenv gem is used for setting variables for test environment (`token`, for e.g.).   |
+| [Coderay][205]   | The Coderay gem is used for colorizing Rspec output.                                     |
+| [YARD][206]      | The YARD gem is used for the documentation.                                              |
+| [RBS][207]       | The RBS gem is used for Ruby type signatures.                                            |
+| [Steep][208]     | The Steep gem is used for static type checking.                                          |
+| [Docscribe][209] | The Docscribe gem is used for automated YARD documentation generation.                   |
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rspec` to run the tests.
+You can
+also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the
+version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version,
+push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Type checking
+
+This project uses RBS for type signatures and Steep for static type checking.
+
+### RBS
+
+RBS type signatures are located in `sig/` directory. To validate them:
+
+```shell
+bundle exec rbs validate
+```
+
+### Steep
+
+To run the Steep type checker:
+
+```shell
+bundle exec steep check
+```
+
+## Documentation
+
+This project uses YARD for documentation with Docscribe for automated annotation generation.
+
+### YARD
+
+To generate YARD documentation:
+
+```shell
+bundle exec yard doc -o docs
+```
+
+Generated docs will be placed in `docs/` (gitignored).
+
+### Docscribe
+
+Docscribe keeps YARD annotations in sync with the codebase. To check for missing or outdated docs:
+
+```shell
+bundle exec docscribe lib
+```
+
+To regenerate annotations using RBS type information:
+
+```shell
+bundle exec docscribe -A --rbs-collection lib
+```
+
+## Project style guide
+
+To make the code base much cleaner gem has its own style guides. They are defined in a root folder of the gem in
+a [CONTRIBUTING.md](https://github.com/unurgunite/genius-api/blob/master/CONTRIBUTING.md) file. Check it for more
+details.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/unurgunite/genius-api. This project is
+intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to
+the [code of conduct](https://github.com/unurgunite/genius-api/blob/master/CODE_OF_CONDUCT.md). To contribute you should
+fork this project and create there new branch:
+
+```shell
+git clone https://github.com/your-beautiful-username/genius-api.git && \
+git checkout -b refactor && \
+git commit -m "Affected new changes" && \
+git push origin refactor
+```
+
+And then make new pull request with additional notes of what you have done. The better the changes are scheduled, the
+faster the PR will be checked.
+
+## License
+
+The gem is available as open source under the terms of the [GPLv3 License](https://opensource.org/licenses/GPL-3.0). The
+copy of the license is stored in project under the `LICENSE.txt` file
+name: [copy of the License](https://github.com/unurgunite/genius-api/blob/master/LICENSE.txt)
+
+The documentation is available as open source under the terms of
+the [CC BY-SA 4.0 License](https://creativecommons.org/licenses/by-sa/4.0/)
+
+The other libs are available as open source under the terms of
+the [New BSD License](https://opensource.org/licenses/BSD-3-Clause)
+
+![GPLv3 logo](https://www.gnu.org/graphics/gplv3-or-later.png)
+![CC BY-SA 4.0](https://mirrors.creativecommons.org/presskit/buttons/88x31/svg/by-nc.svg)
+![BSD license logo](https://upload.wikimedia.org/wikipedia/commons/4/42/License_icon-bsd-88x31.png)
+
+[1]:https://github.com/unurgunite/genius-api#overview
+
+[2]:https://github.com/unurgunite/genius-api#installation
+
+[2.1]:https://github.com/unurgunite/genius-api#build-from-source
+
+[2.1.1]:https://github.com/unurgunite/genius-api#manual-installation
+
+[2.1.2]:https://github.com/unurgunite/genius-api#automatic-installation
+
+[2.2]:https://github.com/unurgunite/genius-api#build-via-bundler
+
+[3]:https://github.com/unurgunite/genius-api#usage
+
+[4]:https://github.com/unurgunite/genius-api#requirements
+
+[4.1]:https://github.com/unurgunite/genius-api#common-usage
+
+[4.2]:https://github.com/unurgunite/genius-api#development-purposes
+
+[5]:https://github.com/unurgunite/genius-api#development
+
+[6]:https://github.com/unurgunite/genius-api#type-checking
+
+[6.1]:https://github.com/unurgunite/genius-api#rbs
+
+[6.2]:https://github.com/unurgunite/genius-api#steep
+
+[7]:https://github.com/unurgunite/genius-api#documentation
+
+[7.1]:https://github.com/unurgunite/genius-api#yard
+
+[7.2]:https://github.com/unurgunite/genius-api#docscribe
+
+[8]:https://github.com/unurgunite/genius-api#project-style-guide
+
+[9]:https://github.com/unurgunite/genius-api#contributing
+
+[10]:https://github.com/unurgunite/genius-api#license
+
+[11]:https://github.com/unurgunite/genius-api#code-of-conduct
+
+[101]:https://rubygems.org/gems/httparty
+
+[102]:https://rubygems.org/gems/nokogiri
+
+[201]:https://rubygems.org/gems/rspec
+
+[202]:https://rubygems.org/gems/rubocop
+
+[203]:https://rubygems.org/gems/rake
+
+[204]:https://rubygems.org/gems/dotenv
+
+[205]:https://rubygems.org/gems/coderay
+
+[206]:https://rubygems.org/gems/yard
+
+[207]:https://rubygems.org/gems/rbs
+
+[208]:https://rubygems.org/gems/steep
+
+[209]:https://rubygems.org/gems/docscribe

data/SECURITY.md

@@ -0,0 +1,14 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+|---------|--------------------|
+| 0.3.x   | :white_check_mark: |
+| < 0.3.0 | :x:                |
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability, please do **not** open a public issue. Instead, send a private email to the maintainers at the address listed in the gem specification.
+
+We will acknowledge receipt within 48 hours and provide an estimated timeline for a fix.

data/Steepfile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+D = Steep::Diagnostic
+
+target :lib do
+  signature 'sig'
+  check 'lib'
+  ignore 'lib/extensions/extensions.rb'
+
+  configure_code_diagnostics do |config|
+    config[D::Ruby::NoMethod] = :information
+  end
+end

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'genius/api'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start(__FILE__)

data/bin/release

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+bash <(curl -sSL https://raw.githubusercontent.com/unurgunite/release_gem/refs/heads/master/release)

data/bin/setup

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+PROJECT_NAME='genius-api'
+if pwd | grep $PROJECT_NAME; then
+  cd "${PWD%$PROJECT_NAME*}$PROJECT_NAME"
+else
+  echo "Change your working directory to the $PROJECT_NAME dir or its relative directories. Exiting with error code 1"
+  exit 1
+fi
+
+bundle install
+
+gem build "$PROJECT_NAME".gemspec
+GEM_VERSION=$(bundle info $PROJECT_NAME | head -n 1 | sed 's/.*(\(.*\))/\1/')
+GEM_ARCHIVE="$PROJECT_NAME-$GEM_VERSION.gem"
+gem install "$GEM_ARCHIVE"
+# @todo: add params to `bin/console` script
+bin/console

data/docscribe.yml

@@ -0,0 +1,9 @@
+---
+rbs:
+  enabled: true
+  collection: true
+  collapse_generics: true
+
+filter:
+  exclude:
+    - Genius::Errors::DynamicRescue.rescue_from

data/exe/genius-api

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'genius/api'

data/genius-api.gemspec

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative 'lib/genius/api/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'genius-api'
+  spec.version       = Genius::Api::VERSION
+  spec.authors       = ['unurgunite']
+
+  spec.summary       = 'Library to work with Genius API'
+  spec.description   = 'Library to work with Genius API, written in Ruby'
+  spec.homepage      = 'https://github.com/unurgunite/genius-api'
+  spec.license       = 'GPL-3.0'
+  spec.required_ruby_version = Gem::Requirement.new('>= 3.2')
+
+  spec.metadata = {
+    'homepage_uri' => spec.homepage,
+    'source_code_uri' => 'https://github.com/unurgunite/genius-api',
+    'changelog_uri' => 'https://github.com/unurgunite/genius-api/blob/master/CHANGELOG.md',
+    'rubygems_mfa_required' => 'true'
+  }
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.post_install_message = "Thanks for installing!\nA Ruby gem for scraping with Genius API🤓"
+
+  spec.add_dependency 'httparty', '~> 0.21'
+  spec.add_dependency 'nokogiri'
+  spec.add_development_dependency 'coderay'
+  spec.add_development_dependency 'docscribe'
+  spec.add_development_dependency 'dotenv', '~> 2.7.6'
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'rbs'
+  spec.add_development_dependency 'rspec', '~> 3.4'
+  spec.add_development_dependency 'rubocop'
+  spec.add_development_dependency 'rubocop-performance'
+  spec.add_development_dependency 'rubocop-rake'
+  spec.add_development_dependency 'rubocop-rspec'
+  spec.add_development_dependency 'rubocop-sorted_methods_by_call'
+  spec.add_development_dependency 'steep'
+  spec.add_development_dependency 'yard'
+end

data/lib/extensions/deep_find.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+class Hash # :nodoc:
+  # Searches for a key in nested hashes and arrays. Returns matching values or +nil+.
+  #
+  # @param [Object] key Key to search for.
+  # @param [Boolean] uniq If +true+, deduplicates results.
+  # @return [nil, Object]
+  def deep_find(key, uniq: true)
+    result = collect_values(key)
+    result.compact!
+    result.delete_if { |i| i.is_a?(Array) && i.empty? }
+    result.uniq! if uniq
+    return nil if result.empty?
+
+    result.size == 1 ? result.first : result
+  end
+
+  private
+
+  # Recursively collects values for a key from nested hashes.
+  #
+  # @private
+  # @param [Object] key Key to search for.
+  # @return [Array]
+  def collect_values(key)
+    result = [self[key]]
+    each_value do |value|
+      values = value.is_a?(Array) ? value : [value]
+      values.each do |v|
+        result << v.deep_find(key) if v.is_a?(Hash)
+      end
+    end
+    result
+  end
+end

data/lib/extensions/extensions.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# This file is an extension initializer. That means that it includes extension files
+# during initialization and extension methods are visible from everywhere
+require_relative 'deep_find'
+require_relative 'unescape'
+require_relative 'token_ext'
+require_relative 'options_helper'
+
+require 'json'
+require 'nokogiri'
+require 'httparty'

data/lib/extensions/options_helper.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: false
+
+class Object # :nodoc:
+  # +Object#options_helper+                           -> String
+  #
+  # @param [Hash] options Hash with params for response.
+  # @param [Array] arry Array of possible params for response.
+  # @return [String]
+  def options_helper(options, arry)
+    params = ''
+    opt = arry
+    options.each do |k, v|
+      params.insert(params.length, "&#{k}=#{v}") if opt.include? k
+    end
+    params
+  end
+end

data/lib/extensions/token_ext.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+class Object # :nodoc:
+  # +Object#token_ext+                                -> String
+  #
+  # Helper method to check if token is correct
+  # @param [String?] token Token to access https://api.genius.com.
+  # @return [String]
+  def token_ext(token)
+    token || Genius::Auth.instance_variable_get(:@token)
+  end
+end

data/lib/extensions/unescape.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+class String # :nodoc:
+  # +String#unescape+                                 -> String
+  #
+  # String#unescape method unescapes input JSON strings.
+  #
+  # @return [String]
+  def unescape
+    string = gsub(/(?<!\\)(\\")/, '"')
+    string.gsub(/(?<!\\)(\\\\")/, '\"')
+  end
+end

data/lib/genius/api/account.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Genius
+  # +Genius::Account+ module provides methods to work with Genius account
+  module Account
+    class << self
+      # +Genius::Account.account+                     -> value
+      #
+      # An alias to {Genius::Account.account me} method
+      #
+      # @param [String?] token Token to access https://api.genius.com.
+      # @raise [TokenError] if +token+ or +Genius::Auth.token+ are invalid.
+      # @return [Hash, nil] if TokenError exception raised.
+      # This method is a standard Genius API {request}[https://docs.genius.com/#search-h2] to get
+      # account info. Output +JSON+ is translated to Hash structure to make it easy to work with account fields.
+      #
+      # @example
+      #     Genius::Auth.login="yuiaYqbncErCVwItjQxFspNWUZLhGpXrPbkvgbgHSEKJRAlToamzMfdOeDB"
+      #     Genius::Account.account #=> {"meta"=>{"status"=>200}, "response"=>{"user"=>{...}}}
+      # @todo somehow refactor 50/52 exceptions
+      def account(token: nil)
+        return if token.nil? && !Auth.authorized?.nil?
+
+        Errors.validate_token(token) unless token.nil?
+
+        response = HTTParty.get("https://api.genius.com/account?access_token=#{token_ext(token)}").body
+        JSON.parse(response)
+      end
+
+      alias me account
+
+      Genius::Errors::DynamicRescue.rescue(Module.nesting[1])
+    end
+  end
+end

data/lib/genius/api/annotations.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Genius
+  # An annotation is a piece of content about a part of a document. The document may be a song (hosted on Genius) or a
+  # web page (hosted anywhere). The part of a document that an annotation is attached to is called a referent.
+  module Annotations
+    class << self
+      # Data for a specific annotation. Supports GET, POST, PUT, DELETE verbs with optional voting actions.
+      #
+      # @param [Integer] id ID of the annotation.
+      # @param [String?] action Action for PUT request: +nil+, +upvote+, +downvote+, or +unvote+.
+      # @param [String?] token Token to access https://api.genius.com.
+      # @param [String] http_verb HTTP verb: +get+, +post+, +put+, +delete+.
+      # @param [Hash] options Options for POST/PUT payload.
+      # @raise [ArgumentError] if +action+ is set for non-PUT request.
+      # @return [Hash, nil]
+      def annotations(id:, action:, token:, http_verb: 'get', options: {})
+        return if token.nil? && !Auth.authorized?.nil?
+
+        Errors.validate_token(token) unless token.nil?
+        raise ArgumentError, 'only PUT accepts `action` param' if http_verb != 'put' && !action.nil?
+
+        JSON.parse(request(id: id, action: action, token: token, http_verb: http_verb, options: options).body)
+      end
+
+      private
+
+      # Sends an HTTP request based on the verb and returns the raw response.
+      #
+      # @private
+      # @param [Integer] id ID of the annotation.
+      # @param [String?] action Action for PUT request.
+      # @param [String?] token Token to access https://api.genius.com.
+      # @param [String] http_verb HTTP verb.
+      # @param [Hash] options Options for POST/PUT payload.
+      # @raise [ArgumentError] if HTTP verb is invalid.
+      # @return [HTTParty::Response]
+      def request(id:, action:, token:, http_verb:, options:)
+        case http_verb
+        when 'get' then HTTParty.get("#{Api::RESOURCE}/annotations/#{id}?access_token=#{token_ext(token)}")
+        when 'post' then HTTParty.post("#{Api::RESOURCE}/annotations/#{id}?access_token=#{token_ext(token)}",
+                                       body: post_payload(options: options))
+        when 'put' then put_request(id: id, action: action, token: token, options: options)
+        when 'delete' then HTTParty.delete("#{Api::RESOURCE}/annotations/#{id}?access_token=#{token_ext(token)}")
+        else raise ArgumentError, 'Something bad happened...'
+        end
+      end
+
+      # Sends a PUT request with optional voting action.
+      #
+      # @private
+      # @param [Integer] id ID of the annotation.
+      # @param [String?] action Action: +nil+, +upvote+, +downvote+, or +unvote+.
+      # @param [String?] token Token to access https://api.genius.com.
+      # @param [Hash] options Options for PUT payload.
+      # @raise [ArgumentError] if +action+ is invalid.
+      # @return [HTTParty::Response]
+      def put_request(id:, action:, token:, options:)
+        case action
+        when nil then HTTParty.put("#{Api::RESOURCE}/annotations/#{id}/#{action}?access_token=#{token_ext(token)}",
+                                   body: post_payload(options: options))
+        when 'upvote', 'downvote', 'unvote' then HTTParty.put("#{Api::RESOURCE}/annotations/#{id}/#{action}?access_token=#{token_ext(token)}")
+        else
+          actions = %w[upvote downvote unvote]
+          raise ArgumentError,
+                "Invalid value for `action` param. Allowed values are: #{actions.join(', ')}"
+        end
+      end
+
+      # Builds a JSON payload for POST and PUT requests from options.
+      #
+      # @private
+      # @param [Hash] options Options containing +:markdown+, +:raw_annotatable_url+, +:fragment+, etc.
+      # @return [String]
+      def post_payload(options: {})
+        {
+          annotation: { body: { markdown: options[:markdown] } },
+          referent: {
+            raw_annotatable_url: options[:raw_annotatable_url],
+            fragment: options[:fragment],
+            context_for_display: { before_html: options[:before_html], after_html: options[:after_html] }
+          },
+          web_page: { canonical_url: options[:canonical_url], og_url: options[:og_url], title: options[:title] }
+        }.to_json
+      end
+
+      Genius::Errors::DynamicRescue.rescue(Module.nesting[1])
+    end
+  end
+end