nexus_mods 2.2.0 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a25aa2568a5be1e1a8592196344fde1ca68bcf814b67a51cf6921f7ed64c0f70
-  data.tar.gz: cdb50c9b1394af620109ea82439a3254b96ad223286ae1f797fcbc37c32a1a58
+  metadata.gz: a55e8c7bacc06ef260c5b4e6f0ac64d3e9391e39f7d1ebb00c74c110a6eae214
+  data.tar.gz: 9647e6745975eb0c8c0fe9023a2e66936773fd9389a5d5087511e8edb3e06876
 SHA512:
-  metadata.gz: b7f49167041ee67f3855c0a474cdba90a744660f424356943516016628f1e65f37154c7c6b596eca2b7ac2430eae4b0726db6a45d3685b750bdf7a33e8674d2e
-  data.tar.gz: ce904391c82e93f029a41a47d3e7e391af8dac23625ac38eda01b2066ea9261ae3ff7bbea2aed23fbbba9b124846be80640bdbbf94ef98291b1b020824ec74df
+  metadata.gz: 29732e93998b9b8b88d66af4ebd67d37d8eaa51f8ab47b487bf0ce2aa3f81312aed8e1275e83a428e5cfa60a2330a7603a6c114f9bf8898593695b0df79603c3
+  data.tar.gz: 8b3542308bd2736695165a337cef28a2e8ea7e63bd7f67d55f74b4ec797edf556d92e4792e3ea7f83a3f7f56dd028b914bcfba8f713b96679687bb29ddac8a00

data/CHANGELOG.md

