v1.5.0: Complete documentation rewrite - 50+ files with AlisaReactionBot style

- Box-style header comments (Project, Author, License) on every file
- Section headers using double-line box decorators
- Feature markers (// ---- FEATURE: XYZ ----) before every major function
- JSDoc comments for EVERY function with @param, @returns, @example
- Inline notes (NOTE, WARNING, TIP) for non-obvious logic
- Footer END markers on every module
- Matched code style to AlisaReactionBot repository
- All files now searchable by feature name via grep

Author: Shinei Nouzen <157171073+Shineii86@users.noreply.github.com>

src/extractors/streamInfo.extractor.js

@@ -1,10 +1,46 @@
+/*
+ * ======= • ======= • ======= • ======= • =======• =======
+ * AniKatoAPI — streamInfo.extractor.js
+ * Repository: https://github.com/Shineii86/AniKatoAPI
+ *
+ * @description
+ *   Handles server/stream resolution for episodes — fetches individual
+ *   stream URLs, server lists via AJAX, and alternative servers from
+ *   the nekostream mapper API.
+ *
+ * @exports
+ *   extractStreamInfo, extractServerList, extractMapperServers
+ *
+ * @author  Shinei Nouzen
+ * @license MIT
+ * ======= • ======= • ======= • ======= • =======• =======
+ */
+
 import axios from "axios";
 import { headers } from "../configs/header.config.js";
 import { BASE_URL } from "../configs/dataUrl.js";
 
+// ══════════════════════════════════════════════════════════════
+// STREAM INFO EXTRACTOR
+// ══════════════════════════════════════════════════════════════
+
+// ---- FEATURE: Resolve a single stream URL from a linkId ----
+/**
+ * Fetches the actual stream URL and skip data for a given server link ID.
+ * This is the primary method for resolving playable video URLs.
+ *
+ * @param {string} linkId - The server link ID to resolve
+ * @returns {Promise<Object>} Object with linkId, url, and skipData (intro/outro timestamps)
+ *
+ * @example
+ *   const stream = await extractStreamInfo("abc123");
+ *   console.log(stream.url);      // direct video URL
+ *   console.log(stream.skipData); // intro/outro skip ranges
+ */
 const extractStreamInfo = async (linkId) => {
   try {
     const url = `${BASE_URL}/ajax/server?get=${linkId}`;
+    // NOTE: X-Requested-With header is required for AJAX endpoints on anikototv.to
     const { data } = await axios.get(url, {
       headers: {
         ...headers,
@@ -26,6 +62,22 @@ const extractStreamInfo = async (linkId) => {
   }
 };
 
+// ══════════════════════════════════════════════════════════════
+// SERVER LIST EXTRACTOR
+// ══════════════════════════════════════════════════════════════
+
+// ---- FEATURE: Fetch available servers for a set of episode IDs ----
+/**
+ * Retrieves the server list for the given episode IDs from the AJAX endpoint.
+ * Returns raw server data as provided by the source site.
+ *
+ * @param {string} episodeIds - Comma-separated or single episode ID string
+ * @returns {Promise<Object>} Raw server list data from the AJAX response
+ *
+ * @example
+ *   const servers = await extractServerList("12345");
+ *   // servers contains the server configuration for that episode
+ */
 const extractServerList = async (episodeIds) => {
   try {
     const url = `${BASE_URL}/ajax/server/list?servers=${episodeIds}`;
@@ -42,6 +94,26 @@ const extractServerList = async (episodeIds) => {
   }
 };
 
+// ══════════════════════════════════════════════════════════════
+// MAPPER SERVERS EXTRACTOR
+// ══════════════════════════════════════════════════════════════
+
+// ---- FEATURE: Fetch alternative streaming servers from nekostream mapper API ----
+/**
+ * Queries the nekostream mapper API for alternative streaming providers
+ * (sub and dub) for a given anime identified by MAL ID, slug, and timestamp.
+ * Returns a flat array of server objects per provider.
+ *
+ * @param {number|string} malId - MyAnimeList ID for the anime
+ * @param {string} slug - The anime slug on anikototv.to
+ * @param {string|number} timestamp - Episode timestamp identifier
+ * @returns {Promise<Array>} Array of server objects with provider, type, url, download fields
+ *
+ * @example
+ *   const servers = await extractMapperServers(21, "one-piece", 1234567890);
+ *   console.log(servers[0].provider); // "vidstreaming"
+ *   console.log(servers[0].type);     // "sub" or "dub"
+ */
 const extractMapperServers = async (malId, slug, timestamp) => {
   try {
     const url = `https://mapper.nekostream.site/api/mal/${malId}/${slug}/${timestamp}`;
@@ -51,6 +123,7 @@ const extractMapperServers = async (malId, slug, timestamp) => {
 
     if (data && typeof data === "object") {
       for (const [provider, sources] of Object.entries(data)) {
+        // NOTE: Each provider may have sub, dub, or both source types
         if (sources && sources.sub) {
           servers.push({
             provider,
@@ -72,8 +145,11 @@ const extractMapperServers = async (malId, slug, timestamp) => {
 
     return servers;
   } catch (error) {
+    // NOTE: Returns empty array on failure — mapper API may be unavailable
     return [];
   }
 };
 
-export { extractStreamInfo, extractServerList, extractMapperServers };
+export { extractStreamInfo, extractServerList, extractMapperServers };
+
+// ══════════════════════════════════════════════════════════════ END: streamInfo.extractor.js