nexus_mods 0.1.0

data/lib/nexus_mods.rb

@@ -0,0 +1,274 @@
+require 'addressable/uri'
+require 'json'
+require 'time'
+require 'tmpdir'
+require 'faraday'
+require 'nexus_mods/api_limits'
+require 'nexus_mods/category'
+require 'nexus_mods/game'
+require 'nexus_mods/user'
+require 'nexus_mods/mod'
+require 'nexus_mods/mod_file'
+
+# Ruby API to access NexusMods REST API
+class NexusMods
+
+  # Error raised by the API calls
+  class ApiError < RuntimeError
+  end
+
+  # Error raised when the API calls have exceed their usage limits
+  class LimitsExceededError < ApiError
+  end
+
+  # Error raised when the API key is invalid
+  class InvalidApiKeyError < ApiError
+  end
+
+  # The default game domain name to be queried
+  #   String
+  attr_accessor :game_domain_name
+
+  # The default mod id to be queried
+  #   Integer
+  attr_accessor :mod_id
+
+  # Constructor
+  #
+  # Parameters::
+  # * *api_key* (String or nil): The API key to be used, or nil for another authentication [default: nil]
+  # * *game_domain_name* (String): Game domain name to query by default [default: 'skyrimspecialedition']
+  # * *mod_id* (Integer): Mod to query by default [default: 1]
+  # * *file_id* (Integer): File to query by default [default: 1]
+  # * *logger* (Logger): The logger to be used for log messages [default: Logger.new(STDOUT)]
+  def initialize(
+    api_key: nil,
+    game_domain_name: 'skyrimspecialedition',
+    mod_id: 1,
+    file_id: 1,
+    logger: Logger.new($stdout)
+  )
+    @api_key = api_key
+    @game_domain_name = game_domain_name
+    @mod_id = mod_id
+    @file_id = file_id
+    @logger = logger
+    @premium = false
+    # Initialize our HTTP client
+    @http_client = Faraday.new do |builder|
+      builder.adapter Faraday.default_adapter
+    end
+    # Check that the key is correct and know if the user is premium
+    begin
+      @premium = api('users/validate')['is_premium?']
+    rescue LimitsExceededError
+      raise
+    rescue ApiError
+      raise InvalidApiKeyError, 'Invalid API key'
+    end
+  end
+
+  # Get limits of API calls.
+  # This call does not count in the limits.
+  #
+  # Result::
+  # * ApiLimits: API calls limits
+  def api_limits
+    api_limits_headers = http('users/validate').headers
+    ApiLimits.new(
+      daily_limit: Integer(api_limits_headers['x-rl-daily-limit']),
+      daily_remaining: Integer(api_limits_headers['x-rl-daily-remaining']),
+      daily_reset: Time.parse(api_limits_headers['x-rl-daily-reset']).utc,
+      hourly_limit: Integer(api_limits_headers['x-rl-hourly-limit']),
+      hourly_remaining: Integer(api_limits_headers['x-rl-hourly-remaining']),
+      hourly_reset: Time.parse(api_limits_headers['x-rl-hourly-reset']).utc
+    )
+  end
+
+  # Get the list of games
+  #
+  # Result::
+  # * Array<Game>: List of games
+  def games
+    api('games').map do |game_json|
+      # First create categories tree
+      # Hash<Integer, [Category, Integer]>: Category and its parent category id, per category id
+      categories = game_json['categories'].to_h do |category_json|
+        category_id = category_json['category_id']
+        [
+          category_id,
+          [
+            Category.new(
+              id: category_id,
+              name: category_json['name']
+            ),
+            category_json['parent_category']
+          ]
+        ]
+      end
+      categories.each_value do |(category, parent_category_id)|
+        category.parent_category = categories[parent_category_id].first if parent_category_id
+      end
+      Game.new(
+        id: game_json['id'],
+        name: game_json['name'],
+        forum_url: game_json['forum_url'],
+        nexusmods_url: game_json['nexusmods_url'],
+        genre: game_json['genre'],
+        domain_name: game_json['domain_name'],
+        approved_date: Time.at(game_json['approved_date']),
+        files_count: game_json['file_count'],
+        files_views: game_json['file_views'],
+        files_endorsements: game_json['file_endorsements'],
+        downloads_count: game_json['downloads'],
+        authors_count: game_json['authors'],
+        mods_count: game_json['mods'],
+        categories: categories.values.map { |(category, _parent_category_id)| category }
+      )
+    end
+  end
+
+  # Get information about a mod
+  #
+  # Parameters::
+  # * *game_domain_name* (String): Game domain name to query by default [default: @game_domain_name]
+  # * *mod_id* (Integer): The mod ID [default: @mod_id]
+  # Result::
+  # * Mod: Mod information
+  def mod(game_domain_name: @game_domain_name, mod_id: @mod_id)
+    mod_json = api "games/#{game_domain_name}/mods/#{mod_id}"
+    Mod.new(
+      uid: mod_json['uid'],
+      mod_id: mod_json['mod_id'],
+      game_id: mod_json['game_id'],
+      allow_rating: mod_json['allow_rating'],
+      domain_name: mod_json['domain_name'],
+      category_id: mod_json['category_id'],
+      version: mod_json['version'],
+      created_time: Time.parse(mod_json['created_time']),
+      updated_time: Time.parse(mod_json['updated_time']),
+      author: mod_json['author'],
+      contains_adult_content: mod_json['contains_adult_content'],
+      status: mod_json['status'],
+      available: mod_json['available'],
+      uploader: User.new(
+        member_id: mod_json['user']['member_id'],
+        member_group_id: mod_json['user']['member_group_id'],
+        name: mod_json['user']['name'],
+        profile_url: mod_json['uploaded_users_profile_url']
+      ),
+      name: mod_json['name'],
+      summary: mod_json['summary'],
+      description: mod_json['description'],
+      picture_url: mod_json['picture_url'],
+      downloads_count: mod_json['mod_downloads'],
+      unique_downloads_count: mod_json['mod_unique_downloads'],
+      endorsements_count: mod_json['endorsement_count']
+    )
+  end
+
+  # Enum of file categories from the API
+  FILE_CATEGORIES = {
+    1 => :main,
+    2 => :patch,
+    3 => :optional,
+    4 => :old,
+    6 => :deleted
+  }
+
+  # Get files belonging to a mod
+  #
+  # Parameters::
+  # * *game_domain_name* (String): Game domain name to query by default [default: @game_domain_name]
+  # * *mod_id* (Integer): The mod ID [default: @mod_id]
+  # Result::
+  # * Array<ModFile>: List of mod's files
+  def mod_files(game_domain_name: @game_domain_name, mod_id: @mod_id)
+    api("games/#{game_domain_name}/mods/#{mod_id}/files")['files'].map do |file_json|
+      category_id = FILE_CATEGORIES[file_json['category_id']]
+      raise "Unknown file category: #{file_json['category_id']}" if category_id.nil?
+
+      ModFile.new(
+        ids: file_json['id'],
+        uid: file_json['uid'],
+        id: file_json['file_id'],
+        name: file_json['name'],
+        version: file_json['version'],
+        category_id:,
+        category_name: file_json['category_name'],
+        is_primary: file_json['is_primary'],
+        size: file_json['size_in_bytes'],
+        file_name: file_json['file_name'],
+        uploaded_time: Time.parse(file_json['uploaded_time']),
+        mod_version: file_json['mod_version'],
+        external_virus_scan_url: file_json['external_virus_scan_url'],
+        description: file_json['description'],
+        changelog_html: file_json['changelog_html'],
+        content_preview_url: file_json['content_preview_link']
+      )
+    end
+  end
+
+  private
+
+  # Send an HTTP request to the API and get back the answer as a JSON
+  #
+  # Parameters::
+  # * *path* (String): API path to contact (from v1/ and without .json)
+  # * *verb* (Symbol): Verb to be used (:get, :post...) [default: :get]
+  # Result::
+  # * Object: The JSON response
+  def api(path, verb: :get)
+    res = http(path, verb:)
+    json = JSON.parse(res.body)
+    uri = api_uri(path)
+    @logger.debug "[API call] - #{verb} #{uri} => #{res.status}\n#{
+        JSON.
+          pretty_generate(json).
+          split("\n").
+          map { |line| "  #{line}" }.
+          join("\n")
+      }\n#{
+        res.
+          headers.
+          map { |header, value| "  #{header}: #{value}" }.
+          join("\n")
+      }"
+    case res.status
+    when 200
+      # Happy
+    when 429
+      # Some limits of the API have been reached
+      raise LimitsExceededError, "Exceeding limits of API calls: #{res.headers.select { |header, _value| header =~ /^x-rl-.+$/ }}"
+    else
+      raise ApiError, "API #{uri} returned error code #{res.status}" unless res.status == '200'
+    end
+    json
+  end
+
+  # Send an HTTP request to the API and get back the HTTP response
+  #
+  # Parameters::
+  # * *path* (String): API path to contact (from v1/ and without .json)
+  # * *verb* (Symbol): Verb to be used (:get, :post...) [default: :get]
+  # Result::
+  # * Faraday::Response: The HTTP response
+  def http(path, verb: :get)
+    @http_client.send(verb) do |req|
+      req.url api_uri(path)
+      req.headers['apikey'] = @api_key
+      req.headers['User-Agent'] = "nexus_mods (#{RUBY_PLATFORM}) Ruby/#{RUBY_VERSION}"
+    end
+  end
+
+  # Get the real URI to query for a given API path
+  #
+  # Parameters::
+  # * *path* (String): API path to contact (from v1/ and without .json)
+  # Result::
+  # * String: The URI
+  def api_uri(path)
+    "https://api.nexusmods.com/v1/#{path}.json"
+  end
+
+end

