raiderio-api 0.0.1

package/README.md

@@ -0,0 +1,99 @@
+# raiderio-api
+
+A typed Node.js client and helpers for the [Raider.io API](https://raider.io/api).
+
+- **Fully typed** — every endpoint returns a parsed, typed response.
+- **Grouped by area** — `character`, `general`, `guild`, `mythicPlus`, `raiding`.
+- **Tiny runtime** — built on [`ky`](https://github.com/sindresorhus/ky). ESM-only.
+- **No API key required** — the Raider.io API is public; most endpoints work without one.
+
+## Install
+
+```sh
+npm install raiderio-api
+# or
+pnpm add raiderio-api
+```
+
+> Requires Node.js `^20.19.0 || ^22.13.0 || >=24`. This package is **ESM-only**.
+
+## Quick start
+
+```ts
+import { createRaiderioClient } from 'raiderio-api'
+
+const client = createRaiderioClient()
+
+const profile = await client.character.profile('eu', 'ysondre', 'melestra', [
+  'gear',
+  'mythic_plus_scores_by_season'
+])
+
+console.log(profile.name, profile.gear?.item_level_equipped)
+```
+
+You can also instantiate the class directly:
+
+```ts
+import { RaiderioClient } from 'raiderio-api'
+
+const client = new RaiderioClient()
+```
+
+## Options
+
+```ts
+const client = createRaiderioClient({
+  // Optional. Most endpoints are public and work without a key.
+  key: process.env.RAIDERIO_API_KEY,
+  // Optional. Forwarded to the underlying `ky` instance
+  // (timeout, retry, hooks, custom fetch, etc.).
+  kyOptions: {
+    timeout: 10_000,
+    retry: 2
+  }
+})
+```
+
+Per-request overrides are supported on the escape hatch (see below).
+
+## Endpoints
+
+Each method returns a `Promise` of the fully-typed response.
+
+| Group        | Methods                                                                                             |
+| ------------ | --------------------------------------------------------------------------------------------------- |
+| `character`  | `profile`                                                                                           |
+| `general`    | `periods`                                                                                           |
+| `guild`      | `bossKill`, `profile`                                                                               |
+| `mythicPlus` | `affixes`, `leaderboardCapacity`, `runDetails`, `runs`, `scoreTiers`, `seasonCutoffs`, `staticData` |
+| `raiding`    | `bossRankings`, `hallOfFame`, `progression`, `raidRankings`, `staticData`                           |
+
+```ts
+const affixes = await client.mythicPlus.affixes('us', 'en')
+const periods = await client.general.periods()
+const guild = await client.guild.profile('us', 'illidan', 'liquid', [
+  'raid_progression'
+])
+```
+
+## Advanced: resource builders + escape hatch
+
+Every endpoint is backed by a standalone **resource builder** that returns a
+`Resource` description (`path` + `query`). You can build one by hand and send it
+through the client, with optional per-request overrides:
+
+```ts
+import { createRaiderioClient, characterProfile } from 'raiderio-api'
+
+const client = createRaiderioClient()
+
+const resource = characterProfile('eu', 'ysondre', 'melestra', ['gear'])
+const profile = await client.request(resource, { key: 'per-request-key' })
+```
+
+The low-level `HttpClient` is also exported for fully custom setups.
+
+## License
+
+[MIT](./LICENSE)