nexus_mods 2.0.1 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3aa5f91eb62460b72b2f0f31434cc1d3741c70970b3e4db5f22b57e95bbe6b4c
-  data.tar.gz: 31cdf30406cbed8fa23a432cc7b916ed8223c9344a3d07379adb5cff19f4bfea
+  metadata.gz: a25aa2568a5be1e1a8592196344fde1ca68bcf814b67a51cf6921f7ed64c0f70
+  data.tar.gz: cdb50c9b1394af620109ea82439a3254b96ad223286ae1f797fcbc37c32a1a58
 SHA512:
-  metadata.gz: 03a0ddca6e1d752aee0cb6ec887067340d3f31546cb6212da7c01082327fd47f898aa176f0c24175483db6657a8ff54d00bedd71411c37a00141b26e5c68b09c
-  data.tar.gz: ffd3177a8b3dcee3f1c96eeb03e5a9526c5bbcf967ae81c6d926a0f7158eeccae5b7214b4e8c0d769e98f6d5d2058135d8cab5e27436c1ae3df890378c6bca1e
+  metadata.gz: b7f49167041ee67f3855c0a474cdba90a744660f424356943516016628f1e65f37154c7c6b596eca2b7ac2430eae4b0726db6a45d3685b750bdf7a33e8674d2e
+  data.tar.gz: ce904391c82e93f029a41a47d3e7e391af8dac23625ac38eda01b2066ea9261ae3ff7bbea2aed23fbbba9b124846be80640bdbbf94ef98291b1b020824ec74df

data/CHANGELOG.md

