@nekosuneprojects/gaming-infos 2.2.0 → 2.4.0

package/.github/workflows/sync-api-cache.yml

@@ -3,8 +3,9 @@ name: Sync APINODE fallback caches
 on:
   workflow_dispatch:
   schedule:
-    # Daily at 03:23 UTC. GitHub Actions cron uses UTC.
-    - cron: "23 3 * * *"
+    # Hourly change-watch at minute 23. The mirror hashes API content and only
+    # commits when APINODE actually added, changed, repaired or removed data.
+    - cron: "23 * * * *"
   push:
     branches:
       - main

package/CACHE_SYNC.md

@@ -9,13 +9,36 @@ The repository keeps **two independent last-good fallback snapshots** synchroniz
 
 ## Schedule
 
-The GitHub Action runs **once every day at 03:23 UTC** and can also be started manually with `workflow_dispatch`.
+The GitHub Action runs an **hourly APINODE change-watch at minute 23** and can also be started manually with `workflow_dispatch`.
 
-It also runs when the cache implementation itself changes so a newly deployed cache format can be populated immediately.
+The mirror uses full content hashes, so an hourly check with no stable API data changes creates **no commit**. If APINODE adds, updates, repairs, moves, or removes a game-info file or game-code record, the next successful hourly pass mirrors that change into this repository.
 
-## Mirrored gaming-infos datasets
+## Gaming Infos dataset discovery
 
-| Game | API type(s) |
+Gaming Infos cache schema 2 no longer depends only on a hard-coded game manifest.
+
+The mirror first requests:
+
+```http
+GET /v5/games/api/gaming-infos
+```
+
+Modern APINODE responses expose each game's stable `slug` and dataset `types`, for example:
+
+```json
+{
+  "slug": "codblackops2",
+  "types": ["characters", "npcs", "maps"]
+}
+```
+
+The mirror merges those declarations into its safety/baseline manifest and then fetches every discovered game/type. This means the full Call of Duty catalog, and future public Gaming Infos games/types, can propagate into the repository without adding one hard-coded mirror entry per title.
+
+The built-in baseline remains for compatibility with older APINODE deployments and can still be replaced explicitly with `GAMING_INFOS_CACHE_MANIFEST_JSON`.
+
+Current important datasets include:
+
+| Game / family | API type(s) |
 |---|---|
 | VRChat | `players`, `groups`, `worlds`, `avatars` |
 | Genshin Impact | `characters` |
@@ -23,14 +46,17 @@ It also runs when the cache implementation itself changes so a newly deployed ca
 | Neverness to Everness | `characters` |
 | Wuthering Waves | `characters` (Resonators) |
 | Warframe | `characters` (Warframes) |
-| Fortnite | `characters` (current/released Battle Royale characters) |
+| Fortnite | `characters` = released Outfits/skins, `npcs` = Battle Royale NPCs, `maps` = Named Locations/maps |
+| Call of Duty mainline | `characters`, `npcs`, `maps` per title, auto-discovered from APINODE |
 | Zenless Zone Zero | `characters` (Agents) |
 | Tower of Fantasy | `characters` (Simulacra) |
 | Arknights: Endfield | `characters` (Operators) |
 
+Call of Duty covers mainline slugs from `cod2003` through `codblackops7`, plus `codmodernwarfare4`. The 2026 MW4 dataset is restricted upstream to official Activision beta/public announcement information; the fallback never expands that policy by scraping separate unofficial data.
+
 ## Mirrored Game Codes endpoints
 
-The daily mirror also caches:
+The hourly mirror also caches:
 
 ```text
 GET /v5/games/api/codes
@@ -50,21 +76,7 @@ The per-game request uses `includeUnknown=true`, so the fallback contains all th
 }
 ```
 
-The mirror does not call every `/:game/:code` endpoint. `GameCode(game, code)` can search the full cached per-game snapshot during an outage, which keeps the daily request count low.
-
-Game-code fallback layout:
-
-```text
-data/game-codes/
-├── directory.json
-├── status.json
-├── .cache-manifest.json
-└── games/
-    ├── fortnite.json
-    ├── warframe.json
-    ├── genshin-impact.json
-    └── ...
-```
+The repository does not store ticking `expiresInSeconds` / `countdown` values as authoritative file changes. Those values are rehydrated from stable `expiresAt` dates when the package reads a local fallback, preventing pointless hourly commits.
 
 ## Atomic synchronization / deletion behavior
 
@@ -72,59 +84,78 @@ Each cache is authoritative only **after its complete API download succeeds**.
 
 For Gaming Infos:
 