@@ -1,3 +1,15 @@
+# [v2.4.0](https://github.com/Muriel-Salvan/nexus_mods/compare/v2.3.0...v2.4.0) (2023-04-12 17:23:29)
+
+### Features
+
+* [[Feature] Add options and methods for mod and mod_files to query for updates to check data freshness](https://github.com/Muriel-Salvan/nexus_mods/commit/72a933a6ac22faae601fbdc547cc9e0ffa8908fc)
+
+# [v2.3.0](https://github.com/Muriel-Salvan/nexus_mods/compare/v2.2.0...v2.3.0) (2023-04-12 15:08:22)
+
+### Features
+
+* [[Feature] Add a way to set cache timestamps manually](https://github.com/Muriel-Salvan/nexus_mods/commit/7e5ac1d16d1d31f4aa33ebb9a748310e4572a06f)
+
 # [v2.2.0](https://github.com/Muriel-Salvan/nexus_mods/compare/v2.1.0...v2.2.0) (2023-04-12 12:56:31)
 
 ### Features

data/lib/nexus_mods/api_client.rb

@@ -76,6 +76,21 @@ class NexusMods
       str_time.nil? ? nil : Time.parse(str_time)
     end
 
+    # Set the timestamp of the cached data linked to a given API call.
+    # This should be used only to update the cache timestamp of a resource we know is still up-to-date without fetching the resource for real again.
+    #
+    # 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]
+    # * *cache_timestamp* (Time): The cache timestamp to set for this resource
+    def set_api_cache_timestamp(path, cache_timestamp:, parameters: {}, verb: :get)
+      key = ApiClient.cache_key(path, parameters:, verb:)
+      Cacheable.cache_adapter.context[key] = {} unless Cacheable.cache_adapter.context.key?(key)
+      Cacheable.cache_adapter.context[key]['invalidate_time'] = cache_timestamp.utc.strftime('%FT%T.%9NUTC')
+      save_api_cache
+    end
+
     # Send an HTTP request to the API and get back the HTTP response
     #
     # Parameters::

data/lib/nexus_mods/version.rb

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

data/lib/nexus_mods.rb

@@ -151,15 +151,28 @@ class NexusMods
     @api_client.api_cache_timestamp('games')
   end
 
+  # Set the cached timestamp of the list of games.
+  # This should be used only to update the cache timestamp of a resource we know is still up-to-date without fetching the resource for real again.
+  #
+  # Parameters::
+  # * *cache_timestamp* (Time): The cache timestamp to set for this resource
+  def set_games_cache_timestamp(cache_timestamp:)
+    @api_client.set_api_cache_timestamp('games', cache_timestamp:)
+  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]
   # * *clear_cache* (Boolean): Should we clear the API cache for this resource? [default: false]
+  # * *check_updates* (Boolean): Should we check updates?
+  #   If yes then an extra call to updated_mods may be done to check for updates before retrieving the mod information.
+  #   In case the mod was previously retrieved and may be in an old cache, then using this will optimize the calls to NexusMods API to the minimum.
   # Result::
   # * Mod: Mod information
-  def mod(game_domain_name: @game_domain_name, mod_id: @mod_id, clear_cache: false)
+  def mod(game_domain_name: @game_domain_name, mod_id: @mod_id, clear_cache: false, check_updates: false)
+    mod_cache_up_to_date?(game_domain_name:, mod_id:) if check_updates
     mod_json = @api_client.api("games/#{game_domain_name}/mods/#{mod_id}", clear_cache:)
     Api::Mod.new(
       uid: mod_json['uid'],
@@ -202,15 +215,30 @@ class NexusMods
     @api_client.api_cache_timestamp("games/#{game_domain_name}/mods/#{mod_id}")
   end
 
+  # Set the cached timestamp of a mod information.
+  # This should be used only to update the cache timestamp of a resource we know is still up-to-date without fetching the resource for real again.
+  #
+  # 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]
+  # * *cache_timestamp* (Time): The cache timestamp to set for this resource
+  def set_mod_cache_timestamp(cache_timestamp:, game_domain_name: @game_domain_name, mod_id: @mod_id)
+    @api_client.set_api_cache_timestamp("games/#{game_domain_name}/mods/#{mod_id}", cache_timestamp:)
+  end
+
   # 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]
   # * *clear_cache* (Boolean): Should we clear the API cache for this resource? [default: false]
+  # * *check_updates* (Boolean): Should we check updates?
+  #   If yes then an extra call to updated_mods may be done to check for updates before retrieving the mod information.
+  #   In case the mod files were previously retrieved and may be in an old cache, then using this will optimize the calls to NexusMods API to the minimum.
   # Result::
   # * Array<ModFile>: List of mod's files
-  def mod_files(game_domain_name: @game_domain_name, mod_id: @mod_id, clear_cache: false)
+  def mod_files(game_domain_name: @game_domain_name, mod_id: @mod_id, clear_cache: false, check_updates: false)
+    mod_files_cache_up_to_date?(game_domain_name:, mod_id:) if check_updates
     @api_client.api("games/#{game_domain_name}/mods/#{mod_id}/files", clear_cache:)['files'].map do |file_json|
       Api::ModFile.new(
         ids: file_json['id'],
@@ -244,6 +272,17 @@ class NexusMods
     @api_client.api_cache_timestamp("games/#{game_domain_name}/mods/#{mod_id}/files")
   end
 
+  # Set the cached timestamp of a mod files information.
+  # This should be used only to update the cache timestamp of a resource we know is still up-to-date without fetching the resource for real again.
+  #
+  # 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]
+  # * *cache_timestamp* (Time): The cache timestamp to set for this resource
+  def set_mod_files_cache_timestamp(cache_timestamp:, game_domain_name: @game_domain_name, mod_id: @mod_id)
+    @api_client.set_api_cache_timestamp("games/#{game_domain_name}/mods/#{mod_id}/files", cache_timestamp:)
+  end
+
   # Get a list of updated mod ids since a given time
   #
   # Parameters::
@@ -266,7 +305,7 @@ class NexusMods
     end
   end
 
-  # Get the cached timestamp of a mod files information
+  # Get the cached timestamp of updated mod ids
   #
   # Parameters::
   # * *game_domain_name* (String): Game domain name to query by default [default: @game_domain_name]
@@ -281,6 +320,95 @@ class NexusMods
     @api_client.api_cache_timestamp("games/#{game_domain_name}/mods/updated", parameters: period_to_url_params(since))
   end
 
+  # Set the cached timestamp of updated mod ids.
+  # This should be used only to update the cache timestamp of a resource we know is still up-to-date without fetching the resource for real again.
+  #
+  # 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
+  # * *cache_timestamp* (Time): The cache timestamp to set for this resource
+  def set_updated_mods_cache_timestamp(cache_timestamp:, game_domain_name: @game_domain_name, since: :one_day)
+    @api_client.set_api_cache_timestamp("games/#{game_domain_name}/mods/updated", parameters: period_to_url_params(since), cache_timestamp:)
+  end
+
+  # Does a given mod id have fresh information in our cache?
+  # This may fire queries to the updated mods API to get info from NexusMods about the latest updated mods.
+  # If we know the mod is up-to-date, then its mod information cache timestamp will be set to the time when we checked for updates if it was greater than the cache date.
+  #
+  # Here is the algorithm:
+  # If it is not in the cache, then it is not up-to-date.
+  # Otherwise, the API allows us to know if it has been updated up to 1 month in the past.
+  # Therefore if the current cache timestamp is older than 1 month, assume that it has to be updated.
+  # Otherwise query the API to know the latest updated mods since 1 month:
+  # * If the mod ID is not there, then it is up-to-date.
+  # * If the mod ID is there, then check if our cache timestamp is older than the last update timestamp from NexusMods.
+  #
+  # 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::
+  # * Boolean: Is the mod cache up-to-date?
+  def mod_cache_up_to_date?(game_domain_name: @game_domain_name, mod_id: @mod_id)
+    existing_cache_timestamp = mod_cache_timestamp(game_domain_name:, mod_id:)
+    mod_up_to_date =
+      if existing_cache_timestamp.nil? || existing_cache_timestamp < Time.now - (30 * 24 * 60 * 60)
+        # It's not in the cache
+        # or it's older than 1 month
+        false
+      else
+        found_mod_updates = updated_mods(game_domain_name:, since: :one_month).find { |mod_updates| mod_updates.mod_id == mod_id }
+        # true if it has not been updated on NexusMods since 1 month
+        # or our cache timestamp is more recent
+        found_mod_updates.nil? || found_mod_updates.latest_mod_activity < existing_cache_timestamp
+      end
+    if mod_up_to_date
+      update_time = updated_mods_cache_timestamp(game_domain_name:, since: :one_month)
+      set_mod_cache_timestamp(cache_timestamp: update_time, game_domain_name:, mod_id:) if update_time > existing_cache_timestamp
+    end
+    mod_up_to_date
+  end
+
+  # Does a given mod id have fresh files information in our cache?
+  # This may fire queries to the updated mods API to get info from NexusMods about the latest updated mods.
+  # If we know the mod is up-to-date, then its mod information cache timestamp will be set to the time when we checked for updates if it was greater than the cache date.
+  #
+  # Here is the algorithm:
+  # If it is not in the cache, then it is not up-to-date.
+  # Otherwise, the API allows us to know if it has been updated up to 1 month in the past.
+  # Therefore if the current cache timestamp is older than 1 month, assume that it has to be updated.
+  # Otherwise query the API to know the latest updated mods since 1 month:
+  # * If the mod ID is not there, then it is up-to-date.
+  # * If the mod ID is there, then check if our cache timestamp is older than the last update timestamp from NexusMods.
+  #
+  # 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::
+  # * Boolean: Is the mod cache up-to-date?
+  def mod_files_cache_up_to_date?(game_domain_name: @game_domain_name, mod_id: @mod_id)
+    existing_cache_timestamp = mod_files_cache_timestamp(game_domain_name:, mod_id:)
+    mod_up_to_date =
+      if existing_cache_timestamp.nil? || existing_cache_timestamp < Time.now - (30 * 24 * 60 * 60)
+        # It's not in the cache
+        # or it's older than 1 month
+        false
+      else
+        found_mod_updates = updated_mods(game_domain_name:, since: :one_month).find { |mod_updates| mod_updates.mod_id == mod_id }
+        # true if it has not been updated on NexusMods since 1 month
+        # or our cache timestamp is more recent
+        found_mod_updates.nil? || found_mod_updates.latest_file_update < existing_cache_timestamp
+      end
+    if mod_up_to_date
+      update_time = updated_mods_cache_timestamp(game_domain_name:, since: :one_month)
+      set_mod_files_cache_timestamp(cache_timestamp: update_time, game_domain_name:, mod_id:) if update_time > existing_cache_timestamp
+    end
+    mod_up_to_date
+  end
+
   private
 
   # Get the URL parameters from the required period

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

@@ -25,60 +25,47 @@ describe NexusMods::Api::ModFile do
       expect_mod_file_to_be2487(sorted_mod_files[1])
     end
 
-    it 'returns a mod files list' do
-      expect_http_call_to(
-        path: '/v1/games/skyrimspecialedition/mods/2014/files.json',
-        json: { files: json_example_mod_files }
-      )
-      expect_mod_files_to_be_example(nexus_mods.mod_files(game_domain_name: 'skyrimspecialedition', mod_id: 2014))
-    end
+    context 'when testing a mod with 2 files' do
 
-    it 'returns the default mod files list' do
-      expect_http_call_to(
-        path: '/v1/games/skyrimspecialedition/mods/2014/files.json',
-        json: { files: json_example_mod_files }
-      )
-      expect_mod_files_to_be_example(nexus_mods(mod_id: 2014).mod_files(game_domain_name: 'skyrimspecialedition'))
-    end
+      before do
+        expect_http_call_to(
+          path: '/v1/games/skyrimspecialedition/mods/2014/files.json',
+          json: { 'files' => json_example_mod_files }
+        )
+      end
 
-    it 'returns mod files list for the default game' do
-      expect_http_call_to(
-        path: '/v1/games/skyrimspecialedition/mods/2014/files.json',
-        json: { files: json_example_mod_files }
-      )
-      expect_mod_files_to_be_example(nexus_mods(game_domain_name: 'skyrimspecialedition').mod_files(mod_id: 2014))
-    end
+      it 'returns a mod files list' do
+        expect_mod_files_to_be_example(nexus_mods.mod_files(game_domain_name: 'skyrimspecialedition', mod_id: 2014))
+      end
 
-    it 'returns mod files list for the default game set using accessor' do
-      expect_http_call_to(
-        path: '/v1/games/skyrimspecialedition/mods/2014/files.json',
-        json: { files: json_example_mod_files }
-      )
-      nexus_mods.game_domain_name = 'skyrimspecialedition'
-      expect_mod_files_to_be_example(nexus_mods.mod_files(mod_id: 2014))
-    end
+      it 'returns the default mod files list' do
+        expect_mod_files_to_be_example(nexus_mods(mod_id: 2014).mod_files(game_domain_name: 'skyrimspecialedition'))
+      end
 
-    it 'returns mod files list for the default game and mod' do
-      expect_http_call_to(
-        path: '/v1/games/skyrimspecialedition/mods/2014/files.json',
-        json: { files: json_example_mod_files }
-      )
-      expect_mod_files_to_be_example(nexus_mods(game_domain_name: 'skyrimspecialedition', mod_id: 2014).mod_files)
-    end
+      it 'returns mod files list for the default game' do
+        expect_mod_files_to_be_example(nexus_mods(game_domain_name: 'skyrimspecialedition').mod_files(mod_id: 2014))
+      end
+
+      it 'returns mod files list for the default game set using accessor' do
+        nexus_mods.game_domain_name = 'skyrimspecialedition'
+        expect_mod_files_to_be_example(nexus_mods.mod_files(mod_id: 2014))
+      end
+
+      it 'returns mod files list for the default game and mod' do
+        expect_mod_files_to_be_example(nexus_mods(game_domain_name: 'skyrimspecialedition', mod_id: 2014).mod_files)
+      end
+
+      it 'returns mod files list for the default game and mod using accessor' do
+        nexus_mods.mod_id = 2014
+        expect_mod_files_to_be_example(nexus_mods.mod_files(game_domain_name: 'skyrimspecialedition'))
+      end
 
-    it 'returns mod files list for the default game and mod using accessor' do
-      expect_http_call_to(
-        path: '/v1/games/skyrimspecialedition/mods/2014/files.json',
-        json: { files: json_example_mod_files }
-      )
-      nexus_mods.mod_id = 2014
-      expect_mod_files_to_be_example(nexus_mods.mod_files(game_domain_name: 'skyrimspecialedition'))
     end
 
     it 'compares objects for equality' do
       expect_http_call_to(
         path: '/v1/games/skyrimspecialedition/mods/2014/files.json',
-        json: { files: [json_mod_file2472] }
+        json: { 'files' => [json_mod_file2472] }
       )
       mod_file1 = nexus_mods(game_domain_name: 'skyrimspecialedition', mod_id: 2014).mod_files.first
       mod_file2 = nexus_mods(game_domain_name: 'skyrimspecialedition', mod_id: 2014).mod_files.first
@@ -100,7 +87,7 @@ describe NexusMods::Api::ModFile do
         expect_http_call_to(
           path: '/v1/games/skyrimspecialedition/mods/2014/files.json',
           json: {
-            files: [
+            'files' => [
               {
                 'id' => [
                   2472,
@@ -134,6 +121,196 @@ describe NexusMods::Api::ModFile do
       end
     end
 
+    context 'when checking cache data freshness' do
+
+      it 'returns that mod files never retrieved are not up-to-date' do
+        expect(nexus_mods.mod_files_cache_up_to_date?(game_domain_name: 'skyrimspecialedition', mod_id: 2014)).to be false
+      end
+
+      context 'when retrieving mod files previously' do
+
+        before do
+          expect_http_call_to(
+            path: '/v1/games/skyrimspecialedition/mods/2014/files.json',
+            json: { 'files' => [json_mod_file2472] }
+          )
+          nexus_mods.mod_files(game_domain_name: 'skyrimspecialedition', mod_id: 2014)
+        end
+
+        context 'when retrieved 40 days ago' do
+
+          let(:forty_days_ago) { Time.now - (40 * 24 * 60 * 60) }
+
+          before do
+            nexus_mods.set_mod_files_cache_timestamp(cache_timestamp: forty_days_ago, game_domain_name: 'skyrimspecialedition', mod_id: 2014)
+          end
+
+          it 'returns that mod files are not up-to-date' do
+            expect(nexus_mods.mod_files_cache_up_to_date?(game_domain_name: 'skyrimspecialedition', mod_id: 2014)).to be false
+            expect(nexus_mods.mod_files_cache_timestamp(game_domain_name: 'skyrimspecialedition', mod_id: 2014)).to eq forty_days_ago
+          end
+
+        end
+
+        context 'when retrieved 2 days ago' do
+
+          let(:two_days_ago) { Time.now - (2 * 24 * 60 * 60) }
+
+          before do
+            nexus_mods.set_mod_files_cache_timestamp(cache_timestamp: two_days_ago, game_domain_name: 'skyrimspecialedition', mod_id: 2014)
+          end
+
+          it 'returns that mod files are up-to-date after checking updated mods and not finding it, and updates its cache timestamp to the update time' do
+            expect_http_call_to(
+              path: '/v1/games/skyrimspecialedition/mods/updated.json?period=1m',
+              json: []
+            )
+            expect(nexus_mods.mod_files_cache_up_to_date?(game_domain_name: 'skyrimspecialedition', mod_id: 2014)).to be true
+            expect(nexus_mods.mod_files_cache_timestamp(game_domain_name: 'skyrimspecialedition', mod_id: 2014)).to eq(
+              nexus_mods.updated_mods_cache_timestamp(game_domain_name: 'skyrimspecialedition', since: :one_month)
+            )
+          end
+
+          it 'returns that mod files are up-to-date after checking updated mods and finding that cache is more recent, and updates its cache timestamp to the update time' do
+            expect_http_call_to(
+              path: '/v1/games/skyrimspecialedition/mods/updated.json?period=1m',
+              json: [
+                {
+                  'mod_id' => 2014,
+                  # Mock that mod was updated 3 days ago
+                  'latest_file_update' => Integer((Time.now - (3 * 24 * 60 * 60)).strftime('%s')),
+                  'latest_mod_activity' => 1
+                }
+              ]
+            )
+            expect(nexus_mods.mod_files_cache_up_to_date?(game_domain_name: 'skyrimspecialedition', mod_id: 2014)).to be true
+            expect(nexus_mods.mod_files_cache_timestamp(game_domain_name: 'skyrimspecialedition', mod_id: 2014)).to eq(
+              nexus_mods.updated_mods_cache_timestamp(game_domain_name: 'skyrimspecialedition', since: :one_month)
+            )
+          end
+
+          it 'returns that mod files are not up-to-date after checking updated mods and finding that cache is less recent' do
+            expect_http_call_to(
+              path: '/v1/games/skyrimspecialedition/mods/updated.json?period=1m',
+              json: [
+                {
+                  'mod_id' => 2014,
+                  # Mock that mod was updated yesterday
+                  'latest_file_update' => Integer((Time.now - (24 * 60 * 60)).strftime('%s')),
+                  'latest_mod_activity' => 1
+                }
+              ]
+            )
+            expect(nexus_mods.mod_files_cache_up_to_date?(game_domain_name: 'skyrimspecialedition', mod_id: 2014)).to be false
+            expect(nexus_mods.mod_files_cache_timestamp(game_domain_name: 'skyrimspecialedition', mod_id: 2014)).to eq two_days_ago
+          end
+
+        end
+
+        context 'when retrieved 3 minutes ago with an updated mods query 4 minutes ago in the cache' do
+
+          let(:three_minutes_ago) { Time.now - (3 * 60) }
+          let(:four_minutes_ago) { Time.now - (4 * 60) }
+
+          before do
+            expect_http_call_to(
+              path: '/v1/games/skyrimspecialedition/mods/updated.json?period=1m',
+              json: [
+                {
+                  'mod_id' => 2014,
+                  # Mock that mod was updated 3 days ago
+                  'latest_file_update' => Integer((Time.now - (3 * 24 * 60 * 60)).strftime('%s')),
+                  'latest_mod_activity' => 1
+                }
+              ]
+            )
+            nexus_mods.updated_mods(game_domain_name: 'skyrimspecialedition', since: :one_month)
+            nexus_mods.set_mod_files_cache_timestamp(cache_timestamp: three_minutes_ago, game_domain_name: 'skyrimspecialedition', mod_id: 2014)
+            nexus_mods.set_updated_mods_cache_timestamp(cache_timestamp: four_minutes_ago, game_domain_name: 'skyrimspecialedition', since: :one_month)
+          end
+
+          it 'returns that mod files are up-to-date but doesn\'t change its mod cache timestamp' do
+            expect(nexus_mods.mod_files_cache_up_to_date?(game_domain_name: 'skyrimspecialedition', mod_id: 2014)).to be true
+            expect(nexus_mods.mod_files_cache_timestamp(game_domain_name: 'skyrimspecialedition', mod_id: 2014)).to eq three_minutes_ago
+            expect(nexus_mods.updated_mods_cache_timestamp(game_domain_name: 'skyrimspecialedition', since: :one_month)).to eq four_minutes_ago
+          end
+
+        end
+
+      end
+
+    end
+
+    context 'when checking for updates' do
+
+      before do
+        nexus_mods(game_domain_name: 'skyrimspecialedition', mod_id: 2014)
+      end
+
+      it 'does not check for updates if mod files have not been retrieved before' do
+        expect_http_call_to(
+          path: '/v1/games/skyrimspecialedition/mods/2014/files.json',
+          json: { 'files' => [json_mod_file2472] }
+        )
+        expect_mod_file_to_be2472(nexus_mods.mod_files(check_updates: true).first)
+      end
+
+      it 'does not check for updates if mod files have been retrieved more than 1 month ago, and re-query the mod' do
+        expect_http_call_to(
+          path: '/v1/games/skyrimspecialedition/mods/2014/files.json',
+          json: { 'files' => [json_mod_file2472] },
+          times: 2
+        )
+        nexus_mods.mod_files
+        nexus_mods.set_mod_files_cache_timestamp(cache_timestamp: Time.now - (40 * 24 * 60 * 60), game_domain_name: 'skyrimspecialedition', mod_id: 2014)
+        expect_mod_file_to_be2472(nexus_mods.mod_files(check_updates: true).first)
+      end
+
+      it 'checks for updates when mod has been retrieved less than 1 month ago and does nothing if its date is less recent than the cache' do
+        expect_http_call_to(
+          path: '/v1/games/skyrimspecialedition/mods/2014/files.json',
+          json: { 'files' => [json_mod_file2472] }
+        )
+        expect_http_call_to(
+          path: '/v1/games/skyrimspecialedition/mods/updated.json?period=1m',
+          json: [
+            {
+              'mod_id' => 2014,
+              # Mock that mod was updated 25 days ago
+              'latest_file_update' => Integer((Time.now - (25 * 24 * 60 * 60)).strftime('%s')),
+              'latest_mod_activity' => 1
+            }
+          ]
+        )
+        nexus_mods.mod_files
+        nexus_mods.set_mod_files_cache_timestamp(cache_timestamp: Time.now - (20 * 24 * 60 * 60), game_domain_name: 'skyrimspecialedition', mod_id: 2014)
+        expect_mod_file_to_be2472(nexus_mods.mod_files(check_updates: true).first)
+      end
+
+      it 'checks for updates when mod has been retrieved less than 1 month ago and re-query the mod if its date is more recent than the cache' do
+        expect_http_call_to(
+          path: '/v1/games/skyrimspecialedition/mods/2014/files.json',
+          json: { 'files' => [json_mod_file2472] },
+          times: 2
+        )
+        expect_http_call_to(
+          path: '/v1/games/skyrimspecialedition/mods/updated.json?period=1m',
+          json: [
+            {
+              'mod_id' => 2014,
+              # Mock that mod was updated 15 days ago
+              'latest_file_update' => Integer((Time.now - (15 * 24 * 60 * 60)).strftime('%s')),
+              'latest_mod_activity' => 1
+            }
+          ]
+        )
+        nexus_mods.mod_files
+        nexus_mods.set_mod_files_cache_timestamp(cache_timestamp: Time.now - (20 * 24 * 60 * 60), game_domain_name: 'skyrimspecialedition', mod_id: 2014)
+        expect_mod_file_to_be2472(nexus_mods.mod_files(check_updates: true).first)
+      end
+
+    end
+
   end
 
 end

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

@@ -6,73 +6,253 @@ describe NexusMods::Api::Mod do
       expect_validate_user
     end
 
-    it 'returns a mod complete information' do
-      expect_http_call_to(
-        path: '/v1/games/skyrimspecialedition/mods/2014.json',
-        json: json_complete_mod
-      )
-      expect_mod_to_be_complete(nexus_mods.mod(game_domain_name: 'skyrimspecialedition', mod_id: 2014))
-    end
+    context 'when accessing a partial mod' do
 
-    it 'returns a mod partial information' do
-      expect_http_call_to(
-        path: '/v1/games/skyrimspecialedition/mods/2014.json',
-        json: json_partial_mod
-      )
-      expect_mod_to_be_partial(nexus_mods.mod(game_domain_name: 'skyrimspecialedition', mod_id: 2014))
-    end
+      before do
+        expect_http_call_to(
+          path: '/v1/games/skyrimspecialedition/mods/2014.json',
+          json: json_partial_mod
+        )
+      end
 
-    it 'returns the default mod information' do
-      expect_http_call_to(
-        path: '/v1/games/skyrimspecialedition/mods/2014.json',
-        json: json_complete_mod
-      )
-      expect_mod_to_be_complete(nexus_mods(mod_id: 2014).mod(game_domain_name: 'skyrimspecialedition'))
-    end
+      it 'returns the mod information' do
+        expect_mod_to_be_partial(nexus_mods.mod(game_domain_name: 'skyrimspecialedition', mod_id: 2014))
+      end
 
-    it 'returns mod information for the default game' do
-      expect_http_call_to(
-        path: '/v1/games/skyrimspecialedition/mods/2014.json',
-        json: json_complete_mod
-      )
-      expect_mod_to_be_complete(nexus_mods(game_domain_name: 'skyrimspecialedition').mod(mod_id: 2014))
     end
 
-    it 'returns mod information for the default game set using accessor' do
-      expect_http_call_to(
-        path: '/v1/games/skyrimspecialedition/mods/2014.json',
-        json: json_complete_mod
-      )
-      nexus_mods.game_domain_name = 'skyrimspecialedition'
-      expect_mod_to_be_complete(nexus_mods.mod(mod_id: 2014))
-    end
+    context 'when accessing a complete mod' do
+
+      before do
+        expect_http_call_to(
+          path: '/v1/games/skyrimspecialedition/mods/2014.json',
+          json: json_complete_mod
+        )
+      end
+
+      it 'returns the mod information' do
+        expect_mod_to_be_complete(nexus_mods.mod(game_domain_name: 'skyrimspecialedition', mod_id: 2014))
+      end
+
+      it 'returns the default mod information' do
+        expect_mod_to_be_complete(nexus_mods(mod_id: 2014).mod(game_domain_name: 'skyrimspecialedition'))
+      end
+
+      it 'returns mod information for the default game' do
+        expect_mod_to_be_complete(nexus_mods(game_domain_name: 'skyrimspecialedition').mod(mod_id: 2014))
+      end
+
+      it 'returns mod information for the default game set using accessor' do
+        nexus_mods.game_domain_name = 'skyrimspecialedition'
+        expect_mod_to_be_complete(nexus_mods.mod(mod_id: 2014))
+      end
+
+      it 'returns mod information for the default game and mod' do
+        expect_mod_to_be_complete(nexus_mods(game_domain_name: 'skyrimspecialedition', mod_id: 2014).mod)
+      end
+
+      it 'returns mod information for the default game and mod set using accessor' do
+        nexus_mods.mod_id = 2014
+        expect_mod_to_be_complete(nexus_mods.mod(game_domain_name: 'skyrimspecialedition'))
+      end
+
+      it 'compares objects for equality' do
+        mod1 = nexus_mods.mod(game_domain_name: 'skyrimspecialedition', mod_id: 2014)
+        mod2 = nexus_mods.mod(game_domain_name: 'skyrimspecialedition', mod_id: 2014)
+        expect(mod1.object_id).not_to eq mod2.object_id
+        expect(mod1).to eq mod2
+      end
 
-    it 'returns mod information for the default game and mod' do
-      expect_http_call_to(
-        path: '/v1/games/skyrimspecialedition/mods/2014.json',
-        json: json_complete_mod
-      )
-      expect_mod_to_be_complete(nexus_mods(game_domain_name: 'skyrimspecialedition', mod_id: 2014).mod)
     end
 
-    it 'returns mod information for the default game and mod set using accessor' do
-      expect_http_call_to(
-        path: '/v1/games/skyrimspecialedition/mods/2014.json',
-        json: json_complete_mod
-      )
-      nexus_mods.mod_id = 2014
-      expect_mod_to_be_complete(nexus_mods.mod(game_domain_name: 'skyrimspecialedition'))
+    context 'when checking cache data freshness' do
+
+      it 'returns that a mod never retrieved is not up-to-date' do
+        expect(nexus_mods.mod_cache_up_to_date?(game_domain_name: 'skyrimspecialedition', mod_id: 2014)).to be false
+      end
+
+      context 'when retrieving a mod previously' do
+
+        before do
+          expect_http_call_to(
+            path: '/v1/games/skyrimspecialedition/mods/2014.json',
+            json: json_complete_mod
+          )
+          nexus_mods.mod(game_domain_name: 'skyrimspecialedition', mod_id: 2014)
+        end
+
+        context 'when retrieved 40 days ago' do
+
+          let(:forty_days_ago) { Time.now - (40 * 24 * 60 * 60) }
+
+          before do
+            nexus_mods.set_mod_cache_timestamp(cache_timestamp: forty_days_ago, game_domain_name: 'skyrimspecialedition', mod_id: 2014)
+          end
+
+          it 'returns that the mod is not up-to-date' do
+            expect(nexus_mods.mod_cache_up_to_date?(game_domain_name: 'skyrimspecialedition', mod_id: 2014)).to be false
+            expect(nexus_mods.mod_cache_timestamp(game_domain_name: 'skyrimspecialedition', mod_id: 2014)).to eq forty_days_ago
+          end
+
+        end
+
+        context 'when retrieved 2 days ago' do
+
+          let(:two_days_ago) { Time.now - (2 * 24 * 60 * 60) }
+
+          before do
+            nexus_mods.set_mod_cache_timestamp(cache_timestamp: two_days_ago, game_domain_name: 'skyrimspecialedition', mod_id: 2014)
+          end
+
+          it 'returns that the mod is up-to-date after checking updated mods and not finding it, and updates its cache timestamp to the update time' do
+            expect_http_call_to(
+              path: '/v1/games/skyrimspecialedition/mods/updated.json?period=1m',
+              json: []
+            )
+            expect(nexus_mods.mod_cache_up_to_date?(game_domain_name: 'skyrimspecialedition', mod_id: 2014)).to be true
+            expect(nexus_mods.mod_cache_timestamp(game_domain_name: 'skyrimspecialedition', mod_id: 2014)).to eq(
+              nexus_mods.updated_mods_cache_timestamp(game_domain_name: 'skyrimspecialedition', since: :one_month)
+            )
+          end
+
+          it 'returns that the mod is up-to-date after checking updated mods and finding that cache is more recent, and updates its cache timestamp to the update time' do
+            expect_http_call_to(
+              path: '/v1/games/skyrimspecialedition/mods/updated.json?period=1m',
+              json: [
+                {
+                  'mod_id' => 2014,
+                  # Mock that mod was updated 3 days ago
+                  'latest_file_update' => 1,
+                  'latest_mod_activity' => Integer((Time.now - (3 * 24 * 60 * 60)).strftime('%s'))
+                }
+              ]
+            )
+            expect(nexus_mods.mod_cache_up_to_date?(game_domain_name: 'skyrimspecialedition', mod_id: 2014)).to be true
+            expect(nexus_mods.mod_cache_timestamp(game_domain_name: 'skyrimspecialedition', mod_id: 2014)).to eq(
+              nexus_mods.updated_mods_cache_timestamp(game_domain_name: 'skyrimspecialedition', since: :one_month)
+            )
+          end
+
+          it 'returns that the mod is not up-to-date after checking updated mods and finding that cache is less recent' do
+            expect_http_call_to(
+              path: '/v1/games/skyrimspecialedition/mods/updated.json?period=1m',
+              json: [
+                {
+                  'mod_id' => 2014,
+                  # Mock that mod was updated yesterday
+                  'latest_file_update' => 1,
+                  'latest_mod_activity' => Integer((Time.now - (24 * 60 * 60)).strftime('%s'))
+                }
+              ]
+            )
+            expect(nexus_mods.mod_cache_up_to_date?(game_domain_name: 'skyrimspecialedition', mod_id: 2014)).to be false
+            expect(nexus_mods.mod_cache_timestamp(game_domain_name: 'skyrimspecialedition', mod_id: 2014)).to eq two_days_ago
+          end
+
+        end
+
+        context 'when retrieved 3 minutes ago with an updated mods query 4 minutes ago in the cache' do
+
+          let(:three_minutes_ago) { Time.now - (3 * 60) }
+          let(:four_minutes_ago) { Time.now - (4 * 60) }
+
+          before do
+            expect_http_call_to(
+              path: '/v1/games/skyrimspecialedition/mods/updated.json?period=1m',
+              json: [
+                {
+                  'mod_id' => 2014,
+                  # Mock that mod was updated 3 days ago
+                  'latest_file_update' => 1,
+                  'latest_mod_activity' => Integer((Time.now - (3 * 24 * 60 * 60)).strftime('%s'))
+                }
+              ]
+            )
+            nexus_mods.updated_mods(game_domain_name: 'skyrimspecialedition', since: :one_month)
+            nexus_mods.set_mod_cache_timestamp(cache_timestamp: three_minutes_ago, game_domain_name: 'skyrimspecialedition', mod_id: 2014)
+            nexus_mods.set_updated_mods_cache_timestamp(cache_timestamp: four_minutes_ago, game_domain_name: 'skyrimspecialedition', since: :one_month)
+          end
+
+          it 'returns that the mod is up-to-date but doesn\'t change its mod cache timestamp' do
+            expect(nexus_mods.mod_cache_up_to_date?(game_domain_name: 'skyrimspecialedition', mod_id: 2014)).to be true
+            expect(nexus_mods.mod_cache_timestamp(game_domain_name: 'skyrimspecialedition', mod_id: 2014)).to eq three_minutes_ago
+            expect(nexus_mods.updated_mods_cache_timestamp(game_domain_name: 'skyrimspecialedition', since: :one_month)).to eq four_minutes_ago
+          end
+
+        end
+
+      end
+
     end
 
-    it 'compares objects for equality' do
-      expect_http_call_to(
-        path: '/v1/games/skyrimspecialedition/mods/2014.json',
-        json: json_complete_mod
-      )
-      mod1 = nexus_mods.mod(game_domain_name: 'skyrimspecialedition', mod_id: 2014)
-      mod2 = nexus_mods.mod(game_domain_name: 'skyrimspecialedition', mod_id: 2014)
-      expect(mod1.object_id).not_to eq mod2.object_id
-      expect(mod1).to eq mod2
+    context 'when checking for updates' do
+
+      before do
+        nexus_mods(game_domain_name: 'skyrimspecialedition', mod_id: 2014)
+      end
+
+      it 'does not check for updates if mod has not been retrieved before' do
+        expect_http_call_to(
+          path: '/v1/games/skyrimspecialedition/mods/2014.json',
+          json: json_complete_mod
+        )
+        expect_mod_to_be_complete(nexus_mods.mod(check_updates: true))
+      end
+
+      it 'does not check for updates if mod has been retrieved more than 1 month ago, and re-query the mod' do
+        expect_http_call_to(
+          path: '/v1/games/skyrimspecialedition/mods/2014.json',
+          json: json_complete_mod,
+          times: 2
+        )
+        nexus_mods.mod
+        nexus_mods.set_mod_cache_timestamp(cache_timestamp: Time.now - (40 * 24 * 60 * 60), game_domain_name: 'skyrimspecialedition', mod_id: 2014)
+        expect_mod_to_be_complete(nexus_mods.mod(check_updates: true))
+      end
+
+      it 'checks for updates when mod has been retrieved less than 1 month ago and does nothing if its date is less recent than the cache' do
+        expect_http_call_to(
+          path: '/v1/games/skyrimspecialedition/mods/2014.json',
+          json: json_complete_mod
+        )
+        expect_http_call_to(
+          path: '/v1/games/skyrimspecialedition/mods/updated.json?period=1m',
+          json: [
+            {
+              'mod_id' => 2014,
+              # Mock that mod was updated 25 days ago
+              'latest_file_update' => 1,
+              'latest_mod_activity' => Integer((Time.now - (25 * 24 * 60 * 60)).strftime('%s'))
+            }
+          ]
+        )
+        nexus_mods.mod
+        nexus_mods.set_mod_cache_timestamp(cache_timestamp: Time.now - (20 * 24 * 60 * 60), game_domain_name: 'skyrimspecialedition', mod_id: 2014)
+        expect_mod_to_be_complete(nexus_mods.mod(check_updates: true))
+      end
+
+      it 'checks for updates when mod has been retrieved less than 1 month ago and re-query the mod if its date is more recent than the cache' do
+        expect_http_call_to(
+          path: '/v1/games/skyrimspecialedition/mods/2014.json',
+          json: json_complete_mod,
+          times: 2
+        )
+        expect_http_call_to(
+          path: '/v1/games/skyrimspecialedition/mods/updated.json?period=1m',
+          json: [
+            {
+              'mod_id' => 2014,
+              # Mock that mod was updated 15 days ago
+              'latest_file_update' => 1,
+              'latest_mod_activity' => Integer((Time.now - (15 * 24 * 60 * 60)).strftime('%s'))
+            }
+          ]
+        )
+        nexus_mods.mod
+        nexus_mods.set_mod_cache_timestamp(cache_timestamp: Time.now - (20 * 24 * 60 * 60), game_domain_name: 'skyrimspecialedition', mod_id: 2014)
+        expect_mod_to_be_complete(nexus_mods.mod(check_updates: true))
+      end
+
     end
 
   end

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

@@ -20,6 +20,7 @@ describe NexusMods do
         query: proc { |nm| nm.games },
         query_without_cache: proc { |nm| nm.games(clear_cache: true) },
         get_cache_timestamp: proc { |nm| nm.games_cache_timestamp },
+        set_cache_timestamp: proc { |nm, ts| nm.set_games_cache_timestamp(cache_timestamp: ts) },
         expiry_cache_param: :games
       },
       'mods' => {
@@ -28,6 +29,7 @@ describe NexusMods do
         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) },
+        set_cache_timestamp: proc { |nm, ts| nm.set_mod_cache_timestamp(game_domain_name: 'skyrimspecialedition', mod_id: 2014, cache_timestamp: ts) },
         expiry_cache_param: :mod
       },
       'mod files' => {
@@ -41,6 +43,7 @@ describe NexusMods do
         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) },
+        set_cache_timestamp: proc { |nm, ts| nm.set_mod_files_cache_timestamp(game_domain_name: 'skyrimspecialedition', mod_id: 2014, cache_timestamp: ts) },
         expiry_cache_param: :mod_files
       }
     }.merge(
@@ -68,7 +71,8 @@ describe NexusMods do
             ],
             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]) }