@@ -1,3 +1,15 @@
+# [v2.2.0](https://github.com/Muriel-Salvan/nexus_mods/compare/v2.1.0...v2.2.0) (2023-04-12 12:56:31)
+
+### Features
+
+* [[Feature] Add possibility to retrieve the cache timestamp of API resources](https://github.com/Muriel-Salvan/nexus_mods/commit/ba67323a32472deb1f063a51683ff9282ef96981)
+
+# [v2.1.0](https://github.com/Muriel-Salvan/nexus_mods/compare/v2.0.1...v2.1.0) (2023-04-11 18:24:04)
+
+### Features
+
+* [[Feature] Add API entry point to retrieve last updated mods](https://github.com/Muriel-Salvan/nexus_mods/commit/cf702fc2c146cc7d61aadca005aa0e784b807c44)
+
 # [v2.0.1](https://github.com/Muriel-Salvan/nexus_mods/compare/v2.0.0...v2.0.1) (2023-04-11 10:22:54)
 
 ### Patches

data/lib/nexus_mods/api/mod_updates.rb

@@ -0,0 +1,49 @@
+class NexusMods
+
+  module Api
+
+    # A NexusMods mod updates.
+    class ModUpdates
+
+      attr_reader(
+        *%i[
+          mod_id
+          latest_file_update
+          latest_mod_activity
+        ]
+      )
+
+      # Constructor
+      #
+      # Parameters::
+      # * *mod_id* (Integer): The mod's id
+      # * *latest_file_update* (Time): The mod's latest file update
+      # * *latest_mod_activity* (Time): The mod's latest activity
+      def initialize(
+        mod_id:,
+        latest_file_update:,
+        latest_mod_activity:
+      )
+        @mod_id = mod_id
+        @latest_file_update = latest_file_update
+        @latest_mod_activity = latest_mod_activity
+      end
+
+      # Equality operator
+      #
+      # Parameters::
+      # * *other* (Object): Other object to compare with
+      # Result::
+      # * Boolean: Are objects equal?
+      def ==(other)
+        other.is_a?(ModUpdates) &&
+          @mod_id == other.mod_id &&
+          @latest_file_update == other.latest_file_update &&
+          @latest_mod_activity == other.latest_mod_activity
+      end
+
+    end
+
+  end
+
+end

data/lib/nexus_mods/api_client.rb

@@ -50,25 +50,43 @@ class NexusMods
     #
     # Parameters::
     # * *path* (String): API path to contact (from v1/ and without .json)
+    # * *parameters* (Hash<Symbol,Object>): Optional parameters to add to the path [default: {}]
     # * *verb* (Symbol): Verb to be used (:get, :post...) [default: :get]
     # * *clear_cache* (Boolean): Should we clear the API cache for this resource? [default: false]
     # Result::
     # * Object: The JSON response
-    def api(path, verb: :get, clear_cache: false)
-      clear_cached_api_cache(path, verb:) if clear_cache
-      cached_api(path, verb:)
+    def api(path, parameters: {}, verb: :get, clear_cache: false)
+      clear_cached_api_cache(path, parameters:, verb:) if clear_cache
+      cached_api(path, parameters:, verb:)
+    end
+
+    # Get the timestamp of the cached data linked to a given API call
+    #
+    # Parameters::
+    # * *path* (String): API path to contact (from v1/ and without .json)
+    # * *parameters* (Hash<Symbol,Object>): Optional parameters to add to the path [default: {}]
+    # * *verb* (Symbol): Verb to be used (:get, :post...) [default: :get]
+    # Result::
+    # * Time or nil: The refresh time of the data, or nil if not part of the cache
+    def api_cache_timestamp(path, parameters: {}, verb: :get)
+      key = ApiClient.cache_key(path, parameters:, verb:)
+      return unless Cacheable.cache_adapter.exist?(key)
+
+      str_time = Cacheable.cache_adapter.context.dig(key, 'invalidate_time')
+      str_time.nil? ? nil : Time.parse(str_time)
     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)
+    # * *parameters* (Hash<Symbol,Object>): Optional parameters to add to the path [default: {}]
     # * *verb* (Symbol): Verb to be used (:get, :post...) [default: :get]
     # Result::
     # * Faraday::Response: The HTTP response
-    def http(path, verb: :get)
+    def http(path, parameters: {}, verb: :get)
       @http_client.send(verb) do |req|
-        req.url api_uri(path)
+        req.url api_uri(path, parameters:)
         req.headers['apikey'] = @api_key
         req.headers['User-Agent'] = "nexus_mods/#{NexusMods::VERSION} (#{RUBY_PLATFORM}) Ruby/#{RUBY_VERSION}"
       end
@@ -97,6 +115,18 @@ class NexusMods
       # ApiClient: The API client to be used by the cacheable adapter (singleton pattern)
       attr_accessor :api_client
 
+      # Get the cache key to be used for a given API query
+      #
+      # Parameters::
+      # * *path* (String): API path to contact (from v1/ and without .json)
+      # * *parameters* (Hash<Symbol,Object>): Optional parameters to add to the path [default: {}]
+      # * *verb* (Symbol): Verb to be used (:get, :post...) [default: :get]
+      # Result::
+      # * String: The corresponding cache key
+      def cache_key(path, parameters:, verb:)
+        "#{verb}/#{path}#{parameters.empty? ? '' : "/#{parameters.map { |param, value| "#{param}=#{value}" }.sort.join('/')}"}"
+      end
+
     end
 
     @api_client = nil
@@ -106,11 +136,12 @@ class NexusMods
     #
     # Parameters::
     # * *path* (String): API path to contact (from v1/ and without .json)
+    # * *parameters* (Hash<Symbol,Object>): Optional parameters to add to the path [default: {}]
     # * *verb* (Symbol): Verb to be used (:get, :post...) [default: :get]
     # Result::
     # * Object: The JSON response
-    def cached_api(path, verb: :get)
-      res = http(path, verb:)
+    def cached_api(path, parameters: {}, verb: :get)
+      res = http(path, parameters:, verb:)
       json = JSON.parse(res.body)
       uri = api_uri(path)
       @logger.debug "[API call] - #{verb} #{uri} => #{res.status}\n#{
@@ -139,11 +170,12 @@ class NexusMods
     cacheable_api(
       :cached_api,
       key_format: proc do |_target, _method_name, method_args, method_kwargs|
-        "#{method_kwargs[:verb]}/#{method_args.first}"
+        cache_key(method_args.first, parameters: method_kwargs[:parameters], verb: method_kwargs[:verb])
       end,
       expiry_from_key: proc do |key|
         # Example of keys:
         # get/games
+        # get/games/skyrimspecialedition/mods/updated/period=1d
         # get/games/skyrimspecialedition/mods/2014
         # get/games/skyrimspecialedition/mods/2014/files
         # get/users/validate
@@ -155,13 +187,19 @@ class NexusMods
           else
             case key_components[2]
             when 'mods'
-              case key_components[4]
-              when nil
-                ApiClient.api_client.api_cache_expiry[:mod]
-              when 'files'
-                ApiClient.api_client.api_cache_expiry[:mod_files]
+              case key_components[3]
+              when 'updated'
+                # According to the API doc, this is updated every 5 minutes
+                5 * 60
               else
-                raise "Unknown API path: #{key}"
+                case key_components[4]
+                when nil
+                  ApiClient.api_client.api_cache_expiry[:mod]
+                when 'files'
+                  ApiClient.api_client.api_cache_expiry[:mod_files]
+                else
+                  raise "Unknown API path: #{key}"
+                end
               end
             else
               raise "Unknown API path: #{key}"
@@ -183,10 +221,11 @@ class NexusMods
     #
     # Parameters::
     # * *path* (String): API path to contact (from v1/ and without .json)
+    # * *parameters* (Hash<Symbol,Object>): Optional parameters to add to the path [default: {}]
     # Result::
     # * String: The URI
-    def api_uri(path)
-      "https://api.nexusmods.com/v1/#{path}.json"
+    def api_uri(path, parameters: {})
+      "https://api.nexusmods.com/v1/#{path}.json#{parameters.empty? ? '' : "?#{parameters.map { |param, value| "#{param}=#{value}" }.join('&')}"}"
     end
 
   end

data/lib/nexus_mods/cacheable_with_expiry.rb

@@ -45,7 +45,7 @@ class NexusMods
                     expiry_cache[key].nil? || (Time.now.utc - Time.parse(context['invalidate_time']).utc > expiry_cache[key])
                   end,
                   update_context_after_fetch: proc do |_key, _value, _options, context|
-                    context['invalidate_time'] = Time.now.utc.strftime('%FT%TUTC')
+                    context['invalidate_time'] = Time.now.utc.strftime('%FT%T.%9NUTC')
                   end
                 }
               )

data/lib/nexus_mods/core_extensions/cacheable/cache_adapters/persistent_json_adapter.rb

@@ -13,6 +13,8 @@ module Cacheable
     # * The context information is JSON serializable.
     class PersistentJsonAdapter < MemoryAdapter
 
+      attr_reader :context
+
       # Fetch a key with the givien cache options
       #
       # Parameters::
@@ -87,10 +89,6 @@ module Cacheable
         @context = loaded_content['context']
       end
 
-      private
-
-      attr_reader :context
-
     end
 
   end

data/lib/nexus_mods/version.rb

@@ -1,5 +1,5 @@
 class NexusMods
 
-  VERSION = '2.0.1'
+  VERSION = '2.2.0'
 
 end

data/lib/nexus_mods.rb

@@ -8,6 +8,7 @@ require 'nexus_mods/api/game'
 require 'nexus_mods/api/user'
 require 'nexus_mods/api/mod'
 require 'nexus_mods/api/mod_file'
+require 'nexus_mods/api/mod_updates'
 
 # Ruby API to access NexusMods REST API
 class NexusMods
