ani-client 1.3.0 → 1.4.1

package/README.md

@@ -7,7 +7,7 @@
 > A simple, typed client to fetch anime, manga, character, staff and user data from [AniList](https://anilist.co).
 
 - **Zero dependencies** — uses the native `fetch` API
-- **Universal** — Node.js ≥ 18, Bun, Deno and modern browsers
+- **Universal** — Node.js ≥ 20, Bun, Deno and modern browsers
 - **Dual format** — ships ESM + CJS with full TypeScript declarations
 - **Built-in caching** — in-memory LRU with optional Redis adapter
 - **Rate-limit aware** — auto-retry on 429, configurable timeout & network error retry
@@ -22,6 +22,7 @@
 - [Client options](#client-options)
 - [API reference](#api-reference)
   - [Media](#media)
+  - [Include options](#include-options)
   - [Characters](#characters)
   - [Staff](#staff)
   - [Users](#users)
@@ -145,15 +146,27 @@ const client = new AniListClient({
 
 | Method | Description |
 | --- | --- |
-| `getMedia(id)` | Fetch a single anime / manga by ID |
+| `getMedia(id, include?)` | Fetch a single anime / manga by ID with optional extra data |
 | `searchMedia(options?)` | Search & filter anime / manga |
 | `getTrending(type?, page?, perPage?)` | Currently trending entries |
 | `getMediaBySeason(options)` | Anime/manga for a given season & year |
 | `getRecommendations(mediaId, options?)` | User recommendations for a media |
 
 ```ts
+// Simple — same as before
 const anime = await client.getMedia(1);
 
+// With extra data
+const anime = await client.getMedia(1, {
+  characters: { perPage: 25, sort: true },
+  staff: true,
+  relations: true,
+  streamingEpisodes: true,
+  externalLinks: true,
+  stats: true,
+  recommendations: { perPage: 5 },
+});
+
 const results = await client.searchMedia({
   query: "Naruto",
   type: MediaType.ANIME,
@@ -163,16 +176,89 @@ const results = await client.searchMedia({
 });
 ```
 
+### Include options
+
+The second parameter of `getMedia()` lets you opt-in to additional data. By default, only `relations` are included for backward compatibility.
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `characters` | `boolean \| { perPage?, sort?, voiceActors? }` | — | Characters with their roles (MAIN, SUPPORTING, BACKGROUND). Set `voiceActors: true` to include VA data. |
+| `staff` | `boolean \| { perPage?, sort? }` | — | Staff members with their roles |
+| `relations` | `boolean` | `true` | Sequels, prequels, adaptations, etc. Set `false` to exclude |
+| `streamingEpisodes` | `boolean` | — | Streaming links (Crunchyroll, Funimation, etc.) |
+| `externalLinks` | `boolean` | — | External links (MAL, official site, etc.) |
+| `stats` | `boolean` | — | Score & status distribution |
+| `recommendations` | `boolean \| { perPage? }` | — | User recommendations |
+
+```ts
+// Include characters sorted by role (25 per page by default)
+const anime = await client.getMedia(1, { characters: true });
+anime.characters?.edges.forEach((e) =>
+  console.log(`${e.node.name.full} (${e.role})`)
+);
+
+// 50 characters, no sorting
+const anime = await client.getMedia(1, {
+  characters: { perPage: 50, sort: false },
+});
+
+// Include voice actors alongside characters
+const anime = await client.getMedia(1, {
+  characters: { voiceActors: true },
+});
+anime.characters?.edges.forEach((e) => {
+  console.log(e.node.name.full);
+  e.voiceActors?.forEach((va) =>
+    console.log(`  VA: ${va.name.full} (${va.languageV2})`)
+  );
+});
+
+// Staff members
+const anime = await client.getMedia(1, { staff: true });
+anime.staff?.edges.forEach((e) =>
+  console.log(`${e.node.name.full} — ${e.role}`)
+);
+
+// Everything at once
+const anime = await client.getMedia(1, {
+  characters: { perPage: 50 },
+  staff: { perPage: 25 },
+  relations: true,
+  streamingEpisodes: true,
+  externalLinks: true,
+  stats: true,
+  recommendations: { perPage: 10 },
+});
+
+// Lightweight — exclude relations
+const anime = await client.getMedia(1, {
+  characters: true,
+  relations: false,
+});
+```
+
 ### Characters
 
 | Method | Description |
 | --- | --- |
-| `getCharacter(id)` | Fetch a character by ID |
-| `searchCharacters(options?)` | Search characters by name |
+| `getCharacter(id, include?)` | Fetch a character by ID, optionally with voice actors |
+| `searchCharacters(options?)` | Search characters by name, optionally with voice actors |
 
 ```ts
 const spike = await client.getCharacter(1);
 const results = await client.searchCharacters({ query: "Luffy", perPage: 5 });
+
+// With voice actors
+const spike = await client.getCharacter(1, { voiceActors: true });
+spike.media?.edges?.forEach((e) => {
+  console.log(e.node.title.romaji);
+  e.voiceActors?.forEach((va) =>
+    console.log(`  VA: ${va.name.full} (${va.languageV2})`)
+  );
+});
+
+// Search with voice actors
+const result = await client.searchCharacters({ query: "Luffy", voiceActors: true });
 ```
 
 ### Staff
@@ -266,13 +352,16 @@ recs.results.forEach((r) =>
 
 ### Relations
 
-Every media object includes a `relations` field with sequels, prequels, spin-offs, etc.
+Relations (sequels, prequels, spin-offs, etc.) are included by default when using `getMedia()`. You can also explicitly request them via the `include` parameter, or exclude them with `relations: false`.
 
 ```ts
 const anime = await client.getMedia(1);
 anime.relations?.edges.forEach((edge) =>
   console.log(`${edge.relationType}: ${edge.node.title.romaji}`)
 );
+
+// Exclude relations for a lighter response
+const anime = await client.getMedia(1, { relations: false });
 ```
 
 Available types: `ADAPTATION`, `PREQUEL`, `SEQUEL`, `PARENT`, `SIDE_STORY`, `CHARACTER`, `SUMMARY`, `ALTERNATIVE`, `SPIN_OFF`, `OTHER`, `SOURCE`, `COMPILATION`, `CONTAINS`.
@@ -472,9 +561,13 @@ All types and enums are exported:
 
 ```ts
 import type {
-  Media, Character, Staff, User,
+  Media, Character, Staff, User, VoiceActor,
   AiringSchedule, MediaListEntry, Recommendation, StudioDetail,
-  MediaEdge, MediaConnection, PageInfo, PagedResult,
+  MediaEdge, MediaConnection, MediaCharacterEdge, MediaCharacterConnection,
+  CharacterMediaEdge, CharacterIncludeOptions,
+  MediaStaffEdge, MediaStaffConnection, MediaIncludeOptions,
+  StreamingEpisode, ExternalLink, MediaStats, MediaRecommendationNode,
+  PageInfo, PagedResult,
   CacheAdapter, AniListHooks, AniListClientOptions,
   SearchMediaOptions, SearchCharacterOptions, SearchStaffOptions,
   SearchStudioOptions, GetAiringOptions, GetRecentChaptersOptions,
@@ -484,7 +577,7 @@ import type {
 
 import {
   MediaType, MediaFormat, MediaStatus, MediaSeason, MediaSort,
-  CharacterSort, AiringSort, RecommendationSort,
+  CharacterSort, CharacterRole, AiringSort, RecommendationSort,
   MediaRelationType, MediaListStatus, MediaListSort,
 } from "ani-client";
 ```