data/spec/nexus_mods_test/helpers.rb

@@ -0,0 +1,140 @@
+require 'digest'
+require 'webmock/rspec'
+require 'rspec/support/object_formatter'
+require 'nexus_mods'
+
+module NexusModsTests
+
+  module Helpers
+
+    # Integer: Mocked user ID
+    MOCKED_USER_ID = 1_234_567
+
+    # String: Mocked API key
+    MOCKED_API_KEY = '1234567891234566546543123546879s8df46s5df4sd5f4sd6f87wer9f846sf54sd65v16x5v48r796rwe84f654f35sd1v5df6v54687rUGZWcG0rdz09--62dcd41bb308d2d660548a3cd1ef4094162c4379'
+
+    # String: Mocked user name
+    MOCKED_USER_NAME = 'NexusModsUser'
+
+    # String: Mocked user email
+    MOCKED_USER_EMAIL = 'nexus_mods_user@test_mail.com'
+
+    # Hash<String, String>: Default HTTP headers returned by the HTTP responses
+    DEFAULT_API_HEADERS = {
+      'date' => 'Wed, 02 Oct 2019 15:08:43 GMT',
+      'content-type' => 'application/json; charset=utf-8',
+      'transfer-encoding' => 'chunked',
+      'connection' => 'close',
+      'set-cookie' => '__cfduid=1234561234561234561234561234561234560028923; expires=Thu, 01-Oct-20 15:08:43 GMT; path=/; domain=.nexusmods.com; HttpOnly; Secure',
+      'vary' => 'Accept-Encoding, Origin',
+      'userid' => MOCKED_USER_ID.to_s,
+      'x-rl-hourly-limit' => '100',
+      'x-rl-hourly-remaining' => '100',
+      'x-rl-hourly-reset' => '2019-10-02T16:00:00+00:00',
+      'x-rl-daily-limit' => '2500',
+      'x-rl-daily-remaining' => '2500',
+      'x-rl-daily-reset' => '2019-10-03 00:00:00 +0000',
+      'cache-control' => 'max-age=0, private, must-revalidate',
+      'x-request-id' => '1234561234561234561daf88a8134abc',
+      'x-runtime' => '0.022357',
+      'strict-transport-security' => 'max-age=15724800; includeSubDomains',
+      'expect-ct' => 'max-age=604800, report-uri="https://report-uri.cloudflare.com/cdn-cgi/beacon/expect-ct"',
+      'server' => 'cloudflare',
+      'cf-ray' => '1234561234561234-MAD'
+    }
+
+    # Return the NexusMods instance to be tested.
+    # Handle the API key.
+    # Cache it for the scope of a test case.
+    #
+    # Parameters::
+    # * *args* (Hash): List of named arguments to give the constructor for the first time usage
+    def nexus_mods(**args)
+      if @nexus_mods.nil?
+        args[:api_key] = MOCKED_API_KEY unless args.key?(:api_key)
+        # Redirect any log into a string so that they don't pollute the tests output and they could be asserted.
+        nexus_mods_logger = StringIO.new
+        args[:logger] = Logger.new(nexus_mods_logger)
+        @nexus_mods = NexusMods.new(**args)
+      end
+      @nexus_mods
+    end
+
+    # Expect an HTTP API call to be made, and mock the corresponding HTTP response.
+    # Handle the API key and user agent.
+    #
+    # Parameters::
+    # * *host* (String): Expected host being targeted [default: 'api.nexusmodstoto.com']
+    # * *http_method* (Symbol): Expected requested HTTP method [default: :get]
+    # * *path* (String): Expected requested path [default: '/']
+    # * *api_key* (String): Expected API key to be used in request headers [default: MOCKED_API_KEY]
+    # * *code* (Integer): Mocked return code [default: 200]
+    # * *message* (String): Mocked returned message [default: 'OK']
+    # * *json* (Object): Mocked JSON body [default: {}]
+    # * *headers* (Hash<String,String>): Mocked additional HTTP headers [default: {}]
+    def expect_http_call_to(
+      host: 'api.nexusmods.com',
+      http_method: :get,
+      path: '/',
+      api_key: MOCKED_API_KEY,
+      code: 200,
+      message: 'OK',
+      json: {},
+      headers: {}
+    )
+      json_as_str = json.to_json
+      mocked_etag = "W/\"#{Digest::MD5.hexdigest("#{path}|#{json_as_str}")}\""
+      expected_request_headers = {
+        'User-Agent' => "nexus_mods (#{RUBY_PLATFORM}) Ruby/#{RUBY_VERSION}",
+        'apikey' => api_key
+      }
+      if @expected_returned_etags.include? mocked_etag
+        expected_request_headers['If-None-Match'] = mocked_etag
+      else
+        @expected_returned_etags << mocked_etag
+      end
+      stub_request(http_method, "https://#{host}#{path}").with(headers: expected_request_headers).to_return(
+        status: [code, message],
+        body: json_as_str,
+        headers: DEFAULT_API_HEADERS.
+          merge(
+            'etag' => mocked_etag
+          ).
+          merge(headers)
+      )
+    end
+
+    # Expect a successfull call made to validate the user
+    def expect_validate_user
+      expect_http_call_to(
+        path: '/v1/users/validate.json',
+        json: {
+          user_id: MOCKED_USER_ID,
+          key: MOCKED_API_KEY,
+          name: MOCKED_USER_NAME,
+          email: MOCKED_USER_EMAIL,
+          is_premium?: false,
+          is_supporter?: false,
+          profile_url: 'https://www.nexusmods.com/Contents/Images/noavatar.gif',
+          is_supporter: false,
+          is_premium: false
+        }
+      )
+    end
+
+  end
+
+end
+
+RSpec.configure do |config|
+  config.include NexusModsTests::Helpers
+  config.before do
+    @nexus_mods = nil
+    # Keep a list of the etags we should have returned, so that we know when queries should contain them
+    # Array<String>
+    @expected_returned_etags = []
+  end
+end
+
+# Set a bigger output length for expectation errors, as most error messages include API keys and headers which can be lengthy
+RSpec::Support::ObjectFormatter.default_instance.max_formatted_output_length = 16_384

