ani-client 1.0.0 → 1.2.0

package/dist/index.d.ts

@@ -46,6 +46,16 @@ declare enum MediaSort {
     UPDATED_AT = "UPDATED_AT",
     SEARCH_MATCH = "SEARCH_MATCH"
 }
+declare enum AiringSort {
+    ID = "ID",
+    ID_DESC = "ID_DESC",
+    MEDIA_ID = "MEDIA_ID",
+    MEDIA_ID_DESC = "MEDIA_ID_DESC",
+    TIME = "TIME",
+    TIME_DESC = "TIME_DESC",
+    EPISODE = "EPISODE",
+    EPISODE_DESC = "EPISODE_DESC"
+}
 declare enum CharacterSort {
     ID = "ID",
     ROLE = "ROLE",
@@ -91,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;
@@ -135,6 +167,7 @@ interface Media {
     trending: number | null;
     tags: MediaTag[];
     studios: StudioConnection;
+    relations: MediaConnection | null;
     isAdult: boolean | null;
     siteUrl: string | null;
 }
@@ -210,6 +243,14 @@ interface User {
         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;
@@ -242,10 +283,162 @@ interface SearchStaffOptions {
     page?: number;
     perPage?: number;
 }
+interface PaginatedOptions {
+    page?: number;
+    perPage?: number;
+}
 interface PagedResult<T> {
     pageInfo: PageInfo;
     results: T[];
 }
+interface GetAiringOptions {
+    /** Only show episodes that aired after this UNIX timestamp */
+    airingAtGreater?: number;
+    /** Only show episodes that aired before this UNIX timestamp */
+    airingAtLesser?: number;
+    /** Sort order (default: TIME_DESC) */
+    sort?: AiringSort[];
+    page?: number;
+    perPage?: number;
+}
+interface GetRecentChaptersOptions {
+    /** Page number (default: 1) */
+    page?: number;
+    /** Results per page (default: 20, max 50) */
+    perPage?: number;
+}
+interface GetPlanningOptions {
+    /** Filter by ANIME or MANGA (returns both if omitted) */
+    type?: MediaType;
+    /** Sort order (default: POPULARITY_DESC) */
+    sort?: MediaSort[];
+    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;
@@ -366,6 +559,176 @@ declare class AniListClient {
      * @param variables - Optional variables object
      */
     raw<T = unknown>(query: string, variables?: Record<string, unknown>): Promise<T>;
+    /**
+     * Get recently aired anime episodes.
+     *
+     * By default returns episodes that aired in the last 24 hours.
+     *
+     * @param options - Filter / pagination parameters
+     * @returns Paginated list of airing schedule entries
+     *
+     * @example
+     * ```ts
+     * // Episodes that aired in the last 48h
+     * const recent = await client.getAiredEpisodes({
+     *   airingAtGreater: Math.floor(Date.now() / 1000) - 48 * 3600,
+     * });
+     * ```
+     */
+    getAiredEpisodes(options?: GetAiringOptions): Promise<PagedResult<AiringSchedule>>;
+    /**
+     * Get manga that are currently releasing, sorted by most recently updated.
+     *
+     * This is the closest equivalent to "recently released chapters" on AniList,
+     * since the API does not expose per-chapter airing schedules for manga.
+     *
+     * @param options - Pagination parameters
+     * @returns Paginated list of currently releasing manga
+     *
+     * @example
+     * ```ts
+     * const chapters = await client.getAiredChapters({ perPage: 10 });
+     * ```
+     */
+    getAiredChapters(options?: GetRecentChaptersOptions): Promise<PagedResult<Media>>;
+    /**
+     * Get upcoming (not yet released) anime and/or manga, sorted by popularity.
+     *
+     * @param options - Filter / pagination parameters
+     * @returns Paginated list of planned media
+     *
+     * @example
+     * ```ts
+     * import { MediaType } from "ani-client";
+     *
+     * // Most anticipated upcoming anime
+     * const planning = await client.getPlanning({ type: MediaType.ANIME, perPage: 10 });
+     * ```
+     */
+    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.
      */
@@ -458,4 +821,4 @@ declare class RateLimiter {
     private sleep;
 }
 
-export { AniListClient, type AniListClientOptions, AniListError, type CacheOptions, type Character, type CharacterImage, type CharacterName, CharacterSort, type FuzzyDate, 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 };