ani-client 1.1.0 → 1.3.0

package/dist/index.d.mts

@@ -101,6 +101,28 @@ interface Studio {
 interface StudioConnection {
     nodes: Studio[];
 }
+declare enum MediaRelationType {
+    ADAPTATION = "ADAPTATION",
+    PREQUEL = "PREQUEL",
+    SEQUEL = "SEQUEL",
+    PARENT = "PARENT",
+    SIDE_STORY = "SIDE_STORY",
+    CHARACTER = "CHARACTER",
+    SUMMARY = "SUMMARY",
+    ALTERNATIVE = "ALTERNATIVE",
+    SPIN_OFF = "SPIN_OFF",
+    OTHER = "OTHER",
+    SOURCE = "SOURCE",
+    COMPILATION = "COMPILATION",
+    CONTAINS = "CONTAINS"
+}
+interface MediaEdge {
+    relationType: MediaRelationType;
+    node: Pick<Media, "id" | "title" | "type" | "format" | "status" | "coverImage" | "siteUrl">;
+}
+interface MediaConnection {
+    edges: MediaEdge[];
+}
 interface CharacterName {
     first: string | null;
     middle: string | null;
@@ -145,6 +167,7 @@ interface Media {
     trending: number | null;
     tags: MediaTag[];
     studios: StudioConnection;
+    relations: MediaConnection | null;
     isAdult: boolean | null;
     siteUrl: string | null;
 }
@@ -288,6 +311,163 @@ interface GetPlanningOptions {
     page?: number;
     perPage?: number;
 }
+declare enum RecommendationSort {
+    ID = "ID",
+    ID_DESC = "ID_DESC",
+    RATING = "RATING",
+    RATING_DESC = "RATING_DESC"
+}
+interface Recommendation {
+    id: number;
+    rating: number | null;
+    userRating: string | null;
+    mediaRecommendation: Media;
+    user: {
+        id: number;
+        name: string;
+        avatar: UserAvatar;
+    } | null;
+}
+interface GetRecommendationsOptions {
+    /** The AniList media ID to get recommendations for */
+    mediaId: number;
+    /** Sort order (default: RATING_DESC) */
+    sort?: RecommendationSort[];
+    page?: number;
+    perPage?: number;
+}
+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 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;
+    /** 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 {
+    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 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(): IterableIterator<string> | string[] | Promise<string[]>;
+    /** Bulk-remove entries matching a pattern. Optional — the client provides a fallback. */
+    invalidate?(pattern: string | RegExp): number | Promise<number>;
+}
+/** 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;
@@ -302,6 +482,8 @@ interface AniListClientOptions {
         /** Set to false to disable caching entirely */
         enabled?: boolean;
     };
+    /** 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) */
@@ -314,7 +496,13 @@ interface AniListClientOptions {
         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 */
+    hooks?: AniListHooks;
 }
 
 /**
@@ -338,13 +526,22 @@ interface AniListClientOptions {
 declare class AniListClient {
     private readonly apiUrl;
     private readonly headers;
-    private readonly cache;
+    private readonly cacheAdapter;
     private readonly rateLimiter;
+    private readonly hooks;
+    private readonly inFlight;
     constructor(options?: AniListClientOptions);
     /**
      * @internal
      */
     private request;
+    /** @internal */
+    private executeRequest;
+    /**
+     * @internal
+     * Shorthand for paginated queries that follow the `Page { pageInfo, <field>[] }` pattern.
+     */
+    private pagedRequest;
     /**
      * Fetch a single media entry by its AniList ID.
      *
@@ -455,14 +652,171 @@ declare class AniListClient {
      * ```
      */
     getPlanning(options?: GetPlanningOptions): Promise<PagedResult<Media>>;
