@nekosuneprojects/gaming-infos 2.2.0 → 2.4.0

package/gamecodes.js

@@ -91,6 +91,31 @@ async function resolveCachedGame(game) {
   return slug;
 }
 
+function hydrateCachedExpiry(entry) {
+  if (!entry || typeof entry !== 'object') return entry;
+  const output = { ...entry };
+  if (!entry.expiry || typeof entry.expiry !== 'object' || Array.isArray(entry.expiry)) return output;
+
+  const expiry = { ...entry.expiry };
+  const expiresAtMs = expiry.expiresAt ? new Date(expiry.expiresAt).getTime() : NaN;
+  if (!Number.isNaN(expiresAtMs)) {
+    const remainingSeconds = Math.max(0, Math.floor((expiresAtMs - Date.now()) / 1000));
+    expiry.expiresInSeconds = remainingSeconds;
+    expiry.expired = expiresAtMs <= Date.now();
+    expiry.countdown = {
+      days: Math.floor(remainingSeconds / 86400),
+      hours: Math.floor((remainingSeconds % 86400) / 3600),
+      minutes: Math.floor((remainingSeconds % 3600) / 60),
+      seconds: remainingSeconds % 60
+    };
+  } else {
+    expiry.expiresInSeconds = null;
+    expiry.countdown = null;
+  }
+  output.expiry = expiry;
+  return output;
+}
+
 function filterCachedList(data, options = {}) {
   if (!data || typeof data !== 'object') return data;
   const includeUnknown = Boolean(options.includeUnknown);
@@ -104,11 +129,12 @@ function filterCachedList(data, options = {}) {
     return true;
   };
 
+  const hydrate = (rows) => Array.isArray(rows) ? rows.filter(matches).map(hydrateCachedExpiry) : [];
   const result = {
-    Active: Array.isArray(data.Active) ? data.Active.filter(matches) : [],
-    Expired: Array.isArray(data.Expired) ? data.Expired.filter(matches) : []
+    Active: hydrate(data.Active),
+    Expired: hydrate(data.Expired)
   };
-  if (includeUnknown) result.Unknown = Array.isArray(data.Unknown) ? data.Unknown.filter(matches) : [];
+  if (includeUnknown) result.Unknown = hydrate(data.Unknown);
   return result;
 }
 
