ani-client 1.5.0 → 1.6.0

package/dist/index.mjs

@@ -1,4 +1,157 @@
-// src/queries/index.ts
+// src/utils/markdown.ts
+function parseAniListMarkdown(text) {
+  if (!text) return "";
+  let html = text;
+  html = html.replace(/~!(.*?)!~/gs, '<span class="anilist-spoiler">$1</span>');
+  html = html.replace(/~~~(.*?)~~~/gs, '<div class="anilist-center">$1</div>');
+  html = html.replace(/img(\d+)\((.*?)\)/gi, '<img src="$2" width="$1" alt="" class="anilist-image" />');
+  html = html.replace(/img\((.*?)\)/gi, '<img src="$1" alt="" class="anilist-image" />');
+  html = html.replace(
+    /youtube\((.*?)\)/gi,
+    '<iframe src="https://www.youtube.com/embed/$1" frameborder="0" allowfullscreen class="anilist-youtube"></iframe>'
+  );
+  html = html.replace(/webm\((.*?)\)/gi, '<video src="$1" controls class="anilist-webm"></video>');
+  html = html.replace(/__(.*?)__/g, "<strong>$1</strong>");
+  html = html.replace(/\*\*(.*?)\*\*/g, "<strong>$1</strong>");
+  html = html.replace(/_(.*?)_/g, "<em>$1</em>");
+  html = html.replace(/(?<!\*)\*(?!\*)(.*?)(?<!\*)\*(?!\*)/g, "<em>$1</em>");
+  html = html.replace(/~~(.*?)~~/g, "<del>$1</del>");
+  html = html.replace(/\[(.*?)\]\((.*?)\)/g, '<a href="$2" target="_blank" rel="noopener noreferrer">$1</a>');
+  html = html.replace(/\r\n/g, "\n");
+  const paragraphs = html.split(/\n{2,}/);
+  html = paragraphs.map((p) => {
+    const withBr = p.replace(/\n/g, "<br />");
+    if (withBr.match(/^(<div|<iframe|<video|<img)/)) {
+      return withBr;
+    }
+    return `<p>${withBr}</p>`;
+  }).join("\n");
+  return html;
+}
+
+// src/utils/index.ts
+var WHITESPACE_RE = /\s+/g;
+function normalizeQuery(query) {
+  return query.replace(WHITESPACE_RE, " ").trim();
+}
+function clampPerPage(value) {
+  return Math.min(Math.max(value, 1), 50);
+}
+function chunk(arr, size) {
+  const chunks = [];
+  for (let i = 0; i < arr.length; i += size) {
+    chunks.push(arr.slice(i, i + size));
+  }
+  return chunks;
+}
+function validateId(id, label = "id") {
+  if (!Number.isFinite(id) || !Number.isInteger(id) || id < 1) {
+    throw new RangeError(`Invalid ${label}: expected a positive integer, got ${id}`);
+  }
+}
+function validateIds(ids, label = "id") {
+  for (const id of ids) {
+    validateId(id, label);
+  }
+}
+function sortObjectKeys(obj) {
+  if (obj === null || typeof obj !== "object") return obj;
+  if (Array.isArray(obj)) return obj.map(sortObjectKeys);
+  const sorted = {};
+  for (const key of Object.keys(obj).sort()) {
+    sorted[key] = sortObjectKeys(obj[key]);
+  }
+  return sorted;
+}
+
+// src/cache/index.ts
+var ONE_DAY_MS = 24 * 60 * 60 * 1e3;
+var MemoryCache = class {
+  constructor(options = {}) {
+    this.store = /* @__PURE__ */ new Map();
+    this.ttl = options.ttl ?? ONE_DAY_MS;
+    this.maxSize = options.maxSize ?? 500;
+    this.enabled = options.enabled ?? true;
+  }
+  /** Build a deterministic cache key from a query + variables pair. */
+  static key(query, variables) {
+    const normalized = normalizeQuery(query);
+    return `${normalized}|${JSON.stringify(sortObjectKeys(variables))}`;
+  }
+  /** Retrieve a cached value, or `undefined` if missing / expired. */
+  get(key) {
+    if (!this.enabled) return void 0;
+    const entry = this.store.get(key);
+    if (!entry) return void 0;
+    if (Date.now() > entry.expiresAt) {
+      this.store.delete(key);
+      return void 0;
+    }
+    this.store.delete(key);
+    this.store.set(key, entry);
+    return entry.data;
+  }
+  /** Store a value in the cache. */
+  set(key, data) {
+    if (!this.enabled) return;
+    this.store.delete(key);
+    if (this.maxSize > 0 && this.store.size >= this.maxSize) {
+      const firstKey = this.store.keys().next().value;
+      if (firstKey !== void 0) this.store.delete(firstKey);
+    }
+    this.store.set(key, { data, expiresAt: Date.now() + this.ttl });
+  }
+  /** Remove a specific entry. */
+  delete(key) {
+    return this.store.delete(key);
+  }
+  /** Clear the entire cache. */
+  clear() {
+    this.store.clear();
+  }
+  /** Number of entries currently stored. */
+  get size() {
+    return this.store.size;
+  }
+  /** Return all cache keys. */
+  keys() {
+    return [...this.store.keys()];
+  }
+  /**
+   * Remove all entries whose key matches the given pattern.
+   *
+   * - **String**: treated as a substring match (e.g. `"Media"` removes all keys containing `"Media"`).
+   * - **RegExp**: tested against each key directly.
+   *
+   * @param pattern — A string (substring match) or RegExp.
+   * @returns Number of entries removed.
+   */
+  invalidate(pattern) {
+    const test = typeof pattern === "string" ? (key) => key.includes(pattern) : (key) => pattern.test(key);
+    const toDelete = [];
+    for (const key of this.store.keys()) {
+      if (test(key)) toDelete.push(key);
+    }
+    for (const key of toDelete) this.store.delete(key);
+    return toDelete.length;
+  }
+};
+
+// src/errors/index.ts
+var AniListError = class _AniListError extends Error {
+  constructor(message, status, errors = []) {
+    super(message);
+    this.name = "AniListError";
+    this.status = status;
+    this.errors = errors;
+    Object.setPrototypeOf(this, _AniListError.prototype);
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _AniListError);
+    }
+  }
+};
+
+// src/queries/fragments.ts
 var MEDIA_FIELDS_BASE = `
   id
   idMal
@@ -191,6 +344,92 @@ var USER_FIELDS = `
     manga { count meanScore minutesWatched episodesWatched chaptersRead volumesRead }
   }
 `;
+var USER_FAVORITES_FIELDS = `
+  favourites {
+    anime(perPage: 25) {
+      nodes {
+        id
+        title { romaji english native userPreferred }
+        coverImage { large medium }
+        type
+        format
+        siteUrl
+      }
+    }
+    manga(perPage: 25) {
+      nodes {
+        id
+        title { romaji english native userPreferred }
+        coverImage { large medium }
+        type
+        format
+        siteUrl
+      }
+    }
+    characters(perPage: 25) {
+      nodes {
+        id
+        name { full native }
+        image { large medium }
+        siteUrl
+      }
+    }
+    staff(perPage: 25) {
+      nodes {
+        id
+        name { full native }
+        image { large medium }
+        siteUrl
+      }
+    }
+    studios(perPage: 25) {
+      nodes {
+        id
+        name
+        siteUrl
+      }
+    }
+  }
+`;
+var MEDIA_LIST_FIELDS = `
+  id
+  mediaId
+  status
+  score(format: POINT_100)
+  progress
+  progressVolumes
+  repeat
+  priority
+  private
+  notes
+  startedAt { year month day }
+  completedAt { year month day }
+  updatedAt
+  createdAt
+  media {
+    ${MEDIA_FIELDS_BASE}
+  }
+`;
+var STUDIO_FIELDS = `
+  id
+  name
+  isAnimationStudio
+  siteUrl
+  favourites
+  media(page: 1, perPage: 25, sort: POPULARITY_DESC) {
+    pageInfo { total perPage currentPage lastPage hasNextPage }
+    nodes {
+      id
+      title { romaji english native userPreferred }
+      type
+      format
+      coverImage { large medium }
+      siteUrl
+    }
+  }
+`;
+
+// src/queries/media.ts
 var QUERY_MEDIA_BY_ID = `
 query ($id: Int!) {
   Media(id: $id) {
@@ -247,79 +486,6 @@ query ($type: MediaType, $page: Int, $perPage: Int) {
     }
   }
 }`;
-var QUERY_CHARACTER_BY_ID = `
-query ($id: Int!) {
-  Character(id: $id) {
-    ${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) {
-    pageInfo { total perPage currentPage lastPage hasNextPage }
-    characters(search: $search, sort: $sort) {
-      ${CHARACTER_FIELDS}
-    }
-  }
-}`;
-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) {
-    ${STAFF_FIELDS}
-  }
-}`;
-var QUERY_STAFF_BY_ID_WITH_MEDIA = `
-query ($id: Int!, $perPage: Int) {
-  Staff(id: $id) {
-    ${STAFF_FIELDS}
-    ${STAFF_MEDIA_FIELDS}
-  }
-}`;
-var QUERY_STAFF_SEARCH = `
-query ($search: String, $sort: [StaffSort], $page: Int, $perPage: Int) {
-  Page(page: $page, perPage: $perPage) {
-    pageInfo { total perPage currentPage lastPage hasNextPage }
-    staff(search: $search, sort: $sort) {
-      ${STAFF_FIELDS}
-    }
-  }
-}`;
-var QUERY_USER_BY_ID = `
-query ($id: Int!) {
-  User(id: $id) {
-    ${USER_FIELDS}
-  }
-}`;
-var QUERY_USER_BY_NAME = `
-query ($name: String!) {
-  User(name: $name) {
-    ${USER_FIELDS}
-  }
-}`;
-var QUERY_USER_SEARCH = `
-query ($search: String, $sort: [UserSort], $page: Int, $perPage: Int) {
-  Page(page: $page, perPage: $perPage) {
-    pageInfo { total perPage currentPage lastPage hasNextPage }
-    users(search: $search, sort: $sort) {
-      ${USER_FIELDS}
-    }
-  }
-}`;
 var QUERY_AIRING_SCHEDULE = `
 query ($airingAt_greater: Int, $airingAt_lesser: Int, $sort: [AiringSort], $page: Int, $perPage: Int) {
   Page(page: $page, perPage: $perPage) {
@@ -363,25 +529,6 @@ query ($season: MediaSeason!, $seasonYear: Int!, $type: MediaType, $sort: [Media
     }
   }
 }`;
-var MEDIA_LIST_FIELDS = `
-  id
-  mediaId
-  status
-  score(format: POINT_100)
-  progress
-  progressVolumes
-  repeat
-  priority
-  private
-  notes
-  startedAt { year month day }
-  completedAt { year month day }
-  updatedAt
-  createdAt
-  media {
-    ${MEDIA_FIELDS_BASE}
-  }
-`;
 var QUERY_RECOMMENDATIONS = `
 query ($mediaId: Int!, $page: Int, $perPage: Int, $sort: [RecommendationSort]) {
   Media(id: $mediaId) {
@@ -416,6 +563,85 @@ query ($mediaId: Int!, $page: Int, $perPage: Int, $sort: [RecommendationSort]) {
     }
   }
 }`;
+
+// src/queries/character.ts
+var QUERY_CHARACTER_BY_ID = `
+query ($id: Int!) {
+  Character(id: $id) {
+    ${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) {
+    pageInfo { total perPage currentPage lastPage hasNextPage }
+    characters(search: $search, sort: $sort) {
+      ${CHARACTER_FIELDS}
+    }
+  }
+}`;
+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}
+    }
+  }
+}`;
+
+// src/queries/staff.ts
+var QUERY_STAFF_BY_ID = `
+query ($id: Int!) {
+  Staff(id: $id) {
+    ${STAFF_FIELDS}
+  }
+}`;
+var QUERY_STAFF_BY_ID_WITH_MEDIA = `
+query ($id: Int!, $perPage: Int) {
+  Staff(id: $id) {
+    ${STAFF_FIELDS}
+    ${STAFF_MEDIA_FIELDS}
+  }
+}`;
+var QUERY_STAFF_SEARCH = `
+query ($search: String, $sort: [StaffSort], $page: Int, $perPage: Int) {
+  Page(page: $page, perPage: $perPage) {
+    pageInfo { total perPage currentPage lastPage hasNextPage }
+    staff(search: $search, sort: $sort) {
+      ${STAFF_FIELDS}
+    }
+  }
+}`;
+
+// src/queries/user.ts
+var QUERY_USER_BY_ID = `
+query ($id: Int!) {
+  User(id: $id) {
+    ${USER_FIELDS}
+  }
+}`;
+var QUERY_USER_BY_NAME = `
+query ($name: String!) {
+  User(name: $name) {
+    ${USER_FIELDS}
+  }
+}`;
+var QUERY_USER_SEARCH = `
+query ($search: String, $sort: [UserSort], $page: Int, $perPage: Int) {
+  Page(page: $page, perPage: $perPage) {
+    pageInfo { total perPage currentPage lastPage hasNextPage }
+    users(search: $search, sort: $sort) {
+      ${USER_FIELDS}
+    }
+  }
+}`;
 var QUERY_USER_MEDIA_LIST = `
 query ($userId: Int, $userName: String, $type: MediaType!, $status: MediaListStatus, $sort: [MediaListSort], $page: Int, $perPage: Int) {
   Page(page: $page, perPage: $perPage) {
@@ -425,24 +651,24 @@ query ($userId: Int, $userName: String, $type: MediaType!, $status: MediaListSta
     }
   }
 }`;
-var STUDIO_FIELDS = `
-  id
-  name
-  isAnimationStudio
-  siteUrl
-  favourites
-  media(page: 1, perPage: 25, sort: POPULARITY_DESC) {
-    pageInfo { total perPage currentPage lastPage hasNextPage }
-    nodes {
-      id
-      title { romaji english native userPreferred }
-      type
-      format
-      coverImage { large medium }
-      siteUrl
-    }
+var QUERY_USER_FAVORITES_BY_ID = `
+query ($id: Int!) {
+  User(id: $id) {
+    id
+    name
+    ${USER_FAVORITES_FIELDS}
   }
-`;
+}`;
+var QUERY_USER_FAVORITES_BY_NAME = `
+query ($name: String!) {
+  User(name: $name) {
+    id
+    name
+    ${USER_FAVORITES_FIELDS}
+  }
+}`;
+
+// src/queries/studio.ts
 var QUERY_STUDIO_BY_ID = `
 query ($id: Int!) {
   Studio(id: $id) {
@@ -458,6 +684,8 @@ query ($search: String, $page: Int, $perPage: Int) {
     }
   }
 }`;
+
+// src/queries/metadata.ts
 var QUERY_GENRES = `
 query {
   GenreCollection
@@ -472,6 +700,8 @@ query {
     isAdult
   }
 }`;
+
+// src/queries/builders.ts
 function buildMediaByIdQuery(include) {
   if (!include) return QUERY_MEDIA_BY_ID;
   const extra = [];
@@ -574,107 +804,64 @@ var buildBatchMediaQuery = (ids) => buildBatchQuery(ids, "Media", MEDIA_FIELDS_B
 var buildBatchCharacterQuery = (ids) => buildBatchQuery(ids, "Character", CHARACTER_FIELDS, "c");
 var buildBatchStaffQuery = (ids) => buildBatchQuery(ids, "Staff", STAFF_FIELDS, "s");
 
-// src/utils/index.ts
-function normalizeQuery(query) {
-  return query.replace(/\s+/g, " ").trim();
-}
-function clampPerPage(value) {
-  return Math.min(Math.max(value, 1), 50);
-}
-function chunk(arr, size) {
-  const chunks = [];
-  for (let i = 0; i < arr.length; i += size) {
-    chunks.push(arr.slice(i, i + size));
-  }
-  return chunks;
-}
-
-// src/cache/index.ts
-var ONE_DAY_MS = 24 * 60 * 60 * 1e3;
-var MemoryCache = class {
-  constructor(options = {}) {
-    this.store = /* @__PURE__ */ new Map();
-    this.ttl = options.ttl ?? ONE_DAY_MS;
-    this.maxSize = options.maxSize ?? 500;
-    this.enabled = options.enabled ?? true;
-  }
-  /** Build a deterministic cache key from a query + variables pair. */
-  static key(query, variables) {
-    const normalized = normalizeQuery(query);
-    return `${normalized}|${JSON.stringify(variables, Object.keys(variables).sort())}`;
-  }
-  /** Retrieve a cached value, or `undefined` if missing / expired. */
-  get(key) {
-    if (!this.enabled) return void 0;
-    const entry = this.store.get(key);
-    if (!entry) return void 0;
-    if (Date.now() > entry.expiresAt) {
-      this.store.delete(key);
-      return void 0;
-    }
-    this.store.delete(key);
-    this.store.set(key, entry);
-    return entry.data;
-  }
-  /** Store a value in the cache. */
-  set(key, data) {
-    if (!this.enabled) return;
-    this.store.delete(key);
-    if (this.maxSize > 0 && this.store.size >= this.maxSize) {
-      const firstKey = this.store.keys().next().value;
-      if (firstKey !== void 0) this.store.delete(firstKey);
-    }
-    this.store.set(key, { data, expiresAt: Date.now() + this.ttl });
+// src/queries/thread.ts
+var THREAD_FIELDS = `
+  id
+  title
+  body(asHtml: false)
+  userId
+  replyUserId
+  replyCommentId
+  replyCount
+  viewCount
+  isLocked
+  isSticky
+  isSubscribed
+  repliedAt
+  createdAt
+  updatedAt
+  siteUrl
+  user {
+    id
+    name
+    avatar { large medium }
   }