-1. Temporarily preserve `data/game-codes/` outside the gaming-info snapshot.
-2. Fetch the root gaming-infos endpoint.
-3. Fetch every configured game's meta endpoint.
-4. Fetch every configured type-list endpoint.
-5. Validate every response and entry slug.
-6. Build a completely separate temporary snapshot.
-7. Atomically replace the gaming-info `data/` snapshot.
-8. Restore the previous game-code fallback before the code phase begins.
+1. Temporarily preserve `data/game-codes/` outside the Gaming Infos snapshot.
+2. Fetch the root Gaming Infos endpoint.
+3. Merge valid root `slug` + `types` declarations into the effective manifest.
+4. Fetch every effective game's meta endpoint.
+5. Fetch every discovered/configured type-list endpoint.
+6. Validate every response and entity slug.
+7. Build a completely separate temporary snapshot.
+8. Atomically replace the Gaming Infos `data/` snapshot only after every required request succeeds.
+9. Restore the previous Game Codes fallback before the code phase begins.
 
 For Game Codes:
 
 1. Fetch `/codes` and validate its game directory.
 2. Fetch cache-only `/codes/status`.
 3. Fetch every listed game's full `Active` / `Expired` / `Unknown` snapshot.
-4. Build a separate temporary `data/game-codes/` tree.
-5. Only after every game succeeds, atomically replace the old game-code snapshot.
+4. Normalize volatile request-time/countdown values.
+5. Build a separate temporary `data/game-codes/` tree.
+6. Only after every game succeeds, atomically replace the old Game Codes snapshot.
 
-Because successful API snapshots are authoritative, **adds, changes and removals are mirrored**. If APINODE removes an entry/code/game, the corresponding fallback disappears on the next successful daily sync.
+Because successful API snapshots are authoritative, **adds, changes and removals are mirrored**. If APINODE moves an old Fortnite record between datasets, or removes/changes a Call of Duty entity, the next fully successful mirror reproduces that structure in the fallback.
 
 If APINODE is down, times out, returns 429/5xx, or one required endpoint fails halfway through, that cache is **not replaced**. The previous last-good fallback remains available.
 
-## Package API
+## APINODE synchronization / repair propagation
+
+APINODE performs content synchronization and data-quality repair before this repository consumes the public API. That includes bad Game Code cleanup, image repair, Fortnite dataset separation, and the database-backed Call of Duty public-data sync.
+
+```text
+APINODE source refresh / repair
+        ↓
+Gaming Infos + Game Codes API
+        ↓
+hourly GitHub change-watch
+        ↓
+repository data/ fallback
+```
 
-Gaming Infos functions remain available:
+## Package API
 
 ```js
 const info = require('@nekosuneprojects/gaming-infos');
 
-await info.Games();
+// Fortnite
+await info.List('fortnite', 'characters');
+await info.List('fortnite', 'npcs');
+await info.List('fortnite', 'maps');
+
+// Call of Duty
+await info.List('codblackops2', 'characters');
+await info.List('codblackops2', 'npcs');
+await info.List('codblackops2', 'maps');
+await info.List('codmodernwarfare4', 'maps');
+
+await info.Characters('codblackops2', 'character-slug');
+await info.NPCs('codblackops2', 'npc-slug');
+await info.Maps('codblackops2', 'map-slug');
+
+// Other Gaming Infos
 await info.List('vrchat', 'avatars');
 await info.Characters('wutheringwaves', 'cartethyia');
-```
-
-Game Codes helpers use live APINODE first and the daily fallback second:
 
-```js
-await info.Codes();                    // GET /v5/games/api/codes
-await info.CodesStatus();              // GET /v5/games/api/codes/status
-await info.GameCodes('fortnite');      // Active + Expired
+// Game Codes
+await info.Codes();
+await info.CodesStatus();
 await info.GameCodes('fortnite', { includeUnknown: true });
 await info.GameCode('fortnite', 'NEKOSUNEVR');
-await info.CodeCacheInfo();
 ```
 
-Per-game fallback filtering is supported for `category` and `claimType` as well.
-
 ## Commands
 
 ```bash
-# Test both atomic cache systems
 npm run test:all-cache
-
-# Mirror both Gaming Infos and Game Codes
 npm run sync:cache
 
 # Debug individually
@@ -147,15 +178,16 @@ Useful variables:
 | `GAMING_INFOS_API_BASE` | `https://api.nekosunevr.co.uk` | APINODE host used by both caches |
 | `GAMING_INFOS_API_PATH` | `/v5/games/api/gaming-infos` | Gaming Infos path |
 | `GAME_CODES_API_PATH` | `/v5/games/api/codes` | Game Codes path |
+| `GAMING_INFOS_CACHE_MANIFEST_JSON` | baseline + root discovery | Optional explicit baseline manifest |
 | `GAMING_INFOS_CACHE_TIMEOUT_MS` | `15000` | Gaming Infos per-request timeout |
 | `GAMING_INFOS_CACHE_RETRIES` | `2` | Gaming Infos retry count |
-| `GAME_CODES_CACHE_TIMEOUT_MS` | `15000` | Game Codes per-request timeout |
+| `GAME_CODES_CACHE_TIMEOUT_MS` | `15000` | Game Codes sync request timeout |
 | `GAME_CODES_CACHE_RETRIES` | `2` | Game Codes retry count |
 | `GAME_CODES_CACHE_GAME_DELAY_MS` | `150` | Small delay between game-list requests |
 
 ## Runtime fallback behavior
 
