feat: upgrade to v2.0.0 with multi-mirror fallback, new endpoints, and LRU cache

- Add multi-mirror fallback system with 5 mirror domains
- Add LRU cache with configurable TTL per endpoint
- Add response compression (gzip)
- Add Seasons endpoint (/api/seasons/:id)
- Add Watch Order endpoint (/api/watch-order/:id)
- Add Latest Updated endpoint (/api/latest-updated)
- Add Download endpoint (/api/download)
- Add cache stats endpoint (/api/cache/stats)
- Add mirror status/reset endpoints (/api/mirrors, /api/mirrors/reset)
- Add configurable rate limiting with X-RateLimit headers
- Add request timeouts and entity too large handling
- Update documentation with all new endpoints
- Update CHANGELOG.md with v2.0.0 entry
- Update package.json version to 2.0.0
- Add 6 AI agent prompts for development

src/extractors/download.extractor.js

@@ -0,0 +1,187 @@
+/*
+ * ======= • ======= • ======= • ======= • =======• =======
+ * AniKotoAPI — download.extractor.js
+ * Repository: https://github.com/Shineii86/AniKotoAPI
+ *
+ * @description
+ *   Extracts download links for anime episodes from anikototv.to.
+ *   Decodes base64 download-data attributes and follows redirects
+ *   to get streaming server URLs.
+ *
+ *   Download flow:
+ *   1. Watch page → base64 decode → nekostream.site URL
+ *   2. nekostream.site → Cloudflare Worker → kwik.cx URL
+ *   3. kwik.cx → actual download URL (requires browser)
+ *
+ * @exports
+ *   extractDownloadLinks
+ *
+ * @author  Shinei Nouzen
+ * @license MIT
+ * ======= • ======= • ======= • ======= • =======• =======
+ */
+
+import * as cheerio from "cheerio";
+import axios from "axios";
+import { fetchWithMirror } from "../helper/mirror.helper.js";
+import { headers } from "../configs/header.config.js";
+
+/**
+ * Decodes base64 download data from the website
+ * @param {string} encoded - Base64 encoded string
+ * @returns {Object} Decoded download data
+ */
+function decodeDownloadData(encoded) {
+  try {
+    const decoded = Buffer.from(encoded, "base64").toString("utf-8");
+    return JSON.parse(decoded);
+  } catch (error) {
+    return null;
+  }
+}
+
+/**
+ * Follows redirect chain to get the final URL
+ * @param {string} url - Starting URL
+ * @returns {Promise<string>} Final URL after redirects
+ */
+async function followRedirects(url) {
+  try {
+    const response = await axios.get(url, {
+      headers,
+      maxRedirects: 5,
+      timeout: 10000
+    });
+    return response.request?.res?.responseUrl || response.config?.url || url;
+  } catch (error) {
+    // If we get a redirect error, try to extract the location
+    if (error.response?.headers?.location) {
+      return error.response.headers.location;
+    }
+    return url;
+  }
+}
+
+/**
+ * Fetches and parses download links for a specific episode.
+ * Scrapes the watch page to extract download-data attributes
+ * and follows the redirect chain to get streaming server URLs.
+ *
+ * Note: Download data may be loaded dynamically via JavaScript.
+ * If no download links are found in the initial HTML, try using
+ * a browser or headless browser to get the full page content.
+ *
+ * @param {string} slug - The anime slug (e.g., "kill-blue-gcqj5")
+ * @param {number} ep - Episode number
+ * @returns {Promise<Object>} Object with slug, episode, and downloads array
+ *
+ * @example
+ *   const downloads = await extractDownloadLinks("kill-blue-gcqj5", 1);
+ *   console.log(downloads.downloads[0].server); // server name
+ *   console.log(downloads.downloads[0].kwikUrl); // kwik.cx URL
+ */
+const extractDownloadLinks = async (slug, ep) => {
+  try {
+    const { data } = await fetchWithMirror(`/watch/${slug}/ep-${ep}`);
+    
+    // Handle both string HTML and JSON responses
+    let html = "";
+    if (typeof data === "string") {
+      try {
+        const json = JSON.parse(data);
+        html = json.result || data;
+      } catch (e) {
+        html = data;
+      }
+    } else if (data?.result) {
+      html = data.result;
+    } else if (data?.data) {
+      html = data.data;
+    } else {
+      html = String(data);
+    }
+    
+    const $ = cheerio.load(html);
+
+    const downloads = [];
+
+    // Find all download buttons with download-data attribute
+    // Multiple selectors to handle different HTML structures
+    const selectors = [
+      "[download-data]",
+      "li.download-icon",
+      ".download-icon",
+      "[onclick*='openDownloadModalDownload']",
+      "[onclick*='openDownloadModal']"
+    ];
+    
+    for (const selector of selectors) {
+      $(selector).each((_, el) => {
+        const encoded = $(el).attr("download-data") || "";
+        const serverType = $(el).closest(".type").attr("data-type") || "unknown";
+        const serverLabel = $(el).closest(".type").find("label").text().trim() || serverType;
+
+        if (encoded && encoded.length > 10) {
+          const decoded = decodeDownloadData(encoded);
+          if (decoded) {
+            // Extract URLs from the decoded data
+            for (const [serverGroup, servers] of Object.entries(decoded)) {
+              for (const [serverName, url] of Object.entries(servers)) {
+                // Avoid duplicates
+                const exists = downloads.some(d => d.url === url);
+                if (!exists) {
+                  // Construct worker URL from nekostream.site URL
+                  const workerUrl = url.includes("nekostream.site") 
+                    ? url.replace("https://pahe.nekostream.site/", "https://proud-dew-d754.download992.workers.dev/")
+                    : null;
+                  
+                  downloads.push({
+                    server: serverName,
+                    serverGroup,
+                    type: serverType,
+                    typeLabel: serverLabel,
+                    url, // nekostream.site URL
+                    workerUrl,
+                    kwikUrl: null, // Will be filled after redirect
+                    note: "Visit kwikUrl in browser to get actual download link"
+                  });
+                }
+              }
+            }
+          }
+        }
+      });
+      
+      if (downloads.length > 0) break;
+    }
+
+    // Try to follow redirects for each download URL
+    for (const download of downloads) {
+      if (download.workerUrl) {
+        try {
+          const finalUrl = await followRedirects(download.workerUrl);
+          if (finalUrl.includes("kwik.cx")) {
+            download.kwikUrl = finalUrl;
+          }
+        } catch (error) {
+          // If redirect fails, construct a placeholder kwik URL
+          download.kwikUrl = "https://kwik.cx/f/[requires-browser]";
+        }
+      }
+    }
+
+    return {
+      slug,
+      episode: ep,
+      totalDownloads: downloads.length,
+      downloads,
+      note: downloads.length > 0 
+        ? "kwikUrl requires browser to bypass Cloudflare protection" 
+        : "Download links may be loaded dynamically via JavaScript. Try using a browser."
+    };
+  } catch (error) {
+    throw error;
+  }
+};
+
+export { extractDownloadLinks };