+    /**
+     * Get recommendations for a specific media.
+     *
+     * Returns other anime/manga that users have recommended based on the given media.
+     *
+     * @param mediaId - The AniList media ID
+     * @param options - Optional sort / pagination parameters
+     * @returns Paginated list of recommendations
+     *
+     * @example
+     * ```ts
+     * // Get recommendations for Cowboy Bebop
+     * const recs = await client.getRecommendations(1);
+     * recs.results.forEach((r) =>
+     *   console.log(`${r.mediaRecommendation.title.romaji} (rating: ${r.rating})`)
+     * );
+     * ```
+     */
+    getRecommendations(mediaId: number, options?: Omit<GetRecommendationsOptions, "mediaId">): Promise<PagedResult<Recommendation>>;
+    /**
+     * Get anime (or manga) for a specific season and year.
+     *
+     * @param options - Season, year and optional filter / pagination parameters
+     * @returns Paginated list of media for the given season
+     *
+     * @example
+     * ```ts
+     * import { MediaSeason } from "ani-client";
+     *
+     * const winter2026 = await client.getMediaBySeason({
+     *   season: MediaSeason.WINTER,
+     *   seasonYear: 2026,
+     *   perPage: 10,
+     * });
+     * ```
+     */
+    getMediaBySeason(options: GetSeasonOptions): Promise<PagedResult<Media>>;
+    /**
+     * Get a user's anime or manga list.
+     *
+     * Provide either `userId` or `userName` to identify the user.
+     * Requires `type` (ANIME or MANGA). Optionally filter by list status.
+     *
+     * @param options - User identifier, media type, and optional filters
+     * @returns Paginated list of media list entries
+     *
+     * @example
+     * ```ts
+     * import { MediaType, MediaListStatus } from "ani-client";
+     *
+     * // Get a user's completed anime list
+     * const list = await client.getUserMediaList({
+     *   userName: "AniList",
+     *   type: MediaType.ANIME,
+     *   status: MediaListStatus.COMPLETED,
+     * });
+     * list.results.forEach((entry) =>
+     *   console.log(`${entry.media.title.romaji} — ${entry.score}/100`)
+     * );
+     * ```
+     */
+    getUserMediaList(options: GetUserMediaListOptions): Promise<PagedResult<MediaListEntry>>;
+    /**
+     * Fetch a studio by its AniList ID.
+     *
+     * Returns studio details along with its most popular productions.
+     *
+     * @param id - The AniList studio ID
+     */
+    getStudio(id: number): Promise<StudioDetail>;
+    /**
+     * Search for studios by name.
+     *
+     * @param options - Search / pagination parameters
+     * @returns Paginated list of studios
+     *
+     * @example
+     * ```ts
+     * const studios = await client.searchStudios({ query: "MAPPA" });
+     * ```
+     */
+    searchStudios(options?: SearchStudioOptions): Promise<PagedResult<StudioDetail>>;
+    /**
+     * Get all available genres on AniList.
+     *
+     * @returns Array of genre strings (e.g. "Action", "Adventure", ...)
+     */
+    getGenres(): Promise<string[]>;
+    /**
+     * Get all available media tags on AniList.
+     *
+     * @returns Array of tag objects with id, name, description, category, isAdult
+     */
+    getTags(): Promise<MediaTag[]>;
+    /**
+     * Auto-paginating async iterator.
+     *
+     * Wraps any paginated method and yields individual items across all pages.
+     * Stops when `hasNextPage` is `false` or `maxPages` is reached.
+     *
+     * @param fetchPage - A function that takes a page number and returns a `PagedResult<T>`
+     * @param maxPages - Maximum number of pages to fetch (default: Infinity)
+     * @returns An async iterable iterator of individual items
+     *
+     * @example
+     * ```ts
+     * // Iterate over all search results
+     * for await (const anime of client.paginate((page) =>
+     *   client.searchMedia({ query: "Naruto", page, perPage: 10 })
+     * )) {
+     *   console.log(anime.title.romaji);
+     * }
+     *
+     * // Limit to 3 pages
+     * for await (const anime of client.paginate(
+     *   (page) => client.getTrending(MediaType.ANIME, page, 20),
+     *   3,
+     * )) {
+     *   console.log(anime.title.romaji);
+     * }
+     * ```
+     */
+    paginate<T>(fetchPage: (page: number) => Promise<PagedResult<T>>, maxPages?: number): AsyncGenerator<T, void, undefined>;
+    /**
+     * Fetch multiple media entries in a single API request.
+     * Uses GraphQL aliases to batch up to 50 IDs per call.
+     *
+     * @param ids - Array of AniList media IDs
+     * @returns Array of media objects (same order as input IDs)
+     */
+    getMediaBatch(ids: number[]): Promise<Media[]>;
+    /**
+     * Fetch multiple characters in a single API request.
+     *
+     * @param ids - Array of AniList character IDs
+     * @returns Array of character objects (same order as input IDs)
+     */
+    getCharacterBatch(ids: number[]): Promise<Character[]>;
+    /**
+     * Fetch multiple staff members in a single API request.
+     *
+     * @param ids - Array of AniList staff IDs
+     * @returns Array of staff objects (same order as input IDs)
+     */
+    getStaffBatch(ids: number[]): Promise<Staff[]>;
+    /** @internal */
+    private executeBatch;
+    /** @internal */
+    private chunk;
     /**
      * Clear the entire response cache.
      */
-    clearCache(): void;
+    clearCache(): Promise<void>;
     /**
-     * Number of entries currently in the cache.
+     * Number of entries currently in the cache (sync).
+     * For async adapters like Redis, this may be approximate.
      */
     get cacheSize(): number;
