ani-client 1.4.2 → 1.4.3

package/dist/index.d.ts

@@ -1,3 +1,320 @@
+interface PageInfo {
+    total: number | null;
+    perPage: number | null;
+    currentPage: number | null;
+    lastPage: number | null;
+    hasNextPage: boolean | null;
+}
+interface PagedResult<T> {
+    pageInfo: PageInfo;
+    results: T[];
+}
+interface FuzzyDate {
+    year: number | null;
+    month: number | null;
+    day: number | null;
+}
+interface ExternalLink {
+    id: number;
+    url: string | null;
+    site: string;
+    type: string | null;
+    icon: string | null;
+    color: string | null;
+}
+/**
+ * Interface that all cache adapters must implement.
+ * Methods may return sync values or Promises — the client awaits all calls.
+ */
+interface CacheAdapter {
+    /** Retrieve a cached value, or `undefined` if missing / expired. */
+    get<T>(key: string): T | undefined | Promise<T | undefined>;
+    /** Store a value in the cache. */
+    set<T>(key: string, data: T): void | Promise<void>;
+    /** Remove a specific entry. Returns `true` if the key existed. */
+    delete(key: string): boolean | Promise<boolean>;
+    /** Clear the entire cache. */
+    clear(): void | Promise<void>;
+    /** Number of entries currently stored. */
+    readonly size: number | Promise<number>;
+    /** Return all cache keys. */
+    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. */
+    onRequest?: (query: string, variables: Record<string, unknown>) => void;
+    /** Called when a response is served from cache. */
+    onCacheHit?: (key: string) => void;
+    /** Called when the rate limiter enforces a wait (429 received). */
+    onRateLimit?: (retryAfterMs: number) => void;
+    /** Called when a request is retried (429 or network error). */
+    onRetry?: (attempt: number, reason: string, delayMs: number) => void;
+    /** Called when a request completes. */
+    onResponse?: (query: string, durationMs: number, fromCache: boolean) => void;
+}
+interface AniListClientOptions {
+    /** Optional AniList OAuth token for authenticated requests */
+    token?: string;
+    /** Custom API endpoint (defaults to https://graphql.anilist.co) */
+    apiUrl?: string;
+    /** Cache configuration (enabled by default, 24h TTL) */
+    cache?: CacheOptions;
+    /** Custom cache adapter (e.g. RedisCache). Takes precedence over `cache`. */
+    cacheAdapter?: CacheAdapter;
+    /** Rate limiter configuration (enabled by default, 85 req/min) */
+    rateLimit?: RateLimitOptions;
+    /** Event hooks for logging, debugging, and monitoring */
+    hooks?: AniListHooks;
+}
+
+interface StaffName {
+    first: string | null;
+    middle: string | null;
+    last: string | null;
+    full: string | null;
+    native: string | null;
+}
+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;
+    language: string | null;
+    image: StaffImage;
+    description: string | null;
+    primaryOccupations: string[];
+    gender: string | null;
+    dateOfBirth: FuzzyDate | null;
+    dateOfDeath: FuzzyDate | null;
+    age: string | null;
+    yearsActive: number[];
+    homeTown: string | null;
+    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 SearchStaffOptions {
+    query?: string;
+    sort?: CharacterSort[];
+    page?: number;
+    perPage?: number;
+}
+/** 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;
+}
+
+declare enum CharacterSort {
+    ID = "ID",
+    ID_DESC = "ID_DESC",
+    ROLE = "ROLE",
+    ROLE_DESC = "ROLE_DESC",
+    SEARCH_MATCH = "SEARCH_MATCH",
+    FAVOURITES = "FAVOURITES",
+    FAVOURITES_DESC = "FAVOURITES_DESC"
+}
+declare enum CharacterRole {
+    MAIN = "MAIN",
+    SUPPORTING = "SUPPORTING",
+    BACKGROUND = "BACKGROUND"
+}
+interface CharacterName {
+    first: string | null;
+    middle: string | null;
+    last: string | null;
+    full: string | null;
+    native: string | null;
+    alternative: string[];
+}
+interface CharacterImage {
+    large: string | null;
+    medium: string | null;
+}
+type CharacterMediaNode = Pick<Media, "id" | "title" | "type" | "coverImage" | "siteUrl">;
+interface CharacterMediaEdge {
+    node: CharacterMediaNode;
+    voiceActors?: VoiceActor[];
+}
+interface Character {
+    id: number;
+    name: CharacterName;
+    image: CharacterImage;
+    description: string | null;
+    gender: string | null;
+    dateOfBirth: FuzzyDate | null;
+    age: string | null;
+    bloodType: string | null;
+    favourites: number | null;
+    siteUrl: string | null;
+    media: {
+        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 SearchCharacterOptions {
+    query?: string;
+    sort?: CharacterSort[];
+    page?: number;
+    perPage?: number;
+    /** Include voice actors for each media the character appears in. */
+    voiceActors?: boolean;
+}
+
+interface Studio {
+    id: number;
+    name: string;
+    isAnimationStudio: boolean;
+    siteUrl: string | null;
+}
+interface StudioConnection {
+    nodes: Studio[];
+}
+interface StudioDetail {
+    id: number;
+    name: string;
+    isAnimationStudio: boolean;
+    siteUrl: string | null;
+    favourites: number | null;
+    media: {
+        pageInfo: PageInfo;
+        nodes: Pick<Media, "id" | "title" | "type" | "format" | "coverImage" | "siteUrl">[];
+    } | null;
+}
+interface SearchStudioOptions {
+    query?: string;
+    page?: number;
+    perPage?: number;
+}
+
+interface UserAvatar {
+    large: string | null;
+    medium: string | null;
+}
+interface UserStatistics {
+    count: number;
+    meanScore: number;
+    minutesWatched: number;
+    episodesWatched: number;
+    chaptersRead: number;
+    volumesRead: number;
+}
+interface User {
+    id: number;
+    name: string;
+    about: string | null;
+    avatar: UserAvatar;
+    bannerImage: string | null;
+    isFollowing: boolean | null;
+    isFollower: boolean | null;
+    donatorTier: number | null;
+    donatorBadge: string | null;
+    createdAt: number | null;
+    siteUrl: string | null;
+    statistics: {
+        anime: UserStatistics;
+        manga: UserStatistics;
+    } | null;
+}
+
 declare enum MediaType {
     ANIME = "ANIME",
     MANGA = "MANGA"
@@ -72,20 +389,6 @@ declare enum AiringSort {
     EPISODE = "EPISODE",
     EPISODE_DESC = "EPISODE_DESC"
 }
-declare enum CharacterSort {
-    ID = "ID",
-    ID_DESC = "ID_DESC",
-    ROLE = "ROLE",
-    ROLE_DESC = "ROLE_DESC",
-    SEARCH_MATCH = "SEARCH_MATCH",
-    FAVOURITES = "FAVOURITES",
-    FAVOURITES_DESC = "FAVOURITES_DESC"
-}
-declare enum CharacterRole {
-    MAIN = "MAIN",
-    SUPPORTING = "SUPPORTING",
-    BACKGROUND = "BACKGROUND"
-}
 interface MediaTitle {
     romaji: string | null;
     english: string | null;
@@ -98,11 +401,6 @@ interface MediaCoverImage {
     medium: string | null;
     color: string | null;
 }
-interface FuzzyDate {
-    year: number | null;
-    month: number | null;
-    day: number | null;
-}
 interface MediaTrailer {
     id: string | null;
     site: string | null;
@@ -116,15 +414,6 @@ interface MediaTag {
     rank: number | null;
     isMediaSpoiler: boolean | null;
 }
-interface Studio {
-    id: number;
-    name: string;
-    isAnimationStudio: boolean;
-    siteUrl: string | null;
-}
-interface StudioConnection {
-    nodes: Studio[];
-}
 declare enum MediaRelationType {
     ADAPTATION = "ADAPTATION",
     PREQUEL = "PREQUEL",
@@ -147,35 +436,6 @@ interface MediaEdge {
 interface MediaConnection {
     edges: MediaEdge[];
 }
-interface CharacterName {
-    first: string | null;
-    middle: string | null;
-    last: string | null;
-    full: string | null;
-    native: string | null;
-    alternative: string[];
-}
-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">;
@@ -197,20 +457,12 @@ interface StreamingEpisode {
     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;
+    status: string;
     amount: number;
 }
 interface MediaStats {
@@ -236,183 +488,35 @@ interface Media {
     seasonYear: number | null;
     episodes: number | null;
     duration: number | null;
-    chapters: number | null;
-    volumes: number | null;
-    countryOfOrigin: string | null;
-    isLicensed: boolean | null;
-    source: string | null;
-    hashtag: string | null;
-    trailer: MediaTrailer | null;
-    coverImage: MediaCoverImage;
-    bannerImage: string | null;
-    genres: string[];
-    synonyms: string[];
-    averageScore: number | null;
-    meanScore: number | null;
-    popularity: number | null;
-    favourites: number | null;
-    trending: number | null;
-    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;
-    image: CharacterImage;
-    description: string | null;
-    gender: string | null;
-    dateOfBirth: FuzzyDate | null;
-    age: string | null;
-    bloodType: string | null;
-    favourites: number | null;
-    siteUrl: string | null;
-    media: {
-        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;
-    last: string | null;
-    full: string | null;
-    native: string | null;
-}
-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;
-    language: string | null;
-    image: StaffImage;
-    description: string | null;
-    primaryOccupations: string[];
-    gender: string | null;
-    dateOfBirth: FuzzyDate | null;
-    dateOfDeath: FuzzyDate | null;
-    age: string | null;
-    yearsActive: number[];
-    homeTown: string | null;
-    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;
-    medium: string | null;
-}
-interface UserStatistics {
-    count: number;
-    meanScore: number;
-    minutesWatched: number;
-    episodesWatched: number;
-    chaptersRead: number;
-    volumesRead: number;
-}
-interface User {
-    id: number;
-    name: string;
-    about: string | null;
-    avatar: UserAvatar;
+    chapters: number | null;
+    volumes: number | null;
+    countryOfOrigin: string | null;
+    isLicensed: boolean | null;
+    source: string | null;
+    hashtag: string | null;
+    trailer: MediaTrailer | null;
+    coverImage: MediaCoverImage;
     bannerImage: string | null;
-    isFollowing: boolean | null;
-    isFollower: boolean | null;
-    donatorTier: number | null;
-    donatorBadge: string | null;
-    createdAt: number | null;
+    genres: string[];
+    synonyms: string[];
+    averageScore: number | null;
+    meanScore: number | null;
+    popularity: number | null;
+    favourites: number | null;
+    trending: number | null;
+    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;
-    statistics: {
-        anime: UserStatistics;
-        manga: UserStatistics;
-    } | null;
-}
-interface AiringSchedule {
-    id: number;
-    airingAt: number;
-    timeUntilAiring: number;
-    episode: number;
-    mediaId: number;
-    media: Media;
-}
-interface PageInfo {
-    total: number | null;
-    perPage: number | null;
-    currentPage: number | null;
-    lastPage: number | null;
-    hasNextPage: boolean | null;
 }
 interface SearchMediaOptions {
     query?: string;
@@ -428,24 +532,6 @@ interface SearchMediaOptions {
     page?: number;
     perPage?: number;
 }
-interface SearchCharacterOptions {
-    query?: string;
-    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;
-}
-interface PagedResult<T> {
-    pageInfo: PageInfo;
-    results: T[];
-}
 interface GetAiringOptions {
     /** Only show episodes that aired after this UNIX timestamp */
     airingAtGreater?: number;
@@ -495,6 +581,58 @@ interface GetRecommendationsOptions {
     page?: number;
     perPage?: number;
 }
+interface GetSeasonOptions {
+    /** The season (WINTER, SPRING, SUMMER, FALL) */
+    season: MediaSeason;
+    /** The year */
+    seasonYear: number;
+    /** Filter by ANIME or MANGA (defaults to ANIME) */
+    type?: MediaType;
+    /** Sort order (default: POPULARITY_DESC) */
+    sort?: MediaSort[];
+    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 AiringSchedule {
+    id: number;
+    airingAt: number;
+    timeUntilAiring: number;
+    episode: number;
+    mediaId: number;
+    media: Media;
+}
+
 declare enum MediaListStatus {
     CURRENT = "CURRENT",
     PLANNING = "PLANNING",
@@ -552,18 +690,6 @@ interface MediaListEntry {
     createdAt: number | null;
     media: Media;
 }
-interface GetSeasonOptions {
-    /** The season (WINTER, SPRING, SUMMER, FALL) */
-    season: MediaSeason;
-    /** The year */
-    seasonYear: number;
-    /** Filter by ANIME or MANGA (defaults to ANIME) */
-    type?: MediaType;
-    /** Sort order (default: POPULARITY_DESC) */
-    sort?: MediaSort[];
-    page?: number;
-    perPage?: number;
-}
 interface GetUserMediaListOptions {
     /** User ID (provide either userId or userName) */
     userId?: number;
@@ -578,126 +704,6 @@ interface GetUserMediaListOptions {
     page?: number;
     perPage?: number;
 }
-interface StudioDetail {
-    id: number;
-    name: string;
-    isAnimationStudio: boolean;
-    siteUrl: string | null;
-    favourites: number | null;
-    media: {
-        pageInfo: PageInfo;
-        nodes: Pick<Media, "id" | "title" | "type" | "format" | "coverImage" | "siteUrl">[];
-    } | null;
-}
-interface SearchStudioOptions {
-    query?: string;
-    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.
- */
-interface CacheAdapter {
-    /** Retrieve a cached value, or `undefined` if missing / expired. */
-    get<T>(key: string): T | undefined | Promise<T | undefined>;
-    /** Store a value in the cache. */
-    set<T>(key: string, data: T): void | Promise<void>;
-    /** Remove a specific entry. Returns `true` if the key existed. */
-    delete(key: string): boolean | Promise<boolean>;
-    /** Clear the entire cache. */
-    clear(): void | Promise<void>;
-    /** Number of entries currently stored (sync). Returns -1 if unknown. */
-    readonly size: number;
-    /** Return all cache keys. */
-    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. */
-    onRequest?: (query: string, variables: Record<string, unknown>) => void;
-    /** Called when a response is served from cache. */
-    onCacheHit?: (key: string) => void;
-    /** Called when the rate limiter enforces a wait (429 received). */
-    onRateLimit?: (retryAfterMs: number) => void;
-    /** Called when a request is retried (429 or network error). */
-    onRetry?: (attempt: number, reason: string, delayMs: number) => void;
-    /** Called when a request completes. */
-    onResponse?: (query: string, durationMs: number, fromCache: boolean) => void;
-}
-interface AniListClientOptions {
-    /** Optional AniList OAuth token for authenticated requests */
-    token?: string;
-    /** Custom API endpoint (defaults to https://graphql.anilist.co) */
-    apiUrl?: string;
-    /** Cache configuration (enabled by default, 24h TTL) */
-    cache?: CacheOptions;
-    /** Custom cache adapter (e.g. RedisCache). Takes precedence over `cache`. */
-    cacheAdapter?: CacheAdapter;
-    /** Rate limiter configuration (enabled by default, 85 req/min) */
-    rateLimit?: RateLimitOptions;
-    /** Event hooks for logging, debugging, and monitoring */
-    hooks?: AniListHooks;
-}
 
 /**
  * Lightweight AniList GraphQL client with built-in caching and rate limiting.
@@ -736,11 +742,6 @@ 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.
      *
@@ -1095,17 +1096,15 @@ declare class AniListClient {
     getStaffBatch(ids: number[]): Promise<Staff[]>;
     /** @internal */
     private executeBatch;
-    /** @internal */
-    private chunk;
     /**
      * Clear the entire response cache.
      */
     clearCache(): Promise<void>;
     /**
-     * Number of entries currently in the cache (sync).
-     * For async adapters like Redis, this may be approximate.
+     * Number of entries currently in the cache.
+     * For async adapters like Redis, this may return a Promise.
      */
-    get cacheSize(): number;
+    get cacheSize(): number | Promise<number>;
     /**
      * Remove cache entries whose key matches the given pattern.
      *
@@ -1143,7 +1142,7 @@ declare class MemoryCache implements CacheAdapter {
     /** Clear the entire cache. */
     clear(): void;
     /** Number of entries currently stored. */
-    get size(): number;
+    get size(): number | Promise<number>;
     /** Return all cache keys. */
     keys(): string[];
     /**
@@ -1211,12 +1210,11 @@ declare class RedisCache implements CacheAdapter {
     private collectKeys;
     clear(): Promise<void>;
     /**
-     * Returns -1 because Redis keys can expire silently via TTL.
-     * Use `getSize()` for an accurate count.
+     * Get the actual number of keys with this prefix in Redis.
      */
-    get size(): number;
-    /** Get the actual number of keys with this prefix in Redis. */
-    getSize(): Promise<number>;
+    get size(): Promise<number>;
+    /** @internal */
+    private getSize;
     keys(): Promise<string[]>;
     /**
      * Remove all entries whose key matches the given glob pattern.