-  /** Remove a specific entry. */
-  delete(key) {
-    return this.store.delete(key);
+  replyUser {
+    id
+    name
+    avatar { large medium }
   }
-  /** Clear the entire cache. */
-  clear() {
-    this.store.clear();
+  categories {
+    id
+    name
   }
-  /** Number of entries currently stored. */
-  get size() {
-    return this.store.size;
+  mediaCategories {
+    id
+    title { romaji english native userPreferred }
+    type
+    coverImage { large medium }
+    siteUrl
   }
-  /** Return all cache keys. */
-  keys() {
-    return [...this.store.keys()];
+  likes {
+    id
+    name
   }
-  /**
-   * Remove all entries whose key matches the given pattern.
-   *
-   * - **String**: treated as a substring match (e.g. `"Media"` removes all keys containing `"Media"`).
-   * - **RegExp**: tested against each key directly.
-   *
-   * @param pattern — A string (substring match) or RegExp.
-   * @returns Number of entries removed.
-   */
-  invalidate(pattern) {
-    const test = typeof pattern === "string" ? (key) => key.includes(pattern) : (key) => pattern.test(key);
-    const toDelete = [];
-    for (const key of this.store.keys()) {
-      if (test(key)) toDelete.push(key);
-    }
-    for (const key of toDelete) this.store.delete(key);
-    return toDelete.length;
+`;
+var QUERY_THREAD_BY_ID = `
+query ($id: Int!) {
+  Thread(id: $id) {
+    ${THREAD_FIELDS}
   }
-};
-
-// src/errors/index.ts
-var AniListError = class _AniListError extends Error {
-  constructor(message, status, errors = []) {
-    super(message);
-    this.name = "AniListError";
-    this.status = status;
-    this.errors = errors;
-    Object.setPrototypeOf(this, _AniListError.prototype);
-    if (Error.captureStackTrace) {
-      Error.captureStackTrace(this, _AniListError);
+}`;
+var QUERY_THREAD_SEARCH = `
+query ($search: String, $mediaCategoryId: Int, $categoryId: Int, $sort: [ThreadSort], $page: Int, $perPage: Int) {
+  Page(page: $page, perPage: $perPage) {
+    pageInfo { total perPage currentPage lastPage hasNextPage }
+    threads(search: $search, mediaCategoryId: $mediaCategoryId, categoryId: $categoryId, sort: $sort) {
+      ${THREAD_FIELDS}
     }
   }
-};
+}`;
 
 // src/rate-limiter/index.ts
 var RateLimiter = class {
@@ -688,6 +875,7 @@ var RateLimiter = class {
     this.enabled = options.enabled ?? true;
     this.timeoutMs = options.timeoutMs ?? 3e4;
     this.retryOnNetworkError = options.retryOnNetworkError ?? true;
+    this.retryStrategy = options.retryStrategy;
     this.timestamps = new Array(this.maxRequests).fill(0);
   }
   /**
@@ -748,8 +936,11 @@ var RateLimiter = class {
     if (lastResponse) return lastResponse;
     throw lastError;
   }
-  /** @internal — Exponential backoff with jitter, capped at 30s */
+  /** @internal — Exponential backoff with jitter, capped at 30s (or custom strategy) */
   exponentialDelay(attempt) {
+    if (this.retryStrategy) {
+      return this.retryStrategy(attempt, this.retryDelayMs);
+    }
     const base = this.retryDelayMs * 2 ** attempt;
     const jitter = Math.random() * 1e3;
     return Math.min(base + jitter, 3e4);
@@ -787,6 +978,19 @@ function isNetworkError(err) {
   return false;
 }
 
+// src/client/character.ts
+async function getCharacter(client, id, include) {
+  validateId(id, "characterId");
+  const query = include?.voiceActors ? QUERY_CHARACTER_BY_ID_WITH_VA : QUERY_CHARACTER_BY_ID;
+  const data = await client.request(query, { id });
+  return data.Character;
+}
+async function searchCharacters(client, options = {}) {
+  const { query: search, page = 1, perPage = 20, sort, voiceActors } = options;
+  const gqlQuery = voiceActors ? QUERY_CHARACTER_SEARCH_WITH_VA : QUERY_CHARACTER_SEARCH;
+  return client.pagedRequest(gqlQuery, { search, sort, page, perPage: clampPerPage(perPage) }, "characters");
+}
+
 // src/types/media.ts
 var MediaType = /* @__PURE__ */ ((MediaType2) => {
   MediaType2["ANIME"] = "ANIME";
@@ -1001,6 +1205,274 @@ var MediaListSort = /* @__PURE__ */ ((MediaListSort2) => {
   return MediaListSort2;
 })(MediaListSort || {});
 
+// src/types/thread.ts
+var ThreadSort = /* @__PURE__ */ ((ThreadSort2) => {
+  ThreadSort2["ID"] = "ID";
+  ThreadSort2["ID_DESC"] = "ID_DESC";
+  ThreadSort2["TITLE"] = "TITLE";
+  ThreadSort2["TITLE_DESC"] = "TITLE_DESC";
+  ThreadSort2["CREATED_AT"] = "CREATED_AT";
+  ThreadSort2["CREATED_AT_DESC"] = "CREATED_AT_DESC";
+  ThreadSort2["UPDATED_AT"] = "UPDATED_AT";
+  ThreadSort2["UPDATED_AT_DESC"] = "UPDATED_AT_DESC";
+  ThreadSort2["REPLIED_AT"] = "REPLIED_AT";
+  ThreadSort2["REPLIED_AT_DESC"] = "REPLIED_AT_DESC";
+  ThreadSort2["REPLY_COUNT"] = "REPLY_COUNT";
+  ThreadSort2["REPLY_COUNT_DESC"] = "REPLY_COUNT_DESC";
+  ThreadSort2["VIEW_COUNT"] = "VIEW_COUNT";
+  ThreadSort2["VIEW_COUNT_DESC"] = "VIEW_COUNT_DESC";
+  ThreadSort2["IS_STICKY"] = "IS_STICKY";
+  ThreadSort2["SEARCH_MATCH"] = "SEARCH_MATCH";
+  return ThreadSort2;
+})(ThreadSort || {});
+
+// src/client/media.ts
+async function getMedia(client, id, include) {
+  validateId(id, "mediaId");
+  const query = buildMediaByIdQuery(include);
+  const data = await client.request(query, { id });
+  return data.Media;
+}
+async function searchMedia(client, options = {}) {
+  const { query: search, page = 1, perPage = 20, genres, tags, genresExclude, tagsExclude, ...filters } = options;
+  return client.pagedRequest(
+    QUERY_MEDIA_SEARCH,
+    {
+      search,
+      ...filters,
+      genre_in: genres,
+      tag_in: tags,
+      genre_not_in: genresExclude,
+      tag_not_in: tagsExclude,
+      page,
+      perPage: clampPerPage(perPage)
+    },
+    "media"
+  );
+}
+async function getTrending(client, type = "ANIME" /* ANIME */, page = 1, perPage = 20) {
+  return client.pagedRequest(QUERY_TRENDING, { type, page, perPage: clampPerPage(perPage) }, "media");
+}
+async function getPopular(client, type = "ANIME" /* ANIME */, page = 1, perPage = 20) {
+  return searchMedia(client, { type, sort: ["POPULARITY_DESC" /* POPULARITY_DESC */], page, perPage });
+}
+async function getTopRated(client, type = "ANIME" /* ANIME */, page = 1, perPage = 20) {
+  return searchMedia(client, { type, sort: ["SCORE_DESC" /* SCORE_DESC */], page, perPage });
+}
+async function getAiredEpisodes(client, options = {}) {
+  const now = Math.floor(Date.now() / 1e3);
+  return client.pagedRequest(
+    QUERY_AIRING_SCHEDULE,
+    {
+      airingAt_greater: options.airingAtGreater ?? now - 24 * 3600,
+      airingAt_lesser: options.airingAtLesser ?? now,
+      sort: options.sort,
+      page: options.page ?? 1,
+      perPage: clampPerPage(options.perPage ?? 20)
+    },
+    "airingSchedules"
+  );
+}
+async function getAiredChapters(client, options = {}) {
+  return client.pagedRequest(
+    QUERY_RECENT_CHAPTERS,
+    {
+      page: options.page ?? 1,
+      perPage: clampPerPage(options.perPage ?? 20)
+    },
+    "media"
+  );
+}
+async function getPlanning(client, options = {}) {
+  return client.pagedRequest(
+    QUERY_PLANNING,
+    {
+      type: options.type,
+      sort: options.sort ?? ["POPULARITY_DESC" /* POPULARITY_DESC */],
+      page: options.page ?? 1,
+      perPage: clampPerPage(options.perPage ?? 20)
+    },
+    "media"
+  );
+}
+async function getRecommendations(client, mediaId, options = {}) {
+  const data = await client.request(QUERY_RECOMMENDATIONS, {
+    mediaId,
+    page: options.page ?? 1,
+    perPage: clampPerPage(options.perPage ?? 20),
+    sort: options.sort
+  });
+  return {
+    pageInfo: data.Media.recommendations.pageInfo,
+    results: data.Media.recommendations.nodes
+  };
+}
+async function getMediaBySeason(client, options) {
+  return client.pagedRequest(
+    QUERY_MEDIA_BY_SEASON,
+    {
+      season: options.season,
+      seasonYear: options.seasonYear,
+      type: options.type,
+      sort: options.sort,
+      page: options.page ?? 1,
+      perPage: clampPerPage(options.perPage ?? 20)
+    },
+    "media"
+  );
+}
+async function getWeeklySchedule(client, date = /* @__PURE__ */ new Date()) {
+  const schedule = {
+    Monday: [],
+    Tuesday: [],
+    Wednesday: [],
+    Thursday: [],
+    Friday: [],
+    Saturday: [],
+    Sunday: []
+  };
+  const startOfWeek = new Date(date);
+  const day = startOfWeek.getDay();
+  const diff = startOfWeek.getDate() - day + (day === 0 ? -6 : 1);
+  startOfWeek.setDate(diff);
+  startOfWeek.setHours(0, 0, 0, 0);
+  const endOfWeek = new Date(startOfWeek);
+  endOfWeek.setDate(startOfWeek.getDate() + 6);
+  endOfWeek.setHours(23, 59, 59, 999);
+  const startTimestamp = Math.floor(startOfWeek.getTime() / 1e3);
+  const endTimestamp = Math.floor(endOfWeek.getTime() / 1e3);
+  const iterator = client.paginate(
+    (page) => getAiredEpisodes(client, {
+      airingAtGreater: startTimestamp,
+      airingAtLesser: endTimestamp,
+      page,
+      perPage: 50
+    })
+  );
+  const names = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
+  for await (const episode of iterator) {
+    const epDate = new Date(episode.airingAt * 1e3);
+    const dayName = names[epDate.getDay()];
+    schedule[dayName].push(episode);
+  }
+  return schedule;
+}
+
+// src/client/staff.ts
+async function getStaff(client, id, include) {
+  validateId(id, "staffId");
+  if (include?.media) {
+    const perPage = typeof include.media === "object" ? include.media.perPage ?? 25 : 25;
+    const data2 = await client.request(QUERY_STAFF_BY_ID_WITH_MEDIA, { id, perPage });
+    return data2.Staff;
+  }
+  const data = await client.request(QUERY_STAFF_BY_ID, { id });
+  return data.Staff;
+}
+async function searchStaff(client, options = {}) {
+  const { query: search, page = 1, perPage = 20, sort } = options;
+  return client.pagedRequest(
+    QUERY_STAFF_SEARCH,
+    { search, sort, page, perPage: clampPerPage(perPage) },
+    "staff"
+  );
+}
+
+// src/client/studio.ts
+async function getStudio(client, id) {
+  validateId(id, "studioId");
+  const data = await client.request(QUERY_STUDIO_BY_ID, { id });
+  return data.Studio;
+}
+async function searchStudios(client, options = {}) {
+  return client.pagedRequest(
+    QUERY_STUDIO_SEARCH,
+    {
+      search: options.query,
+      page: options.page ?? 1,
+      perPage: clampPerPage(options.perPage ?? 20)
+    },
+    "studios"
+  );
+}
+
+// src/client/thread.ts
+async function getThread(client, id) {
+  validateId(id, "threadId");
+  const data = await client.request(QUERY_THREAD_BY_ID, { id });
+  return data.Thread;
+}
+async function getRecentThreads(client, options = {}) {
+  const { query: search, page = 1, perPage = 20, sort, mediaId, categoryId } = options;
+  return client.pagedRequest(
+    QUERY_THREAD_SEARCH,
+    {
+      search,
+      mediaCategoryId: mediaId,
+      categoryId,
+      sort: sort ?? ["REPLIED_AT_DESC" /* REPLIED_AT_DESC */],
+      page,
+      perPage: clampPerPage(perPage)
+    },
+    "threads"
+  );
+}
+
+// src/client/user.ts
+async function getUser(client, idOrName) {
+  if (typeof idOrName === "number") {
+    validateId(idOrName, "userId");
+    const data2 = await client.request(QUERY_USER_BY_ID, { id: idOrName });
+    return data2.User;
+  }
+  const data = await client.request(QUERY_USER_BY_NAME, { name: idOrName });
+  return data.User;
+}
+async function searchUsers(client, options = {}) {
+  const { query: search, page = 1, perPage = 20, sort } = options;
+  return client.pagedRequest(QUERY_USER_SEARCH, { search, sort, page, perPage: clampPerPage(perPage) }, "users");
+}
+async function getUserMediaList(client, options) {
+  if (!options.userId && !options.userName) {
+    throw new AniListError("getUserMediaList requires either userId or userName", 0, []);
+  }
+  return client.pagedRequest(
+    QUERY_USER_MEDIA_LIST,
+    {
+      userId: options.userId,
+      userName: options.userName,
+      type: options.type,
+      status: options.status,
+      sort: options.sort,
+      page: options.page ?? 1,
+      perPage: clampPerPage(options.perPage ?? 20)
+    },
+    "mediaList"
+  );
+}
+async function getUserFavorites(client, idOrName) {
+  if (typeof idOrName === "number") {
+    validateId(idOrName, "userId");
+    const data2 = await client.request(QUERY_USER_FAVORITES_BY_ID, {
+      id: idOrName
+    });
+    return mapFavorites(data2.User.favourites);
+  }
+  const data = await client.request(QUERY_USER_FAVORITES_BY_NAME, {
+    name: idOrName
+  });
+  return mapFavorites(data.User.favourites);
+}
+function mapFavorites(fav) {
+  return {
+    anime: fav.anime?.nodes ?? [],
+    manga: fav.manga?.nodes ?? [],
+    characters: fav.characters?.nodes ?? [],
+    staff: fav.staff?.nodes ?? [],
+    studios: fav.studios?.nodes ?? []
+  };
+}
+
 // src/client/index.ts
 var DEFAULT_API_URL = "https://graphql.anilist.co";
 var AniListClient = class {
@@ -1017,15 +1489,31 @@ var AniListClient = class {
     this.cacheAdapter = options.cacheAdapter ?? new MemoryCache(options.cache);
     this.rateLimiter = new RateLimiter(options.rateLimit);
     this.hooks = options.hooks ?? {};
+    this.signal = options.signal;
   }
   /**
-   * @internal
+   * The current rate limit information from the last API response.
+   * Updated after every non-cached request.
+   */
+  get rateLimitInfo() {
+    return this._rateLimitInfo;
+  }
+  /**
+   * Metadata about the last request (duration, cache status, rate limit info).
+   * Useful for debugging and monitoring.
    */
+  get lastRequestMeta() {
+    return this._lastRequestMeta;
+  }
+  // ── Core infrastructure (internal) ──
+  /** @internal */
   async request(query, variables = {}) {
     const cacheKey = MemoryCache.key(query, variables);
     const cached = await this.cacheAdapter.get(cacheKey);
     if (cached !== void 0) {
       this.hooks.onCacheHit?.(cacheKey);
+      const meta = { durationMs: 0, fromCache: true };
+      this._lastRequestMeta = meta;
       this.hooks.onResponse?.(query, 0, true);
       return cached;
     }
@@ -1049,7 +1537,8 @@ var AniListClient = class {
       {
         method: "POST",
         headers: this.headers,
-        body: JSON.stringify({ query: minifiedQuery, variables })
+        body: JSON.stringify({ query: minifiedQuery, variables }),
+        signal: this.signal
       },
       { onRetry: this.hooks.onRetry, onRateLimit: this.hooks.onRateLimit }
     );
@@ -1058,15 +1547,25 @@ var AniListClient = class {
       const message = json.errors?.[0]?.message ?? `AniList API error (HTTP ${res.status})`;
       throw new AniListError(message, res.status, json.errors ?? []);
     }
+    const rlLimit = res.headers.get("X-RateLimit-Limit");
+    const rlRemaining = res.headers.get("X-RateLimit-Remaining");
+    const rlReset = res.headers.get("X-RateLimit-Reset");
+    if (rlLimit && rlRemaining && rlReset) {
+      this._rateLimitInfo = {
+        limit: Number.parseInt(rlLimit, 10),
+        remaining: Number.parseInt(rlRemaining, 10),
+        reset: Number.parseInt(rlReset, 10)
+      };
+    }
+    const durationMs = Date.now() - start;
     const data = json.data;
     await this.cacheAdapter.set(cacheKey, data);
-    this.hooks.onResponse?.(query, Date.now() - start, false);
+    const meta = { durationMs, fromCache: false, rateLimitInfo: this._rateLimitInfo };
+    this._lastRequestMeta = meta;
+    this.hooks.onResponse?.(query, durationMs, false, this._rateLimitInfo);
     return data;
   }
-  /**
-   * @internal
-   * Shorthand for paginated queries that follow the `Page { pageInfo, <field>[] }` pattern.
-   */
+  /** @internal */
   async pagedRequest(query, variables, field) {
     const data = await this.request(query, variables);
     const results = data.Page[field];
@@ -1075,6 +1574,7 @@ var AniListClient = class {
     }
     return { pageInfo: data.Page.pageInfo, results };
   }
+  // ── Media ──
   /**
    * Fetch a single media entry by its AniList ID.
    *
@@ -1082,514 +1582,145 @@ var AniListClient = class {
    *
    * @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, include) {
-    const query = include ? buildMediaByIdQuery(include) : QUERY_MEDIA_BY_ID;
-    const data = await this.request(query, { id });
-    return data.Media;
+    return getMedia(this, id, include);
   }
   /**
    * Search for anime or manga.
    *
    * @param options - Search / filter parameters
    * @returns Paginated results with matching media
-   *
-   * @example
-   * ```ts
-   * const results = await client.searchMedia({
-   *   query: "Naruto",
-   *   type: MediaType.ANIME,
-   *   perPage: 5,
-   * });
-   * ```
    */
   async searchMedia(options = {}) {
-    const { query: search, page = 1, perPage = 20, genres, tags, genresExclude, tagsExclude, ...filters } = options;
-    return this.pagedRequest(
-      QUERY_MEDIA_SEARCH,
-      {
-        search,
-        ...filters,
-        genre_in: genres,
-        tag_in: tags,
-        genre_not_in: genresExclude,
-        tag_not_in: tagsExclude,
-        page,
-        perPage: clampPerPage(perPage)
-      },
-      "media"
-    );
+    return searchMedia(this, options);
   }
-  /**
-   * Get currently trending anime or manga.
-   *
-   * @param type - `MediaType.ANIME` or `MediaType.MANGA` (defaults to ANIME)
-   * @param page - Page number (default 1)
-   * @param perPage - Results per page (default 20, max 50)
-   */
-  async getTrending(type = "ANIME" /* ANIME */, page = 1, perPage = 20) {
-    return this.pagedRequest(QUERY_TRENDING, { type, page, perPage: clampPerPage(perPage) }, "media");
+  /** Get currently trending anime or manga. */
+  async getTrending(type, page, perPage) {
+    return getTrending(this, type, page, perPage);
   }
-  /**
-   * Get the most popular anime or manga.
-   *
-   * Convenience wrapper around `searchMedia` with `sort: POPULARITY_DESC`.
-   *
-   * @param type - `MediaType.ANIME` or `MediaType.MANGA` (defaults to ANIME)
-   * @param page - Page number (default 1)
-   * @param perPage - Results per page (default 20, max 50)
-   */
-  async getPopular(type = "ANIME" /* ANIME */, page = 1, perPage = 20) {
-    return this.searchMedia({ type, sort: ["POPULARITY_DESC" /* POPULARITY_DESC */], page, perPage });
+  /** Get the most popular anime or manga. */
+  async getPopular(type, page, perPage) {
+    return getPopular(this, type, page, perPage);
   }
-  /**
-   * Get the highest-rated anime or manga.
-   *
-   * Convenience wrapper around `searchMedia` with `sort: SCORE_DESC`.
-   *
-   * @param type - `MediaType.ANIME` or `MediaType.MANGA` (defaults to ANIME)
-   * @param page - Page number (default 1)
-   * @param perPage - Results per page (default 20, max 50)
-   */
-  async getTopRated(type = "ANIME" /* ANIME */, page = 1, perPage = 20) {
-    return this.searchMedia({ type, sort: ["SCORE_DESC" /* SCORE_DESC */], page, perPage });
+  /** Get the highest-rated anime or manga. */
+  async getTopRated(type, page, perPage) {
+    return getTopRated(this, type, page, perPage);
   }
-  /**
-   * 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}`));
-   * });
-   * ```
-   */
+  /** Get recently aired anime episodes. */
+  async getAiredEpisodes(options = {}) {
+    return getAiredEpisodes(this, options);
+  }
+  /** Get currently releasing manga. */
+  async getAiredChapters(options = {}) {
+    return getAiredChapters(this, options);
+  }
+  /** Get the detailed schedule for the current week, sorted by day. */
+  async getWeeklySchedule(date) {
+    return getWeeklySchedule(this, date);
+  }
+  /** Get upcoming (not yet released) media. */
+  async getPlanning(options = {}) {
+    return getPlanning(this, options);
+  }
+  /** Get recommendations for a specific media. */
+  async getRecommendations(mediaId, options = {}) {
+    return getRecommendations(this, mediaId, options);
+  }
+  /** Get anime (or manga) for a specific season and year. */
+  async getMediaBySeason(options) {
+    return getMediaBySeason(this, options);
+  }
+  // ── Characters ──
+  /** Fetch a character by AniList ID. Pass `{ voiceActors: true }` to include VA data. */
   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;
+    return getCharacter(this, id, include);
   }
-  /**
-   * 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 });
-   * ```
-   */
+  /** Search for characters by name. */
   async searchCharacters(options = {}) {
-    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: clampPerPage(perPage) },
-      "characters"
-    );
+    return searchCharacters(this, options);
   }
