@nekosuneprojects/gaming-infos 2.4.0 → 3.0.1

package/CHANGELOG.md

@@ -7,6 +7,49 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+### Fixed
+- Fixed npmjs publishing from automatic GitHub Actions runs to use Trusted Publisher OIDC instead of selecting an npm token that was rejected with `EOTP` (interactive two-factor authentication required).
+- Clarified the required npmjs Trusted Publisher configuration for `NekoSuneProjectsNPM/gaming-infos` and workflow `build-publish.yml`.
+
+### Fixed
+- Corrected the publishing workflow so successful `main` push builds can publish to npmjs and GitHub Packages; previously both registry jobs were skipped because they required `workflow_dispatch`.
+- Added a published-version check to skip existing versions instead of reattempting immutable releases.
+- Preserved manual registry selection and npm token/Trusted Publisher authentication.
+
+### Fixed
+- Fixed npm installation error E404 by aligning the VRChat dependency and lockfile with the published `@nekosuneprojects/vrchat-api@1.0.0` release. The unreleased `1.0.1` tarball was previously referenced incorrectly.
+
+## 3.0.1 - 2026-11-07
+
+### Added
+- Integrated `@nekosuneprojects/vrchat-api@1.0.0` as the second independent game provider alongside Warframe.
+- Added `createVRChat()` and `createClient('vrchat')` for local VRChat JSON, worlds search/browse, groups search and avatar provider searches.
+- Added GitHub Actions validation, Node.js checks, unit tests and package packing on main pushes and pull requests.
+- Added manual npmjs and GitHub Packages publishing with selectable registries and npm token/Trusted Publisher authentication.
+
+### Changed
+- Bumped the gaming-infos package version from `3.0.0` to `3.0.1` for the next release.
+- Consolidated publishing into one workflow, removing duplicate release-triggered publish workflows.
+- Retained `@nekosuneprojects/warframe-api@1.0.1` and exact package dependency locking.
+
+
+### Added
+- Added `@nekosuneprojects/vrchat-api@1.0.0` as the second modular provider alongside Warframe.
+- Added `createVRChat()` / `createClient('vrchat')` with bundled VRChat JSON lookups, online world search and browsing, group search, and external avatar search.
+- Extended provider smoke tests and documentation for VRChat.
+
+### Changed
+- Started the 3.0.0 major-version modular rebuild.
+- Removed legacy multi-game JSON cache, scripts and synchronisation workflows.
+- Added the standalone `@nekosuneprojects/warframe-api@1.0.1` dependency as the first provider.
+- Preserved package publishing workflows and switched them to GitHub-hosted runners.
+
+## 3.0.0 - Unreleased
+
+### Breaking changes
+- Replaced the 2.x monolithic API and bundled game data with a small modular provider registry. Only Warframe is included initially.
+- Old `gamecodes`, data mirrors and cache sync commands were removed.
+
 ## 2.4.0 - 2026-08-24
 
 ### Added

package/README.md

@@ -1,14 +1,8 @@
-# 🌐 @nekosuneprojects/gaming-infos
+# @nekosuneprojects/gaming-infos
 
