ani-client 1.4.3 → 1.5.0

package/dist/index.d.ts

@@ -96,6 +96,18 @@ interface AniListClientOptions {
     hooks?: AniListHooks;
 }
 
+declare enum StaffSort {
+    ID = "ID",
+    ID_DESC = "ID_DESC",
+    ROLE = "ROLE",
+    ROLE_DESC = "ROLE_DESC",
+    LANGUAGE = "LANGUAGE",
+    LANGUAGE_DESC = "LANGUAGE_DESC",
+    SEARCH_MATCH = "SEARCH_MATCH",
+    FAVOURITES = "FAVOURITES",
+    FAVOURITES_DESC = "FAVOURITES_DESC",
+    RELEVANCE = "RELEVANCE"
+}
 interface StaffName {
     first: string | null;
     middle: string | null;
@@ -176,7 +188,7 @@ interface StaffIncludeOptions {
 }
 interface SearchStaffOptions {
     query?: string;
-    sort?: CharacterSort[];
+    sort?: StaffSort[];
     page?: number;
     perPage?: number;
 }
@@ -259,32 +271,113 @@ interface SearchCharacterOptions {
     voiceActors?: boolean;
 }
 
-interface Studio {
+declare enum MediaListStatus {
+    CURRENT = "CURRENT",
+    PLANNING = "PLANNING",
+    COMPLETED = "COMPLETED",
+    DROPPED = "DROPPED",
+    PAUSED = "PAUSED",
+    REPEATING = "REPEATING"
+}
+declare enum MediaListSort {
+    MEDIA_ID = "MEDIA_ID",
+    MEDIA_ID_DESC = "MEDIA_ID_DESC",
+    SCORE = "SCORE",
+    SCORE_DESC = "SCORE_DESC",
+    STATUS = "STATUS",
+    STATUS_DESC = "STATUS_DESC",
+    PROGRESS = "PROGRESS",
+    PROGRESS_DESC = "PROGRESS_DESC",
+    PROGRESS_VOLUMES = "PROGRESS_VOLUMES",
+    PROGRESS_VOLUMES_DESC = "PROGRESS_VOLUMES_DESC",
+    REPEAT = "REPEAT",
+    REPEAT_DESC = "REPEAT_DESC",
+    PRIORITY = "PRIORITY",
+    PRIORITY_DESC = "PRIORITY_DESC",
+    STARTED_ON = "STARTED_ON",
+    STARTED_ON_DESC = "STARTED_ON_DESC",
+    FINISHED_ON = "FINISHED_ON",
+    FINISHED_ON_DESC = "FINISHED_ON_DESC",
+    ADDED_TIME = "ADDED_TIME",
+    ADDED_TIME_DESC = "ADDED_TIME_DESC",
+    UPDATED_TIME = "UPDATED_TIME",
+    UPDATED_TIME_DESC = "UPDATED_TIME_DESC",
+    MEDIA_TITLE_ROMAJI = "MEDIA_TITLE_ROMAJI",
+    MEDIA_TITLE_ROMAJI_DESC = "MEDIA_TITLE_ROMAJI_DESC",
+    MEDIA_TITLE_ENGLISH = "MEDIA_TITLE_ENGLISH",
+    MEDIA_TITLE_ENGLISH_DESC = "MEDIA_TITLE_ENGLISH_DESC",
+    MEDIA_TITLE_NATIVE = "MEDIA_TITLE_NATIVE",
+    MEDIA_TITLE_NATIVE_DESC = "MEDIA_TITLE_NATIVE_DESC",
+    MEDIA_POPULARITY = "MEDIA_POPULARITY",
+    MEDIA_POPULARITY_DESC = "MEDIA_POPULARITY_DESC"
+}
+interface MediaListEntry {
     id: number;
-    name: string;
-    isAnimationStudio: boolean;
-    siteUrl: string | null;
+    mediaId: number;
+    status: MediaListStatus;
+    score: number | null;
+    progress: number | null;
+    progressVolumes: number | null;
+    repeat: number | null;
+    priority: number | null;
+    private: boolean | null;
+    notes: string | null;
+    startedAt: FuzzyDate | null;
+    completedAt: FuzzyDate | null;
+    updatedAt: number | null;
+    createdAt: number | null;
+    media: Media;
 }
-interface StudioConnection {
-    nodes: Studio[];
+interface GetUserMediaListOptions {
+    /** User ID (provide either userId or userName) */
+    userId?: number;
+    /** Username (provide either userId or userName) */
+    userName?: string;
+    /** ANIME or MANGA */
+    type: MediaType;
+    /** Filter by list status (CURRENT, COMPLETED, etc.) */
+    status?: MediaListStatus;
+    /** Sort order */
+    sort?: MediaListSort[];
+    page?: number;
+    perPage?: number;
 }
-interface StudioDetail {
+
+interface Studio {
     id: number;
     name: string;
     isAnimationStudio: boolean;
     siteUrl: string | null;
-    favourites: number | null;
-    media: {
+    favourites?: number | null;
+    media?: {
         pageInfo: PageInfo;
         nodes: Pick<Media, "id" | "title" | "type" | "format" | "coverImage" | "siteUrl">[];
     } | null;
 }
+interface StudioConnection {
+    nodes: Studio[];
+}
+/**
+ * @deprecated Use `Studio` instead. `StudioDetail` is an alias kept for backward compatibility.
+ */
+type StudioDetail = Studio;
 interface SearchStudioOptions {
     query?: string;
     page?: number;
     perPage?: number;
 }
 
+declare enum UserSort {
+    ID = "ID",
+    ID_DESC = "ID_DESC",
+    USERNAME = "USERNAME",
+    USERNAME_DESC = "USERNAME_DESC",
+    WATCHED_TIME = "WATCHED_TIME",
+    WATCHED_TIME_DESC = "WATCHED_TIME_DESC",
+    CHAPTERS_READ = "CHAPTERS_READ",
+    CHAPTERS_READ_DESC = "CHAPTERS_READ_DESC",
+    SEARCH_MATCH = "SEARCH_MATCH"
+}
 interface UserAvatar {
     large: string | null;
     medium: string | null;
@@ -314,11 +407,34 @@ interface User {
         manga: UserStatistics;
     } | null;
 }
+interface SearchUserOptions {
+    query?: string;
+    sort?: UserSort[];
+    page?: number;
+    perPage?: number;
+}
 
 declare enum MediaType {
     ANIME = "ANIME",
     MANGA = "MANGA"
 }
+declare enum MediaSource {
+    ORIGINAL = "ORIGINAL",
+    MANGA = "MANGA",
+    LIGHT_NOVEL = "LIGHT_NOVEL",
+    VISUAL_NOVEL = "VISUAL_NOVEL",
+    VIDEO_GAME = "VIDEO_GAME",
+    OTHER = "OTHER",
+    NOVEL = "NOVEL",
+    DOUJINSHI = "DOUJINSHI",
+    ANIME = "ANIME",
+    WEB_NOVEL = "WEB_NOVEL",
+    LIVE_ACTION = "LIVE_ACTION",
+    GAME = "GAME",
+    COMIC = "COMIC",
+    MULTIMEDIA_PROJECT = "MULTIMEDIA_PROJECT",
+    PICTURE_BOOK = "PICTURE_BOOK"
+}
 declare enum MediaFormat {
     TV = "TV",
     TV_SHORT = "TV_SHORT",
@@ -462,7 +578,7 @@ interface ScoreDistribution {
     amount: number;
 }
 interface StatusDistribution {
-    status: string;
+    status: MediaListStatus | string;
     amount: number;
 }
 interface MediaStats {
@@ -474,6 +590,13 @@ interface MediaRecommendationNode {
     rating: number | null;
     mediaRecommendation: Pick<Media, "id" | "title" | "type" | "format" | "coverImage" | "averageScore" | "siteUrl">;
 }
+interface NextAiringEpisode {
+    id: number;
+    airingAt: number;
+    episode: number;
+    mediaId: number;
+    timeUntilAiring: number;
+}
 interface Media {
     id: number;
     idMal: number | null;
@@ -492,7 +615,7 @@ interface Media {
     volumes: number | null;
     countryOfOrigin: string | null;
     isLicensed: boolean | null;
-    source: string | null;
+    source: MediaSource | null;
     hashtag: string | null;
     trailer: MediaTrailer | null;
     coverImage: MediaCoverImage;
@@ -515,6 +638,7 @@ interface Media {
     recommendations?: {
         nodes: MediaRecommendationNode[];
     };
+    nextAiringEpisode: NextAiringEpisode | null;
     isAdult: boolean | null;
     siteUrl: string | null;
 }
@@ -525,8 +649,18 @@ interface SearchMediaOptions {
     status?: MediaStatus;
     season?: MediaSeason;
     seasonYear?: number;
+    /** Single genre filter (kept for backward compat) */
     genre?: string;
+    /** Single tag filter (kept for backward compat) */
     tag?: string;
+    /** Filter by multiple genres (media must match ALL) */
+    genres?: string[];
+    /** Filter by multiple tags (media must match ALL) */
+    tags?: string[];
+    /** Exclude media with any of these genres */
+    genresExclude?: string[];
+    /** Exclude media with any of these tags */
+    tagsExclude?: string[];
     isAdult?: boolean;
     sort?: MediaSort[];
     page?: number;
@@ -633,78 +767,6 @@ interface AiringSchedule {
     media: Media;
 }
 
-declare enum MediaListStatus {
-    CURRENT = "CURRENT",
-    PLANNING = "PLANNING",
-    COMPLETED = "COMPLETED",
-    DROPPED = "DROPPED",
-    PAUSED = "PAUSED",
-    REPEATING = "REPEATING"
-}
-declare enum MediaListSort {
-    MEDIA_ID = "MEDIA_ID",
-    MEDIA_ID_DESC = "MEDIA_ID_DESC",
-    SCORE = "SCORE",
-    SCORE_DESC = "SCORE_DESC",
-    STATUS = "STATUS",
-    STATUS_DESC = "STATUS_DESC",
-    PROGRESS = "PROGRESS",
-    PROGRESS_DESC = "PROGRESS_DESC",
-    PROGRESS_VOLUMES = "PROGRESS_VOLUMES",
-    PROGRESS_VOLUMES_DESC = "PROGRESS_VOLUMES_DESC",
-    REPEAT = "REPEAT",
-    REPEAT_DESC = "REPEAT_DESC",
-    PRIORITY = "PRIORITY",
-    PRIORITY_DESC = "PRIORITY_DESC",
-    STARTED_ON = "STARTED_ON",
-    STARTED_ON_DESC = "STARTED_ON_DESC",
-    FINISHED_ON = "FINISHED_ON",
-    FINISHED_ON_DESC = "FINISHED_ON_DESC",
-    ADDED_TIME = "ADDED_TIME",
-    ADDED_TIME_DESC = "ADDED_TIME_DESC",
-    UPDATED_TIME = "UPDATED_TIME",
-    UPDATED_TIME_DESC = "UPDATED_TIME_DESC",
-    MEDIA_TITLE_ROMAJI = "MEDIA_TITLE_ROMAJI",
-    MEDIA_TITLE_ROMAJI_DESC = "MEDIA_TITLE_ROMAJI_DESC",
-    MEDIA_TITLE_ENGLISH = "MEDIA_TITLE_ENGLISH",
-    MEDIA_TITLE_ENGLISH_DESC = "MEDIA_TITLE_ENGLISH_DESC",
-    MEDIA_TITLE_NATIVE = "MEDIA_TITLE_NATIVE",
-    MEDIA_TITLE_NATIVE_DESC = "MEDIA_TITLE_NATIVE_DESC",
-    MEDIA_POPULARITY = "MEDIA_POPULARITY",
-    MEDIA_POPULARITY_DESC = "MEDIA_POPULARITY_DESC"
-}
-interface MediaListEntry {
-    id: number;
-    mediaId: number;
-    status: MediaListStatus;
-    score: number | null;
-    progress: number | null;
-    progressVolumes: number | null;
-    repeat: number | null;
-    priority: number | null;
-    private: boolean | null;
-    notes: string | null;
-    startedAt: FuzzyDate | null;
-    completedAt: FuzzyDate | null;
-    updatedAt: number | null;
-    createdAt: number | null;
-    media: Media;
-}
-interface GetUserMediaListOptions {
-    /** User ID (provide either userId or userName) */
-    userId?: number;
-    /** Username (provide either userId or userName) */
-    userName?: string;
-    /** ANIME or MANGA */
-    type: MediaType;
-    /** Filter by list status (CURRENT, COMPLETED, etc.) */
-    status?: MediaListStatus;
-    /** Sort order */
-    sort?: MediaListSort[];
-    page?: number;
-    perPage?: number;
-}
-
 /**
  * Lightweight AniList GraphQL client with built-in caching and rate limiting.
  *
@@ -802,6 +864,26 @@ declare class AniListClient {
      * @param perPage - Results per page (default 20, max 50)
      */
     getTrending(type?: MediaType, page?: number, perPage?: number): Promise<PagedResult<Media>>;
+    /**
+     * Get the most popular anime or manga.
+     *
+     * Convenience wrapper around `searchMedia` with `sort: POPULARITY_DESC`.
+     *
+     * @param type - `MediaType.ANIME` or `MediaType.MANGA` (defaults to ANIME)
+     * @param page - Page number (default 1)
+     * @param perPage - Results per page (default 20, max 50)
+     */
+    getPopular(type?: MediaType, page?: number, perPage?: number): Promise<PagedResult<Media>>;
+    /**
+     * Get the highest-rated anime or manga.
+     *
+     * Convenience wrapper around `searchMedia` with `sort: SCORE_DESC`.
+     *
+     * @param type - `MediaType.ANIME` or `MediaType.MANGA` (defaults to ANIME)
+     * @param page - Page number (default 1)
+     * @param perPage - Results per page (default 20, max 50)
+     */
+    getTopRated(type?: MediaType, page?: number, perPage?: number): Promise<PagedResult<Media>>;
     /**
      * Fetch a character by AniList ID.
      *
@@ -869,31 +951,39 @@ declare class AniListClient {
      */
     searchStaff(options?: SearchStaffOptions): Promise<PagedResult<Staff>>;
     /**
-     * Fetch a user by AniList ID.
+     * Fetch a user by AniList ID or username.
      *
-     * @param id - The AniList user ID
+     * @param idOrName - The AniList user ID (number) or username (string)
      * @returns The user object
      *
      * @example
      * ```ts
      * const user = await client.getUser(1);
+     * const user2 = await client.getUser("AniList");
      * console.log(user.name);
      * ```
      */
-    getUser(id: number): Promise<User>;
+    getUser(idOrName: number | string): Promise<User>;
     /**
      * Fetch a user by username.
      *
+     * @deprecated Use `getUser(name)` instead.
      * @param name - The AniList username
      * @returns The user object
+     */
+    getUserByName(name: string): Promise<User>;
+    /**
+     * Search for users by name.
+     *
+     * @param options - Search / pagination parameters
+     * @returns Paginated results with matching users
      *
      * @example
      * ```ts
-     * const user = await client.getUserByName("AniList");
-     * console.log(user.statistics);
+     * const result = await client.searchUsers({ query: "AniList", perPage: 5 });
      * ```
      */
-    getUserByName(name: string): Promise<User>;
+    searchUsers(options?: SearchUserOptions): Promise<PagedResult<User>>;
     /**
      * Execute an arbitrary GraphQL query against the AniList API.
      * Useful for advanced use-cases not covered by the built-in methods.
@@ -1018,7 +1108,7 @@ declare class AniListClient {
      *
      * @param id - The AniList studio ID
      */
-    getStudio(id: number): Promise<StudioDetail>;
+    getStudio(id: number): Promise<Studio>;
     /**
      * Search for studios by name.
      *
@@ -1030,7 +1120,7 @@ declare class AniListClient {
      * const studios = await client.searchStudios({ query: "MAPPA" });
      * ```
      */
-    searchStudios(options?: SearchStudioOptions): Promise<PagedResult<StudioDetail>>;
+    searchStudios(options?: SearchStudioOptions): Promise<PagedResult<Studio>>;
     /**
      * Get all available genres on AniList.
      *
@@ -1112,6 +1202,14 @@ declare class AniListClient {
      * @returns Number of entries removed
      */
     invalidateCache(pattern: string | RegExp): Promise<number>;
+    /**
+     * Clean up resources held by the client.
+     *
+     * Clears the in-memory cache and aborts any pending in-flight requests.
+     * If using a custom cache adapter (e.g. Redis), call its close/disconnect
+     * method separately.
+     */
+    destroy(): Promise<void>;
 }
 
 /**
@@ -1148,7 +1246,10 @@ declare class MemoryCache implements CacheAdapter {
     /**
      * Remove all entries whose key matches the given pattern.
      *
-     * @param pattern — A string (converted to RegExp) or RegExp.
+     * - **String**: treated as a substring match (e.g. `"Media"` removes all keys containing `"Media"`).
+     * - **RegExp**: tested against each key directly.
+     *
+     * @param pattern — A string (substring match) or RegExp.
      * @returns Number of entries removed.
      */
     invalidate(pattern: string | RegExp): number;
@@ -1241,8 +1342,10 @@ declare class RateLimiter {
     private readonly enabled;
     private readonly timeoutMs;
     private readonly retryOnNetworkError;
-    /** @internal */
-    private timestamps;
+    /** @internal — sliding window: circular buffer of timestamps */
+    private readonly timestamps;
+    private head;
+    private count;
     constructor(options?: RateLimitOptions);
     /**
      * Wait until it's safe to make a request (respects rate limit window).
@@ -1250,14 +1353,17 @@ declare class RateLimiter {
     acquire(): Promise<void>;
     /**
      * Execute a fetch with automatic retry on 429 responses and network errors.
+     * Uses exponential backoff with jitter for retry delays.
      */
     fetchWithRetry(url: string, init: RequestInit, hooks?: {
         onRetry?: (attempt: number, reason: string, delayMs: number) => void;
         onRateLimit?: (retryAfterMs: number) => void;
     }): Promise<Response>;
+    /** @internal — Exponential backoff with jitter, capped at 30s */
+    private exponentialDelay;
     /** @internal */
     private fetchWithTimeout;
     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 StaffIncludeOptions, type StaffMediaNode, 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, MediaSource, type MediaStaffConnection, type MediaStaffEdge, type MediaStats, MediaStatus, type MediaTag, type MediaTitle, type MediaTrailer, MediaType, MemoryCache, type NextAiringEpisode, 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 SearchUserOptions, type Staff, type StaffImage, type StaffIncludeOptions, type StaffMediaNode, type StaffName, StaffSort, type StatusDistribution, type StreamingEpisode, type Studio, type StudioConnection, type StudioDetail, type User, type UserAvatar, UserSort, type UserStatistics, type VoiceActor };