@nekosuneprojects/gaming-infos 2.1.0 → 2.4.0

package/data/warframe/meta.json

@@ -0,0 +1,14 @@
+{
+  "name": "Warframe",
+  "title": "Cooperative science-fiction action game by Digital Extremes.",
+  "engine": "Evolution",
+  "Platform": "Windows, PlayStation, Xbox, Nintendo Switch, iOS, Android",
+  "Release date": "March 25, 2013",
+  "Genre": "Action RPG, Third-person shooter, Online co-op",
+  "developers": "Digital Extremes",
+  "publisher": "Digital Extremes",
+  "aliases": "WF, Warframe",
+  "image": "https://www.warframe.com/favicon.ico",
+  "description": "Online action game built around collectible Warframes, weapons, companions and the Origin System.",
+  "url": "https://www.warframe.com/"
+}

package/data/wutheringwaves/meta.json

@@ -0,0 +1,14 @@
+{
+  "name": "Wuthering Waves",
+  "title": "Open-world action RPG by Kuro Games.",
+  "engine": "Unreal Engine 4",
+  "Platform": "Windows, PlayStation 5, iOS, Android, macOS",
+  "Release date": "May 22, 2024",
+  "Genre": "Action RPG, Open World, Gacha",
+  "developers": "Kuro Games",
+  "publisher": "Kuro Games",
+  "aliases": "WuWa, Wuthering Waves",
+  "image": "https://wutheringwaves.kurogames.com/favicon.ico",
+  "description": "Open-world action RPG featuring playable Resonators with distinct attributes and weapons.",
+  "url": "https://wutheringwaves.kurogames.com/"
+}

package/data/zenlesszonezero/meta.json

@@ -0,0 +1,14 @@
+{
+  "name": "Zenless Zone Zero",
+  "title": "Urban fantasy action RPG by HoYoverse.",
+  "engine": "Unity",
+  "Platform": "Windows, PlayStation 5, Xbox Series X/S, iOS, Android",
+  "Release date": "July 4, 2024",
+  "Genre": "Action RPG, Urban Fantasy, Gacha",
+  "developers": "miHoYo",
+  "publisher": "HoYoverse",
+  "aliases": "ZZZ, Zenless Zone Zero",
+  "image": "https://zenless.hoyoverse.com/favicon.ico",
+  "description": "Action RPG featuring playable Agents organized by faction, attribute and specialty.",
+  "url": "https://zenless.hoyoverse.com/"
+}

package/gamecodes.js

