@nekosuneprojects/gaming-infos 2.2.0 → 3.0.1

package/README.md

@@ -1,535 +1,102 @@
-# 🌐 @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 **game information, VRChat community data, characters, redeem codes, and creator codes**.
+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.
 
-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 data in this repository is mirrored from APINODE once per day using an atomic add/change/remove synchronization system.
-
-Current package version: **2.2.0**
-
----
-
-## ✨ What it provides
-
-- 🎮 Multi-game metadata and character data
-- 🌐 Live NekoSuneVR V5 API lookups
-- 💾 Automatic local JSON fallback when the API is unavailable
-- 🔄 Daily APINODE → repository cache synchronization
-- 🧹 Add/change/remove mirroring so deleted API entries disappear from the next successful fallback snapshot
-- 🛡️ Last-good-cache protection if APINODE is down or a sync only partially succeeds
-- 👤 VRChat players
-- 👥 VRChat groups
-- 🌍 VRChat worlds
-- 🧍 VRChat avatars
-- 🧝 Character/roster datasets for supported games
-- 🎁 Redeem-code and creator-code helpers
-- 📊 Game-code directory, counts, aliases, status, and source-cache information
-- 🧪 Offline smoke tests for cache replacement and failure recovery
-
----
-
-## 🎮 Gaming Infos coverage
-
-| Game | Slug | Data |
-|---|---|---|
-| VRChat | `vrchat` | players, groups, worlds, avatars |
-| Genshin Impact | `genshinimpact` | characters |
-| Honkai: Star Rail | `honkaistarrail` | characters |
-| Neverness to Everness | `nte` | characters |
-| Wuthering Waves | `wutheringwaves` | Resonators under `characters` |
-| Warframe | `warframe` | Warframes under `characters` |
-| Fortnite | `fortnite` | current/released Battle Royale characters |
-| Zenless Zone Zero | `zenlesszonezero` | Agents under `characters` |
-| Tower of Fantasy | `toweroffantasy` | Simulacra under `characters` |
-| Arknights: Endfield | `arknightsendfield` | Operators under `characters` |
-
-The Game Codes system is separate and its supported game list is returned dynamically by the APINODE `/codes` directory endpoint.
-
----
-
-## 📦 Installation
+## Installation
 
 ```bash
 npm install @nekosuneprojects/gaming-infos
 ```
 
-Requires **Node.js 18 or newer**.
-
----
-
-# 🚀 Quick start
-
-```js
-const gamingInfos = require('@nekosuneprojects/gaming-infos');
-
-async function main() {
-  const games = await gamingInfos.Games();
-  const vrchat = await gamingInfos.Game('vrchat');
-
-  const worlds = await gamingInfos.List('vrchat', 'worlds');
-  const avatars = await gamingInfos.List('vrchat', 'avatars');
-  const genshinCharacters = await gamingInfos.List('genshinimpact', 'characters');
-  const wuwaCharacters = await gamingInfos.List('wutheringwaves', 'characters');
-
-  console.log({
-    gameCount: games.length,
-    vrchat,
-    worlds: worlds.length,
-    avatars: avatars.length,
-    genshinCharacters: genshinCharacters.length,
-    wuwaCharacters: wuwaCharacters.length
-  });
-}
-
-main();
-```
-
----
-
-# 🧠 Gaming Infos API
-
-## `Games()`
-
-Returns every game with bundled/API Gaming Infos metadata.
-
-```js
-const games = await gamingInfos.Games();
-```
-
-Live endpoint:
-
-```http
-GET /v5/games/api/gaming-infos
-```
-
-## `Game(game)`
-
-Returns game-level metadata.
-
-```js
-const game = await gamingInfos.Game('warframe');
-```
-
-## `List(game, type)`
-
-Returns every entity for a game/type.
-
-```js
-const resonators = await gamingInfos.List('wutheringwaves', 'characters');
-const agents = await gamingInfos.List('zenlesszonezero', 'characters');
-const operators = await gamingInfos.List('arknightsendfield', 'characters');
-const vrchatGroups = await gamingInfos.List('vrchat', 'groups');
-```
-
-Live endpoint:
-
-```http
-GET /v5/games/api/gaming-infos/:game/:type
-```
-
-## Single-entity helpers
+To use an individual game package directly:
 
