ani-client 1.4.0 → 1.4.2

package/README.md

@@ -182,7 +182,7 @@ The second parameter of `getMedia()` lets you opt-in to additional data. By defa
 
 | Option | Type | Default | Description |
 | --- | --- | --- | --- |
-| `characters` | `boolean \| { perPage?, sort? }` | — | Characters with their roles (MAIN, SUPPORTING, BACKGROUND) |
+| `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.) |
@@ -202,6 +202,17 @@ 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) =>
@@ -230,24 +241,45 @@ const anime = await client.getMedia(1, {
 
 | 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
 
 | Method | Description |
 | --- | --- |
-| `getStaff(id)` | Fetch a staff member by ID |
+| `getStaff(id, include?)` | Fetch a staff member by ID (optionally with media) |
 | `searchStaff(options?)` | Search for staff members |
 
 ```ts
 const staff = await client.getStaff(95001);
 const results = await client.searchStaff({ query: "Miyazaki" });
+
+// With media the staff member worked on
+const staffWithMedia = await client.getStaff(95001, { media: true });
+staffWithMedia.staffMedia?.nodes.forEach((m) => {
+  console.log(m.title.romaji, m.format, m.averageScore);
+});
+
+// Customize the number of media returned
+const staffWith5Media = await client.getStaff(95001, { media: { perPage: 5 } });
 ```
 
 ### Users
@@ -538,10 +570,12 @@ All types and enums are exported:
 
 ```ts
 import type {
-  Media, Character, Staff, User,
+  Media, Character, Staff, User, VoiceActor,
   AiringSchedule, MediaListEntry, Recommendation, StudioDetail,
   MediaEdge, MediaConnection, MediaCharacterEdge, MediaCharacterConnection,
+  CharacterMediaEdge, CharacterIncludeOptions,
   MediaStaffEdge, MediaStaffConnection, MediaIncludeOptions,
+  StaffMediaNode, StaffIncludeOptions,
   StreamingEpisode, ExternalLink, MediaStats, MediaRecommendationNode,
   PageInfo, PagedResult,
   CacheAdapter, AniListHooks, AniListClientOptions,

package/dist/index.d.mts

@@ -159,9 +159,27 @@ interface CharacterImage {
     large: string | null;
     medium: string | null;
 }
+/** Compact voice actor data returned inside character edges. */
+interface VoiceActor {
+    id: number;
+    name: {
+        first: string | null;
+        middle: string | null;
+        last: string | null;
+        full: string | null;
+        native: string | null;
+        userPreferred: string | null;
+    };
+    languageV2: string | null;
+    image: StaffImage;
+    gender: string | null;
+    primaryOccupations: string[];
+    siteUrl: string | null;
+}
 interface MediaCharacterEdge {
     role: CharacterRole;
     node: Omit<Character, "media">;
+    voiceActors?: VoiceActor[];
 }
 interface MediaCharacterConnection {
     edges: MediaCharacterEdge[];
@@ -248,6 +266,11 @@ interface Media {
     isAdult: boolean | null;
     siteUrl: string | null;
 }
+type CharacterMediaNode = Pick<Media, "id" | "title" | "type" | "coverImage" | "siteUrl">;
+interface CharacterMediaEdge {
+    node: CharacterMediaNode;
+    voiceActors?: VoiceActor[];
+}
 interface Character {
     id: number;
     name: CharacterName;
@@ -260,9 +283,15 @@ interface Character {
     favourites: number | null;
     siteUrl: string | null;
     media: {
-        nodes: Pick<Media, "id" | "title" | "type" | "coverImage" | "siteUrl">[];
+        nodes?: CharacterMediaNode[];
+        edges?: CharacterMediaEdge[];
     } | null;
 }
+/** Options for including extra data when fetching a character. */
+interface CharacterIncludeOptions {
+    /** Include voice actors for each media the character appears in. */
+    voiceActors?: boolean;
+}
 interface StaffName {
     first: string | null;
     middle: string | null;
@@ -274,6 +303,43 @@ interface StaffImage {
     large: string | null;
     medium: string | null;
 }
+/** A media node returned inside `Staff.staffMedia`. */
+interface StaffMediaNode {
+    id: number;
+    title: MediaTitle;
+    type: MediaType;
+    format: MediaFormat | null;
+    status: MediaStatus | null;
+    coverImage: MediaCoverImage;
+    bannerImage: string | null;
+    genres: string[];
+    averageScore: number | null;
+    meanScore: number | null;
+    popularity: number | null;
+    favourites: number | null;
+    episodes: number | null;
+    trending: number | null;
+    hashtag: string | null;
+    season: MediaSeason | null;
+    seasonYear: number | null;
+    startDate: FuzzyDate | null;
+    endDate: FuzzyDate | null;
+    nextAiringEpisode: {
+        id: number;
+        airingAt: number;
+        episode: number;
+        mediaId: number;
+        timeUntilAiring: number;
+    } | null;
+    studios: {
+        edges: {
+            node: {
+                name: string;
+            };
+        }[];
+    } | null;
+    siteUrl: string | null;
+}
 interface Staff {
     id: number;
     name: StaffName;
@@ -290,6 +356,19 @@ interface Staff {
     bloodType: string | null;
     favourites: number | null;
     siteUrl: string | null;
+    /** Media the staff member has worked on — only present when requested via include options. */
+    staffMedia?: {
+        nodes: StaffMediaNode[];
+    } | null;
+}
+/** Options to include additional related data when fetching a staff member by ID. */
+interface StaffIncludeOptions {
+    /** Include media the staff member has worked on.
+     *  `true` = 25 results sorted by popularity. Object form to customize. */
+    media?: boolean | {
+        perPage?: number;
+        sort?: boolean;
+    };
 }
 interface UserAvatar {
     large: string | null;
@@ -354,6 +433,8 @@ interface SearchCharacterOptions {
     sort?: CharacterSort[];
     page?: number;
     perPage?: number;
+    /** Include voice actors for each media the character appears in. */
+    voiceActors?: boolean;
 }
 interface SearchStaffOptions {
     query?: string;
@@ -523,6 +604,7 @@ interface MediaIncludeOptions {
     characters?: boolean | {
         perPage?: number;
         sort?: boolean;
+        voiceActors?: boolean;
     };
     /** Include staff members with their roles.
      *  `true` = 25 results sorted by relevance. Object form to customize. */
@@ -676,6 +758,9 @@ declare class AniListClient {
      * // Include characters sorted by role, 25 results
      * const anime = await client.getMedia(1, { characters: true });
      *
+     * // Include characters with voice actors
+     * const anime = await client.getMedia(1, { characters: { voiceActors: true } });
+     *
      * // Full control
      * const anime = await client.getMedia(1, {
      *   characters: { perPage: 50, sort: true },
@@ -720,24 +805,35 @@ declare class AniListClient {
      * Fetch a character by AniList ID.
      *
      * @param id - The AniList character ID
+     * @param include - Optional include options (e.g. voice actors)
      * @returns The character object
      *
      * @example
      * ```ts
      * const spike = await client.getCharacter(1);
      * console.log(spike.name.full); // "Spike Spiegel"
+     *
+     * // 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}`));
+     * });
      * ```
      */
-    getCharacter(id: number): Promise<Character>;
+    getCharacter(id: number, include?: CharacterIncludeOptions): Promise<Character>;
     /**
      * Search for characters by name.
      *
-     * @param options - Search / pagination parameters
+     * @param options - Search / pagination parameters (includes optional `voiceActors`)
      * @returns Paginated results with matching characters
      *
      * @example
      * ```ts
      * const result = await client.searchCharacters({ query: "Luffy", perPage: 5 });
+     *
+     * // With voice actors
+     * const result = await client.searchCharacters({ query: "Luffy", voiceActors: true });
      * ```
      */
     searchCharacters(options?: SearchCharacterOptions): Promise<PagedResult<Character>>;
@@ -745,15 +841,20 @@ declare class AniListClient {
      * Fetch a staff member by AniList ID.
      *
      * @param id - The AniList staff ID
+     * @param include - Optional include options to fetch related data (e.g. media)
      * @returns The staff object
      *
      * @example
      * ```ts
      * const staff = await client.getStaff(95001);
      * console.log(staff.name.full);
+     *
+     * // With media the staff worked on
+     * const staff = await client.getStaff(95001, { media: true });
+     * staff.staffMedia?.nodes.forEach((m) => console.log(m.title.romaji));
      * ```
      */
-    getStaff(id: number): Promise<Staff>;
+    getStaff(id: number, include?: StaffIncludeOptions): Promise<Staff>;
     /**
      * Search for staff (voice actors, directors, etc.).
      *
@@ -1161,4 +1262,4 @@ declare class RateLimiter {
     private sleep;
 }
 
-export { type AiringSchedule, AiringSort, AniListClient, type AniListClientOptions, AniListError, type AniListHooks, type CacheAdapter, type CacheOptions, type Character, type CharacterImage, type CharacterName, CharacterRole, CharacterSort, type ExternalLink, type FuzzyDate, type GetAiringOptions, type GetPlanningOptions, type GetRecentChaptersOptions, type GetRecommendationsOptions, type GetSeasonOptions, type GetUserMediaListOptions, type Media, type MediaCharacterConnection, type MediaCharacterEdge, type MediaConnection, type MediaCoverImage, type MediaEdge, MediaFormat, type MediaIncludeOptions, type MediaListEntry, MediaListSort, MediaListStatus, type MediaRecommendationNode, MediaRelationType, MediaSeason, MediaSort, type MediaStaffConnection, type MediaStaffEdge, type MediaStats, MediaStatus, type MediaTag, type MediaTitle, type MediaTrailer, MediaType, MemoryCache, type PageInfo, type PagedResult, type RateLimitOptions, RateLimiter, type Recommendation, RecommendationSort, RedisCache, type RedisCacheOptions, type RedisLikeClient, type ScoreDistribution, type SearchCharacterOptions, type SearchMediaOptions, type SearchStaffOptions, type SearchStudioOptions, type Staff, type StaffImage, type StaffName, type StatusDistribution, type StreamingEpisode, type Studio, type StudioConnection, type StudioDetail, type User, type UserAvatar, type UserStatistics };
+export { type AiringSchedule, AiringSort, AniListClient, type AniListClientOptions, AniListError, type AniListHooks, type CacheAdapter, type CacheOptions, type Character, type CharacterImage, type CharacterIncludeOptions, type CharacterMediaEdge, type CharacterName, CharacterRole, CharacterSort, type ExternalLink, type FuzzyDate, type GetAiringOptions, type GetPlanningOptions, type GetRecentChaptersOptions, type GetRecommendationsOptions, type GetSeasonOptions, type GetUserMediaListOptions, type Media, type MediaCharacterConnection, type MediaCharacterEdge, type MediaConnection, type MediaCoverImage, type MediaEdge, MediaFormat, type MediaIncludeOptions, type MediaListEntry, MediaListSort, MediaListStatus, type MediaRecommendationNode, MediaRelationType, MediaSeason, MediaSort, type MediaStaffConnection, type MediaStaffEdge, type MediaStats, MediaStatus, type MediaTag, type MediaTitle, type MediaTrailer, MediaType, MemoryCache, type PageInfo, type PagedResult, type RateLimitOptions, RateLimiter, type Recommendation, RecommendationSort, RedisCache, type RedisCacheOptions, type RedisLikeClient, type ScoreDistribution, type SearchCharacterOptions, type SearchMediaOptions, type SearchStaffOptions, type SearchStudioOptions, type Staff, type StaffImage, type StaffIncludeOptions, type StaffMediaNode, type StaffName, type StatusDistribution, type StreamingEpisode, type Studio, type StudioConnection, type StudioDetail, type User, type UserAvatar, type UserStatistics, type VoiceActor };

package/dist/index.d.ts

@@ -159,9 +159,27 @@ interface CharacterImage {
     large: string | null;
     medium: string | null;
 }
+/** Compact voice actor data returned inside character edges. */
+interface VoiceActor {
+    id: number;
+    name: {
+        first: string | null;
+        middle: string | null;
+        last: string | null;
+        full: string | null;
+        native: string | null;
+        userPreferred: string | null;
+    };
+    languageV2: string | null;
+    image: StaffImage;
+    gender: string | null;
+    primaryOccupations: string[];
+    siteUrl: string | null;
+}
 interface MediaCharacterEdge {
     role: CharacterRole;
     node: Omit<Character, "media">;
+    voiceActors?: VoiceActor[];
 }
 interface MediaCharacterConnection {
     edges: MediaCharacterEdge[];
@@ -248,6 +266,11 @@ interface Media {
     isAdult: boolean | null;
     siteUrl: string | null;
 }
+type CharacterMediaNode = Pick<Media, "id" | "title" | "type" | "coverImage" | "siteUrl">;
+interface CharacterMediaEdge {
+    node: CharacterMediaNode;
+    voiceActors?: VoiceActor[];
+}
 interface Character {
     id: number;
     name: CharacterName;
@@ -260,9 +283,15 @@ interface Character {
     favourites: number | null;
     siteUrl: string | null;
     media: {
-        nodes: Pick<Media, "id" | "title" | "type" | "coverImage" | "siteUrl">[];
+        nodes?: CharacterMediaNode[];
+        edges?: CharacterMediaEdge[];
     } | null;
 }
+/** Options for including extra data when fetching a character. */
+interface CharacterIncludeOptions {
+    /** Include voice actors for each media the character appears in. */
+    voiceActors?: boolean;
+}
 interface StaffName {
     first: string | null;
     middle: string | null;
@@ -274,6 +303,43 @@ interface StaffImage {
     large: string | null;
     medium: string | null;
 }
+/** A media node returned inside `Staff.staffMedia`. */
+interface StaffMediaNode {
+    id: number;
+    title: MediaTitle;
+    type: MediaType;
+    format: MediaFormat | null;
+    status: MediaStatus | null;
+    coverImage: MediaCoverImage;
+    bannerImage: string | null;
+    genres: string[];
+    averageScore: number | null;
+    meanScore: number | null;
+    popularity: number | null;
+    favourites: number | null;
+    episodes: number | null;
+    trending: number | null;
+    hashtag: string | null;
+    season: MediaSeason | null;
+    seasonYear: number | null;
+    startDate: FuzzyDate | null;
+    endDate: FuzzyDate | null;
+    nextAiringEpisode: {
+        id: number;
+        airingAt: number;
+        episode: number;
+        mediaId: number;
+        timeUntilAiring: number;
+    } | null;
+    studios: {
+        edges: {
+            node: {
+                name: string;
+            };
+        }[];
+    } | null;
+    siteUrl: string | null;
+}
 interface Staff {
     id: number;
     name: StaffName;
@@ -290,6 +356,19 @@ interface Staff {
     bloodType: string | null;
     favourites: number | null;
     siteUrl: string | null;
+    /** Media the staff member has worked on — only present when requested via include options. */
+    staffMedia?: {
+        nodes: StaffMediaNode[];
+    } | null;
+}
+/** Options to include additional related data when fetching a staff member by ID. */
+interface StaffIncludeOptions {
+    /** Include media the staff member has worked on.
+     *  `true` = 25 results sorted by popularity. Object form to customize. */
+    media?: boolean | {
+        perPage?: number;
+        sort?: boolean;
+    };
 }
 interface UserAvatar {
     large: string | null;
@@ -354,6 +433,8 @@ interface SearchCharacterOptions {
     sort?: CharacterSort[];
     page?: number;
     perPage?: number;
+    /** Include voice actors for each media the character appears in. */
+    voiceActors?: boolean;
 }
 interface SearchStaffOptions {
     query?: string;
@@ -523,6 +604,7 @@ interface MediaIncludeOptions {
     characters?: boolean | {
         perPage?: number;
         sort?: boolean;
+        voiceActors?: boolean;
     };
     /** Include staff members with their roles.
      *  `true` = 25 results sorted by relevance. Object form to customize. */
@@ -676,6 +758,9 @@ declare class AniListClient {
      * // Include characters sorted by role, 25 results
      * const anime = await client.getMedia(1, { characters: true });
      *
+     * // Include characters with voice actors
+     * const anime = await client.getMedia(1, { characters: { voiceActors: true } });
+     *
      * // Full control
      * const anime = await client.getMedia(1, {
      *   characters: { perPage: 50, sort: true },
@@ -720,24 +805,35 @@ declare class AniListClient {
      * Fetch a character by AniList ID.
      *
      * @param id - The AniList character ID
+     * @param include - Optional include options (e.g. voice actors)
      * @returns The character object
      *
      * @example
      * ```ts
      * const spike = await client.getCharacter(1);
      * console.log(spike.name.full); // "Spike Spiegel"
+     *
+     * // 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}`));
+     * });
      * ```
      */
-    getCharacter(id: number): Promise<Character>;
+    getCharacter(id: number, include?: CharacterIncludeOptions): Promise<Character>;
     /**
      * Search for characters by name.
      *
-     * @param options - Search / pagination parameters
+     * @param options - Search / pagination parameters (includes optional `voiceActors`)
      * @returns Paginated results with matching characters
      *
      * @example
      * ```ts
      * const result = await client.searchCharacters({ query: "Luffy", perPage: 5 });
+     *
+     * // With voice actors
+     * const result = await client.searchCharacters({ query: "Luffy", voiceActors: true });
      * ```
      */
     searchCharacters(options?: SearchCharacterOptions): Promise<PagedResult<Character>>;
@@ -745,15 +841,20 @@ declare class AniListClient {
      * Fetch a staff member by AniList ID.
      *
      * @param id - The AniList staff ID
+     * @param include - Optional include options to fetch related data (e.g. media)
      * @returns The staff object
      *
      * @example
      * ```ts
      * const staff = await client.getStaff(95001);
      * console.log(staff.name.full);
+     *
+     * // With media the staff worked on
+     * const staff = await client.getStaff(95001, { media: true });
+     * staff.staffMedia?.nodes.forEach((m) => console.log(m.title.romaji));
      * ```
      */
-    getStaff(id: number): Promise<Staff>;
+    getStaff(id: number, include?: StaffIncludeOptions): Promise<Staff>;
     /**
      * Search for staff (voice actors, directors, etc.).
      *
@@ -1161,4 +1262,4 @@ declare class RateLimiter {
     private sleep;
 }
 
-export { type AiringSchedule, AiringSort, AniListClient, type AniListClientOptions, AniListError, type AniListHooks, type CacheAdapter, type CacheOptions, type Character, type CharacterImage, type CharacterName, CharacterRole, CharacterSort, type ExternalLink, type FuzzyDate, type GetAiringOptions, type GetPlanningOptions, type GetRecentChaptersOptions, type GetRecommendationsOptions, type GetSeasonOptions, type GetUserMediaListOptions, type Media, type MediaCharacterConnection, type MediaCharacterEdge, type MediaConnection, type MediaCoverImage, type MediaEdge, MediaFormat, type MediaIncludeOptions, type MediaListEntry, MediaListSort, MediaListStatus, type MediaRecommendationNode, MediaRelationType, MediaSeason, MediaSort, type MediaStaffConnection, type MediaStaffEdge, type MediaStats, MediaStatus, type MediaTag, type MediaTitle, type MediaTrailer, MediaType, MemoryCache, type PageInfo, type PagedResult, type RateLimitOptions, RateLimiter, type Recommendation, RecommendationSort, RedisCache, type RedisCacheOptions, type RedisLikeClient, type ScoreDistribution, type SearchCharacterOptions, type SearchMediaOptions, type SearchStaffOptions, type SearchStudioOptions, type Staff, type StaffImage, type StaffName, type StatusDistribution, type StreamingEpisode, type Studio, type StudioConnection, type StudioDetail, type User, type UserAvatar, type UserStatistics };
+export { type AiringSchedule, AiringSort, AniListClient, type AniListClientOptions, AniListError, type AniListHooks, type CacheAdapter, type CacheOptions, type Character, type CharacterImage, type CharacterIncludeOptions, type CharacterMediaEdge, type CharacterName, CharacterRole, CharacterSort, type ExternalLink, type FuzzyDate, type GetAiringOptions, type GetPlanningOptions, type GetRecentChaptersOptions, type GetRecommendationsOptions, type GetSeasonOptions, type GetUserMediaListOptions, type Media, type MediaCharacterConnection, type MediaCharacterEdge, type MediaConnection, type MediaCoverImage, type MediaEdge, MediaFormat, type MediaIncludeOptions, type MediaListEntry, MediaListSort, MediaListStatus, type MediaRecommendationNode, MediaRelationType, MediaSeason, MediaSort, type MediaStaffConnection, type MediaStaffEdge, type MediaStats, MediaStatus, type MediaTag, type MediaTitle, type MediaTrailer, MediaType, MemoryCache, type PageInfo, type PagedResult, type RateLimitOptions, RateLimiter, type Recommendation, RecommendationSort, RedisCache, type RedisCacheOptions, type RedisLikeClient, type ScoreDistribution, type SearchCharacterOptions, type SearchMediaOptions, type SearchStaffOptions, type SearchStudioOptions, type Staff, type StaffImage, type StaffIncludeOptions, type StaffMediaNode, type StaffName, type StatusDistribution, type StreamingEpisode, type Studio, type StudioConnection, type StudioDetail, type User, type UserAvatar, type UserStatistics, type VoiceActor };