nexus_mods 2.3.0 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0d5efb3b98f3d8b66565eff56b7b6360fc99bae69a256423e6eae391eb3cd676
-  data.tar.gz: 7091d96c8a79ec591e805bcc09958199187b5f0afd73de85b5da314c2e24381a
+  metadata.gz: a55e8c7bacc06ef260c5b4e6f0ac64d3e9391e39f7d1ebb00c74c110a6eae214
+  data.tar.gz: 9647e6745975eb0c8c0fe9023a2e66936773fd9389a5d5087511e8edb3e06876
 SHA512:
-  metadata.gz: 1485e5270d8fcffb7a2ebfec15848f0f2af3a2575beef6b2d1c4746af682bd13142d15f140adae1c9e7c15d731d85d63d01ec135f28600e73d58249bc130990e
-  data.tar.gz: eccb9f4312f63a8c8fc459592c4c0c618378f59a69a261512981e890c0bfffa8c2044bafbcd16da9ec9c8d3b980a53a2e5322a89c5eece959240cafb7ac05e19
+  metadata.gz: 29732e93998b9b8b88d66af4ebd67d37d8eaa51f8ab47b487bf0ce2aa3f81312aed8e1275e83a428e5cfa60a2330a7603a6c114f9bf8898593695b0df79603c3
+  data.tar.gz: 8b3542308bd2736695165a337cef28a2e8ea7e63bd7f67d55f74b4ec797edf556d92e4792e3ea7f83a3f7f56dd028b914bcfba8f713b96679687bb29ddac8a00

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+# [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

data/lib/nexus_mods/version.rb

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

data/lib/nexus_mods.rb

@@ -166,9 +166,13 @@ class NexusMods
   # * *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'],
@@ -228,9 +232,13 @@ class NexusMods
   # * *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'],
@@ -327,6 +335,80 @@ class NexusMods
     @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

metadata

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