-```js
-await gamingInfos.Worlds('vrchat', 'world-slug');
-await gamingInfos.Groups('vrchat', 'group-slug');
-await gamingInfos.Players('vrchat', 'player-slug');
-await gamingInfos.Avatars('vrchat', 'avatar-slug');
-await gamingInfos.Characters('warframe', 'warframe-slug');
-```
-
-Generic lookup:
-
-```js
-await gamingInfos.Get('vrchat', 'worlds', 'world-slug');
-```
-
-Live endpoint:
-
-```http
-GET /v5/games/api/gaming-infos/:game/:type/:name
-```
-
-The V5 API returns stable `slug` values for list entries. Use those slugs for detail lookups instead of trying to generate filenames from display names yourself.
-
-## `CacheInfo()`
-
-Reads information about the last mirrored Gaming Infos fallback snapshot.
-
-```js
-const cache = await gamingInfos.CacheInfo();
-console.log(cache?.syncedAt, cache?.contentHash);
-```
-
----
-
-# 🎁 Game Codes API
-
-Version 2.2.0 adds API-first redeem-code and creator-code support using the same fallback model.
-
-APINODE endpoints:
-
-```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
+```bash
+npm install @nekosuneprojects/warframe-api@1.0.1
+npm install @nekosuneprojects/vrchat-api@1.0.0
 ```
 
-`/codes/status` is cache/status data only and does **not** trigger website scraping or a source refresh.
+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.
 
-## `Codes()`
-
-Returns the Game Codes directory, including supported games, aliases, metadata, counters, source counts, and endpoint information.
+## Warframe
 
 ```js
-const directory = await gamingInfos.Codes();
+const gaming = require('@nekosuneprojects/gaming-infos');
 
-console.log(directory.games);
-console.log(directory.aliases);
+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);
 ```
 
-## `CodesStatus()`
-
-Returns the cached source-refresh state.
+## VRChat
 
 ```js