@@ -0,0 +1,204 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const DATA_DIR = path.join(__dirname, 'data', 'game-codes');
+const DEFAULT_API_BASE = 'https://api.nekosunevr.co.uk';
+const DEFAULT_API_PATH = '/v5/games/api/codes';
+const DEFAULT_TIMEOUT_MS = 4000;
+
+function apiBase() {
+  return String(process.env.GAMING_INFOS_API_BASE || DEFAULT_API_BASE).replace(/\/+$/, '');
+}
+
+function apiPath() {
+  const raw = String(process.env.GAME_CODES_API_PATH || DEFAULT_API_PATH).trim();
+  return `/${raw.replace(/^\/+|\/+$/g, '')}`;
+}
+
+function apiDisabled() {
+  const raw = String(process.env.GAMING_INFOS_DISABLE_API || '').toLowerCase();
+  return raw === '1' || raw === 'true';
+}
+
+function timeoutMs() {
+  const raw = Number(process.env.GAMING_INFOS_TIMEOUT_MS);
+  return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_TIMEOUT_MS;
+}
+
+async function apiGet(suffix = '', query = {}) {
+  if (apiDisabled() || typeof fetch !== 'function') return null;
+
+  const url = new URL(`${apiBase()}${apiPath()}${suffix}`);
+  for (const [key, value] of Object.entries(query)) {
+    if (value !== undefined && value !== null && value !== '') url.searchParams.set(key, String(value));
+  }
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs());
+  try {
+    const response = await fetch(url, { signal: controller.signal, headers: { Accept: 'application/json' } });
+    if (!response.ok) return null;
+    const body = await response.json();
+    if (!body || body.success === false) return null;
+    return body;
+  } catch (_) {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function readJson(filePath) {
+  return JSON.parse(await fs.promises.readFile(filePath, 'utf8'));
+}
+
+function safeFallbackPath(fileName) {
+  const filePath = path.resolve(DATA_DIR, fileName);
+  const root = `${path.resolve(DATA_DIR)}${path.sep}`;
+  return filePath.startsWith(root) ? filePath : null;
+}
+
+async function readFallback(fileName) {
+  const filePath = safeFallbackPath(fileName);
+  if (!filePath || !fs.existsSync(filePath)) return null;
+  try {
+    return await readJson(filePath);
+  } catch (_) {
+    return null;
+  }
+}
+
+function normalizeGame(game) {
+  const slug = String(game || '').trim().toLowerCase();
+  return /^[a-z0-9][a-z0-9-]*$/.test(slug) ? slug : null;
+}
+
+function normalizeCode(code) {
+  return String(code || '').trim().toLowerCase();
+}
+
+async function resolveCachedGame(game) {
+  const slug = normalizeGame(game);
+  if (!slug) return null;
+  if (await readFallback(path.join('games', `${slug}.json`))) return slug;
+
+  const cachedDirectory = await readFallback('directory.json');
+  const aliasTarget = cachedDirectory?.aliases?.[slug];
+  const canonical = normalizeGame(aliasTarget);
+  if (canonical && await readFallback(path.join('games', `${canonical}.json`))) return canonical;
+  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);
+  const category = options.category ? String(options.category).toLowerCase() : null;
+  const claimType = options.claimType ? String(options.claimType).toLowerCase() : null;
+
+  const matches = (entry) => {
+    if (!entry || typeof entry !== 'object') return false;
+    if (category && String(entry.category || '').toLowerCase() !== category) return false;
+    if (claimType && String(entry.claimType || '').toLowerCase() !== claimType) return false;
+    return true;
+  };
+
+  const hydrate = (rows) => Array.isArray(rows) ? rows.filter(matches).map(hydrateCachedExpiry) : [];
+  const result = {
+    Active: hydrate(data.Active),
+    Expired: hydrate(data.Expired)
+  };
+  if (includeUnknown) result.Unknown = hydrate(data.Unknown);
+  return result;
+}
+
+async function directory() {
+  const live = await apiGet('');
+  if (live) return live;
+  const cached = await readFallback('directory.json');
+  return cached || { success: false, error: 'Game code directory is unavailable and no fallback cache exists.' };
+}
+
+async function status() {
+  const live = await apiGet('/status');
+  if (live) return live.data !== undefined ? live.data : live;
+  const cached = await readFallback('status.json');
+  return cached || { error: 'Game code status is unavailable and no fallback cache exists.' };
+}
+
+async function gameCodes(game, options = {}) {
+  if (!game) return { error: 'game is required' };
+  const requested = normalizeGame(game);
+  if (!requested) return { error: 'invalid game slug' };
+  const query = {
+    timezone: options.timezone,
+    category: options.category,
+    claimType: options.claimType,
+    includeUnknown: options.includeUnknown ? 'true' : undefined
+  };
+  const live = await apiGet(`/${encodeURIComponent(requested)}`, query);
+  if (live) return live;
+
+  const cachedGame = await resolveCachedGame(requested);
+  const cached = cachedGame ? await readFallback(path.join('games', `${cachedGame}.json`)) : null;
+  if (!cached) return { error: `No cached game codes found for "${game}".` };
+  return filterCachedList(cached, options);
+}
+
+async function gameCode(game, code, options = {}) {
+  if (!game || !code) return { error: 'game and code are both required' };
+  const requested = normalizeGame(game);
+  if (!requested) return { error: 'invalid game slug' };
+  const codeValue = String(code).trim();
+  const live = await apiGet(`/${encodeURIComponent(requested)}/${encodeURIComponent(codeValue)}`, { timezone: options.timezone });
+  if (live) return live.data !== undefined ? live.data : live;
+
+  const cachedGame = await resolveCachedGame(requested);
+  const cached = cachedGame ? await readFallback(path.join('games', `${cachedGame}.json`)) : null;
+  if (!cached) return { error: `No cached game codes found for "${game}".` };
+  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 hydrateCachedExpiry(entry);
+    }
+  }
+  return { error: `Code "${code}" not found for game "${game}".` };
+}
+
+async function cacheInfo() {
+  return readFallback('.cache-manifest.json');
+}
+
+module.exports = {
+  Codes: () => directory(),
+  CodesStatus: () => status(),
+  GameCodes: (game, options) => gameCodes(game, options),
+  GameCode: (game, code, options) => gameCode(game, code, options),
+  CodeCacheInfo: () => cacheInfo()
+};

