@nekosuneprojects/gaming-infos 2.1.0 → 2.4.0

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

@@ -0,0 +1,73 @@
+name: Sync APINODE fallback caches
+
+on:
+  workflow_dispatch:
+  schedule:
+    # 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
+    paths:
+      - "scripts/sync-api-cache.js"
+      - "scripts/sync-gaming-info-cache.js"
+      - "scripts/sync-game-code-cache.js"
+      - "scripts/sync-all-cache.js"
+      - "scripts/cache-sync-smoke.js"
+      - "scripts/game-code-cache-smoke.js"
+      - "gamecodes.js"
+      - "index.js"
+      - "package.json"
+      - "CACHE_SYNC.md"
+      - ".github/workflows/sync-api-cache.yml"
+
+permissions:
+  contents: write
+
+concurrency:
+  group: gaming-infos-api-cache
+  cancel-in-progress: false
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Use Node.js 22
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Test atomic cache behavior
+        run: npm run test:all-cache
+
+      - name: Mirror APINODE gaming-infos and game codes
+        run: npm run sync:cache
+        env:
+          GAMING_INFOS_API_BASE: https://api.nekosunevr.co.uk
+          GAMING_INFOS_API_PATH: /v5/games/api/gaming-infos
+          GAME_CODES_API_PATH: /v5/games/api/codes
+          GAMING_INFOS_CACHE_TIMEOUT_MS: 20000
+          GAMING_INFOS_CACHE_RETRIES: 2
+          GAME_CODES_CACHE_TIMEOUT_MS: 20000
+          GAME_CODES_CACHE_RETRIES: 2
+          GAME_CODES_CACHE_GAME_DELAY_MS: 150
+
+      - name: Commit fallback changes
+        shell: bash
+        run: |
+          git add -A data
+          if git diff --cached --quiet; then
+            echo "Fallback caches already match APINODE."
+            exit 0
+          fi
+
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git commit -m "chore(cache): mirror APINODE fallback data [skip ci]"
+          git push

package/CACHE_SYNC.md

@@ -0,0 +1,202 @@
+# APINODE fallback-cache mirror
+
+`@nekosuneprojects/gaming-infos` is API-first. Normal reads try the NekoSuneVR V5 API before using bundled JSON under `data/`.
+
+The repository keeps **two independent last-good fallback snapshots** synchronized automatically:
+
+- Gaming Infos: `GET /v5/games/api/gaming-infos`
+- Game Codes: `GET /v5/games/api/codes`
+
+## Schedule
+
+The GitHub Action runs an **hourly APINODE change-watch at minute 23** and can also be started manually with `workflow_dispatch`.
+
+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.
+
+## Gaming Infos dataset discovery
+
+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` |
+| Honkai: Star Rail | `characters` |
+| Neverness to Everness | `characters` |
+| Wuthering Waves | `characters` (Resonators) |
+| Warframe | `characters` (Warframes) |
+| 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 hourly mirror also caches:
+
+```text
+GET /v5/games/api/codes
+GET /v5/games/api/codes/status
+GET /v5/games/api/codes/:game?includeUnknown=true
+```
+
+`/codes/status` only reads APINODE's cached source state. It does **not** trigger source website refreshes.
+
+The per-game request uses `includeUnknown=true`, so the fallback contains all three buckets when available:
+
+```json
+{
+  "Active": [],
+  "Expired": [],
+  "Unknown": []
+}
+```
+
+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
+
+Each cache is authoritative only **after its complete API download succeeds**.
+
+For Gaming Infos:
+
+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. 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 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.
+
+## 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
+```
+
+## Package API
+
+```js
+const info = require('@nekosuneprojects/gaming-infos');
+
+// 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
+await info.Codes();
+await info.CodesStatus();
+await info.GameCodes('fortnite', { includeUnknown: true });
+await info.GameCode('fortnite', 'NEKOSUNEVR');
+```
+
+## Commands
+
+```bash
+npm run test:all-cache
+npm run sync:cache
+
+# Debug individually
+npm run sync:gaming-infos-cache
+npm run sync:game-codes-cache
+npm run test:cache-sync
+npm run test:game-code-cache
+```
+
+Override APINODE while testing:
+
+```bash
+GAMING_INFOS_API_BASE=http://localhost:3000 npm run sync:cache
+```
+
+Useful variables:
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `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 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 remains API-first:
+
+```text
+application
+   ↓
+live APINODE
+   ├─ success → current API response
+   └─ unavailable/error → last-good bundled fallback
+```
+
+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 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,59 @@ 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
+- Added API-first Game Codes helpers: `Codes()`, `CodesStatus()`, `GameCodes(game, options)`, `GameCode(game, code, options)`, and `CodeCacheInfo()`.
+- Added an atomic `data/game-codes/` fallback mirror for `/v5/games/api/codes`, cache-only `/status`, and every per-game Active/Expired/Unknown dataset.
+- Added game-code fallback alias resolution using the cached `/codes` directory aliases.
+- Added game-code cache smoke tests covering additions, changes, removals, and partial API outages.
+- Added `Avatars(game, name)` for VRChat avatar records.
+- Added public Gaming Infos support for Wuthering Waves Resonators, Warframe Warframes, Fortnite current/released Battle Royale characters, Zenless Zone Zero Agents, Tower of Fantasy Simulacra, and Arknights: Endfield Operators.
+- Expanded the mirrored VRChat datasets to include players, groups, worlds, and avatars.
+- Added `CacheInfo()` for inspecting the last mirrored Gaming Infos snapshot.
+- Added automatic fallback-cache manifests with source URL, content hash, counts, and add/change/remove statistics.
+
+### Changed
+- `npm run sync:cache` now mirrors both Gaming Infos and Game Codes.
+- 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 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, sync workflow, cache commands, configuration, and examples.
+
 ## 2.1.0 - 2026-08-02
 
 ### Added
@@ -27,10 +80,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Renamed package from `vrchat-infos` to `gaming-infos` to reflect multi-game support (VRChat today, Genshin Impact and more coming soon).
 - `data/` is now scoped per game: `data/<game>/worlds`, `data/<game>/groups`, `data/<game>/players`, `data/<game>/meta.json`. VRChat data moved under `data/vrchat/`.
 - Every lookup function now takes a `game` as its first argument, e.g. `Worlds('vrchat', 'theblackcat')` instead of `Worlds('theblackcat')`.
-- Added `Game(game)` for game-level meta info, `Characters(game, name)` for character-based games, and a generic `Get(game, type, name)` escape hatch.
+- Added `Game(game)` for game-level info, `Characters(game, name)` for character-based games, and a generic `Get(game, type, name)` escape hatch.
 
 ### Added
 - Lookups now try the NekoSuneVR V5 API first (`GAMING_INFOS_API_BASE`, default `https://api.nekosunevr.co.uk`) and fall back to the bundled local JSON if the API is unreachable, so data can be updated in real time without republishing this package. Set `GAMING_INFOS_DISABLE_API=1` to force local-only lookups.
 - Added `genshinimpact`, `nte` (Neverness to Everness), and `honkaistarrail` games, each with `meta.json`.
 - Added all 104 currently-released Genshin Impact characters, all 20 currently-playable NTE characters, and all 69 currently-released Honkai: Star Rail characters under their respective `data/<game>/characters/` folders.
-