-const status = await gamingInfos.CodesStatus();
-```
+const gaming = require('@nekosuneprojects/gaming-infos');
 
-## `GameCodes(game, options)`
-
-Returns code lists using the existing APINODE response shape:
-
-```js
-const fortniteCodes = await gamingInfos.GameCodes('fortnite');
-
-console.log(fortniteCodes.Active);
-console.log(fortniteCodes.Expired);
-```
-
-Default shape:
-
-```json
-{
-  "Active": [],
-  "Expired": []
-}
-```
-
-Include queued/unknown records:
-
-```js
-const allFortniteCodes = await gamingInfos.GameCodes('fortnite', {
-  includeUnknown: true
+// Local-first bundled VRChat JSON, no VRChat login needed:
+const vrchat = gaming.createClient('vrchat', {
+  cacheDir: './storage/vrchat'
 });
-```
-
-Which can return:
+const game = await vrchat.About();
+const localWorld = await vrchat.world('theblackcat');
+const localGroups = await vrchat.groups.search('club');
 
-```json
-{
-  "Active": [],
-  "Expired": [],
-  "Unknown": []
-}
-```
+// 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});
 
-Filtering is supported:
+// Public third-party avatar-search providers (availability varies):
+const avatars = await vrchat.avatars.searchOnline('Rindo');
 
-```js
-const creatorCodes = await gamingInfos.GameCodes('fortnite', {
-  category: 'creator-code',
-  includeUnknown: true
-});
-
-const freeCodes = await gamingInfos.GameCodes('genshin-impact', {
-  claimType: 'free'
-});
+console.log(game.name, localWorld.name, localGroups.total);
+console.log(worlds.meta, foundWorlds.meta, groups.meta, avatars.successful);
 ```
 
-Timezone can also be passed through to the live 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.
 
-```js
-const codes = await gamingInfos.GameCodes('fortnite', {
-  timezone: 'Europe/London',
-  includeUnknown: true
-});
-```
+### World browsing
 
-Cached aliases from the `/codes` directory are resolved during API outages as well, so aliases such as `fn`, `genshin`, `hsr`, or `wuwa` can still map to their canonical cached game dataset.
-
-## `GameCode(game, code, options)`
-
-Looks up one specific code.
+The online world browser supports `updated`, `newest`, `oldest` and `popular`, using the remote API's 24-world pagination:
 
 ```js
-const creator = await gamingInfos.GameCode('fortnite', 'NEKOSUNEVR');
-console.log(creator);
-```
-
-Live endpoint:
-
-```http
-GET /v5/games/api/codes/:game/:code
-```
-
-When APINODE is unavailable, the package searches the locally mirrored Active, Expired, and Unknown code buckets.
-
-## `CodeCacheInfo()`
-
-Returns the local Game Codes cache manifest.
-
-```js
-const codeCache = await gamingInfos.CodeCacheInfo();
-console.log(codeCache?.syncedAt, codeCache?.stats);
-```
-
----
-
-# 📚 Function reference
-
-| Function | Purpose |
-|---|---|
-| `Games()` | List Gaming Infos games |
-| `Game(game)` | Get game metadata |
-| `List(game, type)` | List every entry for one game/type |
-| `Worlds(game, name)` | Get one world |
-| `Groups(game, name)` | Get one group |
-| `Players(game, name)` | Get one player |
-| `Avatars(game, name)` | Get one avatar |
-| `Characters(game, name)` | Get one character/Warframe/Agent/etc. |
-| `Get(game, type, name)` | Generic entity lookup |
-| `CacheInfo()` | Gaming Infos fallback manifest |
-| `Codes()` | Game Codes directory |
-| `CodesStatus()` | Cached Game Codes source status |
-| `GameCodes(game, options)` | Active/Expired/Unknown code lists |
-| `GameCode(game, code, options)` | One specific redeem/creator code |
-| `CodeCacheInfo()` | Game Codes fallback manifest |
-
----
-
-# 💾 API-first fallback behavior
-
-Normal reads follow this path:
-
-```text
-Application
-   │
-   ▼
-NekoSuneVR V5 API
-   │
-   ├── available ──► return live data
-   │
-   └── unavailable
-          │
-          ▼
-     bundled data/
-          │
-          ▼
-     return last-good fallback
-```
-
-The package does not need an API key for the public read endpoints documented above.
-
-Set this to force local-only reads:
-
-```bash
-GAMING_INFOS_DISABLE_API=1
-```
-
----
-
-# 🔄 Daily fallback synchronization
-
-The repository automatically runs the cache mirror **once every day at 03:23 UTC** through GitHub Actions.
-
-The combined command is:
-
-```bash
-npm run sync:cache
-```
-
-That performs both:
-
-```bash
-npm run sync:gaming-infos-cache
-npm run sync:game-codes-cache
-```
-
-The synchronization process is designed to be authoritative and failure-safe:
-
-1. Download the complete configured API snapshot into a temporary directory.
-2. Validate all required responses.
-3. Calculate content hashes and add/change/remove statistics.
-4. Replace the old fallback only after the new snapshot succeeds completely.
-5. Keep the previous fallback untouched if the API fails, times out, returns an error, or produces an incomplete snapshot.
-6. Commit actual fallback changes back to the repository.
-
-Successful syncs mirror **additions, modifications, and removals**. If APINODE removes an entry, that entry is removed from the fallback during the next successful mirror.
-
-Gaming Infos and Game Codes use independent atomic caches so a failure in one dataset cannot destroy the last-good snapshot of the other.
-
-See [CACHE_SYNC.md](CACHE_SYNC.md) for the detailed cache architecture.
-
----
-
-# 🧪 Cache tests
-
-Run all cache safety tests:
-
-```bash
-npm run test:all-cache
-```
-
-Or individually:
-
-```bash
-npm run test:cache-sync
-npm run test:game-code-cache
-```
-
-The tests cover scenarios including:
-
-- new entries appearing
-- existing entries changing
-- upstream entries being removed
-- duplicate/invalid data protection
-- partial API failures
-- simulated HTTP 5xx outages
-- preserving the last-good fallback after a failed sync
-
----
-
-# 📁 Fallback data structure
-
-```text
-data/
-├── genshinimpact/
-│   ├── meta.json
-│   └── characters/
-├── honkaistarrail/
-├── nte/
-├── wutheringwaves/
-├── warframe/
-├── fortnite/
-├── zenlesszonezero/
-├── toweroffantasy/
-├── arknightsendfield/
-├── vrchat/
-│   ├── meta.json
-│   ├── players/
-│   ├── groups/
-│   ├── worlds/
-│   └── avatars/
-├── .cache-manifest.json
-└── game-codes/
-    ├── directory.json
-    ├── status.json
-    ├── .cache-manifest.json
-    └── games/
-        └── <game>.json
-```
-
-An entity with no verified image can use:
-
-```json
-{
-  "image": ""
-}
-```
-
-Consumers should treat a blank image string as "no verified image available".
-
----
-
-# ⚙️ Environment variables
-
-## Runtime API reads
-
-| Variable | Default | Purpose |
-|---|---|---|
-| `GAMING_INFOS_API_BASE` | `https://api.nekosunevr.co.uk` | NekoSuneVR APINODE base URL |
-| `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_DISABLE_API` | unset | `1`/`true` forces local-only operation |
-| `GAMING_INFOS_TIMEOUT_MS` | `4000` | Runtime API timeout before fallback |
-
-## Cache mirror
-
-| Variable | Default | Purpose |
-|---|---|---|
-| `GAMING_INFOS_CACHE_TIMEOUT_MS` | `15000` | Gaming Infos sync request timeout |
-| `GAMING_INFOS_CACHE_RETRIES` | `2` | Gaming Infos retry count |
-| `GAMING_INFOS_CACHE_RETRY_DELAY_MS` | `750` | Gaming Infos retry delay |
-| `GAME_CODES_CACHE_TIMEOUT_MS` | `15000` | Game Codes sync request timeout |
-| `GAME_CODES_CACHE_RETRIES` | `2` | Game Codes retry count |
-| `GAME_CODES_CACHE_RETRY_DELAY_MS` | `750` | Game Codes retry delay |
-| `GAME_CODES_CACHE_GAME_DELAY_MS` | small delay | Delay between per-game code snapshots |
-
----
-
-# 📝 Example character entry
-
-Different games expose different fields. Consumers should use the fields relevant to that game rather than assuming every title has the same schema.
-
-```json
-{
-  "name": "Example Character",
-  "slug": "examplecharacter",
-  "rarity": "5-star",
-  "element": "Electro",
-  "weapon": "Sword",
-  "description": "Public character information.",
-  "image": "https://example.com/character.webp",
-  "url": "https://example.com/source",
-  "source": {
-    "provider": "Public source",
-    "publicDataOnly": true
-  }
-}
+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);
 ```
 
----
-
-# 🤝 Contributions
-
-Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
-
-Please follow these rules:
-
-- Only include publicly available data or data you have permission to publish.
-- Do not include private profiles, private Discord messages, DMs, private logs, authentication data, or personal information.
-- Do not add leaks, datamined/unreleased content, hidden APIs, memory-inspection data, or client-extracted private data.
-- Respect each game's Terms of Service and community rules.
-- Keep sources clear and verifiable.
-- Do not submit harassment, defamation, doxxing, or invasive profile information.
-
----
-
-# ⚠️ Package fallback note
-
-GitHub repository cache snapshots update automatically, but published npm packages are immutable.
-
-An already-installed npm release keeps the fallback JSON bundled with that release until you update the package. While APINODE is online, live API reads still provide current data without requiring a package release.
-
----
-
-# ⚠️ Disclaimer
+## Module layout
 
-This project is not affiliated with or endorsed by VRChat Inc., HoYoverse, Kuro Games, Digital Extremes, Epic Games, Hotta Studio, Hypergryph/GRYPHLINE, or any other game publisher represented by the data.
+- `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
 
-Game names, logos, characters, and related trademarks belong to their respective owners.
+## API surface
 
----
+| 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 |
 
-# 🧠 Credits
+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).
 
-Maintained by **NekoSune Projects**.
+## Migration from 2.x
 
-Contributions are welcome — keep the data public, accurate, and game-friendly.
+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.
 
-<!-- GitAds-Verify: 2XHQSF1IKOWF4FH8P2TRI5GRWIJG2TJP -->
+## Publishing
 
-## GitAds Sponsored
-[![Sponsored by GitAds](https://gitads.dev/v1/ad-serve?source=nekosuneprojects/gaming-infos@github)](https://gitads.dev/v1/ad-track?source=nekosuneprojects/gaming-infos@github)
+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.