ani-client 2.0.2 → 2.0.3

package/README.md

@@ -22,6 +22,7 @@
 - **Rate-limit protection** with exponential backoff, retries, and custom strategies
 - **Request deduplication** — concurrent identical queries share a single in-flight request
 - **Batch queries** — fetch up to 50 media/characters/staff in one API call
+- **Paginated media relationships** — `getMediaCharacters()` and `getMediaStaff()` support paged results for large casts and staff listings
 - **Auto-pagination** — async iterator that yields items across pages
 - **AbortSignal support** — cancel globally or per-request with `withSignal()`
 - **Injectable logger** — plug in `console`, pino, winston, or any compatible logger
@@ -58,6 +59,10 @@ const results = await client.searchMedia({
 
 // Cross-platform lookup by MyAnimeList ID
 const fma = await client.getMediaByMalId(5114);
+
+// Paginated media relationships
+const characters = await client.getMediaCharacters(1, { page: 1, perPage: 25, voiceActors: true });
+const staff = await client.getMediaStaff(1, { page: 1, perPage: 25 });
 ```
 
 ## Features at a glance
@@ -134,6 +139,8 @@ for await (const anime of client.paginate(
 const user = await client.getUser("AniList");
 const favs = await client.getUserFavorites("AniList", { perPage: 50 });
 const char = await client.getCharacter(1, { voiceActors: true });
+const characters = await client.getMediaCharacters(1, { page: 1, perPage: 25, voiceActors: true });
+const staff = await client.getMediaStaff(1, { page: 1, perPage: 25 });
 const studio = await client.getStudio(21, { media: { perPage: 50 } });
 const schedule = await client.getWeeklySchedule();
 ```

package/dist/index.d.mts

@@ -59,7 +59,7 @@ interface CacheOptions {
 }
 /** Rate limiter configuration options. */
 interface RateLimitOptions {
-    /** Max requests per window (default: 85) */
+    /** Max requests per window (default: 25) */
     maxRequests?: number;
     /** Window size in ms (default: 60 000) */
     windowMs?: number;
@@ -852,6 +852,24 @@ interface MediaIncludeOptions {
         perPage?: number;
     };
 }
+interface GetMediaCharactersOptions {
+    /** Page number */
+    page?: number;
+    /** Results per page (max 50) */
+    perPage?: number;
+    /** Disable default sort order */
+    sort?: boolean;
+    /** Include voice actors for each character edge */
+    voiceActors?: boolean;
+}
+interface GetMediaStaffOptions {
+    /** Page number */
+    page?: number;
+    /** Results per page (max 50) */
+    perPage?: number;
+    /** Disable default sort order */
+    sort?: boolean;
+}
 interface AiringSchedule {
     id: number;
     airingAt: number;
@@ -1198,6 +1216,8 @@ declare class AniListClient {
      * @param include - Optional related data to include
      */
     getMedia(id: number, include?: MediaIncludeOptions): Promise<Media>;
+    getMediaCharacters(mediaId: number, options?: GetMediaCharactersOptions): Promise<PagedResult<MediaCharacterEdge>>;
+    getMediaStaff(mediaId: number, options?: GetMediaStaffOptions): Promise<PagedResult<MediaStaffEdge>>;
     /**
      * Search for anime or manga.
      *
@@ -1220,7 +1240,7 @@ declare class AniListClient {
      */
     getRecentlyUpdatedManga(options?: GetRecentChaptersOptions): Promise<PagedResult<Media>>;
     /**
-     * @deprecated Use `getRecentlyUpdatedManga` instead. This alias will be removed in v2.
+     * @deprecated Use `getRecentlyUpdatedManga()` instead. This alias will be removed in v3.
      */
     getAiredChapters(options?: GetRecentChaptersOptions): Promise<PagedResult<Media>>;
     /**
@@ -1392,4 +1412,4 @@ declare class RateLimiter {
 
 declare function parseAniListMarkdown(text: string): string;
 
-export { type AiringSchedule, AiringSort, AniListClient, type AniListClientOptions, AniListError, type AniListHooks, type CacheAdapter, type CacheOptions, type CacheStats, type Character, type CharacterImage, type CharacterIncludeOptions, type CharacterMediaEdge, type CharacterName, CharacterRole, CharacterSort, type DayOfWeek, type ExternalLink, type FavoriteCharacterNode, type FavoriteMediaNode, type FavoriteStaffNode, type FavoriteStudioNode, type FuzzyDate, type GetAiringOptions, type GetPlanningOptions, type GetRecentChaptersOptions, type GetRecommendationsOptions, type GetSeasonOptions, type GetUserMediaListOptions, type Logger, type Media, type MediaCharacterConnection, type MediaCharacterEdge, type MediaConnection, type MediaCoverImage, type MediaEdge, MediaFormat, type MediaIncludeOptions, type MediaListEntry, MediaListSort, MediaListStatus, type MediaRecommendationNode, MediaRelationType, MediaSeason, MediaSort, MediaSource, type MediaStaffConnection, type MediaStaffEdge, type MediaStats, MediaStatus, type MediaTag, type MediaTitle, type MediaTrailer, MediaType, MemoryCache, type NextAiringEpisode, type PageInfo, type PagedResult, type RateLimitInfo, type RateLimitOptions, RateLimiter, type Recommendation, RecommendationSort, RedisCache, type RedisCacheOptions, type RedisLikeClient, type ResponseMeta, type ScoreDistribution, type SearchCharacterOptions, type SearchMediaOptions, type SearchStaffOptions, type SearchStudioOptions, type SearchThreadOptions, type SearchUserOptions, type Staff, type StaffImage, type StaffIncludeOptions, type StaffMediaNode, type StaffName, StaffSort, type StatusDistribution, type StreamingEpisode, type Studio, type StudioConnection, type StudioIncludeOptions, StudioSort, type Thread, type ThreadCategory, type ThreadMediaCategory, ThreadSort, type User, type UserAvatar, type UserFavorites, type UserFavoritesOptions, UserSort, type UserStatistics, type VoiceActor, type WeeklySchedule, parseAniListMarkdown };
+export { type AiringSchedule, AiringSort, AniListClient, type AniListClientOptions, AniListError, type AniListHooks, type CacheAdapter, type CacheOptions, type CacheStats, type Character, type CharacterImage, type CharacterIncludeOptions, type CharacterMediaEdge, type CharacterName, CharacterRole, CharacterSort, type DayOfWeek, type ExternalLink, type FavoriteCharacterNode, type FavoriteMediaNode, type FavoriteStaffNode, type FavoriteStudioNode, type FuzzyDate, type GetAiringOptions, type GetMediaCharactersOptions, type GetMediaStaffOptions, type GetPlanningOptions, type GetRecentChaptersOptions, type GetRecommendationsOptions, type GetSeasonOptions, type GetUserMediaListOptions, type Logger, type Media, type MediaCharacterConnection, type MediaCharacterEdge, type MediaConnection, type MediaCoverImage, type MediaEdge, MediaFormat, type MediaIncludeOptions, type MediaListEntry, MediaListSort, MediaListStatus, type MediaRecommendationNode, MediaRelationType, MediaSeason, MediaSort, MediaSource, type MediaStaffConnection, type MediaStaffEdge, type MediaStats, MediaStatus, type MediaTag, type MediaTitle, type MediaTrailer, MediaType, MemoryCache, type NextAiringEpisode, type PageInfo, type PagedResult, type RateLimitInfo, type RateLimitOptions, RateLimiter, type Recommendation, RecommendationSort, RedisCache, type RedisCacheOptions, type RedisLikeClient, type ResponseMeta, type ScoreDistribution, type SearchCharacterOptions, type SearchMediaOptions, type SearchStaffOptions, type SearchStudioOptions, type SearchThreadOptions, type SearchUserOptions, type Staff, type StaffImage, type StaffIncludeOptions, type StaffMediaNode, type StaffName, StaffSort, type StatusDistribution, type StreamingEpisode, type Studio, type StudioConnection, type StudioIncludeOptions, StudioSort, type Thread, type ThreadCategory, type ThreadMediaCategory, ThreadSort, type User, type UserAvatar, type UserFavorites, type UserFavoritesOptions, UserSort, type UserStatistics, type VoiceActor, type WeeklySchedule, parseAniListMarkdown };

package/dist/index.d.ts

@@ -59,7 +59,7 @@ interface CacheOptions {
 }
 /** Rate limiter configuration options. */
 interface RateLimitOptions {
-    /** Max requests per window (default: 85) */
+    /** Max requests per window (default: 25) */
     maxRequests?: number;
     /** Window size in ms (default: 60 000) */
     windowMs?: number;
@@ -852,6 +852,24 @@ interface MediaIncludeOptions {
         perPage?: number;
     };
 }
+interface GetMediaCharactersOptions {
+    /** Page number */
+    page?: number;
+    /** Results per page (max 50) */
+    perPage?: number;
+    /** Disable default sort order */
+    sort?: boolean;
+    /** Include voice actors for each character edge */
+    voiceActors?: boolean;
+}
+interface GetMediaStaffOptions {
+    /** Page number */
+    page?: number;
+    /** Results per page (max 50) */
+    perPage?: number;
+    /** Disable default sort order */
+    sort?: boolean;
+}
 interface AiringSchedule {
     id: number;
     airingAt: number;
@@ -1198,6 +1216,8 @@ declare class AniListClient {
      * @param include - Optional related data to include
      */
     getMedia(id: number, include?: MediaIncludeOptions): Promise<Media>;
+    getMediaCharacters(mediaId: number, options?: GetMediaCharactersOptions): Promise<PagedResult<MediaCharacterEdge>>;
+    getMediaStaff(mediaId: number, options?: GetMediaStaffOptions): Promise<PagedResult<MediaStaffEdge>>;
     /**
      * Search for anime or manga.
      *
@@ -1220,7 +1240,7 @@ declare class AniListClient {
      */
     getRecentlyUpdatedManga(options?: GetRecentChaptersOptions): Promise<PagedResult<Media>>;
     /**
-     * @deprecated Use `getRecentlyUpdatedManga` instead. This alias will be removed in v2.
+     * @deprecated Use `getRecentlyUpdatedManga()` instead. This alias will be removed in v3.
      */
     getAiredChapters(options?: GetRecentChaptersOptions): Promise<PagedResult<Media>>;
     /**
@@ -1392,4 +1412,4 @@ declare class RateLimiter {
 
 declare function parseAniListMarkdown(text: string): string;
 
-export { type AiringSchedule, AiringSort, AniListClient, type AniListClientOptions, AniListError, type AniListHooks, type CacheAdapter, type CacheOptions, type CacheStats, type Character, type CharacterImage, type CharacterIncludeOptions, type CharacterMediaEdge, type CharacterName, CharacterRole, CharacterSort, type DayOfWeek, type ExternalLink, type FavoriteCharacterNode, type FavoriteMediaNode, type FavoriteStaffNode, type FavoriteStudioNode, type FuzzyDate, type GetAiringOptions, type GetPlanningOptions, type GetRecentChaptersOptions, type GetRecommendationsOptions, type GetSeasonOptions, type GetUserMediaListOptions, type Logger, type Media, type MediaCharacterConnection, type MediaCharacterEdge, type MediaConnection, type MediaCoverImage, type MediaEdge, MediaFormat, type MediaIncludeOptions, type MediaListEntry, MediaListSort, MediaListStatus, type MediaRecommendationNode, MediaRelationType, MediaSeason, MediaSort, MediaSource, type MediaStaffConnection, type MediaStaffEdge, type MediaStats, MediaStatus, type MediaTag, type MediaTitle, type MediaTrailer, MediaType, MemoryCache, type NextAiringEpisode, type PageInfo, type PagedResult, type RateLimitInfo, type RateLimitOptions, RateLimiter, type Recommendation, RecommendationSort, RedisCache, type RedisCacheOptions, type RedisLikeClient, type ResponseMeta, type ScoreDistribution, type SearchCharacterOptions, type SearchMediaOptions, type SearchStaffOptions, type SearchStudioOptions, type SearchThreadOptions, type SearchUserOptions, type Staff, type StaffImage, type StaffIncludeOptions, type StaffMediaNode, type StaffName, StaffSort, type StatusDistribution, type StreamingEpisode, type Studio, type StudioConnection, type StudioIncludeOptions, StudioSort, type Thread, type ThreadCategory, type ThreadMediaCategory, ThreadSort, type User, type UserAvatar, type UserFavorites, type UserFavoritesOptions, UserSort, type UserStatistics, type VoiceActor, type WeeklySchedule, parseAniListMarkdown };
+export { type AiringSchedule, AiringSort, AniListClient, type AniListClientOptions, AniListError, type AniListHooks, type CacheAdapter, type CacheOptions, type CacheStats, type Character, type CharacterImage, type CharacterIncludeOptions, type CharacterMediaEdge, type CharacterName, CharacterRole, CharacterSort, type DayOfWeek, type ExternalLink, type FavoriteCharacterNode, type FavoriteMediaNode, type FavoriteStaffNode, type FavoriteStudioNode, type FuzzyDate, type GetAiringOptions, type GetMediaCharactersOptions, type GetMediaStaffOptions, type GetPlanningOptions, type GetRecentChaptersOptions, type GetRecommendationsOptions, type GetSeasonOptions, type GetUserMediaListOptions, type Logger, type Media, type MediaCharacterConnection, type MediaCharacterEdge, type MediaConnection, type MediaCoverImage, type MediaEdge, MediaFormat, type MediaIncludeOptions, type MediaListEntry, MediaListSort, MediaListStatus, type MediaRecommendationNode, MediaRelationType, MediaSeason, MediaSort, MediaSource, type MediaStaffConnection, type MediaStaffEdge, type MediaStats, MediaStatus, type MediaTag, type MediaTitle, type MediaTrailer, MediaType, MemoryCache, type NextAiringEpisode, type PageInfo, type PagedResult, type RateLimitInfo, type RateLimitOptions, RateLimiter, type Recommendation, RecommendationSort, RedisCache, type RedisCacheOptions, type RedisLikeClient, type ResponseMeta, type ScoreDistribution, type SearchCharacterOptions, type SearchMediaOptions, type SearchStaffOptions, type SearchStudioOptions, type SearchThreadOptions, type SearchUserOptions, type Staff, type StaffImage, type StaffIncludeOptions, type StaffMediaNode, type StaffName, StaffSort, type StatusDistribution, type StreamingEpisode, type Studio, type StudioConnection, type StudioIncludeOptions, StudioSort, type Thread, type ThreadCategory, type ThreadMediaCategory, ThreadSort, type User, type UserAvatar, type UserFavorites, type UserFavoritesOptions, UserSort, type UserStatistics, type VoiceActor, type WeeklySchedule, parseAniListMarkdown };

package/dist/index.js

@@ -974,6 +974,44 @@ query ($id: Int!) {
   }
 }`;
 }
+function buildMediaCharactersQuery(options = {}) {
+  const sortClause = options.sort === false ? "" : ", sort: [ROLE, RELEVANCE, ID]";
+  const voiceActorBlock = options.voiceActors ? `
+            voiceActors {
+              ${VOICE_ACTOR_FIELDS_COMPACT}
+            }` : "";
+  return `
+query ($mediaId: Int!, $page: Int, $perPage: Int) {
+  Media(id: $mediaId) {
+    characters(page: $page, perPage: $perPage${sortClause}) {
+      pageInfo { total perPage currentPage lastPage hasNextPage }
+      edges {
+        role
+        node {
+          ${CHARACTER_FIELDS_COMPACT}
+        }${voiceActorBlock}
+      }
+    }
+  }
+}`;
+}
+function buildMediaStaffQuery(options = {}) {
+  const sortClause = options.sort === false ? "" : ", sort: [RELEVANCE, ID]";
+  return `
+query ($mediaId: Int!, $page: Int, $perPage: Int) {
+  Media(id: $mediaId) {
+    staff(page: $page, perPage: $perPage${sortClause}) {
+      pageInfo { total perPage currentPage lastPage hasNextPage }
+      edges {
+        role
+        node {
+          ${STAFF_FIELDS}
+        }
+      }
+    }
+  }
+}`;
+}
 function buildBatchQuery(ids, typeName, fields, prefix) {
   const aliases = ids.map((id, i) => `${prefix}${i}: ${typeName}(id: ${id}) { ${fields} }`).join("\n  ");
   return `query {
@@ -1626,6 +1664,25 @@ async function getMedia(client, id, include) {
   const data = await client.request(query, { id });
   return data.Media;
 }
+async function getMediaCharacters(client, mediaId, options = {}) {
+  validateId(mediaId, "mediaId");
+  const query = buildMediaCharactersQuery(options);
+  const data = await client.request(
+    query,
+    { mediaId, page: options.page ?? 1, perPage: clampPerPage(options.perPage ?? 25) }
+  );
+  return { pageInfo: data.Media.characters.pageInfo, results: data.Media.characters.edges };
+}
+async function getMediaStaff(client, mediaId, options = {}) {
+  validateId(mediaId, "mediaId");
+  const query = buildMediaStaffQuery(options);
+  const data = await client.request(query, {
+    mediaId,
+    page: options.page ?? 1,
+    perPage: clampPerPage(options.perPage ?? 25)
+  });
+  return { pageInfo: data.Media.staff.pageInfo, results: data.Media.staff.edges };
+}
 async function getMediaByMalId(client, malId, type) {
   validateId(malId, "malId");
   const data = await client.request(QUERY_MEDIA_BY_MAL_ID, {
@@ -1910,7 +1967,7 @@ function mapFavorites(fav) {
 
 // src/client/index.ts
 var DEFAULT_API_URL = "https://graphql.anilist.co";
-var LIB_VERSION = "2.0.2" ;
+var LIB_VERSION = "2.0.3" ;
 var AniListClient = class {
   apiUrl;
   headers;
@@ -2053,6 +2110,12 @@ var AniListClient = class {
   async getMedia(id, include) {
     return getMedia(this, id, include);
   }
+  async getMediaCharacters(mediaId, options = {}) {
+    return getMediaCharacters(this, mediaId, options);
+  }
+  async getMediaStaff(mediaId, options = {}) {
+    return getMediaStaff(this, mediaId, options);
+  }
   /**
    * Search for anime or manga.
    *
@@ -2087,7 +2150,7 @@ var AniListClient = class {
     return getRecentlyUpdatedManga(this, options);
   }
   /**
-   * @deprecated Use `getRecentlyUpdatedManga` instead. This alias will be removed in v2.
+   * @deprecated Use `getRecentlyUpdatedManga()` instead. This alias will be removed in v3.
    */
   async getAiredChapters(options = {}) {
     return this.getRecentlyUpdatedManga(options);