@@ -130,7 +131,7 @@ class NexusMods
         nexusmods_url: game_json['nexusmods_url'],
         genre: game_json['genre'],
         domain_name: game_json['domain_name'],
-        approved_date: Time.at(game_json['approved_date']),
+        approved_date: Time.at(game_json['approved_date']).utc,
         files_count: game_json['file_count'],
         files_views: game_json['file_views'],
         files_endorsements: game_json['file_endorsements'],
@@ -142,6 +143,14 @@ class NexusMods
     end
   end
 
+  # Get the cached timestamp of the list of games
+  #
+  # Result::
+  # * Time or nil: Freshness time of the data in the API cache, or nil if not present in the cache
+  def games_cache_timestamp
+    @api_client.api_cache_timestamp('games')
+  end
+
   # Get information about a mod
   #
   # Parameters::
@@ -182,6 +191,17 @@ class NexusMods
     )
   end
 
+  # Get the cached timestamp of a mod information
+  #
+  # 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::
+  # * Time or nil: Freshness time of the data in the API cache, or nil if not present in the cache
+  def mod_cache_timestamp(game_domain_name: @game_domain_name, mod_id: @mod_id)
+    @api_client.api_cache_timestamp("games/#{game_domain_name}/mods/#{mod_id}")
+  end
+
   # Get files belonging to a mod
   #
   # Parameters::
@@ -213,4 +233,75 @@ class NexusMods
     end
   end
 
+  # Get the cached timestamp of a mod files information
+  #
+  # 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::
+  # * Time or nil: Freshness time of the data in the API cache, or nil if not present in the cache
+  def mod_files_cache_timestamp(game_domain_name: @game_domain_name, mod_id: @mod_id)
+    @api_client.api_cache_timestamp("games/#{game_domain_name}/mods/#{mod_id}/files")
+  end
+
+  # Get a list of updated mod ids since a given time
+  #
+  # Parameters::
+  # * *game_domain_name* (String): Game domain name to query by default [default: @game_domain_name]
+  # * *since* (Symbol): The time from which we look for updated mods [default: :one_day]
+  #   Possible values are:
+  #   * *one_day*: Since 1 day
+  #   * *one_week*: Since 1 week
+  #   * *one_month*: Since 1 month
+  # * *clear_cache* (Boolean): Should we clear the API cache for this resource? [default: false]
+  # Result::
+  # * Array<ModUpdates>: Mod's updates information
+  def updated_mods(game_domain_name: @game_domain_name, since: :one_day, clear_cache: false)
+    @api_client.api("games/#{game_domain_name}/mods/updated", parameters: period_to_url_params(since), clear_cache:).map do |updated_mod_json|
+      Api::ModUpdates.new(
+        mod_id: updated_mod_json['mod_id'],
+        latest_file_update: Time.at(updated_mod_json['latest_file_update']).utc,
+        latest_mod_activity: Time.at(updated_mod_json['latest_mod_activity']).utc
+      )
+    end
+  end
+
+  # Get the cached timestamp of a mod files information
+  #
+  # Parameters::
+  # * *game_domain_name* (String): Game domain name to query by default [default: @game_domain_name]
+  # * *since* (Symbol): The time from which we look for updated mods [default: :one_day]
+  #   Possible values are:
+  #   * *one_day*: Since 1 day
+  #   * *one_week*: Since 1 week
+  #   * *one_month*: Since 1 month
+  # Result::
+  # * Time or nil: Freshness time of the data in the API cache, or nil if not present in the cache
+  def updated_mods_cache_timestamp(game_domain_name: @game_domain_name, since: :one_day)
+    @api_client.api_cache_timestamp("games/#{game_domain_name}/mods/updated", parameters: period_to_url_params(since))
+  end
+
+  private
+
+  # Get the URL parameters from the required period
+  #
+  # Parameters::
+  # * *since* (Symbol): The time from which we look for updated mods
+  #   Possible values are:
+  #   * *one_day*: Since 1 day
+  #   * *one_week*: Since 1 week
+  #   * *one_month*: Since 1 month
+  # Result::
+  # * Hash<Symbol,Object>: Corresponding URL parameters
+  def period_to_url_params(since)
+    nexus_mods_period = {
+      one_day: '1d',
+      one_week: '1w',
+      one_month: '1m'
+    }[since]
+    raise "Unknown time stamp: #{since}" if nexus_mods_period.nil?
+
+    { period: nexus_mods_period }
+  end
+
 end

data/spec/nexus_mods_test/factories/games.rb

@@ -5,7 +5,7 @@ module NexusModsTest
     module Games
 
       # Test game with id 100
-      def json_game100
+      def self.json_game100
         {
           'id' => 100,
           'name' => 'Morrowind',
@@ -35,8 +35,12 @@ module NexusModsTest
         }
       end
 
+      def json_game100
+        Games.json_game100
+      end
+
       # Test game with id 101
-      def json_game101
+      def self.json_game101
         {
           'id' => 101,
           'name' => 'Oblivion',
@@ -66,6 +70,10 @@ module NexusModsTest
         }
       end
 
+      def json_game101
+        Games.json_game101
+      end
+
       # Expect a game to be the test game of id 100
       #
       # Parameters::

data/spec/nexus_mods_test/factories/mod_files.rb

@@ -5,7 +5,7 @@ module NexusModsTest
     module ModFiles
 
       # Test mod file with id 2472