+    /**
+     * Remove cache entries whose key matches the given pattern.
+     *
+     * @param pattern — A string (converted to RegExp) or RegExp
+     * @returns Number of entries removed
+     */
+    invalidateCache(pattern: string | RegExp): Promise<number>;
 }
 
 /**
@@ -488,7 +842,7 @@ interface CacheOptions {
     /** Disable caching entirely (default: false) */
     enabled?: boolean;
 }
-declare class MemoryCache {
+declare class MemoryCache implements CacheAdapter {
     private readonly ttl;
     private readonly maxSize;
     private readonly enabled;
@@ -506,6 +860,74 @@ declare class MemoryCache {
     clear(): void;
     /** Number of entries currently stored. */
     get size(): number;
+    /** Return an iterator over all cache keys. */
+    keys(): IterableIterator<string>;
+    /**
+     * Remove all entries whose key matches the given pattern.
+     *
+     * @param pattern — A string (converted to RegExp) or RegExp.
+     * @returns Number of entries removed.
+     */
+    invalidate(pattern: string | RegExp): number;
+}
+
+/**
+ * Minimal interface representing a Redis client.
+ * Compatible with both `ioredis` and `redis` (node-redis v4+).
+ */
+interface RedisLikeClient {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ...args: unknown[]): Promise<unknown>;
+    del(...keys: (string | string[])[]): Promise<number>;
+    keys(pattern: string): Promise<string[]>;
+}
+interface RedisCacheOptions {
+    /** A Redis client instance (ioredis or node-redis). */
+    client: RedisLikeClient;
+    /** Key prefix to namespace ani-client entries (default: `"ani:"`) */
+    prefix?: string;
+    /** TTL in seconds (default: 86 400 = 24 h) */
+    ttl?: number;
+}
+/**
+ * Redis-backed cache adapter for AniListClient.
+ *
+ * @example
+ * ```ts
+ * import Redis from "ioredis";
+ * import { AniListClient, RedisCache } from "ani-client";
+ *
+ * const redis = new Redis();
+ * const client = new AniListClient({
+ *   cacheAdapter: new RedisCache({ client: redis }),
+ * });
+ * ```
+ */
+declare class RedisCache implements CacheAdapter {
+    private readonly client;
+    private readonly prefix;
+    private readonly ttl;
+    constructor(options: RedisCacheOptions);
+    private prefixedKey;
+    get<T>(key: string): Promise<T | undefined>;
+    set<T>(key: string, data: T): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    clear(): Promise<void>;
+    /**
+     * Returns -1 because Redis keys can expire silently via TTL.
+     * Use `getSize()` for an accurate count.
+     */
+    get size(): number;
+    /** Get the actual number of keys with this prefix in Redis. */
+    getSize(): Promise<number>;
+    keys(): Promise<string[]>;
+    /**
+     * Remove all entries whose key matches the given glob pattern.
+     *
+     * @param pattern — A glob pattern (e.g. `"*Media*"`)
+     * @returns Number of entries removed.
+     */
+    invalidate(pattern: string): Promise<number>;
 }
 
 /**
@@ -526,6 +948,10 @@ interface RateLimitOptions {
     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;
@@ -533,6 +959,8 @@ declare class RateLimiter {
     private readonly maxRetries;
     private readonly retryDelayMs;
     private readonly enabled;
+    private readonly timeoutMs;
+    private readonly retryOnNetworkError;
     /** @internal */
     private timestamps;
     constructor(options?: RateLimitOptions);
@@ -541,10 +969,15 @@ declare class RateLimiter {
      */
     acquire(): Promise<void>;
     /**
-     * Execute a fetch with automatic retry on 429 responses.
+     * Execute a fetch with automatic retry on 429 responses and network errors.
      */
-    fetchWithRetry(url: string, init: RequestInit): Promise<Response>;
+    fetchWithRetry(url: string, init: RequestInit, hooks?: {
+        onRetry?: (attempt: number, reason: string, delayMs: number) => void;
+        onRateLimit?: (retryAfterMs: number) => void;
+    }): Promise<Response>;
+    /** @internal */
+    private fetchWithTimeout;
     private sleep;
 }
 
-export { type AiringSchedule, AiringSort, AniListClient, type AniListClientOptions, AniListError, type CacheOptions, type Character, type CharacterImage, type CharacterName, CharacterSort, type FuzzyDate, type GetAiringOptions, type GetPlanningOptions, type GetRecentChaptersOptions, type Media, type MediaCoverImage, MediaFormat, MediaSeason, MediaSort, MediaStatus, type MediaTag, type MediaTitle, type MediaTrailer, MediaType, MemoryCache, type PageInfo, type PagedResult, type RateLimitOptions, RateLimiter, type SearchCharacterOptions, type SearchMediaOptions, type SearchStaffOptions, type Staff, type StaffImage, type StaffName, type Studio, type StudioConnection, 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 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 };