ani-client 1.4.1 → 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 {
@@ -237,132 +489,34 @@ interface Media {
     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;
-}
-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;
-}
-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;
+    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;
@@ -378,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;
@@ -445,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",
@@ -502,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;
@@ -528,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.
@@ -686,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.
      *
@@ -791,15 +842,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.).
      *
@@ -1040,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.
      *
@@ -1088,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[];
     /**
@@ -1156,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.
@@ -1207,4 +1260,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 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 };
+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 };