@nekosuneprojects/gaming-infos 2.4.0 → 3.0.1

package/CACHE_SYNC.md

@@ -1,202 +0,0 @@
-# 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/CONTRIBUTING.md

@@ -1,217 +0,0 @@
-# 🤝 Contributing to @nekosuneprojects/gaming-infos
-
-Thank you for your interest in contributing to **@nekosuneprojects/gaming-infos**!
-This project relies on community help to keep game data organized, accurate, and friendly — across every game it covers,
-not just VRChat.
-
-Please read this guide carefully **before submitting a Pull Request (PR)**.
-
----
-
-## 🦊 Overview
-
-This project provides **community game info** — worlds, groups, players, characters, and more — in JSON format, used by
-scripts and tools. Data lives in the `data/` folder, scoped per game:
-
-```
-data/
-└── <game>/
-    ├── meta.json
-    ├── worlds/
-    ├── groups/
-    ├── players/
-    └── characters/
-```
-
-Each JSON file represents a public piece of info about a world, group, player, or character for that game.
-Not every game uses every folder — e.g. VRChat uses `worlds`/`groups`/`players`, while a character-driven game like
-Genshin Impact mainly uses `characters`. Use the `Get(game, type, name)` function for any entity type a new game
-needs that isn't already listed above.
-
----
-
-## ✅ Contribution Rules
-
-### 1. Permission & Privacy
-
-- Only include **publicly available data** or **data you have explicit permission** to share.
-- If the data comes from **private profiles, Discord servers, or DMs**, **do not submit it**.
-- You must **ask permission** from the world/group/player/character owner if the information is not publicly listed.
-- Do **not** upload personal or sensitive details under any circumstance.
-
-### 2. Accepted Public Sources
-
-You may use:
-- Official game wikis/fandoms (e.g. [VRChat Legends (Fandom)](https://vrchat-legends.fandom.com), official Genshin Impact wiki, etc.)
-- Official game pages, group listings, or public user profiles.
-- Other verified public sources (must be referenced in the PR description).
-
-If the source is not verifiable or permission is unclear, your PR will be closed.
-
----
-
-## 🚫 Community & Safety Guidelines
-
-All contributions must comply with the relevant game's Terms of Service and Community Guidelines, e.g. for VRChat:
-
-- **VRChat's Terms of Service**:
-  [https://hello.vrchat.com/legal](https://hello.vrchat.com/legal)
-
-- **VRChat's Community Guidelines**:
-  [https://hello.vrchat.com/community-guidelines](https://hello.vrchat.com/community-guidelines)
-
-### Forbidden Content:
-- Harassment, bullying, or targeted remarks.
-- Doxxing or sharing private user data.
-- Hate speech, NSFW content, or anything that violates a game's ToS or GitHub rules.
-- False, misleading, or defamatory information.
-
-Such PRs will be rejected and may result in a report to platform moderators.
-
----
-
-## 🖼️ Image Requirement
-
-Every JSON file **must include an `image` field** linking to a **safe, representative image** (world thumbnail, group
-logo, avatar/character art).
-
-Example:
-```json
-"image": "https://example.com/images/world.png"
-```
-
-Images must not contain:
-- Private or copyrighted art without permission.
-- NSFW or offensive visuals.
-
----
-
-## 🧩 JSON Format Guidelines
-
-Follow these formats exactly when adding files. New games should follow the same shape for whichever entity types
-apply to them.
-
-### 🌍 Worlds (`data/<game>/worlds/worldname.json`)
-```json
-{
-  "name": "The Black Cat",
-  "title": "Main Hall",
-  "creator": "spookyghostboo",
-  "aliases": "Black Cat",
-  "image": "https://example.com/images/world.jpg",
-  "description": "A cozy hangout world for friends.",
-  "url": "VRCHAT WORLD URL"
-}
-```
-
-### 👥 Groups (`data/<game>/groups/groupname.json`)
-```json
-{
-  "name": "NekoSune Community",
-  "owner": "NekoSuneVR",
-  "image": "https://example.com/images/group.png",
-  "description": "A friendly VRChat group for chill vibes and fun events.",
-  "url": "VRCHAT GROUP URL"
-}
-```
-
-### 🧍 Players (`data/<game>/players/playername.json`)
-```json
-{
-    "name": "NekoSuneVR",
-    "title": "The Cutie Streamer",
-    "species": "half human - half catgirl",
-    "gender": "Male",
-    "aliases": "ChisdealHDYT, Chisdeal2013, Chisdeal2014, ChisdealHD, progamer-gr, DarkBlackWolfs",
-    "image": "https://media.discordapp.net/attachments/794229972490387496/794231249652678696/VRChat_1920x1080_2020-09-14_09-22-18.855.png",
-    "description": "A long time ago, Wild Player Chisdeal2013 (later known as ChisdealHDYT). He had been hanging out in a place called [The Black Cat](https://vrchat-legends.fandom.com/wiki/The_Black_Cat), [The Great Pug](https://vrchat-legends.fandom.com/wiki/The_Great_Pug) and [Japan Shrine (ITOAR)](https://vrchat-legends.fandom.com/wiki/Japan_Shrine_(ITOAR)). He had been talking about how he wanted to be Popular on [Twitch](https://twitch.tv/chisdealhdyt) and [TikTok](https://www.tiktok.com/@chisdealhd) / [YouTube](https://www.youtube.com/chisdealhd). Then he did started to streaming on Twitch and Upload Videos on TikTok / YouTube. He loves interest Cryptocurrency Money making and has lot support from [ZENZO Community](https://zenzo.io). He building Community with VRChat, Warframe and many more. He want become as VTuber as Twitch and doing a lot of VR Gaming. That dream is coming very soon in stage getting VR Headset and Brand new VR Ready PC.\n\nYou should Support this Cutie Streamer much on your Heart it can go.",
-    "url": "https://creator.nekosunevr.co.uk"
-}
-```
-
-### 🧝 Characters (`data/<game>/characters/charactername.json`)
-```json
-{
-    "name": "Amber",
-    "quote": "Outrider Amber, at the ready!",
-    "cv": "Iwami Manaka",
-    "description": "A perky, straightforward girl, who is also the only Outrider of the Knights of Favonius.",
-    "image": "https://uploadstatic-sea.mihoyo.com/contentweb/20191009/2019100914372396510.png",
-    "city": "Mondstadt",
-    "url": "https://genshin.mihoyo.com/en/character/mondstadt?char=1",
-    "element": "Pyro",
-    "weapon": "Bow",
-    "rating": 4
-}
-```
-`element` stays a plain string (icon mapping is a consumer-side concern, not stored here).
-`rating` is the in-game star rarity (1-5) as a number. Include whatever fields apply to that
-game's characters (`cv`, `city`, etc.) and drop what doesn't.
-
-### 🎮 Game meta (`data/<game>/meta.json`)
-```json
-{
-  "name": "Genshin Impact",
-  "title": "An open-world action RPG developed by HoYoverse.",
-  "engine": "Unity",
-  "Platform": "PC, PlayStation, iOS, Android",
-  "Release date": "September 28, 2020",
-  "Genre": "Action RPG, Open World, Gacha",
-  "developers": "HoYoverse",
-  "aliases": "GI, Genshin",
-  "image": "https://example.com/images/genshin-logo.png",
-  "description": "Short factual description of the game.",
-  "url": "https://en.wikipedia.org/wiki/Genshin_Impact"
-}
-```
-
----
-
-## 🪶 How to Submit a Pull Request
-
-1. **Fork** this repository.
-2. **Create a new branch** for your changes:
-   ```bash
-   git checkout -b add-new-world
-   ```
-3. Add or update JSON files under `data/<game>/...`. If adding a **new game**, create `data/<newgame>/meta.json`
-   plus whichever entity folders apply (`worlds`, `groups`, `players`, `characters`, or a new type via `Get()`).
-4. Ensure your files are valid JSON and properly formatted.
-5. **Commit and push** your changes:
-   ```bash
-   git commit -m "Add Example World info"
-   git push origin add-new-world
-   ```
-6. **Open a Pull Request** on GitHub with:
-   - A clear title (e.g., "Add Genshin Impact character Furina")
-   - A short explanation
-   - Source links or permissions if applicable
-
----
-
-## 🔍 Before Submitting
-
-✅ Validate your JSON syntax using:
-```bash
-npm run lint
-```
-(if available) or an online JSON validator.
-
-✅ Make sure:
-- You have **permission** to share the content.
-- The **image link** works and is safe.
-- The **file name matches the item name** (lowercase recommended).
-- The file is in the correct `data/<game>/<type>/` folder.
-
----
-
-## 🧠 Final Notes
-
-- This project is **game-friendly** and follows all relevant ToS and Community Guidelines.
-- The maintainers reserve the right to remove or edit contributions that break policy.
-- All content remains under the [MIT License](LICENSE) unless otherwise noted.
-
----
-
-🐾 Maintained by **NekoSune Projects**
-💬 Community contributions are welcome — just keep it kind, safe, and respectful!