-      def json_mod_file2472
+      def self.json_mod_file2472
         {
           'id' => [
             2472,
@@ -32,8 +32,12 @@ module NexusModsTest
         }
       end
 
+      def json_mod_file2472
+        ModFiles.json_mod_file2472
+      end
+
       # Test mod file with id 2487
-      def json_mod_file2487
+      def self.json_mod_file2487
         {
           'id' => [
             2487,
@@ -60,10 +64,14 @@ module NexusModsTest
         }
       end
 
+      def json_mod_file2487
+        ModFiles.json_mod_file2487
+      end
+
       # Expect a mod's file to be the example one with id 2472
       #
       # Parameters::
-      # * *mod_file* (NexusMods::Api::File): Mod file to validate
+      # * *mod_file* (NexusMods::Api::ModFile): Mod file to validate
       def expect_mod_file_to_be2472(mod_file)
         expect(mod_file.ids).to eq [2472, 1704]
         expect(mod_file.uid).to eq 7_318_624_274_856
@@ -87,7 +95,7 @@ module NexusModsTest
       # Expect a mod's file to be the example one with id 2487
       #
       # Parameters::
-      # * *mod_file* (NexusMods::Api::File): Mod file to validate
+      # * *mod_file* (NexusMods::Api::ModFile): Mod file to validate
       def expect_mod_file_to_be2487(mod_file)
         expect(mod_file.ids).to eq [2487, 1705]
         expect(mod_file.uid).to eq 7_318_624_274_857

data/spec/nexus_mods_test/factories/mod_updates.rb

@@ -0,0 +1,57 @@
+module NexusModsTest
+
+  module Factories
+
+    module ModUpdates
+
+      # Test mod updates with id 2014
+      def self.json_mod_updates2014
+        {
+          'mod_id' => 2014,
+          'latest_file_update' => 1_655_813_855,
+          'latest_mod_activity' => 1_681_169_675
+        }
+      end
+
+      def json_mod_updates2014
+        ModUpdates.json_mod_updates2014
+      end
+
+      # Test mod updates with id 100
+      def self.json_mod_updates100
+        {
+          'mod_id' => 100,
+          'latest_file_update' => 1_681_143_964,
+          'latest_mod_activity' => 1_681_143_964
+        }
+      end
+
+      def json_mod_updates100
+        ModUpdates.json_mod_updates100
+      end
+
+      # Expect a mod's updates to be the example one with id 2014
+      #
+      # Parameters::
+      # * *mod_updates* (NexusMods::Api::ModUpdates): Mod updates to validate
+      def expect_mod_file_to_be2014(mod_updates)
+        expect(mod_updates.mod_id).to eq 2014
+        expect(mod_updates.latest_file_update).to eq Time.parse('2022-06-21 12:17:35 UTC')
+        expect(mod_updates.latest_mod_activity).to eq Time.parse('2023-04-10 23:34:35 UTC')
+      end
+
+      # Expect a mod's updates to be the example one with id 100
+      #
+      # Parameters::
+      # * *mod_updates* (NexusMods::Api::ModUpdates): Mod updates to validate
+      def expect_mod_file_to_be100(mod_updates)
+        expect(mod_updates.mod_id).to eq 100
+        expect(mod_updates.latest_file_update).to eq Time.parse('2023-04-10 16:26:04 UTC')
+        expect(mod_updates.latest_mod_activity).to eq Time.parse('2023-04-10 16:26:04 UTC')
+      end
+
+    end
+
+  end
+
+end

data/spec/nexus_mods_test/factories/mods.rb

@@ -5,7 +5,7 @@ module NexusModsTest
     module Mods
 
       # Example of JSON object returned by the API for a mod information, having all possible fields
-      def json_complete_mod
+      def self.json_complete_mod
         {
           'name' => 'ApachiiSkyHair SSE',
           'summary' => 'New Female and Male Hairstyles for Humans, Elves and Orcs. Converted hair from Sims2 and Sims3.<br />Standalone version.',
@@ -44,8 +44,12 @@ module NexusModsTest
         }
       end
 
+      def json_complete_mod
+        Mods.json_complete_mod
+      end
+
       # Example of JSON object returned by the API for a mod information, having minimum fields
-      def json_partial_mod
+      def self.json_partial_mod
         {
           'mod_downloads' => 13_634_545,
           'mod_unique_downloads' => 4_052_221,
@@ -75,6 +79,10 @@ module NexusModsTest
         }
       end
 
+      def json_partial_mod
+        Mods.json_partial_mod
+      end
+
       # Expect a mod to be the example complete one
       #
       # Parameters::

data/spec/nexus_mods_test/helpers.rb

@@ -4,6 +4,7 @@ require 'rspec/support/object_formatter'
 require 'nexus_mods_test/factories/games'
 require 'nexus_mods_test/factories/mods'
 require 'nexus_mods_test/factories/mod_files'
+require 'nexus_mods_test/factories/mod_updates'
 require 'nexus_mods'
 
 module NexusModsTest
@@ -180,6 +181,7 @@ RSpec.configure do |config|
   config.include NexusModsTest::Factories::Games
   config.include NexusModsTest::Factories::Mods
   config.include NexusModsTest::Factories::ModFiles
+  config.include NexusModsTest::Factories::ModUpdates
   config.before do
     @nexus_mods = nil
     # Reload the ApiClient as it stores caches at class level

data/spec/nexus_mods_test/scenarios/nexus_mods/api/mod_updates_spec.rb

@@ -0,0 +1,91 @@
+describe NexusMods::Api::ModUpdates do
+
+  context 'when testing mod updates' do
+
+    before do
+      expect_validate_user
+    end
+
+    # Expect the given array of mod updates to be the ones of examples (for mods 100 and 2014)
+    #
+    # Parameters::
+    # * *mod_updates* (Array<NexusMods::Api::ModUpdates>): The list of mod updates to validate
+    def expect_mod_updates_to_be_example(mod_updates)
+      sorted_mod_updates = mod_updates.sort_by(&:mod_id)
+      expect_mod_file_to_be100(sorted_mod_updates.first)
+      expect_mod_file_to_be2014(sorted_mod_updates[1])
+    end
+
+    {
+      'last day' => {
+        since: :one_day,
+        expected_url_params: 'period=1d'
+      },
+      'last week' => {
+        since: :one_week,
+        expected_url_params: 'period=1w'
+      },
+      'last month' => {
+        since: :one_month,
+        expected_url_params: 'period=1m'
+      }
+    }.each do |since, since_config|
+
+      context "when testing updated months since #{since}" do
+
+        it 'returns updated mods' do
+          expect_http_call_to(
+            path: "/v1/games/skyrimspecialedition/mods/updated.json?#{since_config[:expected_url_params]}",
+            json: [
+              json_mod_updates2014,
+              json_mod_updates100
+            ]
+          )
+          expect_mod_updates_to_be_example(nexus_mods.updated_mods(game_domain_name: 'skyrimspecialedition', since: since_config[:since]))
+        end
+
+        it 'returns updated mods information for the default game' do
+          expect_http_call_to(
+            path: "/v1/games/skyrimspecialedition/mods/updated.json?#{since_config[:expected_url_params]}",
+            json: [
+              json_mod_updates2014,
+              json_mod_updates100
+            ]
+          )
+          expect_mod_updates_to_be_example(nexus_mods(game_domain_name: 'skyrimspecialedition').updated_mods(since: since_config[:since]))
+        end
+
+        it 'returns updated mods information for the default game set using accessor' do
+          expect_http_call_to(
+            path: "/v1/games/skyrimspecialedition/mods/updated.json?#{since_config[:expected_url_params]}",
+            json: [
+              json_mod_updates2014,
+              json_mod_updates100
+            ]
+          )
+          nexus_mods.game_domain_name = 'skyrimspecialedition'
+          expect_mod_updates_to_be_example(nexus_mods.updated_mods(since: since_config[:since]))
+        end
+
+        it 'compares objects for equality' do
+          expect_http_call_to(
+            path: "/v1/games/skyrimspecialedition/mods/updated.json?#{since_config[:expected_url_params]}",
+            json: [json_mod_updates2014]
+          )
+          mod_updates1 = nexus_mods.updated_mods(game_domain_name: 'skyrimspecialedition', since: since_config[:since])
+          mod_updates2 = nexus_mods.updated_mods(game_domain_name: 'skyrimspecialedition', since: since_config[:since])
+          expect(mod_updates1.object_id).not_to eq mod_updates2.object_id
+          expect(mod_updates1).to eq mod_updates2
+        end
+
+      end
+
+    end
+
+    it 'fails to fetch updated mods for an unknown period' do
+      expect { nexus_mods.updated_mods(game_domain_name: 'skyrimspecialedition', since: :unknown_since) }.to raise_error 'Unknown time stamp: unknown_since'
+    end
+
+  end
+
+end

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

@@ -10,115 +10,245 @@ describe NexusMods do
       nexus_mods.api_limits
     end
 
-    it 'caches games queries' do
-      expect_validate_user
-      expect_http_call_to(
-        path: '/v1/games.json',
-        json: [
-          json_game100,
-          json_game101
+    {
+      'games' => {
+        expected_api_path: '/v1/games.json',
+        mocked_api_json: [
+          NexusModsTest::Factories::Games.json_game100,
+          NexusModsTest::Factories::Games.json_game101
+        ],
+        query: proc { |nm| nm.games },
+        query_without_cache: proc { |nm| nm.games(clear_cache: true) },
+        get_cache_timestamp: proc { |nm| nm.games_cache_timestamp },
+        expiry_cache_param: :games
+      },
+      'mods' => {
+        expected_api_path: '/v1/games/skyrimspecialedition/mods/2014.json',
+        mocked_api_json: NexusModsTest::Factories::Mods.json_complete_mod,
+        query: proc { |nm| nm.mod(game_domain_name: 'skyrimspecialedition', mod_id: 2014) },
+        query_without_cache: proc { |nm| nm.mod(game_domain_name: 'skyrimspecialedition', mod_id: 2014, clear_cache: true) },
+        get_cache_timestamp: proc { |nm| nm.mod_cache_timestamp(game_domain_name: 'skyrimspecialedition', mod_id: 2014) },
+        expiry_cache_param: :mod
+      },
+      'mod files' => {
+        expected_api_path: '/v1/games/skyrimspecialedition/mods/2014/files.json',
+        mocked_api_json: {
+          files: [
+            NexusModsTest::Factories::ModFiles.json_mod_file2472,
+            NexusModsTest::Factories::ModFiles.json_mod_file2487
+          ]
+        },
+        query: proc { |nm| nm.mod_files(game_domain_name: 'skyrimspecialedition', mod_id: 2014) },
+        query_without_cache: proc { |nm| nm.mod_files(game_domain_name: 'skyrimspecialedition', mod_id: 2014, clear_cache: true) },
+        get_cache_timestamp: proc { |nm| nm.mod_files_cache_timestamp(game_domain_name: 'skyrimspecialedition', mod_id: 2014) },
+        expiry_cache_param: :mod_files
+      }
+    }.merge(
+      {
+        'last day' => {
+          since: :one_day,
+          expected_url_params: 'period=1d'
+        },
+        'last week' => {
+          since: :one_week,
+          expected_url_params: 'period=1w'
+        },
+        'last month' => {
+          since: :one_month,
+          expected_url_params: 'period=1m'
+        }
+      }.to_h do |since, since_config|
+        [
+          "mod updates since #{since}",
+          {
+            expected_api_path: "/v1/games/skyrimspecialedition/mods/updated.json?#{since_config[:expected_url_params]}",
+            mocked_api_json: [
+              NexusModsTest::Factories::ModUpdates.json_mod_updates2014,
+              NexusModsTest::Factories::ModUpdates.json_mod_updates100
+            ],
+            query: proc { |nm| nm.updated_mods(game_domain_name: 'skyrimspecialedition', since: since_config[:since]) },
+            query_without_cache: proc { |nm| nm.updated_mods(game_domain_name: 'skyrimspecialedition', since: since_config[:since], clear_cache: true) },
+            get_cache_timestamp: proc { |nm| nm.updated_mods_cache_timestamp(game_domain_name: 'skyrimspecialedition', since: since_config[:since]) }
+          }
         ]
-      )
-      games = nexus_mods.games
-      expect(nexus_mods.games).to eq(games)
-    end
+      end
+    ).each do |resource, resource_config|
 
-    it 'does not cache games queries if asked' do
-      expect_validate_user
-      expect_http_call_to(
-        path: '/v1/games.json',
-        json: [
-          json_game100,
-          json_game101
-        ],
-        times: 2
-      )
-      games = nexus_mods.games
-      expect(nexus_mods.games(clear_cache: true)).to eq(games)
-    end
+      context "when testing #{resource}" do
 
-    it 'caches mod queries' do
-      expect_validate_user
-      expect_http_call_to(
-        path: '/v1/games/skyrimspecialedition/mods/2014.json',
-        json: json_complete_mod
-      )
-      mod = nexus_mods.mod(game_domain_name: 'skyrimspecialedition', mod_id: 2014)
-      expect(nexus_mods.mod(game_domain_name: 'skyrimspecialedition', mod_id: 2014)).to eq(mod)
-    end
+        it 'caches API queries' do
+          expect_validate_user
+          expect_http_call_to(
+            path: resource_config[:expected_api_path],
+            json: resource_config[:mocked_api_json]
+          )
+          resource = resource_config[:query].call(nexus_mods)
+          expect(resource_config[:query].call(nexus_mods)).to eq resource
+        end
 
-    it 'does not cache mod queries if asked' do
-      expect_validate_user
-      expect_http_call_to(
-        path: '/v1/games/skyrimspecialedition/mods/2014.json',
-        json: json_complete_mod,
-        times: 2
-      )
-      mod = nexus_mods.mod(game_domain_name: 'skyrimspecialedition', mod_id: 2014)
-      expect(nexus_mods.mod(game_domain_name: 'skyrimspecialedition', mod_id: 2014, clear_cache: true)).to eq(mod)
-    end
+        it 'does not cache API queries if asked' do
+          expect_validate_user
+          expect_http_call_to(
+            path: resource_config[:expected_api_path],
+            json: resource_config[:mocked_api_json],
+            times: 2
+          )
+          resource = resource_config[:query].call(nexus_mods)
+          expect(resource_config[:query_without_cache].call(nexus_mods)).to eq resource
+        end
 
-    it 'caches mod files queries' do
-      expect_validate_user
-      expect_http_call_to(
-        path: '/v1/games/skyrimspecialedition/mods/2014/files.json',
-        json: { files: [json_mod_file2472, json_mod_file2487] }
-      )
-      mod_files = nexus_mods.mod_files(game_domain_name: 'skyrimspecialedition', mod_id: 2014)
-      expect(nexus_mods.mod_files(game_domain_name: 'skyrimspecialedition', mod_id: 2014)).to eq(mod_files)
-    end
+        if resource_config[:expiry_cache_param]
 
-    it 'does not cache mod files queries if asked' do
-      expect_validate_user
-      expect_http_call_to(
-        path: '/v1/games/skyrimspecialedition/mods/2014/files.json',
-        json: { files: [json_mod_file2472, json_mod_file2487] },
-        times: 2
-      )
-      mod_files = nexus_mods.mod_files(game_domain_name: 'skyrimspecialedition', mod_id: 2014)
-      expect(nexus_mods.mod_files(game_domain_name: 'skyrimspecialedition', mod_id: 2014, clear_cache: true)).to eq(mod_files)
-    end
+          it 'expires API queries cache' do
+            expect_validate_user
+            expect_http_call_to(
+              path: resource_config[:expected_api_path],
+              json: resource_config[:mocked_api_json],
+              times: 2
+            )
+            nexus_mods_instance = nexus_mods(api_cache_expiry: { resource_config[:expiry_cache_param] => 1 })
+            resource = resource_config[:query].call(nexus_mods_instance)
+            sleep 2
+            expect(resource_config[:query].call(nexus_mods_instance)).to eq resource
+          end
 
-    it 'expires games queries cache' do
-      expect_validate_user
-      expect_http_call_to(
-        path: '/v1/games.json',
-        json: [
-          json_game100,
-          json_game101
-        ],
-        times: 2
-      )
-      nexus_mods_instance = nexus_mods(api_cache_expiry: { games: 1 })
-      games = nexus_mods_instance.games
-      sleep 2
-      expect(nexus_mods_instance.games).to eq(games)
-    end
+        end
 
-    it 'expires mod queries cache' do
-      expect_validate_user
-      expect_http_call_to(
-        path: '/v1/games/skyrimspecialedition/mods/2014.json',
-        json: json_complete_mod,
-        times: 2
-      )
-      nexus_mods_instance = nexus_mods(api_cache_expiry: { mod: 1 })
-      mod = nexus_mods_instance.mod(game_domain_name: 'skyrimspecialedition', mod_id: 2014)
-      sleep 2
-      expect(nexus_mods_instance.mod(game_domain_name: 'skyrimspecialedition', mod_id: 2014)).to eq(mod)
-    end
+        it 'stores no timestamp of the data stored in the API cache before fetching data' do
+          expect_validate_user
+          expect(resource_config[:get_cache_timestamp].call(nexus_mods)).to be_nil
+        end
+
+        it 'retrieves the timestamp of the data stored in the API cache' do
+          expect_validate_user
+          expect_http_call_to(
+            path: resource_config[:expected_api_path],
+            json: resource_config[:mocked_api_json]
+          )
+          before = Time.now
+          resource_config[:query].call(nexus_mods)
+          after = Time.now
+          expect(resource_config[:get_cache_timestamp].call(nexus_mods)).to be_between(before, after)
+        end
+
+        it 'retrieves the timestamp of the games data stored in the cache even after cache is used' do
+          expect_validate_user
+          expect_http_call_to(
+            path: resource_config[:expected_api_path],
+            json: resource_config[:mocked_api_json]
+          )
+          before = Time.now
+          resource_config[:query].call(nexus_mods)
+          after = Time.now
+          resource_config[:query].call(nexus_mods)
+          expect(resource_config[:get_cache_timestamp].call(nexus_mods)).to be_between(before, after)
+        end
+
+        it 'retrieves the timestamp of the games data stored in the cache even after cache is persisted' do
+          with_api_cache_file do |api_cache_file|
+            expect_validate_user(times: 2)
+            expect_http_call_to(
+              path: resource_config[:expected_api_path],
+              json: resource_config[:mocked_api_json]
+            )
+            before = Time.now
+            resource_config[:query].call(nexus_mods(api_cache_file:))
+            after = Time.now
+            reset_nexus_mods
+            expect(resource_config[:get_cache_timestamp].call(nexus_mods(api_cache_file:))).to be_between(before, after)
+          end
+        end
+
+        it 'updates the timestamp of the data stored in the API cache' do
+          expect_validate_user
+          expect_http_call_to(
+            path: resource_config[:expected_api_path],
+            json: resource_config[:mocked_api_json],
+            times: 2
+          )
+          resource_config[:query].call(nexus_mods)
+          sleep 1
+          before = Time.now
+          resource_config[:query_without_cache].call(nexus_mods)
+          after = Time.now
+          expect(resource_config[:get_cache_timestamp].call(nexus_mods)).to be_between(before, after)
+        end
+
+        context 'when testing cache persistence in files' do
+
+          it 'persists API cache in a file' do
+            with_api_cache_file do |api_cache_file|
+              expect_validate_user
+              expect_http_call_to(
+                path: resource_config[:expected_api_path],
+                json: resource_config[:mocked_api_json]
+              )
+              resource_config[:query].call(nexus_mods(api_cache_file:))
+              expect(File.exist?(api_cache_file)).to be true
+              expect(File.size(api_cache_file)).to be > 0
+            end
+          end
+
+          it 'uses API cache from a file' do
+            with_api_cache_file do |api_cache_file|
+              expect_validate_user(times: 2)
+              expect_http_call_to(
+                path: resource_config[:expected_api_path],
+                json: resource_config[:mocked_api_json]
+              )
+              # Generate the cache first
+              resource = resource_config[:query].call(nexus_mods(api_cache_file:))
+              # Force a new instance of NexusMods API to run
+              reset_nexus_mods
+              expect(resource_config[:query].call(nexus_mods(api_cache_file:))).to eq resource
+            end
+          end
+
+          if resource_config[:expiry_cache_param]
+
+            it 'uses API cache from a file, taking expiry time into account' do
+              with_api_cache_file do |api_cache_file|
+                expect_validate_user(times: 2)
+                expect_http_call_to(
+                  path: resource_config[:expected_api_path],
+                  json: resource_config[:mocked_api_json],
+                  times: 2
+                )
+                # Generate the cache first
+                resource = resource_config[:query].call(nexus_mods(api_cache_file:, api_cache_expiry: { resource_config[:expiry_cache_param] => 1 }))
+                # Force a new instance of NexusMods API to run
+                reset_nexus_mods
+                sleep 2
+                # As the expiry time is 1 second, then the cache should still be invalidated
+                expect(resource_config[:query].call(nexus_mods(api_cache_file:, api_cache_expiry: { resource_config[:expiry_cache_param] => 1 }))).to eq resource
+              end
+            end
+
+            it 'uses API cache from a file, taking expiry time of the new process into account' do
+              with_api_cache_file do |api_cache_file|
+                expect_validate_user(times: 2)
+                expect_http_call_to(
+                  path: resource_config[:expected_api_path],
+                  json: resource_config[:mocked_api_json],
+                  times: 2
+                )
+                # Generate the cache first
+                resource = resource_config[:query].call(nexus_mods(api_cache_file:, api_cache_expiry: { resource_config[:expiry_cache_param] => 10 }))
+                # Force a new instance of NexusMods API to run
+                reset_nexus_mods
+                sleep 2
+                # Even if the expiry time was 10 seconds while fetching the resource,
+                # if we decide it has to be 1 second now then it has to be invalidated.
+                expect(resource_config[:query].call(nexus_mods(api_cache_file:, api_cache_expiry: { resource_config[:expiry_cache_param] => 1 }))).to eq resource
+              end
+            end
+
+          end
+
+        end
+
+      end
 
-    it 'expires mod files queries cache' do
-      expect_validate_user
-      expect_http_call_to(
-        path: '/v1/games/skyrimspecialedition/mods/2014/files.json',
-        json: { files: [json_mod_file2472, json_mod_file2487] },
-        times: 2
-      )
-      nexus_mods_instance = nexus_mods(api_cache_expiry: { mod_files: 1 })
-      mod_files = nexus_mods_instance.mod_files(game_domain_name: 'skyrimspecialedition', mod_id: 2014)
-      sleep 2
-      expect(nexus_mods_instance.mod_files(game_domain_name: 'skyrimspecialedition', mod_id: 2014)).to eq(mod_files)
     end
 
     it 'only clears the cache of the wanted resource' do
@@ -136,89 +266,12 @@ describe NexusMods do
       mod_files20151 = nexus_mods.mod_files(game_domain_name: 'skyrimspecialedition', mod_id: 2015)
       mod_files20142 = nexus_mods.mod_files(game_domain_name: 'skyrimspecialedition', mod_id: 2014, clear_cache: true)
       mod_files20152 = nexus_mods.mod_files(game_domain_name: 'skyrimspecialedition', mod_id: 2015)
-      expect(mod_files20141).to eq(mod_files20142)
-      expect(mod_files20151).to eq(mod_files20152)
+      expect(mod_files20141).to eq mod_files20142
+      expect(mod_files20151).to eq mod_files20152
     end
 
     context 'with file persistence' do
 
-      it 'persists API cache in a file' do
-        with_api_cache_file do |api_cache_file|
-          expect_validate_user
-          expect_http_call_to(
-            path: '/v1/games.json',
-            json: [
-              json_game100,
-              json_game101
-            ]
-          )
-          nexus_mods(api_cache_file:).games
-          expect(File.exist?(api_cache_file)).to be true
-          expect(File.size(api_cache_file)).to be > 0
-        end
-      end
-
-      it 'uses API cache from a file' do
-        with_api_cache_file do |api_cache_file|
-          expect_validate_user(times: 2)
-          expect_http_call_to(
-            path: '/v1/games.json',
-            json: [
-              json_game100,
-              json_game101
-            ]
-          )
-          # Generate the cache first
-          games = nexus_mods(api_cache_file:).games
-          # Force a new instance of NexusMods API to run
-          reset_nexus_mods
-          expect(nexus_mods(api_cache_file:).games).to eq games
-        end
-      end
-
-      it 'uses API cache from a file, taking expiry time into account' do
-        with_api_cache_file do |api_cache_file|
-          expect_validate_user(times: 2)
-          expect_http_call_to(
-            path: '/v1/games.json',
-            json: [
-              json_game100,
-              json_game101
-            ],
-            times: 2
-          )
-          # Generate the cache first
-          games = nexus_mods(api_cache_file:, api_cache_expiry: { games: 1 }).games
-          # Force a new instance of NexusMods API to run
-          reset_nexus_mods
-          sleep 2
-          # As the expiry time is 1 second, then the cache should still be invalidated
-          expect(nexus_mods(api_cache_file:, api_cache_expiry: { games: 1 }).games).to eq games
-        end
-      end
-
-      it 'uses API cache from a file, taking expiry time of the new process into account' do
-        with_api_cache_file do |api_cache_file|
-          expect_validate_user(times: 2)
-          expect_http_call_to(
-            path: '/v1/games.json',
-            json: [
-              json_game100,
-              json_game101
-            ],
-            times: 2
-          )
-          # Generate the cache first
-          games = nexus_mods(api_cache_file:, api_cache_expiry: { games: 10 }).games
-          # Force a new instance of NexusMods API to run
-          reset_nexus_mods
-          sleep 2
-          # Even if the expiry time was 10 seconds while fetching the resource,
-          # if we decide it has to be 1 second now then it has to be invalidated.
-          expect(nexus_mods(api_cache_file:, api_cache_expiry: { games: 1 }).games).to eq games
-        end
-      end
-
       it 'completes the API cache from a file' do
         with_api_cache_file do |api_cache_file|
           expect_validate_user(times: 3)
@@ -276,10 +329,10 @@ describe NexusMods do
           nexus_mods_instance3 = nexus_mods(api_cache_file:)
           mod_files20143 = nexus_mods_instance3.mod_files(game_domain_name: 'skyrimspecialedition', mod_id: 2014)
           mod_files20153 = nexus_mods_instance3.mod_files(game_domain_name: 'skyrimspecialedition', mod_id: 2015)
-          expect(mod_files20141).to eq(mod_files20142)
-          expect(mod_files20141).to eq(mod_files20143)
-          expect(mod_files20151).to eq(mod_files20152)
-          expect(mod_files20151).to eq(mod_files20153)
+          expect(mod_files20141).to eq mod_files20142
+          expect(mod_files20141).to eq mod_files20143
+          expect(mod_files20151).to eq mod_files20152
+          expect(mod_files20151).to eq mod_files20153
         end
       end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: nexus_mods
 version: !ruby/object:Gem::Version
-  version: 2.0.1
+  version: 2.2.0
 platform: ruby
 authors:
 - Muriel Salvan
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-04-11 00:00:00.000000000 Z
+date: 2023-04-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -137,6 +137,7 @@ files:
 - lib/nexus_mods/api/game.rb
 - lib/nexus_mods/api/mod.rb
 - lib/nexus_mods/api/mod_file.rb
+- lib/nexus_mods/api/mod_updates.rb
 - lib/nexus_mods/api/user.rb
 - lib/nexus_mods/api_client.rb
 - lib/nexus_mods/cacheable_api.rb
@@ -146,12 +147,14 @@ files:
 - lib/nexus_mods/version.rb
 - spec/nexus_mods_test/factories/games.rb
 - spec/nexus_mods_test/factories/mod_files.rb
+- spec/nexus_mods_test/factories/mod_updates.rb
 - spec/nexus_mods_test/factories/mods.rb
 - spec/nexus_mods_test/helpers.rb
 - spec/nexus_mods_test/scenarios/nexus_mods/api/api_limits_spec.rb
 - spec/nexus_mods_test/scenarios/nexus_mods/api/game_spec.rb
 - spec/nexus_mods_test/scenarios/nexus_mods/api/mod_file_spec.rb
 - spec/nexus_mods_test/scenarios/nexus_mods/api/mod_spec.rb
+- spec/nexus_mods_test/scenarios/nexus_mods/api/mod_updates_spec.rb
 - spec/nexus_mods_test/scenarios/nexus_mods/nexus_mods_access_spec.rb
 - spec/nexus_mods_test/scenarios/nexus_mods/nexus_mods_caching_spec.rb
 - spec/nexus_mods_test/scenarios/nexus_mods/nexus_mods_common_spec.rb