ani-client 1.1.0 → 1.2.0

package/README.md

@@ -69,6 +69,8 @@ client.getMedia(1).then((anime) => console.log(anime.title.romaji));
 | `getMedia(id: number)`              | Fetch a single anime / manga by ID   |
 | `searchMedia(options?)`             | Search & filter anime / manga        |
 | `getTrending(type?, page?, perPage?)` | Get currently trending entries      |
+| `getMediaBySeason(options)`         | Get all anime/manga for a given season & year |
+| `getRecommendations(mediaId, options?)` | Get user recommendations for a media |
 
 ### Characters
 
@@ -90,6 +92,7 @@ client.getMedia(1).then((anime) => console.log(anime.title.romaji));
 | ----------------------------------- | ------------------------------------ |
 | `getUser(id: number)`               | Fetch a user by ID                   |
 | `getUserByName(name: string)`       | Fetch a user by username             |
+| `getUserMediaList(options)`         | Get a user's anime or manga list     |
 
 ### Airing, Chapters & Planning
 
@@ -99,12 +102,32 @@ client.getMedia(1).then((anime) => console.log(anime.title.romaji));
 | `getAiredChapters(options?)`        | Recently updated releasing manga     |
 | `getPlanning(options?)`             | Upcoming not-yet-released anime / manga |
 
+### Studios
+
+| Method                              | Description                          |
+| ----------------------------------- | ------------------------------------ |
+| `getStudio(id: number)`             | Fetch a studio by ID                 |
+| `searchStudios(options?)`           | Search studios by name               |
+
+### Genres & Tags
+
+| Method                              | Description                          |
+| ----------------------------------- | ------------------------------------ |
+| `getGenres()`                       | List all available genres            |
+| `getTags()`                         | List all available media tags        |
+
 ### Raw queries
 
 | Method                              | Description                          |
 | ----------------------------------- | ------------------------------------ |
 | `raw<T>(query, variables?)`         | Execute any GraphQL query            |
 
+### Pagination helper
+
+| Method                              | Description                          |
+| ----------------------------------- | ------------------------------------ |
+| `paginate<T>(fetchPage, maxPages?)` | Auto-paginating async iterator       |
+
 ### Cache management
 
 | Method / Property                   | Description                          |
