@nekosuneprojects/gaming-infos 2.1.0 → 2.2.0

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

@@ -0,0 +1,72 @@
+name: Sync APINODE fallback caches
+
+on:
+  workflow_dispatch:
+  schedule:
+    # Daily at 03:23 UTC. GitHub Actions cron uses UTC.
+    - cron: "23 3 * * *"
+  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,172 @@
+# 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 **once every day at 03:23 UTC** 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.
+
+## Mirrored gaming-infos datasets
+
+| Game | 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` (current/released Battle Royale characters) |
+| Zenless Zone Zero | `characters` (Agents) |
+| Tower of Fantasy | `characters` (Simulacra) |
+| Arknights: Endfield | `characters` (Operators) |
+
+## Mirrored Game Codes endpoints
+
+The daily 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 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
+    └── ...
+```
+
+## 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-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.
+
+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.
+
+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.
+
+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
+
+Gaming Infos functions remain available:
+
+```js
+const info = require('@nekosuneprojects/gaming-infos');
+
+await info.Games();
+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
+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
+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_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_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:
+
+```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`. 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.
+
+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.

package/CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+## 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 now runs once daily at 03:23 UTC instead of every six hours.
+- 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.
+- 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.
+
 ## 2.1.0 - 2026-08-02
 
 ### Added
@@ -27,10 +49,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.
-