-[![npm version](https://img.shields.io/npm/v/@nekosuneprojects/gaming-infos.svg)](https://www.npmjs.com/package/@nekosuneprojects/gaming-infos)
+Modular multi-game information toolkit for Node.js 18+. **Version 3.0.1 continues the clean-break 3.x rebuild** of the old monolithic data-mirror package, using independent npm packages for each game. The previous embedded datasets, API cache syncs and legacy add-on implementation have been removed.
 
-A Node.js data package for **multi-game information, Fortnite skins/NPCs/maps, Call of Duty characters/NPCs/maps, VRChat community data, redeem codes, and creator codes**.
-
-The package is **API-first**: it reads from the NekoSuneVR V5 API whenever possible, then automatically falls back to bundled JSON when the API is unavailable. The fallback repository checks APINODE every hour and only commits real add/change/remove data updates.
-
-Current package source version: **2.4.0**
-
-> Published npm releases are immutable. The GitHub source can be ahead of the version currently available from the npm registry until a new package release is published.
+The rebuilt package now includes **Warframe and VRChat**, backed by `@nekosuneprojects/warframe-api@1.0.1` and `@nekosuneprojects/vrchat-api@1.0.0` respectively. Additional games can be added later without reintroducing the old monolithic cache.
 
 ## Installation
 
@@ -16,359 +10,93 @@ Current package source version: **2.4.0**
 npm install @nekosuneprojects/gaming-infos
 ```
 
-Requires Node.js 18+.
-
-## Gaming Infos coverage
-
-| Game / franchise | Slug | Datasets |
-|---|---|---|
-| VRChat | `vrchat` | `players`, `groups`, `worlds`, `avatars` |
-| Genshin Impact | `genshinimpact` | `characters` |
-| Honkai: Star Rail | `honkaistarrail` | `characters` |
-| Neverness to Everness | `nte` | `characters` |
-| Wuthering Waves | `wutheringwaves` | `characters` (Resonators) |
-| Warframe | `warframe` | `characters` (Warframes) |
-| **Fortnite** | `fortnite` | `characters` = released skins/Outfits, `npcs` = Battle Royale NPCs, `maps` = Named Locations/maps |
-| **Call of Duty mainline** | see table below | `characters`, `npcs`, `maps` per title |
-| Zenless Zone Zero | `zenlesszonezero` | `characters` (Agents) |
-| Tower of Fantasy | `toweroffantasy` | `characters` (Simulacra) |
-| Arknights: Endfield | `arknightsendfield` | `characters` (Operators) |
-
-## Call of Duty mainline coverage
-
-Version 2.4.0 adds the mainline PC/console Call of Duty series from the original **Call of Duty (2003)** through **Black Ops 7**, plus **Modern Warfare 4 (2026)** public beta/official announcement data.
-
-| Title | Slug | Year/status |
-|---|---|---:|
-| Call of Duty | `cod2003` | 2003 |
-| Call of Duty 2 | `cod2` | 2005 |
-| Call of Duty 3 | `cod3` | 2006 |
-| Call of Duty 4: Modern Warfare | `cod4modernwarfare` | 2007 |
-| Call of Duty: World at War | `codworldatwar` | 2008 |
-| Call of Duty: Modern Warfare 2 | `codmodernwarfare2` | 2009 |
-| Call of Duty: Black Ops | `codblackops` | 2010 |
-| Call of Duty: Modern Warfare 3 | `codmodernwarfare3` | 2011 |
-| Call of Duty: Black Ops II | `codblackops2` | 2012 |
-| Call of Duty: Ghosts | `codghosts` | 2013 |
-| Call of Duty: Advanced Warfare | `codadvancedwarfare` | 2014 |
-| Call of Duty: Black Ops III | `codblackops3` | 2015 |
-| Call of Duty: Infinite Warfare | `codinfinitewarfare` | 2016 |
-| Call of Duty: WWII | `codwwii` | 2017 |
-| Call of Duty: Black Ops 4 | `codblackops4` | 2018 |
-| Call of Duty: Modern Warfare (2019) | `codmodernwarfare2019` | 2019 |
-| Call of Duty: Black Ops Cold War | `codblackopscoldwar` | 2020 |
-| Call of Duty: Vanguard | `codvanguard` | 2021 |
-| Call of Duty: Modern Warfare II | `codmodernwarfareii2022` | 2022 |
-| Call of Duty: Modern Warfare III | `codmodernwarfareiii2023` | 2023 |
-| Call of Duty: Black Ops 6 | `codblackops6` | 2024 |
-| Call of Duty: Black Ops 7 | `codblackops7` | 2025 |
-| Call of Duty: Modern Warfare 4 | `codmodernwarfare4` | 2026 beta / announced launch |
-
-### Call of Duty dataset rules
-
-Each Call of Duty title uses the same three public datasets:
-
-```text
-<cod-slug>/characters → playable/main characters, protagonists, Operators and Specialists
-<cod-slug>/npcs       → other campaign/game character and NPC records
-<cod-slug>/maps       → multiplayer, Zombies, Warzone and other public map/mission records
-```
-
-Historical released titles are populated from public Call of Duty Wiki game-specific categories. APINODE excludes categories marked cut, unused, cancelled, unreleased, non-canon, prototype/concept, screenshot/image-only, or file-only.
-
-`codmodernwarfare4` is handled more strictly while the game is pre-release: only **officially published Activision beta/public announcement information** is accepted. Leaks, datamines, hidden APIs, and unofficial unreleased lists are not imported. Campaign NPCs are not invented; they only appear once publicly identified by an allowed source.
-
-Examples:
-
-```js
-const bo2Characters = await info.List('codblackops2', 'characters');
-const mw2CampaignNpcs = await info.List('codmodernwarfare2', 'npcs');
-const cod4Maps = await info.List('cod4modernwarfare', 'maps');
-const mw4PublicMaps = await info.List('codmodernwarfare4', 'maps');
-
-const oneCharacter = await info.Characters('codblackops2', 'character-slug');
-const oneNpc = await info.NPCs('codblackops2', 'npc-slug');
-const oneMap = await info.Maps('codblackops2', 'map-slug');
-```
-
-## Fortnite dataset rules
+To use an individual game package directly:
 
-Fortnite is deliberately separated into three API/package datasets:
-
-```text
-fortnite/characters  → released Outfit cosmetics / skins
-fortnite/npcs        → Battle Royale NPCs / Characters
-fortnite/maps        → Named Locations / map locations
+```bash
+npm install @nekosuneprojects/warframe-api@1.0.1
+npm install @nekosuneprojects/vrchat-api@1.0.0
 ```
 
-A map/location should never appear in the skins dataset. APINODE also removes legacy NPC duplicates when a title is confirmed by the Fortnite Named Locations catalog.
+Node.js 18+ is required. Pushes to `main` run build/tests and attempt to publish the package to npmjs and GitHub Packages when the exact version is not already available. Pull requests build/test only.
 
-## Quick start
+## Warframe
 
 ```js
-const info = require('@nekosuneprojects/gaming-infos');
-
-async function main() {
-  const games = await info.Games();
-
-  const fortniteSkins = await info.List('fortnite', 'characters');
-  const fortniteNpcs = await info.List('fortnite', 'npcs');
-  const fortniteMaps = await info.List('fortnite', 'maps');
-
-  const blackOps2Characters = await info.List('codblackops2', 'characters');
-  const blackOps2Npcs = await info.List('codblackops2', 'npcs');
-  const blackOps2Maps = await info.List('codblackops2', 'maps');
-
-  const vrchatWorlds = await info.List('vrchat', 'worlds');
-
-  console.log({
-    games: games.length,
-    fortniteSkins: fortniteSkins.length,
-    blackOps2Characters: blackOps2Characters.length,
-    blackOps2Npcs: blackOps2Npcs.length,
-    blackOps2Maps: blackOps2Maps.length,
-    vrchatWorlds: vrchatWorlds.length,
-  });
-}
-
-main();
-```
-
-## Gaming Infos API
+const gaming = require('@nekosuneprojects/gaming-infos');
 
-Live APINODE endpoints:
-
-```http
-GET /v5/games/api/gaming-infos
-GET /v5/games/api/gaming-infos/:game/:type
-GET /v5/games/api/gaming-infos/:game/:type/:name
-```
-
-The root endpoint publishes each game's stable `slug` and available `types`. Type-list responses publish stable entity `slug` values for detail lookups.
-
-Examples:
-
-```http
-GET /v5/games/api/gaming-infos/codblackops2/characters
-GET /v5/games/api/gaming-infos/codblackops2/npcs
-GET /v5/games/api/gaming-infos/codblackops2/maps
-GET /v5/games/api/gaming-infos/codmodernwarfare4/characters
-GET /v5/games/api/gaming-infos/codmodernwarfare4/maps
+const warframe = gaming.createClient('warframe', { platform: 'pc', language: 'en' });
+const about = await warframe.About(); 
+const matches = await warframe.search('Ash');
+const codes = await warframe.codes.active({ hasCode: true });
+const alerts = await warframe.api.alerts();
+console.log(about.name, matches.total, codes.length, alerts.length);
 ```
 
-### Main helpers
+## VRChat
 
 ```js
-await info.Games();
-await info.Game('codblackops2');
+const gaming = require('@nekosuneprojects/gaming-infos');
 
-await info.List('codblackops2', 'characters');
-await info.List('codblackops2', 'npcs');
-await info.List('codblackops2', 'maps');
+// Local-first bundled VRChat JSON, no VRChat login needed:
+const vrchat = gaming.createClient('vrchat', {
+  cacheDir: './storage/vrchat'
+});
+const game = await vrchat.About();
+const localWorld = await vrchat.world('theblackcat');
+const localGroups = await vrchat.groups.search('club');
 
-await info.Characters('codblackops2', 'character-slug');
-await info.NPCs('codblackops2', 'npc-slug');
-await info.Maps('codblackops2', 'map-slug');
+// Live online NekoSune APIs:
+const worlds = await vrchat.worlds.browse({sort:'popular',page:1});
+const foundWorlds = await vrchat.worlds.searchOnline('Mirror',{platform:'pc'});
+const groups = await vrchat.groups.searchOnline('Dance',{page:1});
 
-await info.Worlds('vrchat', 'world-slug');
-await info.Groups('vrchat', 'group-slug');
-await info.Players('vrchat', 'player-slug');
-await info.Avatars('vrchat', 'avatar-slug');
+// Public third-party avatar-search providers (availability varies):
+const avatars = await vrchat.avatars.searchOnline('Rindo');
 
-await info.Get('codblackops2', 'maps', 'map-slug');
-await info.CacheInfo();
+console.log(game.name, localWorld.name, localGroups.total);
+console.log(worlds.meta, foundWorlds.meta, groups.meta, avatars.successful);
 ```
 
-## Game Codes API
+The `vrchat-api` provider bundles local JSON for worlds, groups, players and game metadata; online methods make on-demand HTTP calls. It does **not** fetch private VRChat account data or bypass authentication. The upstream JSON currently contains no local avatar catalog, so `avatars.searchOnline` uses external providers.
 
-Game Codes are separate from Gaming Infos and are discovered dynamically from APINODE.
+### World browsing
 
-```http
-GET /v5/games/api/codes
-GET /v5/games/api/codes/status
-GET /v5/games/api/codes/:game
-GET /v5/games/api/codes/:game/:code
-```
-
-Package helpers:
+The online world browser supports `updated`, `newest`, `oldest` and `popular`, using the remote API's 24-world pagination:
 
 ```js
-const directory = await info.Codes();
-const status = await info.CodesStatus();
-
-const codes = await info.GameCodes('fortnite');
-const allCodes = await info.GameCodes('fortnite', { includeUnknown: true });
-const oneCode = await info.GameCode('fortnite', 'SOME-CODE');
-const codeCache = await info.CodeCacheInfo();
-```
-
-Default per-game shape:
-
-```json
-{
-  "Active": [],
-  "Expired": []
-}
-```
-
-With `includeUnknown: true`:
-
-```json
-{
-  "Active": [],
-  "Expired": [],
-  "Unknown": []
-}
-```
-
-`GameCodes()` also supports `category`, `claimType`, and `timezone` options.
-
-## Function reference
-
-| Function | Purpose |
-|---|---|
-| `Games()` | List Gaming Infos games |
-| `Game(game)` | Get game metadata |
-| `List(game, type)` | List a complete dataset |
-| `Characters(game, name)` | Get one character/skin/Operator/roster entity |
-| `NPCs(game, name)` | Get one NPC |
-| `Maps(game, name)` | Get one map/location |
-| `Worlds(game, name)` | Get one world |
-| `Groups(game, name)` | Get one group |
-| `Players(game, name)` | Get one player |
-| `Avatars(game, name)` | Get one avatar |
-| `Get(game, type, name)` | Generic Gaming Infos detail lookup |
-| `CacheInfo()` | Gaming Infos fallback manifest |
-| `Codes()` | Game Codes directory |
-| `CodesStatus()` | Game Codes source/sync status |
-| `GameCodes(game, options)` | Active/Expired/Unknown code lists |
-| `GameCode(game, code, options)` | One redeem/creator code |
-| `CodeCacheInfo()` | Game Codes fallback manifest |
-
-## API-first fallback behavior
-
-```text
-application
-   ↓
-live APINODE
-   ├─ success → use current live data
-   └─ unavailable/error
-          ↓
-     bundled data/
-          ↓
-     last-good fallback
-```
-
-Set this to force local-only reads:
-
-```bash
-GAMING_INFOS_DISABLE_API=1
-```
-
-Useful runtime variables:
-
-| Variable | Default |
-|---|---|
-| `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_TIMEOUT_MS` | `4000` |
-
-## Hourly fallback mirror
-
-The GitHub Action checks APINODE **every hour at minute 23**.
-
-```bash
-npm run sync:cache
-```
-
-This mirrors both:
-
-```bash
-npm run sync:gaming-infos-cache
-npm run sync:game-codes-cache
-```
-
-Gaming Infos now **auto-discovers games and dataset types** from the APINODE root response. The built-in manifest remains a compatibility/safety baseline for older APINODE deployments, but when the API reports:
-
-```json
-{
-  "slug": "codblackops2",
-  "types": ["characters", "npcs", "maps"]
-}
-```
-
-the mirror automatically includes all three datasets. This is how all Call of Duty titles are picked up without hard-coding 23 package mirror entries, and it also makes future public game/type additions easier to propagate.
-
-The mirror is atomic and last-good-safe:
-
-1. Download the root Gaming Infos directory and merge its `slug`/`types` declarations into the effective mirror manifest.
-2. Download every game meta + every discovered/configured dataset to a temporary tree.
-3. Validate all required endpoints and entity slugs.
-4. Calculate hashes and add/change/remove statistics.
-5. Replace the old snapshot only after the new one succeeds completely.
-6. Keep the previous snapshot if APINODE is unavailable or any required dataset fails.
-7. Commit only when stable content actually changed.
-
-Game-code countdown seconds are not stored as meaningful repository changes; fallback countdowns are recalculated from stable expiry dates when read.
-
-See [CACHE_SYNC.md](CACHE_SYNC.md) for the detailed mirror design.
-
-## Cache tests
-
-```bash
-npm run test:all-cache
-npm run test:cache-sync
-npm run test:game-code-cache
+const { createVRChat } = require('@nekosuneprojects/gaming-infos');
+const vrchat = createVRChat();
+const page2 = await vrchat.worlds.browse({sort:'updated',page:2});
+console.log(page2.data, page2.meta);
 ```
 
-Tests cover additions, updates, removals, duplicate/invalid data, dynamic APINODE dataset discovery, partial HTTP failures, and last-good snapshot preservation.
-
-## Fallback structure
+## Module layout
 
-After APINODE has populated a title and the hourly mirror has completed successfully, the repository structure includes entries like:
-
-```text
-data/
-├── fortnite/
-│   ├── meta.json
-│   ├── characters/
-│   ├── npcs/
-│   └── maps/
-├── codblackops2/
-│   ├── meta.json
-│   ├── characters/
-│   ├── npcs/
-│   └── maps/
-├── codmodernwarfare4/
-│   ├── meta.json
-│   ├── characters/
-│   ├── npcs/
-│   └── maps/
-├── ...
-├── vrchat/
-│   ├── players/
-│   ├── groups/
-│   ├── worlds/
-│   └── avatars/
-├── .cache-manifest.json
-└── game-codes/
-    ├── directory.json
-    ├── status.json
-    ├── .cache-manifest.json
-    └── games/
-```
+- `index.js` — public entrypoint
+- `src/registry.js` — provider registry and selection
+- `src/providers/warframe.js` — Warframe npm adapter
+- `src/providers/vrchat.js` — VRChat npm adapter
+- `test/registry.test.js` — provider smoke tests
+- `.github/workflows/npm-publish.yml` — npmjs release publishing
+- `.github/workflows/npm-publish-github-packages.yml` — GitHub Packages release publishing
 
-## Data policy
+## API surface
 
-Only add publicly available released data, or clearly official public beta/announcement information for a currently pre-release title. Do not add private profiles, private messages, authentication data, leaks, unofficial unreleased lists, datamined content, hidden APIs, or client-memory extraction.
+| Export | Purpose |
+| --- | --- |
+| `createClient(game, options)` | Instantiate the game provider |
+| `createWarframe(options)` | Shortcut to the Warframe provider |
+| `createVRChat(options)` | Shortcut to the VRChat provider |
+| `listProviders()` | List installed game IDs |
+| `providers.warframe` | Warframe provider adapter |
+| `providers.vrchat` | VRChat provider adapter |
 
-## npm fallback note
+Read the standalone packages' documentation for complete features: [Warframe API](https://www.npmjs.com/package/@nekosuneprojects/warframe-api) and [VRChat API](https://www.npmjs.com/package/@nekosuneprojects/vrchat-api).
 
-Published npm releases are immutable. The GitHub repository fallback can update hourly, but an already-installed npm release keeps the files bundled with that release until upgraded. Normal package reads still use live APINODE first when it is available.
+## Migration from 2.x
 
-## Disclaimer
+The 2.x `gaming-infos` API-first caches, embedded JSON catalogs, `gamecodes`, and sync scripts are **not available** in 3.0.0. Previous consumers must migrate explicitly. Old releases remain accessible through Git history and npm.
 
-This project is not affiliated with or endorsed by Activision, Epic Games, VRChat Inc., HoYoverse, Kuro Games, Digital Extremes, Hotta Studio, Hypergryph/GRYPHLINE, or other publishers represented by the data. Game names, logos, characters, and related trademarks belong to their respective owners.
+## Publishing
 
-Maintained by **NekoSune Projects**.
+The source version is `3.0.1`; package publication is manual through GitHub Actions. Before publishing, confirm both exact dependency versions exist on npmjs.org, run `npm ci`, `npm run check`, `npm test`, and `npm pack --dry-run`. The consolidated `Build and publish gaming-infos` workflow builds/tests on every `main` push and pull request. After a successful build on `main`, it also attempts **both** registry publications, skipping any version already published. The manual **Run workflow** action still supports `registry=both`, `npmjs`, or `github`. On automatic pushes, npmjs uses **Trusted Publisher OIDC only**, not the existing `npm_token` (which caused EOTP). Configure npm's Trusted Publisher for the exact `NekoSuneProjectsNPM/gaming-infos` repository and `build-publish.yml` workflow, and enable direct `npm publish`. Manual dispatch still permits a token if it is eligible to publish without an interactive OTP (which must be configured for repository `NekoSuneProjectsNPM/gaming-infos`, workflow `build-publish.yml`). Manual dispatch uses the selected `npm_auth` setting. GitHub Packages publishes as `@nekosuneprojectsnpm/gaming-infos`. Each new npm release still requires incrementing the package version in both package files.