data/spec/nexus_mods_test/scenarios/nexus_mods/api_limits_spec.rb

@@ -0,0 +1,19 @@
+describe NexusMods::ApiLimits do
+
+  context 'when testing API limits' do
+
+    it 'gets api limits' do
+      expect_validate_user
+      expect_validate_user
+      api_limits = nexus_mods.api_limits
+      expect(api_limits.daily_limit).to eq 2500
+      expect(api_limits.daily_remaining).to eq 2500
+      expect(api_limits.daily_reset).to eq Time.parse('2019-10-03 00:00:00 +0000')
+      expect(api_limits.hourly_limit).to eq 100
+      expect(api_limits.hourly_remaining).to eq 100
+      expect(api_limits.hourly_reset).to eq Time.parse('2019-10-02T16:00:00+00:00')
+    end
+
+  end
+
+end

data/spec/nexus_mods_test/scenarios/nexus_mods/game_spec.rb

@@ -0,0 +1,122 @@
+describe NexusMods::Game do
+
+  context 'when testing games' do
+
+    it 'returns the games list' do
+      expect_validate_user
+      expect_http_call_to(
+        path: '/v1/games.json',
+        json: [
+          {
+            'id' => 100,
+            'name' => 'Morrowind',
+            'forum_url' => 'https://forums.nexusmods.com/index.php?/forum/111-morrowind/',
+            'nexusmods_url' => 'http://www.nexusmods.com/morrowind',
+            'genre' => 'RPG',
+            'file_count' => 14_143,
+            'downloads' => 20_414_985,
+            'domain_name' => 'morrowind',
+            'approved_date' => 1,
+            'file_views' => 100_014_750,
+            'authors' => 2062,
+            'file_endorsements' => 719_262,
+            'mods' => 6080,
+            'categories' => [
+              {
+                'category_id' => 1,
+                'name' => 'Morrowind',
+                'parent_category' => false
+              },
+              {
+                'category_id' => 2,
+                'name' => 'Buildings',
+                'parent_category' => 1
+              }
+            ]
+          },
+          {
+            'id' => 101,
+            'name' => 'Oblivion',
+            'forum_url' => 'https://forums.nexusmods.com/index.php?/forum/131-oblivion/',
+            'nexusmods_url' => 'http://www.nexusmods.com/oblivion',
+            'genre' => 'RPG',
+            'file_count' => 52_775,
+            'downloads' => 187_758_634,
+            'domain_name' => 'oblivion',
+            'approved_date' => 1,
+            'file_views' => 880_508_188,
+            'authors' => 10_673,
+            'file_endorsements' => 4_104_067,
+            'mods' => 29_220,
+            'categories' => [
+              {
+                'category_id' => 20,
+                'name' => 'Oblivion',
+                'parent_category' => false
+              },
+              {
+                'category_id' => 22,
+                'name' => 'New structures - Buildings',
+                'parent_category' => 20
+              }
+            ]
+          }
+        ]
+      )
+      games = nexus_mods.games.sort_by(&:id)
+      expect(games.size).to eq 2
+      first_game = games.first
+      expect(first_game.id).to eq 100
+      expect(first_game.name).to eq 'Morrowind'
+      expect(first_game.forum_url).to eq 'https://forums.nexusmods.com/index.php?/forum/111-morrowind/'
+      expect(first_game.nexusmods_url).to eq 'http://www.nexusmods.com/morrowind'
+      expect(first_game.genre).to eq 'RPG'
+      expect(first_game.files_count).to eq 14_143
+      expect(first_game.downloads_count).to eq 20_414_985
+      expect(first_game.domain_name).to eq 'morrowind'
+      expect(first_game.approved_date).to eq Time.parse('1970-01-01 00:00:01 +0000')
+      expect(first_game.files_views).to eq 100_014_750
+      expect(first_game.authors_count).to eq 2062
+      expect(first_game.files_endorsements).to eq 719_262
+      expect(first_game.mods_count).to eq 6080
+      first_game_categories = first_game.categories
+      expect(first_game_categories.size).to eq 2
+      expect(first_game_categories.first.id).to eq 1
+      expect(first_game_categories.first.name).to eq 'Morrowind'
+      expect(first_game_categories.first.parent_category).to be_nil
+      expect(first_game_categories[1].id).to eq 2
+      expect(first_game_categories[1].name).to eq 'Buildings'
+      expect(first_game_categories[1].parent_category).not_to be_nil
+      expect(first_game_categories[1].parent_category.id).to eq 1
+      expect(first_game_categories[1].parent_category.name).to eq 'Morrowind'
+      expect(first_game_categories[1].parent_category.parent_category).to be_nil
+      second_game = games[1]
+      expect(second_game.id).to eq 101
+      expect(second_game.name).to eq 'Oblivion'
+      expect(second_game.forum_url).to eq 'https://forums.nexusmods.com/index.php?/forum/131-oblivion/'
+      expect(second_game.nexusmods_url).to eq 'http://www.nexusmods.com/oblivion'
+      expect(second_game.genre).to eq 'RPG'
+      expect(second_game.files_count).to eq 52_775
+      expect(second_game.downloads_count).to eq 187_758_634
+      expect(second_game.domain_name).to eq 'oblivion'
+      expect(second_game.approved_date).to eq Time.parse('1970-01-01 00:00:01 +0000')
+      expect(second_game.files_views).to eq 880_508_188
+      expect(second_game.authors_count).to eq 10_673
+      expect(second_game.files_endorsements).to eq 4_104_067
+      expect(second_game.mods_count).to eq 29_220
+      second_game_categories = second_game.categories
+      expect(second_game_categories.size).to eq 2
+      expect(second_game_categories.first.id).to eq 20
+      expect(second_game_categories.first.name).to eq 'Oblivion'
+      expect(second_game_categories.first.parent_category).to be_nil
+      expect(second_game_categories[1].id).to eq 22
+      expect(second_game_categories[1].name).to eq 'New structures - Buildings'
+      expect(second_game_categories[1].parent_category).not_to be_nil
+      expect(second_game_categories[1].parent_category.id).to eq 20
+      expect(second_game_categories[1].parent_category.name).to eq 'Oblivion'
+      expect(second_game_categories[1].parent_category.parent_category).to be_nil
+    end
+
+  end
+
+end