@voxary/valorant-client 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 valorant-client contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,122 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# valorant-client
+
+Typed TypeScript client for the unofficial Valorant API.
+
+- **176 endpoints** in 15 groups: PVP, party, store, pre-game, current game, contracts, local client, local chat, local voice,
+  Premier, esports, restrictions, account extras, Riot auth, and a static data catalog. Plus a live event stream for the local client.
+- **One context object** for everything that rarely changes (shard, region, tokens, client version, cookies, local port).
+  Replace or update it at any moment and the next request uses it.
+- **Typed end to end**: path parameters, query, body and results are inferred. Wrong calls fail at compile time.
+- **Validated responses** with the schemas of [`valorant-api-types`](https://github.com/techchrism/valorant-api-docs), in a mode that
+  survives game updates.
+- **Retries, rate limit handling and automatic token refresh.**
+- **Verified against a live client.** See [what was checked](docs/compatibility.md).
+
+> These endpoints are not officially supported by Riot and can change without notice. Use your own account only.
+
+## Install
+
+```bash
+npm install @voxary/valorant-client
+```
+
+Node 20.3+. ESM and CommonJS. Add `ws` for the local event stream.
+
+## Quick start
+
+```ts
+import {ValorantClient} from '@voxary/valorant-client'
+
+const client = new ValorantClient()
+
+// Riot Client running: fills tokens, puuid, region, shard and client version
+await client.local.connect()
+
+const mmr = await client.pvp.playerMmr()
+const history = await client.pvp.matchHistory({query: {startIndex: 0, endIndex: 10}})
+const store = await client.store.storefrontV3()
+const agents = await client.catalog.agents({query: {isPlayableCharacter: true}})
+```
+
+No local client? Provide the values or reauthenticate from saved cookies:
+
+```ts
+const client = new ValorantClient({
+    context: {shard: 'eu', region: 'eu', puuid, accessToken, entitlementToken, clientVersion},
+    refreshTokens: client => client.auth.reauthenticate()
+})
+```
+
+## The context
+
+```ts
+client.context.set('accessToken', token)
+client.context.update({shard: 'na', region: 'latam'})
+client.context.replace(otherAccountState)       // switch account
+client.context.applyAffinity('latam')           // region latam, shard na
+client.context.subscribe((state, changed) => save(state))
+```
+
+See [The context](docs/context.md).
+
+## Documentation
+
+| | |
+|-|-|
+| [Getting started](docs/getting-started.md) | Install, connect, first calls |
+| [The context](docs/context.md) | Shared state, persistence, switching accounts |
+| [Authentication](docs/authentication.md) | Local client, cookies, tokens, credentials |
+| [Calling endpoints](docs/calling-endpoints.md) | Parameters, query, body, results, validation |
+| [Errors and retries](docs/errors-and-retries.md) | Error classes, retries, token refresh |
+| [Local client](docs/local-client.md) | Lockfile, friends, chat, live events |
+| [Static data](docs/static-data.md) | Agents, skins, maps and ranks by UUID |
+| [Recipes](docs/recipes.md) | Rank, daily store, match recap, wallet |
+| [Testing and custom transports](docs/testing.md) | Mocks, proxies, other HTTP stacks |
+| [Compatibility](docs/compatibility.md) | Verified endpoints, known schema drift |
+| [API reference](docs/api/README.md) | Every endpoint, generated from the code |
+
+## Endpoint groups
+
+| Accessor | Endpoints | Notes |
+|----------|-----------|-------|
+| `client.pvp` | 13 | MMR, history, match details, loadout, XP, penalties, leaderboard |
+| `client.party` | 22 | Parties, queue, custom games, invite codes |
+| `client.store` | 7 | Wallet, storefront v3, entitlements, agent store |
+| `client.pregame` | 6 | Agent select |
+| `client.currentGame` | 4 | Match in progress |
+| `client.contracts` | 4 | Contracts, item upgrades, recruitment event |
+| `client.local` | 23 | Riot Client API, plus `connect()` and `events()` |
+| `client.chat` | 9 | Local chat |
+| `client.voice` | 3 | Local audio devices and levels |
+| `client.premier` | 7 | Premier seasons, conferences, eligibility, rosters |
+| `client.esports` | 3 | Esports schedule and pickem |
+| `client.restrictions` | 2 | Avoid list, active interventions |
+| `client.account` | 7 | Daily ticket, favorites, goldstars |
+| `client.auth` | 9 | Riot auth, plus `login()`, `reauthenticate()`, `establishSession()` |
+| `client.catalog` | 57 | Static data from valorant-api.com |
+
+## Validation modes
+
+`validation` is `loose` (default: report schema drift, return raw data), `strict` (throw) or `off`. The schemas are community-made,
+so `loose` keeps your program running when the game changes. Details in [Calling endpoints](docs/calling-endpoints.md#validation-modes).
+
+## Not covered
+
+The XMPP chat connection (raw TCP).
+
+## Development
+
+```bash
+npm run typecheck   # source, tests and documented recipes
+npm test            # unit tests, no network
+npm run build       # ESM + CJS + types
+npm run docs:api    # regenerate docs/api
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Credits and license
+
+MIT. Endpoint knowledge and schemas come from the community project
+[techchrism/valorant-api-docs](https://github.com/techchrism/valorant-api-docs) (MIT), and static data from
+[valorant-api.com](https://valorant-api.com). This project is not affiliated with Riot Games.