ani-client 1.3.0 → 1.4.1

package/dist/index.d.ts

@@ -29,21 +29,37 @@ declare enum MediaSeason {
 }
 declare enum MediaSort {
     ID = "ID",
+    ID_DESC = "ID_DESC",
     TITLE_ROMAJI = "TITLE_ROMAJI",
+    TITLE_ROMAJI_DESC = "TITLE_ROMAJI_DESC",
     TITLE_ENGLISH = "TITLE_ENGLISH",
+    TITLE_ENGLISH_DESC = "TITLE_ENGLISH_DESC",
     TITLE_NATIVE = "TITLE_NATIVE",
+    TITLE_NATIVE_DESC = "TITLE_NATIVE_DESC",
     TYPE = "TYPE",
+    TYPE_DESC = "TYPE_DESC",
     FORMAT = "FORMAT",
+    FORMAT_DESC = "FORMAT_DESC",
     START_DATE = "START_DATE",
+    START_DATE_DESC = "START_DATE_DESC",
     END_DATE = "END_DATE",
+    END_DATE_DESC = "END_DATE_DESC",
     SCORE = "SCORE",
+    SCORE_DESC = "SCORE_DESC",
     POPULARITY = "POPULARITY",
+    POPULARITY_DESC = "POPULARITY_DESC",
     TRENDING = "TRENDING",
+    TRENDING_DESC = "TRENDING_DESC",
     EPISODES = "EPISODES",
+    EPISODES_DESC = "EPISODES_DESC",
     DURATION = "DURATION",
+    DURATION_DESC = "DURATION_DESC",
     STATUS = "STATUS",
+    STATUS_DESC = "STATUS_DESC",
     FAVOURITES = "FAVOURITES",
+    FAVOURITES_DESC = "FAVOURITES_DESC",
     UPDATED_AT = "UPDATED_AT",
+    UPDATED_AT_DESC = "UPDATED_AT_DESC",
     SEARCH_MATCH = "SEARCH_MATCH"
 }
 declare enum AiringSort {
@@ -58,9 +74,17 @@ declare enum AiringSort {
 }
 declare enum CharacterSort {
     ID = "ID",
+    ID_DESC = "ID_DESC",
     ROLE = "ROLE",
+    ROLE_DESC = "ROLE_DESC",
     SEARCH_MATCH = "SEARCH_MATCH",
-    FAVOURITES = "FAVOURITES"
+    FAVOURITES = "FAVOURITES",
+    FAVOURITES_DESC = "FAVOURITES_DESC"
+}
+declare enum CharacterRole {
+    MAIN = "MAIN",
+    SUPPORTING = "SUPPORTING",
+    BACKGROUND = "BACKGROUND"
 }
 interface MediaTitle {
     romaji: string | null;
@@ -135,6 +159,69 @@ 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[];
+}
+interface MediaStaffEdge {
+    role: string;
+    node: Staff;
+}
+interface MediaStaffConnection {
+    edges: MediaStaffEdge[];
+}
+interface StreamingEpisode {
+    title: string | null;
+    thumbnail: string | null;
+    url: string | null;
+    site: string | null;
+}
+interface ExternalLink {
+    id: number;
+    url: string | null;
+    site: string;
+    type: string | null;
+    icon: string | null;
+    color: string | null;
+}
+interface ScoreDistribution {
+    score: number;
+    amount: number;
+}
+interface StatusDistribution {
+    status: MediaListStatus | string;
+    amount: number;
+}
+interface MediaStats {
+    scoreDistribution: ScoreDistribution[];
+    statusDistribution: StatusDistribution[];
+}
+interface MediaRecommendationNode {
+    id: number;
+    rating: number | null;
+    mediaRecommendation: Pick<Media, "id" | "title" | "type" | "format" | "coverImage" | "averageScore" | "siteUrl">;
+}
 interface Media {
     id: number;
     idMal: number | null;
@@ -168,9 +255,22 @@ interface Media {
     tags: MediaTag[];
     studios: StudioConnection;
     relations: MediaConnection | null;
+    characters?: MediaCharacterConnection;
+    staff?: MediaStaffConnection;
+    streamingEpisodes?: StreamingEpisode[];
+    externalLinks?: ExternalLink[];
+    stats?: MediaStats;
+    recommendations?: {
+        nodes: MediaRecommendationNode[];
+    };
     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;
@@ -183,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;
@@ -207,7 +313,7 @@ interface Staff {
     gender: string | null;
     dateOfBirth: FuzzyDate | null;
     dateOfDeath: FuzzyDate | null;
-    age: number | null;
+    age: string | null;
     yearsActive: number[];
     homeTown: string | null;
     bloodType: string | null;
@@ -277,9 +383,12 @@ interface SearchCharacterOptions {
     sort?: CharacterSort[];
     page?: number;
     perPage?: number;
+    /** Include voice actors for each media the character appears in. */
+    voiceActors?: boolean;
 }
 interface SearchStaffOptions {
     query?: string;
+    sort?: CharacterSort[];
     page?: number;
     perPage?: number;
 }
@@ -435,6 +544,37 @@ interface SearchStudioOptions {
     page?: number;
     perPage?: number;
 }
+/**
+ * Options to include additional related data when fetching a media entry.
+ * Pass `true` to include with defaults, or an object to customize.
+ */
+interface MediaIncludeOptions {
+    /** Include characters with their roles (MAIN, SUPPORTING, BACKGROUND).
+     *  `true` = 25 results sorted by role. Object form to customize. */
+    characters?: boolean | {
+        perPage?: number;
+        sort?: boolean;
+        voiceActors?: boolean;
+    };
+    /** Include staff members with their roles.
+     *  `true` = 25 results sorted by relevance. Object form to customize. */
+    staff?: boolean | {
+        perPage?: number;
+        sort?: boolean;
+    };
+    /** Include relations (default: `true` for backward compat). Set to `false` to exclude. */
+    relations?: boolean;
+    /** Include streaming episode links (Crunchyroll, Funimation, etc.) */
+    streamingEpisodes?: boolean;
+    /** Include external links (MAL, official site, etc.) */
+    externalLinks?: boolean;
+    /** Include score & status distribution stats */
+    stats?: boolean;
+    /** Include user recommendations. `true` = 10 results, or customize with `{ perPage }`. */
+    recommendations?: boolean | {
+        perPage?: number;
+    };
+}
 /**
  * Interface that all cache adapters must implement.
  * Methods may return sync values or Promises — the client awaits all calls.
@@ -451,10 +591,36 @@ interface CacheAdapter {
     /** Number of entries currently stored (sync). Returns -1 if unknown. */
     readonly size: number;
     /** Return all cache keys. */
-    keys(): IterableIterator<string> | string[] | Promise<string[]>;
+    keys(): string[] | Promise<string[]>;
     /** Bulk-remove entries matching a pattern. Optional — the client provides a fallback. */
     invalidate?(pattern: string | RegExp): number | Promise<number>;
 }
+/** Cache configuration options. */
+interface CacheOptions {
+    /** Time-to-live in milliseconds (default: 86 400 000 = 24h) */
+    ttl?: number;
+    /** Maximum number of cached entries (default: 500, 0 = unlimited) */
+    maxSize?: number;
+    /** Set to false to disable caching entirely */
+    enabled?: boolean;
+}
+/** Rate limiter configuration options. */
+interface RateLimitOptions {
+    /** Max requests per window (default: 85) */
+    maxRequests?: number;
+    /** Window size in ms (default: 60 000) */
+    windowMs?: number;
+    /** Max retries on 429 (default: 3) */
+    maxRetries?: number;
+    /** Retry delay in ms when Retry-After header is absent (default: 2000) */
+    retryDelayMs?: number;
+    /** Set to false to disable rate limiting entirely */
+    enabled?: boolean;
+    /** Timeout per request in ms (default: 30 000). 0 = no timeout. */
+    timeoutMs?: number;
+    /** Retry on network errors like ECONNRESET / ETIMEDOUT (default: true) */
+    retryOnNetworkError?: boolean;
+}
 /** Event hooks for logging, debugging, and monitoring. */
 interface AniListHooks {
     /** Called before every API request. */
@@ -474,33 +640,11 @@ interface AniListClientOptions {
     /** Custom API endpoint (defaults to https://graphql.anilist.co) */
     apiUrl?: string;
     /** Cache configuration (enabled by default, 24h TTL) */
-    cache?: {
-        /** Time-to-live in milliseconds (default: 86 400 000 = 24h) */
-        ttl?: number;
-        /** Maximum number of cached entries (default: 500, 0 = unlimited) */
-        maxSize?: number;
-        /** Set to false to disable caching entirely */
-        enabled?: boolean;
-    };
+    cache?: CacheOptions;
     /** Custom cache adapter (e.g. RedisCache). Takes precedence over `cache`. */
     cacheAdapter?: CacheAdapter;
     /** Rate limiter configuration (enabled by default, 85 req/min) */
-    rateLimit?: {
-        /** Max requests per window (default: 85) */
-        maxRequests?: number;
-        /** Window size in ms (default: 60 000) */
-        windowMs?: number;
-        /** Max retries on 429 (default: 3) */
-        maxRetries?: number;
-        /** Retry delay in ms when Retry-After header is absent (default: 2000) */
-        retryDelayMs?: number;
-        /** Set to false to disable rate limiting entirely */
-        enabled?: boolean;
-        /** Timeout per request in ms (default: 30 000). 0 = no timeout. */
-        timeoutMs?: number;
-        /** Retry on network errors like ECONNRESET / ETIMEDOUT (default: true) */
-        retryOnNetworkError?: boolean;
-    };
+    rateLimit?: RateLimitOptions;
     /** Event hooks for logging, debugging, and monitoring */
     hooks?: AniListHooks;
 }
@@ -542,13 +686,47 @@ declare class AniListClient {
      * Shorthand for paginated queries that follow the `Page { pageInfo, <field>[] }` pattern.
      */
     private pagedRequest;
+    /**
+     * @internal
+     * Clamp perPage to AniList's maximum of 50.
+     */
+    private clampPerPage;
     /**
      * Fetch a single media entry by its AniList ID.
      *
+     * Optionally include related data (characters, staff, relations, etc.) via the `include` parameter.
+     *
      * @param id - The AniList media ID
+     * @param include - Optional related data to include
      * @returns The media object
+     *
+     * @example
+     * ```ts
+     * // Basic usage — same as before (includes relations by default)
+     * const anime = await client.getMedia(1);
+     *
+     * // 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 },
+     *   staff: true,
+     *   relations: true,
+     *   streamingEpisodes: true,
+     *   externalLinks: true,
+     *   stats: true,
+     *   recommendations: { perPage: 5 },
+     * });
+     *
+     * // Exclude relations for a lighter response
+     * const anime = await client.getMedia(1, { characters: true, relations: false });
+     * ```
      */
-    getMedia(id: number): Promise<Media>;
+    getMedia(id: number, include?: MediaIncludeOptions): Promise<Media>;
     /**
      * Search for anime or manga.
      *
@@ -575,26 +753,89 @@ declare class AniListClient {
     getTrending(type?: MediaType, page?: number, perPage?: number): Promise<PagedResult<Media>>;
     /**
      * 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 (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>>;
     /**
      * Fetch a staff member by AniList ID.
+     *
+     * @param id - The AniList staff ID
+     * @returns The staff object
+     *
+     * @example
+     * ```ts
+     * const staff = await client.getStaff(95001);
+     * console.log(staff.name.full);
+     * ```
      */
     getStaff(id: number): Promise<Staff>;
     /**
      * Search for staff (voice actors, directors, etc.).
+     *
+     * @param options - Search / pagination parameters
+     * @returns Paginated results with matching staff
+     *
+     * @example
+     * ```ts
+     * const result = await client.searchStaff({ query: "Miyazaki", perPage: 5 });
+     * ```
      */
     searchStaff(options?: SearchStaffOptions): Promise<PagedResult<Staff>>;
     /**
      * Fetch a user by AniList ID.
+     *
+     * @param id - The AniList user ID
+     * @returns The user object
+     *
+     * @example
+     * ```ts
+     * const user = await client.getUser(1);
+     * console.log(user.name);
+     * ```
      */
     getUser(id: number): Promise<User>;
     /**
      * Fetch a user by username.
+     *
+     * @param name - The AniList username
+     * @returns The user object
+     *
+     * @example
+     * ```ts
+     * const user = await client.getUserByName("AniList");
+     * console.log(user.statistics);
+     * ```
      */
     getUserByName(name: string): Promise<User>;
     /**
@@ -830,18 +1071,6 @@ declare class AniListError extends Error {
     constructor(message: string, status: number, errors?: unknown[]);
 }
 
-/**
- * Simple in-memory cache with configurable TTL.
- * Used internally by AniListClient to avoid redundant API calls.
- */
-interface CacheOptions {
-    /** Time-to-live in milliseconds (default: 24 hours) */
-    ttl?: number;
-    /** Maximum number of entries to keep (default: 500, 0 = unlimited) */
-    maxSize?: number;
-    /** Disable caching entirely (default: false) */
-    enabled?: boolean;
-}
 declare class MemoryCache implements CacheAdapter {
     private readonly ttl;
     private readonly maxSize;
@@ -860,8 +1089,8 @@ declare class MemoryCache implements CacheAdapter {
     clear(): void;
     /** Number of entries currently stored. */
     get size(): number;
-    /** Return an iterator over all cache keys. */
-    keys(): IterableIterator<string>;
+    /** Return all cache keys. */
+    keys(): string[];
     /**
      * Remove all entries whose key matches the given pattern.
      *
@@ -880,6 +1109,11 @@ interface RedisLikeClient {
     set(key: string, value: string, ...args: unknown[]): Promise<unknown>;
     del(...keys: (string | string[])[]): Promise<number>;
     keys(pattern: string): Promise<string[]>;
+    /** Optional SCAN-based iteration — used when available to avoid blocking the server. */
+    scanIterator?(options: {
+        MATCH: string;
+        COUNT?: number;
+    }): AsyncIterable<string>;
 }
 interface RedisCacheOptions {
     /** A Redis client instance (ioredis or node-redis). */
@@ -912,6 +1146,14 @@ declare class RedisCache implements CacheAdapter {
     get<T>(key: string): Promise<T | undefined>;
     set<T>(key: string, data: T): Promise<void>;
     delete(key: string): Promise<boolean>;
+    /**
+     * Collect keys matching a pattern. Uses SCAN when available, falls back to KEYS.
+     *
+     * **Warning:** The `KEYS` fallback is O(N) and blocks the Redis server.
+     * Provide a client with `scanIterator` support for production use.
+     * @internal
+     */
+    private collectKeys;
     clear(): Promise<void>;
     /**
      * Returns -1 because Redis keys can expire silently via TTL.
@@ -927,7 +1169,7 @@ declare class RedisCache implements CacheAdapter {
      * @param pattern — A glob pattern (e.g. `"*Media*"`)
      * @returns Number of entries removed.
      */
-    invalidate(pattern: string): Promise<number>;
+    invalidate(pattern: string | RegExp): Promise<number>;
 }
 
 /**
@@ -937,22 +1179,7 @@ declare class RedisCache implements CacheAdapter {
  * When a 429 (Too Many Requests) is received, the client
  * waits for the Retry-After header and retries automatically.
  */
-interface RateLimitOptions {
-    /** Max requests per window (default: 85, conservative under AniList's 90/min) */
-    maxRequests?: number;
-    /** Window size in milliseconds (default: 60 000 = 1 minute) */
-    windowMs?: number;
-    /** Max number of retries on 429 responses (default: 3) */
-    maxRetries?: number;
-    /** Default retry delay in ms when Retry-After header is missing (default: 2000) */
-    retryDelayMs?: number;
-    /** Disable rate limiting entirely (default: false) */
-    enabled?: boolean;
-    /** Timeout per request in milliseconds (default: 30 000). 0 = no timeout. */
-    timeoutMs?: number;
-    /** Retry on network errors like ECONNRESET / ETIMEDOUT (default: true) */
-    retryOnNetworkError?: boolean;
-}
+
 declare class RateLimiter {
     private readonly maxRequests;
     private readonly windowMs;
@@ -980,4 +1207,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, CharacterSort, type FuzzyDate, type GetAiringOptions, type GetPlanningOptions, type GetRecentChaptersOptions, type GetRecommendationsOptions, type GetSeasonOptions, type GetUserMediaListOptions, type Media, type MediaConnection, type MediaCoverImage, type MediaEdge, MediaFormat, type MediaListEntry, MediaListSort, MediaListStatus, MediaRelationType, MediaSeason, MediaSort, 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 SearchCharacterOptions, type SearchMediaOptions, type SearchStaffOptions, type SearchStudioOptions, type Staff, type StaffImage, type StaffName, 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 StaffName, type StatusDistribution, type StreamingEpisode, type Studio, type StudioConnection, type StudioDetail, type User, type UserAvatar, type UserStatistics, type VoiceActor };