ani-client 1.5.1 → 1.6.0

package/README.md

@@ -1,12 +1,13 @@
-# ani-client
+# ani-client 
 
+![ani-client logo](docs/public/assets/logo.png)
 [![CI](https://github.com/gonzyui/ani-client/actions/workflows/ci.yml/badge.svg)](https://github.com/gonzyui/ani-client/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/ani-client)](https://www.npmjs.com/package/ani-client)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
 > A simple, typed client to fetch anime, manga, character, staff and user data from [AniList](https://anilist.co).
 
-✨ **Showcase**: [Check here](https://docs-aniclient.gonzyuidev.xyz/showcase) to see which projects use this package!
+✨ **Showcase**: [Check here](https://gonzyuidev.xyz/projects/aniclient/showcase) to see which projects use this package!
 
 - **Zero dependencies** — uses the native `fetch` API
 - **Universal** — Node.js ≥ 20, Bun, Deno and modern browsers
@@ -17,7 +18,7 @@
 
 The full API reference, usage guide, and configuration examples are available on our official documentation website!
 
-**[👉 View the full documentation here](https://docs-aniclient.gonzyuidev.xyz/)**
+**[👉 View the full documentation here](https://gonzyuidev.xyz/projects/aniclient/)**
 
 ## Install
 
@@ -55,6 +56,43 @@ const results = await client.searchMedia({
 console.log(results.results.map((m) => m.title.english));
 ```
 
+### Fetch user favorites
+
+```ts
+const favs = await client.getUserFavorites("AniList");
+
+favs.anime.forEach((a) => console.log(a.title.romaji));
+favs.characters.forEach((c) => console.log(c.name.full));
+```
+
+### Monitor rate limits
+
+```ts
+const client = new AniListClient({
+  rateLimit: {
+    retryStrategy: (attempt) => (attempt + 1) * 1000, // linear backoff
+  },
+});
+
+await client.getMedia(1);
+
+const info = client.rateLimitInfo;
+console.log(`${info?.remaining}/${info?.limit} requests remaining`);
+
+const meta = client.lastRequestMeta;
+console.log(`${meta?.durationMs}ms, cache: ${meta?.fromCache}`);
+```
+
+### Cancel requests
+
+```ts
+const controller = new AbortController();
+const client = new AniListClient({ signal: controller.signal });
+
+setTimeout(() => controller.abort(), 5_000);
+await client.getMedia(1); // aborted after 5s
+```
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, coding standards, and how to submit changes.

package/dist/index.d.mts

@@ -67,6 +67,16 @@ interface RateLimitOptions {
     timeoutMs?: number;
     /** Retry on network errors like ECONNRESET / ETIMEDOUT (default: true) */
     retryOnNetworkError?: boolean;
+    /**
+     * Custom retry delay strategy. Receives the attempt number (0-based) and the base delay,
+     * and should return the delay in ms before retrying.
+     * When omitted, the default exponential backoff with jitter is used.
+     *
+     * @example
+     * // Linear backoff: 1s, 2s, 3s, ...
+     * retryStrategy: (attempt) => (attempt + 1) * 1000
+     */
+    retryStrategy?: (attempt: number, baseDelayMs: number) => number;
 }
 /** Event hooks for logging, debugging, and monitoring. */
 interface AniListHooks {
@@ -79,7 +89,25 @@ interface AniListHooks {
     /** 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;
+    onResponse?: (query: string, durationMs: number, fromCache: boolean, rateLimitInfo?: RateLimitInfo) => void;
+}
+/** Rate limit information parsed from AniList API response headers. */
+interface RateLimitInfo {
+    /** Maximum number of requests allowed per window. */
+    limit: number;
+    /** Remaining requests in the current window. */
+    remaining: number;
+    /** UNIX timestamp (seconds) when the rate limit window resets. */
+    reset: number;
+}
+/** Metadata about the last request, useful for debugging and monitoring. */
+interface ResponseMeta {
+    /** Duration of the request in milliseconds. */
+    durationMs: number;
+    /** Whether the response was served from cache. */
+    fromCache: boolean;
+    /** Rate limit information from the API response headers (not present for cached responses). */
+    rateLimitInfo?: RateLimitInfo;
 }
 interface AniListClientOptions {
     /** Optional AniList OAuth token for authenticated requests */
@@ -94,6 +122,8 @@ interface AniListClientOptions {
     rateLimit?: RateLimitOptions;
     /** Event hooks for logging, debugging, and monitoring */
     hooks?: AniListHooks;
+    /** Optional AbortSignal to cancel all requests made by this client */
+    signal?: AbortSignal;
 }
 
 declare enum StaffSort {
@@ -409,6 +439,58 @@ interface SearchUserOptions {
     page?: number;
     perPage?: number;
 }
+interface FavoriteMediaNode {
+    id: number;
+    title: {
+        romaji: string | null;
+        english: string | null;
+        native: string | null;
+        userPreferred: string | null;
+    };
+    coverImage: {
+        large: string | null;
+        medium: string | null;
+    };
+    type: string | null;
+    format: string | null;
+    siteUrl: string | null;
+}
+interface FavoriteCharacterNode {
+    id: number;
+    name: {
+        full: string | null;
+        native: string | null;
+    };
+    image: {
+        large: string | null;
+        medium: string | null;
+    };
+    siteUrl: string | null;
+}
+interface FavoriteStaffNode {
+    id: number;
+    name: {
+        full: string | null;
+        native: string | null;
+    };
+    image: {
+        large: string | null;
+        medium: string | null;
+    };
+    siteUrl: string | null;
+}
+interface FavoriteStudioNode {
+    id: number;
+    name: string;
+    siteUrl: string | null;
+}
+interface UserFavorites {
+    anime: FavoriteMediaNode[];
+    manga: FavoriteMediaNode[];
+    characters: FavoriteCharacterNode[];
+    staff: FavoriteStaffNode[];
+    studios: FavoriteStudioNode[];
+}
 
 declare enum MediaType {
     ANIME = "ANIME",
@@ -877,8 +959,21 @@ declare class AniListClient {
     private readonly cacheAdapter;
     private readonly rateLimiter;
     private readonly hooks;
+    private readonly signal?;
     private readonly inFlight;
+    private _rateLimitInfo?;
+    private _lastRequestMeta?;
     constructor(options?: AniListClientOptions);
+    /**
+     * The current rate limit information from the last API response.
+     * Updated after every non-cached request.
+     */
+    get rateLimitInfo(): RateLimitInfo | undefined;
+    /**
+     * Metadata about the last request (duration, cache status, rate limit info).
+     * Useful for debugging and monitoring.
+     */
+    get lastRequestMeta(): ResponseMeta | undefined;
     /** @internal */
     request<T>(query: string, variables?: Record<string, unknown>): Promise<T>;
     /** @internal */
@@ -937,6 +1032,19 @@ declare class AniListClient {
     searchUsers(options?: SearchUserOptions): Promise<PagedResult<User>>;
     /** Get a user's anime or manga list. */
     getUserMediaList(options: GetUserMediaListOptions): Promise<PagedResult<MediaListEntry>>;
+    /**
+     * Fetch a user's favorite anime, manga, characters, staff, and studios.
+     *
+     * @param idOrName - AniList user ID (number) or username (string)
+     * @returns The user's favorites grouped by category
+     *
+     * @example
+     * ```typescript
+     * const favs = await client.getUserFavorites("AniList");
+     * favs.anime.forEach(a => console.log(a.title.romaji));
+     * ```
+     */
+    getUserFavorites(idOrName: number | string): Promise<UserFavorites>;
     /** Fetch a studio by its AniList ID. */
     getStudio(id: number): Promise<Studio>;
     /** Search for studios by name. */
@@ -1106,6 +1214,7 @@ declare class RateLimiter {
     private readonly enabled;
     private readonly timeoutMs;
     private readonly retryOnNetworkError;
+    private readonly retryStrategy?;
     /** @internal — sliding window: circular buffer of timestamps */
     private readonly timestamps;
     private head;
@@ -1123,7 +1232,7 @@ declare class RateLimiter {
         onRetry?: (attempt: number, reason: string, delayMs: number) => void;
         onRateLimit?: (retryAfterMs: number) => void;
     }): Promise<Response>;
-    /** @internal — Exponential backoff with jitter, capped at 30s */
+    /** @internal — Exponential backoff with jitter, capped at 30s (or custom strategy) */
     private exponentialDelay;
     /** @internal */
     private fetchWithTimeout;
@@ -1139,4 +1248,4 @@ declare class RateLimiter {
  */
 declare function parseAniListMarkdown(text: string): string;
 
-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 DayOfWeek, 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 SearchThreadOptions, type SearchUserOptions, type Staff, type StaffImage, type StaffIncludeOptions, type StaffMediaNode, type StaffName, StaffSort, type StatusDistribution, type StreamingEpisode, type Studio, type StudioConnection, type Thread, type ThreadCategory, type ThreadMediaCategory, ThreadSort, type User, type UserAvatar, UserSort, type UserStatistics, type VoiceActor, type WeeklySchedule, parseAniListMarkdown };
+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 DayOfWeek, type ExternalLink, type FavoriteCharacterNode, type FavoriteMediaNode, type FavoriteStaffNode, type FavoriteStudioNode, 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 RateLimitInfo, type RateLimitOptions, RateLimiter, type Recommendation, RecommendationSort, RedisCache, type RedisCacheOptions, type RedisLikeClient, type ResponseMeta, type ScoreDistribution, type SearchCharacterOptions, type SearchMediaOptions, type SearchStaffOptions, type SearchStudioOptions, type SearchThreadOptions, type SearchUserOptions, type Staff, type StaffImage, type StaffIncludeOptions, type StaffMediaNode, type StaffName, StaffSort, type StatusDistribution, type StreamingEpisode, type Studio, type StudioConnection, type Thread, type ThreadCategory, type ThreadMediaCategory, ThreadSort, type User, type UserAvatar, type UserFavorites, UserSort, type UserStatistics, type VoiceActor, type WeeklySchedule, parseAniListMarkdown };

package/dist/index.d.ts

@@ -67,6 +67,16 @@ interface RateLimitOptions {
     timeoutMs?: number;
     /** Retry on network errors like ECONNRESET / ETIMEDOUT (default: true) */
     retryOnNetworkError?: boolean;
+    /**
+     * Custom retry delay strategy. Receives the attempt number (0-based) and the base delay,
+     * and should return the delay in ms before retrying.
+     * When omitted, the default exponential backoff with jitter is used.
+     *
+     * @example
+     * // Linear backoff: 1s, 2s, 3s, ...
+     * retryStrategy: (attempt) => (attempt + 1) * 1000
+     */
+    retryStrategy?: (attempt: number, baseDelayMs: number) => number;
 }
 /** Event hooks for logging, debugging, and monitoring. */
 interface AniListHooks {
@@ -79,7 +89,25 @@ interface AniListHooks {
     /** 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;
+    onResponse?: (query: string, durationMs: number, fromCache: boolean, rateLimitInfo?: RateLimitInfo) => void;
+}
+/** Rate limit information parsed from AniList API response headers. */
+interface RateLimitInfo {
+    /** Maximum number of requests allowed per window. */
+    limit: number;
+    /** Remaining requests in the current window. */
+    remaining: number;
+    /** UNIX timestamp (seconds) when the rate limit window resets. */
+    reset: number;
+}
+/** Metadata about the last request, useful for debugging and monitoring. */
+interface ResponseMeta {
+    /** Duration of the request in milliseconds. */
+    durationMs: number;
+    /** Whether the response was served from cache. */
+    fromCache: boolean;
+    /** Rate limit information from the API response headers (not present for cached responses). */
+    rateLimitInfo?: RateLimitInfo;
 }
 interface AniListClientOptions {
     /** Optional AniList OAuth token for authenticated requests */
@@ -94,6 +122,8 @@ interface AniListClientOptions {
     rateLimit?: RateLimitOptions;
     /** Event hooks for logging, debugging, and monitoring */
     hooks?: AniListHooks;
+    /** Optional AbortSignal to cancel all requests made by this client */
+    signal?: AbortSignal;
 }
 
 declare enum StaffSort {
@@ -409,6 +439,58 @@ interface SearchUserOptions {
     page?: number;
     perPage?: number;
 }
+interface FavoriteMediaNode {
+    id: number;
+    title: {
+        romaji: string | null;
+        english: string | null;
+        native: string | null;
+        userPreferred: string | null;
+    };
+    coverImage: {
+        large: string | null;
+        medium: string | null;
+    };
+    type: string | null;
+    format: string | null;
+    siteUrl: string | null;
+}
+interface FavoriteCharacterNode {
+    id: number;
+    name: {
+        full: string | null;
+        native: string | null;
+    };
+    image: {
+        large: string | null;
+        medium: string | null;
+    };
+    siteUrl: string | null;
+}
+interface FavoriteStaffNode {
+    id: number;
+    name: {
+        full: string | null;
+        native: string | null;
+    };
+    image: {
+        large: string | null;
+        medium: string | null;
+    };
+    siteUrl: string | null;
+}
+interface FavoriteStudioNode {
+    id: number;
+    name: string;
+    siteUrl: string | null;
+}
+interface UserFavorites {
+    anime: FavoriteMediaNode[];
+    manga: FavoriteMediaNode[];
+    characters: FavoriteCharacterNode[];
+    staff: FavoriteStaffNode[];
+    studios: FavoriteStudioNode[];
+}
 
 declare enum MediaType {
     ANIME = "ANIME",
@@ -877,8 +959,21 @@ declare class AniListClient {
     private readonly cacheAdapter;
     private readonly rateLimiter;
     private readonly hooks;
+    private readonly signal?;
     private readonly inFlight;
+    private _rateLimitInfo?;
+    private _lastRequestMeta?;
     constructor(options?: AniListClientOptions);
+    /**
+     * The current rate limit information from the last API response.
+     * Updated after every non-cached request.
+     */
+    get rateLimitInfo(): RateLimitInfo | undefined;
+    /**
+     * Metadata about the last request (duration, cache status, rate limit info).
+     * Useful for debugging and monitoring.
+     */
+    get lastRequestMeta(): ResponseMeta | undefined;
     /** @internal */
     request<T>(query: string, variables?: Record<string, unknown>): Promise<T>;
     /** @internal */
@@ -937,6 +1032,19 @@ declare class AniListClient {
     searchUsers(options?: SearchUserOptions): Promise<PagedResult<User>>;
     /** Get a user's anime or manga list. */
     getUserMediaList(options: GetUserMediaListOptions): Promise<PagedResult<MediaListEntry>>;
+    /**
+     * Fetch a user's favorite anime, manga, characters, staff, and studios.
+     *
+     * @param idOrName - AniList user ID (number) or username (string)
+     * @returns The user's favorites grouped by category
+     *
+     * @example
+     * ```typescript
+     * const favs = await client.getUserFavorites("AniList");
+     * favs.anime.forEach(a => console.log(a.title.romaji));
+     * ```
+     */
+    getUserFavorites(idOrName: number | string): Promise<UserFavorites>;
     /** Fetch a studio by its AniList ID. */
     getStudio(id: number): Promise<Studio>;
     /** Search for studios by name. */
@@ -1106,6 +1214,7 @@ declare class RateLimiter {
     private readonly enabled;
     private readonly timeoutMs;
     private readonly retryOnNetworkError;
+    private readonly retryStrategy?;
     /** @internal — sliding window: circular buffer of timestamps */
     private readonly timestamps;
     private head;
@@ -1123,7 +1232,7 @@ declare class RateLimiter {
         onRetry?: (attempt: number, reason: string, delayMs: number) => void;
         onRateLimit?: (retryAfterMs: number) => void;
     }): Promise<Response>;
-    /** @internal — Exponential backoff with jitter, capped at 30s */
+    /** @internal — Exponential backoff with jitter, capped at 30s (or custom strategy) */
     private exponentialDelay;
     /** @internal */
     private fetchWithTimeout;
@@ -1139,4 +1248,4 @@ declare class RateLimiter {
  */
 declare function parseAniListMarkdown(text: string): string;
 
-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 DayOfWeek, 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 SearchThreadOptions, type SearchUserOptions, type Staff, type StaffImage, type StaffIncludeOptions, type StaffMediaNode, type StaffName, StaffSort, type StatusDistribution, type StreamingEpisode, type Studio, type StudioConnection, type Thread, type ThreadCategory, type ThreadMediaCategory, ThreadSort, type User, type UserAvatar, UserSort, type UserStatistics, type VoiceActor, type WeeklySchedule, parseAniListMarkdown };
+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 DayOfWeek, type ExternalLink, type FavoriteCharacterNode, type FavoriteMediaNode, type FavoriteStaffNode, type FavoriteStudioNode, 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 RateLimitInfo, type RateLimitOptions, RateLimiter, type Recommendation, RecommendationSort, RedisCache, type RedisCacheOptions, type RedisLikeClient, type ResponseMeta, type ScoreDistribution, type SearchCharacterOptions, type SearchMediaOptions, type SearchStaffOptions, type SearchStudioOptions, type SearchThreadOptions, type SearchUserOptions, type Staff, type StaffImage, type StaffIncludeOptions, type StaffMediaNode, type StaffName, StaffSort, type StatusDistribution, type StreamingEpisode, type Studio, type StudioConnection, type Thread, type ThreadCategory, type ThreadMediaCategory, ThreadSort, type User, type UserAvatar, type UserFavorites, UserSort, type UserStatistics, type VoiceActor, type WeeklySchedule, parseAniListMarkdown };