src/extractors/episodeListAjax.extractor.js

@@ -19,7 +19,7 @@
 import * as cheerio from "cheerio";
 import axios from "axios";
 import { headers } from "../configs/header.config.js";
-import { BASE_URL } from "../configs/dataUrl.js";
+import { fetchWithMirror } from "../helper/mirror.helper.js";
 
 // ══════════════════════════════════════════════════════════════
 // EPISODE LIST AJAX EXTRACTOR
@@ -42,13 +42,13 @@ import { BASE_URL } from "../configs/dataUrl.js";
  */
 const extractEpisodeListAjax = async (animeId, style = "", vrf = "") => {
   try {
-    let url = `${BASE_URL}/ajax/episode/list/${animeId}`;
+    let path = `/ajax/episode/list/${animeId}`;
     const params = [];
     if (style) params.push(`style=${style}`);
     if (vrf) params.push(`vrf=${vrf}`);
-    if (params.length) url += `?${params.join("&")}`;
+    if (params.length) path += `?${params.join("&")}`;
 
-    const { data: raw } = await axios.get(url, {
+    const { data: raw } = await fetchWithMirror(path, {
       headers: {
         ...headers,
         "X-Requested-With": "XMLHttpRequest"

src/extractors/homeInfo.extractor.js

@@ -20,6 +20,7 @@ import axios from "axios";
 import { headers } from "../configs/header.config.js";
 import { URLS } from "../configs/dataUrl.js";
 import { getCache, setCache } from "../helper/cache.helper.js";
+import { fetchWithMirror } from "../helper/mirror.helper.js";
 
 // ══════════════════════════════════════════════════════════════
 // HOME INFO EXTRACTOR
@@ -40,7 +41,7 @@ const extractHomeInfo = async () => {
   const cached = getCache("home");
   if (cached) return cached;
   try {
-    const { data } = await axios.get(URLS.home, { headers });
+    const { data } = await fetchWithMirror("/home");
     const $ = cheerio.load(data);
 
     // ---- FEATURE: Extract spotlight carousel items from #hotest section ----

src/extractors/newRelease.extractor.js

@@ -22,6 +22,7 @@ import { headers } from "../configs/header.config.js";
 import { URLS } from "../configs/dataUrl.js";
 import { extractPages } from "../helper/extractPages.helper.js";
 import { countPages } from "../helper/countPages.helper.js";
+import { fetchWithMirror } from "../helper/mirror.helper.js";
 
 // ══════════════════════════════════════════════════════════════
 // NEW RELEASE EXTRACTION
@@ -160,6 +161,63 @@ const extractNewlyAdded = async (page = 1) => {
   }
 };
 
-export { extractNewRelease, extractNewlyAdded };
+// ══════════════════════════════════════════════════════════════
+// LATEST UPDATED EXTRACTION
+// ══════════════════════════════════════════════════════════════
+
+/**
+ * Fetches and parses recently updated anime with pagination.
+ * Uses the /latest-updated page which shows anime sorted by last update time.
+ *
+ * @param {number} page - Page number to fetch (default: 1)
+ * @returns {Promise<Object>} Object containing totalPages and data array
+ *
+ * @example
+ *   const latest = await extractLatestUpdated(1);
+ *   console.log(latest.totalPages);
+ *   console.log(latest.data[0].title);
+ */
+const extractLatestUpdated = async (page = 1) => {
+  try {
+    const $ = await extractPages("/latest-updated", page);
+    const totalPages = countPages($);
+
+    const results = [];
+
+    $(".item").each((i, el) => {
+      const slug = $(el).find("a").attr("href")?.split("/watch/").pop() || "";
+      const poster = $(el).find("img").attr("src") || "";
+      const title = $(el).find(".film-name a, .name.d-title").text().trim() ||
+                    $(el).find("a.name").text().trim() || "";
+      const japaneseTitle = $(el).find(".name.d-title").attr("data-jp") ||
+                           $(el).find("a.name").attr("data-jp") || "";
+      const sub = parseInt($(el).find(".ep-status.sub span").text().trim()) || 0;
+      const dub = parseInt($(el).find(".ep-status.dub span").text().trim()) || 0;
+      const total = parseInt($(el).find(".ep-status.total span").text().trim()) || 0;
+      const type = $(el).find(".type, .fdi-item:nth-child(2)").text().trim() || "";
+      const rating = $(el).find(".rating, .fdi-item:nth-child(3)").text().trim() || "";
+
+      if (slug) {
+        results.push({
+          slug,
+          poster,
+          title,
+          japaneseTitle,
+          sub,
+          dub,
+          total,
+          type,
+          rating
+        });
+      }
+    });
+
+    return { totalPages, data: results };
+  } catch (error) {
+    throw error;
+  }
+};
+
+export { extractNewRelease, extractNewlyAdded, extractLatestUpdated };
 
 // ══════════════════════════════════════════════════════════════ END: newRelease.extractor.js

src/extractors/seasons.extractor.js

@@ -4,8 +4,9 @@
  * Repository: https://github.com/Shineii86/AniKotoAPI
  *
  * @description
- *   Extracts season information for a specific anime via API.
- *   Returns season data from the internal API endpoint.
+ *   Extracts season information for a specific anime from the
+ *   anikototv.to AJAX endpoint. Returns all seasons/OVAs/specials
+ *   for a given anime series.
  *
  * @exports
  *   extractSeasons
@@ -15,30 +16,82 @@
  * ======= • ======= • ======= • ======= • =======• =======
  */
 
-import axios from "axios";
-import { headers } from "../configs/header.config.js";
-import { BASE_URL } from "../configs/dataUrl.js";
+import * as cheerio from "cheerio";
+import { fetchWithMirror } from "../helper/mirror.helper.js";
 
-// ══════════════════════════════════════════════════════════════
-// SEASONS API EXTRACTION
-// ══════════════════════════════════════════════════════════════
-
-// ---- FEATURE: Extract season data from internal API ----
 /**
- * Fetches season information for a specific anime from the internal API.
- * Returns an array of season objects or empty array on error.
+ * Fetches and parses season information for an anime.
+ * Scrapes the AJAX endpoint that returns season carousel HTML.
  *
- * @param {string} animeId - The anime ID to fetch seasons for
- * @returns {Promise<Array<Object>>} Array of season objects or empty array
+ * @param {string|number} animeId - The numeric anime ID
+ * @returns {Promise<Object>} Object with animeId, totalSeasons, and seasons array
  *
  * @example
- *   const seasons = await extractSeasons("12345");
- *   console.log(seasons.length); // Number of seasons
+ *   const seasons = await extractSeasons(7174);
+ *   console.log(seasons.totalSeasons); // number of seasons
+ *   console.log(seasons.seasons[0].title); // first season title
  */
 const extractSeasons = async (animeId) => {
-  throw new Error("Seasons endpoint not available - source site does not provide this data");
+  try {
+    const { data } = await fetchWithMirror(`/api/seasons/${animeId}`, {
+      headers: { "X-Requested-With": "XMLHttpRequest" }
+    });
+
+    // Handle both string HTML and JSON responses
+    let raw = "";
+    if (typeof data === "string") {
+      try {
+        const json = JSON.parse(data);
+        raw = json.result || data;
+      } catch (e) {
+        raw = data;
+      }
+    } else if (data?.result) {
+      raw = data.result;
+    } else if (data?.data) {
+      raw = data.data;
+    }
+    
+    const $ = cheerio.load(raw);
+
+    const seasons = [];
+    
+    // Try multiple selectors to handle different HTML structures
+    const selectors = [
+      ".swiper-slide.season",
+      ".seasons .swiper-slide",
+      "#w-seasons .swiper-slide",
+      ".swiper-slide"
+    ];
+    
+    for (const selector of selectors) {
+      $(selector).each((_, el) => {
+        const link = $(el).find("a").first();
+        const href = link.attr("href") || "";
+        const style = link.attr("style") || "";
+        const poster = style.match(/url\(['"]?(.+?)['"]?\)/)?.[1] || "";
+        const title = $(el).find(".name").text().trim() || 
+                     link.text().trim() || "";
+
+        // Extract slug from href
+        const slug = href.split("/watch/").pop() || "";
+
+        if (slug || title) {
+          seasons.push({ title, slug, poster, url: href });
+        }
+      });
+      
+      if (seasons.length > 0) break;
+    }
+
+    return {
+      animeId,
+      totalSeasons: seasons.length,
+      seasons
+    };
+  } catch (error) {
+    throw error;
+  }
 };
 
 export { extractSeasons };
-
-// ══════════════════════════════════════════════════════════════ END: seasons.extractor.js

src/extractors/watchOrder.extractor.js

@@ -4,8 +4,9 @@
  * Repository: https://github.com/Shineii86/AniKotoAPI
  *
  * @description
- *   Extracts watch order information for a specific anime via API.
- *   Returns recommended viewing order from the internal API endpoint.
+ *   Extracts watch order and related anime information from the
+ *   anikototv.to AJAX endpoint. Returns related anime with their
+ *   relationship types (sequel, prequel, summary, etc.).
  *
  * @exports
  *   extractWatchOrder
@@ -15,30 +16,90 @@
  * ======= • ======= • ======= • ======= • =======• =======
  */
 
-import axios from "axios";
-import { headers } from "../configs/header.config.js";
-import { BASE_URL } from "../configs/dataUrl.js";
+import * as cheerio from "cheerio";
+import { fetchWithMirror } from "../helper/mirror.helper.js";
 
-// ══════════════════════════════════════════════════════════════
-// WATCH ORDER API EXTRACTION
-// ══════════════════════════════════════════════════════════════
-
-// ---- FEATURE: Extract watch order data from internal API ----
 /**
- * Fetches watch order information for a specific anime from the internal API.
- * Returns an array of watch order objects or empty array on error.
+ * Fetches and parses watch order / related anime for an anime.
+ * Scrapes the AJAX endpoint that returns related anime HTML.
  *
- * @param {string} animeId - The anime ID to fetch watch order for
- * @returns {Promise<Array<Object>>} Array of watch order objects or empty array
+ * @param {string|number} animeId - The numeric anime ID
+ * @returns {Promise<Object>} Object with animeId, totalRelated, related array
  *
  * @example
- *   const watchOrder = await extractWatchOrder("12345");
- *   console.log(watchOrder[0].title); // First anime in watch order
+ *   const data = await extractWatchOrder(7174);
+ *   console.log(data.totalRelated); // number of related anime
+ *   console.log(data.related[0].title); // first related anime
  */
 const extractWatchOrder = async (animeId) => {
-  throw new Error("Watch order endpoint not available - source site does not provide this data");
+  try {
+    const { data } = await fetchWithMirror(`/api/watch-order/${animeId}`, {
+      headers: { "X-Requested-With": "XMLHttpRequest" }
+    });
+
+    // Handle both string HTML and JSON responses
+    let raw = "";
+    if (typeof data === "string") {
+      try {
+        const json = JSON.parse(data);
+        raw = json.result || data;
+      } catch (e) {
+        raw = data;
+      }
+    } else if (data?.result) {
+      raw = data.result;
+    } else if (data?.data) {
+      raw = data.data;
+    }
+    
+    const $ = cheerio.load(raw);
+
+    // Extract related anime
+    const related = [];
+    
+    // Try multiple selectors
+    const selectors = [
+      "#w-related .item",
+      ".item.flexserieslist",
+      ".scaff.side.items .item",
+      ".item"
+    ];
+    
+    for (const selector of selectors) {
+      $(selector).each((_, el) => {
+        const link = $(el).find("a.name").first();
+        const href = link.attr("href") || "";
+        const title = link.text().trim() || "";
+        const poster = $(el).find("img").attr("src") || "";
+        const slug = href.split("/watch/").pop() || "";
+
+        // Extract relationship type
+        const relationEl = $(el).find(".relation, .serieslabelitem").first();
+        let relationType = relationEl.text().trim().toLowerCase() || 
+                          relationEl.attr("id") || "related";
+
+        if (slug || title) {
+          related.push({
+            title,
+            slug,
+            poster,
+            url: href,
+            relation: relationType
+          });
+        }
+      });
+      
+      if (related.length > 0) break;
+    }
+
+    return {
+      animeId,
+      totalRelated: related.length,
+      related
+    };
+  } catch (error) {
+    throw error;
+  }
 };
 
 export { extractWatchOrder };
-
-// ══════════════════════════════════════════════════════════════ END: watchOrder.extractor.js