-The package does **not** use the cache instead of live data. It remains API-first:
+The package remains API-first:
 
 ```text
 application
@@ -165,8 +197,6 @@ live APINODE
    └─ unavailable/error → last-good bundled fallback
 ```
 
-A successful changed Gaming Infos snapshot records `data/.cache-manifest.json`. Game Codes records its own `data/game-codes/.cache-manifest.json`. Both include source URL, content hash, counts, synchronization time and add/change/remove statistics.
-
-The hash comparison ignores manifest timestamps, so an unchanged API dataset does not create a pointless daily commit.
+A successful changed Gaming Infos snapshot records `data/.cache-manifest.json` with schema version 2, its effective game/type manifest, content hash, counts and add/change/remove statistics. Game Codes records `data/game-codes/.cache-manifest.json` separately. The hash comparison ignores manifest timestamps and other explicitly volatile values.
 
-Note: npm releases are immutable. Repository fallback files update daily, but an already-installed npm version keeps the bundled snapshot from that package release until upgraded. Live API reads still remain current whenever APINODE is available.
+Note: npm releases are immutable. Repository fallback files update automatically, but an already-installed npm version keeps the snapshot bundled with that release until upgraded. Live API reads still remain current whenever APINODE is available.

package/CHANGELOG.md

@@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+## 2.4.0 - 2026-08-24
+
+### Added
+- Added mainline Call of Duty Gaming Infos coverage from `cod2003` (Call of Duty 2003) through `codblackops7`, plus `codmodernwarfare4` for official 2026 beta/public announcement data.
+- Added per-title Call of Duty `characters`, `npcs`, and `maps` datasets. `characters` is intended for playable/main characters, protagonists, Operators and Specialists; `npcs` contains other campaign/game character records; `maps` contains public multiplayer/Zombies/Warzone/map/mission records.
+- Added Call of Duty examples and the complete supported slug list to `README.md`.
+- Added mirror smoke coverage for APINODE root `slug`/`types` auto-discovery.
+
+### Changed
+- Gaming Infos fallback synchronization now auto-discovers games and dataset types from APINODE's root response instead of requiring every new game/type to be hard-coded into the package mirror.
+- Gaming Infos cache manifests now use schema version 2 and record that dataset types were auto-discovered.
+- Updated package metadata and keywords for Call of Duty, Modern Warfare, Black Ops, characters, NPCs and maps.
+- Bumped the package source version to `2.4.0`.
+
+### Data policy
+- Historical Call of Duty data is limited to public released-game sources. Cut, unused, cancelled, unofficial unreleased, non-canon, prototype/concept and image-only categories are excluded.
+- Modern Warfare 4 data is limited to official Activision beta/public announcement information while the title is pre-release; leaks/datamines are not mirrored.
+
+## 2.3.0 - 2026-08-24
+
+### Added
+- Added `NPCs(game, name)` and `Maps(game, name)` helpers.
+- Added dedicated Fortnite `npcs` and `maps` datasets alongside `characters`.
+- Fortnite `characters` now means released Outfit/skin records rather than Battle Royale NPCs.
+
+### Changed
+- The fallback mirror now fetches `fortnite/characters`, `fortnite/npcs`, and `fortnite/maps` independently from APINODE.
+- The repository APINODE change-watch runs hourly and only commits real content changes.
+- Volatile Game Code countdown fields are excluded from fallback hashes and are rehydrated from `expiresAt` when the local fallback is read.
+- Updated package metadata for Fortnite skins, NPCs, and maps.
+
 ## 2.2.0 - 2026-08-24
 
 ### Added
@@ -22,12 +53,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 - `npm run sync:cache` now mirrors both Gaming Infos and Game Codes.
-- The automatic cache workflow now runs once daily at 03:23 UTC instead of every six hours.
+- The automatic cache workflow was changed to a daily schedule in this release and was subsequently upgraded to an hourly change-watch in 2.3.0.
 - Gaming Infos and Game Codes are mirrored as independent atomic snapshots so a failure in one cache cannot destroy the other cache's last-good data.
-- Successful mirror runs now synchronize additions, updates, and removals from APINODE while failed or partial runs preserve the previous fallback snapshot.
+- Successful mirror runs synchronize additions, updates, and removals from APINODE while failed or partial runs preserve the previous fallback snapshot.
 - Local fallback entities expose stable slugs so offline lookups match live API behavior more closely.
 - Expanded the package description and keywords for the new games, VRChat avatars, and redeem/creator-code support.
-- Reworked `README.md` to document the full supported-game matrix, API-first fallback behavior, Game Codes API helpers, daily sync workflow, cache commands, configuration, and examples.
+- Reworked `README.md` to document the full supported-game matrix, API-first fallback behavior, Game Codes API helpers, sync workflow, cache commands, configuration, and examples.
 
 ## 2.1.0 - 2026-08-02