ani-client 1.3.0 → 1.4.1

package/dist/index.js

@@ -1,7 +1,7 @@
 'use strict';
 
 // src/queries/index.ts
-var MEDIA_FIELDS = `
+var MEDIA_FIELDS_BASE = `
   id
   idMal
   title { romaji english native userPreferred }
@@ -33,6 +33,10 @@ var MEDIA_FIELDS = `
   trending
   tags { id name description category rank isMediaSpoiler }
   studios { nodes { id name isAnimationStudio siteUrl } }
+  isAdult
+  siteUrl
+`;
+var RELATIONS_FIELDS = `
   relations {
     edges {
       relationType(version: 2)
@@ -47,10 +51,12 @@ var MEDIA_FIELDS = `
       }
     }
   }
-  isAdult
-  siteUrl
 `;
-var CHARACTER_FIELDS = `
+var MEDIA_FIELDS = `
+  ${MEDIA_FIELDS_BASE}
+  ${RELATIONS_FIELDS}
+`;
+var CHARACTER_FIELDS_COMPACT = `
   id
   name { first middle last full native alternative }
   image { large medium }
@@ -61,6 +67,8 @@ var CHARACTER_FIELDS = `
   bloodType
   favourites
   siteUrl
+`;
+var CHARACTER_MEDIA_NODES = `
   media(perPage: 10) {
     nodes {
       id
@@ -71,6 +79,39 @@ var CHARACTER_FIELDS = `
     }
   }
 `;
+var VOICE_ACTOR_FIELDS_COMPACT = `
+  id
+  name { first middle last full native userPreferred }
+  languageV2
+  image { large medium }
+  gender
+  primaryOccupations
+  siteUrl
+`;
+var CHARACTER_MEDIA_EDGES_WITH_VA = `
+  media(perPage: 10) {
+    edges {
+      voiceActors {
+        ${VOICE_ACTOR_FIELDS_COMPACT}
+      }
+      node {
+        id
+        title { romaji english native userPreferred }
+        type
+        coverImage { large medium }
+        siteUrl
+      }
+    }
+  }
+`;
+var CHARACTER_FIELDS = `
+  ${CHARACTER_FIELDS_COMPACT}
+  ${CHARACTER_MEDIA_NODES}
+`;
+var CHARACTER_FIELDS_WITH_VA = `
+  ${CHARACTER_FIELDS_COMPACT}
+  ${CHARACTER_MEDIA_EDGES_WITH_VA}
+`;
 var STAFF_FIELDS = `
   id
   name { first middle last full native }
@@ -140,7 +181,7 @@ query (
       isAdult: $isAdult,
       sort: $sort
     ) {
-      ${MEDIA_FIELDS}
+      ${MEDIA_FIELDS_BASE}
     }
   }
 }`;
@@ -149,7 +190,7 @@ query ($type: MediaType, $page: Int, $perPage: Int) {
   Page(page: $page, perPage: $perPage) {
     pageInfo { total perPage currentPage lastPage hasNextPage }
     media(type: $type, sort: TRENDING_DESC) {
-      ${MEDIA_FIELDS}
+      ${MEDIA_FIELDS_BASE}
     }
   }
 }`;
@@ -159,6 +200,12 @@ query ($id: Int!) {
     ${CHARACTER_FIELDS}
   }
 }`;
+var QUERY_CHARACTER_BY_ID_WITH_VA = `
+query ($id: Int!) {
+  Character(id: $id) {
+    ${CHARACTER_FIELDS_WITH_VA}
+  }
+}`;
 var QUERY_CHARACTER_SEARCH = `
 query ($search: String, $sort: [CharacterSort], $page: Int, $perPage: Int) {
   Page(page: $page, perPage: $perPage) {
@@ -168,6 +215,15 @@ query ($search: String, $sort: [CharacterSort], $page: Int, $perPage: Int) {
     }
   }
 }`;
+var QUERY_CHARACTER_SEARCH_WITH_VA = `
+query ($search: String, $sort: [CharacterSort], $page: Int, $perPage: Int) {
+  Page(page: $page, perPage: $perPage) {
+    pageInfo { total perPage currentPage lastPage hasNextPage }
+    characters(search: $search, sort: $sort) {
+      ${CHARACTER_FIELDS_WITH_VA}
+    }
+  }
+}`;
 var QUERY_STAFF_BY_ID = `
 query ($id: Int!) {
   Staff(id: $id) {
@@ -175,10 +231,10 @@ query ($id: Int!) {
   }
 }`;
 var QUERY_STAFF_SEARCH = `
-query ($search: String, $page: Int, $perPage: Int) {
+query ($search: String, $sort: [StaffSort], $page: Int, $perPage: Int) {
   Page(page: $page, perPage: $perPage) {
     pageInfo { total perPage currentPage lastPage hasNextPage }
-    staff(search: $search) {
+    staff(search: $search, sort: $sort) {
       ${STAFF_FIELDS}
     }
   }
@@ -206,7 +262,7 @@ query ($airingAt_greater: Int, $airingAt_lesser: Int, $sort: [AiringSort], $page
       episode
       mediaId
       media {
-        ${MEDIA_FIELDS}
+        ${MEDIA_FIELDS_BASE}
       }
     }
   }
@@ -216,7 +272,7 @@ query ($page: Int, $perPage: Int) {
   Page(page: $page, perPage: $perPage) {
     pageInfo { total perPage currentPage lastPage hasNextPage }
     media(type: MANGA, status: RELEASING, sort: UPDATED_AT_DESC) {
-      ${MEDIA_FIELDS}
+      ${MEDIA_FIELDS_BASE}
     }
   }
 }`;
@@ -225,7 +281,7 @@ query ($type: MediaType, $sort: [MediaSort], $page: Int, $perPage: Int) {
   Page(page: $page, perPage: $perPage) {
     pageInfo { total perPage currentPage lastPage hasNextPage }
     media(type: $type, status: NOT_YET_RELEASED, sort: $sort) {
-      ${MEDIA_FIELDS}
+      ${MEDIA_FIELDS_BASE}
     }
   }
 }`;
@@ -234,7 +290,7 @@ query ($season: MediaSeason!, $seasonYear: Int!, $type: MediaType, $sort: [Media
   Page(page: $page, perPage: $perPage) {
     pageInfo { total perPage currentPage lastPage hasNextPage }
     media(season: $season, seasonYear: $seasonYear, type: $type, sort: $sort) {
-      ${MEDIA_FIELDS}
+      ${MEDIA_FIELDS_BASE}
     }
   }
 }`;
@@ -254,7 +310,7 @@ var MEDIA_LIST_FIELDS = `
   updatedAt
   createdAt
   media {
-    ${MEDIA_FIELDS}
+    ${MEDIA_FIELDS_BASE}
   }
 `;
 var QUERY_RECOMMENDATIONS = `
@@ -347,13 +403,105 @@ query {
     isAdult
   }
 }`;
+function buildMediaByIdQuery(include) {
+  if (!include) return QUERY_MEDIA_BY_ID;
+  const extra = [];
+  if (include.relations !== false) {
+    extra.push(RELATIONS_FIELDS);
+  }
+  if (include.characters) {
+    const opts = typeof include.characters === "object" ? include.characters : {};
+    const perPage = opts.perPage ?? 25;
+    const sortClause = opts.sort !== false ? ", sort: [ROLE, RELEVANCE, ID]" : "";
+    const voiceActorBlock = opts.voiceActors ? `
+            voiceActors {
+              ${VOICE_ACTOR_FIELDS_COMPACT}
+            }` : "";
+    extra.push(`
+    characters(perPage: ${perPage}${sortClause}) {
+      edges {
+        role
+        node {
+          ${CHARACTER_FIELDS_COMPACT}
+        }${voiceActorBlock}
+      }
+    }`);
+  }
+  if (include.staff) {
+    const opts = typeof include.staff === "object" ? include.staff : {};
+    const perPage = opts.perPage ?? 25;
+    const sortClause = opts.sort !== false ? ", sort: [RELEVANCE, ID]" : "";
+    extra.push(`
+    staff(perPage: ${perPage}${sortClause}) {
+      edges {
+        role
+        node {
+          ${STAFF_FIELDS}
+        }
+      }
+    }`);
+  }
+  if (include.recommendations) {
+    const perPage = typeof include.recommendations === "object" ? include.recommendations.perPage ?? 10 : 10;
+    extra.push(`
+    recommendations(perPage: ${perPage}, sort: [RATING_DESC]) {
+      nodes {
+        id
+        rating
+        mediaRecommendation {
+          id
+          title { romaji english native userPreferred }
+          type
+          format
+          coverImage { large medium }
+          averageScore
+          siteUrl
+        }
+      }
+    }`);
+  }
+  if (include.streamingEpisodes) {
+    extra.push(`
+    streamingEpisodes {
+      title
+      thumbnail
+      url
+      site
+    }`);
+  }
+  if (include.externalLinks) {
+    extra.push(`
+    externalLinks {
+      id
+      url
+      site
+      type
+      icon
+      color
+    }`);
+  }
+  if (include.stats) {
+    extra.push(`
+    stats {
+      scoreDistribution { score amount }
+      statusDistribution { status amount }
+    }`);
+  }
+  return `
+query ($id: Int!) {
+  Media(id: $id) {
+    ${MEDIA_FIELDS_BASE}
+    ${extra.join("\n")}
+  }
+}`;
+}
 function buildBatchQuery(ids, typeName, fields, prefix) {
   const aliases = ids.map((id, i) => `${prefix}${i}: ${typeName}(id: ${id}) { ${fields} }`).join("\n  ");
   return `query {
   ${aliases}
 }`;
 }
-var buildBatchMediaQuery = (ids) => buildBatchQuery(ids, "Media", MEDIA_FIELDS, "m");
+var buildBatchMediaQuery = (ids) => buildBatchQuery(ids, "Media", MEDIA_FIELDS_BASE, "m");
 var buildBatchCharacterQuery = (ids) => buildBatchQuery(ids, "Character", CHARACTER_FIELDS, "c");
 var buildBatchStaffQuery = (ids) => buildBatchQuery(ids, "Staff", STAFF_FIELDS, "s");
 
@@ -368,7 +516,8 @@ var MemoryCache = class {
   }
   /** Build a deterministic cache key from a query + variables pair. */
   static key(query, variables) {
-    return `${query.trim()}|${JSON.stringify(variables, Object.keys(variables).sort())}`;
+    const normalized = query.replace(/\s+/g, " ").trim();
+    return `${normalized}|${JSON.stringify(variables, Object.keys(variables).sort())}`;
   }
   /** Retrieve a cached value, or `undefined` if missing / expired. */
   get(key) {
@@ -405,9 +554,9 @@ var MemoryCache = class {
   get size() {
     return this.store.size;
   }
-  /** Return an iterator over all cache keys. */
+  /** Return all cache keys. */
   keys() {
-    return this.store.keys();
+    return [...this.store.keys()];
   }
   /**
    * Remove all entries whose key matches the given pattern.
@@ -416,25 +565,26 @@ var MemoryCache = class {
    * @returns Number of entries removed.
    */
   invalidate(pattern) {
-    const regex = typeof pattern === "string" ? new RegExp(pattern) : pattern;
-    let count = 0;
-    for (const key of [...this.store.keys()]) {
-      if (regex.test(key)) {
-        this.store.delete(key);
-        count++;
-      }
+    const regex = typeof pattern === "string" ? new RegExp(pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")) : pattern;
+    const toDelete = [];
+    for (const key of this.store.keys()) {
+      if (regex.test(key)) toDelete.push(key);
     }
-    return count;
+    for (const key of toDelete) this.store.delete(key);
+    return toDelete.length;
   }
 };
 
 // src/errors/index.ts
-var AniListError = class extends Error {
+var AniListError = class _AniListError extends Error {
   constructor(message, status, errors = []) {
     super(message);
     this.name = "AniListError";
     this.status = status;
     this.errors = errors;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _AniListError);
+    }
   }
 };
 
@@ -533,6 +683,169 @@ function isNetworkError(err) {
   return false;
 }
 
+// src/types/index.ts
+var MediaType = /* @__PURE__ */ ((MediaType2) => {
+  MediaType2["ANIME"] = "ANIME";
+  MediaType2["MANGA"] = "MANGA";
+  return MediaType2;
+})(MediaType || {});
+var MediaFormat = /* @__PURE__ */ ((MediaFormat2) => {
+  MediaFormat2["TV"] = "TV";
+  MediaFormat2["TV_SHORT"] = "TV_SHORT";
+  MediaFormat2["MOVIE"] = "MOVIE";
+  MediaFormat2["SPECIAL"] = "SPECIAL";
+  MediaFormat2["OVA"] = "OVA";
+  MediaFormat2["ONA"] = "ONA";
+  MediaFormat2["MUSIC"] = "MUSIC";
+  MediaFormat2["MANGA"] = "MANGA";
+  MediaFormat2["NOVEL"] = "NOVEL";
+  MediaFormat2["ONE_SHOT"] = "ONE_SHOT";
+  return MediaFormat2;
+})(MediaFormat || {});
+var MediaStatus = /* @__PURE__ */ ((MediaStatus2) => {
+  MediaStatus2["FINISHED"] = "FINISHED";
+  MediaStatus2["RELEASING"] = "RELEASING";
+  MediaStatus2["NOT_YET_RELEASED"] = "NOT_YET_RELEASED";
+  MediaStatus2["CANCELLED"] = "CANCELLED";
+  MediaStatus2["HIATUS"] = "HIATUS";
+  return MediaStatus2;
+})(MediaStatus || {});
+var MediaSeason = /* @__PURE__ */ ((MediaSeason2) => {
+  MediaSeason2["WINTER"] = "WINTER";
+  MediaSeason2["SPRING"] = "SPRING";
+  MediaSeason2["SUMMER"] = "SUMMER";
+  MediaSeason2["FALL"] = "FALL";
+  return MediaSeason2;
+})(MediaSeason || {});
+var MediaSort = /* @__PURE__ */ ((MediaSort2) => {
+  MediaSort2["ID"] = "ID";
+  MediaSort2["ID_DESC"] = "ID_DESC";
+  MediaSort2["TITLE_ROMAJI"] = "TITLE_ROMAJI";
+  MediaSort2["TITLE_ROMAJI_DESC"] = "TITLE_ROMAJI_DESC";
+  MediaSort2["TITLE_ENGLISH"] = "TITLE_ENGLISH";
+  MediaSort2["TITLE_ENGLISH_DESC"] = "TITLE_ENGLISH_DESC";
+  MediaSort2["TITLE_NATIVE"] = "TITLE_NATIVE";
+  MediaSort2["TITLE_NATIVE_DESC"] = "TITLE_NATIVE_DESC";
+  MediaSort2["TYPE"] = "TYPE";
+  MediaSort2["TYPE_DESC"] = "TYPE_DESC";
+  MediaSort2["FORMAT"] = "FORMAT";
+  MediaSort2["FORMAT_DESC"] = "FORMAT_DESC";
+  MediaSort2["START_DATE"] = "START_DATE";
+  MediaSort2["START_DATE_DESC"] = "START_DATE_DESC";
+  MediaSort2["END_DATE"] = "END_DATE";
+  MediaSort2["END_DATE_DESC"] = "END_DATE_DESC";
+  MediaSort2["SCORE"] = "SCORE";
+  MediaSort2["SCORE_DESC"] = "SCORE_DESC";
+  MediaSort2["POPULARITY"] = "POPULARITY";
+  MediaSort2["POPULARITY_DESC"] = "POPULARITY_DESC";
+  MediaSort2["TRENDING"] = "TRENDING";
+  MediaSort2["TRENDING_DESC"] = "TRENDING_DESC";
+  MediaSort2["EPISODES"] = "EPISODES";
+  MediaSort2["EPISODES_DESC"] = "EPISODES_DESC";
+  MediaSort2["DURATION"] = "DURATION";
+  MediaSort2["DURATION_DESC"] = "DURATION_DESC";
+  MediaSort2["STATUS"] = "STATUS";
+  MediaSort2["STATUS_DESC"] = "STATUS_DESC";
+  MediaSort2["FAVOURITES"] = "FAVOURITES";
+  MediaSort2["FAVOURITES_DESC"] = "FAVOURITES_DESC";
+  MediaSort2["UPDATED_AT"] = "UPDATED_AT";
+  MediaSort2["UPDATED_AT_DESC"] = "UPDATED_AT_DESC";
+  MediaSort2["SEARCH_MATCH"] = "SEARCH_MATCH";
+  return MediaSort2;
+})(MediaSort || {});
+var AiringSort = /* @__PURE__ */ ((AiringSort2) => {
+  AiringSort2["ID"] = "ID";
+  AiringSort2["ID_DESC"] = "ID_DESC";
+  AiringSort2["MEDIA_ID"] = "MEDIA_ID";
+  AiringSort2["MEDIA_ID_DESC"] = "MEDIA_ID_DESC";
+  AiringSort2["TIME"] = "TIME";
+  AiringSort2["TIME_DESC"] = "TIME_DESC";
+  AiringSort2["EPISODE"] = "EPISODE";
+  AiringSort2["EPISODE_DESC"] = "EPISODE_DESC";
+  return AiringSort2;
+})(AiringSort || {});
+var CharacterSort = /* @__PURE__ */ ((CharacterSort2) => {
+  CharacterSort2["ID"] = "ID";
+  CharacterSort2["ID_DESC"] = "ID_DESC";
+  CharacterSort2["ROLE"] = "ROLE";
+  CharacterSort2["ROLE_DESC"] = "ROLE_DESC";
+  CharacterSort2["SEARCH_MATCH"] = "SEARCH_MATCH";
+  CharacterSort2["FAVOURITES"] = "FAVOURITES";
+  CharacterSort2["FAVOURITES_DESC"] = "FAVOURITES_DESC";
+  return CharacterSort2;
+})(CharacterSort || {});
+var CharacterRole = /* @__PURE__ */ ((CharacterRole2) => {
+  CharacterRole2["MAIN"] = "MAIN";
+  CharacterRole2["SUPPORTING"] = "SUPPORTING";
+  CharacterRole2["BACKGROUND"] = "BACKGROUND";
+  return CharacterRole2;
+})(CharacterRole || {});
+var MediaRelationType = /* @__PURE__ */ ((MediaRelationType2) => {
+  MediaRelationType2["ADAPTATION"] = "ADAPTATION";
+  MediaRelationType2["PREQUEL"] = "PREQUEL";
+  MediaRelationType2["SEQUEL"] = "SEQUEL";
+  MediaRelationType2["PARENT"] = "PARENT";
+  MediaRelationType2["SIDE_STORY"] = "SIDE_STORY";
+  MediaRelationType2["CHARACTER"] = "CHARACTER";
+  MediaRelationType2["SUMMARY"] = "SUMMARY";
+  MediaRelationType2["ALTERNATIVE"] = "ALTERNATIVE";
+  MediaRelationType2["SPIN_OFF"] = "SPIN_OFF";
+  MediaRelationType2["OTHER"] = "OTHER";
+  MediaRelationType2["SOURCE"] = "SOURCE";
+  MediaRelationType2["COMPILATION"] = "COMPILATION";
+  MediaRelationType2["CONTAINS"] = "CONTAINS";
+  return MediaRelationType2;
+})(MediaRelationType || {});
+var RecommendationSort = /* @__PURE__ */ ((RecommendationSort2) => {
+  RecommendationSort2["ID"] = "ID";
+  RecommendationSort2["ID_DESC"] = "ID_DESC";
+  RecommendationSort2["RATING"] = "RATING";
+  RecommendationSort2["RATING_DESC"] = "RATING_DESC";
+  return RecommendationSort2;
+})(RecommendationSort || {});
+var MediaListStatus = /* @__PURE__ */ ((MediaListStatus2) => {
+  MediaListStatus2["CURRENT"] = "CURRENT";
+  MediaListStatus2["PLANNING"] = "PLANNING";
+  MediaListStatus2["COMPLETED"] = "COMPLETED";
+  MediaListStatus2["DROPPED"] = "DROPPED";
+  MediaListStatus2["PAUSED"] = "PAUSED";
+  MediaListStatus2["REPEATING"] = "REPEATING";
+  return MediaListStatus2;
+})(MediaListStatus || {});
+var MediaListSort = /* @__PURE__ */ ((MediaListSort2) => {
+  MediaListSort2["MEDIA_ID"] = "MEDIA_ID";
+  MediaListSort2["MEDIA_ID_DESC"] = "MEDIA_ID_DESC";
+  MediaListSort2["SCORE"] = "SCORE";
+  MediaListSort2["SCORE_DESC"] = "SCORE_DESC";
+  MediaListSort2["STATUS"] = "STATUS";
+  MediaListSort2["STATUS_DESC"] = "STATUS_DESC";
+  MediaListSort2["PROGRESS"] = "PROGRESS";
+  MediaListSort2["PROGRESS_DESC"] = "PROGRESS_DESC";
+  MediaListSort2["PROGRESS_VOLUMES"] = "PROGRESS_VOLUMES";
+  MediaListSort2["PROGRESS_VOLUMES_DESC"] = "PROGRESS_VOLUMES_DESC";
+  MediaListSort2["REPEAT"] = "REPEAT";
+  MediaListSort2["REPEAT_DESC"] = "REPEAT_DESC";
+  MediaListSort2["PRIORITY"] = "PRIORITY";
+  MediaListSort2["PRIORITY_DESC"] = "PRIORITY_DESC";
+  MediaListSort2["STARTED_ON"] = "STARTED_ON";
+  MediaListSort2["STARTED_ON_DESC"] = "STARTED_ON_DESC";
+  MediaListSort2["FINISHED_ON"] = "FINISHED_ON";
+  MediaListSort2["FINISHED_ON_DESC"] = "FINISHED_ON_DESC";
+  MediaListSort2["ADDED_TIME"] = "ADDED_TIME";
+  MediaListSort2["ADDED_TIME_DESC"] = "ADDED_TIME_DESC";
+  MediaListSort2["UPDATED_TIME"] = "UPDATED_TIME";
+  MediaListSort2["UPDATED_TIME_DESC"] = "UPDATED_TIME_DESC";
+  MediaListSort2["MEDIA_TITLE_ROMAJI"] = "MEDIA_TITLE_ROMAJI";
+  MediaListSort2["MEDIA_TITLE_ROMAJI_DESC"] = "MEDIA_TITLE_ROMAJI_DESC";
+  MediaListSort2["MEDIA_TITLE_ENGLISH"] = "MEDIA_TITLE_ENGLISH";
+  MediaListSort2["MEDIA_TITLE_ENGLISH_DESC"] = "MEDIA_TITLE_ENGLISH_DESC";
+  MediaListSort2["MEDIA_TITLE_NATIVE"] = "MEDIA_TITLE_NATIVE";
+  MediaListSort2["MEDIA_TITLE_NATIVE_DESC"] = "MEDIA_TITLE_NATIVE_DESC";
+  MediaListSort2["MEDIA_POPULARITY"] = "MEDIA_POPULARITY";
+  MediaListSort2["MEDIA_POPULARITY_DESC"] = "MEDIA_POPULARITY_DESC";
+  return MediaListSort2;
+})(MediaListSort || {});
+
 // src/client/index.ts
 var DEFAULT_API_URL = "https://graphql.anilist.co";
 var AniListClient = class {
@@ -600,16 +913,57 @@ var AniListClient = class {
    */
   async pagedRequest(query, variables, field) {
     const data = await this.request(query, variables);
-    return { pageInfo: data.Page.pageInfo, results: data.Page[field] };
+    const results = data.Page[field];
+    if (!Array.isArray(results)) {
+      throw new AniListError(`Unexpected response: missing field "${field}" in Page`, 0, []);
+    }
+    return { pageInfo: data.Page.pageInfo, results };
+  }
+  /**
+   * @internal
+   * Clamp perPage to AniList's maximum of 50.
+   */
+  clampPerPage(value) {
+    return Math.min(Math.max(value, 1), 50);
   }
   /**
    * Fetch a single media entry by its AniList ID.
    *
+   * Optionally include related data (characters, staff, relations, etc.) via the `include` parameter.
+   *
    * @param id - The AniList media ID
+   * @param include - Optional related data to include
    * @returns The media object
+   *
+   * @example
+   * ```ts
+   * // Basic usage — same as before (includes relations by default)
+   * const anime = await client.getMedia(1);
+   *
+   * // Include characters sorted by role, 25 results
+   * const anime = await client.getMedia(1, { characters: true });
+   *
+   * // Include characters with voice actors
+   * const anime = await client.getMedia(1, { characters: { voiceActors: true } });
+   *
+   * // Full control
+   * const anime = await client.getMedia(1, {
+   *   characters: { perPage: 50, sort: true },
+   *   staff: true,
+   *   relations: true,
+   *   streamingEpisodes: true,
+   *   externalLinks: true,
+   *   stats: true,
+   *   recommendations: { perPage: 5 },
+   * });
+   *
+   * // Exclude relations for a lighter response
+   * const anime = await client.getMedia(1, { characters: true, relations: false });
+   * ```
    */
-  async getMedia(id) {
-    const data = await this.request(QUERY_MEDIA_BY_ID, { id });
+  async getMedia(id, include) {
+    const query = include ? buildMediaByIdQuery(include) : QUERY_MEDIA_BY_ID;
+    const data = await this.request(query, { id });
     return data.Media;
   }
   /**
@@ -629,7 +983,11 @@ var AniListClient = class {
    */
   async searchMedia(options = {}) {
     const { query: search, page = 1, perPage = 20, ...filters } = options;
-    return this.pagedRequest(QUERY_MEDIA_SEARCH, { search, ...filters, page, perPage }, "media");
+    return this.pagedRequest(
+      QUERY_MEDIA_SEARCH,
+      { search, ...filters, page, perPage: this.clampPerPage(perPage) },
+      "media"
+    );
   }
   /**
    * Get currently trending anime or manga.
@@ -638,25 +996,68 @@ var AniListClient = class {
    * @param page - Page number (default 1)
    * @param perPage - Results per page (default 20, max 50)
    */
-  async getTrending(type = "ANIME", page = 1, perPage = 20) {
-    return this.pagedRequest(QUERY_TRENDING, { type, page, perPage }, "media");
+  async getTrending(type = "ANIME" /* ANIME */, page = 1, perPage = 20) {
+    return this.pagedRequest(QUERY_TRENDING, { type, page, perPage: this.clampPerPage(perPage) }, "media");
   }
   /**
    * Fetch a character by AniList ID.
+   *
+   * @param id - The AniList character ID
+   * @param include - Optional include options (e.g. voice actors)
+   * @returns The character object
+   *
+   * @example
+   * ```ts
+   * const spike = await client.getCharacter(1);
+   * console.log(spike.name.full); // "Spike Spiegel"
+   *
+   * // With voice actors
+   * const spike = await client.getCharacter(1, { voiceActors: true });
+   * spike.media?.edges?.forEach((e) => {
+   *   console.log(e.node.title.romaji);
+   *   e.voiceActors?.forEach((va) => console.log(`  VA: ${va.name.full}`));
+   * });
+   * ```
    */
-  async getCharacter(id) {
-    const data = await this.request(QUERY_CHARACTER_BY_ID, { id });
+  async getCharacter(id, include) {
+    const query = include?.voiceActors ? QUERY_CHARACTER_BY_ID_WITH_VA : QUERY_CHARACTER_BY_ID;
+    const data = await this.request(query, { id });
     return data.Character;
   }
   /**
    * Search for characters by name.
+   *
+   * @param options - Search / pagination parameters (includes optional `voiceActors`)
+   * @returns Paginated results with matching characters
+   *
+   * @example
+   * ```ts
+   * const result = await client.searchCharacters({ query: "Luffy", perPage: 5 });
+   *
+   * // With voice actors
+   * const result = await client.searchCharacters({ query: "Luffy", voiceActors: true });
+   * ```
    */
   async searchCharacters(options = {}) {
-    const { query: search, page = 1, perPage = 20, ...rest } = options;
-    return this.pagedRequest(QUERY_CHARACTER_SEARCH, { search, ...rest, page, perPage }, "characters");
+    const { query: search, page = 1, perPage = 20, voiceActors, ...rest } = options;
+    const gqlQuery = voiceActors ? QUERY_CHARACTER_SEARCH_WITH_VA : QUERY_CHARACTER_SEARCH;
+    return this.pagedRequest(
+      gqlQuery,
+      { search, ...rest, page, perPage: this.clampPerPage(perPage) },
+      "characters"
+    );
   }
   /**
    * Fetch a staff member by AniList ID.
+   *
+   * @param id - The AniList staff ID
+   * @returns The staff object
+   *
+   * @example
+   * ```ts
+   * const staff = await client.getStaff(95001);
+   * console.log(staff.name.full);
+   * ```
    */
   async getStaff(id) {
     const data = await this.request(QUERY_STAFF_BY_ID, { id });
@@ -664,13 +1065,34 @@ var AniListClient = class {
   }
   /**
    * Search for staff (voice actors, directors, etc.).
+   *
+   * @param options - Search / pagination parameters
+   * @returns Paginated results with matching staff
+   *
+   * @example
+   * ```ts
+   * const result = await client.searchStaff({ query: "Miyazaki", perPage: 5 });
+   * ```
    */
   async searchStaff(options = {}) {
-    const { query: search, page = 1, perPage = 20 } = options;
-    return this.pagedRequest(QUERY_STAFF_SEARCH, { search, page, perPage }, "staff");
+    const { query: search, page = 1, perPage = 20, sort } = options;
+    return this.pagedRequest(
+      QUERY_STAFF_SEARCH,
+      { search, sort, page, perPage: this.clampPerPage(perPage) },
+      "staff"
+    );
   }
   /**
    * Fetch a user by AniList ID.
+   *
+   * @param id - The AniList user ID
+   * @returns The user object
+   *
+   * @example
+   * ```ts
+   * const user = await client.getUser(1);
+   * console.log(user.name);
+   * ```
    */
   async getUser(id) {
     const data = await this.request(QUERY_USER_BY_ID, { id });
@@ -678,6 +1100,15 @@ var AniListClient = class {
   }
   /**
    * Fetch a user by username.
+   *
+   * @param name - The AniList username
+   * @returns The user object
+   *
+   * @example
+   * ```ts
+   * const user = await client.getUserByName("AniList");
+   * console.log(user.statistics);
+   * ```
    */
   async getUserByName(name) {
     const data = await this.request(QUERY_USER_BY_NAME, { name });
@@ -716,7 +1147,7 @@ var AniListClient = class {
       airingAt_lesser: options.airingAtLesser ?? now,
       sort: options.sort ?? ["TIME_DESC"],
       page: options.page ?? 1,
-      perPage: options.perPage ?? 20
+      perPage: this.clampPerPage(options.perPage ?? 20)
     };
     return this.pagedRequest(QUERY_AIRING_SCHEDULE, variables, "airingSchedules");
   }
@@ -739,7 +1170,7 @@ var AniListClient = class {
       QUERY_RECENT_CHAPTERS,
       {
         page: options.page ?? 1,
-        perPage: options.perPage ?? 20
+        perPage: this.clampPerPage(options.perPage ?? 20)
       },
       "media"
     );
@@ -765,7 +1196,7 @@ var AniListClient = class {
         type: options.type,
         sort: options.sort ?? ["POPULARITY_DESC"],
         page: options.page ?? 1,
-        perPage: options.perPage ?? 20
+        perPage: this.clampPerPage(options.perPage ?? 20)
       },
       "media"
     );
@@ -827,7 +1258,7 @@ var AniListClient = class {
         type: options.type ?? "ANIME",
         sort: options.sort ?? ["POPULARITY_DESC"],
         page: options.page ?? 1,
-        perPage: options.perPage ?? 20
+        perPage: this.clampPerPage(options.perPage ?? 20)
       },
       "media"
     );
@@ -869,7 +1300,7 @@ var AniListClient = class {
         status: options.status,
         sort: options.sort,
         page: options.page ?? 1,
-        perPage: options.perPage ?? 20
+        perPage: this.clampPerPage(options.perPage ?? 20)
       },
       "mediaList"
     );
@@ -902,7 +1333,7 @@ var AniListClient = class {
       {
         search: options.query,
         page: options.page ?? 1,
-        perPage: options.perPage ?? 20
+        perPage: this.clampPerPage(options.perPage ?? 20)
       },
       "studios"
     );
@@ -1003,13 +1434,14 @@ var AniListClient = class {
   /** @internal */
   async executeBatch(ids, buildQuery, prefix) {
     const chunks = this.chunk(ids, 50);
-    const results = [];
-    for (const chunk of chunks) {
-      const query = buildQuery(chunk);
-      const data = await this.request(query);
-      results.push(...chunk.map((_, i) => data[`${prefix}${i}`]));
-    }
-    return results;
+    const chunkResults = await Promise.all(
+      chunks.map(async (chunk) => {
+        const query = buildQuery(chunk);
+        const data = await this.request(query);
+        return chunk.map((_, i) => data[`${prefix}${i}`]);
+      })
+    );
+    return chunkResults.flat();
   }
   /** @internal */
   chunk(arr, size) {
@@ -1082,8 +1514,25 @@ var RedisCache = class {
     const count = await this.client.del(this.prefixedKey(key));
     return count > 0;
   }
+  /**
+   * Collect keys matching a pattern. Uses SCAN when available, falls back to KEYS.
+   *
+   * **Warning:** The `KEYS` fallback is O(N) and blocks the Redis server.
+   * Provide a client with `scanIterator` support for production use.
+   * @internal
+   */
+  async collectKeys(pattern) {
+    if (this.client.scanIterator) {
+      const keys = [];
+      for await (const key of this.client.scanIterator({ MATCH: pattern, COUNT: 100 })) {
+        keys.push(key);
+      }
+      return keys;
+    }
+    return this.client.keys(pattern);
+  }
   async clear() {
-    const keys = await this.client.keys(`${this.prefix}*`);
+    const keys = await this.collectKeys(`${this.prefix}*`);
     if (keys.length > 0) {
       await this.client.del(...keys);
     }
@@ -1101,7 +1550,7 @@ var RedisCache = class {
     return keys.length;
   }
   async keys() {
-    const raw = await this.client.keys(`${this.prefix}*`);
+    const raw = await this.collectKeys(`${this.prefix}*`);
     return raw.map((k) => k.slice(this.prefix.length));
   }
   /**
@@ -1111,153 +1560,22 @@ var RedisCache = class {
    * @returns Number of entries removed.
    */
   async invalidate(pattern) {
-    const keys = await this.client.keys(`${this.prefix}${pattern}`);
-    if (keys.length === 0) return 0;
-    return this.client.del(...keys);
+    if (typeof pattern === "string") {
+      const keys = await this.collectKeys(`${this.prefix}${pattern}`);
+      if (keys.length === 0) return 0;
+      return this.client.del(...keys);
+    }
+    const allKeys = await this.collectKeys(`${this.prefix}*`);
+    const matching = allKeys.filter((k) => pattern.test(k.slice(this.prefix.length)));
+    if (matching.length === 0) return 0;
+    return this.client.del(...matching);
   }
 };
 
-// src/types/index.ts
-var MediaType = /* @__PURE__ */ ((MediaType2) => {
-  MediaType2["ANIME"] = "ANIME";
-  MediaType2["MANGA"] = "MANGA";
-  return MediaType2;
-})(MediaType || {});
-var MediaFormat = /* @__PURE__ */ ((MediaFormat2) => {
-  MediaFormat2["TV"] = "TV";
-  MediaFormat2["TV_SHORT"] = "TV_SHORT";
-  MediaFormat2["MOVIE"] = "MOVIE";
-  MediaFormat2["SPECIAL"] = "SPECIAL";
-  MediaFormat2["OVA"] = "OVA";
-  MediaFormat2["ONA"] = "ONA";
-  MediaFormat2["MUSIC"] = "MUSIC";
-  MediaFormat2["MANGA"] = "MANGA";
-  MediaFormat2["NOVEL"] = "NOVEL";
-  MediaFormat2["ONE_SHOT"] = "ONE_SHOT";
-  return MediaFormat2;
-})(MediaFormat || {});
-var MediaStatus = /* @__PURE__ */ ((MediaStatus2) => {
-  MediaStatus2["FINISHED"] = "FINISHED";
-  MediaStatus2["RELEASING"] = "RELEASING";
-  MediaStatus2["NOT_YET_RELEASED"] = "NOT_YET_RELEASED";
-  MediaStatus2["CANCELLED"] = "CANCELLED";
-  MediaStatus2["HIATUS"] = "HIATUS";
-  return MediaStatus2;
-})(MediaStatus || {});
-var MediaSeason = /* @__PURE__ */ ((MediaSeason2) => {
-  MediaSeason2["WINTER"] = "WINTER";
-  MediaSeason2["SPRING"] = "SPRING";
-  MediaSeason2["SUMMER"] = "SUMMER";
-  MediaSeason2["FALL"] = "FALL";
-  return MediaSeason2;
-})(MediaSeason || {});
-var MediaSort = /* @__PURE__ */ ((MediaSort2) => {
-  MediaSort2["ID"] = "ID";
-  MediaSort2["TITLE_ROMAJI"] = "TITLE_ROMAJI";
-  MediaSort2["TITLE_ENGLISH"] = "TITLE_ENGLISH";
-  MediaSort2["TITLE_NATIVE"] = "TITLE_NATIVE";
-  MediaSort2["TYPE"] = "TYPE";
-  MediaSort2["FORMAT"] = "FORMAT";
-  MediaSort2["START_DATE"] = "START_DATE";
-  MediaSort2["END_DATE"] = "END_DATE";
-  MediaSort2["SCORE"] = "SCORE";
-  MediaSort2["POPULARITY"] = "POPULARITY";
-  MediaSort2["TRENDING"] = "TRENDING";
-  MediaSort2["EPISODES"] = "EPISODES";
-  MediaSort2["DURATION"] = "DURATION";
-  MediaSort2["STATUS"] = "STATUS";
-  MediaSort2["FAVOURITES"] = "FAVOURITES";
-  MediaSort2["UPDATED_AT"] = "UPDATED_AT";
-  MediaSort2["SEARCH_MATCH"] = "SEARCH_MATCH";
-  return MediaSort2;
-})(MediaSort || {});
-var AiringSort = /* @__PURE__ */ ((AiringSort2) => {
-  AiringSort2["ID"] = "ID";
-  AiringSort2["ID_DESC"] = "ID_DESC";
-  AiringSort2["MEDIA_ID"] = "MEDIA_ID";
-  AiringSort2["MEDIA_ID_DESC"] = "MEDIA_ID_DESC";
-  AiringSort2["TIME"] = "TIME";
-  AiringSort2["TIME_DESC"] = "TIME_DESC";
-  AiringSort2["EPISODE"] = "EPISODE";
-  AiringSort2["EPISODE_DESC"] = "EPISODE_DESC";
-  return AiringSort2;
-})(AiringSort || {});
-var CharacterSort = /* @__PURE__ */ ((CharacterSort2) => {
-  CharacterSort2["ID"] = "ID";
-  CharacterSort2["ROLE"] = "ROLE";
-  CharacterSort2["SEARCH_MATCH"] = "SEARCH_MATCH";
-  CharacterSort2["FAVOURITES"] = "FAVOURITES";
-  return CharacterSort2;
-})(CharacterSort || {});
-var MediaRelationType = /* @__PURE__ */ ((MediaRelationType2) => {
-  MediaRelationType2["ADAPTATION"] = "ADAPTATION";
-  MediaRelationType2["PREQUEL"] = "PREQUEL";
-  MediaRelationType2["SEQUEL"] = "SEQUEL";
-  MediaRelationType2["PARENT"] = "PARENT";
-  MediaRelationType2["SIDE_STORY"] = "SIDE_STORY";
-  MediaRelationType2["CHARACTER"] = "CHARACTER";
-  MediaRelationType2["SUMMARY"] = "SUMMARY";
-  MediaRelationType2["ALTERNATIVE"] = "ALTERNATIVE";
-  MediaRelationType2["SPIN_OFF"] = "SPIN_OFF";
-  MediaRelationType2["OTHER"] = "OTHER";
-  MediaRelationType2["SOURCE"] = "SOURCE";
-  MediaRelationType2["COMPILATION"] = "COMPILATION";
-  MediaRelationType2["CONTAINS"] = "CONTAINS";
-  return MediaRelationType2;
-})(MediaRelationType || {});
-var RecommendationSort = /* @__PURE__ */ ((RecommendationSort2) => {
-  RecommendationSort2["ID"] = "ID";
-  RecommendationSort2["ID_DESC"] = "ID_DESC";
-  RecommendationSort2["RATING"] = "RATING";
-  RecommendationSort2["RATING_DESC"] = "RATING_DESC";
-  return RecommendationSort2;
-})(RecommendationSort || {});
-var MediaListStatus = /* @__PURE__ */ ((MediaListStatus2) => {
-  MediaListStatus2["CURRENT"] = "CURRENT";
-  MediaListStatus2["PLANNING"] = "PLANNING";
-  MediaListStatus2["COMPLETED"] = "COMPLETED";
-  MediaListStatus2["DROPPED"] = "DROPPED";
-  MediaListStatus2["PAUSED"] = "PAUSED";
-  MediaListStatus2["REPEATING"] = "REPEATING";
-  return MediaListStatus2;
-})(MediaListStatus || {});
-var MediaListSort = /* @__PURE__ */ ((MediaListSort2) => {
-  MediaListSort2["MEDIA_ID"] = "MEDIA_ID";
-  MediaListSort2["MEDIA_ID_DESC"] = "MEDIA_ID_DESC";
-  MediaListSort2["SCORE"] = "SCORE";
-  MediaListSort2["SCORE_DESC"] = "SCORE_DESC";
-  MediaListSort2["STATUS"] = "STATUS";
-  MediaListSort2["STATUS_DESC"] = "STATUS_DESC";
-  MediaListSort2["PROGRESS"] = "PROGRESS";
-  MediaListSort2["PROGRESS_DESC"] = "PROGRESS_DESC";
-  MediaListSort2["PROGRESS_VOLUMES"] = "PROGRESS_VOLUMES";
-  MediaListSort2["PROGRESS_VOLUMES_DESC"] = "PROGRESS_VOLUMES_DESC";
-  MediaListSort2["REPEAT"] = "REPEAT";
-  MediaListSort2["REPEAT_DESC"] = "REPEAT_DESC";
-  MediaListSort2["PRIORITY"] = "PRIORITY";
-  MediaListSort2["PRIORITY_DESC"] = "PRIORITY_DESC";
-  MediaListSort2["STARTED_ON"] = "STARTED_ON";
-  MediaListSort2["STARTED_ON_DESC"] = "STARTED_ON_DESC";
-  MediaListSort2["FINISHED_ON"] = "FINISHED_ON";
-  MediaListSort2["FINISHED_ON_DESC"] = "FINISHED_ON_DESC";
-  MediaListSort2["ADDED_TIME"] = "ADDED_TIME";
-  MediaListSort2["ADDED_TIME_DESC"] = "ADDED_TIME_DESC";
-  MediaListSort2["UPDATED_TIME"] = "UPDATED_TIME";
-  MediaListSort2["UPDATED_TIME_DESC"] = "UPDATED_TIME_DESC";
-  MediaListSort2["MEDIA_TITLE_ROMAJI"] = "MEDIA_TITLE_ROMAJI";
-  MediaListSort2["MEDIA_TITLE_ROMAJI_DESC"] = "MEDIA_TITLE_ROMAJI_DESC";
-  MediaListSort2["MEDIA_TITLE_ENGLISH"] = "MEDIA_TITLE_ENGLISH";
-  MediaListSort2["MEDIA_TITLE_ENGLISH_DESC"] = "MEDIA_TITLE_ENGLISH_DESC";
-  MediaListSort2["MEDIA_TITLE_NATIVE"] = "MEDIA_TITLE_NATIVE";
-  MediaListSort2["MEDIA_TITLE_NATIVE_DESC"] = "MEDIA_TITLE_NATIVE_DESC";
-  MediaListSort2["MEDIA_POPULARITY"] = "MEDIA_POPULARITY";
-  MediaListSort2["MEDIA_POPULARITY_DESC"] = "MEDIA_POPULARITY_DESC";
-  return MediaListSort2;
-})(MediaListSort || {});
-
 exports.AiringSort = AiringSort;
 exports.AniListClient = AniListClient;
 exports.AniListError = AniListError;
+exports.CharacterRole = CharacterRole;
 exports.CharacterSort = CharacterSort;
 exports.MediaFormat = MediaFormat;
 exports.MediaListSort = MediaListSort;