@@ -159,7 +185,7 @@ async function gameCode(game, code, options = {}) {
   const wanted = normalizeCode(codeValue);
   for (const bucket of ['Active', 'Expired', 'Unknown']) {
     for (const entry of Array.isArray(cached[bucket]) ? cached[bucket] : []) {
-      if (normalizeCode(entry?.code) === wanted) return entry;
+      if (normalizeCode(entry?.code) === wanted) return hydrateCachedExpiry(entry);
     }
   }
   return { error: `Code "${code}" not found for game "${game}".` };

package/index.js

@@ -31,8 +31,8 @@ function withLocalSlug(filePath, data) {
 
 // Live lookups go through the NekoSuneVR V5 API first so data can be updated
 // in real time without republishing this package. The bundled JSON under
-// data/ is the offline fallback and is mirrored from APINODE by the scheduled
-// sync workflow.
+// data/ is the offline fallback and is mirrored from APINODE by the hourly
+// change-watch workflow.
 async function fetchFromApi(game, type, name) {
   if (apiDisabled() || typeof fetch !== 'function') return null;
 
@@ -210,12 +210,14 @@ module.exports = {
   Players: (game, name) => load(game, 'players', name),
   Avatars: (game, name) => load(game, 'avatars', name),
   Characters: (game, name) => load(game, 'characters', name),
+  NPCs: (game, name) => load(game, 'npcs', name),
+  Maps: (game, name) => load(game, 'maps', name),
   Get: (game, type, name) => load(game, type, name),
   List: (game, type) => list(game, type),
   CacheInfo: () => cacheInfo(),
 
   // Game redeem/creator code API helpers. These also use live APINODE first and
-  // automatically fall back to the daily mirrored data/game-codes snapshot.
+  // automatically fall back to the hourly mirrored data/game-codes snapshot.
   Codes: gameCodes.Codes,
   CodesStatus: gameCodes.CodesStatus,
   GameCodes: gameCodes.GameCodes,

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@nekosuneprojects/gaming-infos",
-    "version": "2.2.0",
-    "description": "Multi-game data loader for VRChat, character datasets, and game redeem/creator codes. Uses the NekoSuneVR V5 API first with automatically mirrored local JSON fallbacks.",
+    "version": "2.4.0",
+    "description": "Multi-game data loader for VRChat, Fortnite, Call of Duty, character/NPC/map datasets, and game redeem/creator codes. Uses the NekoSuneVR V5 API first with automatically mirrored local JSON fallbacks.",
     "main": "index.js",
     "type": "commonjs",
     "engines": {
@@ -34,6 +34,16 @@
         "wuthering-waves",
         "warframe",
         "fortnite",
+        "fortnite-skins",
+        "fortnite-npcs",
+        "fortnite-maps",
+        "call-of-duty",
+        "cod",
+        "modern-warfare",
+        "black-ops",
+        "call-of-duty-maps",
+        "call-of-duty-characters",
+        "call-of-duty-npcs",
         "zenless-zone-zero",
         "tower-of-fantasy",
         "arknights-endfield",
@@ -41,7 +51,9 @@
         "groups",
         "players",
         "avatars",
-        "characters"
+        "characters",
+        "npcs",
+        "maps"
     ],
     "author": "NekoSuneVR",
     "license": "MIT"

package/scripts/cache-sync-smoke.js

@@ -5,7 +5,12 @@ const fs = require('fs');
 const http = require('http');
 const os = require('os');
 const path = require('path');
-const { syncApiCache } = require('./sync-api-cache');
+const {
+  DEFAULT_MANIFEST,
+  mergeDiscoveredManifest,
+  validateRootSyncState,
+  syncApiCache
+} = require('./sync-api-cache');
 
 function json(res, status, body) {
   const payload = JSON.stringify(body);
@@ -14,6 +19,40 @@ function json(res, status, body) {
 }
 
 async function main() {
+  assert.deepStrictEqual(
+    DEFAULT_MANIFEST.fortnite,
+    ['characters', 'npcs', 'maps'],
+    'Fortnite fallback mirror must keep skins, NPCs, and maps as separate datasets'
+  );
+
+  const discovered = mergeDiscoveredManifest(
+    [
+      { slug: 'codblackops2', name: 'Call of Duty: Black Ops II', types: ['characters', 'npcs', 'maps'] },
+      { slug: 'futuregame', name: 'Future Public Game', types: ['characters', 'maps'] }
+    ],
+    { testgame: ['characters'] }
+  );
+  assert.deepStrictEqual(discovered.testgame, ['characters']);
+  assert.deepStrictEqual(discovered.codblackops2, ['characters', 'npcs', 'maps']);
+  assert.deepStrictEqual(discovered.futuregame, ['characters', 'maps']);
+
+  assert.doesNotThrow(() => validateRootSyncState({
+    sync: {
+      running: false,
+      syncSchemaVersion: 2,
+      state: { lastStatus: 'success', syncSchemaVersion: 2, requiredSyncSchemaVersion: 2 }
+    }
+  }));
+  assert.throws(() => validateRootSyncState({ sync: { running: true, state: { lastStatus: 'running' } } }), /currently running/);
+  assert.throws(() => validateRootSyncState({ sync: { running: false, state: { lastStatus: 'failed' } } }), /state is failed/);
+  assert.throws(() => validateRootSyncState({
+    sync: {
+      running: false,
+      syncSchemaVersion: 2,
+      state: { lastStatus: 'success', syncSchemaVersion: 1, requiredSyncSchemaVersion: 2 }
+    }
+  }), /schema catch-up is incomplete/);
+
   const root = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'gaming-infos-cache-test-'));
   const dataDir = path.join(root, 'data');
   let failCharacters = false;
@@ -24,10 +63,18 @@ async function main() {
 
   const server = http.createServer((req, res) => {
     if (req.url === '/v5/games/api/gaming-infos') {
-      return json(res, 200, { success: true, data: [{ name: 'Test Game' }] });
+      return json(res, 200, {
+        success: true,
+        data: [{ slug: 'testgame', name: 'Test Game', types: ['characters'] }],
+        sync: {
+          running: false,
+          syncSchemaVersion: 2,
+          state: { lastStatus: 'success', syncSchemaVersion: 2, requiredSyncSchemaVersion: 2 }
+        }
+      });
     }
     if (req.url === '/v5/games/api/gaming-infos/testgame/meta/testgame') {
-      return json(res, 200, { success: true, data: { name: 'Test Game', description: 'fixture' } });
+      return json(res, 200, { success: true, data: { slug: 'testgame', name: 'Test Game', description: 'fixture', types: ['characters'] } });
     }
     if (req.url === '/v5/games/api/gaming-infos/testgame/characters') {
       if (failCharacters) return json(res, 503, { success: false, error: 'fixture outage' });

package/scripts/game-code-cache-smoke.js

@@ -18,21 +18,51 @@ async function main() {
   const temp = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'game-code-cache-'));
   const dataDir = path.join(temp, 'game-codes');
   let phase = 1;
+  let requestTick = 0;
 
   const directory = () => ({
     success: true,
     games: [
-      { game: 'alpha', name: 'Alpha', counts: { total: phase === 1 ? 2 : 2 } },
-      { game: 'beta', name: 'Beta', counts: { total: 1 } }
+      { game: 'alpha', name: 'Alpha', counts: { total: 2 }, lastUpdatedAt: '2026-08-24T10:00:00.000Z' },
+      { game: 'beta', name: 'Beta', counts: { total: 1 }, lastUpdatedAt: '2026-08-24T10:05:00.000Z' }
     ],
-    aliases: { a: 'alpha', b: 'beta' }
+    aliases: { a: 'alpha', b: 'beta' },
+    // Simulates APINODE's request-time directory timestamp. This must not make
+    // an otherwise-identical fallback snapshot look changed.
+    updatedAt: new Date(Date.UTC(2026, 7, 24, 10, 10, requestTick++)).toISOString()
   });
 
+  function expiry() {
+    return {
+      type: 'fixed',
+      expiresAt: '2030-12-31T23:59:59.000Z',
+      local: '31/12/2030, 23:59:59 UTC',
+      expired: false,
+      // These are deliberately volatile and should be stripped by the mirror.
+      expiresInSeconds: 100000 - requestTick,
+      countdown: { days: 1, hours: 2, minutes: 3, seconds: 59 - (requestTick % 50) }
+    };
+  }
+
   const datasets = () => ({
     alpha: phase === 1
-      ? { Active: [{ code: 'KEEP', status: 'active' }, { code: 'REMOVE', status: 'active' }], Expired: [], Unknown: [] }
-      : { Active: [{ code: 'KEEP', status: 'active', notes: 'changed' }, { code: 'ADD', status: 'active' }], Expired: [], Unknown: [] },
-    beta: { Active: [], Expired: [{ code: 'OLD', status: 'expired' }], Unknown: [] }
+      ? {
+          Active: [
+            { code: 'KEEP', status: 'active', expiry: expiry() },
+            { code: 'REMOVE', status: 'active', expiry: expiry() }
+          ],
+          Expired: [],
+          Unknown: []
+        }
+      : {
+          Active: [
+            { code: 'KEEP', status: 'active', notes: 'changed', expiry: expiry() },
+            { code: 'ADD', status: 'active', expiry: expiry() }
+          ],
+          Expired: [],
+          Unknown: []
+        },
+    beta: { Active: [], Expired: [{ code: 'OLD', status: 'expired', expiry: expiry() }], Unknown: [] }
   });
 
   const originalFetch = global.fetch;
@@ -52,15 +82,25 @@ async function main() {
     assert.equal(fs.existsSync(path.join(dataDir, 'games', 'alpha.json')), true);
     let alpha = JSON.parse(await fs.promises.readFile(path.join(dataDir, 'games', 'alpha.json'), 'utf8'));
     assert.deepEqual(alpha.Active.map((row) => row.code), ['KEEP', 'REMOVE']);
+    assert.equal(alpha.Active[0].expiry.expiresAt, '2030-12-31T23:59:59.000Z');
+    assert.equal('expiresInSeconds' in alpha.Active[0].expiry, false);
+    assert.equal('countdown' in alpha.Active[0].expiry, false);
 
     phase = 2;
     const second = await syncGameCodeCache({ dataDir, apiBase: 'https://example.test', apiPath: '/v5/games/api/codes', retries: 0, delayMs: 0 });
     assert.equal(second.success, true);
+    assert.equal(second.changed, true);
     alpha = JSON.parse(await fs.promises.readFile(path.join(dataDir, 'games', 'alpha.json'), 'utf8'));
     assert.deepEqual(alpha.Active.map((row) => row.code), ['KEEP', 'ADD']);
     assert.equal(alpha.Active[0].notes, 'changed');
     assert.equal(alpha.Active.some((row) => row.code === 'REMOVE'), false);
 
+    // Same real API data, but request-time updatedAt/countdowns change again.
+    // The stable snapshot must detect this as unchanged.
+    const unchanged = await syncGameCodeCache({ dataDir, apiBase: 'https://example.test', apiPath: '/v5/games/api/codes', retries: 0, delayMs: 0 });
+    assert.equal(unchanged.success, true);
+    assert.equal(unchanged.changed, false, 'volatile countdown/request timestamps must not create cache commits');
+
     const beforeFailure = await fs.promises.readFile(path.join(dataDir, 'games', 'alpha.json'), 'utf8');
     phase = 3;
     await assert.rejects(

package/scripts/sync-api-cache.js

@@ -9,9 +9,10 @@ const DEFAULT_DATA_DIR = path.join(ROOT_DIR, 'data');
 const DEFAULT_API_BASE = 'https://api.nekosunevr.co.uk';
 const DEFAULT_API_PATH = '/v5/games/api/gaming-infos';
 
-// APINODE currently exposes these game/type pairs. The mirror is authoritative:
-// after a fully successful sync, anything no longer returned by APINODE is removed
-// from data/ so the bundled fallback matches the API snapshot exactly.
+// Safety baseline for older APINODE deployments. Newer APINODE root responses
+// expose { slug, types } for every game, so the mirror automatically adds any
+// newly published datasets (including the full Call of Duty catalog) without a
+// package-code change. Explicit GAMING_INFOS_CACHE_MANIFEST_JSON still works.
 const DEFAULT_MANIFEST = Object.freeze({
   vrchat: ['players', 'groups', 'worlds', 'avatars'],
   genshinimpact: ['characters'],
@@ -19,7 +20,7 @@ const DEFAULT_MANIFEST = Object.freeze({
   nte: ['characters'],
   wutheringwaves: ['characters'],
   warframe: ['characters'],
-  fortnite: ['characters'],
+  fortnite: ['characters', 'npcs', 'maps'],
   zenlesszonezero: ['characters'],
   toweroffantasy: ['characters'],
   arknightsendfield: ['characters']
@@ -61,11 +62,9 @@ function fallbackSlug(name) {
   return safeSlug(slug, 'derived slug');
 }
 
-function loadManifest(raw = process.env.GAMING_INFOS_CACHE_MANIFEST_JSON) {
-  if (!raw) return { ...DEFAULT_MANIFEST };
-  const parsed = typeof raw === 'string' ? JSON.parse(raw) : raw;
+function normalizeManifestObject(parsed) {
   if (!parsed || Array.isArray(parsed) || typeof parsed !== 'object') {
-    throw new Error('GAMING_INFOS_CACHE_MANIFEST_JSON must be a JSON object');
+    throw new Error('Gaming Infos cache manifest must be a JSON object');
   }
   const result = {};
   for (const [gameRaw, typesRaw] of Object.entries(parsed)) {
@@ -76,6 +75,23 @@ function loadManifest(raw = process.env.GAMING_INFOS_CACHE_MANIFEST_JSON) {
   return result;
 }
 
+function loadManifest(raw = process.env.GAMING_INFOS_CACHE_MANIFEST_JSON) {
+  if (!raw) return { ...DEFAULT_MANIFEST };
+  return normalizeManifestObject(typeof raw === 'string' ? JSON.parse(raw) : raw);
+}
+
+function mergeDiscoveredManifest(rootData, configuredManifest = DEFAULT_MANIFEST) {
+  const result = normalizeManifestObject(configuredManifest);
+  for (const row of Array.isArray(rootData) ? rootData : []) {
+    if (!row || typeof row !== 'object' || Array.isArray(row)) continue;
+    if (!row.slug || !Array.isArray(row.types) || !row.types.length) continue;
+    const game = safeSlug(row.slug, 'root game slug');
+    const types = [...new Set(row.types.map((type) => safeSlug(type, `type for ${game}`)))];
+    if (types.length) result[game] = types;
+  }
+  return result;
+}
+
 async function requestJson(url, options = {}) {
   const timeoutMs = numberOption(options.timeoutMs ?? process.env.GAMING_INFOS_CACHE_TIMEOUT_MS, 15000, 1000, 120000);
   const retries = numberOption(options.retries ?? process.env.GAMING_INFOS_CACHE_RETRIES, 2, 0, 5);
@@ -104,6 +120,7 @@ async function requestJson(url, options = {}) {
       if (!body || body.success === false) {
         throw new Error(`API returned an unsuccessful response for ${url}`);
       }
+      if (options.rawEnvelope) return body;
       return body.data !== undefined ? body.data : body;
     } catch (error) {
       lastError = error;
@@ -123,6 +140,26 @@ function apiUrl(base, apiPath, suffix = '') {
   return `${normalizeBase(base)}${normalizeApiPath(apiPath)}${suffix}`;
 }
 
+function validateRootSyncState(rootEnvelope) {
+  const sync = rootEnvelope && typeof rootEnvelope === 'object' ? rootEnvelope.sync : null;
+  if (!sync || typeof sync !== 'object') return;
+
+  const state = sync.state && typeof sync.state === 'object' ? sync.state : null;
+  const status = String(state?.lastStatus || '').toLowerCase();
+  if (sync.running || status === 'running') {
+    throw new Error('APINODE content synchronization is currently running; preserving the previous fallback until it is idle');
+  }
+  if (state && ['never-run', 'failed'].includes(status)) {
+    throw new Error(`APINODE content synchronization state is ${status}; preserving the previous fallback`);
+  }
+
+  const persistedSchema = Number(state?.syncSchemaVersion || 0);
+  const requiredSchema = Number(state?.requiredSyncSchemaVersion || sync.syncSchemaVersion || 0);
+  if (requiredSchema > 0 && persistedSchema < requiredSchema) {
+    throw new Error(`APINODE content schema catch-up is incomplete (${persistedSchema}/${requiredSchema}); preserving the previous fallback`);
+  }
+}
+
 async function writeJson(filePath, value) {
   await fs.promises.mkdir(path.dirname(filePath), { recursive: true });
   await fs.promises.writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
@@ -196,40 +233,48 @@ function normalizedEntry(item) {
 }
 
 async function buildNextSnapshot(options) {
-  const { apiBase, apiPath, dataDir, manifest } = options;
+  const { apiBase, apiPath, dataDir, manifest: configuredManifest } = options;
   const parentDir = path.dirname(dataDir);
   const nextDir = path.join(parentDir, `.gaming-infos-cache-next-${process.pid}-${Date.now()}`);
   await fs.promises.rm(nextDir, { recursive: true, force: true });
   await fs.promises.mkdir(nextDir, { recursive: true });
 
-  const rootData = await requestJson(apiUrl(apiBase, apiPath), options);
-  if (!Array.isArray(rootData) || !rootData.length) {
-    throw new Error('Gaming-infos root endpoint returned no games; refusing to replace the fallback cache');
-  }
-
-  const counts = {};
-  for (const [game, types] of Object.entries(manifest)) {
-    const meta = await requestJson(apiUrl(apiBase, apiPath, `/${encodeURIComponent(game)}/meta/${encodeURIComponent(game)}`), options);
-    if (!meta || Array.isArray(meta) || typeof meta !== 'object') throw new Error(`Invalid meta payload for ${game}`);
-    await writeJson(path.join(nextDir, game, 'meta.json'), meta);
-    counts[game] = { meta: 1 };
-
-    for (const type of types) {
-      const list = await requestJson(apiUrl(apiBase, apiPath, `/${encodeURIComponent(game)}/${encodeURIComponent(type)}`), options);
-      if (!Array.isArray(list)) throw new Error(`Expected an array for ${game}/${type}`);
-
-      const seen = new Set();
-      counts[game][type] = list.length;
-      for (const rawItem of list) {
-        const item = normalizedEntry(rawItem);
-        if (seen.has(item.slug)) throw new Error(`Duplicate slug ${item.slug} in ${game}/${type}`);
-        seen.add(item.slug);
-        await writeJson(path.join(nextDir, game, type, `${item.slug}.json`), item);
+  try {
+    const rootEnvelope = await requestJson(apiUrl(apiBase, apiPath), { ...options, rawEnvelope: true });
+    validateRootSyncState(rootEnvelope);
+    const rootData = rootEnvelope.data !== undefined ? rootEnvelope.data : rootEnvelope;
+    if (!Array.isArray(rootData) || !rootData.length) {
+      throw new Error('Gaming-infos root endpoint returned no games; refusing to replace the fallback cache');
+    }
+    const manifest = mergeDiscoveredManifest(rootData, configuredManifest);
+
+    const counts = {};
+    for (const [game, types] of Object.entries(manifest)) {
+      const meta = await requestJson(apiUrl(apiBase, apiPath, `/${encodeURIComponent(game)}/meta/${encodeURIComponent(game)}`), options);
+      if (!meta || Array.isArray(meta) || typeof meta !== 'object') throw new Error(`Invalid meta payload for ${game}`);
+      await writeJson(path.join(nextDir, game, 'meta.json'), meta);
+      counts[game] = { meta: 1 };
+
+      for (const type of types) {
+        const list = await requestJson(apiUrl(apiBase, apiPath, `/${encodeURIComponent(game)}/${encodeURIComponent(type)}`), options);
+        if (!Array.isArray(list)) throw new Error(`Expected an array for ${game}/${type}`);
+
+        const seen = new Set();
+        counts[game][type] = list.length;
+        for (const rawItem of list) {
+          const item = normalizedEntry(rawItem);
+          if (seen.has(item.slug)) throw new Error(`Duplicate slug ${item.slug} in ${game}/${type}`);
+          seen.add(item.slug);
+          await writeJson(path.join(nextDir, game, type, `${item.slug}.json`), item);
+        }
       }
     }
-  }
 
-  return { nextDir, rootGameCount: rootData.length, counts };
+    return { nextDir, rootGameCount: rootData.length, counts, manifest };
+  } catch (error) {
+    await fs.promises.rm(nextDir, { recursive: true, force: true }).catch(() => {});
+    throw error;
+  }
 }
 
 async function syncApiCache(options = {}) {
@@ -251,6 +296,7 @@ async function syncApiCache(options = {}) {
   try {
     const built = await buildNextSnapshot(requestOptions);
     nextDir = built.nextDir;
+    const effectiveManifest = built.manifest;
     const oldFiles = await walkFiles(dataDir);
     const newFiles = await walkFiles(nextDir);
     const oldHash = hashFiles(oldFiles);
@@ -264,19 +310,20 @@ async function syncApiCache(options = {}) {
         changed: false,
         contentHash: newHash,
         source: apiUrl(apiBase, apiPath),
-        games: Object.keys(manifest),
+        games: Object.keys(effectiveManifest),
         counts: built.counts,
         stats
       };
     }
 
     const cacheManifest = {
-      schemaVersion: 1,
+      schemaVersion: 2,
       source: apiUrl(apiBase, apiPath),
       syncedAt: new Date().toISOString(),
       contentHash: newHash,
       rootGameCount: built.rootGameCount,
-      games: Object.fromEntries(Object.entries(manifest).map(([game, types]) => [game, { types, counts: built.counts[game] }])),
+      autoDiscoveredTypes: true,
+      games: Object.fromEntries(Object.entries(effectiveManifest).map(([game, types]) => [game, { types, counts: built.counts[game] }])),
       stats
     };
     await writeJson(path.join(nextDir, '.cache-manifest.json'), cacheManifest);
@@ -288,7 +335,7 @@ async function syncApiCache(options = {}) {
       changed: true,
       contentHash: newHash,
       source: cacheManifest.source,
-      games: Object.keys(manifest),
+      games: Object.keys(effectiveManifest),
       counts: built.counts,
       stats
     };
@@ -313,6 +360,8 @@ if (require.main === module) {
 module.exports = {
   DEFAULT_MANIFEST,
   loadManifest,
+  mergeDiscoveredManifest,
+  validateRootSyncState,
   normalizedEntry,
   snapshotHash,
   syncApiCache

package/scripts/sync-game-code-cache.js

@@ -145,16 +145,51 @@ function validateCodeList(game, payload) {
   return payload;
 }
 
+function stableDirectorySnapshot(directory) {
+  const stable = JSON.parse(JSON.stringify(directory));
+  const updatedTimes = (stable.games || [])
+    .map((game) => new Date(game?.lastUpdatedAt || 0).getTime())
+    .filter((value) => Number.isFinite(value) && value > 0);
+
+  // APINODE's root `updatedAt` describes when the HTTP directory response was
+  // generated, so it changes every request. Keep a meaningful stable timestamp
+  // based on actual per-game data updates instead.
+  if (updatedTimes.length) stable.updatedAt = new Date(Math.max(...updatedTimes)).toISOString();
+  else delete stable.updatedAt;
+  return stable;
+}
+
+function stableCodeRow(row) {
+  const stable = JSON.parse(JSON.stringify(row));
+  if (stable.expiry && typeof stable.expiry === 'object' && !Array.isArray(stable.expiry)) {
+    // These values are calculated from Date.now() on every API request. The
+    // fallback retains expiresAt/local/expired, while consumers can calculate
+    // a live countdown themselves when needed.
+    delete stable.expiry.expiresInSeconds;
+    delete stable.expiry.countdown;
+  }
+  return stable;
+}
+
+function stableCodePayload(payload) {
+  const stable = {};
+  for (const bucket of ['Active', 'Expired', 'Unknown']) {
+    if (Array.isArray(payload[bucket])) stable[bucket] = payload[bucket].map(stableCodeRow);
+  }
+  return stable;
+}
+
 async function buildNextSnapshot(options) {
   const { apiBase, apiPath, dataDir } = options;
   const nextDir = path.join(path.dirname(dataDir), `.game-codes-cache-next-${process.pid}-${Date.now()}`);
   await fs.promises.rm(nextDir, { recursive: true, force: true });
   await fs.promises.mkdir(nextDir, { recursive: true });
 
-  const directory = await requestJson(apiUrl(apiBase, apiPath), options);
-  if (!Array.isArray(directory.games) || !directory.games.length) {
+  const rawDirectory = await requestJson(apiUrl(apiBase, apiPath), options);
+  if (!Array.isArray(rawDirectory.games) || !rawDirectory.games.length) {
     throw new Error('Game code directory returned no games; refusing to replace fallback cache');
   }
+  const directory = stableDirectorySnapshot(rawDirectory);
   await writeJson(path.join(nextDir, 'directory.json'), directory);
 
   // /status is cache-only on APINODE and does not trigger source website requests.
@@ -167,10 +202,11 @@ async function buildNextSnapshot(options) {
   const delayMs = numberOption(options.delayMs ?? process.env.GAME_CODES_CACHE_GAME_DELAY_MS, 150, 0, 10000);
   for (let i = 0; i < directory.games.length; i += 1) {
     const game = gameSlug(directory.games[i]);
-    const payload = validateCodeList(
+    const rawPayload = validateCodeList(
       game,
       await requestJson(apiUrl(apiBase, apiPath, `/${encodeURIComponent(game)}`, { includeUnknown: 'true' }), options)
     );
+    const payload = stableCodePayload(rawPayload);
     await writeJson(path.join(nextDir, 'games', `${game}.json`), payload);
     counts[game] = {
       active: payload.Active.length,
@@ -214,6 +250,7 @@ async function syncGameCodeCache(options = {}) {
       gameCount: built.directory.games.length,
       counts: built.counts,
       statusIsCacheOnly: true,
+      volatileFieldsRemoved: ['directory.updatedAt(request-time)', 'expiry.expiresInSeconds', 'expiry.countdown'],
       stats
     };
     await writeJson(path.join(nextDir, '.cache-manifest.json'), manifest);
@@ -239,6 +276,8 @@ if (require.main === module) {
 }
 
 module.exports = {
+  stableDirectorySnapshot,
+  stableCodePayload,
   syncGameCodeCache,
   validateCodeList
 };