@@ -218,6 +241,189 @@ upcoming.results.forEach((m) => console.log(m.title.romaji));
 const all = await client.getPlanning();
 ```
 
+## Season charts
+
+Fetch all anime (or manga) for a specific season and year.
+
+### `getMediaBySeason(options)`
+
+| Option       | Type           | Default              | Description                              |
+| ------------ | -------------- | -------------------- | ---------------------------------------- |
+| `season`     | `MediaSeason`  | **(required)**       | WINTER, SPRING, SUMMER, or FALL          |
+| `seasonYear` | `number`       | **(required)**       | The year (e.g. 2026)                     |
+| `type`       | `MediaType`    | `ANIME`              | Filter by ANIME or MANGA                 |
+| `sort`       | `MediaSort[]`  | `["POPULARITY_DESC"]`| Sort order                               |
+| `page`       | `number`       | `1`                  | Page number                              |
+| `perPage`    | `number`       | `20`                 | Results per page (max 50)                |
+
+```ts
+import { AniListClient, MediaSeason } from "ani-client";
+
+const client = new AniListClient();
+
+// All anime from Winter 2026
+const winter2026 = await client.getMediaBySeason({
+  season: MediaSeason.WINTER,
+  seasonYear: 2026,
+  perPage: 25,
+});
+winter2026.results.forEach((m) => console.log(m.title.romaji));
+
+// Spring 2025 manga
+const spring = await client.getMediaBySeason({
+  season: MediaSeason.SPRING,
+  seasonYear: 2025,
+  type: MediaType.MANGA,
+});
+```
+
+## User media lists
+
+Fetch a user's anime or manga list, optionally filtered by status.
+
+### `getUserMediaList(options)`
+
+| Option     | Type              | Default              | Description                                |
+| ---------- | ----------------- | -------------------- | ------------------------------------------ |
+| `userId`   | `number`          | —                    | User ID (provide userId **or** userName)   |
+| `userName` | `string`          | —                    | Username (provide userId **or** userName)  |
+| `type`     | `MediaType`       | **(required)**       | ANIME or MANGA                             |
+| `status`   | `MediaListStatus` | —                    | Filter: CURRENT, COMPLETED, PLANNING, etc. |
+| `sort`     | `MediaListSort[]` | —                    | Sort order                                 |
+| `page`     | `number`          | `1`                  | Page number                                |
+| `perPage`  | `number`          | `20`                 | Results per page (max 50)                  |
+
+```ts
+import { AniListClient, MediaType, MediaListStatus } from "ani-client";
+
+const client = new AniListClient();
+
+// All anime on a user's list
+const list = await client.getUserMediaList({
+  userName: "AniList",
+  type: MediaType.ANIME,
+  perPage: 10,
+});
+list.results.forEach((entry) =>
+  console.log(`${entry.media.title.romaji} — ${entry.score}/100`)
+);
+
+// Only completed anime
+const completed = await client.getUserMediaList({
+  userName: "AniList",
+  type: MediaType.ANIME,
+  status: MediaListStatus.COMPLETED,
+});
+
+// By user ID
+const byId = await client.getUserMediaList({
+  userId: 1,
+  type: MediaType.MANGA,
+});
+```
+
+## Recommendations
+
+Get user-submitted recommendations for a specific anime or manga.
+
+### `getRecommendations(mediaId, options?)`
+
+| Option    | Type                   | Default            | Description             |
+| --------- | ---------------------- | ------------------ | ----------------------- |
+| `sort`    | `RecommendationSort[]` | `["RATING_DESC"]`  | Sort order              |
+| `page`    | `number`               | `1`                | Page number             |
+| `perPage` | `number`               | `20`               | Results per page        |
+
+```ts
+import { AniListClient } from "ani-client";
+
+const client = new AniListClient();
+
+// Recommendations for Cowboy Bebop
+const recs = await client.getRecommendations(1);
+recs.results.forEach((r) =>
+  console.log(`${r.mediaRecommendation.title.romaji} (rating: ${r.rating})`)
+);
+
+// With pagination
+const page2 = await client.getRecommendations(20, { page: 2, perPage: 10 });
+```
+
+## Relations
+
+All media objects now include a `relations` field with sequels, prequels, spin-offs, etc.
+
+```ts
+const anime = await client.getMedia(1); // Cowboy Bebop
+anime.relations?.edges.forEach((edge) =>
+  console.log(`${edge.relationType}: ${edge.node.title.romaji}`)
+);
+// SIDE_STORY: Cowboy Bebop: Tengoku no Tobira
+```
+
+Available relation types: `ADAPTATION`, `PREQUEL`, `SEQUEL`, `PARENT`, `SIDE_STORY`, `CHARACTER`, `SUMMARY`, `ALTERNATIVE`, `SPIN_OFF`, `OTHER`, `SOURCE`, `COMPILATION`, `CONTAINS`.
+
+## Studios
+
+Fetch or search for animation studios.
+
+### `getStudio(id)`
+
+Returns the studio with its most popular productions.
+
+```ts
+const studio = await client.getStudio(44); // Bones
+console.log(studio.name); // "Bones"
+console.log(studio.isAnimationStudio); // true
+studio.media?.nodes.forEach((m) => console.log(m.title.romaji));
+```
+
+### `searchStudios(options?)`
+
+| Option    | Type     | Default | Description             |
+| --------- | -------- | ------- | ----------------------- |
+| `query`   | `string` | —       | Search term             |
+| `page`    | `number` | `1`     | Page number             |
+| `perPage` | `number` | `20`    | Results per page        |
+
+```ts
+const result = await client.searchStudios({ query: "MAPPA" });
+result.results.forEach((s) => console.log(s.name));
+```
+
+## Genres & Tags
+
+List all genres and tags available on AniList.
+
+```ts
+const genres = await client.getGenres();
+console.log(genres); // ["Action", "Adventure", "Comedy", ...]
+
+const tags = await client.getTags();
+tags.forEach((t) => console.log(`${t.name} (${t.category})`));
+```
+
+## Auto-pagination
+
+Use `paginate()` to iterate across all pages automatically with an async iterator.
+
+```ts
+// Iterate over all search results
+for await (const anime of client.paginate((page) =>
+  client.searchMedia({ query: "Gundam", page, perPage: 10 })
+)) {
+  console.log(anime.title.romaji);
+}
+
+// Limit to 3 pages max
+for await (const anime of client.paginate(
+  (page) => client.getTrending(MediaType.ANIME, page, 20),
+  3,
+)) {
+  console.log(anime.title.romaji);
+}
+```
+
 ## Error handling
 
 All API errors throw an `AniListError` with:
@@ -249,11 +455,20 @@ import type {
   Staff,
   User,
   AiringSchedule,
+  MediaListEntry,
+  Recommendation,
+  StudioDetail,
+  MediaEdge,
+  MediaConnection,
   PagedResult,
   SearchMediaOptions,
+  SearchStudioOptions,
   GetAiringOptions,
   GetRecentChaptersOptions,
   GetPlanningOptions,
+  GetSeasonOptions,
+  GetUserMediaListOptions,
+  GetRecommendationsOptions,
 } from "ani-client";
 ```
 

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;
 }
@@ -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 };