+            get_cache_timestamp: proc { |nm| nm.updated_mods_cache_timestamp(game_domain_name: 'skyrimspecialedition', since: since_config[:since]) },
+            set_cache_timestamp: proc { |nm, ts| nm.set_updated_mods_cache_timestamp(game_domain_name: 'skyrimspecialedition', since: since_config[:since], cache_timestamp: ts) }
           }
         ]
       end
@@ -131,6 +135,18 @@ describe NexusMods do
           expect(resource_config[:get_cache_timestamp].call(nexus_mods)).to be_between(before, after)
         end
 
+        it 'changes manually 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]
+          )
+          resource_config[:query].call(nexus_mods)
+          new_cache_timestamp = Time.parse('2023-01-12 11:22:33 UTC')
+          resource_config[:set_cache_timestamp].call(nexus_mods, new_cache_timestamp)
+          expect(resource_config[:get_cache_timestamp].call(nexus_mods)).to eq new_cache_timestamp
+        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(
@@ -159,7 +175,22 @@ describe NexusMods do
           end
         end
 
-        it 'updates the timestamp of the data stored in the API cache' do
+        it 'persists the cache timestamp that has been changed manually' 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]
+            )
+            resource_config[:query].call(nexus_mods(api_cache_file:))
+            new_cache_timestamp = Time.parse('2023-01-12 11:22:33 UTC')
+            resource_config[:set_cache_timestamp].call(nexus_mods, new_cache_timestamp)
+            reset_nexus_mods
+            expect(resource_config[:get_cache_timestamp].call(nexus_mods(api_cache_file:))).to eq new_cache_timestamp
+          end
+        end
+
+        it 'updates the timestamp of the data stored in the API cache by forcing an API query' do
           expect_validate_user
           expect_http_call_to(
             path: resource_config[:expected_api_path],
@@ -174,6 +205,21 @@ describe NexusMods do
           expect(resource_config[:get_cache_timestamp].call(nexus_mods)).to be_between(before, after)
         end
 
+        it 'updates the timestamp of the data stored in the API cache by updating manually the cache timestamp' 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)
+          resource_config[:set_cache_timestamp].call(nexus_mods, Time.now.utc - (365 * 24 * 60 * 60))
+          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
+
         context 'when testing cache persistence in files' do
 
           it 'persists API cache in a file' do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nexus_mods
 version: !ruby/object:Gem::Version
-  version: 2.2.0
+  version: 2.4.0
 platform: ruby
 authors:
 - Muriel Salvan