-  /**
-   * Fetch a staff member by AniList ID.
-   *
-   * @param id - The AniList staff ID
-   * @param include - Optional include options to fetch related data (e.g. media)
-   * @returns The staff object
-   *
-   * @example
-   * ```ts
-   * const staff = await client.getStaff(95001);
-   * console.log(staff.name.full);
-   *
-   * // With media the staff worked on
-   * const staff = await client.getStaff(95001, { media: true });
-   * staff.staffMedia?.nodes.forEach((m) => console.log(m.title.romaji));
-   * ```
-   */
+  // ── Staff ──
+  /** Fetch a staff member by AniList ID. Pass `{ media: true }` or `{ media: { perPage } }` for media credits. */
   async getStaff(id, include) {
-    if (include?.media) {
-      const opts = typeof include.media === "object" ? include.media : {};
-      const perPage = opts.perPage ?? 25;
-      const data2 = await this.request(QUERY_STAFF_BY_ID_WITH_MEDIA, { id, perPage });
-      return data2.Staff;
-    }
-    const data = await this.request(QUERY_STAFF_BY_ID, { id });
-    return data.Staff;
+    return getStaff(this, id, include);
   }
-  /**
-   * 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 });
-   * ```
-   */
+  /** Search for staff (voice actors, directors, etc.). */
   async searchStaff(options = {}) {
-    const { query: search, page = 1, perPage = 20, sort } = options;
-    return this.pagedRequest(
-      QUERY_STAFF_SEARCH,
-      { search, sort, page, perPage: clampPerPage(perPage) },
-      "staff"
-    );
+    return searchStaff(this, options);
   }
