ani-client 1.1.0 → 1.2.0

package/dist/index.d.ts

@@ -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;
 }
@@ -260,6 +283,10 @@ interface SearchStaffOptions {
     page?: number;
     perPage?: number;
 }
+interface PaginatedOptions {
+    page?: number;
+    perPage?: number;
+}
 interface PagedResult<T> {
     pageInfo: PageInfo;
     results: T[];
@@ -288,6 +315,130 @@ 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 AniListClientOptions {
     /** Optional AniList OAuth token for authenticated requests */
     token?: string;
@@ -455,6 +606,129 @@ 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>;
     /**
      * Clear the entire response cache.
      */
@@ -547,4 +821,4 @@ declare class RateLimiter {
     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 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 PaginatedOptions, type RateLimitOptions, RateLimiter, type Recommendation, RecommendationSort, 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 };