package/index.js

@@ -1,5 +1,6 @@
 const fs = require('fs');
 const path = require('path');
+const gameCodes = require('./gamecodes');
 
 const DATA_DIR = path.join(__dirname, 'data');
 const DEFAULT_API_BASE = 'https://api.nekosunevr.co.uk';
@@ -23,9 +24,15 @@ function timeoutMs() {
   return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_TIMEOUT_MS;
 }
 
+function withLocalSlug(filePath, data) {
+  if (!data || Array.isArray(data) || typeof data !== 'object' || data.slug) return data;
+  return { ...data, slug: path.basename(filePath, '.json').toLowerCase() };
+}
+
 // 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 only the offline fallback for when the API can't be reached.
+// 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;
 
@@ -53,7 +60,7 @@ async function loadLocal(game, type, name) {
   }
 
   const raw = await fs.promises.readFile(filePath, 'utf8');
-  return JSON.parse(raw);
+  return withLocalSlug(filePath, JSON.parse(raw));
 }
 
 async function fetchListFromApi(game, type) {
@@ -81,12 +88,12 @@ async function listLocal(game, type) {
   const dir = path.join(DATA_DIR, game.toLowerCase(), type);
   if (!fs.existsSync(dir)) return [];
 
-  const files = await fs.promises.readdir(dir);
+  const files = (await fs.promises.readdir(dir)).filter((file) => file.endsWith('.json')).sort((a, b) => a.localeCompare(b));
   const items = [];
   for (const file of files) {
-    if (!file.endsWith('.json')) continue;
-    const raw = await fs.promises.readFile(path.join(dir, file), 'utf8');
-    items.push(JSON.parse(raw));
+    const filePath = path.join(dir, file);
+    const raw = await fs.promises.readFile(filePath, 'utf8');
+    items.push(withLocalSlug(filePath, JSON.parse(raw)));
   }
   return items;
 }
@@ -131,7 +138,7 @@ async function listGamesLocal() {
   const entries = await fs.promises.readdir(DATA_DIR, { withFileTypes: true });
   const games = [];
   for (const entry of entries) {
-    if (!entry.isDirectory()) continue;
+    if (!entry.isDirectory() || entry.name.startsWith('.') || entry.name === 'game-codes') continue;
     const metaPath = path.join(DATA_DIR, entry.name, 'meta.json');
     if (!fs.existsSync(metaPath)) continue;
     const raw = await fs.promises.readFile(metaPath, 'utf8');
@@ -185,23 +192,35 @@ async function loadGameMeta(game) {
   }
 }
 
+async function cacheInfo() {
+  try {
+    const filePath = path.join(DATA_DIR, '.cache-manifest.json');
+    if (!fs.existsSync(filePath)) return null;
+    return JSON.parse(await fs.promises.readFile(filePath, 'utf8'));
+  } catch (err) {
+    return { error: err.message };
+  }
+}
+
 module.exports = {
-  // All supported games, e.g. Games() -> [data/vrchat/meta.json, data/genshinimpact/meta.json, ...]
   Games: () => games(),
-
-  // Game-level info, e.g. Game('vrchat') -> data/vrchat/meta.json
   Game: (game) => loadGameMeta(game),
-
-  // Entity lookups, scoped per game: Worlds('vrchat', 'theblackcat')
   Worlds: (game, name) => load(game, 'worlds', name),
   Groups: (game, name) => load(game, 'groups', name),
   Players: (game, name) => load(game, 'players', name),
+  Avatars: (game, name) => load(game, 'avatars', name),
   Characters: (game, name) => load(game, 'characters', name),
-
-  // Generic escape hatch for entity types not covered above
-  // (new games may need types other than worlds/groups/players/characters)
+  NPCs: (game, name) => load(game, 'npcs', name),
+  Maps: (game, name) => load(game, 'maps', name),
   Get: (game, type, name) => load(game, type, name),
-
-  // Full listing of every entry of a given type for a game, e.g. List('genshinimpact', 'characters')
   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 hourly mirrored data/game-codes snapshot.
+  Codes: gameCodes.Codes,
+  CodesStatus: gameCodes.CodesStatus,
+  GameCodes: gameCodes.GameCodes,
+  GameCode: gameCodes.GameCode,
+  CodeCacheInfo: gameCodes.CodeCacheInfo
 };

package/package.json

@@ -1,12 +1,20 @@
 {
     "name": "@nekosuneprojects/gaming-infos",
-    "version": "2.1.0",
-    "description": "Multi-game data loader (VRChat, Genshin Impact, and more to come) for worlds, groups, players, and characters. Fetches live from the NekoSuneVR V5 API with local JSON fallback.",
+    "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": {
         "node": ">=18"
     },
+    "scripts": {
+        "sync:cache": "node scripts/sync-all-cache.js",
+        "sync:gaming-infos-cache": "node scripts/sync-gaming-info-cache.js",
+        "sync:game-codes-cache": "node scripts/sync-game-code-cache.js",
+        "test:cache-sync": "node scripts/cache-sync-smoke.js",
+        "test:game-code-cache": "node scripts/game-code-cache-smoke.js",
+        "test:all-cache": "npm run test:cache-sync && npm run test:game-code-cache"
+    },
     "repository": {
         "type": "git",
         "url": "https://github.com/NekoSuneProjects/gaming-infos.git"
@@ -18,12 +26,34 @@
     "keywords": [
         "gaming",
         "infos",
+        "game-codes",
+        "redeem-codes",
+        "creator-codes",
         "vrchat",
         "genshin-impact",
+        "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",
         "worlds",
         "groups",
         "players",
-        "characters"
+        "avatars",
+        "characters",
+        "npcs",
+        "maps"
     ],
     "author": "NekoSuneVR",
     "license": "MIT"

package/scripts/cache-sync-smoke.js

@@ -0,0 +1,139 @@
+'use strict';
+
+const assert = require('assert');
+const fs = require('fs');
+const http = require('http');
+const os = require('os');
+const path = require('path');
+const {
+  DEFAULT_MANIFEST,
+  mergeDiscoveredManifest,
+  validateRootSyncState,
+  syncApiCache
+} = require('./sync-api-cache');
+
+function json(res, status, body) {
+  const payload = JSON.stringify(body);
+  res.writeHead(status, { 'content-type': 'application/json', 'content-length': Buffer.byteLength(payload) });
+  res.end(payload);
+}
+
+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;
+  let characters = [
+    { slug: 'alpha', name: 'Alpha', value: 1 },
+    { slug: 'beta', name: 'Beta', value: 2 }
+  ];
+
+  const server = http.createServer((req, res) => {
+    if (req.url === '/v5/games/api/gaming-infos') {
+      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: { 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' });
+      return json(res, 200, { success: true, data: characters });
+    }
+    return json(res, 404, { success: false, error: 'not found' });
+  });
+
+  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+  const address = server.address();
+  const apiBase = `http://127.0.0.1:${address.port}`;
+  const options = {
+    apiBase,
+    apiPath: '/v5/games/api/gaming-infos',
+    dataDir,
+    manifest: { testgame: ['characters'] },
+    retries: 0,
+    timeoutMs: 3000
+  };
+
+  try {
+    const first = await syncApiCache(options);
+    assert.strictEqual(first.changed, true);
+    assert.ok(fs.existsSync(path.join(dataDir, 'testgame', 'characters', 'alpha.json')));
+    assert.ok(fs.existsSync(path.join(dataDir, 'testgame', 'characters', 'beta.json')));
+
+    characters = [
+      { slug: 'alpha', name: 'Alpha', value: 99 },
+      { slug: 'gamma', name: 'Gamma', value: 3 }
+    ];
+    const second = await syncApiCache(options);
+    assert.strictEqual(second.changed, true);
+    assert.strictEqual(second.stats.added, 1);
+    assert.strictEqual(second.stats.removed, 1);
+    assert.ok(second.stats.changed >= 1);
+    assert.strictEqual(JSON.parse(await fs.promises.readFile(path.join(dataDir, 'testgame', 'characters', 'alpha.json'), 'utf8')).value, 99);
+    assert.ok(fs.existsSync(path.join(dataDir, 'testgame', 'characters', 'gamma.json')));
+    assert.ok(!fs.existsSync(path.join(dataDir, 'testgame', 'characters', 'beta.json')));
+
+    const beforeOutage = await fs.promises.readFile(path.join(dataDir, 'testgame', 'characters', 'alpha.json'), 'utf8');
+    failCharacters = true;
+    let failed = false;
+    try {
+      await syncApiCache(options);
+    } catch (_) {
+      failed = true;
+    }
+    assert.strictEqual(failed, true, 'partial API outage must fail the sync');
+    assert.strictEqual(await fs.promises.readFile(path.join(dataDir, 'testgame', 'characters', 'alpha.json'), 'utf8'), beforeOutage);
+    assert.ok(fs.existsSync(path.join(dataDir, 'testgame', 'characters', 'gamma.json')), 'last good snapshot must survive an outage');
+
+    console.log('gaming-infos cache sync smoke test passed');
+  } finally {
+    await new Promise((resolve) => server.close(resolve));
+    await fs.promises.rm(root, { recursive: true, force: true });
+  }
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exitCode = 1;
+});

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

@@ -0,0 +1,125 @@
+'use strict';
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { syncGameCodeCache } = require('./sync-game-code-cache');
+
+function response(body, status = 200) {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    async json() { return body; }
+  };
+}
+
+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: 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' },
+    // 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', 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;
+  global.fetch = async (input) => {
+    const url = new URL(String(input));
+    if (phase === 3 && url.pathname.endsWith('/beta')) return response({ success: false }, 503);
+    if (url.pathname.endsWith('/codes')) return response(directory());
+    if (url.pathname.endsWith('/codes/status')) return response({ success: true, data: { generic: { ok: true }, specialized: [] } });
+    const game = url.pathname.split('/').pop();
+    if (datasets()[game]) return response(datasets()[game]);
+    return response({ success: false }, 404);
+  };
+
+  try {
+    const first = await syncGameCodeCache({ dataDir, apiBase: 'https://example.test', apiPath: '/v5/games/api/codes', retries: 0, delayMs: 0 });
+    assert.equal(first.success, true);
+    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(
+      () => syncGameCodeCache({ dataDir, apiBase: 'https://example.test', apiPath: '/v5/games/api/codes', retries: 0, delayMs: 0 }),
+      /503/
+    );
+    const afterFailure = await fs.promises.readFile(path.join(dataDir, 'games', 'alpha.json'), 'utf8');
+    assert.equal(afterFailure, beforeFailure, 'failed partial sync must preserve last-good code cache');
+
+    const status = JSON.parse(await fs.promises.readFile(path.join(dataDir, 'status.json'), 'utf8'));
+    assert.equal(status.generic.ok, true);
+    console.log('game-code-cache smoke test passed');
+  } finally {
+    global.fetch = originalFetch;
+    await fs.promises.rm(temp, { recursive: true, force: true });
+  }
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exitCode = 1;
+});