+  // ── Users ──
   /**
    * Fetch a user by AniList ID or username.
    *
    * @param idOrName - The AniList user ID (number) or username (string)
-   * @returns The user object
-   *
-   * @example
-   * ```ts
-   * const user = await client.getUser(1);
-   * const user2 = await client.getUser("AniList");
-   * console.log(user.name);
-   * ```
    */
   async getUser(idOrName) {
-    if (typeof idOrName === "number") {
-      const data2 = await this.request(QUERY_USER_BY_ID, { id: idOrName });
-      return data2.User;
-    }
-    const data = await this.request(QUERY_USER_BY_NAME, { name: idOrName });
-    return data.User;
-  }
-  /**
-   * Fetch a user by username.
-   *
-   * @deprecated Use `getUser(name)` instead.
-   * @param name - The AniList username
-   * @returns The user object
-   */
-  async getUserByName(name) {
-    return this.getUser(name);
+    return getUser(this, idOrName);
   }
-  /**
-   * Search for users by name.
-   *
-   * @param options - Search / pagination parameters
-   * @returns Paginated results with matching users
-   *
-   * @example
-   * ```ts
-   * const result = await client.searchUsers({ query: "AniList", perPage: 5 });
-   * ```
-   */
+  /** Search for users by name. */
   async searchUsers(options = {}) {
-    const { query: search, page = 1, perPage = 20, sort } = options;
-    return this.pagedRequest(QUERY_USER_SEARCH, { search, sort, page, perPage: clampPerPage(perPage) }, "users");
-  }
-  /**
-   * Execute an arbitrary GraphQL query against the AniList API.
-   * Useful for advanced use-cases not covered by the built-in methods.
-   *
-   * @param query - A valid GraphQL query string
-   * @param variables - Optional variables object
-   */
-  async raw(query, variables) {
-    return this.request(query, variables);
-  }
-  /**
-   * 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,
-   * });
-   * ```
-   */
-  async getAiredEpisodes(options = {}) {
-    const now = Math.floor(Date.now() / 1e3);
-    const variables = {
-      airingAt_greater: options.airingAtGreater ?? now - 24 * 3600,
-      airingAt_lesser: options.airingAtLesser ?? now,
-      sort: options.sort ?? ["TIME_DESC"],
-      page: options.page ?? 1,
-      perPage: clampPerPage(options.perPage ?? 20)
-    };
-    return this.pagedRequest(QUERY_AIRING_SCHEDULE, variables, "airingSchedules");
-  }
-  /**
-   * 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 });
-   * ```
-   */
-  async getAiredChapters(options = {}) {
-    return this.pagedRequest(
-      QUERY_RECENT_CHAPTERS,
-      {
-        page: options.page ?? 1,
-        perPage: clampPerPage(options.perPage ?? 20)
-      },
-      "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 });
-   * ```
-   */
-  async getPlanning(options = {}) {
-    return this.pagedRequest(
-      QUERY_PLANNING,
-      {
-        type: options.type,
-        sort: options.sort ?? ["POPULARITY_DESC"],
-        page: options.page ?? 1,
-        perPage: clampPerPage(options.perPage ?? 20)
-      },
-      "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})`)
-   * );
-   * ```
-   */
-  async getRecommendations(mediaId, options = {}) {
-    const variables = {
-      mediaId,
-      sort: options.sort ?? ["RATING_DESC"],
-      page: options.page ?? 1,
-      perPage: clampPerPage(options.perPage ?? 20)
-    };
-    const data = await this.request(QUERY_RECOMMENDATIONS, variables);
-    return {
-      pageInfo: data.Media.recommendations.pageInfo,
-      results: data.Media.recommendations.nodes
-    };
+    return searchUsers(this, options);
   }
-  /**
-   * 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,
-   * });
-   * ```
-   */
-  async getMediaBySeason(options) {
-    return this.pagedRequest(
-      QUERY_MEDIA_BY_SEASON,
-      {
-        season: options.season,
-        seasonYear: options.seasonYear,
-        type: options.type ?? "ANIME",
-        sort: options.sort ?? ["POPULARITY_DESC"],
-        page: options.page ?? 1,
-        perPage: clampPerPage(options.perPage ?? 20)
-      },
-      "media"
-    );
+  /** Get a user's anime or manga list. */
+  async getUserMediaList(options) {
+    return getUserMediaList(this, options);
   }
   /**
-   * Get a user's anime or manga list.
+   * Fetch a user's favorite anime, manga, characters, staff, and studios.
    *
-   * 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
+   * @param idOrName - AniList user ID (number) or username (string)
+   * @returns The user's favorites grouped by category
    *
    * @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`)
-   * );
+   * ```typescript
+   * const favs = await client.getUserFavorites("AniList");
+   * favs.anime.forEach(a => console.log(a.title.romaji));
    * ```
    */
-  async getUserMediaList(options) {
-    if (!options.userId && !options.userName) {
-      throw new Error("Either userId or userName must be provided");
-    }
-    return this.pagedRequest(
-      QUERY_USER_MEDIA_LIST,
-      {
-        userId: options.userId,
-        userName: options.userName,
-        type: options.type,
-        status: options.status,
-        sort: options.sort,
-        page: options.page ?? 1,
-        perPage: clampPerPage(options.perPage ?? 20)
-      },
-      "mediaList"
-    );
+  async getUserFavorites(idOrName) {
+    return getUserFavorites(this, idOrName);
   }
-  /**
-   * Fetch a studio by its AniList ID.
-   *
-   * Returns studio details along with its most popular productions.
-   *
-   * @param id - The AniList studio ID
-   */
+  // ── Studios ──
+  /** Fetch a studio by its AniList ID. */
   async getStudio(id) {
-    const data = await this.request(QUERY_STUDIO_BY_ID, { id });
-    return data.Studio;
+    return getStudio(this, id);
   }
-  /**
-   * Search for studios by name.
-   *
-   * @param options - Search / pagination parameters
-   * @returns Paginated list of studios
-   *
-   * @example
-   * ```ts
-   * const studios = await client.searchStudios({ query: "MAPPA" });
-   * ```
-   */
+  /** Search for studios by name. */
   async searchStudios(options = {}) {
-    return this.pagedRequest(
-      QUERY_STUDIO_SEARCH,
-      {
-        search: options.query,
-        page: options.page ?? 1,
-        perPage: clampPerPage(options.perPage ?? 20)
-      },
-      "studios"
-    );
+    return searchStudios(this, options);
   }
-  /**
-   * Get all available genres on AniList.
-   *
-   * @returns Array of genre strings (e.g. "Action", "Adventure", ...)
-   */
+  // ── Metadata ──
+  // ── Threads ──
+  /** Fetch a forum thread by its AniList ID. */
+  async getThread(id) {
+    return getThread(this, id);
+  }
+  /** Get recent forum threads, optionally filtered by search, media, or category. */
+  async getRecentThreads(options = {}) {
+    return getRecentThreads(this, options);
+  }
+  /** Get all available genres on AniList. */
   async getGenres() {
     const data = await this.request(QUERY_GENRES);
     return data.GenreCollection;
   }
-  /**
-   * Get all available media tags on AniList.
-   *
-   * @returns Array of tag objects with id, name, description, category, isAdult
-   */
+  /** Get all available media tags on AniList. */
   async getTags() {
     const data = await this.request(QUERY_TAGS);
     return data.MediaTagCollection;
   }
+  // ── Raw query ──
+  /** Execute an arbitrary GraphQL query against the AniList API. */
+  async raw(query, variables) {
+    return this.request(query, variables ?? {});
+  }
+  // ── Pagination ──
   /**
-   * Auto-paginating async iterator.
-   *
-   * Wraps any paginated method and yields individual items across all pages.
-   * Stops when `hasNextPage` is `false` or `maxPages` is reached.
+   * Auto-paginating async iterator. Yields individual items across all pages.
    *
    * @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);
-   * }
-   * ```
    */
   async *paginate(fetchPage, maxPages = Number.POSITIVE_INFINITY) {
     let page = 1;
@@ -1604,71 +1735,49 @@ var AniListClient = class {
     }
   }
   // ── Batch queries ──
-  /**
-   * Fetch multiple media entries in a single API request.
-   * Uses GraphQL aliases to batch up to 50 IDs per call.
-   *
-   * @param ids - Array of AniList media IDs
-   * @returns Array of media objects (same order as input IDs)
-   */
+  /** Fetch multiple media entries in a single API request. */
   async getMediaBatch(ids) {
     if (ids.length === 0) return [];
+    validateIds(ids, "mediaId");
     if (ids.length === 1) return [await this.getMedia(ids[0])];
     return this.executeBatch(ids, buildBatchMediaQuery, "m");
   }
-  /**
-   * Fetch multiple characters in a single API request.
-   *
-   * @param ids - Array of AniList character IDs
-   * @returns Array of character objects (same order as input IDs)
-   */
+  /** Fetch multiple characters in a single API request. */
   async getCharacterBatch(ids) {
     if (ids.length === 0) return [];
+    validateIds(ids, "characterId");
     if (ids.length === 1) return [await this.getCharacter(ids[0])];
     return this.executeBatch(ids, buildBatchCharacterQuery, "c");
   }
-  /**
-   * Fetch multiple staff members in a single API request.
-   *
-   * @param ids - Array of AniList staff IDs
-   * @returns Array of staff objects (same order as input IDs)
-   */
+  /** Fetch multiple staff members in a single API request. */
   async getStaffBatch(ids) {
     if (ids.length === 0) return [];
+    validateIds(ids, "staffId");
     if (ids.length === 1) return [await this.getStaff(ids[0])];
     return this.executeBatch(ids, buildBatchStaffQuery, "s");
   }
   /** @internal */
   async executeBatch(ids, buildQuery, prefix) {
     const chunks = chunk(ids, 50);
-    const chunkResults = [];
-    for (const idChunk of chunks) {
-      const query = buildQuery(idChunk);
-      const data = await this.request(query);
-      chunkResults.push(idChunk.map((_, i) => data[`${prefix}${i}`]));
-    }
+    const chunkResults = await Promise.all(
+      chunks.map(async (idChunk) => {
+        const query = buildQuery(idChunk);
+        const data = await this.request(query);
+        return idChunk.map((_, i) => data[`${prefix}${i}`]);
+      })
+    );
     return chunkResults.flat();
   }
   // ── Cache management ──
-  /**
-   * Clear the entire response cache.
-   */
+  /** Clear the entire response cache. */
   async clearCache() {
     await this.cacheAdapter.clear();
   }
-  /**
-   * Number of entries currently in the cache.
-   * For async adapters like Redis, this may return a Promise.
-   */
+  /** Number of entries currently in the cache. */
   get cacheSize() {
     return this.cacheAdapter.size;
   }
-  /**
-   * Remove cache entries whose key matches the given pattern.
-   *
-   * @param pattern — A string (converted to RegExp) or RegExp
-   * @returns Number of entries removed
-   */
+  /** Remove cache entries whose key matches the given pattern. */
   async invalidateCache(pattern) {
     if (this.cacheAdapter.invalidate) {
       return this.cacheAdapter.invalidate(pattern);
@@ -1684,13 +1793,7 @@ var AniListClient = class {
     }
     return count;
   }
-  /**
-   * Clean up resources held by the client.
-   *
-   * Clears the in-memory cache and aborts any pending in-flight requests.
-   * If using a custom cache adapter (e.g. Redis), call its close/disconnect
-   * method separately.
-   */
+  /** Clean up resources held by the client. */
   async destroy() {
     await this.cacheAdapter.clear();
     this.inFlight.clear();
@@ -1780,6 +1883,6 @@ var RedisCache = class {
   }
 };
 
-export { AiringSort, AniListClient, AniListError, CharacterRole, CharacterSort, MediaFormat, MediaListSort, MediaListStatus, MediaRelationType, MediaSeason, MediaSort, MediaSource, MediaStatus, MediaType, MemoryCache, RateLimiter, RecommendationSort, RedisCache, StaffSort, UserSort };
+export { AiringSort, AniListClient, AniListError, CharacterRole, CharacterSort, MediaFormat, MediaListSort, MediaListStatus, MediaRelationType, MediaSeason, MediaSort, MediaSource, MediaStatus, MediaType, MemoryCache, RateLimiter, RecommendationSort, RedisCache, StaffSort, ThreadSort, UserSort, parseAniListMarkdown };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map