ani-client 1.5.1 → 1.6.0

package/dist/index.js

@@ -32,8 +32,9 @@ function parseAniListMarkdown(text) {
 }
 
 // src/utils/index.ts
+var WHITESPACE_RE = /\s+/g;
 function normalizeQuery(query) {
-  return query.replace(/\s+/g, " ").trim();
+  return query.replace(WHITESPACE_RE, " ").trim();
 }
 function clampPerPage(value) {
   return Math.min(Math.max(value, 1), 50);
@@ -45,6 +46,25 @@ function chunk(arr, 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;
@@ -58,7 +78,7 @@ var MemoryCache = class {
   /** 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())}`;
+    return `${normalized}|${JSON.stringify(sortObjectKeys(variables))}`;
   }
   /** Retrieve a cached value, or `undefined` if missing / expired. */
   get(key) {
@@ -326,6 +346,53 @@ 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
@@ -586,6 +653,22 @@ query ($userId: Int, $userName: String, $type: MediaType!, $status: MediaListSta
     }
   }
 }`;
+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 = `
@@ -794,6 +877,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);
   }
   /**
@@ -854,8 +938,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);
@@ -895,6 +982,7 @@ function isNetworkError(err) {
 
 // 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;
@@ -1142,6 +1230,7 @@ var ThreadSort = /* @__PURE__ */ ((ThreadSort2) => {
 
 // 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;
@@ -1262,9 +1351,9 @@ async function getWeeklySchedule(client, date = /* @__PURE__ */ new Date()) {
       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 names = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
     const dayName = names[epDate.getDay()];
     schedule[dayName].push(episode);
   }
@@ -1273,6 +1362,7 @@ async function getWeeklySchedule(client, date = /* @__PURE__ */ new Date()) {
 
 // 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 });
@@ -1292,6 +1382,7 @@ async function searchStaff(client, options = {}) {
 
 // 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;
 }
@@ -1309,6 +1400,7 @@ async function searchStudios(client, options = {}) {
 
 // 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;
 }
@@ -1331,6 +1423,7 @@ async function getRecentThreads(client, options = {}) {
 // 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;
   }
@@ -1359,6 +1452,28 @@ async function getUserMediaList(client, options) {
     "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";
@@ -1376,6 +1491,21 @@ 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;
+  }
+  /**
+   * 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 */
@@ -1384,6 +1514,8 @@ var AniListClient = class {
     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;
     }
@@ -1407,7 +1539,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 }
     );
@@ -1416,9 +1549,22 @@ 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 */
@@ -1522,6 +1668,21 @@ var AniListClient = class {
   async getUserMediaList(options) {
     return getUserMediaList(this, options);
   }
+  /**
+   * Fetch a user's favorite anime, manga, characters, staff, and studios.
+   *
+   * @param idOrName - AniList user ID (number) or username (string)
+   * @returns The user's favorites grouped by category
+   *
+   * @example
+   * ```typescript
+   * const favs = await client.getUserFavorites("AniList");
+   * favs.anime.forEach(a => console.log(a.title.romaji));
+   * ```
+   */
+  async getUserFavorites(idOrName) {
+    return getUserFavorites(this, idOrName);
+  }
   // ── Studios ──
   /** Fetch a studio by its AniList ID. */
   async getStudio(id) {
@@ -1579,30 +1740,34 @@ var AniListClient = class {
   /** 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. */
   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. */
   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 ──