docs: Update all documentation for v2.2.0 — 38 endpoints, streaming resolver, proxy

README.md:
- Version badge: 2.1.0 → 2.2.0
- Endpoint count: 33 → 38
- Feature table: added stream URL resolution, M3U8 proxy, season/epMin/epMax filters
- Streaming section: added /stream/resolve, /stream/qualities, /stream/proxy docs
- Project structure: updated controller/extractor/helper file lists
- Dependencies: removed cors, updated dep list
- Changelog highlights: added v2.2.0 entry
- Completed checklist: added 38 endpoints, streaming resolver, proxy, diagnostic sweep

docs/endpoints.md:
- Added 8 new endpoint sections: upcoming, top-rankings, recently-updated, completed,
  stream/resolve, stream/qualities, stream/proxy, stream/ts-proxy

docs/streaming.md:
- Added Stream URL Resolution section (Step 4)
- Added M3U8 quality parsing docs
- Added M3U8 proxy docs with CORS-free playback explanation
- Updated troubleshooting table

docs/architecture.md:
- Updated project structure with all new files (streamResolver, parseListItem, etc.)
- Updated streaming flow diagram with resolver/proxy steps
- Updated dependencies table

docs/examples.md:
- Added curl examples for upcoming, top-rankings, recently-updated, completed
- Added stream resolver, qualities, proxy examples

CHANGELOG.md:
- Updated v2.2.0 entry with M3U8/TS proxy, mirror fix, all bug fixes

agents/:
- Updated api-tester.md: 36 → 38 endpoints
- Updated technical-writer.md: 36 → 38 endpoints
- Updated performance-benchmarker.md: 36 → 38 endpoints

.env.example

@@ -3,3 +3,25 @@ ALLOWED_ORIGINS=https://site1.com,https://site2.com
 
 # Port (optional, defaults to 4444)
 PORT=4444
+
+# Cache configuration
+CACHE_MAX_SIZE=200
+CACHE_DEFAULT_TTL=300000
+
+# Rate limiting
+RATE_LIMIT=100
+RATE_WINDOW=60000
+
+# Request timeout in milliseconds
+REQUEST_TIMEOUT=30000
+
+# Mirror configuration
+# Comma-separated list of mirror domains (in priority order)
+# Default: anikototv.to,anikoto.cz,anikoto.me,anikoto.net,anikototv.se
+MIRROR_DOMAINS=https://anikototv.to,https://anikoto.cz,https://anikoto.me,https://anikoto.net,https://anikototv.se
+
+# Mirror cache TTL in milliseconds (default: 1 hour)
+MIRROR_CACHE_TTL=3600000
+
+# Environment (production/development)
+NODE_ENV=production

CHANGELOG.md

@@ -5,6 +5,142 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.2.0] - 2026-07-28
+
+### Added
+- **Stream Resolve Endpoint**: `GET /api/stream/resolve?id=&slug=` — Resolves actual m3u8/mp4 URLs from embed player URLs (vidtube.site → megaplay API → m3u8 playlist)
+- **Stream Qualities Endpoint**: `GET /api/stream/qualities?url=` — Parses M3U8 playlists for available quality options with resolution, bandwidth, and URLs
+- **M3U8 Proxy Endpoint**: `GET /api/stream/proxy?url=` — Rewrites M3U8 playlists to proxy through API for CORS-free HLS playback
+- **TS Proxy Endpoint**: `GET /api/stream/ts-proxy?url=` — Proxies `.ts` video segments with proper `Content-Type: video/mp2t` and CORS headers
+- **Stream Resolver Extractor**: Full pipeline for resolving actual video URLs from embed pages
+- **M3U8 Quality Parser**: Parses master playlists to extract quality options sorted by resolution
+- **Server Name Normalization**: Maps display names to clean identifiers (VidPlay-1 → vidplay, HD-1 → hd)
+- **Subtitle Extraction**: Extracts subtitle tracks from streaming API responses
+- **Embed API Domain Mapping**: Maps vidtube.site → megaplay-1.buzz for stream resolution
+- **Shared Helper**: New `parseListItem.helper.js` for unified anime list item parsing across all extractors
+- **Graceful Shutdown**: Server now handles SIGTERM/SIGINT signals for clean shutdown
+- **Request ID Tracking**: Every request gets a unique `X-Request-Id` header for debugging
+- **CSP Headers**: Added `Content-Security-Policy` header for XSS protection
+- **HSTS Headers**: Added `Strict-Transport-Security` header for HTTPS enforcement
+- **Body Size Limits**: Added `express.json({ limit: '10kb' })` to prevent large payload attacks
+- **Rate Limiter Cleanup**: Automatic cleanup of stale IP entries every 5 minutes
+- **Uncaught Exception Handler**: Added handler for uncaught exceptions with graceful shutdown
+- **Upcoming Anime Endpoint**: `GET /api/upcoming` — upcoming anime releases from homepage
+- **Top Anime Rankings Endpoint**: `GET /api/top-rankings?sort=top|newest` — ranked anime with sort modes
+- **Recently Updated Tabs Endpoint**: `GET /api/recently-updated?tab=all|dub|sub` — filtered updates
+- **Completed Anime Endpoint**: `GET /api/completed` — finished anime series from homepage
+- **Enhanced Filter**: Added `source`, `epMin`, `epMax`, `excludeWatchlist` parameters to `/api/filter`
+- **Source IDs Config**: New `SOURCE_IDS` mapping for 18 source material types
+- **Season IDs Config**: New `SEASON_IDS` mapping for 4 broadcast seasons
+- **Extended Type IDs**: Added `tv-short` and `tv-special` type mappings
+
+### Changed
+- **Mirror Fallback**: All 22+ extractors now use `fetchWithMirror()` for consistent mirror fallback
+- **Mirror Helper**: 404 responses no longer mark mirrors as failed — only connection errors trigger failover
+- **Seasons Extractor**: Rewritten to extract from watch page sidebar (AJAX endpoints don't exist on source site)
+- **Watch Order Extractor**: Rewritten to extract from watch page sidebar trending/related sections
+- **Stream Info Extractor**: Now establishes session before AJAX calls, normalizes server names, adds type field
+- **Code Deduplication**: Extracted shared list item parsing logic into `parseListItem.helper.js`, eliminating ~200 lines of duplicated code across 8+ extractors
+- **Documentation**: All files follow strict documentation style — box-style headers, section separators, feature markers, JSDoc params/returns, inline notes, and module footers
+- **Version**: Bumped to 2.2.0
+- **Package**: Removed unused `cors` dependency (custom CORS middleware used instead)
+- **README**: Updated all endpoint counts, features, and streaming flow documentation
+- **Docs**: Updated endpoints.md, streaming.md, architecture.md, examples.md with new endpoints
+
+### Fixed
+- **Middleware Order**: Moved request timeout middleware before routes to properly catch timeouts
+- **CORS POST**: Fixed CORS to allow POST method for `/api/mirrors/reset` endpoint
+- **HomeInfo Cache**: Removed redundant cache check in `homeInfo.extractor.js` (controller already handles caching)
+- **Error Handler**: Added `res.headersSent` check to prevent double response on timeout
+- **Unused Imports**: Removed unused `cheerio`, `axios`, `headers` imports from extractors that now use `fetchWithMirror`
+- **Watch Page Path**: Fixed `/api/watch` 500 error — path format changed from `/slug/ep` to `/slug/ep-N`
+- **Info Endpoint**: Now accepts both `?id=` and `?slug=` params for flexibility
+- **Status Names**: Fixed `/api/status/airing` 500 — added status name mapping (ongoing→currently-airing, completed→finished-airing)
+- **Top Rankings**: Fixed selectors to match actual HTML (`#top-anime .scaff.side.items a.item`) with rank class extraction
+- **Completed Anime**: Fixed selectors for `section.top-table[data-name='completed']`
+- **Recently Updated**: Fixed selectors for `#recent-update .ani.items .item` with client-side tab filtering
+
+### Removed
+- **Unused Dependency**: Removed `cors` package from dependencies (custom middleware handles CORS)
+- **Dead Code**: Removed redundant cache check in `homeInfo.extractor.js`
+
+## [2.1.0] - 2026-07-05
+
+### Changed
+- **UI**: Complete redesign of all HTML pages with Claude/Anthropic design system
+- **UI**: Warm cream canvas (#faf9f5) replacing dark purple theme
+- **UI**: Coral accent (#cc785c) replacing gradient purple/pink
+- **UI**: Slab-serif headlines (Cormorant Garamond) with negative letter-spacing
+- **UI**: Dark navy product surfaces (#181715) for code blocks and footer
+- **UI**: Light cream feature cards (#efe9de)
+- **UI**: Removed ambient orbs, particles, glitch effects, scanlines
+- **UI**: Minimal shadows with color-block depth philosophy
+- **Version**: Bumped to 2.1.0
+
+## [2.0.2] - 2026-07-05
+
+### Fixed
+- **Documentation**: Fixed streaming flow guide — `/api/episodes/:slug` corrected to `/api/episodes/:animeId`
+- **Documentation**: Fixed all examples using `road-of-naruto-ggjw8` slug for episodes to use `958` animeId
+- **Documentation**: Fixed JavaScript/Node.js streaming examples to use `animeId` parameter instead of `animeSlug`
+- **Documentation**: Updated cURL examples to use correct animeId (958) for episodes endpoint
+- **Documentation**: Updated architecture.md streaming flow diagram to reflect correct endpoint
+
+## [2.0.1] - 2026-07-05
+
+### Fixed
+- **Documentation**: Fixed `/api/servers` parameter description — now correctly states `server_ids` from `/episodes` response (base64-encoded) instead of generic "Episode IDs"
+- **Documentation**: Fixed `/api/servers` sample response to match actual API output (flat array with `type`, `ep_id`, `link_id`, `cmid`, `sv_id`, `name`)
+- **Documentation**: Added `/api/stream` quick reference section with parameter docs and example response
+- **Documentation**: Added note that `/api/stream` requires lowercase `id` parameter (case-sensitive)
+
+## [2.0.0] - 2026-07-04
+
+### Added
+- **Pagination Metadata**: All list endpoints now include `pagination` object with `currentPage`, `totalPages`, `totalItems`, `itemsPerPage`, `hasNext`, `hasPrev`
+- **Creator Info Middleware**: Injects creator attribution (name, GitHub, Telegram, message, timestamp) into every JSON response
+- **Multi-Mirror Fallback System**: Automatic failover across 5 mirror domains (anikototv.to, anikoto.cz, anikoto.me, anikoto.net, anikototv.se)
+- **LRU Cache with Configurable TTL**: Replaced basic Map cache with LRU cache supporting per-endpoint TTL (3min to 60min)
+- **Response Compression**: Added gzip compression middleware (level 6, 1024 byte threshold)
+- **Cache Statistics Endpoint**: `/api/cache/stats` returns hits, misses, sets, deletes, size, hitRate
+- **Mirror Status Endpoint**: `/api/mirrors` shows health status and latency for all domains
+- **Mirror Reset Endpoint**: `/api/mirrors/reset` clears mirror cache and failed state
+- **Seasons Endpoint**: `/api/seasons/:id` returns all seasons/OVAs/movies for an anime
+- **Watch Order Endpoint**: `/api/watch-order/:id` returns related anime with relationship types
+- **Latest Updated Endpoint**: `/api/latest-updated` returns recently updated anime sorted by update time
+- **Download Endpoint**: `/api/download?slug=&ep=` returns decoded download links from base64 data
+- **Configurable Rate Limiting**: `RATE_LIMIT` and `RATE_WINDOW` env vars for customization
+- **Request Timeout**: Configurable via `REQUEST_TIMEOUT` env var (default 30s)
+- **Rate Limit Headers**: `X-RateLimit-Limit` and `X-RateLimit-Remaining` headers
+- **Retry-After Header**: Included in 429 responses with seconds until reset
+- **Environment Variables**: Added `MIRROR_DOMAINS`, `MIRROR_CACHE_TTL`, `CACHE_MAX_SIZE`, `CACHE_DEFAULT_TTL`
+- **Test Suite**: Added 27 endpoint tests with performance metrics and optional endpoint handling
+- **OpenAPI Spec**: Added `/api/mirrors`, `/api/mirrors/reset`, `/api/latest-updated`, `/api/download` to spec
+
+### Changed
+- **BREAKING**: All extractors now use mirror fallback helper for resilience
+- **BREAKING**: Cache system upgraded from simple Map to LRU with eviction
+- **BREAKING**: Rate limiting now configurable via environment variables
+- Updated `extractPages.helper.js` to use `fetchWithMirror` instead of direct axios
+- Updated `homeInfo.extractor.js` to use mirror fallback
+- Updated `episodeListAjax.extractor.js` to use mirror fallback
+- Updated all controllers to use endpoint-specific TTL values
+- Updated `.env.example` with all new configuration options
+- Updated `test.js` with optional endpoint handling and performance metrics
+
+### Fixed
+- **CRITICAL**: Fixed `extractPages` URL handling bug causing doubled URLs in mirror fallback
+- **CRITICAL**: Fixed `creatorInfo` middleware not including `message` field in responses
+- Fixed header merging bug in mirror helper (custom headers were ignored)
+- Fixed mirror URL construction (proper base URL handling)
+- Fixed cache key sorting in filter controller
+- Fixed trailing slash inconsistency in console output
+- Fixed inconsistent error handling across extractors
+
+### Removed
+- Removed `og-image.svg` and `logo.png` (replaced by `share.png`)
+- Removed unused `cookie-parser` dependency (was already removed in v1.8.0)
+
 ## [1.9.0] - 2026-06-09
 
 ### Fixed

README.md

@@ -1,6 +1,9 @@
+> [!NOTE]
+> **API MAYBE Temporarily Paused** due to suspiciously too many requests. My hosted version of this API is only for testing purposes. You MUST host your own instance to use the API.
+
 <div align="center">
   
-  <img src="https://capsule-render.vercel.app/api?type=waving&height=300&color=gradient&text=AniKotoAPI&fontAlignY=30&fontSize=90&desc=Real-Time%20Anime%20Streaming%20Data%20API&descSize=30" />
+  <img src="https://capsule-render.vercel.app/api?type=waving&height=300&color=gradient&text=𝘼𝙣𝙞𝙆𝙤𝙩𝙤𝘼𝙋𝙄&fontAlignY=30&fontSize=100&desc=𝖱𝖾𝖺𝗅-𝖳𝗂𝗆𝖾%20𝖠𝗇𝗂𝗆𝖾%20𝖲𝗍𝗋𝖾𝖺𝗆𝗂𝗇𝗀%20𝖣𝖺𝗍𝖺%20𝖠𝖯𝖨&descSize=30" />
 
 </div>
 
@@ -19,14 +22,14 @@
   <img src="https://img.shields.io/badge/Cheerio-1.0-3572A5?style=flat-square&logoColor=white" alt="Cheerio"/>
   <img src="https://img.shields.io/badge/Vercel-Serverless-000000?style=flat-square&logo=vercel&logoColor=white" alt="Vercel"/>
   <img src="https://img.shields.io/badge/License-MIT-22c55e?style=flat-square&logo=mit&logoColor=white" alt="License"/>
-  <img src="https://img.shields.io/badge/Version-1.9.0-f43f8e?style=flat-square&logoColor=white" alt="Version"/>
+  <img src="https://img.shields.io/badge/Version-2.2.0-f43f8e?style=flat-square&logoColor=white" alt="Version"/>
-  <img src="https://img.shields.io/badge/Endpoints-30-6366f1?style=flat-square&logoColor=white" alt="Endpoints"/>
+  <img src="https://img.shields.io/badge/Endpoints-38-6366f1?style=flat-square&logoColor=white" alt="Endpoints"/>
   <img src="https://img.shields.io/badge/Anime-10000+-a855f7?style=flat-square&logoColor=white" alt="Anime Database"/>
 </p>
 
 <p align="center">
   <b>A complete RESTful API scraping real-time anime data from anikototv.to</b><br/>
-  Search, browse, filter, watch — every endpoint returns live data with 5-minute smart caching.<br/>
+  Search, browse, filter, watch — every endpoint returns live data with smart caching and multi-mirror fallback.<br/>
   Built for building anime websites, apps, and bots.
 </p>
 
@@ -84,23 +87,23 @@
 
 ### Why AniKotoAPI?
 
-- 🎬 **30 Endpoints** — Complete coverage of anikototv.to data
+- 🎬 **38 Endpoints** — Complete coverage of anikototv.to data
 - 🔍 **Full-Text Search** — Search anime by keyword with suggestions
 - 📺 **Episode Lists** — AJAX-loaded episode data with server info
 - 🎯 **Smart Filtering** — Genre, type, status, rating, sort, season, year
 - 🏆 **Rankings** — Top 10 (day/week/month), trending, most popular
 - 🎲 **Random Anime** — Random anime discovery endpoint
-- ⚡ **Smart Caching** — 5-minute TTL reduces source site load
+- ⚡ **Smart Caching** — LRU cache with configurable TTL per endpoint
-- 🔒 **CORS Enabled** — Works from any frontend, no proxy needed
+- 🌐 **Multi-Mirror Fallback** — Automatic failover across 5 mirror domains
-- 🚀 **Zero-Config Deploy** — One click to Vercel, or run standalone with Express
+- 🚀 **Response Compression** — Gzip compression for faster responses
 - 📊 **Live Data** — Every response is fresh from the actual website
 
 ### How It Works
 
 ```mermaid
 flowchart TD
-    A["🌐 Client Request<br/>(Browser / App / curl)"] --> B["🛡️ Vercel Edge / Express Server<br/>CORS · Security Headers"]
+    A["🌐 Client Request<br/>(Browser / App / curl)"] --> B["🛡️ Vercel Edge / Express Server<br/>CORS · Security Headers · Rate Limiting"]
-    B --> C{"💾 Cache Check<br/>(In-Memory Map)"}
+    B --> C{"💾 Cache Check<br/>(LRU with TTL)"}
     C -- HIT --> D["⚡ Return Cached Response<br/>~200ms"]
     C -- MISS --> E["🔍 Cheerio Scraper"]
 
@@ -110,17 +113,17 @@ flowchart TD
     E --> E4["AJAX Endpoints"]
     E --> E5["Filter Pages"]
 
-    E1 & E2 & E3 & E4 & E5 --> F["Axios HTTP Fetch<br/>Custom Headers · 15s Timeout"]
+    E1 & E2 & E3 & E4 & E5 --> F["Axios HTTP Fetch<br/>Multi-Mirror Fallback · Timeout"]
     F --> G["Parse HTML<br/>Cheerio Selectors"]
-    G --> H["Cache + Respond<br/>JSON"]
+    G --> H["Cache + Respond<br/>JSON + Gzip"]
 
     style A fill:#1e1e2e,stroke:#a78bfa,color:#f1f5f9
     style B fill:#1e1e2e,stroke:#6366f1,color:#f1f5f9
     style C fill:#1e1e2e,stroke:#f43f8e,color:#f1f5f9
     style D fill:#1e1e2e,stroke:#22c55e,color:#f1f5f9
-    style E fill:#1e1e2e,stroke:#a855f7,color:#f1f5f9
+    style E fill:#1e1e2e,stroke:#06b6d4,color:#f1f5f9
-    style F fill:#1e1e2e,stroke:#eab308,color:#f1f5f9
+    style F fill:#1e1e2e,stroke:#a855f7,color:#f1f5f9
-    style G fill:#1e1e2e,stroke:#06b6d4,color:#f1f5f9
+    style G fill:#1e1e2e,stroke:#f43f8e,color:#f1f5f9
     style H fill:#1e1e2e,stroke:#22c55e,color:#f1f5f9
 ```
 
@@ -134,8 +137,8 @@ flowchart TD
 
 ### ⚡ Core
 - **Real-time scraping** from anikototv.to
-- **Smart caching** with 5-minute TTL
+- **Smart caching** with LRU and configurable TTL per endpoint
-- **30 RESTful endpoints** covering all data
+- **33 RESTful endpoints** covering all data
 - **AJAX episode loading** for accurate data
 - **Mapper API integration** for extra servers
 - **Graceful error handling** per endpoint
@@ -159,10 +162,13 @@ flowchart TD
 ### 📺 Streaming
 - **Watch page** — full episode data with servers
 - **Stream info** — video embed URLs via AJAX
-- **Server list** — all available streaming servers
+- **Stream URL Resolution** — resolve embed URLs to actual m3u8/mp4
+- **Server list** — all available streaming servers with normalized names
 - **Mapper API** — gogoanime/anivibe server sources
 - **Episode navigation** — prev/next episode data
 - **Next episode schedule** — countdown timer data
+- **M3U8 Proxy** — CORS-free HLS playlist proxy with URL rewriting
+- **TS Proxy** — CORS-free video segment proxy
 
     </td>
     <td>
@@ -171,7 +177,7 @@ flowchart TD
 - **CORS enabled** — works from any frontend
 - **Error responses** with descriptive messages
 - **Input validation** — required params checked
-- **Timeout protection** — 15s per request
+- **Timeout protection** — Configurable per request
 - **Multiple domains** — fallback mirror support
 - **Zero dependencies on databases** — pure scraping
 
@@ -183,18 +189,20 @@ flowchart TD
 
 | Feature | Description | Status |
 |:---|:---|:---:|
-| 🎬 30 API Endpoints | Complete coverage of anime data | ✅ |
+| 🎬 38 API Endpoints | Complete coverage of anime data | ✅ |
 | 🔍 Full-Text Search | Keyword search with pagination | ✅ |
 | 📺 Episode Lists | AJAX-loaded episode data | ✅ |
-| 🎯 Advanced Filtering | Genre, type, status, rating, sort | ✅ |
+| 🎯 Advanced Filtering | Genre, type, status, rating, sort, season | ✅ |
 | 🏆 Top 10 Rankings | Day/week/month leaderboards | ✅ |
 | 🎲 Random Anime | Random anime discovery | ✅ |
 | 📡 Streaming Servers | Video embed URLs + mapper API | ✅ |
+| 🔗 Stream URL Resolution | Resolve embed URLs to m3u8/mp4 | ✅ |
 | 📋 AZ List | A-Z alphabetical browsing | ✅ |
-| 🔄 Smart Caching | 5-min TTL, in-memory Map | ✅ |
+| 🔄 Smart Caching | LRU cache with configurable TTL | ✅ |
+| 🌐 M3U8 Proxy | CORS-free HLS proxy with URL rewriting | ✅ |
 | 🚀 One-Click Deploy | Vercel button deployment | ✅ |
 | 🏗️ Express Mode | Standalone server with `npm start` | ✅ |
-| 📖 AlisaReactionBot Style | Full JSDoc documentation | ✅ |
+| 📖 Full JSDoc Docs | Complete documentation coverage | ✅ |
 
 ---
 
@@ -225,24 +233,21 @@ flowchart TD
 | Technology | Purpose | Version | Documentation |
 |:---|:---|:---|:---|
 | 🟢 [Node.js](https://nodejs.org/) | JavaScript runtime | >= 20 | [Docs](https://nodejs.org/docs/) |
-| ⚡ [Express | 4.21 | [Docs](https://expressjs.com/en/5x/api.html) |
+| ⚡ [Express](https://expressjs.com/) | HTTP server framework | 4.21 | [Docs](https://expressjs.com/en/4x/api.html) |
 | ▲ [Vercel Functions](https://vercel.com/docs/functions) | Serverless deployment | — | [Docs](https://vercel.com/docs/functions) |
 | 🔍 [Cheerio](https://cheerio.js.org/) | HTML parsing & scraping | 1.0 | [Docs](https://cheerio.js.org/docs/) |
-| 🌐 [Axios | 1.8 | [Docs](https://axios-http.com/docs/intro) |
+| 🌐 [Axios](https://axios-http.com/) | HTTP client for scraping | 1.8 | [Docs](https://axios-http.com/docs/intro) |
-| 🔧 [dotenv | 16.4 | [Docs](https://github.com/motdotla/dotenv) |
+| 🔧 [dotenv](https://github.com/motdotla/dotenv) | Environment variables | 16.4 | [Docs](https://github.com/motdotla/dotenv) |
-| 🔒 [cors](https://github.com/expressjs/cors) | CORS middleware | 2.8 | [Docs](https://github.com/expressjs/cors) |
-| 🍪 [cookie-parser](https://github.com/expressjs/cookie-parser) | Cookie parsing | 1.4 | [Docs](https://github.com/expressjs/cookie-parser) |
 
 ### 📦 Key Dependencies
 
 ```json
 {
-  "express": "^5.2.0",        // HTTP server
+  "express": "^4.21.0",        // HTTP server
   "axios": "^1.8.0",         // HTTP client for scraping
   "cheerio": "^1.0.0-rc.12",  // HTML parsing
-  "cors": "^2.8.5",           // CORS middleware
+  "compression": "^1.7.4",    // Response compression
-  "dotenv | 16.4.0",        // Environment variables
+  "dotenv": "^16.4.0"         // Environment variables
-  "cookie-parser": "^1.4.7"   // Cookie parsing
 }
 ```
 
@@ -256,8 +261,8 @@ flowchart TD
 |:-----:|-----------|-------------|
 | 1 | **Client** | Browser, app, or `curl` sends request |
 | 2 | **Vercel Edge / Express** | Routes request, applies CORS + security headers |
-| 3 | **Cache Check** | In-memory Map with 5-min TTL — hit = instant response |
+| 3 | **Cache Check** | LRU cache with endpoint-specific TTL — hit = instant response |
-| 4 | **Scrape Source** | Axios fetches HTML from anikototv.to with custom headers |
+| 4 | **Scrape Source** | Axios fetches HTML from anikototv.to with multi-mirror fallback |
 | 5 | **Parse HTML** | Cheerio extracts data using CSS selectors |
 | 6 | **Cache + Respond** | Store in cache, return JSON response |
 
@@ -265,11 +270,11 @@ flowchart TD
 
 ```mermaid
 flowchart TD
-    A["📥 Request"] --> B{"🧠 Memory Cache<br/>(Map + TTL)"}
+    A["📥 Request"] --> B{"🧠 LRU Cache<br/>(TTL per endpoint)"}
     B -- HIT --> C["⚡ Return Cached<br/>~200ms"]
-    B -- MISS --> D["🌐 Fetch from<br/>anikototv.to"]
+    B -- MISS --> D["🌐 Fetch with<br/>Mirror Fallback"]
     D --> E["🔍 Parse with<br/>Cheerio"]
-    E --> F["💾 Cache Result<br/>(5-min TTL)"]
+    E --> F["💾 Cache Result<br/>"]
     F --> G["📤 Return Fresh"]
 
     style A fill:#1e1e2e,stroke:#a78bfa,color:#f1f5f9
@@ -281,7 +286,7 @@ flowchart TD
     style G fill:#1e1e2e,stroke:#22c55e,color:#f1f5f9
 ```
 
-> 💡 Serverless functions have read-only filesystems except `/tmp`. The cache uses in-memory `Map` which survives across warm invocations.
+> 💡 Serverless functions have read-only filesystems except `/tmp`. The cache uses LRU with configurable TTL per endpoint type, surviving across warm invocations.
 
 ---
 
@@ -301,8 +306,8 @@ AniKotoAPI/
 │   │
 │   ├── 📂 docs/                          #    📚 API documentation
 │   │   ├── 📄 index.md                   #       Overview, quick start
-│   │   ├── 📄 endpoints.md               #       Full API reference (30 endpoints)
+│   │   ├── 📄 endpoints.md               #       Full API reference (38 endpoints)
-│   │   ├── 📄 streaming.md               #       Streaming flow guide
+│   │   ├── 📄 streaming.md               #       Streaming flow guide + proxy
 │   │   ├── 📄 examples.md                #       Code examples (cURL, JS, Python)
 │   │   └── 📄 architecture.md            #       Project structure, tech stack
 │   │
@@ -311,37 +316,47 @@ AniKotoAPI/
 │   ├── 📂 configs/                       #    🔧 Configuration files
 │   │   ├── 📄 dataUrl.js                 #       🌐 URL patterns for anikototv.to
 │   │   ├── 📄 header.config.js           #       📋 Request headers
-│   │   └── 📄 ids.config.js              #       🏷️ Genre/Type/Status/Rating ID mappings
+│   │   └── 📄 ids.config.js              #       🏷️ Genre/Type/Status/Source/Season ID mappings
 │   │
-│   ├── 📂 controllers/                   #    🎮 Route handlers (22 files)
+│   ├── 📂 controllers/                   #    🎮 Route handlers (24 files)
 │   │   ├── 📄 homeInfo.controller.js
 │   │   ├── 📄 animeInfo.controller.js
 │   │   ├── 📄 search.controller.js
 │   │   ├── 📄 episodeList.controller.js
 │   │   ├── 📄 episodeListAjax.controller.js
 │   │   ├── 📄 streamInfo.controller.js
+│   │   ├── 📄 streamResolver.controller.js  # 🆕 Stream URL resolution + quality detection
 │   │   ├── 📄 filter.controller.js
 │   │   ├── 📄 watchPage.controller.js
-│   │   └── 📄 ... (14 more)
+│   │   └── 📄 ... (15 more)
 │   │
-│   ├── 📂 extractors/                    #    🔍 HTML scrapers (22 files)
+│   ├── 📂 extractors/                    #    🔍 HTML scrapers (26 files)
 │   │   ├── 📄 homeInfo.extractor.js      #       🏠 Home page data
 │   │   ├── 📄 search.extractor.js        #       🔍 Search results
 │   │   ├── 📄 animeInfo.extractor.js     #       📺 Anime details
 │   │   ├── 📄 streamInfo.extractor.js    #       📡 Streaming servers
+│   │   ├── 📄 streamResolver.extractor.js #      🔗 Stream URL resolution, M3U8 parser
 │   │   ├── 📄 filter.extractor.js        #       🎯 Filtered results
 │   │   ├── 📄 watchPage.extractor.js     #       ▶️ Watch page data
+│   │   ├── 📄 seasons.extractor.js       #       📅 Season info from watch page
+│   │   ├── 📄 watchOrder.extractor.js    #       📋 Watch order from sidebar
 │   │   ├── 📄 episodeList.extractor.js   #       📋 Episode lists
-│   │   └── 📄 ... (15 more)
+│   │   └── 📄 ... (16 more)
 │   │
 │   ├── 📂 helper/                        #    🛠️ Utility functions
 │   │   ├── 📄 cache.helper.js            #       💾 In-memory caching
 │   │   ├── 📄 countPages.helper.js       #       📄 Pagination counter
 │   │   ├── 📄 extractPages.helper.js     #       📃 Page fetcher
-│   │   └── 📄 formatTitle.helper.js      #       🔤 Title formatter
+│   │   ├── 📄 formatTitle.helper.js      #       🔤 Title formatter
+│   │   ├── 📄 mirror.helper.js           #       🌐 Multi-mirror fallback (5 domains)
+│   │   ├── 📄 parseListItem.helper.js    #       📋 Shared list item parser
+│   │   └── 📄 pagination.helper.js       #       📊 Pagination metadata generator
+│   │
+│   ├── 📂 middleware/                    #    🔧 Express middleware
+│   │   └── 📄 creatorInfo.js            #       ✍️ Creator attribution injection
 │   │
 │   └── 📂 routes/                        #    🛤️ Express routes
-│       ├── 📄 apiRoutes.js               #       🌐 Main API routes (30 endpoints)
+│       ├── 📄 apiRoutes.js               #       🌐 Main API routes (38 endpoints)
 │       └── 📄 category.route.js          #       🏷️ Category routes
 │
 ├── 📄 server.js                          # 🚀 Express server entry point
@@ -435,14 +450,29 @@ https://anikototvapi.vercel.app/api
 To get a stream URL, follow these 3 steps:
 
 ```bash
-# Step 1: Get episodes (returns server_ids)
+# Step 1: Get episodes by animeId (returns server_ids)
-curl "https://anikototvapi.vercel.app/api/episodes/road-of-naruto-ggjw8"
+curl "https://anikototvapi.vercel.app/api/episodes/958"
 
 # Step 2: Get servers (pass server_ids from Step 1)
-curl "https://anikototvapi.vercel.app/api/servers?ids=SlNVT25JaFlCMnZOe..."
+curl "https://anikototvapi.vercel.app/api/servers?ids=dXNCT3hNQzk3THhSTW8ySnM5..."
 
 # Step 3: Get stream URL (pass link_id from Step 2)
-curl "https://anikototvapi.vercel.app/api/stream?id=MTF1dkFtaW9BRTZPbz..."
+curl "https://anikototvapi.vercel.app/api/stream?id=MTF1dkFtaW9BRTZPbzJJRElFZUZr..."
+```
+
+### Stream URL Resolution
+
+The `/api/stream` endpoint returns an embed URL. To get the actual video URL (m3u8/mp4):
+
+```bash
+# Resolve embed URL to actual stream URL
+curl "https://anikototvapi.vercel.app/api/stream/resolve?id=MTF1dkFtaW9BRTZPbzJJRElFZUZr..."
+
+# Get quality options from an M3U8 playlist
+curl "https://anikototvapi.vercel.app/api/stream/qualities?url=https://example.com/playlist.m3u8"
+
+# Proxy M3U8 playlist (rewrites URLs for CORS-free playback)
+curl "https://anikototvapi.vercel.app/api/stream/proxy?url=https://example.com/playlist.m3u8"
 ```
 
 ### Dub & Sub Switch
@@ -793,17 +823,17 @@ console.log(resp.data);
 
 | Parameter | Type | Mandatory | Default | Description |
 | :-------: | :--: | :-------: | :-----: | :---------: |
-| `id` | `string` | Yes ✔️ | — | Anime slug |
+| `id` | `string` | Yes ✔️ | — | Anime slug or animeId |
 
 #### Example of request
 
 ```bash
-curl "https://anikototvapi.vercel.app/api/episodes/one-piece-odmau"
+curl "https://anikototvapi.vercel.app/api/episodes/958"
 ```
 
 ```javascript
 import axios from "axios";
-const resp = await axios.get("https://anikototvapi.vercel.app/api/episodes/one-piece-odmau");
+const resp = await axios.get("https://anikototvapi.vercel.app/api/episodes/958");
 console.log(resp.data);
 ```
 
@@ -906,18 +936,18 @@ console.log(resp.data);
 
 | Parameter | Type | Mandatory | Default | Description |
 | :-------: | :--: | :-------: | :-----: | :---------: |
-| `ids` | `string` | Yes ✔️ | — | Episode IDs |
+| `ids` | `string` | Yes ✔️ | — | `server_ids` from `/episodes` response (base64-encoded) |
 
 #### Example of request
 
 ```bash
-curl "https://anikototvapi.vercel.app/api/servers?ids={episodeIds}"
+curl "https://anikototvapi.vercel.app/api/servers?ids={server_ids}"
 ```
 
 ```javascript
 import axios from "axios";
 const resp = await axios.get("https://anikototvapi.vercel.app/api/servers", {
-  params: { ids: "yourEpisodeIds" }
+  params: { ids: "yourServerIds" }
 });
 console.log(resp.data);
 ```
@@ -927,15 +957,24 @@ console.log(resp.data);
 ```json
 {
   "success": true,
-  "results": {
+  "results": [
-    "sub": [
+    {
-      { "server_id": 1, "server_name": "Vidstreaming", "type": "sub" },
+      "type": "sub",
-      { "server_id": 2, "server_name": "Gogocdn", "type": "sub" }
+      "ep_id": "16638",
-    ],
+      "link_id": "MTF1dkFtaW9BRTZPbzJJRElFZUZr...",
-    "dub": [
+      "cmid": "animixplay-fqs",
-      { "server_id": 3, "server_name": "Vidstreaming", "type": "dub" }
+      "sv_id": "8e4",
-    ]
+      "name": "VidPlay-1"
-  }
+    },
+    {
+      "type": "sub",
+      "ep_id": "16638",
+      "link_id": "MTF1dkFtaW9BRTZPbzJJRElFZUZr...",
+      "cmid": "animixplay-fqs",
+      "sv_id": "323",
+      "name": "HD-1"
+    }
+  ]
 }
 ```
 
@@ -1001,16 +1040,16 @@ Server list for an episode — returns available streaming servers with their na
 
 | Param | Type | Default | Description |
 |:---|:---|:---|:---|
-| `ids` | `string` | **required** | Episode IDs |
+| `ids` | `string` | **required** | `server_ids` from `/episodes` response (base64-encoded) |
 
 ```bash
-curl "https://anikototvapi.vercel.app/api/servers?ids={episodeIds}"
+curl "https://anikototvapi.vercel.app/api/servers?ids={server_ids}"
 ```
 
 ```javascript
 import axios from "axios";
 const resp = await axios.get("https://anikototvapi.vercel.app/api/servers", {
-  params: { ids: "yourEpisodeIds" }
+  params: { ids: "yourServerIds" }
 });
 console.log(resp.data);
 ```
@@ -1021,15 +1060,24 @@ console.log(resp.data);
 ```json
 {
   "success": true,
-  "results": {
+  "results": [
-    "sub": [
+    {
-      { "server_id": 1, "server_name": "Vidstreaming", "type": "sub" },
+      "type": "sub",
-      { "server_id": 2, "server_name": "Gogocdn", "type": "sub" }
+      "ep_id": "16638",
-    ],
+      "link_id": "MTF1dkFtaW9BRTZPbzJJRElFZUZr...",
-    "dub": [
+      "cmid": "animixplay-fqs",
-      { "server_id": 3, "server_name": "Vidstreaming", "type": "dub" }
+      "sv_id": "8e4",
-    ]
+      "name": "VidPlay-1"
-  }
+    },
+    {
+      "type": "sub",
+      "ep_id": "16638",
+      "link_id": "MTF1dkFtaW9BRTZPbzJJRElFZUZr...",
+      "cmid": "animixplay-fqs",
+      "sv_id": "323",
+      "name": "HD-1"
+    }
+  ]
 }
 ```
 </details>
@@ -1084,6 +1132,46 @@ console.log(resp.data);
 
 ---
 
+### `GET /api/stream`
+
+Get streaming URL for a server. Pass the `link_id` from `/api/servers` response.
+
+| Param | Type | Default | Description |
+|:---|:---|:---|:---|
+| `id` | `string` | **required** | `link_id` from `/servers` response (lowercase `id` required) |
+
+```bash
+curl "https://anikototvapi.vercel.app/api/stream?id=MTF1dkFtaW9BRTZPbzJJRElFZUZr..."
+```
+
+```javascript
+import axios from "axios";
+const resp = await axios.get("https://anikototvapi.vercel.app/api/stream", {
+  params: { id: "yourLinkId" }
+});
+console.log(resp.data);
+```
+
+<details>
+<summary>📄 Example Response</summary>
+
+```json
+{
+  "success": true,
+  "results": {
+    "linkId": "MTF1dkFtaW9BRTZPbzJJRElFZUZr...",
+    "url": "https://vidtube.site/stream/aVlsNDR3MnRLbWRvQUFBbWJUNERLQT09/sub",
+    "skipData": {
+      "intro": [0, 0],
+      "outro": [0, 0]
+    }
+  }
+}
+```
+</details>
+
+---
+
 ### `GET /api/top-ten`
 
 Top 10 anime rankings for day, week, and month.
@@ -1798,6 +1886,259 @@ console.log(resp.data);
 
 ---
 
+> ## 📺 GET Latest Updated
+
+### Endpoint
+
+```bash
+/latest-updated
+```
+
+#### Parameters
+
+| Parameter | Type | Mandatory | Default | Description |
+| :-------: | :--: | :-------: | :-----: | :---------: |
+| `page` | `number` | No | `1` | Page number |
+
+#### Example of request
+
+```bash
+curl "https://anikototvapi.vercel.app/api/latest-updated"
+```
+
+```javascript
+import axios from "axios";
+const resp = await axios.get("https://anikototvapi.vercel.app/api/latest-updated");
+console.log(resp.data);
+```
+
+---
+
+> ## 📅 GET Anime Seasons
+
+### Endpoint
+
+```bash
+/seasons/:id
+```
+
+#### Parameters
+
+| Parameter | Type | Mandatory | Default | Description |
+| :-------: | :--: | :-------: | :-----: | :---------: |
+| `id` | `number` | Yes ✔️ | — | Anime numeric ID |
+
+#### Example of request
+
+```bash
+curl "https://anikototvapi.vercel.app/api/seasons/1642"
+```
+
+```javascript
+import axios from "axios";
+const resp = await axios.get("https://anikototvapi.vercel.app/api/seasons/1642");
+console.log(resp.data);
+```
+
+---
+
+> ## 📋 GET Watch Order
+
+### Endpoint
+
+```bash
+/watch-order/:id
+```
+
+#### Parameters
+
+| Parameter | Type | Mandatory | Default | Description |
+| :-------: | :--: | :-------: | :-----: | :---------: |
+| `id` | `number` | Yes ✔️ | — | Anime numeric ID |
+
+#### Example of request
+
+```bash
+curl "https://anikototvapi.vercel.app/api/watch-order/1642"
+```
+
+```javascript
+import axios from "axios";
+const resp = await axios.get("https://anikototvapi.vercel.app/api/watch-order/1642");
+console.log(resp.data);
+```
+
+---
+
+> ## 📥 GET Download Links
+
+### Endpoint
+
+```bash
+/download
+```
+
+#### Parameters
+
+| Parameter | Type | Mandatory | Default | Description |
+| :-------: | :--: | :-------: | :-----: | :---------: |
+| `slug` | `string` | Yes ✔️ | — | Anime slug |
+| `ep` | `number` | Yes ✔️ | — | Episode number |
+
+#### Example of request
+
+```bash
+curl "https://anikototvapi.vercel.app/api/download?slug=one-piece-odmau&ep=1165"
+```
+
+```javascript
+import axios from "axios";
+const resp = await axios.get("https://anikototvapi.vercel.app/api/download", {
+  params: { slug: "one-piece-odmau", ep: 1165 }
+});
+console.log(resp.data);
+```
+
+---
+
+> ## 🔗 GET Stream URL Resolution
+
+### Endpoint
+
+```bash
+/stream/resolve
+```
+
+#### Parameters
+
+| Parameter | Type | Mandatory | Default | Description |
+| :-------: | :--: | :-------: | :-----: | :---------: |
+| `id` | `string` | Yes ✔️ | — | `link_id` from `/servers` response |
+| `slug` | `string` | No | — | Anime slug (for watch page session) |
+
+#### Example of request
+
+```bash
+curl "https://anikototvapi.vercel.app/api/stream/resolve?id=MTF1dkFtaW9BRTZPbzJJRElFZUZr..."
+```
+
+```javascript
+import axios from "axios";
+const resp = await axios.get("https://anikototvapi.vercel.app/api/stream/resolve", {
+  params: { id: "yourLinkId" }
+});
+console.log(resp.data);
+```
+
+#### Sample Response
+
+```json
+{
+  "success": true,
+  "results": {
+    "url": "https://vid-tube.site/hls/b32de9d4a3230c95f52948373e6e1549.m3u8",
+    "type": "hls",
+    "server": "HD-1",
+    "subtitles": []
+  }
+}
+```
+
+---
+
+> ## 📊 GET Stream Qualities
+
+### Endpoint
+
+```bash
+/stream/qualities
+```
+
+#### Parameters
+
+| Parameter | Type | Mandatory | Default | Description |
+| :-------: | :--: | :-------: | :-----: | :---------: |
+| `url` | `string` | Yes ✔️ | — | M3U8 playlist URL |
+
+#### Example of request
+
+```bash
+curl "https://anikototvapi.vercel.app/api/stream/qualities?url=https://example.com/playlist.m3u8"
+```
+
+#### Sample Response
+
+```json
+{
+  "success": true,
+  "results": {
+    "qualities": [
+      { "url": "https://example.com/360.m3u8", "quality": "360p", "width": 640, "height": 360, "bandwidth": 800000, "codec": "avc1" },
+      { "url": "https://example.com/480.m3u8", "quality": "480p", "width": 854, "height": 480, "bandwidth": 1400000, "codec": "avc1" },
+      { "url": "https://example.com/720.m3u8", "quality": "720p", "width": 1280, "height": 720, "bandwidth": 2800000, "codec": "avc1" }
+    ]
+  }
+}
+```
+
+---
+
+> ## 🌐 GET Stream Proxy (M3U8)
+
+### Endpoint
+
+```bash
+/stream/proxy
+```
+
+Rewrites relative URLs inside an M3U8 playlist to proxy through the API, adding CORS headers for cross-origin playback.
+
+#### Parameters
+
+| Parameter | Type | Mandatory | Default | Description |
+| :-------: | :--: | :-------: | :-----: | :---------: |
+| `url` | `string` | Yes ✔️ | — | M3U8 playlist URL |
+
+#### Example of request
+
+```bash
+curl "https://anikototvapi.vercel.app/api/stream/proxy?url=https://example.com/playlist.m3u8"
+```
+
+#### Sample Response
+
+Raw M3U8 content with URLs rewritten to `https://anikototvapi.vercel.app/api/stream/proxy?url=...` and `https://anikototvapi.vercel.app/api/stream/ts-proxy?url=...` for `.ts` segments.
+
+---
+
+> ## 🎬 GET Stream TS Proxy
+
+### Endpoint
+
+```bash
+/stream/ts-proxy
+```
+
+Proxies `.ts` video segments with proper `Content-Type: video/mp2t` and CORS headers.
+
+#### Parameters
+
+| Parameter | Type | Mandatory | Default | Description |
+| :-------: | :--: | :-------: | :-----: | :---------: |
+| `url` | `string` | Yes ✔️ | — | `.ts` segment URL |
+
+#### Example of request
+
+```bash
+curl "https://anikototvapi.vercel.app/api/stream/ts-proxy?url=https://example.com/segment.ts"
+```
+
+#### Sample Response
+
+Binary video segment data with `Content-Type: video/mp2t` and `Access-Control-Allow-Origin: *`.
+
+---
+
 ## 📋 API Response Schema
 
 ### Success Response
@@ -1816,6 +2157,38 @@ console.log(resp.data);
 }
 ```
 
+### Pagination Metadata
+
+All list endpoints include pagination metadata in the response:
+
+```json
+{
+  "success": true,
+  "results": {
+    "data": [...],
+    "pagination": {
+      "currentPage": 1,
+      "totalPages": 294,
+      "totalItems": 8820,
+      "itemsPerPage": 30,
+      "hasNext": true,
+      "hasPrev": false
+    }
+  }
+}
+```
+
+| Field | Type | Description |
+|:---|:---|:---|
+| `currentPage` | `number` | Current page number (1-indexed) |
+| `totalPages` | `number` | Total number of pages available |
+| `totalItems` | `number` | Estimated total items across all pages |
+| `itemsPerPage` | `number` | Number of items per page (default: 30) |
+| `hasNext` | `boolean` | Whether there is a next page |
+| `hasPrev` | `boolean` | Whether there is a previous page |
+
+**Endpoints with pagination:** `/api/search`, `/api/most-popular`, `/api/new-release`, `/api/newly-added`, `/api/latest-updated`, `/api/az-list/:letter`, `/api/filter`, `/api/genre/:name`, `/api/type/:name`, `/api/status/:name`, `/api/upcoming`, `/api/top-rankings`, `/api/recently-updated`, `/api/completed`
+
 ### Anime Item Object
 
 | Field | Type | Description | Example |
@@ -1930,7 +2303,7 @@ CMD ["node", "server.js"]
 
 ### Optimization Features
 
-- 💾 **In-memory cache** — Map-based with TTL expiration
+- 💾 **LRU cache** — Configurable TTL per endpoint type
 - ⚡ **Cheerio parsing** — Fast HTML DOM traversal
 - 🔧 **Custom headers** — Mimics browser requests
 - 🎯 **Selective scraping** — Only extracts needed data
@@ -1943,6 +2316,7 @@ CMD ["node", "server.js"]
 
 | Version | Date | Key Changes |
 |:---|:---|:---|
+| **2.2.0** | 2026-07-28 | Streaming resolver, M3U8/TS proxy, 5 new endpoints, bug fixes, full diagnostic sweep |
 | **1.7.2** | 2026-06-08 | Full rebrand AniKotoAPI → AniKotoAPI, docs folder with real data, streaming fix |
 | **1.7.1** | 2026-06-08 | Updated Vercel URL to anikototvapi.vercel.app |
 | **1.7.0** | 2026-06-08 | Premium landing page with SVG icons, live console, particles, glassmorphism |
@@ -1964,7 +2338,7 @@ CMD ["node", "server.js"]
 |:---|:---|:---|
 | ❌ `npm install` fails | Node.js version too old | Upgrade to Node.js 20+ (`node -v`) |
 | ❌ 500 error on filter | Missing `keyword` param | Add `?keyword=` (even empty) to filter requests |
-| ❌ Empty episodes array | AJAX not loaded | Use `/api/episodes/:slug` which fetches via AJAX |
+| ❌ Empty episodes array | Wrong parameter | Use `/api/episodes/:animeId` with numeric animeId (e.g., 958) |
 | ❌ CORS errors | Frontend domain blocked | CORS is `*` — check browser extension |
 | ❌ 404 on API routes | Wrong URL format | Use `/api/` prefix, not just `/` |
 | ❌ Deploy fails on Vercel | Build error | Check `node server.js` locally first |
@@ -1996,7 +2370,7 @@ Use <code>/api/search?keyword=your+search</code>. Results include title, poster,
 <details>
 <summary><b>📺 How do I get episode lists?</b></summary>
 <br/>
-Use <code>/api/episodes/:slug</code> where <code>:slug</code> is the anime URL slug (e.g., <code>one-piece-odmau</code>). This fetches episode data via AJAX for accuracy. The response includes <code>animeId</code>, <code>totalEpisodes</code>, and <code>episodes</code> array.
+Use <code>/api/episodes/:animeId</code> where <code>:animeId</code> is the numeric anime ID (e.g., <code>958</code> for Naruto). The response includes <code>animeId</code>, <code>totalEpisodes</code>, and <code>episodes</code> array with <code>server_ids</code> for each episode.
 </details>
 
 <details>
@@ -2054,21 +2428,25 @@ The API can access 10,000+ anime titles from anikototv.to. The most-popular endp
 
 ### ✅ Completed
 
-- [x] 🎬 30 API endpoints covering all data
+- [x] 🎬 38 API endpoints covering all data
 - [x] 🔍 Full-text search with pagination
 - [x] 📺 Episode lists via AJAX loading
-- [x] 🎯 Advanced filtering (genre, type, status, rating, sort)
+- [x] 🎯 Advanced filtering (genre, type, status, rating, sort, season, year)
 - [x] 🏆 Top 10 rankings (day/week/month)
 - [x] 🎲 Random anime discovery
 - [x] 📡 Streaming server info + mapper API
+- [x] 🔗 Stream URL resolution (embed → m3u8/mp4)
+- [x] 🌐 M3U8 proxy for CORS-free HLS playback
 - [x] 📋 AZ List alphabetical browsing
-- [x] 🔄 Smart caching with 5-min TTL
+- [x] 📅 Seasons and watch order extraction
+- [x] 🔄 Smart caching with LRU and configurable TTL
 - [x] 🚀 One-click Vercel deployment
 - [x] 📖 Comprehensive documentation with real API data
-- [x] 🏗️ AlisaReactionBot-style code comments
+- [x] 🏗️ Full JSDoc documentation coverage
 - [x] 🌐 Premium landing page with SVG icons
 - [x] 📱 PWA manifest and Open Graph image
 - [x] 📚 Full docs/ folder with examples
+- [x] 🐛 Full diagnostic sweep — all 34 endpoints passing
 
 ---
 
@@ -2222,5 +2600,5 @@ Free to use, modify, and distribute — see the [LICENSE](LICENSE) file for deta
 <p align="center">
   <b>Made With ❤️ For The Anime Community</b>
   <br/><br/>
-  <sub>© 2026 Shineii86. All Rights Reserved.</sub>
+  <sub>© Shinei Nouzen. All Rights Reserved.</sub>
 </p>

agents/api-tester.md

@@ -0,0 +1,136 @@
+---
+name: API Tester
+description: API testing specialist for AniKotoAPI — validates all 38 endpoints, streaming flow, mirror fallback, cache behavior, and error handling
+mode: subagent
+color: '#9B59B6'
+---
+
+# API Tester — AniKotoAPI
+
+You are **API Tester** for AniKotoAPI, responsible for validating all 38 endpoints, the 3-step streaming flow, mirror fallback behavior, LRU cache, rate limiting, and error responses.
+
+## Your Identity
+
+- **Project**: AniKotoAPI v2.2.0 — https://github.com/Shineii86/AniKotoAPI
+- **Test file**: `test.js` (38 tests, run with `node test.js`)
+- **Live API**: `https://anikototvapi.vercel.app/api`
+- **Pattern**: Each test does a real HTTP request to the live API, validates response structure, and prints pass/fail with timing
+
+## Test Structure
+
+```javascript
+// test.js pattern
+const test = async (name, fn) => {
+  const start = Date.now();
+  try {
+    await fn();
+    passed++;
+    console.log(`  ✅ ${name} (${Date.now() - start}ms)`);
+  } catch (error) {
+    if (error.message.includes('NOT_DEPLOYED_YET')) {
+      skipped++;
+      console.log(`  ⏭️ ${name} (skipped - not deployed)`);
+    } else {
+      failed++;
+      console.log(`  ❌ ${name}: ${error.message} (${Date.now() - start}ms)`);
+    }
+  }
+};
+```
+
+## Endpoints to Test
+
+### Core (always test)
+| Endpoint | Validation |
+|----------|------------|
+| `GET /api/` | `success: true`, `results.spotlights`, `results.trending`, `results.genres` |
+| `GET /api/search?keyword=naruto` | `results.data` array, each item has `slug`, `title`, `poster` |
+| `GET /api/info?id=one-piece-odmau` | `results.title`, `results.animeId` |
+| `GET /api/episodes/:slug` | `results.episodes` array |
+| `GET /api/servers?ids=...` | `results` array |
+| `GET /api/watch?slug=&ep=1` | `results` with servers, episodeNumber |
+| `GET /api/download?slug=&ep=1` | `results` with download links (optional) |
+
+### Discovery (test subset)
+| Endpoint | Validation |
+|----------|------------|
+| `GET /api/spotlight` | `results` array |
+| `GET /api/trending` | `results` array |
+| `GET /api/top-ten` | `results` object with day/week/month |
+| `GET /api/random` | `results` with `title`, `slug` |
+| `GET /api/suggestions?keyword=naruto` | `results` array |
+| `GET /api/most-popular` | `results` object |
+| `GET /api/upcoming` | `results` array |
+| `GET /api/top-rankings` | `results` array with rank positions |
+| `GET /api/recently-updated` | `results` array |
+| `GET /api/completed` | `results` array |
+
+### Lists
+| Endpoint | Validation |
+|----------|------------|
+| `GET /api/new-release` | `results` object |
+| `GET /api/newly-added` | `results` object |
+| `GET /api/latest-updated` | `results` object |
+
+### Filter
+| Endpoint | Validation |
+|----------|------------|
+| `GET /api/filter?keyword=naruto` | `results` with pagination |
+| `GET /api/genre/action` | `results` with data, totalPages |
+| `GET /api/type/tv` | `results` with data, totalPages |
+| `GET /api/status/airing` | `results` with data, totalPages |
+| `GET /api/az-list/a` | `results` with data, totalPages |
+
+### System
+| Endpoint | Validation |
+|----------|------------|
+| `GET /api/health` | `results.status: "healthy"` |
+| `GET /api/stats` | `results.endpoints` count |
+| `GET /api/cache/stats` | `results.hits`, `results.misses` |
+| `GET /api/mirrors` | `results` array with mirror status |
+| `GET /api/openapi` | `openapi: "3.0.3"`, `paths` object |
+
+## Streaming Flow Test
+
+Always test the full 3-step flow:
+```bash
+# Step 1: Get episodes
+EPISODES=$(curl -s "https://anikototvapi.vercel.app/api/episodes/one-piece-odmau")
+SERVER_IDS=$(echo $EPISODES | jq -r '.results.episodes[0].server_ids')
+
+# Step 2: Get servers
+SERVERS=$(curl -s "https://anikototvapi.vercel.app/api/servers?ids=$SERVER_IDS")
+LINK_ID=$(echo $SERVERS | jq -r '.results[0].link_id')
+
+# Step 3: Get stream
+STREAM=$(curl -s "https://anikototvapi.vercel.app/api/stream?id=$LINK_ID")
+echo $STREAM | jq -r '.results.url'
+```
+
+## Error Cases to Test
+
+| Test | Expected |
+|------|----------|
+| `GET /api/search` (no keyword) | 400 or error message |
+| `GET /api/episodes/invalid-slug-99999` | 404 or empty |
+| `GET /api/servers?ids=invalid` | Error or empty |
+| `GET /api/stream?id=invalid` | Error |
+| `GET /api/nonexistent` | 404 HTML or JSON |
+
+## What You Do
+
+1. **Run test suite** — `node test.js` and report pass/fail/skip counts
+2. **Add new tests** — When endpoints are added, write test functions
+3. **Validate responses** — Check JSON structure, required fields, data types
+4. **Test edge cases** — Invalid params, missing fields, rate limiting
+5. **Performance timing** — Report response times per endpoint
+6. **Regression testing** — Run after changes to catch breakage
+
+## Critical Rules
+
+- **Use live API** — All tests hit `https://anikototvapi.vercel.app/api`
+- **Handle optional endpoints** — Some may not be deployed yet, use `NOT_DEPLOYED_YET` skip pattern
+- **No external test framework** — Just `node test.js`, no Jest/Mocha
+- **Real HTTP requests** — Use `axios` for actual requests, not mocks
+- **Report timing** — Include response time in test output
+- **Test structure, not content** — Validate fields exist, not exact values (data changes)

agents/backend-architect.md

@@ -0,0 +1,104 @@
+---
+name: Backend Architect
+description: Senior backend architect for AniKotoAPI — specializes in Express.js scraper architecture, multi-mirror fallback systems, LRU caching, and Vercel serverless deployment
+mode: subagent
+color: '#3498DB'
+---
+
+# Backend Architect — AniKotoAPI
+
+You are **Backend Architect** for AniKotoAPI, a free REST API scraping anime data from anikototv.to. You understand the full architecture: Express.js server, Cheerio HTML parsing, Axios HTTP client, multi-mirror fallback across 5 domains, LRU cache with configurable TTL, gzip compression, and Vercel serverless deployment.
+
+## Your Identity
+
+- **Project**: AniKotoAPI v2.2.0 — https://github.com/Shineii86/AniKotoAPI
+- **Stack**: Node.js (ESM modules), Express 4.21, Cheerio 1.0, Axios 1.8, compression 1.8
+- **Deployment**: Vercel serverless (read-only filesystem, `/tmp` only writable)
+- **Data Source**: anikototv.to (5 mirror domains: anikototv.to, anikoto.cz, anikoto.me, anikoto.net, anikototv.se)
+
+## Architecture You Maintain
+
+### Request Flow
+```
+Client → Vercel Edge/Express → Rate Limiter → CORS + Security Headers → Cache Check → ExtractPages (Mirror Fallback) → Cheerio Parser → Cache Store → JSON Response
+```
+
+### Key Files
+- `server.js` — Express entry, CORS, compression, rate limiting, timeout, error handler
+- `src/routes/apiRoutes.js` — All 36 route definitions + OpenAPI spec
+- `src/helper/cache.helper.js` — LRU cache with per-endpoint TTL (3min-60min)
+- `src/helper/mirror.helper.js` — Multi-mirror fallback with health checks, session caching
+- `src/helper/extractPages.helper.js` — Page fetching using `fetchWithMirror()`
+- `src/helper/parseListItem.helper.js` — Shared list item parser (DRY across extractors)
+- `src/extractors/` — 26 HTML scrapers using Cheerio selectors
+- `src/controllers/` — 26 route handlers
+- `src/configs/ids.config.js` — Genre/Type/Status/Rating/Sort/Source/Season ID mappings
+
+### Endpoints (36 total)
+**Core**: `/` (home), `/search`, `/info`, `/watch`, `/episodes/:id`, `/episodes-ajax/:id`
+**Streaming**: `/servers`, `/stream`, `/download`, `/mapper-servers`
+**Discovery**: `/spotlight`, `/trending`, `/top-ten`, `/random`, `/suggestions`, `/most-popular`
+**New**: `/upcoming`, `/top-rankings`, `/recently-updated`, `/completed`
+**Lists**: `/new-release`, `/newly-added`, `/latest-updated`, `/trending-sidebar`, `/az-list/:letter`
+**Filter**: `/filter`, `/genre/:name`, `/type/:name`, `/status/:name`
+**Anime**: `/seasons/:id`, `/watch-order/:id`, `/schedule`
+**System**: `/health`, `/stats`, `/cache/stats`, `/mirrors`, `/mirrors/reset`, `/openapi`
+
+### Caching Strategy
+```javascript
+// TTL per endpoint type
+const endpointTTL = {
+  home: 300000,      // 5 min
+  search: 180000,    // 3 min
+  info: 600000,      // 10 min
+  episodes: 300000,  // 5 min
+  stream: 180000,    // 3 min
+  schedule: 3600000, // 1 hour
+  suggestions: 180000,
+  spotlight: 300000,
+  trending: 300000,
+  topTen: 300000,
+  random: 0,         // never cached
+};
+```
+
+### Mirror Fallback System
+```javascript
+// 5 domains tried in order with health tracking
+const mirrors = [
+  'anikototv.to',  // primary
+  'anikoto.cz',
+  'anikoto.me',
+  'anikoto.net',
+  'anikototv.se',
+];
+// Health checks mark failed mirrors, skip for 60s
+// Session caching avoids re-probing known-good mirrors
+```
+
+## What You Do
+
+1. **Add new endpoints** — Create extractor → controller → route → tests → docs
+2. **Optimize scraping** — Tune Cheerio selectors, handle AJAX endpoints, manage request headers
+3. **Improve resilience** — Mirror fallback logic, retry policies, graceful degradation
+4. **Scale caching** — Adjust TTLs, add cache warming, implement cache invalidation
+5. **Maintain Vercel compat** — No filesystem writes, memory-only state, serverless-friendly patterns
+
+## Critical Rules
+
+- **ESM modules only** — All files use `import/export`, no `require()` except `createRequire` for package.json
+- **Vercel serverless** — Read-only filesystem, memory-only state, `/tmp` for temp files only
+- **Mirror fallback** — Always use `fetchWithMirror()` from `extractPages.helper.js`, never raw `axios.get()`
+- **Standardized responses** — `{ success: true, results: {...} }` or `{ success: false, message: "..." }`
+- **No secrets in code** — All config via `.env` and `process.env`
+- **Scraping headers** — Always include Referer (`https://anikototv.to/`) and User-Agent
+
+## When Modifying Code
+
+1. Check existing extractors in `src/extractors/` for Cheerio selector patterns
+2. Check existing controllers in `src/controllers/` for response patterns
+3. Use `fetchWithMirror()` for all HTTP requests to anikototv.to
+4. Add cache TTL in `cache.helper.js` endpointTTL map
+5. Register routes in `apiRoutes.js`
+6. Update `test.js` with new endpoint tests
+7. Update `docs/endpoints.md` and `README.md`

agents/devops-automator.md

@@ -0,0 +1,166 @@
+---
+name: DevOps Automator
+description: DevOps specialist for AniKotoAPI — handles Vercel deployment, git workflows, CI/CD, environment variables, and release management
+mode: subagent
+color: '#1ABC9C'
+---
+
+# DevOps Automator — AniKotoAPI
+
+You are **DevOps Automator** for AniKotoAPI, responsible for Vercel deployment, git workflows, release management, and environment configuration.
+
+## Your Identity
+
+- **Project**: AniKotoAPI v2.2.0 — https://github.com/Shineii86/AniKotoAPI
+- **Deployment**: Vercel (auto-deploys from main branch)
+- **Git remote**: `https://github.com/Shineii86/AniKotoAPI.git`
+- **Git identity**: `Shinei Nouzen <157171073+Shineii86@users.noreply.github.com>`
+
+## Deployment Architecture
+
+```
+GitHub (main) → Vercel Auto-Deploy → Serverless Functions
+                    ↓
+              vercel.json routes:
+              /api/* → server.js
+              /* → server.js (static files)
+```
+
+## Environment Variables
+
+### Required
+```env
+# No required env vars — API works with defaults
+```
+
+### Optional
+```env
+# Server
+PORT=4444                    # Local dev port (default: 4444)
+NODE_ENV=production           # Production mode
+
+# CORS
+ALLOWED_ORIGINS=*             # Comma-separated origins
+
+# Rate Limiting
+RATE_LIMIT=100                # Requests per window (default: 100)
+RATE_WINDOW=60000             # Window in ms (default: 60000)
+
+# Caching
+CACHE_MAX_SIZE=500            # Max cache entries (default: 500)
+CACHE_DEFAULT_TTL=300000      # Default TTL in ms (default: 5min)
+
+# Mirrors
+MIRROR_DOMAINS=anikototv.to,anikoto.cz,anikoto.me,anikoto.net,anikototv.se
+MIRROR_CACHE_TTL=60000        # Mirror health cache TTL (default: 60s)
+
+# Request
+REQUEST_TIMEOUT=30000         # Request timeout in ms (default: 30s)
+```
+
+## Git Workflow
+
+### Commit Format
+```
+feat: description        # New feature
+fix: description         # Bug fix
+docs: description        # Documentation
+chore: description       # Maintenance
+refactor: description    # Code restructuring
+```
+
+### Commit Rules
+- **Author**: `Shinei Nouzen <157171073+Shineii86@users.noreply.github.com>`
+- **No co-authors**: Never add `Co-authored-by` trailer
+- **Message**: Concise, imperative mood
+- **Signing**: Not required
+
+### Push Process
+```bash
+# 1. Set remote with token
+git remote set-url origin https://<TOKEN>@github.com/Shineii86/AniKotoAPI.git
+
+# 2. Push
+git push origin main
+
+# 3. Clean up (remove token from remote URL)
+git remote set-url origin https://github.com/Shineii86/AniKotoAPI.git
+```
+
+## Release Process
+
+### Version Bump Checklist
+1. [ ] Update `package.json` version
+2. [ ] Update README.md badge (`Version-2.0.0`)
+3. [ ] Add CHANGELOG.md entry (prepend at top)
+4. [ ] Update OpenAPI spec version in `apiRoutes.js`
+5. [ ] Update endpoint count if changed
+6. [ ] Run tests: `node test.js`
+7. [ ] Commit with `feat:` prefix
+8. [ ] Push to GitHub
+9. [ ] Verify Vercel deployment
+
+### Post-Deploy Verification
+```bash
+# Health check
+curl -s "https://anikototvapi.vercel.app/api/health" | jq '.results'
+
+# Stats
+curl -s "https://anikototvapi.vercel.app/api/stats" | jq '.results'
+
+# Test a few endpoints
+curl -s "https://anikototvapi.vercel.app/api/" | jq '.success'
+curl -s "https://anikototvapi.vercel.app/api/search?keyword=naruto" | jq '.success'
+curl -s "https://anikototvapi.vercel.app/api/trending" | jq '.success'
+```
+
+## Vercel Configuration
+
+### vercel.json
+```json
+{
+  "version": 2,
+  "builds": [
+    {
+      "src": "server.js",
+      "use": "@vercel/node"
+    }
+  ],
+  "routes": [
+    {
+      "src": "/api/(.*)",
+      "dest": "server.js"
+    },
+    {
+      "src": "/(.*)",
+      "dest": "server.js"
+    }
+  ]
+}
+```
+
+### Vercel Limitations
+- **Read-only filesystem** — Only `/tmp` writable
+- **Memory limit** — 1024MB (default)
+- **Execution time** — 10s (free) / 60s (pro)
+- **Cold starts** — ~2s on first request
+- **No persistent state** — Memory-only cache
+
+## What You Do
+
+1. **Manage releases** — Version bumps, CHANGELOG, git tags
+2. **Deploy to Vercel** — Push to main triggers auto-deploy
+3. **Configure env vars** — Set in Vercel dashboard or CLI
+4. **Monitor health** — Check `/api/health` and `/api/stats`
+5. **Troubleshoot deploys** — Check Vercel logs for errors
+6. **Manage git** — Branch strategy, commit format, push process
+7. **Verify deployments** — Post-deploy smoke tests
+
+## Critical Rules
+
+- **Never commit secrets** — All tokens stay out of git
+- **Clean remote URL** — Remove token from git remote after push
+- **CHANGELOG append-only** — Never edit or delete old entries
+- **Test before push** — Run `node test.js` before every push
+- **Verify after deploy** — Check health endpoint after Vercel deploy
+- **Git identity consistent** — Always use `Shinei Nouzen` author

agents/performance-benchmarker.md

@@ -0,0 +1,151 @@
+---
+name: Performance Benchmarker
+description: Performance specialist for AniKotoAPI — benchmarks endpoint response times, cache hit rates, compression ratio, mirror failover latency, and scraping throughput
+mode: subagent
+color: '#F39C12'
+---
+
+# Performance Benchmarker — AniKotoAPI
+
+You are **Performance Benchmarker** for AniKotoAPI, responsible for measuring and optimizing response times, cache efficiency, compression ratios, and scraping performance.
+
+## Your Identity
+
+- **Project**: AniKotoAPI v2.2.0 — https://github.com/Shineii86/AniKotoAPI
+- **Live API**: `https://anikototvapi.vercel.app/api`
+- **Deployment**: Vercel serverless (cold starts, memory limits, execution time limits)
+
+## Performance Baseline
+
+### Target Metrics
+| Metric | Target | Current |
+|--------|--------|---------|
+| P50 response time | < 200ms | ~150ms (cached) |
+| P95 response time | < 500ms | ~300ms |
+| P99 response time | < 1000ms | ~800ms |
+| Cache hit rate | > 80% | ~85% |
+| Compression ratio | > 60% | ~70% |
+| Cold start | < 3s | ~2s |
+
+### Endpoint Benchmarks
+| Endpoint | Cached | Uncached | Notes |
+|----------|--------|----------|-------|
+| `GET /api/` | ~50ms | ~300ms | Homepage with spotlights, trending |
+| `GET /api/search?keyword=naruto` | ~30ms | ~250ms | Search with pagination |
+| `GET /api/info?id=...` | ~40ms | ~350ms | Anime details |
+| `GET /api/episodes/:id` | ~30ms | ~200ms | Episode list |
+| `GET /api/servers?ids=...` | ~20ms | ~150ms | Server list |
+| `GET /api/stream?id=...` | ~15ms | ~100ms | Stream URL |
+| `GET /api/trending` | ~30ms | ~200ms | Trending list |
+| `GET /api/top-ten` | ~30ms | ~250ms | Rankings |
+| `GET /api/random` | 0ms | ~200ms | Never cached |
+| `GET /api/schedule` | ~50ms | ~400ms | 1hr cache TTL |
+
+## What You Measure
+
+### 1. Endpoint Response Times
+```bash
+# Quick benchmark
+for endpoint in "/" "/search?keyword=naruto" "/trending" "/top-ten"; do
+  echo "GET $endpoint"
+  curl -w "Total: %{time_total}s\nDNS: %{time_namelookup}s\nConnect: %{time_connect}s\nTTFB: %{time_starttransfer}s\n" \
+    -o /dev/null -s "https://anikototvapi.vercel.app/api$endpoint"
+done
+```
+
+### 2. Cache Performance
+```bash
+# First request (miss)
+curl -w "Miss: %{time_total}s\n" -o /dev/null -s "https://anikototvapi.vercel.app/api/trending"
+
+# Second request (hit)
+curl -w "Hit: %{time_total}s\n" -o /dev/null -s "https://anikototvapi.vercel.app/api/trending"
+
+# Cache stats
+curl -s "https://anikototvapi.vercel.app/api/cache/stats" | jq '.results'
+```
+
+### 3. Compression
+```bash
+# Without compression
+curl -w "Uncompressed: %{size_download} bytes\n" -o /dev/null -s -H "X-No-Compression: 1" "https://anikototvapi.vercel.app/api/"
+
+# With compression
+curl -w "Compressed: %{size_download} bytes\n" -o /dev/null -s --compressed "https://anikototvapi.vercel.app/api/"
+```
+
+### 4. Mirror Failover
+```bash
+# Check mirror status
+curl -s "https://anikototvapi.vercel.app/api/mirrors" | jq '.results'
+
+# Measure failover time (if primary is slow)
+time curl -s "https://anikototvapi.vercel.app/api/" > /dev/null
+```
+
+### 5. Rate Limiting
+```bash
+# Send rapid requests to trigger rate limit
+for i in $(seq 1 105); do
+  curl -s -o /dev/null -w "Request $i: %{http_code}\n" "https://anikototvapi.vercel.app/api/"
+done
+```
+
+## Performance Optimizations
+
+### Cache TTL Tuning
+| Endpoint | Current TTL | Recommended | Rationale |
+|----------|-------------|-------------|-----------|
+| `/` | 5 min | Keep | Homepage changes frequently |
+| `/search` | 3 min | Keep | Search results update |
+| `/info` | 10 min | Keep | Anime details stable |
+| `/episodes` | 5 min | Keep | Episodes update weekly |
+| `/stream` | 3 min | Keep | Stream URLs rotate |
+| `/schedule` | 1 hour | Keep | Schedule stable |
+| `/random` | 0 | Keep | Must be random |
+| `/trending` | 5 min | Consider 3 min | Changes often |
+| `/top-ten` | 5 min | Consider 10 min | Changes slowly |
+
+### Compression Settings
+```javascript
+// server.js compression config
+compression({
+  level: 6,           // Good balance of speed/ratio
+  threshold: 1024,    // Only compress > 1KB
+  filter: (req, res) => {
+    if (req.headers["x-no-compression"]) return false;
+    return compression.filter(req, res);
+  }
+})
+```
+
+### Request Headers
+```javascript
+// Optimal scraping headers
+{
+  'User-Agent': 'Mozilla/5.0 ...',
+  'Referer': 'https://anikototv.to/',
+  'Accept': 'text/html,application/xhtml+xml',
+  'Accept-Language': 'en-US,en;q=0.9',
+  'Accept-Encoding': 'gzip, deflate, br'
+}
+```
+
+## What You Do
+
+1. **Benchmark endpoints** — Measure response times for all 38 endpoints
+2. **Profile cache** — Track hit/miss ratios, measure TTL effectiveness
+3. **Test compression** — Compare compressed vs uncompressed sizes
+4. **Load test** — Simulate concurrent users, check rate limiting
+5. **Monitor cold starts** — Measure Vercel serverless cold start impact
+6. **Optimize selectors** — Profile Cheerio parsing time for complex extractors
+7. **Track mirror latency** — Measure failover time between domains
+
+## Critical Rules
+
+- **Test against live API** — Always use `https://anikototvapi.vercel.app/api`
+- **Measure real conditions** — Include network latency, not just server time
+- **Cold start awareness** — First request after idle is slower
+- **Cache invalidation** — Test with fresh cache vs warm cache
+- **Compression verification** — Check actual bytes transferred
+- **Rate limit respect** — Don't DDoS your own API during testing

agents/security-architect.md

@@ -0,0 +1,123 @@
+---
+name: Security Architect
+description: Security specialist for AniKotoAPI — validates SSRF protection, input sanitization, rate limiting, CORS, security headers, and scraping safety
+mode: subagent
+color: '#E74C3C'
+---
+
+# Security Architect — AniKotoAPI
+
+You are **Security Architect** for AniKotoAPI, responsible for securing a public scraping API that fetches data from anikototv.to and serves it via Express.js on Vercel.
+
+## Your Identity
+
+- **Project**: AniKotoAPI v2.2.0 — https://github.com/Shineii86/AniKotoAPI
+- **Risk profile**: Public API, no auth, scrapes external site, deployed on Vercel
+- **Attack surface**: SSRF via mapper API, XSS in error messages, rate limit bypass, header injection
+
+## Security Layers You Maintain
+
+### 1. Rate Limiting (server.js:132-156)
+```javascript
+// Configurable via RATE_LIMIT and RATE_WINDOW env vars
+// Default: 100 requests per 60 seconds per IP
+// Returns 429 with retryAfter header
+// Sets X-RateLimit-Limit and X-RateLimit-Remaining headers
+```
+
+### 2. Security Headers (server.js:72-80)
+```javascript
+// X-Frame-Options: DENY
+// X-Content-Type-Options: nosniff
+// X-XSS-Protection: 1; mode=block
+// Referrer-Policy: strict-origin-when-cross-origin
+// Permissions-Policy: camera=(), microphone=(), geolocation=()
+```
+
+### 3. CORS (server.js:58-70)
+```javascript
+// ALLOWED_ORIGINS env var (comma-separated)
+// Default: allow all origins
+// Only GET method allowed
+// Handles OPTIONS preflight
+```
+
+### 4. Input Sanitization
+- Mapper API: Validate `malId` is numeric, `slug` is string, `timestamp` is numeric
+- Search: Sanitize `keyword` parameter
+- All query params: Express auto-sanitizes, but validate types
+
+### 5. SSRF Protection
+```javascript
+// mapper-servers endpoint validates:
+// - malId must be numeric
+// - slug must be string
+// - timestamp must be numeric
+// Prevents arbitrary URL fetching
+```
+
+### 6. Error Handling
+```javascript
+// server.js:178-188
+// - Global error handler catches all errors
+// - Production: generic "Internal server error" message
+// - Development: full error message
+// - Entity too large: 413 response
+// - Request timeout: 408 response
+```
+
+### 7. Scraping Safety
+- **Fixed User-Agent**: Never rotate or randomize (fingerprinting risk)
+- **Referer header**: Always `https://anikototv.to/` (avoids blocks)
+- **No credential storage**: No API keys, no tokens, no passwords
+- **Mirror fallback**: 5 domains, no single point of failure
+
+## What You Audit
+
+### Input Validation
+| Endpoint | Risk | Validation |
+|----------|------|------------|
+| `/api/search?keyword=` | XSS | Sanitize special chars |
+| `/api/info?id=` | Path traversal | Validate slug format |
+| `/api/servers?ids=` | Injection | Base64 decode safely |
+| `/api/mapper-servers?malId=` | SSRF | Must be numeric |
+| `/api/mapper-servers?slug=` | Injection | String validation |
+| `/api/mapper-servers?timestamp=` | Injection | Must be numeric |
+
+### Configuration Security
+| Setting | Check |
+|---------|-------|
+| `.env` file | Never commit to git |
+| `ALLOWED_ORIGINS` | Don't use `*` in production |
+| `RATE_LIMIT` | Reasonable default (100/min) |
+| `REQUEST_TIMEOUT` | Prevent hanging requests (30s) |
+| `NODE_ENV` | Production hides error details |
+
+### Dependencies
+| Package | Version | Vulnerability Check |
+|---------|---------|-------------------|
+| express | 4.21 | Check for known CVEs |
+| axios | 1.8 | Check for SSRF bugs |
+| cheerio | 1.0-rc.12 | Check for prototype pollution |
+| cors | 2.8 | Check for bypass issues |
+| compression | 1.8 | Check for BREACH attacks |
+| dotenv | 16.4 | Check for env injection |
+
+## What You Do
+
+1. **Validate inputs** — Check all endpoint parameters for injection, XSS, path traversal
+2. **Audit headers** — Ensure security headers are set correctly
+3. **Review rate limiting** — Confirm bypass resistance, timing attacks
+4. **Check SSRF** — Validate mapper API doesn't allow arbitrary URL fetch
+5. **Scan dependencies** — Check for known vulnerabilities in package versions
+6. **Test error responses** — Ensure no info leakage in production
+7. **Review scraping safety** — Confirm headers don't expose internal details
+
+## Critical Rules
+
+- **Never store secrets in code** — All config via `.env`
+- **Rate limit before cache** — Rate limiter runs before cache check
+- **Sanitize error messages** — No stack traces in production
+- **Validate all inputs** — Especially mapper API params
+- **No credential forwarding** — Scraping requests don't forward auth headers
+- **CORS before routes** — CORS middleware runs before route matching

agents/technical-writer.md

@@ -0,0 +1,155 @@
+---
+name: Technical Writer
+description: Documentation specialist for AniKotoAPI — maintains README, CHANGELOG, API docs, code examples, and OpenAPI spec
+mode: subagent
+color: '#2ECC71'
+---
+
+# Technical Writer — AniKotoAPI
+
+You are **Technical Writer** for AniKotoAPI, responsible for maintaining all documentation: README.md, CHANGELOG.md, docs/ folder, code examples, and the OpenAPI specification.
+
+## Your Identity
+
+- **Project**: AniKotoAPI v2.2.0 — https://github.com/Shineii86/AniKotoAPI
+- **Author format**: `Shinei Nouzen <157171073+Shineii86@users.noreply.github.com>`
+- **Changelog rule**: Append at top, never delete/edit old entries
+
+## Documentation Structure
+
+```
+AniKotoAPI/
+├── README.md              # Main docs (2200+ lines)
+├── CHANGELOG.md           # Version history (append only)
+├── CONTRIBUTING.md         # Contribution guidelines
+├── docs/
+│   ├── index.md           # Overview, quick start
+│   ├── endpoints.md       # Full API reference (38 endpoints)
+│   ├── streaming.md       # 3-step streaming flow guide
+│   ├── examples.md        # cURL, JS, Python examples
+│   └── architecture.md    # Project structure, tech stack
+└── public/
+    ├── index.html         # Landing page
+    ├── tos.html           # Terms of Service
+    ├── privacy.html       # Privacy Policy
+    └── sitemap.xml        # Sitemap
+```
+
+## What You Maintain
+
+### CHANGELOG.md Format
+```markdown
+## [2.0.0] - 2026-07-04
+
+### Added
+- Multi-mirror fallback system with 5 mirror domains
+- LRU cache with configurable TTL per endpoint
+- Seasons endpoint (/api/seasons/:id)
+- Watch Order endpoint (/api/watch-order/:id)
+
+### Changed
+- BREAKING: All extractors now use mirror fallback helper
+
+### Fixed
+- Header merging bug in mirror helper
+
+### Removed
+- Removed og-image.svg
+```
+
+### README.md Structure
+```markdown
+# AniKotoAPI
+
+## Overview
+## Why AniKotoAPI?
+## How It Works (mermaid diagram)
+## Anime Data Source
+## Tech Stack
+## Project Structure (tree)
+## API Endpoints
+## Streaming Flow
+## Endpoint Documentation (36 sections)
+## API Response Schema
+## Configuration (.env)
+## Deployment
+## Contributing
+## License
+```
+
+### Endpoint Documentation Pattern
+```markdown
+> ## 🎥 GET Endpoint Name
+
+### Endpoint
+\`\`\`
+/endpoint-path
+\`\`\`
+
+#### Parameters
+| Parameter | Type | Mandatory | Default | Description |
+| :-------: | :--: | :-------: | :-----: | :---------: |
+| `param` | `type` | Yes/No | default | description |
+
+#### Example of request
+\`\`\`bash
+curl "https://anikototvapi.vercel.app/api/endpoint"
+\`\`\`
+
+#### Sample Response
+\`\`\`json
+{ "success": true, "results": {...} }
+\`\`\`
+```
+
+## Key Documentation Rules
+
+### Version Bumping
+1. Update `package.json` version
+2. Update README.md badge: `Version-2.2.0`
+3. Update OpenAPI spec version in `apiRoutes.js`
+4. Add CHANGELOG.md entry (prepend, never delete)
+
+### Endpoint Documentation
+When adding a new endpoint:
+1. Add to `docs/endpoints.md` with full details
+2. Add to README.md endpoints section
+3. Add example to `docs/examples.md`
+4. Add to OpenAPI spec in `apiRoutes.js`
+5. Update endpoint count in README badge and stats
+6. Add to `docs/streaming.md` if streaming-related
+
+### Code Examples
+- Always test examples against live API
+- Include cURL, JavaScript (fetch), and Python versions
+- Use realistic data (one-piece, naruto, etc.)
+- Show both success and error responses
+
+### Mermaid Diagrams
+```markdown
+flowchart TD
+    A["Request"] --> B{"Cache"}
+    B -- HIT --> C["Response"]
+    B -- MISS --> D["Scrape"]
+    D --> E["Parse"]
+    E --> F["Cache"]
+    F --> G["Response"]
+```
+
+## What You Do
+
+1. **Update CHANGELOG** — Add entries for every version bump
+2. **Maintain README** — Keep endpoint list, badges, examples current
+3. **Document endpoints** — Full docs for each of 38 endpoints
+4. **Write examples** — cURL, JS, Python for common use cases
+5. **Update OpenAPI** — Keep spec in sync with actual routes
+6. **Review docs/ folder** — Keep all 5 markdown files current
+7. **Update sitemap.xml** — Add dates when content changes
+
+## Critical Rules
+
+- **Never delete CHANGELOG entries** — Only append new versions at top
+- **Consistent author format** — `Shinei Nouzen` everywhere
+- **Test all examples** — Every curl/JS/Python example must work
+- **Count endpoints accurately** — Badge, stats, OpenAPI all must match
+- **Append, don't overwrite** — CHANGELOG entries are permanent

docs/architecture.md

@@ -7,7 +7,7 @@ AniKotoAPI/
 ├── server.js                          # Express entry point, port 4444
 ├── package.json                       # name: "AniKotoAPI"
 ├── vercel.json                        # Routes /api/* and /* to server.js
-├── .env                               # ANIKOTO_CHECK_SERVER_TS env var
+├── .env                               # Configuration (see .env.example)
 │
 ├── public/                            # Static files served from process.cwd()
 │   ├── index.html                     # Premium landing page (56KB, SVG icons, live console)
@@ -21,8 +21,8 @@ AniKotoAPI/
 │
 ├── docs/                              # API documentation
 │   ├── index.md                       # Overview, quick start, features
-│   ├── endpoints.md                   # Full API reference (30 endpoints)
+│   ├── endpoints.md                   # Full API reference (38 endpoints)
-│   ├── streaming.md                   # Streaming flow guide (3-step)
+│   ├── streaming.md                   # Streaming flow guide + resolver/proxy
 │   ├── examples.md                    # cURL, JavaScript, Python, Node.js
 │   └── architecture.md                # This file
 │
@@ -30,55 +30,77 @@ AniKotoAPI/
 │   ├── configs/
 │   │   ├── dataUrl.js                 # URL patterns, BASE_URL: https://anikototv.to
 │   │   ├── header.config.js           # Request headers (User-Agent, Referer, etc.)
-│   │   └── ids.config.js              # Genre/type/status ID mappings
+│   │   └── ids.config.js              # Genre/type/status/source/season ID mappings
 │   │
 │   ├── routes/
-│   │   ├── apiRoutes.js               # All route definitions
+│   │   ├── apiRoutes.js               # All route definitions + OpenAPI spec (38 endpoints)
 │   │   └── category.route.js          # genre/:name, type/:name, status/:name
 │   │
 │   ├── controllers/
 │   │   ├── homeInfo.controller.js         # Homepage data
 │   │   ├── search.controller.js       # Anime search
-│   │   ├── animeInfo.controller.js         # Anime info
+│   │   ├── animeInfo.controller.js         # Anime info (accepts ?id= or ?slug=)
 │   │   ├── episodeList.controller.js     # Episode list
+│   │   ├── episodeListAjax.controller.js # AJAX episode list
 │   │   ├── servers.controller.js      # Server list
 │   │   ├── stream.controller.js       # Stream URL
+│   │   ├── streamResolver.controller.js  # 🆕 Stream URL resolution + quality detection
 │   │   ├── suggestion.controller.js   # Anime suggestions
 │   │   ├── spotlight.controller.js    # Spotlight anime
 │   │   ├── trending.controller.js     # Trending anime
 │   │   ├── topten.controller.js       # Top 10
+│   │   ├── topAnimeRankings.controller.js # 🆕 Top rankings
+│   │   ├── upcomingAnime.controller.js    # 🆕 Upcoming anime
+│   │   ├── recentlyUpdatedTabs.controller.js # 🆕 Recently updated with tabs
+│   │   ├── completedAnime.controller.js    # 🆕 Completed anime
 │   │   ├── schedule.controller.js     # Schedule
 │   │   ├── random.controller.js       # Random anime
-│   │   ├── newRelease.controller.js   # New releases
+│   │   ├── newRelease.controller.js   # New releases + Latest Updated
 │   │   ├── popular.controller.js  # Most popular
-│   │   ├── category.controller.js        # Genre filter
+│   │   ├── category.controller.js        # Genre/Type/Status filter
-│   │   ├── category.controller.js         # Type filter
-│   │   ├── category.controller.js       # Status filter
 │   │   └── filter.controller.js       # Advanced filter
 │   │
 │   ├── extractors/
-│   │   ├── home.extractor.js          # Homepage extraction
+│   │   ├── homeInfo.extractor.js      # Homepage extraction
 │   │   ├── search.extractor.js        # Search results
-│   │   ├── info.extractor.js          # Anime details
+│   │   ├── animeInfo.extractor.js     # Anime details
 │   │   ├── episodeList.extractor.js   # Episode list + server_ids
+│   │   ├── episodeListAjax.extractor.js # AJAX episode list
 │   │   ├── serverList.extractor.js    # Server list
-│   │   ├── streamInfo.extractor.js    # Stream URL extraction
+│   │   ├── streamInfo.extractor.js    # Stream URL extraction (with session cookies)
+│   │   ├── streamResolver.extractor.js  # 🆕 Stream URL resolution, M3U8 parser, server normalization
 │   │   ├── spotlight.extractor.js     # Spotlight anime
 │   │   ├── trending.extractor.js      # Trending anime
 │   │   ├── topTen.extractor.js        # Top 10
+│   │   ├── topAnimeRankings.extractor.js # 🆕 Top rankings from sidebar
+│   │   ├── upcomingAnime.extractor.js    # 🆕 Upcoming anime
+│   │   ├── recentlyUpdatedTabs.extractor.js # 🆕 Recently updated with tab filtering
+│   │   ├── completedAnime.extractor.js    # 🆕 Completed anime from top-table
 │   │   ├── schedule.extractor.js      # Schedule
 │   │   ├── random.extractor.js        # Random anime
-│   │   ├── newRelease.extractor.js    # New releases
+│   │   ├── newRelease.extractor.js    # New releases + Latest Updated
 │   │   ├── mostPopular.extractor.js   # Most popular
 │   │   ├── genre.extractor.js         # Genre filter
-│   │   ├── type.extractor.js          # Type filter
+│   │   ├── filter.extractor.js        # Advanced filter (with source/season params)
-│   │   ├── status.extractor.js        # Status filter
+│   │   ├── suggestion.extractor.js    # Suggestions
-│   │   ├── filter.extractor.js        # Advanced filter
+│   │   ├── seasons.extractor.js       # Seasons from watch page sidebar
-│   │   └── suggestion.extractor.js    # Suggestions
+│   │   ├── watchOrder.extractor.js    # Watch order from watch page sidebar
+│   │   └── download.extractor.js      # Download links
 │   │
 │   └── helper/
-│       └── cache.helper.js            # In-memory Map cache, 5-min TTL
+│       ├── cache.helper.js            # LRU cache with configurable TTL
+│       ├── mirror.helper.js           # Multi-mirror fallback (5 domains, 404-safe)
+│       ├── extractPages.helper.js     # Page fetching with mirror fallback
+│       ├── formatTitle.helper.js      # Title formatter
+│       ├── countPages.helper.js       # Pagination counter
+│       ├── parseListItem.helper.js    # 🆕 Shared list item parser with self-anchor detection
+│       └── pagination.helper.js       # Pagination metadata generator
 │
+│   └── middleware/
+│       └── creatorInfo.js             # Creator attribution injection
+│
+├── test.js                            # Test suite (38 tests)
+├── agents/                            # AI agent prompts (6 agents)
 └── CHANGELOG.md                       # Version history
 ```
 
@@ -90,7 +112,10 @@ AniKotoAPI/
 | Framework | Express.js |
 | Scraping | Cheerio + Axios |
 | Deployment | Vercel (Serverless) |
-| Caching | In-memory Map with 5-min TTL |
+| Caching | LRU cache with configurable TTL |
+| Compression | gzip (level 6, 1024 byte threshold) |
+| Mirror Fallback | 5 mirror domains with health checks |
+| Middleware | Creator info attribution injection |
 | Static Files | Express static middleware |
 
 ## Request Flow
@@ -100,6 +125,14 @@ Client Request
     ↓
 Vercel Routes (/api/* → server.js)
     ↓
+Express Middleware
+    ↓
+├── CORS
+├── Security Headers
+├── Compression (gzip)
+├── Rate Limiting
+├── Creator Info Injection
+    ↓
 Express Router (apiRoutes.js)
     ↓
 Controller (e.g., search.controller.js)
@@ -110,7 +143,7 @@ HTTP Request to anikototv.to (with headers)
     ↓
 Cheerio parses HTML response
     ↓
-Returns structured JSON
+Returns structured JSON with Creator Attribution
     ↓
 Client Response
 ```
@@ -118,7 +151,7 @@ Client Response
 ## Streaming Flow
 
 ```
-/api/episodes/:slug
+/api/episodes/:animeId
     ↓
     Returns: server_ids, animeId, totalEpisodes
     ↓
@@ -128,7 +161,19 @@ Client Response
     ↓
 /api/stream?id={link_id}
     ↓
-    Returns: url (stream link), skipData (intro/outro timestamps)
+    Returns: url (embed URL), skipData (intro/outro timestamps)
+    ↓
+/api/stream/resolve?id={link_id}     ← 🆕 Resolve to actual video URL
+    ↓
+    Returns: url (m3u8/mp4), type, server name, subtitles
+    ↓
+/api/stream/qualities?url={m3u8_url} ← 🆕 Get quality options
+    ↓
+    Returns: qualities array with resolution, bandwidth, codec
+    ↓
+/api/stream/proxy?url={m3u8_url}     ← 🆕 CORS-free proxy
+    ↓
+    Returns: rewritten M3U8 with proxy URLs
 ```
 
 ## Caching Strategy
@@ -207,6 +252,6 @@ Error responses:
 | express | ^4.21.0 | Web framework |
 | cheerio | ^1.0.0-rc.12 | HTML parsing |
 | axios | ^1.8.0 | HTTP requests |
-| cors | ^2.8.5 | CORS headers |
 | cookie-parser | ^1.4.7 | Cookie parsing |
 | dotenv | ^16.4.0 | Environment variables |
+| compression | ^1.7.4 | Response compression |

docs/endpoints.md

@@ -4,6 +4,40 @@ Base URL: `https://anikototvapi.vercel.app/api`
 
 ---
 
+## Pagination
+
+All list endpoints include pagination metadata in the response:
+
+```json
+{
+  "success": true,
+  "results": {
+    "data": [...],
+    "pagination": {
+      "currentPage": 1,
+      "totalPages": 294,
+      "totalItems": 8820,
+      "itemsPerPage": 30,
+      "hasNext": true,
+      "hasPrev": false
+    }
+  }
+}
+```
+
+| Field | Type | Description |
+|:---|:---|:---|
+| `currentPage` | `number` | Current page number (1-indexed) |
+| `totalPages` | `number` | Total number of pages available |
+| `totalItems` | `number` | Estimated total items across all pages |
+| `itemsPerPage` | `number` | Number of items per page (default: 30) |
+| `hasNext` | `boolean` | Whether there is a next page |
+| `hasPrev` | `boolean` | Whether there is a previous page |
+
+**Endpoints with pagination:** `/api/search`, `/api/most-popular`, `/api/new-release`, `/api/newly-added`, `/api/latest-updated`, `/api/az-list/:letter`, `/api/filter`, `/api/genre/:name`, `/api/type/:name`, `/api/status/:name`
+
+---
+
 ## GET /
 
 Returns homepage data: spotlight anime, trending, top-airing, and genres.
@@ -135,12 +169,12 @@ Get episode list for an anime.
 
 | Param | Type | Required | Description |
 |-------|------|----------|-------------|
-| `id` | string | Yes | Anime slug |
+| `id` | string | Yes | Anime slug or animeId |
 
 **Request:**
 
 ```bash
-curl "https://anikototvapi.vercel.app/api/episodes/road-of-naruto-ggjw8"
+curl "https://anikototvapi.vercel.app/api/episodes/958"
 ```
 
 **Response:**
@@ -149,19 +183,20 @@ curl "https://anikototvapi.vercel.app/api/episodes/road-of-naruto-ggjw8"
 {
   "success": true,
   "results": {
-    "animeId": "7174",
+    "animeId": 958,
-    "totalEpisodes": 1,
+    "slug": "958",
+    "totalEpisodes": 220,
     "episodes": [
       {
-        "id": "110289",
+        "id": "16638",
         "episode_no": 1,
         "slug": "1",
         "title": "",
         "active": true,
         "href": "#",
-        "server_ids": "SlNVT25JaFlCMnZOeXZ2aG5takIxL2EybGl4TzJoNE1pN3JXdFNlODVocWtTckt1SFR0YUxrNzNhanQ2MEJoVG9UUEZNeWJOMm1uUThpYjNxejhhUEZWMitnNFFtTUNMYjBTc1FJZjZNNFZPNm5LMlVuTnpOU25ScUI1dHVGczM0UzluZ2xITG5qbExabnBDdGphY0VRPT0",
+        "server_ids": "dXNCT3hNQzk3THhSTW8ySnM5...",
-        "timestamp": "1729249503",
+        "timestamp": "1729197616",
-        "mal_id": "53236"
+        "mal_id": "20"
       }
     ]
   }
@@ -554,33 +589,66 @@ Returns trending anime for sidebar display.
 
 ## GET /seasons/:id
 
-Get season information for an anime.
+Get all seasons for an anime (main season, OVAs, movies, specials).
 
 | Param | Type | Required | Description |
 |-------|------|----------|-------------|
-| `id` | string | Yes | Anime slug |
+| `id` | number | Yes | Anime numeric ID |
 
 ```bash
-curl "https://anikototvapi.vercel.app/api/seasons/one-piece-100"
+curl "https://anikototvapi.vercel.app/api/seasons/1642"
 ```
 
-Returns season data including related seasons.
+Returns all seasons including OVAs, movies, and specials for the anime.
 
 ---
 
 ## GET /watch-order/:id
 
-Get recommended watch order for an anime.
+Get recommended watch order for an anime franchise.
 
 | Param | Type | Required | Description |
 |-------|------|----------|-------------|
-| `id` | string | Yes | Anime slug |
+| `id` | number | Yes | Anime numeric ID |
 
 ```bash
-curl "https://anikototvapi.vercel.app/api/watch-order/one-piece-100"
+curl "https://anikototvapi.vercel.app/api/watch-order/1642"
 ```
 
-Returns recommended watch order sequence.
+Returns recommended watch order sequence with relationship types.
+
+---
+
+## GET /latest-updated
+
+Get recently updated anime sorted by update time.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `page` | number | No | Page number (default: 1) |
+
+```bash
+curl "https://anikototvapi.vercel.app/api/latest-updated"
+```
+
+Returns paginated list of recently updated anime.
+
+---
+
+## GET /download
+
+Get download links for an anime episode.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `slug` | string | Yes | Anime slug |
+| `ep` | number | Yes | Episode number |
+
+```bash
+curl "https://anikototvapi.vercel.app/api/download?slug=one-piece-odmau&ep=1165"
+```
+
+Returns decoded download links for the specified episode.
 
 ---
 
@@ -598,3 +666,133 @@ curl "https://anikototvapi.vercel.app/api/az-list/a"
 ```
 
 Returns paginated list of anime starting with the specified letter.
+
+---
+
+## GET /upcoming
+
+Get upcoming anime sorted by air date.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `page` | number | No | Page number (default: 1) |
+
+```bash
+curl "https://anikototvapi.vercel.app/api/upcoming"
+```
+
+Returns paginated list of upcoming anime with sub/dub counts, type, and rating.
+
+---
+
+## GET /top-rankings
+
+Get top-ranked anime (source site's top section).
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `page` | number | No | Page number (default: 1) |
+
+```bash
+curl "https://anikototvapi.vercel.app/api/top-rankings"
+```
+
+Returns paginated list with rank numbers extracted from CSS classes.
+
+---
+
+## GET /recently-updated
+
+Get recently updated anime. Supports tab filtering.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `tab` | string | No | Filter: `sub`, `dub`, `all` (default: `all`) |
+| `page` | number | No | Page number (default: 1) |
+
+```bash
+curl "https://anikototvapi.vercel.app/api/recently-updated"
+```
+
+Returns paginated list from `#recent-update` section with client-side tab filtering.
+
+---
+
+## GET /completed
+
+Get completed anime sorted by score.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `page` | number | No | Page number (default: 1) |
+
+```bash
+curl "https://anikototvapi.vercel.app/api/completed"
+```
+
+Returns paginated list of finished anime from `section.top-table[data-name='completed']`.
+
+---
+
+## GET /stream/resolve
+
+Resolve an embed URL to actual video URL (m3u8/mp4).
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | string | Yes | `link_id` from `/servers` response |
+| `slug` | string | No | Anime slug (for session cookies) |
+
+```bash
+curl "https://anikototvapi.vercel.app/api/stream/resolve?id=MTF1dkFtaW9BRTZPbzJJRElFZUZr..."
+```
+
+Returns resolved URL, type (hls/mp4), server name, and subtitle URLs.
+
+---
+
+## GET /stream/qualities
+
+Parse M3U8 playlist for available quality options.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `url` | string | Yes | M3U8 playlist URL |
+
+```bash
+curl "https://anikototvapi.vercel.app/api/stream/qualities?url=https://example.com/playlist.m3u8"
+```
+
+Returns array of quality objects with url, quality label, resolution, bandwidth, and codec.
+
+---
+
+## GET /stream/proxy
+
+M3U8 playlist proxy — rewrites relative URLs to proxy endpoints for CORS-free playback.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `url` | string | Yes | M3U8 playlist URL |
+
+```bash
+curl "https://anikototvapi.vercel.app/api/stream/proxy?url=https://example.com/playlist.m3u8"
+```
+
+Returns rewritten M3U8 content with all `.m3u8` and `.ts` URLs pointing to proxy endpoints.
+
+---
+
+## GET /stream/ts-proxy
+
+TS video segment proxy — serves `.ts` segments with proper Content-Type and CORS headers.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `url` | string | Yes | `.ts` segment URL |
+
+```bash
+curl "https://anikototvapi.vercel.app/api/stream/ts-proxy?url=https://example.com/segment.ts"
+```
+
+Returns binary video segment with `Content-Type: video/mp2t` and `Access-Control-Allow-Origin: *`.

docs/examples.md

@@ -21,26 +21,26 @@ curl "https://anikototvapi.vercel.app/api/search?keyword=naruto"
 ### Anime Info
 
 ```bash
-curl "https://anikototvapi.vercel.app/api/info?id=road-of-naruto-ggjw8"
+curl "https://anikototvapi.vercel.app/api/info?id=naruto-eybxz"
 ```
 
 ### Episodes
 
 ```bash
-curl "https://anikototvapi.vercel.app/api/episodes/road-of-naruto-ggjw8"
+curl "https://anikototvapi.vercel.app/api/episodes/958"
 ```
 
 ### Servers
 
 ```bash
-SERVER_IDS=$(curl -s "https://anikototvapi.vercel.app/api/episodes/road-of-naruto-ggjw8" | python3 -c "import sys,json; print(json.load(sys.stdin)['results']['episodes'][0]['server_ids'])")
+SERVER_IDS=$(curl -s "https://anikototvapi.vercel.app/api/episodes/958" | python3 -c "import sys,json; print(json.load(sys.stdin)['results']['episodes'][0]['server_ids'])")
 curl "https://anikototvapi.vercel.app/api/servers?ids=$SERVER_IDS"
 ```
 
 ### Stream URL
 
 ```bash
-LINK_ID=$(curl -s "https://anikototvapi.vercel.app/api/episodes/road-of-naruto-ggjw8" | python3 -c "import sys,json; print(json.load(sys.stdin)['results']['episodes'][0]['server_ids'])" | xargs -I{} curl -s "https://anikototvapi.vercel.app/api/servers?ids={}" | python3 -c "import sys,json; print(json.load(sys.stdin)['results'][0]['link_id'])")
+LINK_ID=$(curl -s "https://anikototvapi.vercel.app/api/episodes/958" | python3 -c "import sys,json; print(json.load(sys.stdin)['results']['episodes'][0]['server_ids'])" | xargs -I{} curl -s "https://anikototvapi.vercel.app/api/servers?ids={}" | python3 -c "import sys,json; print(json.load(sys.stdin)['results'][0]['link_id'])")
 curl "https://anikototvapi.vercel.app/api/stream?id=$LINK_ID"
 ```
 
@@ -140,15 +140,15 @@ async function getAnimeInfo(slug) {
   return info;
 }
 
-getAnimeInfo('road-of-naruto-ggjw8');
+getAnimeInfo('naruto-eybxz');
 ```
 
 ### Full Streaming Flow
 
 ```javascript
-async function getStreamUrl(animeSlug) {
+async function getStreamUrl(animeId) {
   // Step 1: Get episodes
-  const episodesRes = await fetch(`https://anikototvapi.vercel.app/api/episodes/${animeSlug}`);
+  const episodesRes = await fetch(`https://anikototvapi.vercel.app/api/episodes/${animeId}`);
   const episodesData = await episodesRes.json();
   const episodes = episodesData.results.episodes;
   
@@ -179,7 +179,7 @@ async function getStreamUrl(animeSlug) {
 }
 
 // Usage
-getStreamUrl('road-of-naruto-ggjw8')
+getStreamUrl(958)
   .then(url => {
     console.log('Stream URL:', url);
     // Use with video player
@@ -268,11 +268,11 @@ searchAnime('naruto').then(results => {
 ```javascript
 const axios = require('axios');
 
-async function getStreamUrl(animeSlug) {
+async function getStreamUrl(animeId) {
   const BASE = 'https://anikototvapi.vercel.app/api';
   
   // Step 1: Get episodes
-  const { data: episodesData } = await axios.get(`${BASE}/episodes/${animeSlug}`);
+  const { data: episodesData } = await axios.get(`${BASE}/episodes/${animeId}`);
   const episodes = episodesData.results.episodes;
   
   if (!episodes || episodes.length === 0) {
@@ -302,7 +302,7 @@ async function getStreamUrl(animeSlug) {
 }
 
 // Usage
-getStreamUrl('road-of-naruto-ggjw8')
+getStreamUrl(958)
   .then(url => console.log('Stream URL:', url))
   .catch(err => console.error('Error:', err.message));
 ```
@@ -312,12 +312,12 @@ getStreamUrl('road-of-naruto-ggjw8')
 ```javascript
 const axios = require('axios');
 
-async function getEpisodeList(animeSlug) {
+async function getEpisodeList(animeId) {
-  const { data } = await axios.get(`https://anikototvapi.vercel.app/api/episodes/${animeSlug}`);
+  const { data } = await axios.get(`https://anikototvapi.vercel.app/api/episodes/${animeId}`);
   
-  const { animeId, totalEpisodes, episodes } = data.results;
+  const { animeId: id, totalEpisodes, episodes } = data.results;
   
-  console.log(`Anime ID: ${animeId}`);
+  console.log(`Anime ID: ${id}`);
   console.log(`Total Episodes: ${totalEpisodes}`);
   console.log(`Episodes available: ${episodes.length}`);
   
@@ -328,7 +328,7 @@ async function getEpisodeList(animeSlug) {
   return data.results;
 }
 
-getEpisodeList('road-of-naruto-ggjw8');
+getEpisodeList(958);
 ```
 
 ### Suggestions
@@ -363,3 +363,104 @@ async function getSchedule() {
 
 getSchedule();
 ```
+
+### Latest Updated
+
+```javascript
+const axios = require('axios');
+
+async function getLatestUpdated(page = 1) {
+  const { data } = await axios.get('https://anikototvapi.vercel.app/api/latest-updated', {
+    params: { page }
+  });
+  
+  console.log('Recently updated anime:', data.results.length);
+  return data.results;
+}
+
+getLatestUpdated();
+```
+
+### Seasons
+
+```javascript
+const axios = require('axios');
+
+async function getSeasons(animeId) {
+  const { data } = await axios.get(`https://anikototvapi.vercel.app/api/seasons/${animeId}`);
+  
+  console.log('Seasons:', data.results.length);
+  return data.results;
+}
+
+getSeasons(1642);
+```
+
+### Watch Order
+
+```javascript
+const axios = require('axios');
+
+async function getWatchOrder(animeId) {
+  const { data } = await axios.get(`https://anikototvapi.vercel.app/api/watch-order/${animeId}`);
+  
+  console.log('Watch order entries:', data.results.length);
+  return data.results;
+}
+
+getWatchOrder(1642);
+```
+
+### Download Links
+
+```javascript
+const axios = require('axios');
+
+async function getDownloadLinks(slug, episode) {
+  const { data } = await axios.get('https://anikototvapi.vercel.app/api/download', {
+    params: { slug, ep: episode }
+  });
+  
+  console.log('Download links:', data.results);
+  return data.results;
+}
+
+getDownloadLinks('one-piece-odmau', 1165);
+```
+
+### Upcoming Anime
+
+```bash
+curl "https://anikototvapi.vercel.app/api/upcoming"
+```
+
+### Top Rankings
+
+```bash
+curl "https://anikototvapi.vercel.app/api/top-rankings"
+```
+
+### Recently Updated
+
+```bash
+curl "https://anikototvapi.vercel.app/api/recently-updated?tab=sub"
+```
+
+### Completed Anime
+
+```bash
+curl "https://anikototvapi.vercel.app/api/completed"
+```
+
+### Stream URL Resolution
+
+```bash
+# Resolve embed URL to actual video URL
+curl "https://anikototvapi.vercel.app/api/stream/resolve?id=MTF1dkFtaW9BRTZPbzJJRElFZUZr..."
+
+# Get quality options
+curl "https://anikototvapi.vercel.app/api/stream/qualities?url=https://example.com/playlist.m3u8"
+
+# Proxy M3U8 for CORS-free playback
+curl "https://anikototvapi.vercel.app/api/stream/proxy?url=https://example.com/playlist.m3u8"
+```

docs/index.md

@@ -18,7 +18,7 @@ curl https://anikototvapi.vercel.app/api
 curl "https://anikototvapi.vercel.app/api/search?keyword=naruto"
 
 # Get anime info
-curl "https://anikototvapi.vercel.app/api/info?id=road-of-naruto-ggjw8"
+curl "https://anikototvapi.vercel.app/api/info?id=naruto-eybxz"
 ```
 
 **Live Response — Homepage:**
@@ -57,9 +57,12 @@ curl "https://anikototvapi.vercel.app/api/info?id=road-of-naruto-ggjw8"
 
 ## Features
 
-- **30 Endpoints** — Home, search, info, episodes, streaming, schedule, and more
+- **33 Endpoints** — Home, search, info, episodes, streaming, schedule, seasons, watch order, download, and more
 - **No API Key** — Just make requests, no registration needed
-- **In-Memory Cache** — 5-minute TTL for fast responses
+- **LRU Cache** — Configurable TTL per endpoint type (3min to 60min)
+- **Multi-Mirror Fallback** — Automatic failover across 5 mirror domains
+- **Response Compression** — Gzip compression for faster responses
+- **Pagination Metadata** — All list endpoints include `pagination` object with `currentPage`, `totalPages`, `hasNext`, `hasPrev`
 - **CORS Enabled** — Access from any domain
 - **JSON Responses** — Standardized `{success, results}` format
 
@@ -92,7 +95,7 @@ Error responses:
 
 ## Rate Limiting
 
-There are no explicit rate limits, but the API uses a 5-minute in-memory cache. Repeated requests for the same data will be served from cache.
+Rate limiting is configurable via environment variables (`RATE_LIMIT`, `RATE_WINDOW`). Default is 100 requests per 60 seconds per IP. Includes `X-RateLimit-Limit` and `X-RateLimit-Remaining` headers.
 
 ## Disclaimer
 

docs/streaming.md

@@ -5,7 +5,7 @@ This guide explains how to get streaming URLs from AniKotoAPI in 3 steps.
 ## Overview
 
 ```
-Step 1: Get Episodes   →  /api/episodes/:slug
+Step 1: Get Episodes   →  /api/episodes/:id
 Step 2: Get Servers    →  /api/servers?ids={server_ids}
 Step 3: Get Stream URL →  /api/stream?id={link_id}
 ```
@@ -14,12 +14,12 @@ Step 3: Get Stream URL →  /api/stream?id={link_id}
 
 ## Step 1: Get Episodes
 
-Each anime has multiple episodes. Fetch the episode list with the anime slug.
+Each anime has multiple episodes. Fetch the episode list with the anime slug or animeId.
 
 **Request:**
 
 ```bash
-curl "https://anikototvapi.vercel.app/api/episodes/road-of-naruto-ggjw8"
+curl "https://anikototvapi.vercel.app/api/episodes/958"
 ```
 
 **Response:**
@@ -28,19 +28,20 @@ curl "https://anikototvapi.vercel.app/api/episodes/road-of-naruto-ggjw8"
 {
   "success": true,
   "results": {
-    "animeId": "7174",
+    "animeId": 958,
-    "totalEpisodes": 1,
+    "slug": "958",
+    "totalEpisodes": 220,
     "episodes": [
       {
-        "id": "110289",
+        "id": "16638",
         "episode_no": 1,
         "slug": "1",
         "title": "",
         "active": true,
         "href": "#",
-        "server_ids": "SlNVT25JaFlCMnZOeXZ2aG5takIxL2EybGl4TzJoNE1pN3JXdFNlODVocWtTckt1SFR0YUxrNzNhanQ2MEJoVG9UUEZNeWJOMm1uUThpYjNxejhhUEZWMitnNFFtTUNMYjBTc1FJZjZNNFZPNm5LMlVuTnpOU25ScUI1dHVGczM0UzluZ2xITG5qbExabnBDdGphY0VRPT0",
+        "server_ids": "dXNCT3hNQzk3THhSTW8ySnM5...",
-        "timestamp": "1729249503",
+        "timestamp": "1729197616",
-        "mal_id": "53236"
+        "mal_id": "20"
       }
     ]
   }
@@ -58,7 +59,7 @@ Each episode has multiple servers. Use the `server_ids` from Step 1.
 **Request:**
 
 ```bash
-curl "https://anikototvapi.vercel.app/api/servers?ids=SlNVT25JaFlCMnZOeXZ2aG5takIxL2EybGl4TzJoNE1pN3JXdFNlODVocWtTckt1SFR0YUxrNzNhanQ2MEJoVG9UUEZNeWJOMm1uUThpYjNxejhhUEZWMitnNFFtTUNMYjBTc1FJZjZNNFZPNm5LMlVuTnpOU25ScUI1dHVGczM0UzluZ2xITG5qbExabnBDdGphY0VRPT0"
+curl "https://anikototvapi.vercel.app/api/servers?ids=dXNCT3hNQzk3THhSTW8ySnM5..."
 ```
 
 **Response:**
@@ -69,19 +70,19 @@ curl "https://anikototvapi.vercel.app/api/servers?ids=SlNVT25JaFlCMnZOeXZ2aG5tak
   "results": [
     {
       "type": "sub",
-      "ep_id": "110289",
+      "ep_id": "16638",
-      "link_id": "MTF1dkFtaW9BRTZPbzJJRElFZUZrOWdjeldjOERLaWNMMXFNbVB3WUJqOHZGS2FSWVgvbVJraVpIV1dQRjRoN01hOFUvYmxsWXFYNGtiR0h5OWdGQWc9PQ",
+      "link_id": "MTF1dkFtaW9BRTZPbzJJRElFZUZr...",
-      "cmid": "animixplay-fqs",
+      "cmid": "animixplay-fqsqfvdf4u",
-      "sv_id": "1",
+      "sv_id": "8e4",
-      "name": "HD-1"
+      "name": "VidPlay-1"
     },
     {
       "type": "sub",
-      "ep_id": "110289",
+      "ep_id": "16638",
-      "link_id": "MTF1dkFtaW9BRTZPbzJJRElFZUZrOWdjeldjOERLaWNMMXFNbVB3WUJqOEZ4cFNpMDdQbnV1S3dNdklpRkhWbzRsVmgxSGx4YWx3LytPcnZXU0RCVHc9PQ",
+      "link_id": "MTF1dkFtaW9BRTZPbzJJRElFZUZr...",
-      "cmid": "animixplay-fqs",
+      "cmid": "animixplay-fqsqfvdf4u",
-      "sv_id": "2",
+      "sv_id": "323",
-      "name": "Vidstream-2"
+      "name": "HD-1"
     }
   ]
 }
@@ -98,7 +99,7 @@ Get the actual streaming URL using the `link_id` from Step 2.
 **Request:**
 
 ```bash
-curl "https://anikototvapi.vercel.app/api/stream?id=MTF1dkFtaW9BRTZPbzJJRElFZUZrOWdjeldjOERLaWNMMXFNbVB3WUJqOHZGS2FSWVgvbVJraVpIV1dQRjRoN01hOFUvYmxsWXFYNGtiR0h5OWdGQWc9PQ"
+curl "https://anikototvapi.vercel.app/api/stream?id=MTF1dkFtaW9BRTZPbzJJRElFZUZr..."
 ```
 
 **Response:**
@@ -107,8 +108,8 @@ curl "https://anikototvapi.vercel.app/api/stream?id=MTF1dkFtaW9BRTZPbzJJRElFZUZr
 {
   "success": true,
   "results": {
-    "linkId": "MTF1dkFtaW9BRTZPbzJJRElFZUZrOWdjeldjOERLaWNMMXFNbVB3WUJqOHZGS2FSWVgvbVJraVpIV1dQRjRoN01hOFUvYmxsWXFYNGtiR0h5OWdGQWc9PQ",
+    "linkId": "MTF1dkFtaW9BRTZPbzJJRElFZUZr...",
-    "url": "https://megaplay.buzz/stream/s-5/94736/sub",
+    "url": "https://vidtube.site/stream/aVlsNDR3MnRLbWRvQUFBbWJUNERLQT09/sub",
     "skipData": {
       "intro": [0, 0],
       "outro": [0, 0]
@@ -124,9 +125,9 @@ curl "https://anikototvapi.vercel.app/api/stream?id=MTF1dkFtaW9BRTZPbzJJRElFZUZr
 ## JavaScript Example
 
 ```javascript
-async function getStreamUrl(animeSlug) {
+async function getStreamUrl(animeId) {
   // Step 1: Get episodes
-  const episodesRes = await fetch(`https://anikototvapi.vercel.app/api/episodes/${animeSlug}`);
+  const episodesRes = await fetch(`https://anikototvapi.vercel.app/api/episodes/${animeId}`);
   const episodesData = await episodesRes.json();
   const episodes = episodesData.results.episodes;
   
@@ -146,18 +147,18 @@ async function getStreamUrl(animeSlug) {
     throw new Error('No servers found');
   }
   
-  // Pick first server (HD-1)
+  // Pick first server (VidPlay-1)
   const linkId = servers[0].link_id;
   
   // Step 3: Get stream URL
   const streamRes = await fetch(`https://anikototvapi.vercel.app/api/stream?id=${linkId}`);
   const streamData = await streamRes.json();
   
-  return streamData.results.url; // "https://megaplay.buzz/stream/s-5/94736/sub"
+  return streamData.results.url; // "https://vidtube.site/stream/..."
 }
 
 // Usage
-getStreamUrl('road-of-naruto-ggjw8')
+getStreamUrl(958)
   .then(url => console.log('Stream URL:', url))
   .catch(err => console.error('Error:', err));
 ```
@@ -169,11 +170,11 @@ getStreamUrl('road-of-naruto-ggjw8')
 ```python
 import requests
 
-def get_stream_url(anime_slug):
+def get_stream_url(anime_id):
     base = "https://anikototvapi.vercel.app/api"
     
     # Step 1: Get episodes
-    episodes_res = requests.get(f"{base}/episodes/{anime_slug}")
+    episodes_res = requests.get(f"{base}/episodes/{anime_id}")
     episodes_data = episodes_res.json()
     episodes = episodes_data['results']['episodes']
     
@@ -199,7 +200,7 @@ def get_stream_url(anime_slug):
     return stream_data['results']['url']
 
 # Usage
-url = get_stream_url('road-of-naruto-ggjw8')
+url = get_stream_url(958)
 print(f"Stream URL: {url}")
 ```
 
@@ -247,10 +248,68 @@ player.source = {
 
 | Issue | Solution |
 |-------|----------|
-| "No episodes found" | Check the anime slug is correct (use `/api/search` first) |
+| "No episodes found" | Check the anime ID is correct (use `/api/search` first to find slug, then use animeId) |
 | "No servers found" | The `server_ids` may be invalid, try another episode |
 | Stream URL 403 | Some servers require specific referrer headers |
-| CORS error | Use a proxy or access from server-side |
+| CORS error | Use `/api/stream/proxy` endpoint to proxy M3U8 playlists |
+
+---
+
+## Stream URL Resolution (v2.2.0)
+
+The `/api/stream` endpoint returns an **embed URL** (e.g., `vidtube.site/stream/...`). To get the **actual video URL** (m3u8/mp4), use the resolver:
+
+### Step 4: Resolve Embed URL to Video URL
+
+```bash
+# Resolve embed URL to actual stream URL
+curl "https://anikototvapi.vercel.app/api/stream/resolve?id=MTF1dkFtaW9BRTZPbzJJRElFZUZr..."
+```
+
+```json
+{
+  "success": true,
+  "results": {
+    "url": "https://vid-tube.site/hls/b32de9d4a3230c95f52948373e6e1549.m3u8",
+    "type": "hls",
+    "server": "HD-1",
+    "subtitles": []
+  }
+}
+```
+
+### Get Quality Options
+
+```bash
+curl "https://anikototvapi.vercel.app/api/stream/qualities?url=https://example.com/playlist.m3u8"
+```
+
+```json
+{
+  "success": true,
+  "results": {
+    "qualities": [
+      { "url": "https://example.com/360.m3u8", "quality": "360p", "width": 640, "height": 360 },
+      { "url": "https://example.com/720.m3u8", "quality": "720p", "width": 1280, "height": 720 }
+    ]
+  }
+}
+```
+
+### M3U8 Proxy (CORS-Free Playback)
+
+Browser video players often can't fetch M3U8 playlists directly due to CORS. Use the proxy:
+
+```bash
+# Proxy rewrites all relative URLs to go through our API
+curl "https://anikototvapi.vercel.app/api/stream/proxy?url=https://example.com/playlist.m3u8"
+```
+
+The proxy:
+1. Fetches the M3U8 playlist
+2. Rewrites relative `.m3u8` URLs → `https://anikototvapi.vercel.app/api/stream/proxy?url=...`
+3. Rewrites `.ts` segment URLs → `https://anikototvapi.vercel.app/api/stream/ts-proxy?url=...`
+4. Returns the rewritten M3U8 content with CORS headers
 
 ---
 
@@ -261,7 +320,7 @@ For a simpler approach, use the `/watch` endpoint which returns episode data, se
 **Request:**
 
 ```bash
-curl "https://anikototvapi.vercel.app/api/watch?slug=road-of-naruto-ggjw8&ep=1"
+curl "https://anikototvapi.vercel.app/api/watch?slug=naruto-eybxz&ep=1"
 ```
 
 **Response includes:**
@@ -272,3 +331,30 @@ curl "https://anikototvapi.vercel.app/api/watch?slug=road-of-naruto-ggjw8&ep=1"
 - Next episode schedule
 
 This is useful when you need all watch page data at once instead of making 3 separate requests.
+
+---
+
+## Download Links
+
+For downloading episodes, use the `/download` endpoint which returns decoded download links.
+
+**Request:**
+
+```bash
+curl "https://anikototvapi.vercel.app/api/download?slug=one-piece-odmau&ep=1165"
+```
+
+**Response:**
+
+```json
+{
+  "success": true,
+  "results": {
+    "downloadLinks": [...],
+    "episodeNumber": 1165,
+    "title": "One Piece"
+  }
+}
+```
+
+> **Note:** Download links are decoded from base64 data and may require browser interaction due to Cloudflare protection on some hosts.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "AniKotoAPI",
-  "version": "1.9.0",
+  "version": "2.2.0",
   "description": "A restful API to provide all information about anime from anikototv.to",
   "main": "./server.js",
   "scripts": {
@@ -13,7 +13,7 @@
   "dependencies": {
     "axios": "^1.8.0",
     "cheerio": "^1.0.0-rc.12",
-    "cors": "^2.8.5",
+    "compression": "^1.8.1",
     "dotenv": "^16.4.0",
     "express": "^4.21.0"
   },

public/404.html

@@ -5,49 +5,41 @@
   <meta name="robots" content="noindex, nofollow" />
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
   <title>404 — AniKotoAPI</title>
-  <meta name="theme-color" content="#0A0A12" />
+  <meta name="theme-color" content="#faf9f5" />
   <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
   <link rel="preconnect" href="https://fonts.googleapis.com" />
   <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
-  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800;900&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet" />
+  <link href="https://fonts.googleapis.com/css2?family=Cormorant+Garamond:wght@400;500;600;700&family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet" />
   <style>
-    :root{--bg:#0A0A12;--text:#E2E8F0;--text2:#94A3B8;--text3:#64748B;--purple:#A855F7;--pink:#EC4899;--indigo:#6366F1;--green:#22C55E;--red:#EF4444;--border:rgba(255,255,255,.06);--glass:rgba(255,255,255,.03)}
+    :root{
+      --canvas:#faf9f5;--surface-card:#efe9de;--hairline:#e6dfd8;
+      --ink:#141413;--body:#3d3d3a;--muted:#6c6a64;--muted-soft:#8e8b82;
+      --primary:#cc785c;--primary-active:#a9583e;
+      --surface-dark:#181715;--on-dark:#faf9f5;--on-dark-soft:#a09d96;
+      --font-display:'Cormorant Garamond',Garamond,'Times New Roman',serif;
+      --font-body:'Inter',-apple-system,BlinkMacSystemFont,sans-serif;
+    }
     *{margin:0;padding:0;box-sizing:border-box}
-    body{font-family:'Inter',system-ui,sans-serif;background:var(--bg);color:var(--text);min-height:100vh;display:flex;align-items:center;justify-content:center;overflow:hidden}
+    body{font-family:var(--font-body);background:var(--canvas);color:var(--ink);min-height:100vh;display:flex;align-items:center;justify-content:center}
-    .ambient{position:fixed;inset:0;pointer-events:none}
-    .orb{position:absolute;border-radius:50%;filter:blur(120px);opacity:.1}
-    .orb-1{width:500px;height:500px;background:var(--purple);top:-150px;left:-100px;animation:drift 24s ease-in-out infinite}
-    .orb-2{width:400px;height:400px;background:var(--pink);bottom:-100px;right:-80px;animation:drift 20s ease-in-out infinite reverse}
-    @keyframes drift{0%,100%{transform:translate(0,0) scale(1)}50%{transform:translate(40px,-30px) scale(1.08)}}
     .container{position:relative;z-index:1;text-align:center;padding:40px;max-width:560px}
-    .code{font-size:clamp(6rem,18vw,14rem);font-weight:900;line-height:1;letter-spacing:-.06em;background:linear-gradient(135deg,var(--purple),var(--pink),var(--indigo));-webkit-background-clip:text;-webkit-text-fill-color:transparent;animation:float 4s ease-in-out infinite}
+    .code{font-family:var(--font-display);font-size:clamp(6rem,18vw,14rem);font-weight:400;line-height:1;letter-spacing:-.04em;color:var(--ink);opacity:.08}
-    @keyframes float{0%,100%{transform:translateY(0)}50%{transform:translateY(-10px)}}
+    .title{font-family:var(--font-display);font-size:1.8rem;font-weight:400;letter-spacing:-.01em;margin:16px 0 8px;color:var(--ink)}
-    .title{font-size:1.4rem;font-weight:700;margin:16px 0 8px}
+    .desc{color:var(--body);font-size:1rem;margin-bottom:32px;line-height:1.7}
-    .desc{color:var(--text2);font-size:.95rem;margin-bottom:32px;line-height:1.7}
     .actions{display:flex;gap:12px;justify-content:center;flex-wrap:wrap}
-    .btn{display:inline-flex;align-items:center;gap:8px;padding:12px 24px;border-radius:10px;font-size:.88rem;font-weight:600;text-decoration:none;border:none;cursor:pointer;transition:all .25s;font-family:inherit}
+    .btn{display:inline-flex;align-items:center;gap:8px;padding:12px 24px;border-radius:8px;font-size:.875rem;font-weight:500;text-decoration:none;border:none;cursor:pointer;transition:all .15s;font-family:var(--font-body)}
     .btn svg{width:16px;height:16px}
-    .btn-primary{background:linear-gradient(135deg,var(--purple),var(--pink));color:#fff;box-shadow:0 4px 24px rgba(168,85,247,.3)}
+    .btn-primary{background:var(--primary);color:#fff}
-    .btn-primary:hover{transform:translateY(-2px);box-shadow:0 8px 32px rgba(168,85,247,.4)}
+    .btn-primary:hover{background:var(--primary-active);text-decoration:none}
-    .btn-ghost{background:var(--glass);border:1px solid rgba(255,255,255,.1);color:var(--text)}
+    .btn-secondary{background:var(--canvas);border:1px solid var(--hairline);color:var(--ink)}
-    .btn-ghost:hover{background:rgba(255,255,255,.06);border-color:rgba(255,255,255,.15)}
+    .btn-secondary:hover{background:var(--surface-card);text-decoration:none}
-    .glitch{position:relative;display:inline-block}
+    .status-line{display:flex;align-items:center;justify-content:center;gap:8px;margin-top:24px;color:var(--muted-soft);font-size:.78rem;font-family:'JetBrains Mono',monospace}
-    .glitch::before,.glitch::after{content:attr(data-text);position:absolute;top:0;left:0;width:100%;height:100%;background:var(--bg)}
+    .status-dot{width:6px;height:6px;border-radius:50%;background:var(--primary);animation:pulse 1.5s infinite}
-    .glitch::before{left:2px;text-shadow:-2px 0 var(--pink);clip-path:inset(0 0 0 0);animation:glitch-1 2s infinite linear alternate-reverse}
-    .glitch::after{left:-2px;text-shadow:2px 0 var(--indigo);clip-path:inset(0 0 0 0);animation:glitch-2 3s infinite linear alternate-reverse}
-    @keyframes glitch-1{0%{clip-path:inset(40% 0 61% 0)}20%{clip-path:inset(92% 0 1% 0)}40%{clip-path:inset(43% 0 1% 0)}60%{clip-path:inset(25% 0 58% 0)}80%{clip-path:inset(54% 0 7% 0)}100%{clip-path:inset(58% 0 43% 0)}}
-    @keyframes glitch-2{0%{clip-path:inset(65% 0 13% 0)}20%{clip-path:inset(79% 0 2% 0)}40%{clip-path:inset(48% 0 38% 0)}60%{clip-path:inset(33% 0 2% 0)}80%{clip-path:inset(16% 0 62% 0)}100%{clip-path:inset(27% 0 42% 0)}}
-    .status-line{display:flex;align-items:center;justify-content:center;gap:8px;margin-top:24px;color:var(--text3);font-size:.78rem;font-family:'JetBrains Mono',monospace}
-    .status-dot{width:6px;height:6px;border-radius:50%;background:var(--red);animation:pulse 1.5s infinite}
     @keyframes pulse{0%,100%{opacity:1}50%{opacity:.3}}
-    .scanline{position:fixed;inset:0;z-index:0;pointer-events:none;background:repeating-linear-gradient(0deg,transparent,transparent 2px,rgba(0,0,0,.03) 2px,rgba(0,0,0,.03) 4px)}
   </style>
 </head>
 <body>
-  <div class="ambient"><div class="orb orb-1"></div><div class="orb orb-2"></div></div>
-  <div class="scanline"></div>
   <div class="container">
-    <div class="code"><span class="glitch" data-text="404">404</span></div>
+    <div class="code">404</div>
     <div class="title">Endpoint Not Found</div>
     <div class="desc">The path you requested doesn't exist in the AniKotoAPI.<br/>Check the documentation or try a valid endpoint.</div>
     <div class="actions">
@@ -55,11 +47,11 @@
         <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M3 9l9-7 9 7v11a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"/><polyline points="9 22 9 12 15 12 15 22"/></svg>
         Home
       </a>
-      <a href="/api" class="btn btn-ghost">
+      <a href="/api" class="btn btn-secondary">
         <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="16 18 22 12 16 6"/><polyline points="8 6 2 12 8 18"/></svg>
         API Status
       </a>
-      <a href="https://github.com/Shineii86/AniKotoAPI#readme" target="_blank" class="btn btn-ghost">
+      <a href="https://github.com/Shineii86/AniKotoAPI#readme" target="_blank" class="btn btn-secondary">
         <svg viewBox="0 0 24 24" fill="currentColor"><path d="M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z"/></svg>
         Docs
       </a>

public/index.html

@@ -4,255 +4,214 @@
   <meta charset="UTF-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
   <title>AniKotoAPI — Free Anime Data API</title>
-
-  <!-- ──────────────── Basic OG Tags ──────────────── -->
   <meta property="og:title" content="AniKotoAPI — Free Anime Data API" />
   <meta property="og:type" content="website" />
   <meta property="og:url" content="https://anikototvapi.vercel.app" />
   <meta property="og:image" content="https://anikototvapi.vercel.app/share.png" />
-  <meta property="og:description" content="Free REST API for anime data. Browse, search, stream episodes. 30+ endpoints, no API key required." />
+  <meta property="og:description" content="Free REST API for anime data. Browse, search, stream episodes. 33+ endpoints, no API key required." />
   <meta property="og:site_name" content="AniKotoAPI" />
   <meta property="og:locale" content="en_US" />
-
-  <!-- ──────────────── Image Optimization ──────────────── -->
   <meta property="og:image:secure_url" content="https://anikototvapi.vercel.app/share.png" />
   <meta property="og:image:type" content="image/jpeg" />
   <meta property="og:image:width" content="1200" />
   <meta property="og:image:height" content="601" />
   <meta property="og:image:alt" content="AniKotoAPI - Free Anime Data REST API" />
-
-  <!-- ──────────────── Twitter Card Tags ──────────────── -->
   <meta name="twitter:card" content="summary_large_image" />
   <meta name="twitter:site" content="@Shineii86" />
   <meta name="twitter:creator" content="@Shineii86" />
   <meta name="twitter:title" content="AniKotoAPI — Free Anime Data API" />
-  <meta name="twitter:description" content="Free REST API for anime data. Browse, search, stream episodes. 30+ endpoints, no API key required." />
+  <meta name="twitter:description" content="Free REST API for anime data. Browse, search, stream episodes. 33+ endpoints, no API key required." />
   <meta name="twitter:image" content="https://anikototvapi.vercel.app/share.png" />
   <meta name="twitter:image:alt" content="AniKotoAPI - Free Anime Data REST API" />
   <meta name="twitter:domain" content="anikototvapi.vercel.app" />
-
+  <meta name="description" content="Free REST API for anime data. Browse, search, stream episodes. 33+ endpoints, no API key required. Built with Node.js, Express, Cheerio." />
-  <!-- ──────────────── Generic Meta ──────────────── -->
-  <meta name="description" content="Free REST API for anime data. Browse, search, stream episodes. 30+ endpoints, no API key required. Built with Node.js, Express, Cheerio." />
   <meta name="author" content="Shinei Nouzen" />
   <meta name="keywords" content="anime api, free api, rest api, anime data, streaming, episode servers, nodejs, express, anime database, anime search" />
   <meta name="robots" content="index, follow" />
-  <meta name="theme-color" content="#0A0A12" />
+  <meta name="theme-color" content="#faf9f5" />
   <link rel="canonical" href="https://anikototvapi.vercel.app" />
-
-  <!-- ──────────────── Favicon ──────────────── -->
   <link rel="icon" type="image/png" href="/favicon-origin.png" />
   <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
   <link rel="apple-touch-icon" sizes="180x180" href="/favicon-origin.png" />
   <link rel="manifest" href="/manifest.json" />
-
-  <!-- ──────────────── Fonts ──────────────── -->
   <link rel="preconnect" href="https://fonts.googleapis.com" />
   <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
-  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800;900&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet" />
+  <link href="https://fonts.googleapis.com/css2?family=Cormorant+Garamond:wght@400;500;600;700&family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet" />
   <style>
     *,*::before,*::after{margin:0;padding:0;box-sizing:border-box}
     :root{
-      --bg:#0A0A12;--bg2:#111120;--bg3:#16162A;
+      --canvas:#faf9f5;--surface-soft:#f5f0e8;--surface-card:#efe9de;--surface-cream-strong:#e8e0d2;
-      --surface:rgba(17,17,32,.7);--glass:rgba(255,255,255,.03);
+      --surface-dark:#181715;--surface-dark-elevated:#252320;--surface-dark-soft:#1f1e1b;
-      --border:rgba(255,255,255,.06);--border2:rgba(255,255,255,.1);
+      --hairline:#e6dfd8;--hairline-soft:#ebe6df;
-      --text:#E2E8F0;--text2:#94A3B8;--text3:#64748B;
+      --ink:#141413;--body-strong:#252523;--body:#3d3d3a;--muted:#6c6a64;--muted-soft:#8e8b82;
-      --purple:#A855F7;--pink:#EC4899;--indigo:#6366F1;
+      --on-primary:#fff;--on-dark:#faf9f5;--on-dark-soft:#a09d96;
-      --green:#22C55E;--cyan:#06B6D4;--amber:#F59E0B;--red:#EF4444;
+      --primary:#cc785c;--primary-active:#a9583e;--primary-disabled:#e6dfd8;
-      --grad:linear-gradient(135deg,var(--purple),var(--pink));
+      --accent-teal:#5db8a6;--accent-amber:#e8a55a;
-      --grad2:linear-gradient(135deg,var(--indigo),var(--purple));
+      --success:#5db872;--warning:#d4a017;--error:#c64545;
-      --radius:12px;--radius-lg:16px;--radius-xl:20px;
+      --font-display:'Cormorant Garamond',Garamond,'Times New Roman',serif;
+      --font-body:'Inter',-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif;
+      --font-code:'JetBrains Mono',monospace;
     }
     html{scroll-behavior:smooth;-webkit-font-smoothing:antialiased}
-    body{font-family:'Inter',system-ui,sans-serif;background:var(--bg);color:var(--text);overflow-x:hidden;line-height:1.6}
+    body{font-family:var(--font-body);background:var(--canvas);color:var(--body);line-height:1.6}
-    ::selection{background:rgba(168,85,247,.3);color:#fff}
+    ::selection{background:rgba(204,120,92,.2);color:var(--ink)}
     ::-webkit-scrollbar{width:6px}
     ::-webkit-scrollbar-track{background:transparent}
-    ::-webkit-scrollbar-thumb{background:rgba(255,255,255,.08);border-radius:3px}
+    ::-webkit-scrollbar-thumb{background:var(--hairline);border-radius:3px}
-    ::-webkit-scrollbar-thumb:hover{background:rgba(255,255,255,.15)}
 
-    /* ── Ambient ── */
+    .container{max-width:1200px;margin:0 auto;padding:0 24px}
-    .ambient{position:fixed;inset:0;z-index:0;pointer-events:none;overflow:hidden}
+    a{color:var(--primary);text-decoration:none}
-    .orb{position:absolute;border-radius:50%;filter:blur(120px);opacity:.12}
+    a:hover{text-decoration:underline}
-    .orb-1{width:700px;height:700px;background:var(--purple);top:-250px;left:-200px;animation:drift 30s ease-in-out infinite}
-    .orb-2{width:500px;height:500px;background:var(--pink);bottom:-200px;right:-150px;animation:drift 25s ease-in-out infinite reverse}
-    .orb-3{width:400px;height:400px;background:var(--indigo);top:40%;left:40%;animation:drift 22s ease-in-out infinite 5s}
-    @keyframes drift{0%,100%{transform:translate(0,0) scale(1)}33%{transform:translate(50px,-40px) scale(1.1)}66%{transform:translate(-30px,30px) scale(.92)}}
-
-    /* ── Particles Canvas ── */
-    #particles{position:fixed;inset:0;z-index:0;pointer-events:none}
-
-    /* ── Layout ── */
-    .wrap{position:relative;z-index:1}
-    .container{max-width:1120px;margin:0 auto;padding:0 24px}
-    .container-lg{max-width:1280px;margin:0 auto;padding:0 24px}
 
     /* ── Header ── */
-    header{position:fixed;top:0;left:0;right:0;z-index:1000;padding:0 24px;transition:all .35s}
+    header{position:fixed;top:0;left:0;right:0;z-index:1000;background:var(--canvas);border-bottom:1px solid var(--hairline);transition:all .3s}
-    header.scrolled{background:rgba(10,10,18,.88);backdrop-filter:blur(24px) saturate(1.5);border-bottom:1px solid var(--border)}
+    header.scrolled{box-shadow:0 1px 3px rgba(20,20,19,.06)}
-    .header-inner{max-width:1120px;margin:0 auto;display:flex;align-items:center;justify-content:space-between;height:64px}
+    .header-inner{max-width:1200px;margin:0 auto;display:flex;align-items:center;justify-content:space-between;height:64px;padding:0 24px}
-    .logo{display:flex;align-items:center;gap:10px;text-decoration:none;color:var(--text)}
+    .logo{display:flex;align-items:center;gap:8px;text-decoration:none;color:var(--ink)}
-    .logo svg{width:28px;height:28px}
+    .logo-mark{font-family:var(--font-display);font-size:1.3rem;font-weight:600;letter-spacing:-.02em}
-    .logo-text{font-size:1.1rem;font-weight:700;letter-spacing:-.02em}
+    .logo-mark span{color:var(--primary)}
-    .logo-text span{background:var(--grad);-webkit-background-clip:text;-webkit-text-fill-color:transparent}
     nav{display:flex;align-items:center;gap:4px}
-    nav a{color:var(--text2);text-decoration:none;font-size:.8rem;font-weight:500;padding:6px 14px;border-radius:8px;transition:all .2s}
+    nav a{color:var(--muted);text-decoration:none;font-size:.875rem;font-weight:500;padding:6px 14px;border-radius:8px;transition:all .15s}
-    nav a:hover{color:var(--text);background:var(--glass)}
+    nav a:hover{color:var(--ink);background:var(--surface-card);text-decoration:none}
-    nav a.active{color:var(--purple)}
+    .nav-cta{margin-left:8px;background:var(--primary)!important;color:var(--on-primary)!important;padding:8px 18px!important;border-radius:8px!important;font-weight:500!important}
-    .nav-cta{margin-left:8px;background:var(--grad)!important;color:#fff!important;padding:7px 16px!important;border-radius:8px!important;font-weight:600!important}
+    .nav-cta:hover{background:var(--primary-active)!important}
-    .nav-cta:hover{opacity:.9;transform:translateY(-1px)}
 
     /* ── Hero ── */
-    .hero{padding:140px 0 80px;text-align:center;position:relative}
+    .hero{padding:140px 0 80px;max-width:1200px;margin:0 auto;padding-left:24px;padding-right:24px;display:grid;grid-template-columns:1fr 1fr;gap:60px;align-items:center}
-    .hero-badge{display:inline-flex;align-items:center;gap:8px;background:var(--glass);border:1px solid var(--border);padding:6px 16px;border-radius:100px;font-size:.75rem;color:var(--text2);margin-bottom:24px}
+    .hero-badge{display:inline-flex;align-items:center;gap:8px;background:var(--surface-card);border:1px solid var(--hairline);padding:6px 16px;border-radius:9999px;font-size:.75rem;font-weight:500;color:var(--muted);margin-bottom:20px;letter-spacing:.5px;text-transform:uppercase}
-    .hero-badge .dot{width:6px;height:6px;border-radius:50%;background:var(--green);animation:pulse 2s infinite}
+    .hero-badge .dot{width:6px;height:6px;border-radius:50%;background:var(--success);animation:pulse 2s infinite}
-    @keyframes pulse{0%,100%{opacity:1}50%{opacity:.3}}
+    @keyframes pulse{0%,100%{opacity:1}50%{opacity:.4}}
-    .hero h1{font-size:clamp(2.5rem,5.5vw,4rem);font-weight:900;line-height:1.1;letter-spacing:-.04em;margin-bottom:20px}
+    .hero h1{font-family:var(--font-display);font-size:clamp(2.5rem,5vw,3.5rem);font-weight:400;line-height:1.1;letter-spacing:-.02em;color:var(--ink);margin-bottom:16px}
-    .hero h1 .grad{background:var(--grad);-webkit-background-clip:text;-webkit-text-fill-color:transparent}
+    .hero-sub{color:var(--body);font-size:1.05rem;max-width:480px;line-height:1.7;margin-bottom:32px}
-    .hero-sub{color:var(--text2);font-size:1.05rem;max-width:540px;margin:0 auto 40px;line-height:1.7}
+    .hero-actions{display:flex;gap:12px;flex-wrap:wrap}
-    .hero-actions{display:flex;gap:12px;justify-content:center;flex-wrap:wrap;margin-bottom:48px}
+    .btn{display:inline-flex;align-items:center;gap:8px;padding:12px 24px;border-radius:8px;font-size:.875rem;font-weight:500;text-decoration:none;border:none;cursor:pointer;transition:all .15s;font-family:var(--font-body)}
-    .btn{display:inline-flex;align-items:center;gap:8px;padding:12px 24px;border-radius:10px;font-size:.88rem;font-weight:600;text-decoration:none;border:none;cursor:pointer;transition:all .25s;font-family:inherit}
     .btn svg{width:16px;height:16px}
-    .btn-primary{background:var(--grad);color:#fff;box-shadow:0 4px 24px rgba(168,85,247,.3)}
+    .btn-primary{background:var(--primary);color:var(--on-primary)}
-    .btn-primary:hover{transform:translateY(-2px);box-shadow:0 8px 32px rgba(168,85,247,.4)}
+    .btn-primary:hover{background:var(--primary-active);text-decoration:none}
-    .btn-ghost{background:var(--glass);border:1px solid var(--border2);color:var(--text)}
+    .btn-secondary{background:var(--canvas);border:1px solid var(--hairline);color:var(--ink)}
-    .btn-ghost:hover{background:rgba(255,255,255,.06);border-color:rgba(255,255,255,.15)}
+    .btn-secondary:hover{background:var(--surface-card);text-decoration:none}
 
     /* ── Console ── */
-    .console{max-width:720px;margin:0 auto;border-radius:var(--radius-xl);overflow:hidden;border:1px solid var(--border2);background:var(--bg2);box-shadow:0 24px 80px rgba(0,0,0,.5),0 0 120px rgba(168,85,247,.08)}
+    .console-wrap{background:var(--surface-dark);border-radius:12px;overflow:hidden;box-shadow:0 24px 80px rgba(20,20,19,.15)}
-    .console-bar{display:flex;align-items:center;gap:8px;padding:14px 18px;background:rgba(255,255,255,.02);border-bottom:1px solid var(--border)}
+    .console-bar{display:flex;align-items:center;gap:8px;padding:14px 18px;background:var(--surface-dark-elevated);border-bottom:1px solid rgba(255,255,255,.06)}
     .console-dot{width:10px;height:10px;border-radius:50%}
-    .console-dot:nth-child(1){background:#FF5F57}
+    .console-dot:nth-child(1){background:#ff5f57}
-    .console-dot:nth-child(2){background:#FEBC2E}
+    .console-dot:nth-child(2){background:#febc2e}
-    .console-dot:nth-child(3){background:#28C840}
+    .console-dot:nth-child(3){background:#28c840}
-    .console-title{margin-left:12px;font-size:.72rem;color:var(--text3);font-family:'JetBrains Mono',monospace}
+    .console-title{margin-left:12px;font-size:.75rem;color:var(--on-dark-soft);font-family:var(--font-code)}
     .console-body{display:flex;min-height:180px}
-    .console-input{flex:1;padding:18px;font-family:'JetBrains Mono',monospace;font-size:.8rem;line-height:1.8;color:var(--text);border:none;background:transparent;resize:none;outline:none}
+    .console-input{flex:1;padding:18px;font-family:var(--font-code);font-size:.8rem;line-height:1.8;color:var(--on-dark);border:none;background:transparent;resize:none;outline:none}
-    .console-input::placeholder{color:var(--text3)}
+    .console-input::placeholder{color:var(--on-dark-soft)}
-    .console-output{flex:1;padding:18px;border-left:1px solid var(--border);font-family:'JetBrains Mono',monospace;font-size:.78rem;line-height:1.8;color:var(--green);overflow:auto;max-height:300px;white-space:pre-wrap}
+    .console-output{flex:1;padding:18px;border-left:1px solid rgba(255,255,255,.06);font-family:var(--font-code);font-size:.78rem;line-height:1.8;color:var(--success);overflow:auto;max-height:300px;white-space:pre-wrap}
-    .console-actions{display:flex;gap:8px;padding:12px 18px;border-top:1px solid var(--border);background:rgba(255,255,255,.01)}
+    .console-actions{display:flex;gap:8px;padding:12px 18px;border-top:1px solid rgba(255,255,255,.06);background:var(--surface-dark-elevated)}
-    .console-btn{padding:6px 14px;border-radius:6px;border:1px solid var(--border);background:transparent;color:var(--text2);font-size:.75rem;font-weight:500;cursor:pointer;transition:all .2s;font-family:'JetBrains Mono',monospace}
+    .console-btn{padding:6px 14px;border-radius:6px;border:1px solid rgba(255,255,255,.08);background:transparent;color:var(--on-dark-soft);font-size:.75rem;font-weight:500;cursor:pointer;transition:all .15s;font-family:var(--font-code)}
-    .console-btn:hover{background:var(--glass);color:var(--text)}
+    .console-btn:hover{background:rgba(255,255,255,.05);color:var(--on-dark)}
-    .console-btn.active{background:rgba(168,85,247,.15);color:var(--purple);border-color:rgba(168,85,247,.3)}
+    .console-btn.active{background:rgba(204,120,92,.15);color:var(--primary);border-color:rgba(204,120,92,.3)}
-    .console-send{margin-left:auto;padding:6px 16px;border-radius:6px;border:none;background:var(--grad);color:#fff;font-size:.75rem;font-weight:600;cursor:pointer;transition:all .2s;font-family:'JetBrains Mono',monospace}
+    .console-send{margin-left:auto;padding:6px 16px;border-radius:6px;border:none;background:var(--primary);color:var(--on-primary);font-size:.75rem;font-weight:500;cursor:pointer;transition:all .15s;font-family:var(--font-code)}
-    .console-send:hover{opacity:.9;transform:translateY(-1px)}
+    .console-send:hover{background:var(--primary-active)}
 
     /* ── Stats ── */
-    .stats{padding:60px 0;border-top:1px solid var(--border);border-bottom:1px solid var(--border)}
+    .stats{padding:60px 0;border-top:1px solid var(--hairline);border-bottom:1px solid var(--hairline);background:var(--surface-soft)}
     .stats-grid{display:grid;grid-template-columns:repeat(4,1fr);gap:24px;text-align:center}
-    .stat-value{font-size:2rem;font-weight:900;letter-spacing:-.03em}
+    .stat-value{font-family:var(--font-display);font-size:2.5rem;font-weight:400;letter-spacing:-.02em;color:var(--ink)}
-    .stat-value.grad{background:var(--grad);-webkit-background-clip:text;-webkit-text-fill-color:transparent}
+    .stat-label{font-size:.8rem;color:var(--muted);margin-top:4px;font-weight:500}
-    .stat-label{font-size:.78rem;color:var(--text3);margin-top:4px;font-weight:500}
 
     /* ── Section ── */
-    .section{padding:100px 0}
+    .section{padding:96px 0}
-    .section-label{display:inline-flex;align-items:center;gap:6px;font-size:.7rem;text-transform:uppercase;letter-spacing:.1em;color:var(--purple);font-weight:700;margin-bottom:12px}
+    .section-label{display:inline-flex;align-items:center;gap:6px;font-size:.7rem;text-transform:uppercase;letter-spacing:1.5px;color:var(--primary);font-weight:600;margin-bottom:12px}
-    .section-title{font-size:clamp(1.8rem,3vw,2.4rem);font-weight:800;letter-spacing:-.03em;margin-bottom:10px;line-height:1.2}
+    .section-title{font-family:var(--font-display);font-size:clamp(1.8rem,3vw,2.4rem);font-weight:400;letter-spacing:-.01em;margin-bottom:10px;line-height:1.2;color:var(--ink)}
-    .section-desc{color:var(--text2);font-size:1rem;max-width:520px;line-height:1.7;margin-bottom:40px}
+    .section-desc{color:var(--body);font-size:1rem;max-width:520px;line-height:1.7;margin-bottom:40px}
 
     /* ── Features Grid ── */
     .features-grid{display:grid;grid-template-columns:repeat(3,1fr);gap:16px}
-    .feature-card{background:var(--surface);border:1px solid var(--border);border-radius:var(--radius-lg);padding:32px;transition:all .35s;position:relative;overflow:hidden}
+    .feature-card{background:var(--surface-card);border:1px solid var(--hairline);border-radius:12px;padding:32px;transition:all .2s}
-    .feature-card::before{content:'';position:absolute;inset:0;background:linear-gradient(135deg,rgba(168,85,247,.05),rgba(236,72,153,.05));opacity:0;transition:opacity .35s}
+    .feature-card:hover{transform:translateY(-2px);box-shadow:0 4px 12px rgba(20,20,19,.06)}
-    .feature-card:hover{border-color:rgba(168,85,247,.2);transform:translateY(-4px);box-shadow:0 16px 48px rgba(0,0,0,.3)}
+    .feature-icon{width:44px;height:44px;border-radius:8px;display:flex;align-items:center;justify-content:center;margin-bottom:18px;background:var(--canvas);border:1px solid var(--hairline)}
-    .feature-card:hover::before{opacity:1}
+    .feature-icon svg{width:20px;height:20px;color:var(--primary)}
-    .feature-icon{width:44px;height:44px;border-radius:10px;display:flex;align-items:center;justify-content:center;margin-bottom:18px;position:relative;z-index:1}
+    .feature-title{font-family:var(--font-display);font-size:1.1rem;font-weight:500;margin-bottom:8px;color:var(--ink)}
-    .feature-icon svg{width:22px;height:22px}
+    .feature-desc{color:var(--body);font-size:.875rem;line-height:1.7}
-    .fi-purple{background:rgba(168,85,247,.12);color:var(--purple)}
-    .fi-pink{background:rgba(236,72,153,.12);color:var(--pink)}
-    .fi-green{background:rgba(34,197,94,.12);color:var(--green)}
-    .fi-cyan{background:rgba(6,182,212,.12);color:var(--cyan)}
-    .fi-amber{background:rgba(245,158,11,.12);color:var(--amber)}
-    .fi-indigo{background:rgba(99,102,241,.12);color:var(--indigo)}
-    .feature-title{font-size:1rem;font-weight:700;margin-bottom:8px;position:relative;z-index:1}
-    .feature-desc{color:var(--text2);font-size:.84rem;line-height:1.7;position:relative;z-index:1}
 
     /* ── Endpoint Explorer ── */
-    .explorer{display:grid;grid-template-columns:240px 1fr;gap:1px;background:var(--border);border-radius:var(--radius-lg);overflow:hidden;border:1px solid var(--border)}
+    .explorer{display:grid;grid-template-columns:240px 1fr;gap:1px;background:var(--hairline);border-radius:12px;overflow:hidden;border:1px solid var(--hairline)}
-    .explorer-nav{background:var(--bg2);padding:8px}
+    .explorer-nav{background:var(--surface-dark);padding:8px}
-    .explorer-nav-btn{display:flex;align-items:center;gap:8px;width:100%;padding:10px 14px;border:none;background:transparent;color:var(--text2);font-size:.8rem;font-weight:500;border-radius:8px;cursor:pointer;transition:all .2s;text-align:left;font-family:inherit}
+    .explorer-nav-btn{display:flex;align-items:center;gap:8px;width:100%;padding:10px 14px;border:none;background:transparent;color:var(--on-dark-soft);font-size:.8rem;font-weight:500;border-radius:8px;cursor:pointer;transition:all .15s;text-align:left;font-family:var(--font-body)}
-    .explorer-nav-btn:hover{background:var(--glass);color:var(--text)}
+    .explorer-nav-btn:hover{background:rgba(255,255,255,.05);color:var(--on-dark)}
-    .explorer-nav-btn.active{background:rgba(168,85,247,.1);color:var(--purple)}
+    .explorer-nav-btn.active{background:rgba(204,120,92,.15);color:var(--primary)}
     .explorer-nav-btn svg{width:16px;height:16px;flex-shrink:0}
-    .explorer-panel{background:var(--bg2);padding:24px;min-height:400px}
+    .explorer-panel{background:var(--surface-dark);padding:24px;min-height:400px}
-    .explorer-panel-title{font-size:1.1rem;font-weight:700;margin-bottom:4px}
+    .explorer-panel-title{font-family:var(--font-display);font-size:1.2rem;font-weight:500;margin-bottom:4px;color:var(--on-dark)}
-    .explorer-panel-desc{color:var(--text2);font-size:.84rem;margin-bottom:20px;line-height:1.6}
+    .explorer-panel-desc{color:var(--on-dark-soft);font-size:.84rem;margin-bottom:20px;line-height:1.6}
-    .explorer-method{display:inline-flex;align-items:center;gap:6px;padding:4px 10px;border-radius:6px;font-size:.7rem;font-weight:700;font-family:'JetBrains Mono',monospace;letter-spacing:.04em;margin-bottom:12px}
+    .explorer-method{display:inline-flex;align-items:center;gap:6px;padding:4px 10px;border-radius:6px;font-size:.7rem;font-weight:700;font-family:var(--font-code);letter-spacing:.04em;margin-bottom:12px;background:rgba(93,184,114,.15);color:var(--success)}
-    .method-get{background:rgba(34,197,94,.12);color:var(--green)}
+    .explorer-path{font-family:var(--font-code);font-size:.85rem;color:var(--on-dark);margin-bottom:16px;padding:12px 16px;background:var(--surface-dark-soft);border-radius:8px;border:1px solid rgba(255,255,255,.06)}
-    .explorer-path{font-family:'JetBrains Mono',monospace;font-size:.85rem;color:var(--text);margin-bottom:16px;padding:12px 16px;background:rgba(0,0,0,.3);border-radius:8px;border:1px solid var(--border)}
     .explorer-params{margin-bottom:16px}
-    .explorer-params-title{font-size:.72rem;text-transform:uppercase;letter-spacing:.08em;color:var(--text3);font-weight:600;margin-bottom:8px}
+    .explorer-params-title{font-size:.72rem;text-transform:uppercase;letter-spacing:.08em;color:var(--on-dark-soft);font-weight:600;margin-bottom:8px}
     .param-row{display:grid;grid-template-columns:120px 80px 1fr;gap:12px;padding:8px 0;border-bottom:1px solid rgba(255,255,255,.03);font-size:.8rem}
-    .param-name{font-family:'JetBrains Mono',monospace;color:var(--pink);font-weight:500}
+    .param-name{font-family:var(--font-code);color:var(--accent-amber);font-weight:500}
-    .param-type{font-family:'JetBrains Mono',monospace;color:var(--purple);font-size:.75rem}
+    .param-type{font-family:var(--font-code);color:var(--accent-teal);font-size:.75rem}
-    .param-desc{color:var(--text2)}
+    .param-desc{color:var(--on-dark-soft)}
-    .explorer-code{background:rgba(0,0,0,.3);border-radius:8px;padding:16px;font-family:'JetBrains Mono',monospace;font-size:.78rem;line-height:1.8;color:var(--text2);overflow-x:auto;border:1px solid var(--border)}
+    .explorer-code{background:var(--surface-dark-soft);border-radius:8px;padding:16px;font-family:var(--font-code);font-size:.78rem;line-height:1.8;color:var(--on-dark-soft);overflow-x:auto;border:1px solid rgba(255,255,255,.06)}
-    .explorer-code .kw{color:var(--purple)}
-    .explorer-code .str{color:var(--green)}
-    .explorer-code .cmt{color:var(--text3)}
-    .explorer-code .fn{color:var(--cyan)}
-    .explorer-code .num{color:var(--amber)}
 
     /* ── Code Tabs ── */
-    .code-tabs{display:flex;gap:2px;background:rgba(0,0,0,.2);border-radius:8px;padding:3px;margin-bottom:12px;width:fit-content}
+    .code-tabs{display:flex;gap:2px;background:var(--surface-dark-soft);border-radius:8px;padding:3px;margin-bottom:12px;width:fit-content}
-    .code-tab{padding:6px 14px;border-radius:6px;border:none;background:transparent;color:var(--text3);font-size:.72rem;font-weight:600;cursor:pointer;transition:all .2s;font-family:'JetBrains Mono',monospace}
+    .code-tab{padding:6px 14px;border-radius:6px;border:none;background:transparent;color:var(--on-dark-soft);font-size:.72rem;font-weight:600;cursor:pointer;transition:all .15s;font-family:var(--font-code)}
-    .code-tab.active{background:rgba(168,85,247,.15);color:var(--purple)}
+    .code-tab.active{background:rgba(204,120,92,.15);color:var(--primary)}
-    .code-tab:hover:not(.active){color:var(--text2)}
+    .code-tab:hover:not(.active){color:var(--on-dark)}
-    .code-block{display:none}
-    .code-block.active{display:block}
 
     /* ── Playground ── */
-    .playground-card{background:var(--surface);border:1px solid var(--border);border-radius:var(--radius-lg);overflow:hidden}
+    .playground-card{background:var(--surface-card);border:1px solid var(--hairline);border-radius:12px;overflow:hidden}
-    .playground-header{padding:20px 24px;border-bottom:1px solid var(--border);display:flex;align-items:center;gap:10px}
+    .playground-header{padding:20px 24px;border-bottom:1px solid var(--hairline);display:flex;align-items:center;gap:10px}
-    .playground-header svg{width:18px;height:18px;color:var(--purple)}
+    .playground-header svg{width:18px;height:18px;color:var(--primary)}
-    .playground-header h3{font-size:1rem;font-weight:700}
+    .playground-header h3{font-family:var(--font-display);font-size:1.1rem;font-weight:500;color:var(--ink)}
     .playground-body{padding:24px}
     .playground-inputs{display:flex;gap:10px;margin-bottom:16px;flex-wrap:wrap}
-    .playground-inputs input,.playground-inputs select{flex:1;min-width:200px;padding:10px 14px;border-radius:8px;border:1px solid var(--border);background:rgba(0,0,0,.3);color:var(--text);font-size:.85rem;font-family:'JetBrains Mono',monospace;outline:none;transition:border-color .2s}
+    .playground-inputs input,.playground-inputs select{flex:1;min-width:200px;padding:10px 14px;border-radius:8px;border:1px solid var(--hairline);background:var(--canvas);color:var(--ink);font-size:.85rem;font-family:var(--font-code);outline:none;transition:border-color .15s}
-    .playground-inputs input:focus,.playground-inputs select:focus{border-color:var(--purple)}
+    .playground-inputs input:focus,.playground-inputs select:focus{border-color:var(--primary)}
-    .playground-inputs input::placeholder{color:var(--text3)}
+    .playground-inputs input::placeholder{color:var(--muted-soft)}
-    .playground-inputs select option{background:var(--bg2)}
+    .playground-inputs select option{background:var(--canvas)}
-    .playground-output{background:rgba(0,0,0,.3);border:1px solid var(--border);border-radius:8px;padding:16px;font-family:'JetBrains Mono',monospace;font-size:.78rem;line-height:1.7;color:var(--green);max-height:400px;overflow:auto;white-space:pre-wrap;display:none}
+    .playground-output{background:var(--surface-dark);border:1px solid rgba(255,255,255,.06);border-radius:8px;padding:16px;font-family:var(--font-code);font-size:.78rem;line-height:1.7;color:var(--success);max-height:400px;overflow:auto;white-space:pre-wrap;display:none}
     .playground-output.visible{display:block}
 
     /* ── Marquee ── */
-    .marquee{padding:40px 0;overflow:hidden;border-top:1px solid var(--border);border-bottom:1px solid var(--border)}
+    .marquee{padding:40px 0;overflow:hidden;border-top:1px solid var(--hairline);border-bottom:1px solid var(--hairline);background:var(--surface-soft)}
     .marquee-track{display:flex;gap:40px;animation:marquee 30s linear infinite;width:max-content}
-    .marquee-item{display:flex;align-items:center;gap:8px;color:var(--text3);font-size:.8rem;font-weight:500;white-space:nowrap}
+    .marquee-item{display:flex;align-items:center;gap:8px;color:var(--muted);font-size:.8rem;font-weight:500;white-space:nowrap}
     .marquee-item svg{width:16px;height:16px;opacity:.5}
     @keyframes marquee{0%{transform:translateX(0)}100%{transform:translateX(-50%)}}
 
     /* ── CTA ── */
-    .cta{text-align:center;padding:100px 0}
+    .cta{text-align:center;padding:96px 0}
-    .cta-box{background:var(--surface);border:1px solid var(--border);border-radius:var(--radius-xl);padding:60px 40px;position:relative;overflow:hidden}
+    .cta-box{background:var(--primary);border-radius:16px;padding:64px 40px;position:relative;overflow:hidden}
-    .cta-box::before{content:'';position:absolute;inset:0;background:linear-gradient(135deg,rgba(168,85,247,.08),rgba(236,72,153,.08))}
+    .cta-title{font-family:var(--font-display);font-size:clamp(1.8rem,3vw,2.4rem);font-weight:400;letter-spacing:-.01em;margin-bottom:12px;color:var(--on-primary)}
-    .cta-title{font-size:clamp(1.8rem,3vw,2.4rem);font-weight:800;letter-spacing:-.03em;margin-bottom:12px;position:relative}
+    .cta-desc{color:rgba(255,255,255,.85);font-size:1rem;margin-bottom:28px}
-    .cta-desc{color:var(--text2);font-size:1rem;margin-bottom:28px;position:relative}
+    .cta-actions{display:flex;gap:12px;justify-content:center}
-    .cta-actions{display:flex;gap:12px;justify-content:center;position:relative}
+    .btn-on-coral{background:var(--canvas);color:var(--ink);border:1px solid var(--hairline)}
+    .btn-on-coral:hover{background:var(--surface-card);text-decoration:none}
 
     /* ── Footer ── */
-    footer{padding:60px 0 40px;border-top:1px solid var(--border)}
+    footer{background:var(--surface-dark);color:var(--on-dark-soft);padding:64px 0 40px}
     .footer-grid{display:grid;grid-template-columns:2fr 1fr 1fr 1fr;gap:40px;margin-bottom:40px}
     .footer-brand .logo{margin-bottom:12px}
-    .footer-brand p{color:var(--text3);font-size:.82rem;line-height:1.7;max-width:280px}
+    .footer-brand .logo .logo-mark{color:var(--on-dark)}
-    .footer-col h4{font-size:.75rem;text-transform:uppercase;letter-spacing:.08em;color:var(--text3);font-weight:600;margin-bottom:16px}
+    .footer-brand p{color:var(--on-dark-soft);font-size:.84rem;line-height:1.7;max-width:280px}
-    .footer-col a{display:block;color:var(--text2);text-decoration:none;font-size:.84rem;padding:4px 0;transition:color .2s}
+    .footer-col h4{font-size:.7rem;text-transform:uppercase;letter-spacing:1.5px;color:var(--on-dark-soft);font-weight:600;margin-bottom:16px}
-    .footer-col a:hover{color:var(--purple)}
+    .footer-col a{display:block;color:var(--on-dark-soft);text-decoration:none;font-size:.84rem;padding:4px 0;transition:color .15s}
-    .footer-bottom{display:flex;align-items:center;justify-content:space-between;padding-top:24px;border-top:1px solid var(--border);color:var(--text3);font-size:.75rem}
+    .footer-col a:hover{color:var(--on-dark)}
+    .footer-bottom{display:flex;align-items:center;justify-content:space-between;padding-top:24px;border-top:1px solid rgba(255,255,255,.06);color:var(--on-dark-soft);font-size:.75rem}
     .footer-social{display:flex;gap:12px}
-    .footer-social a{color:var(--text3);transition:color .2s}
+    .footer-social a{color:var(--on-dark-soft);transition:color .15s}
-    .footer-social a:hover{color:var(--purple)}
+    .footer-social a:hover{color:var(--on-dark)}
     .footer-social svg{width:18px;height:18px}
 
     /* ── Scroll Reveal ── */
-    .reveal{opacity:0;transform:translateY(30px);transition:all .7s cubic-bezier(.16,1,.3,1)}
+    .reveal{opacity:0;transform:translateY(20px);transition:all .6s cubic-bezier(.16,1,.3,1)}
     .reveal.visible{opacity:1;transform:translateY(0)}
     .reveal-delay-1{transition-delay:.1s}
     .reveal-delay-2{transition-delay:.2s}
     .reveal-delay-3{transition-delay:.3s}
-    .reveal-delay-4{transition-delay:.4s}
 
     /* ── Mobile ── */
     @media(max-width:900px){
+      .hero{grid-template-columns:1fr;gap:40px}
       .features-grid{grid-template-columns:repeat(2,1fr)}
       .explorer{grid-template-columns:1fr}
       .stats-grid{grid-template-columns:repeat(2,1fr)}
@@ -263,20 +222,18 @@
       .hero h1{font-size:2rem}
       .features-grid{grid-template-columns:1fr}
       .console-body{flex-direction:column}
-      .console-output{border-left:none;border-top:1px solid var(--border)}
+      .console-output{border-left:none;border-top:1px solid rgba(255,255,255,.06)}
       .stats-grid{grid-template-columns:repeat(2,1fr);gap:16px}
       .footer-grid{grid-template-columns:1fr}
       nav{display:none}
     }
   </style>
-
-  <!-- ──────────────── JSON-LD Structured Data ──────────────── -->
   <script type="application/ld+json">
   {
     "@context": "https://schema.org",
     "@type": "WebAPI",
     "name": "AniKotoAPI",
-    "description": "Free REST API for anime data. Browse, search, stream episodes. 30+ endpoints, no API key required.",
+    "description": "Free REST API for anime data. Browse, search, stream episodes. 33+ endpoints, no API key required.",
     "url": "https://anikototvapi.vercel.app",
     "image": "https://anikototvapi.vercel.app/share.png",
     "documentation": "https://github.com/Shineii86/AniKotoAPI",
@@ -287,28 +244,16 @@
     },
     "category": "Anime Data API",
     "endpoint": "https://anikototvapi.vercel.app/api",
-    "programmingModel": "REST",
+    "programmingModel": "REST"
-    "documentationUrl": "https://github.com/Shineii86/AniKotoAPI/tree/main/docs"
   }
   </script>
 </head>
 <body>
-
-  <div class="ambient">
-    <div class="orb orb-1"></div>
-    <div class="orb orb-2"></div>
-    <div class="orb orb-3"></div>
-  </div>
-  <canvas id="particles"></canvas>
-
   <div class="wrap">
-
-    <!-- Header -->
     <header id="header">
       <div class="header-inner">
         <a href="/" class="logo">
-          <svg aria-hidden="true" viewBox="0 0 32 32" fill="none"><circle cx="16" cy="16" r="14" stroke="url(#g1)" stroke-width="2"/><path d="M10 20c0-4 3-7 6-7s6 3 6 7" stroke="url(#g1)" stroke-width="2" stroke-linecap="round"/><circle cx="12" cy="12" r="2" fill="var(--purple)"/><circle cx="20" cy="12" r="2" fill="var(--pink)"/><defs><linearGradient id="g1" x1="0" y1="0" x2="32" y2="32"><stop stop-color="var(--purple)"/><stop offset="1" stop-color="var(--pink)"/></linearGradient></defs></svg>
+          <span class="logo-mark"><span>*</span> AniKotoAPI</span>
-          <span class="logo-text"><span>AniKoto</span>API</span>
         </a>
         <nav>
           <a href="#features">Features</a>
@@ -320,27 +265,26 @@
       </div>
     </header>
 
-    <!-- Hero -->
+    <section class="hero">
-    <section class="hero container">
+      <div>
-      <div class="hero-badge"><span class="dot"></span> Free &middot; No API key &middot; Open source</div>
+        <div class="hero-badge"><span class="dot"></span> Free &middot; No API key &middot; Open source</div>
-      <h1>The <span class="grad">Anime Data</span> API<br/>for Your Next Project</h1>
+        <h1>The anime data API for your next project</h1>
-      <p class="hero-sub">Browse, search, and stream anime data from AniKoto. Real-time scraping with 30+ endpoints, in-memory caching, and zero configuration.</p>
+        <p class="hero-sub">Browse, search, and stream anime data from AniKoto. Real-time scraping with 33+ endpoints, in-memory caching, and zero configuration.</p>
-      <div class="hero-actions">
+        <div class="hero-actions">
-        <a href="#playground" class="btn btn-primary">
+          <a href="#playground" class="btn btn-primary">
-          <svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polygon points="5 3 19 12 5 21 5 3"/></svg>
+            <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polygon points="5 3 19 12 5 21 5 3"/></svg>
-          Try It Live
+            Try It Live
-        </a>
+          </a>
-        <a href="https://github.com/Shineii86/AniKotoAPI" target="_blank" class="btn btn-ghost">
+          <a href="https://github.com/Shineii86/AniKotoAPI" target="_blank" class="btn btn-secondary">
-          <svg aria-hidden="true" viewBox="0 0 24 24" fill="currentColor"><path d="M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z"/></svg>
+            <svg viewBox="0 0 24 24" fill="currentColor"><path d="M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z"/></svg>
-          Star on GitHub
+            Star on GitHub
-        </a>
+          </a>
+        </div>
       </div>
-
+      <div class="console-wrap">
-      <!-- Live Console -->
-      <div class="console" id="heroConsole">
         <div class="console-bar">
           <span class="console-dot"></span><span class="console-dot"></span><span class="console-dot"></span>
-          <span class="console-title">anikototvapi.vercel.app — API Console</span>
+          <span class="console-title">anikototvapi.vercel.app/api</span>
         </div>
         <div class="console-body">
           <textarea class="console-input" id="consoleInput" rows="6" spellcheck="false">// Fetch trending anime
@@ -349,7 +293,7 @@ fetch("https://anikototvapi.vercel.app/api")
   .then(data => {
     console.log(data.trending);
   });</textarea>
-          <div class="console-output" id="consoleOutput"><span style="color:var(--text3)">// Click "Run" to see the response</span></div>
+          <div class="console-output" id="consoleOutput"><span style="color:var(--on-dark-soft)">// Click "Run" to see the response</span></div>
         </div>
         <div class="console-actions">
           <button class="console-btn active" onclick="setEndpoint('home', event)">Home</button>
@@ -357,114 +301,88 @@ fetch("https://anikototvapi.vercel.app/api")
           <button class="console-btn" onclick="setEndpoint('stream', event)">Stream</button>
           <button class="console-btn" onclick="setEndpoint('random', event)">Random</button>
           <button class="console-btn" onclick="setEndpoint('schedule', event)">Schedule</button>
-          <button class="console-send" onclick="runConsole()">
+          <button class="console-send" onclick="runConsole()">Run</button>
-            <svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="width:12px;height:12px;display:inline"><polygon points="5 3 19 12 5 21 5 3"/></svg> Run
-          </button>
         </div>
       </div>
     </section>
 
-    <!-- Stats -->
     <section class="stats">
       <div class="container">
         <div class="stats-grid">
-          <div class="reveal"><div class="stat-value grad" data-count="30">0</div><div class="stat-label">API Endpoints</div></div>
+          <div class="reveal"><div class="stat-value" data-count="33">0</div><div class="stat-label">API Endpoints</div></div>
-          <div class="reveal reveal-delay-1"><div class="stat-value grad" data-count="0">0</div><div class="stat-label">API Keys Required</div></div>
+          <div class="reveal reveal-delay-1"><div class="stat-value" data-count="0">0</div><div class="stat-label">API Keys Required</div></div>
-          <div class="reveal reveal-delay-2"><div class="stat-value grad" data-count="40">0</div><div class="stat-label">Anime Genres</div></div>
+          <div class="reveal reveal-delay-2"><div class="stat-value" data-count="40">0</div><div class="stat-label">Anime Genres</div></div>
-          <div class="reveal reveal-delay-3"><div class="stat-value grad">Live</div><div class="stat-label">Real-time Data</div></div>
+          <div class="reveal reveal-delay-3"><div class="stat-value">Live</div><div class="stat-label">Real-time Data</div></div>
         </div>
       </div>
     </section>
 
-    <!-- Marquee -->
     <div class="marquee">
       <div class="marquee-track">
-        <div class="marquee-item"><svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="10"/><path d="M12 6v6l4 2"/></svg> 5-min cache TTL</div>
+        <div class="marquee-item"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="10"/><path d="M12 6v6l4 2"/></svg> 5-min cache TTL</div>
-        <div class="marquee-item"><svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M13 2L3 14h9l-1 8 10-12h-9l1-8z"/></svg> Zero config</div>
+        <div class="marquee-item"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M13 2L3 14h9l-1 8 10-12h-9l1-8z"/></svg> Zero config</div>
-        <div class="marquee-item"><svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 22s8-4 8-10V5l-8-3-8 3v7c0 6 8 10 8 10z"/></svg> No auth needed</div>
+        <div class="marquee-item"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 22s8-4 8-10V5l-8-3-8 3v7c0 6 8 10 8 10z"/></svg> No auth needed</div>
-        <div class="marquee-item"><svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="2" y="3" width="20" height="14" rx="2"/><path d="M8 21h8m-4-4v4"/></svg> Vercel deployed</div>
+        <div class="marquee-item"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="2" y="3" width="20" height="14" rx="2"/><path d="M8 21h8m-4-4v4"/></svg> Vercel deployed</div>
-        <div class="marquee-item"><svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M14.7 6.3a1 1 0 0 0 0 1.4l1.6 1.6a1 1 0 0 0 1.4 0l3.77-3.77a6 6 0 0 1-7.94 7.94l-6.91 6.91a2.12 2.12 0 0 1-3-3l6.91-6.91a6 6 0 0 1 7.94-7.94l-3.76 3.76z"/></svg> Cheerio scraper</div>
+        <div class="marquee-item"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M14.7 6.3a1 1 0 0 0 0 1.4l1.6 1.6a1 1 0 0 0 1.4 0l3.77-3.77a6 6 0 0 1-7.94 7.94l-6.91 6.91a2.12 2.12 0 0 1-3-3l6.91-6.91a6 6 0 0 1 7.94-7.94l-3.76 3.76z"/></svg> Cheerio scraper</div>
-        <div class="marquee-item"><svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><polyline points="16 18 22 12 16 6"/><polyline points="8 6 2 12 8 18"/></svg> REST JSON</div>
+        <div class="marquee-item"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><polyline points="16 18 22 12 16 6"/><polyline points="8 6 2 12 8 18"/></svg> REST JSON</div>
-        <div class="marquee-item"><svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="10"/><path d="M2 12h20"/></svg> CORS enabled</div>
+        <div class="marquee-item"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="10"/><path d="M2 12h20"/></svg> CORS enabled</div>
-        <div class="marquee-item"><svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M4 4h16c1.1 0 2 .9 2 2v12c0 1.1-.9 2-2 2H4c-1.1 0-2-.9-2-2V6c0-1.1.9-2 2-2z"/><polyline points="22,6 12,13 2,6"/></svg> Open source</div>
+        <div class="marquee-item"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M4 4h16c1.1 0 2 .9 2 2v12c0 1.1-.9 2-2 2H4c-1.1 0-2-.9-2-2V6c0-1.1.9-2 2-2z"/><polyline points="22,6 12,13 2,6"/></svg> Open source</div>
-        <!-- duplicate for seamless loop -->
+        <div class="marquee-item"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="10"/><path d="M12 6v6l4 2"/></svg> 5-min cache TTL</div>
-        <div class="marquee-item"><svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="10"/><path d="M12 6v6l4 2"/></svg> 5-min cache TTL</div>
+        <div class="marquee-item"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M13 2L3 14h9l-1 8 10-12h-9l1-8z"/></svg> Zero config</div>
-        <div class="marquee-item"><svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M13 2L3 14h9l-1 8 10-12h-9l1-8z"/></svg> Zero config</div>
+        <div class="marquee-item"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 22s8-4 8-10V5l-8-3-8 3v7c0 6 8 10 8 10z"/></svg> No auth needed</div>
-        <div class="marquee-item"><svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 22s8-4 8-10V5l-8-3-8 3v7c0 6 8 10 8 10z"/></svg> No auth needed</div>
+        <div class="marquee-item"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="2" y="3" width="20" height="14" rx="2"/><path d="M8 21h8m-4-4v4"/></svg> Vercel deployed</div>
-        <div class="marquee-item"><svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="2" y="3" width="20" height="14" rx="2"/><path d="M8 21h8m-4-4v4"/></svg> Vercel deployed</div>
       </div>
     </div>
 
-    <!-- Features -->
     <section class="section" id="features">
       <div class="container">
         <div class="reveal">
-          <div class="section-label">
+          <div class="section-label">Features</div>
-            <svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="width:14px;height:14px"><path d="M12 2L2 7l10 5 10-5-10-5z"/><path d="M2 17l10 5 10-5"/><path d="M2 12l10 5 10-5"/></svg>
-            Features
-          </div>
           <h2 class="section-title">Built for developers</h2>
           <p class="section-desc">Everything you need to build an anime website, mobile app, or Discord bot. No API keys, no rate limits, no hassle.</p>
         </div>
         <div class="features-grid">
           <div class="feature-card reveal">
-            <div class="feature-icon fi-purple">
+            <div class="feature-icon"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="11" cy="11" r="8"/><path d="M21 21l-4.35-4.35"/></svg></div>
-              <svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="11" cy="11" r="8"/><path d="M21 21l-4.35-4.35"/></svg>
-            </div>
             <div class="feature-title">Full-text Search</div>
             <div class="feature-desc">Search by keyword, genre, type, status. Get autocomplete suggestions and paginated results.</div>
           </div>
           <div class="feature-card reveal reveal-delay-1">
-            <div class="feature-icon fi-pink">
+            <div class="feature-icon"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="2" y="2" width="20" height="20" rx="2.18"/><path d="M7 2v20M17 2v20M2 12h20M2 7h5M2 17h5M17 7h5M17 17h5"/></svg></div>
-              <svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="2" y="2" width="20" height="20" rx="2.18"/><path d="M7 2v20M17 2v20M2 12h20M2 7h5M2 17h5M17 7h5M17 17h5"/></svg>
-            </div>
             <div class="feature-title">Episode Streaming</div>
             <div class="feature-desc">Retrieve streaming servers, source links, and m3u8 URLs for any episode via AJAX endpoints.</div>
           </div>
           <div class="feature-card reveal reveal-delay-2">
-            <div class="feature-icon fi-green">
+            <div class="feature-icon"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z"/><path d="M14 2v6h6"/><path d="M16 13H8"/><path d="M16 17H8"/><path d="M10 9H8"/></svg></div>
-              <svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z"/><path d="M14 2v6h6"/><path d="M16 13H8"/><path d="M16 17H8"/><path d="M10 9H8"/></svg>
-            </div>
             <div class="feature-title">Rich Metadata</div>
             <div class="feature-desc">Synopsis, MAL score, genres, characters, relations, recommendations, and more.</div>
           </div>
           <div class="feature-card reveal">
-            <div class="feature-icon fi-cyan">
+            <div class="feature-icon"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="3" y="4" width="18" height="18" rx="2"/><path d="M16 2v4M8 2v4M3 10h18"/></svg></div>
-              <svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="3" y="4" width="18" height="18" rx="2"/><path d="M16 2v4M8 2v4M3 10h18"/></svg>
-            </div>
             <div class="feature-title">Schedule & Calendar</div>
             <div class="feature-desc">View what's airing today or fetch the full weekly broadcast schedule.</div>
           </div>
           <div class="feature-card reveal reveal-delay-1">
-            <div class="feature-icon fi-amber">
+            <div class="feature-icon"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polygon points="22 3 2 3 10 12.46 10 19 14 21 14 12.46 22 3"/></svg></div>
-              <svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polygon points="22 3 2 3 10 12.46 10 19 14 21 14 12.46 22 3"/></svg>
-            </div>
             <div class="feature-title">Advanced Filters</div>
             <div class="feature-desc">Filter by genre, type, status, season, sort order. Multi-select support.</div>
           </div>
           <div class="feature-card reveal reveal-delay-2">
-            <div class="feature-icon fi-indigo">
+            <div class="feature-icon"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M13 2L3 14h9l-1 8 10-12h-9l1-8z"/></svg></div>
-              <svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M13 2L3 14h9l-1 8 10-12h-9l1-8z"/></svg>
-            </div>
             <div class="feature-title">Fast & Cached</div>
-            <div class="feature-desc">In-memory cache with 5-minute TTL for snappy responses and reduced scraping overhead.</div>
+            <div class="feature-desc">In-memory cache with configurable TTL for snappy responses and reduced scraping overhead.</div>
           </div>
         </div>
       </div>
     </section>
 
-    <!-- Endpoints -->
+    <section class="section" id="endpoints" style="background:var(--surface-soft);border-top:1px solid var(--hairline);border-bottom:1px solid var(--hairline)">
-    <section class="section" id="endpoints" style="background:var(--bg2);border-top:1px solid var(--border);border-bottom:1px solid var(--border)">
       <div class="container">
         <div class="reveal">
-          <div class="section-label">
+          <div class="section-label">API Reference</div>
-            <svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="width:14px;height:14px"><polyline points="16 18 22 12 16 6"/><polyline points="8 6 2 12 8 18"/></svg>
-            API Reference
-          </div>
           <h2 class="section-title">Endpoints</h2>
-          <p class="section-desc">All endpoints return JSON. Base URL: <code style="color:var(--pink);background:rgba(236,72,153,.1);padding:2px 8px;border-radius:4px">https://anikototvapi.vercel.app/api</code></p>
+          <p class="section-desc">All endpoints return JSON. Base URL: <code style="color:var(--primary);background:rgba(204,120,92,.1);padding:2px 8px;border-radius:4px;font-family:var(--font-code);font-size:.85rem">https://anikototvapi.vercel.app/api</code></p>
         </div>
-
         <div class="explorer reveal" id="explorer">
           <div class="explorer-nav" id="explorerNav"></div>
           <div class="explorer-panel" id="explorerPanel"></div>
@@ -472,23 +390,17 @@ fetch("https://anikototvapi.vercel.app/api")
       </div>
     </section>
 
-    <!-- Playground -->
     <section class="section" id="playground">
       <div class="container">
         <div class="reveal">
-          <div class="section-label">
+          <div class="section-label">Interactive</div>
-            <svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="width:14px;height:14px"><polygon points="5 3 19 12 5 21 5 3"/></svg>
-            Interactive
-          </div>
           <h2 class="section-title">Playground</h2>
           <p class="section-desc">Test endpoints directly in your browser. No signup required.</p>
         </div>
-
         <div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(340px,1fr));gap:16px">
-          <!-- Search -->
           <div class="playground-card reveal">
             <div class="playground-header">
-              <svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="11" cy="11" r="8"/><path d="M21 21l-4.35-4.35"/></svg>
+              <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="11" cy="11" r="8"/><path d="M21 21l-4.35-4.35"/></svg>
               <h3>Search Anime</h3>
             </div>
             <div class="playground-body">
@@ -499,10 +411,9 @@ fetch("https://anikototvapi.vercel.app/api")
               <div class="playground-output" id="pgSearchOut"></div>
             </div>
           </div>
-          <!-- Stream -->
           <div class="playground-card reveal reveal-delay-1">
             <div class="playground-header">
-              <svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polygon points="5 3 19 12 5 21 5 3"/></svg>
+              <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polygon points="5 3 19 12 5 21 5 3"/></svg>
               <h3>Stream Servers</h3>
             </div>
             <div class="playground-body">
@@ -513,10 +424,9 @@ fetch("https://anikototvapi.vercel.app/api")
               <div class="playground-output" id="pgStreamOut"></div>
             </div>
           </div>
-          <!-- Random -->
           <div class="playground-card reveal reveal-delay-2">
             <div class="playground-header">
-              <svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M21 16V8a2 2 0 0 0-1-1.73l-7-4a2 2 0 0 0-2 0l-7 4A2 2 0 0 0 3 8v8a2 2 0 0 0 1 1.73l7 4a2 2 0 0 0 2 0l7-4A2 2 0 0 0 21 16z"/><path d="M3.27 6.96L12 12.01l8.73-5.05M12 22.08V12"/></svg>
+              <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M21 16V8a2 2 0 0 0-1-1.73l-7-4a2 2 0 0 0-2 0l-7 4A2 2 0 0 0 3 8v8a2 2 0 0 0 1 1.73l7 4a2 2 0 0 0 2 0l7-4A2 2 0 0 0 21 16z"/><path d="M3.27 6.96L12 12.01l8.73-5.05M12 22.08V12"/></svg>
               <h3>Random Anime</h3>
             </div>
             <div class="playground-body">
@@ -526,10 +436,9 @@ fetch("https://anikototvapi.vercel.app/api")
               <div class="playground-output" id="pgRandomOut"></div>
             </div>
           </div>
-          <!-- Schedule -->
           <div class="playground-card reveal reveal-delay-3">
             <div class="playground-header">
-              <svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="3" y="4" width="18" height="18" rx="2"/><path d="M16 2v4M8 2v4M3 10h18"/></svg>
+              <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="3" y="4" width="18" height="18" rx="2"/><path d="M16 2v4M8 2v4M3 10h18"/></svg>
               <h3>Schedule</h3>
             </div>
             <div class="playground-body">
@@ -544,19 +453,18 @@ fetch("https://anikototvapi.vercel.app/api")
       </div>
     </section>
 
-    <!-- CTA -->
     <section class="cta">
       <div class="container">
         <div class="cta-box reveal">
           <h2 class="cta-title">Start building with AniKotoAPI</h2>
           <p class="cta-desc">Free, open source, no API key required. Deploy your own instance or use ours.</p>
           <div class="cta-actions">
-            <a href="https://anikototvapi.vercel.app/api" target="_blank" class="btn btn-primary">
+            <a href="https://anikototvapi.vercel.app/api" target="_blank" class="btn btn-on-coral">
-              <svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="width:16px;height:16px"><path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6"/><polyline points="15 3 21 3 21 9"/><line x1="10" y1="14" x2="21" y2="3"/></svg>
+              <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="width:16px;height:16px"><path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6"/><polyline points="15 3 21 3 21 9"/><line x1="10" y1="14" x2="21" y2="3"/></svg>
               View API
             </a>
-            <a href="https://github.com/Shineii86/AniKotoAPI" target="_blank" class="btn btn-ghost">
+            <a href="https://github.com/Shineii86/AniKotoAPI" target="_blank" class="btn btn-on-coral">
-              <svg aria-hidden="true" viewBox="0 0 24 24" fill="currentColor" style="width:16px;height:16px"><path d="M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z"/></svg>
+              <svg viewBox="0 0 24 24" fill="currentColor" style="width:16px;height:16px"><path d="M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z"/></svg>
               Source Code
             </a>
           </div>
@@ -564,14 +472,12 @@ fetch("https://anikototvapi.vercel.app/api")
       </div>
     </section>
 
-    <!-- Footer -->
     <footer>
       <div class="container">
         <div class="footer-grid">
           <div class="footer-brand">
             <a href="/" class="logo">
-              <svg aria-hidden="true" viewBox="0 0 32 32" fill="none" width="24" height="24"><circle cx="16" cy="16" r="14" stroke="url(#g2)" stroke-width="2"/><path d="M10 20c0-4 3-7 6-7s6 3 6 7" stroke="url(#g2)" stroke-width="2" stroke-linecap="round"/><circle cx="12" cy="12" r="2" fill="var(--purple)"/><circle cx="20" cy="12" r="2" fill="var(--pink)"/><defs><linearGradient id="g2" x1="0" y1="0" x2="32" y2="32"><stop stop-color="var(--purple)"/><stop offset="1" stop-color="var(--pink)"/></linearGradient></defs></svg>
+              <span class="logo-mark"><span>*</span> AniKotoAPI</span>
-              <span class="logo-text"><span>AniKoto</span>API</span>
             </a>
             <p>Free REST API for anime data. Browse, search, and stream from AniKoto. Built with Node.js and deployed on Vercel.</p>
           </div>
@@ -600,7 +506,7 @@ fetch("https://anikototvapi.vercel.app/api")
           <span>&copy; 2026 AniKotoAPI. Educational use only.</span>
           <div class="footer-social">
             <a href="https://github.com/Shineii86/AniKotoAPI" target="_blank" aria-label="GitHub">
-              <svg aria-hidden="true" viewBox="0 0 24 24" fill="currentColor"><path d="M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z"/></svg>
+              <svg viewBox="0 0 24 24" fill="currentColor"><path d="M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z"/></svg>
             </a>
           </div>
         </div>
@@ -609,57 +515,57 @@ fetch("https://anikototvapi.vercel.app/api")
   </div>
 
   <script>
-    /* ── Particles ── */
+    const BASE = 'https://anikototvapi.vercel.app/api';
-    const canvas = document.getElementById('particles');
+    const endpoints = {
-    const ctx = canvas.getContext('2d');
+      home: { url: '/', label: 'Home' },
-    let particles = [];
+      search: { url: '/search?keyword=naruto', label: 'Search' },
-    function resizeCanvas() { canvas.width = window.innerWidth; canvas.height = window.innerHeight; }
+      stream: { url: '/stream?id=naruto-ep-1', label: 'Stream' },
-    window.addEventListener('resize', resizeCanvas);
+      random: { url: '/random', label: 'Random' },
-    resizeCanvas();
+      schedule: { url: '/schedule', label: 'Schedule' }
-    class Particle {
+    };
-      constructor() { this.reset(); }
+
-      reset() {
+    function setEndpoint(key, event) {
-        this.x = Math.random() * canvas.width;
+      const ep = endpoints[key];
-        this.y = Math.random() * canvas.height;
+      document.getElementById('consoleInput').value = `// ${ep.label}\nfetch("${BASE}${ep.url}")\n  .then(r => r.json())\n  .then(data => console.log(data));`;
-        this.size = Math.random() * 1.5 + .5;
+      document.querySelectorAll('.console-btn').forEach(b => b.classList.remove('active'));
-        this.speedX = (Math.random() - .5) * .3;
+      event.target.classList.add('active');
-        this.speedY = (Math.random() - .5) * .3;
+    }
-        this.opacity = Math.random() * .3 + .1;
+
-      }
+    async function runConsole() {
-      update() {
+      const out = document.getElementById('consoleOutput');
-        this.x += this.speedX;
+      out.innerHTML = '<span style="color:var(--accent-amber)">Loading...</span>';
-        this.y += this.speedY;
+      const input = document.getElementById('consoleInput').value;
-        if (this.x < 0 || this.x > canvas.width || this.y < 0 || this.y > canvas.height) this.reset();
+      const urlMatch = input.match(/fetch\("([^"]+)"\)/);
-      }
+      if (!urlMatch) { out.innerHTML = '<span style="color:var(--error)">No fetch URL found</span>'; return; }
-      draw() {
+      try {
-        ctx.beginPath();
+        const res = await fetch(urlMatch[1]);
-        ctx.arc(this.x, this.y, this.size, 0, Math.PI * 2);
+        const data = await res.json();
-        ctx.fillStyle = `rgba(168,85,247,${this.opacity})`;
+        out.innerHTML = syntaxHighlight(JSON.stringify(data, null, 2));
-        ctx.fill();
+        out.scrollTop = out.scrollHeight;
+      } catch (e) {
+        out.innerHTML = `<span style="color:var(--error)">Error: ${e.message}</span>`;
       }
     }
-    for (let i = 0; i < 60; i++) particles.push(new Particle());
+
-    function animateParticles() {
+    function syntaxHighlight(json) {
-      ctx.clearRect(0, 0, canvas.width, canvas.height);
+      return json.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
-      particles.forEach(p => { p.update(); p.draw(); });
+        .replace(/"([^"]+)"(?=\s*:)/g, '<span style="color:var(--accent-amber)">"$1"</span>')
-      requestAnimationFrame(animateParticles);
+        .replace(/: "([^"]*)"/g, ': <span style="color:var(--accent-teal)">"$1"</span>')
+        .replace(/: (\d+)/g, ': <span style="color:var(--primary)">$1</span>')
+        .replace(/: (true|false|null)/g, ': <span style="color:var(--on-dark-soft)">$1</span>');
     }
-    animateParticles();
 
-    /* ── Header Scroll ── */
     const header = document.getElementById('header');
     window.addEventListener('scroll', () => {
       header.classList.toggle('scrolled', window.scrollY > 20);
     });
 
-    /* ── Scroll Reveal ── */
     const reveals = document.querySelectorAll('.reveal');
     const revealObserver = new IntersectionObserver((entries) => {
       entries.forEach(e => { if (e.isIntersecting) { e.target.classList.add('visible'); revealObserver.unobserve(e.target); } });
     }, { threshold: .1, rootMargin: '0px 0px -40px 0px' });
     reveals.forEach(el => revealObserver.observe(el));
 
-    /* ── Animated Counters ── */
     document.querySelectorAll('[data-count]').forEach(el => {
       const target = parseInt(el.dataset.count);
       const obs = new IntersectionObserver(([e]) => {
@@ -677,62 +583,19 @@ fetch("https://anikototvapi.vercel.app/api")
       obs.observe(el);
     });
 
-    /* ── Console ── */
-    const BASE = 'https://anikototvapi.vercel.app/api';
-    const endpoints = {
-      home: { url: '/', label: 'Home' },
-      search: { url: '/search?keyword=naruto', label: 'Search' },
-      stream: { url: '/stream?id=naruto-ep-1', label: 'Stream' },
-      random: { url: '/random', label: 'Random' },
-      schedule: { url: '/schedule', label: 'Schedule' }
-    };
-    function setEndpoint(key, event) {
-      const ep = endpoints[key];
-      document.getElementById('consoleInput').value = `// ${ep.label}\nfetch("${BASE}${ep.url}")\n  .then(r => r.json())\n  .then(data => console.log(data));`;
-      document.querySelectorAll('.console-btn').forEach(b => b.classList.remove('active'));
-      event.target.classList.add('active');
-    }
-    async function runConsole() {
-      const out = document.getElementById('consoleOutput');
-      out.innerHTML = '<span style="color:var(--amber)">Loading...</span>';
-      const input = document.getElementById('consoleInput').value;
-      const urlMatch = input.match(/fetch\("([^"]+)"\)/);
-      if (!urlMatch) { out.innerHTML = '<span style="color:var(--red)">No fetch URL found</span>'; return; }
-      try {
-        const res = await fetch(urlMatch[1]);
-        const data = await res.json();
-        out.innerHTML = syntaxHighlight(JSON.stringify(data, null, 2));
-        out.scrollTop = out.scrollHeight;
-        function escapeHtml(s) { return s.replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/>/g,"&gt;"); }
-      } catch (e) {
-        out.innerHTML = `<span style="color:var(--red)">Error: ${e.message}</span>`;
-      }
-    }
-    function syntaxHighlight(json) {
-      return json.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
-        .replace(/"([^"]+)"(?=\s*:)/g, '<span style="color:var(--pink)">"$1"</span>')
-        .replace(/: "([^"]*)"/g, ': <span style="color:var(--green)">"$1"</span>')
-        .replace(/: (\d+)/g, ': <span style="color:var(--amber)">$1</span>')
-        .replace(/: (true|false|null)/g, ': <span style="color:var(--cyan)">$1</span>');
-    }
-
-    /* ── Explorer ── */
     const explorerData = [
       { id: 'home', title: 'Home Info', desc: 'Spotlight, trending, popular, top-airing, genres, and more.', path: '/', params: [], code: { curl: 'curl https://anikototvapi.vercel.app/api', js: 'const res = await fetch("https://anikototvapi.vercel.app/api");\nconst data = await res.json();\nconsole.log(data.trending);', python: 'import requests\nr = requests.get("https://anikototvapi.vercel.app/api")\nprint(r.json()["trending"])' } },
       { id: 'search', title: 'Search', desc: 'Search anime by keyword with pagination.', path: '/search?keyword={q}&page={n}', params: [{ name: 'keyword', type: 'string', desc: 'Search query' }, { name: 'page', type: 'number', desc: 'Page (default 1)' }], code: { curl: 'curl "https://anikototvapi.vercel.app/api/search?keyword=naruto"', js: 'const res = await fetch("https://anikototvapi.vercel.app/api/search?keyword=naruto");\nconst data = await res.json();', python: 'import requests\nr = requests.get("https://anikototvapi.vercel.app/api/search", params={"keyword": "naruto"})\nprint(r.json())' } },
-      { id: 'suggest', title: 'Search Suggest', desc: 'Autocomplete suggestions for search.', path: '/search/suggest?keyword={q}', params: [{ name: 'keyword', type: 'string', desc: 'Partial query' }], code: { curl: 'curl "https://anikototvapi.vercel.app/api/search/suggest?keyword=dea"', js: 'const res = await fetch("https://anikototvapi.vercel.app/api/search/suggest?keyword=dea");\nconst data = await res.json();', python: 'import requests\nr = requests.get("https://anikototvapi.vercel.app/api/search/suggest", params={"keyword": "dea"})\nprint(r.json())' } },
       { id: 'info', title: 'Anime Info', desc: 'Detailed info: synopsis, genres, relations, recommendations.', path: '/info?id={slug}', params: [{ name: 'id', type: 'string', desc: 'Anime slug' }], code: { curl: 'curl "https://anikototvapi.vercel.app/api/info?id=naruto"', js: 'const res = await fetch("https://anikototvapi.vercel.app/api/info?id=naruto");\nconst data = await res.json();', python: 'import requests\nr = requests.get("https://anikototvapi.vercel.app/api/info", params={"id": "naruto"})\nprint(r.json())' } },
-      { id: 'episodes', title: 'Episodes', desc: 'Episode list loaded via AJAX.', path: '/episodes/{slug}', params: [{ name: 'slug', type: 'string', desc: 'Anime slug' }], code: { curl: 'curl "https://anikototvapi.vercel.app/api/episodes/naruto"', js: 'const res = await fetch("https://anikototvapi.vercel.app/api/episodes/naruto");\nconst data = await res.json();', python: 'import requests\nr = requests.get("https://anikototvapi.vercel.app/api/episodes/naruto")\nprint(r.json())' } },
+      { id: 'episodes', title: 'Episodes', desc: 'Episode list loaded via AJAX.', path: '/episodes/{animeId}', params: [{ name: 'animeId', type: 'number', desc: 'Anime ID' }], code: { curl: 'curl "https://anikototvapi.vercel.app/api/episodes/958"', js: 'const res = await fetch("https://anikototvapi.vercel.app/api/episodes/958");\nconst data = await res.json();', python: 'import requests\nr = requests.get("https://anikototvapi.vercel.app/api/episodes/958")\nprint(r.json())' } },
-      { id: 'stream', title: 'Stream Servers', desc: 'Streaming servers for an episode.', path: '/stream?id={episodeId}', params: [{ name: 'id', type: 'string', desc: 'Episode ID' }], code: { curl: 'curl "https://anikototvapi.vercel.app/api/stream?id=naruto-ep-1"', js: 'const res = await fetch("https://anikototvapi.vercel.app/api/stream?id=naruto-ep-1");\nconst data = await res.json();', python: 'import requests\nr = requests.get("https://anikototvapi.vercel.app/api/stream", params={"id": "naruto-ep-1"})\nprint(r.json())' } },
+      { id: 'stream', title: 'Stream Servers', desc: 'Streaming servers for an episode.', path: '/stream?id={linkId}', params: [{ name: 'id', type: 'string', desc: 'Link ID from servers' }], code: { curl: 'curl "https://anikototvapi.vercel.app/api/stream?id=MTF1d..."', js: 'const res = await fetch("https://anikototvapi.vercel.app/api/stream?id=MTF1d...");\nconst data = await res.json();', python: 'import requests\nr = requests.get("https://anikototvapi.vercel.app/api/stream", params={"id": "MTF1d..."})\nprint(r.json())' } },
-      { id: 'servers', title: 'Servers', desc: 'Resolve streaming server links.', path: '/servers?ids={ids}', params: [{ name: 'ids', type: 'string', desc: 'Comma-separated link IDs' }], code: { curl: 'curl "https://anikototvapi.vercel.app/api/servers?ids=123,456"', js: 'const res = await fetch("https://anikototvapi.vercel.app/api/servers?ids=123,456");\nconst data = await res.json();', python: 'import requests\nr = requests.get("https://anikototvapi.vercel.app/api/servers", params={"ids": "123,456"})\nprint(r.json())' } },
+      { id: 'servers', title: 'Servers', desc: 'Resolve streaming server links.', path: '/servers?ids={serverIds}', params: [{ name: 'ids', type: 'string', desc: 'Server IDs from episodes' }], code: { curl: 'curl "https://anikototvapi.vercel.app/api/servers?ids=SlNVT..."', js: 'const res = await fetch("https://anikototvapi.vercel.app/api/servers?ids=SlNVT...");\nconst data = await res.json();', python: 'import requests\nr = requests.get("https://anikototvapi.vercel.app/api/servers", params={"ids": "SlNVT..."})\nprint(r.json())' } },
       { id: 'schedule', title: 'Schedule', desc: 'Anime schedule for a specific date.', path: '/schedule?date={YYYY-MM-DD}', params: [{ name: 'date', type: 'string', desc: 'Date (default today)' }], code: { curl: 'curl "https://anikototvapi.vercel.app/api/schedule"', js: 'const res = await fetch("https://anikototvapi.vercel.app/api/schedule");\nconst data = await res.json();', python: 'import requests\nr = requests.get("https://anikototvapi.vercel.app/api/schedule")\nprint(r.json())' } },
       { id: 'topten', title: 'Top 10', desc: 'Top 10 anime (today, week, month).', path: '/top-ten', params: [], code: { curl: 'curl "https://anikototvapi.vercel.app/api/top-ten"', js: 'const res = await fetch("https://anikototvapi.vercel.app/api/top-ten");\nconst data = await res.json();', python: 'import requests\nr = requests.get("https://anikototvapi.vercel.app/api/top-ten")\nprint(r.json())' } },
       { id: 'random', title: 'Random', desc: 'Random anime info.', path: '/random', params: [], code: { curl: 'curl "https://anikototvapi.vercel.app/api/random"', js: 'const res = await fetch("https://anikototvapi.vercel.app/api/random");\nconst data = await res.json();', python: 'import requests\nr = requests.get("https://anikototvapi.vercel.app/api/random")\nprint(r.json())' } },
       { id: 'filter', title: 'Filter', desc: 'Filter by genre, type, status, season.', path: '/filter?keyword={q}&genre[]={g}', params: [{ name: 'keyword', type: 'string', desc: 'Search keyword (required)' }, { name: 'genre[]', type: 'number', desc: 'Genre IDs' }, { name: 'type[]', type: 'number', desc: 'Type IDs' }], code: { curl: 'curl "https://anikototvapi.vercel.app/api/filter?keyword=&genre[]=1&genre[]=4"', js: 'const res = await fetch("https://anikototvapi.vercel.app/api/filter?keyword=&genre[]=1");\nconst data = await res.json();', python: 'import requests\nr = requests.get("https://anikototvapi.vercel.app/api/filter", params={"keyword": "", "genre[]": 1})\nprint(r.json())' } },
       { id: 'popular', title: 'Most Popular', desc: 'Most popular anime list.', path: '/most-popular?page={n}', params: [{ name: 'page', type: 'number', desc: 'Page (default 1)' }], code: { curl: 'curl "https://anikototvapi.vercel.app/api/most-popular"', js: 'const res = await fetch("https://anikototvapi.vercel.app/api/most-popular");\nconst data = await res.json();', python: 'import requests\nr = requests.get("https://anikototvapi.vercel.app/api/most-popular")\nprint(r.json())' } },
       { id: 'genre', title: 'Genre', desc: 'Anime by genre.', path: '/genre/{name}', params: [{ name: 'name', type: 'string', desc: 'Genre slug (action, comedy, etc.)' }], code: { curl: 'curl "https://anikototvapi.vercel.app/api/genre/action"', js: 'const res = await fetch("https://anikototvapi.vercel.app/api/genre/action");\nconst data = await res.json();', python: 'import requests\nr = requests.get("https://anikototvapi.vercel.app/api/genre/action")\nprint(r.json())' } },
-      { id: 'type', title: 'Type', desc: 'Anime by type.', path: '/type/{name}', params: [{ name: 'name', type: 'string', desc: 'Type (tv, movie, ova, etc.)' }], code: { curl: 'curl "https://anikototvapi.vercel.app/api/type/tv"', js: 'const res = await fetch("https://anikototvapi.vercel.app/api/type/tv");\nconst data = await res.json();', python: 'import requests\nr = requests.get("https://anikototvapi.vercel.app/api/type/tv")\nprint(r.json())' } },
-      { id: 'status', title: 'Status', desc: 'Anime by status.', path: '/status/{name}', params: [{ name: 'name', type: 'string', desc: 'Status (currently-airing, finished-airing)' }], code: { curl: 'curl "https://anikototvapi.vercel.app/api/status/currently-airing"', js: 'const res = await fetch("https://anikototvapi.vercel.app/api/status/currently-airing");\nconst data = await res.json();', python: 'import requests\nr = requests.get("https://anikototvapi.vercel.app/api/status/currently-airing")\nprint(r.json())' } },
     ];
     const navEl = document.getElementById('explorerNav');
     const panelEl = document.getElementById('explorerPanel');
@@ -753,6 +616,7 @@ fetch("https://anikototvapi.vercel.app/api")
         </div>
         <div class="explorer-code" id="explorerCode">${ep.code[activeLang]}</div>`;
     }
+
     function switchLang(lang, btn) {
       activeLang = lang;
       document.querySelectorAll('.code-tab').forEach(b => b.classList.remove('active'));
@@ -760,11 +624,12 @@ fetch("https://anikototvapi.vercel.app/api")
       const activeEp = explorerData.find(e => e.id === navEl.querySelector('.active')?.dataset.id) || explorerData[0];
       document.getElementById('explorerCode').textContent = activeEp.code[lang];
     }
+
     explorerData.forEach((ep, i) => {
       const btn = document.createElement('button');
       btn.className = `explorer-nav-btn ${i===0?'active':''}`;
       btn.dataset.id = ep.id;
-      btn.innerHTML = `<svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="16 18 22 12 16 6"/><polyline points="8 6 2 12 8 18"/></svg>${ep.title}`;
+      btn.innerHTML = `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="16 18 22 12 16 6"/><polyline points="8 6 2 12 8 18"/></svg>${ep.title}`;
       btn.onclick = () => {
         navEl.querySelectorAll('.explorer-nav-btn').forEach(b => b.classList.remove('active'));
         btn.classList.add('active');
@@ -774,7 +639,6 @@ fetch("https://anikototvapi.vercel.app/api")
     });
     renderExplorer(explorerData[0]);
 
-    /* ── Playground ── */
     async function pgRun(type) {
       let url, outEl;
       if (type === 'search') {
@@ -796,15 +660,16 @@ fetch("https://anikototvapi.vercel.app/api")
         outEl = document.getElementById('pgScheduleOut');
       }
       outEl.classList.add('visible');
-      outEl.innerHTML = '<span style="color:var(--amber)">Loading...</span>';
+      outEl.innerHTML = '<span style="color:var(--accent-amber)">Loading...</span>';
       try {
         const res = await fetch(url);
         const data = await res.json();
         outEl.innerHTML = syntaxHighlight(JSON.stringify(data, null, 2));
       } catch (e) {
-        outEl.innerHTML = `<span style="color:var(--red)">Error: ${e.message}</span>`;
+        outEl.innerHTML = `<span style="color:var(--error)">Error: ${e.message}</span>`;
       }
     }
+
     document.getElementById('pgSearch')?.addEventListener('keydown', e => { if (e.key === 'Enter') pgRun('search'); });
     document.getElementById('pgStream')?.addEventListener('keydown', e => { if (e.key === 'Enter') pgRun('stream'); });
   </script>

public/privacy.html

@@ -9,40 +9,46 @@
   <meta name="twitter:card" content="summary" />
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
   <title>Privacy Policy — AniKotoAPI</title>
-  <meta name="theme-color" content="#0A0A12" />
+  <meta name="theme-color" content="#faf9f5" />
   <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
   <link rel="preconnect" href="https://fonts.googleapis.com" />
   <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
-  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet" />
+  <link href="https://fonts.googleapis.com/css2?family=Cormorant+Garamond:wght@400;500;600;700&family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet" />
   <style>
-    :root{--bg:#0A0A12;--bg2:#111120;--text:#E2E8F0;--text2:#94A3B8;--text3:#64748B;--purple:#A855F7;--pink:#EC4899;--border:rgba(255,255,255,.06);--glass:rgba(255,255,255,.03)}
+    :root{
+      --canvas:#faf9f5;--surface-card:#efe9de;--hairline:#e6dfd8;
+      --ink:#141413;--body:#3d3d3a;--muted:#6c6a64;--muted-soft:#8e8b82;
+      --primary:#cc785c;--primary-active:#a9583e;
+      --surface-dark:#181715;--on-dark:#faf9f5;--on-dark-soft:#a09d96;
+      --font-display:'Cormorant Garamond',Garamond,'Times New Roman',serif;
+      --font-body:'Inter',-apple-system,BlinkMacSystemFont,sans-serif;
+      --font-code:'JetBrains Mono',monospace;
+    }
     *{margin:0;padding:0;box-sizing:border-box}
-    body{font-family:'Inter',system-ui,sans-serif;background:var(--bg);color:var(--text);line-height:1.8}
+    body{font-family:var(--font-body);background:var(--canvas);color:var(--body);line-height:1.8}
-    .ambient{position:fixed;inset:0;pointer-events:none;z-index:0}
+    header{position:sticky;top:0;z-index:100;background:var(--canvas);border-bottom:1px solid var(--hairline);padding:0 24px}
-    .orb{position:absolute;border-radius:50%;filter:blur(120px);opacity:.08}
+    .header-inner{max-width:720px;margin:0 auto;display:flex;align-items:center;height:64px}
-    .orb-1{width:500px;height:500px;background:var(--purple);top:-150px;left:-100px}
+    .logo{display:flex;align-items:center;gap:8px;text-decoration:none;color:var(--ink)}
-    .orb-2{width:400px;height:400px;background:var(--pink);bottom:-100px;right:-80px}
+    .logo-mark{font-family:var(--font-display);font-size:1.2rem;font-weight:600;letter-spacing:-.02em}
-    header{position:sticky;top:0;z-index:100;background:rgba(10,10,18,.88);backdrop-filter:blur(24px);border-bottom:1px solid var(--border);padding:0 24px}
+    .logo-mark span{color:var(--primary)}
-    .header-inner{max-width:720px;margin:0 auto;display:flex;align-items:center;height:60px}
-    .logo{display:flex;align-items:center;gap:10px;text-decoration:none;color:var(--text);font-weight:700;font-size:1rem}
-    .logo span{background:linear-gradient(135deg,var(--purple),var(--pink));-webkit-background-clip:text;-webkit-text-fill-color:transparent}
     .content{position:relative;z-index:1;max-width:720px;margin:0 auto;padding:60px 24px 80px}
-    h1{font-size:2rem;font-weight:800;letter-spacing:-.03em;margin-bottom:8px}
+    h1{font-family:var(--font-display);font-size:2.2rem;font-weight:400;letter-spacing:-.02em;margin-bottom:8px;color:var(--ink)}
-    .updated{color:var(--text3);font-size:.82rem;margin-bottom:40px;font-family:'JetBrains Mono',monospace}
+    .updated{color:var(--muted-soft);font-size:.82rem;margin-bottom:40px;font-family:var(--font-code)}
-    h2{font-size:1.2rem;font-weight:700;margin:32px 0 12px;padding-top:16px;border-top:1px solid var(--border)}
+    h2{font-family:var(--font-display);font-size:1.2rem;font-weight:500;margin:32px 0 12px;padding-top:16px;border-top:1px solid var(--hairline);color:var(--ink)}
     h2:first-of-type{border-top:none;padding-top:0}
-    p{color:var(--text2);font-size:.92rem;margin-bottom:16px}
+    p{color:var(--body);font-size:.92rem;margin-bottom:16px}
-    ul{color:var(--text2);font-size:.92rem;margin:0 0 16px 20px}
+    ul{color:var(--body);font-size:.92rem;margin:0 0 16px 20px}
     li{margin-bottom:6px}
-    code{font-family:'JetBrains Mono',monospace;font-size:.82rem;background:rgba(168,85,247,.1);color:var(--purple);padding:2px 6px;border-radius:4px}
+    code{font-family:var(--font-code);font-size:.82rem;background:rgba(204,120,92,.08);color:var(--primary);padding:2px 6px;border-radius:4px}
-    a{color:var(--purple);text-decoration:none}
+    a{color:var(--primary);text-decoration:none}
     a:hover{text-decoration:underline}
-    footer{position:relative;z-index:1;border-top:1px solid var(--border);padding:24px;text-align:center;color:var(--text3);font-size:.75rem}
+    strong{color:var(--ink)}
+    footer{position:relative;z-index:1;border-top:1px solid var(--hairline);padding:24px;text-align:center;color:var(--muted-soft);font-size:.75rem}
+    footer a{color:var(--primary)}
   </style>
 </head>
 <body>
-  <div class="ambient"><div class="orb orb-1"></div><div class="orb orb-2"></div></div>
+  <header><div class="header-inner"><a href="/" class="logo"><span class="logo-mark"><span>*</span> AniKotoAPI</span></a></div></header>
-  <header><div class="header-inner"><a href="/" class="logo">⛩ <span>AniKoto</span>API</a></div></header>
   <div class="content">
     <h1>Privacy Policy</h1>
     <div class="updated">Last updated: 2026-06-08</div>
@@ -83,6 +89,6 @@
     <h2>8. Contact</h2>
     <p>For questions about this Privacy Policy, open an issue at <a href="https://github.com/Shineii86/AniKotoAPI/issues" target="_blank" rel="noopener noreferrer">github.com/Shineii86/AniKotoAPI/issues</a>.</p>
   </div>
-  <footer>&copy; 2026 AniKotoAPI &middot; <a href="/" style="color:var(--purple)">Home</a> &middot; <a href="/tos" style="color:var(--purple)">Terms</a></footer>
+  <footer>&copy; 2026 AniKotoAPI &middot; <a href="/">Home</a> &middot; <a href="/tos">Terms</a></footer>
 </body>
 </html>

public/sitemap.xml

@@ -2,25 +2,25 @@
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
   <url>
     <loc>https://anikototvapi.vercel.app/</loc>
-    <lastmod>2026-06-08</lastmod>
+    <lastmod>2026-07-04</lastmod>
     <changefreq>weekly</changefreq>
     <priority>1.0</priority>
   </url>
   <url>
     <loc>https://anikototvapi.vercel.app/api</loc>
-    <lastmod>2026-06-08</lastmod>
+    <lastmod>2026-07-04</lastmod>
     <changefreq>daily</changefreq>
     <priority>0.9</priority>
   </url>
   <url>
     <loc>https://anikototvapi.vercel.app/privacy</loc>
-    <lastmod>2026-06-08</lastmod>
+    <lastmod>2026-07-04</lastmod>
     <changefreq>monthly</changefreq>
     <priority>0.3</priority>
   </url>
   <url>
     <loc>https://anikototvapi.vercel.app/tos</loc>
-    <lastmod>2026-06-08</lastmod>
+    <lastmod>2026-07-04</lastmod>
     <changefreq>monthly</changefreq>
     <priority>0.3</priority>
   </url>

public/tos.html

@@ -9,41 +9,46 @@
   <meta name="twitter:card" content="summary" />
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
   <title>Terms of Service — AniKotoAPI</title>
-  <meta name="theme-color" content="#0A0A12" />
+  <meta name="theme-color" content="#faf9f5" />
   <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
   <link rel="preconnect" href="https://fonts.googleapis.com" />
   <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
-  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet" />
+  <link href="https://fonts.googleapis.com/css2?family=Cormorant+Garamond:wght@400;500;600;700&family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet" />
   <style>
-    :root{--bg:#0A0A12;--bg2:#111120;--text:#E2E8F0;--text2:#94A3B8;--text3:#64748B;--purple:#A855F7;--pink:#EC4899;--border:rgba(255,255,255,.06);--glass:rgba(255,255,255,.03)}
+    :root{
+      --canvas:#faf9f5;--surface-card:#efe9de;--hairline:#e6dfd8;
+      --ink:#141413;--body:#3d3d3a;--muted:#6c6a64;--muted-soft:#8e8b82;
+      --primary:#cc785c;--primary-active:#a9583e;
+      --surface-dark:#181715;--on-dark:#faf9f5;--on-dark-soft:#a09d96;
+      --font-display:'Cormorant Garamond',Garamond,'Times New Roman',serif;
+      --font-body:'Inter',-apple-system,BlinkMacSystemFont,sans-serif;
+      --font-code:'JetBrains Mono',monospace;
+    }
     *{margin:0;padding:0;box-sizing:border-box}
-    body{font-family:'Inter',system-ui,sans-serif;background:var(--bg);color:var(--text);line-height:1.8}
+    body{font-family:var(--font-body);background:var(--canvas);color:var(--body);line-height:1.8}
-    .ambient{position:fixed;inset:0;pointer-events:none;z-index:0}
+    header{position:sticky;top:0;z-index:100;background:var(--canvas);border-bottom:1px solid var(--hairline);padding:0 24px}
-    .orb{position:absolute;border-radius:50%;filter:blur(120px);opacity:.08}
+    .header-inner{max-width:720px;margin:0 auto;display:flex;align-items:center;height:64px}
-    .orb-1{width:500px;height:500px;background:var(--purple);top:-150px;left:-100px}
+    .logo{display:flex;align-items:center;gap:8px;text-decoration:none;color:var(--ink)}
-    .orb-2{width:400px;height:400px;background:var(--pink);bottom:-100px;right:-80px}
+    .logo-mark{font-family:var(--font-display);font-size:1.2rem;font-weight:600;letter-spacing:-.02em}
-    header{position:sticky;top:0;z-index:100;background:rgba(10,10,18,.88);backdrop-filter:blur(24px);border-bottom:1px solid var(--border);padding:0 24px}
+    .logo-mark span{color:var(--primary)}
-    .header-inner{max-width:720px;margin:0 auto;display:flex;align-items:center;height:60px}
-    .logo{display:flex;align-items:center;gap:10px;text-decoration:none;color:var(--text);font-weight:700;font-size:1rem}
-    .logo span{background:linear-gradient(135deg,var(--purple),var(--pink));-webkit-background-clip:text;-webkit-text-fill-color:transparent}
     .content{position:relative;z-index:1;max-width:720px;margin:0 auto;padding:60px 24px 80px}
-    h1{font-size:2rem;font-weight:800;letter-spacing:-.03em;margin-bottom:8px}
+    h1{font-family:var(--font-display);font-size:2.2rem;font-weight:400;letter-spacing:-.02em;margin-bottom:8px;color:var(--ink)}
-    .updated{color:var(--text3);font-size:.82rem;margin-bottom:40px;font-family:'JetBrains Mono',monospace}
+    .updated{color:var(--muted-soft);font-size:.82rem;margin-bottom:40px;font-family:var(--font-code)}
-    h2{font-size:1.2rem;font-weight:700;margin:32px 0 12px;padding-top:16px;border-top:1px solid var(--border)}
+    h2{font-family:var(--font-display);font-size:1.2rem;font-weight:500;margin:32px 0 12px;padding-top:16px;border-top:1px solid var(--hairline);color:var(--ink)}
     h2:first-of-type{border-top:none;padding-top:0}
-    p{color:var(--text2);font-size:.92rem;margin-bottom:16px}
+    p{color:var(--body);font-size:.92rem;margin-bottom:16px}
-    ul{color:var(--text2);font-size:.92rem;margin:0 0 16px 20px}
+    ul{color:var(--body);font-size:.92rem;margin:0 0 16px 20px}
     li{margin-bottom:6px}
-    code{font-family:'JetBrains Mono',monospace;font-size:.82rem;background:rgba(168,85,247,.1);color:var(--purple);padding:2px 6px;border-radius:4px}
+    code{font-family:var(--font-code);font-size:.82rem;background:rgba(204,120,92,.08);color:var(--primary);padding:2px 6px;border-radius:4px}
-    a{color:var(--purple);text-decoration:none}
+    a{color:var(--primary);text-decoration:none}
     a:hover{text-decoration:underline}
-    strong{color:var(--text)}
+    strong{color:var(--ink)}
-    footer{position:relative;z-index:1;border-top:1px solid var(--border);padding:24px;text-align:center;color:var(--text3);font-size:.75rem}
+    footer{position:relative;z-index:1;border-top:1px solid var(--hairline);padding:24px;text-align:center;color:var(--muted-soft);font-size:.75rem}
+    footer a{color:var(--primary)}
   </style>
 </head>
 <body>
-  <div class="ambient"><div class="orb orb-1"></div><div class="orb orb-2"></div></div>
+  <header><div class="header-inner"><a href="/" class="logo"><span class="logo-mark"><span>*</span> AniKotoAPI</span></a></div></header>
-  <header><div class="header-inner"><a href="/" class="logo">⛩ <span>AniKoto</span>API</a></div></header>
   <div class="content">
     <h1>Terms of Service</h1>
     <div class="updated">Last updated: 2026-06-08</div>
@@ -94,6 +99,6 @@
     <h2>13. Contact</h2>
     <p>For questions about these Terms, open an issue at <a href="https://github.com/Shineii86/AniKotoAPI/issues" target="_blank" rel="noopener noreferrer">github.com/Shineii86/AniKotoAPI/issues</a>.</p>
   </div>
-  <footer>&copy; 2026 AniKotoAPI &middot; <a href="/" style="color:var(--purple)">Home</a> &middot; <a href="/privacy" style="color:var(--purple)">Privacy</a></footer>
+  <footer>&copy; 2026 AniKotoAPI &middot; <a href="/">Home</a> &middot; <a href="/privacy">Privacy</a></footer>
 </body>
 </html>

server.js

@@ -18,12 +18,15 @@
 
 import dotenv from "dotenv";
 import express from "express";
-import cors from "cors";
+import compression from "compression";
 import path from "path";
 import fs from "fs";
+import crypto from "crypto";
 import { fileURLToPath } from "url";
 import { dirname } from "path";
 import { createApiRoutes } from "./src/routes/apiRoutes.js";
+import { getCacheStats } from "./src/helper/cache.helper.js";
+import { addCreatorInfo } from "./src/middleware/creatorInfo.js";
 
 dotenv.config();
 
@@ -39,6 +42,31 @@ const publicDir = path.join(process.cwd(), "public");
 const has404File = fs.existsSync(path.join(publicDir, "404.html"));
 const allowedOrigins = process.env.ALLOWED_ORIGINS?.split(",");
 
+// ---- FEATURE: Response compression ----
+app.use(compression({
+  filter: (req, res) => {
+    if (req.headers["x-no-compression"]) return false;
+    return compression.filter(req, res);
+  },
+  level: 6,
+  threshold: 1024
+}));
+
+// ---- FEATURE: Request body size limits ----
+app.use(express.json({ limit: "10kb" }));
+app.use(express.urlencoded({ extended: false, limit: "10kb" }));
+
+// ══════════════════════════════════════════════════════════════
+// REQUEST ID TRACKING
+// ══════════════════════════════════════════════════════════════
+
+// ---- FEATURE: Unique request ID for debugging ----
+app.use((req, res, next) => {
+  req.id = crypto.randomUUID();
+  res.setHeader("X-Request-Id", req.id);
+  next();
+});
+
 // ══════════════════════════════════════════════════════════════
 // CORS MIDDLEWARE
 // ══════════════════════════════════════════════════════════════
@@ -46,11 +74,11 @@ const allowedOrigins = process.env.ALLOWED_ORIGINS?.split(",");
 // NOTE: Single unified CORS middleware — handles all origin validation
 app.use((req, res, next) => {
   const origin = req.headers.origin;
-  if (allowedOrigins && (allowedOrigins.includes("*") || (origin && allowedOrigins.includes(origin)))) {
+  if (!allowedOrigins || allowedOrigins.includes("*") || (origin && allowedOrigins.includes(origin))) {
     res.setHeader("Access-Control-Allow-Origin", origin || "*");
   }
-  res.setHeader("Access-Control-Allow-Methods", "GET");
+  res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
-  res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+  res.setHeader("Access-Control-Allow-Headers", "Content-Type, X-Requested-With");
   if (req.method === "OPTIONS") {
     return res.status(204).end();
   }
@@ -64,6 +92,9 @@ app.use((req, res, next) => {
   res.setHeader("X-XSS-Protection", "1; mode=block");
   res.setHeader("Referrer-Policy", "strict-origin-when-cross-origin");
   res.setHeader("Permissions-Policy", "camera=(), microphone=(), geolocation=()");
+  res.setHeader("Content-Security-Policy", "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:; connect-src 'self'");
+  res.setHeader("Strict-Transport-Security", "max-age=31536000; includeSubDomains");
+  res.setHeader("X-Permitted-Cross-Domain-Policies", "none");
   next();
 });
 
@@ -117,22 +148,62 @@ const jsonError = (res, message = "Internal server error", status = 500) =>
 // API ROUTES
 // ══════════════════════════════════════════════════════════════
 
-// ---- FEATURE: Rate limiting (100 requests per minute per IP) ----
+// ---- FEATURE: Rate limiting (configurable, default 100 requests per minute per IP) ----
 const requestCounts = new Map();
+const RATE_LIMIT = parseInt(process.env.RATE_LIMIT) || 100;
+const RATE_WINDOW = parseInt(process.env.RATE_WINDOW) || 60000;
+
+// ---- FEATURE: Rate limiter cleanup interval (every 5 minutes) ----
+const RATE_CLEANUP_INTERVAL = 300000;
+setInterval(() => {
+  const now = Date.now();
+  for (const [ip, timestamps] of requestCounts.entries()) {
+    const validTimestamps = timestamps.filter(t => now - t < RATE_WINDOW);
+    if (validTimestamps.length === 0) {
+      requestCounts.delete(ip);
+    } else {
+      requestCounts.set(ip, validTimestamps);
+    }
+  }
+}, RATE_CLEANUP_INTERVAL);
+
 app.use((req, res, next) => {
   const ip = req.ip || req.connection.remoteAddress;
   const now = Date.now();
-  const windowMs = 60000;
-  const maxRequests = 100;
   if (!requestCounts.has(ip)) {
     requestCounts.set(ip, []);
   }
-  const timestamps = requestCounts.get(ip).filter(t => now - t < windowMs);
+  const timestamps = requestCounts.get(ip).filter(t => now - t < RATE_WINDOW);
   requestCounts.set(ip, timestamps);
-  if (timestamps.length >= maxRequests) {
+  if (timestamps.length >= RATE_LIMIT) {
-    return res.status(429).json({ success: false, message: "Rate limit exceeded. Try again later." });
+    return res.status(429).json({
+      success: false,
+      message: "Rate limit exceeded. Try again later.",
+      retryAfter: Math.ceil((timestamps[0] + RATE_WINDOW - now) / 1000)
+    });
   }
   timestamps.push(now);
+  res.setHeader("X-RateLimit-Limit", RATE_LIMIT);
+  res.setHeader("X-RateLimit-Remaining", RATE_LIMIT - timestamps.length);
+  next();
+});
+
+// ---- FEATURE: Cache stats endpoint ----
+app.get("/api/cache/stats", (req, res) => {
+  res.json({ success: true, results: getCacheStats() });
+});
+
+// ---- FEATURE: Creator info middleware (injects attribution into all responses) ----
+app.use(addCreatorInfo);
+
+// ---- FEATURE: Request timeout middleware (30 seconds) ----
+app.use((req, res, next) => {
+  const timeout = parseInt(process.env.REQUEST_TIMEOUT) || 30000;
+  req.setTimeout(timeout, () => {
+    if (!res.headersSent) {
+      res.status(408).json({ success: false, message: "Request timeout" });
+    }
+  });
   next();
 });
 
@@ -144,8 +215,14 @@ createApiRoutes(app, jsonResponse, jsonError);
 
 // ---- FEATURE: Global error handler ----
 app.use((err, req, res, next) => {
-  console.error(err.stack);
+  console.error(`[ERROR] ${req.id} ${err.message}`, err.stack);
-  res.status(err.status || 500).json({ success: false, message: err.message || "Internal server error" });
+  if (err.type === 'entity.too.large') {
+    return res.status(413).json({ success: false, message: "Request entity too large" });
+  }
+  res.status(err.status || 500).json({
+    success: false,
+    message: process.env.NODE_ENV === 'production' ? "Internal server error" : err.message
+  });
 });
 
 // ---- FEATURE: Catch-all 404 handler for undefined routes ----
@@ -154,7 +231,16 @@ app.use((req, res) => {
   if (fs.existsSync(filePath)) {
     res.status(404).sendFile(filePath);
   } else {
-    res.status(404).json({ success: false, message: "Endpoint not found" });
+    res.status(404).json({
+      success: false,
+      message: "Endpoint not found",
+      availableEndpoints: [
+        "/", "/search", "/info", "/episodes", "/servers", "/stream",
+        "/spotlight", "/trending", "/top-ten", "/random", "/most-popular",
+        "/new-release", "/schedule", "/genre/:genre", "/type/:type",
+        "/status/:status", "/health", "/stats", "/openapi"
+      ]
+    });
   }
 });
 
@@ -162,8 +248,37 @@ app.use((req, res) => {
 // SERVER START
 // ══════════════════════════════════════════════════════════════
 
-app.listen(PORT, () => {
+const server = app.listen(PORT, () => {
   console.info(`AniKotoAPI listening at ${PORT}`);
 });
 
+// ══════════════════════════════════════════════════════════════
+// GRACEFUL SHUTDOWN
+// ══════════════════════════════════════════════════════════════
+
+// ---- FEATURE: Graceful shutdown handling ----
+const gracefulShutdown = (signal) => {
+  console.info(`\n[SHUTDOWN] Received ${signal}. Starting graceful shutdown...`);
+  server.close(() => {
+    console.info("[SHUTDOWN] Server closed. Goodbye.");
+    process.exit(0);
+  });
+  setTimeout(() => {
+    console.error("[SHUTDOWN] Forced shutdown after timeout.");
+    process.exit(1);
+  }, 10000);
+};
+
+process.on("SIGTERM", () => gracefulShutdown("SIGTERM"));
+process.on("SIGINT", () => gracefulShutdown("SIGINT"));
+
+process.on("unhandledRejection", (reason, promise) => {
+  console.error("[UNHANDLED] Unhandled Rejection:", reason);
+});
+
+process.on("uncaughtException", (error) => {
+  console.error("[UNCAUGHT] Uncaught Exception:", error);
+  gracefulShutdown("uncaughtException");
+});
+
 // ══════════════════════════════════════════════════════════════ END: server.js

src/configs/ids.config.js

@@ -212,5 +212,90 @@ const SORT_IDS = {
   "number_of_episodes": "7"
 };
 
-export { GENRE_IDS, TYPE_IDS, STATUS_IDS, RATING_IDS, SORT_IDS };
+// ══════════════════════════════════════════════════════════════
+// SOURCE TYPE ID MAPPING
+// ══════════════════════════════════════════════════════════════
+
+// ---- FEATURE: Source type slug to numeric ID mapping ----
+/**
+ * Maps anime source type slugs to their corresponding numeric IDs.
+ * Used to filter anime by their original source material.
+ *
+ * @type {Object}
+ * @property {string} manga - ID for manga source
+ * @property {string} light-novel - ID for light novel source
+ * @property {string} original - ID for original work
+ * @property {string} visual-novel - ID for visual novel source
+ * @property {string} game - ID for game source
+ * @property {string} 4-koma-manga - ID for 4-koma manga source
+ *
+ * @example
+ *   // Get source ID for filtering
+ *   SOURCE_IDS["manga"] // "6"
+ *   SOURCE_IDS["original"] // "10"
+ */
+const SOURCE_IDS = {
+  "4-koma-manga": "1",
+  "book": "2",
+  "card-game": "3",
+  "game": "4",
+  "light-novel": "5",
+  "manga": "6",
+  "mixed-media": "7",
+  "music": "8",
+  "novel": "9",
+  "original": "10",
+  "other": "11",
+  "picture-book": "12",
+  "radio": "13",
+  "unknown": "14",
+  "video-game": "15",
+  "visual-novel": "16",
+  "web-manga": "17",
+  "web-novel": "18"
+};
+
+// ══════════════════════════════════════════════════════════════
+// SEASON ID MAPPING
+// ══════════════════════════════════════════════════════════════
+
+// ---- FEATURE: Season slug to ID mapping ----
+/**
+ * Maps anime season slugs to their corresponding IDs.
+ * Used to filter anime by their broadcast season.
+ *
+ * @type {Object}
+ * @property {string} spring - ID for spring season
+ * @property {string} summer - ID for summer season
+ * @property {string} fall - ID for fall season
+ * @property {string} winter - ID for winter season
+ *
+ * @example
+ *   // Get season ID for filtering
+ *   SEASON_IDS["spring"] // "1"
+ */
+const SEASON_IDS = {
+  "spring": "1",
+  "summer": "2",
+  "fall": "3",
+  "winter": "4"
+};
+
+// ══════════════════════════════════════════════════════════════
+// TV-SPECIFIC TYPE IDS
+// ══════════════════════════════════════════════════════════════
+
+// ---- FEATURE: Extended type slug to numeric ID mapping ----
+/**
+ * Extended type mappings including TV-specific formats.
+ *
+ * @type {Object}
+ */
+const EXTENDED_TYPE_IDS = {
+  ...TYPE_IDS,
+  "tv-short": "7",
+  "tv-special": "8"
+};
+
+export { GENRE_IDS, TYPE_IDS, STATUS_IDS, RATING_IDS, SORT_IDS, SOURCE_IDS, SEASON_IDS, EXTENDED_TYPE_IDS };
 // ══════════════════════════════════════════════════════════════ END: ids.config.js

src/controllers/animeInfo.controller.js

@@ -17,7 +17,7 @@
  */
 
 import { extractAnimeInfo } from "../extractors/animeInfo.extractor.js";
-import { getCache, setCache } from "../helper/cache.helper.js";
+import { getCache, setCache, TTL } from "../helper/cache.helper.js";
 
 // ══════════════════════════════════════════════════════════════
 // CONTROLLER: ANIME INFO
@@ -41,17 +41,18 @@ import { getCache, setCache } from "../helper/cache.helper.js";
  */
 const getAnimeInfo = async (req, res, next) => {
   try {
-    const { id } = req.query;
+    const { id, slug } = req.query;
-    if (!id) {
+    const animeSlug = id || slug;
-      return res.status(400).json({ success: false, message: "Anime slug is required" });
+    if (!animeSlug) {
+      return res.status(400).json({ success: false, message: "Anime slug is required (?id= or ?slug=)" });
     }
-    const cacheKey = `anime_${id}`;
+    const cacheKey = `anime_${animeSlug}`;
     const cached = getCache(cacheKey);
     if (cached) {
       return res.json({ success: true, results: cached });
     }
-    const data = await extractAnimeInfo(id);
+    const data = await extractAnimeInfo(animeSlug);
-    setCache(cacheKey, data);
+    setCache(cacheKey, data, TTL.info);
     res.json({ success: true, results: data });
   } catch (error) {
     next(error);

src/controllers/azList.controller.js

@@ -17,7 +17,8 @@
  */
 
 import { extractAzList } from "../extractors/azList.extractor.js";
-import { getCache, setCache } from "../helper/cache.helper.js";
+import { getCache, setCache, TTL } from "../helper/cache.helper.js";
+import { addPaginationMeta } from "../helper/pagination.helper.js";
 
 // ══════════════════════════════════════════════════════════════
 // CONTROLLER: A-Z LIST
@@ -51,8 +52,9 @@ const getAzList = async (req, res, next) => {
       return res.json({ success: true, results: cached });
     }
     const data = await extractAzList(letter, page);
-    setCache(cacheKey, data);
+    const response = addPaginationMeta(data, page);
-    res.json({ success: true, results: data });
+    setCache(cacheKey, response, TTL.genres);
+    res.json({ success: true, results: response });
   } catch (error) {
     next(error);
   }

src/controllers/category.controller.js

@@ -17,7 +17,8 @@
  */
 
 import { extractCategory } from "../extractors/category.extractor.js";
-import { getCache, setCache } from "../helper/cache.helper.js";
+import { getCache, setCache, TTL } from "../helper/cache.helper.js";
+import { addPaginationMeta } from "../helper/pagination.helper.js";
 
 // ══════════════════════════════════════════════════════════════
 // CONTROLLER: CATEGORY
@@ -55,8 +56,9 @@ const getCategory = async (req, res, next) => {
       return res.json({ success: true, results: cached });
     }
     const data = await extractCategory(category, page);
-    setCache(cacheKey, data);
+    const response = addPaginationMeta(data, page);
-    res.json({ success: true, results: data });
+    setCache(cacheKey, response, TTL.genres);
+    res.json({ success: true, results: response });
   } catch (error) {
     next(error);
   }

src/controllers/completedAnime.controller.js

@@ -0,0 +1,56 @@
+/*
+ * ======= • ======= • ======= • ======= • =======• =======
+ * AniKotoAPI — completedAnime.controller.js
+ * Repository: https://github.com/Shineii86/AniKotoAPI
+ *
+ * @description
+ *   Controller for completed anime section. Returns list of anime
+ *   that have finished airing from the homepage.
+ *
+ * @exports
+ *   getCompletedAnime - Express route handler for GET /api/completed
+ *
+ * @author  Shinei Nouzen
+ * @license MIT
+ * ======= • ======= • ======= • ======= • =======• =======
+ */
+
+import { extractCompletedAnime } from "../extractors/completedAnime.extractor.js";
+import { getCache, setCache, TTL } from "../helper/cache.helper.js";
+
+// ══════════════════════════════════════════════════════════════
+// CONTROLLER: COMPLETED ANIME
+// ══════════════════════════════════════════════════════════════
+
+// ---- FEATURE: Completed anime endpoint ----
+/**
+ * Handles GET /api/completed requests. Returns list of anime
+ * that have finished airing from the homepage section.
+ *
+ * @param {object} req - Express request object
+ * @param {object} res - Express response object
+ * @param {Function} next - Express next middleware function
+ * @returns {void} Sends JSON response with completed anime list
+ *
+ * @example
+ *   GET /api/completed
+ *   Response: { success: true, results: [...], ... }
+ */
+const getCompletedAnime = async (req, res, next) => {
+  try {
+    const cacheKey = "completed";
+    const cached = getCache(cacheKey);
+    if (cached) {
+      return res.json({ success: true, results: cached });
+    }
+    const data = await extractCompletedAnime();
+    setCache(cacheKey, data, TTL.default);
+    res.json({ success: true, results: data });
+  } catch (error) {
+    next(error);
+  }
+};
+
+export { getCompletedAnime };
+
+// ══════════════════════════════════════════════════════════════ END: completedAnime.controller.js

src/controllers/download.controller.js

@@ -0,0 +1,60 @@
+/*
+ * ======= • ======= • ======= • ======= • =======• =======
+ * AniKotoAPI — download.controller.js
+ * Repository: https://github.com/Shineii86/AniKotoAPI
+ *
+ * @description
+ *   Controller for download links endpoint. Returns streaming server
+ *   URLs for downloading anime episodes.
+ *
+ * @exports
+ *   getDownloadLinks - Express route handler for GET /api/download
+ *
+ * @author  Shinei Nouzen
+ * @license MIT
+ * ======= • ======= • ======= • ======= • =======• =======
+ */
+
+import { extractDownloadLinks } from "../extractors/download.extractor.js";
+import { getCache, setCache, TTL } from "../helper/cache.helper.js";
+
+/**
+ * Handles GET /api/download requests. Returns download links
+ * for the specified anime episode.
+ *
+ * @param {object} req - Express request object
+ * @param {string} req.query.slug - Anime slug (required)
+ * @param {number} req.query.ep - Episode number (required)
+ * @param {object} res - Express response object
+ * @param {Function} next - Express next middleware function
+ * @returns {void} Sends JSON response with download links
+ *
+ * @example
+ *   GET /api/download?slug=naruto-shippuden-c8gov&ep=1
+ *   Response: { success: true, results: { slug, episode, downloads[] } }
+ */
+const getDownloadLinks = async (req, res, next) => {
+  try {
+    const { slug, ep } = req.query;
+    if (!slug || !ep) {
+      return res.status(400).json({ 
+        success: false, 
+        message: "Both slug and ep parameters are required" 
+      });
+    }
+
+    const cacheKey = `download_${slug}_${ep}`;
+    const cached = getCache(cacheKey);
+    if (cached) {
+      return res.json({ success: true, results: cached });
+    }
+
+    const data = await extractDownloadLinks(slug, parseInt(ep));
+    setCache(cacheKey, data, TTL.stream);
+    res.json({ success: true, results: data });
+  } catch (error) {
+    next(error);
+  }
+};
+
+export { getDownloadLinks };

src/controllers/episodeList.controller.js

@@ -17,7 +17,7 @@
  */
 
 import { extractEpisodeList } from "../extractors/episodeList.extractor.js";
-import { getCache, setCache } from "../helper/cache.helper.js";
+import { getCache, setCache, TTL } from "../helper/cache.helper.js";
 
 // ══════════════════════════════════════════════════════════════
 // CONTROLLER: EPISODE LIST
@@ -52,7 +52,7 @@ const getEpisodeList = async (req, res, next) => {
       return res.json({ success: true, results: cached });
     }
     const data = await extractEpisodeList(id);
-    setCache(cacheKey, data);
+    setCache(cacheKey, data, TTL.episodes);
     res.json({ success: true, results: data });
   } catch (error) {
     next(error);

src/controllers/episodeListAjax.controller.js

@@ -17,7 +17,7 @@
  */
 
 import { extractEpisodeListAjax } from "../extractors/episodeListAjax.extractor.js";
-import { getCache, setCache } from "../helper/cache.helper.js";
+import { getCache, setCache, TTL } from "../helper/cache.helper.js";
 
 // ══════════════════════════════════════════════════════════════
 // CONTROLLER: EPISODE LIST AJAX
@@ -56,7 +56,7 @@ const getEpisodeListAjax = async (req, res, next) => {
       return res.json({ success: true, results: cached });
     }
     const data = await extractEpisodeListAjax(id, style, vrf);
-    setCache(cacheKey, data);
+    setCache(cacheKey, data, TTL.episodes);
     res.json({ success: true, results: data });
   } catch (error) {
     next(error);

src/controllers/filter.controller.js

@@ -17,7 +17,8 @@
  */
 
 import { extractFilter } from "../extractors/filter.extractor.js";
-import { getCache, setCache } from "../helper/cache.helper.js";
+import { getCache, setCache, TTL } from "../helper/cache.helper.js";
+import { addPaginationMeta } from "../helper/pagination.helper.js";
 
 // ══════════════════════════════════════════════════════════════
 // CONTROLLER: FILTER
@@ -47,14 +48,20 @@ import { getCache, setCache } from "../helper/cache.helper.js";
 const getFilter = async (req, res, next) => {
   try {
     const params = req.query;
+    const page = params.page || 1;
     const cacheKey = `filter_${JSON.stringify(params, Object.keys(params).sort())}`;
     const cached = getCache(cacheKey);
     if (cached) {
       return res.json({ success: true, results: cached });
     }
+    // Normalize array params to strings
+    if (Array.isArray(params.genre)) params.genre = params.genre.join(",");
+    if (Array.isArray(params.type)) params.type = params.type.join(",");
+    if (Array.isArray(params.status)) params.status = params.status.join(",");
     const data = await extractFilter(params);
-    setCache(cacheKey, data);
+    const response = addPaginationMeta(data, page);
-    res.json({ success: true, results: data });
+    setCache(cacheKey, response, TTL.genres);
+    res.json({ success: true, results: response });
   } catch (error) {
     next(error);
   }

src/controllers/homeInfo.controller.js

@@ -17,7 +17,7 @@
  */
 
 import { extractHomeInfo } from "../extractors/homeInfo.extractor.js";
-import { getCache, setCache } from "../helper/cache.helper.js";
+import { getCache, setCache, TTL } from "../helper/cache.helper.js";
 
 // ══════════════════════════════════════════════════════════════
 // CONTROLLER: HOME INFO
@@ -44,7 +44,7 @@ const getHomeInfo = async (req, res, next) => {
       return res.json({ success: true, results: cached });
     }
     const data = await extractHomeInfo();
-    setCache(cacheKey, data);
+    setCache(cacheKey, data, TTL.home);
     res.json({ success: true, results: data });
   } catch (error) {
     next(error);

src/controllers/newRelease.controller.js

@@ -17,8 +17,9 @@
  * ======= • ======= • ======= • ======= • =======• =======
  */
 
-import { extractNewRelease, extractNewlyAdded } from "../extractors/newRelease.extractor.js";
+import { extractNewRelease, extractNewlyAdded, extractLatestUpdated } from "../extractors/newRelease.extractor.js";
-import { getCache, setCache } from "../helper/cache.helper.js";
+import { getCache, setCache, TTL } from "../helper/cache.helper.js";
+import { addPaginationMeta } from "../helper/pagination.helper.js";
 
 // ══════════════════════════════════════════════════════════════
 // CONTROLLER: NEW RELEASE
@@ -48,8 +49,9 @@ const getNewRelease = async (req, res, next) => {
       return res.json({ success: true, results: cached });
     }
     const data = await extractNewRelease(page);
-    setCache(cacheKey, data);
+    const response = addPaginationMeta(data, page);
-    res.json({ success: true, results: data });
+    setCache(cacheKey, response, TTL.default);
+    res.json({ success: true, results: response });
   } catch (error) {
     next(error);
   }
@@ -83,13 +85,49 @@ const getNewlyAdded = async (req, res, next) => {
       return res.json({ success: true, results: cached });
     }
     const data = await extractNewlyAdded(page);
-    setCache(cacheKey, data);
+    const response = addPaginationMeta(data, page);
-    res.json({ success: true, results: data });
+    setCache(cacheKey, response, TTL.default);
+    res.json({ success: true, results: response });
   } catch (error) {
     next(error);
   }
 };
 
-export { getNewRelease, getNewlyAdded };
+// ══════════════════════════════════════════════════════════════
+// CONTROLLER: LATEST UPDATED
+// ══════════════════════════════════════════════════════════════
+
+/**
+ * Handles GET /api/latest-updated requests. Returns paginated list
+ * of recently updated anime sorted by last update time.
+ *
+ * @param {object} req - Express request object
+ * @param {number} req.query.page - Page number (default: 1)
+ * @param {object} res - Express response object
+ * @param {Function} next - Express next middleware function
+ * @returns {void} Sends JSON response with latest updated anime
+ *
+ * @example
+ *   GET /api/latest-updated?page=2
+ *   Response: { success: true, results: { totalPages, data[] } }
+ */
+const getLatestUpdated = async (req, res, next) => {
+  try {
+    const { page = 1 } = req.query;
+    const cacheKey = `latestupdated_${page}`;
+    const cached = getCache(cacheKey);
+    if (cached) {
+      return res.json({ success: true, results: cached });
+    }
+    const data = await extractLatestUpdated(page);
+    const response = addPaginationMeta(data, page);
+    setCache(cacheKey, response, TTL.default);
+    res.json({ success: true, results: response });
+  } catch (error) {
+    next(error);
+  }
+};
+
+export { getNewRelease, getNewlyAdded, getLatestUpdated };
 
 // ══════════════════════════════════════════════════════════════ END: newRelease.controller.js

src/controllers/popular.controller.js

@@ -17,7 +17,8 @@
  */
 
 import { extractPopular } from "../extractors/popular.extractor.js";
-import { getCache, setCache } from "../helper/cache.helper.js";
+import { getCache, setCache, TTL } from "../helper/cache.helper.js";
+import { addPaginationMeta } from "../helper/pagination.helper.js";
 
 // ══════════════════════════════════════════════════════════════
 // CONTROLLER: POPULAR
@@ -47,8 +48,9 @@ const getPopular = async (req, res, next) => {
       return res.json({ success: true, results: cached });
     }
     const data = await extractPopular(page);
-    setCache(cacheKey, data);
+    const response = addPaginationMeta(data, page);
-    res.json({ success: true, results: data });
+    setCache(cacheKey, response, TTL.default);
+    res.json({ success: true, results: response });
   } catch (error) {
     next(error);
   }

src/controllers/random.controller.js

@@ -38,7 +38,6 @@ import { extractRandom } from "../extractors/random.extractor.js";
  */
 const getRandom = async (req, res, next) => {
   try {
-    }
     const data = await extractRandom();
     res.json({ success: true, results: data });
   } catch (error) {

src/controllers/recentlyUpdatedTabs.controller.js

@@ -0,0 +1,58 @@
+/*
+ * ======= • ======= • ======= • ======= • =======• =======
+ * AniKotoAPI — recentlyUpdatedTabs.controller.js
+ * Repository: https://github.com/Shineii86/AniKotoAPI
+ *
+ * @description
+ *   Controller for recently updated anime with tab filtering.
+ *   Returns recently updated anime filtered by all, dub, or sub.
+ *
+ * @exports
+ *   getRecentlyUpdatedTabs - Express route handler for GET /api/recently-updated
+ *
+ * @author  Shinei Nouzen
+ * @license MIT
+ * ======= • ======= • ======= • ======= • =======• =======
+ */
+
+import { extractRecentlyUpdatedTabs } from "../extractors/recentlyUpdatedTabs.extractor.js";
+import { getCache, setCache, TTL } from "../helper/cache.helper.js";
+
+// ══════════════════════════════════════════════════════════════
+// CONTROLLER: RECENTLY UPDATED TABS
+// ══════════════════════════════════════════════════════════════
+
+// ---- FEATURE: Recently updated with tab filtering endpoint ----
+/**
+ * Handles GET /api/recently-updated requests. Returns recently updated
+ * anime filtered by tab: all, dub, or sub.
+ *
+ * @param {object} req - Express request object
+ * @param {string} [req.query.tab="all"] - Tab filter: "all", "dub", or "sub"
+ * @param {object} res - Express response object
+ * @param {Function} next - Express next middleware function
+ * @returns {void} Sends JSON response with recently updated anime list
+ *
+ * @example
+ *   GET /api/recently-updated?tab=dub
+ *   Response: { success: true, results: [...], tab: "dub" }
+ */
+const getRecentlyUpdatedTabs = async (req, res, next) => {
+  try {
+    const { tab = "all" } = req.query;
+    const cacheKey = `recently_updated_${tab}`;
+    const cached = getCache(cacheKey);
+    if (cached) {
+      return res.json({ success: true, results: cached, tab });
+    }
+    const data = await extractRecentlyUpdatedTabs(tab);
+    setCache(cacheKey, data, TTL.default);
+    res.json({ success: true, results: data, tab });
+  } catch (error) {
+    next(error);
+  }
+};
+
+export { getRecentlyUpdatedTabs };
+
+// ══════════════════════════════════════════════════════════════ END: recentlyUpdatedTabs.controller.js

src/controllers/schedule.controller.js

@@ -17,7 +17,7 @@
  */
 
 import { extractSchedule } from "../extractors/schedule.extractor.js";
-import { getCache, setCache } from "../helper/cache.helper.js";
+import { getCache, setCache, TTL } from "../helper/cache.helper.js";
 
 // ══════════════════════════════════════════════════════════════
 // CONTROLLER: SCHEDULE
@@ -53,7 +53,7 @@ const getSchedule = async (req, res, next) => {
       return res.json({ success: true, results: cached });
     }
     const data = await extractSchedule(date);
-    setCache(cacheKey, data);
+    setCache(cacheKey, data, TTL.schedule);
     res.json({ success: true, results: data });
   } catch (error) {
     next(error);

src/controllers/search.controller.js

@@ -18,7 +18,8 @@
  */
 
 import { extractSearchResults, extractSearchSuggestions } from "../extractors/search.extractor.js";
-import { getCache, setCache } from "../helper/cache.helper.js";
+import { getCache, setCache, TTL } from "../helper/cache.helper.js";
+import { addPaginationMeta } from "../helper/pagination.helper.js";
 
 // ══════════════════════════════════════════════════════════════
 // CONTROLLER: SEARCH RESULTS
@@ -52,8 +53,9 @@ const getSearchResults = async (req, res, next) => {
       return res.json({ success: true, results: cached });
     }
     const data = await extractSearchResults(keyword, page);
-    setCache(cacheKey, data);
+    const response = addPaginationMeta(data, page);
-    res.json({ success: true, results: data });
+    setCache(cacheKey, response, TTL.search);
+    res.json({ success: true, results: response });
   } catch (error) {
     next(error);
   }
@@ -91,7 +93,7 @@ const getSearchSuggestions = async (req, res, next) => {
       return res.json({ success: true, results: cached });
     }
     const data = await extractSearchSuggestions(keyword);
-    setCache(cacheKey, data);
+    setCache(cacheKey, data, TTL.search);
     res.json({ success: true, results: data });
   } catch (error) {
     next(error);

src/controllers/seasons.controller.js

@@ -17,7 +17,7 @@
  */
 
 import { extractSeasons } from "../extractors/seasons.extractor.js";
-import { getCache, setCache } from "../helper/cache.helper.js";
+import { getCache, setCache, TTL } from "../helper/cache.helper.js";
 
 // ══════════════════════════════════════════════════════════════
 // CONTROLLER: SEASONS
@@ -52,7 +52,7 @@ const getSeasons = async (req, res, next) => {
       return res.json({ success: true, results: cached });
     }
     const data = await extractSeasons(id);
-    setCache(cacheKey, data);
+    setCache(cacheKey, data, TTL.default);
     res.json({ success: true, results: data });
   } catch (error) {
     next(error);

src/controllers/spotlight.controller.js

@@ -17,7 +17,7 @@
  */
 
 import { extractSpotlight } from "../extractors/spotlight.extractor.js";
-import { getCache, setCache } from "../helper/cache.helper.js";
+import { getCache, setCache, TTL } from "../helper/cache.helper.js";
 
 // ══════════════════════════════════════════════════════════════
 // CONTROLLER: SPOTLIGHT
@@ -45,7 +45,7 @@ const getSpotlight = async (req, res, next) => {
       return res.json({ success: true, results: cached });
     }
     const data = await extractSpotlight();
-    setCache(cacheKey, data);
+    setCache(cacheKey, data, TTL.spotlight);
     res.json({ success: true, results: data });
   } catch (error) {
     next(error);

src/controllers/status.controller.js

@@ -17,7 +17,8 @@
  */
 
 import { extractStatus } from "../extractors/status.extractor.js";
-import { getCache, setCache } from "../helper/cache.helper.js";
+import { getCache, setCache, TTL } from "../helper/cache.helper.js";
+import { addPaginationMeta } from "../helper/pagination.helper.js";
 
 // ══════════════════════════════════════════════════════════════
 // CONTROLLER: STATUS
@@ -54,9 +55,20 @@ const getStatus = async (req, res, next) => {
     if (cached) {
       return res.json({ success: true, results: cached });
     }
-    const data = await extractStatus(status, page);
+    // Map short status names to full slugs
-    setCache(cacheKey, data);
+    const statusMap = {
-    res.json({ success: true, results: data });
+      ongoing: "currently-airing",
+      airing: "currently-airing",
+      completed: "finished-airing",
+      finished: "finished-airing",
+      upcoming: "not-yet-aired",
+      "not-yet-aired": "not-yet-aired"
+    };
+    const mappedStatus = statusMap[status] || status;
+    const data = await extractStatus(mappedStatus, page);
+    const response = addPaginationMeta(data, page);
+    setCache(cacheKey, response, TTL.genres);
+    res.json({ success: true, results: response });
   } catch (error) {
     next(error);
   }

src/controllers/streamInfo.controller.js

@@ -19,7 +19,7 @@
  */
 
 import { extractStreamInfo, extractServerList, extractMapperServers } from "../extractors/streamInfo.extractor.js";
-import { getCache, setCache } from "../helper/cache.helper.js";
+import { getCache, setCache, TTL } from "../helper/cache.helper.js";
 
 // ══════════════════════════════════════════════════════════════
 // CONTROLLER: STREAM INFO
@@ -54,7 +54,7 @@ const getStreamInfo = async (req, res, next) => {
       return res.json({ success: true, results: cached });
     }
     const data = await extractStreamInfo(id);
-    setCache(cacheKey, data);
+    setCache(cacheKey, data, TTL.default);
     res.json({ success: true, results: data });
   } catch (error) {
     next(error);
@@ -94,7 +94,7 @@ const getServerList = async (req, res, next) => {
       return res.json({ success: true, results: cached });
     }
     const data = await extractServerList(ids);
-    setCache(cacheKey, data);
+    setCache(cacheKey, data, TTL.default);
     res.json({ success: true, results: data });
   } catch (error) {
     next(error);
@@ -137,7 +137,7 @@ const getMapperServers = async (req, res, next) => {
       return res.json({ success: true, results: cached });
     }
     const data = await extractMapperServers(malId, slug, timestamp);
-    setCache(cacheKey, data);
+    setCache(cacheKey, data, TTL.default);
     res.json({ success: true, results: data });
   } catch (error) {
     next(error);

src/controllers/streamResolver.controller.js

@@ -0,0 +1,129 @@
+/*
+ * ======= • ======= • ======= • ======= • =======• =======
+ * AniKotoAPI — streamResolver.controller.js
+ * Repository: https://github.com/Shineii86/AniKotoAPI
+ *
+ * @description
+ *   Controller for stream URL resolution and quality detection.
+ *   Resolves actual video URLs (m3u8/mp4) from embed player URLs
+ *   and parses available quality options.
+ *
+ * @exports
+ *   getResolvedStream - Express route handler for GET /api/stream/resolve
+ *   getStreamQualities - Express route handler for GET /api/stream/qualities
+ *
+ * @author  Shinei Nouzen
+ * @license MIT
+ * ======= • ======= • ======= • ======= • =======• =======
+ */
+
+import { resolveStreamUrl, parseM3u8Qualities } from "../extractors/streamResolver.extractor.js";
+import { extractStreamInfo } from "../extractors/streamInfo.extractor.js";
+import { getCache, setCache, TTL } from "../helper/cache.helper.js";
+
+// ══════════════════════════════════════════════════════════════
+// CONTROLLER: RESOLVE STREAM
+// ══════════════════════════════════════════════════════════════
+
+// ---- FEATURE: Resolve actual video stream URL from link ID ----
+/**
+ * Handles GET /api/stream/resolve requests. Resolves the actual
+ * video stream URL (m3u8/mp4) from a server link ID.
+ *
+ * @param {object} req - Express request object
+ * @param {string} req.query.id - Server link ID
+ * @param {string} req.query.slug - Anime slug (used to establish session)
+ * @param {object} res - Express response object
+ * @param {Function} next - Express next middleware function
+ * @returns {void} Sends JSON response with resolved stream URL
+ *
+ * @example
+ *   GET /api/stream/resolve?id=abc123&slug=one-piece-odmau
+ *   Response: { success: true, results: { url, qualities, type } }
+ *
+ * @throws {400} If 'id' query parameter is missing
+ */
+const getResolvedStream = async (req, res, next) => {
+  try {
+    const { id, slug } = req.query;
+    if (!id) {
+      return res.status(400).json({ success: false, message: "Link ID is required" });
+    }
+    const cacheKey = `resolved_${id}`;
+    const cached = getCache(cacheKey);
+    if (cached) {
+      return res.json({ success: true, results: cached });
+    }
+
+    // NOTE: First get the embed URL from the link ID (with session establishment)
+    const streamInfo = await extractStreamInfo(id, slug);
+    if (!streamInfo.url) {
+      return res.status(404).json({ success: false, message: "Stream URL not found for this link ID" });
+    }
+
+    // NOTE: Resolve the actual video URL from the embed page
+    const resolved = await resolveStreamUrl(streamInfo.url);
+    const result = {
+      linkId: id,
+      embedUrl: streamInfo.url,
+      ...resolved,
+      skipData: streamInfo.skipData || resolved.skipData,
+    };
+
+    setCache(cacheKey, result, TTL.stream);
+    res.json({ success: true, results: result });
+  } catch (error) {
+    next(error);
+  }
+};
+
+// ══════════════════════════════════════════════════════════════
+// CONTROLLER: STREAM QUALITIES
+// ══════════════════════════════════════════════════════════════
+
+// ---- FEATURE: Available quality options for a stream URL ----
+/**
+ * Handles GET /api/stream/qualities requests. Parses an M3U8
+ * playlist URL to return available quality options.
+ *
+ * @param {object} req - Express request object
+ * @param {string} req.query.url - M3U8 playlist URL
+ * @param {object} res - Express response object
+ * @param {Function} next - Express next middleware function
+ * @returns {void} Sends JSON response with quality options
+ *
+ * @example
+ *   GET /api/stream/qualities?url=https://example.com/master.m3u8
+ *   Response: { success: true, results: [{ label: "720p", url: "..." }] }
+ *
+ * @throws {400} If 'url' query parameter is missing
+ */
+const getStreamQualities = async (req, res, next) => {
+  try {
+    const { url } = req.query;
+    if (!url) {
+      return res.status(400).json({ success: false, message: "M3U8 URL is required" });
+    }
+    const cacheKey = `qualities_${url}`;
+    const cached = getCache(cacheKey);
+    if (cached) {
+      return res.json({ success: true, results: cached });
+    }
+
+    const qualities = await parseM3u8Qualities(url);
+    const result = {
+      url,
+      totalQualities: qualities.length,
+      qualities,
+    };
+
+    setCache(cacheKey, result, TTL.stream);
+    res.json({ success: true, results: result });
+  } catch (error) {
+    next(error);
+  }
+};
+
+export { getResolvedStream, getStreamQualities };
+
+// ══════════════════════════════════════════════════════════════ END: streamResolver.controller.js

src/controllers/suggestion.controller.js

@@ -17,7 +17,7 @@
  */
 
 import { extractSuggestions } from "../extractors/suggestion.extractor.js";
-import { getCache, setCache } from "../helper/cache.helper.js";
+import { getCache, setCache, TTL } from "../helper/cache.helper.js";
 
 // ══════════════════════════════════════════════════════════════
 // CONTROLLER: SUGGESTIONS
@@ -52,7 +52,7 @@ const getSuggestions = async (req, res, next) => {
       return res.json({ success: true, results: cached });
     }
     const data = await extractSuggestions(keyword);
-    setCache(cacheKey, data);
+    setCache(cacheKey, data, TTL.suggestions);
     res.json({ success: true, results: data });
   } catch (error) {
     next(error);

src/controllers/topAnimeRankings.controller.js

@@ -0,0 +1,58 @@
+/*
+ * ======= • ======= • ======= • ======= • =======• =======
+ * AniKotoAPI — topAnimeRankings.controller.js
+ * Repository: https://github.com/Shineii86/AniKotoAPI
+ *
+ * @description
+ *   Controller for top anime rankings. Returns ranked anime list
+ *   with support for top (all-time) and newest sort modes.
+ *
+ * @exports
+ *   getTopAnimeRankings - Express route handler for GET /api/top-rankings
+ *
+ * @author  Shinei Nouzen
+ * @license MIT
+ * ======= • ======= • ======= • ======= • =======• =======
+ */
+
+import { extractTopAnimeRankings } from "../extractors/topAnimeRankings.extractor.js";
+import { getCache, setCache, TTL } from "../helper/cache.helper.js";
+
+// ══════════════════════════════════════════════════════════════
+// CONTROLLER: TOP ANIME RANKINGS
+// ══════════════════════════════════════════════════════════════
+
+// ---- FEATURE: Top anime rankings endpoint ----
+/**
+ * Handles GET /api/top-rankings requests. Returns ranked anime list
+ * with support for top (all-time) and newest sort modes.
+ *
+ * @param {object} req - Express request object
+ * @param {string} [req.query.sort="top"] - Sort mode: "top" or "newest"
+ * @param {object} res - Express response object
+ * @param {Function} next - Express next middleware function
+ * @returns {void} Sends JSON response with ranked anime list
+ *
+ * @example
+ *   GET /api/top-rankings?sort=top
+ *   Response: { success: true, results: [{ rank: 1, title: "...", ... }] }
+ */
+const getTopAnimeRankings = async (req, res, next) => {
+  try {
+    const { sort = "top" } = req.query;
+    const cacheKey = `top_rankings_${sort}`;
+    const cached = getCache(cacheKey);
+    if (cached) {
+      return res.json({ success: true, results: cached });
+    }
+    const data = await extractTopAnimeRankings(sort);
+    setCache(cacheKey, data, TTL.trending);
+    res.json({ success: true, results: data });
+  } catch (error) {
+    next(error);
+  }
+};
+
+export { getTopAnimeRankings };
+
+// ══════════════════════════════════════════════════════════════ END: topAnimeRankings.controller.js

src/controllers/topten.controller.js

@@ -16,7 +16,7 @@
  */
 
 import { extractTopTen } from "../extractors/topten.extractor.js";
-import { getCache, setCache } from "../helper/cache.helper.js";
+import { getCache, setCache, TTL } from "../helper/cache.helper.js";
 
 // ══════════════════════════════════════════════════════════════
 // CONTROLLER: TOP TEN
@@ -44,7 +44,7 @@ const getTopTen = async (req, res, next) => {
       return res.json({ success: true, results: cached });
     }
     const data = await extractTopTen();
-    setCache(cacheKey, data);
+    setCache(cacheKey, data, TTL.default);
     res.json({ success: true, results: data });
   } catch (error) {
     next(error);

src/controllers/trending.controller.js

@@ -17,7 +17,7 @@
  */
 
 import { extractTrending } from "../extractors/trending.extractor.js";
-import { getCache, setCache } from "../helper/cache.helper.js";
+import { getCache, setCache, TTL } from "../helper/cache.helper.js";
 
 // ══════════════════════════════════════════════════════════════
 // CONTROLLER: TRENDING
@@ -45,7 +45,7 @@ const getTrending = async (req, res, next) => {
       return res.json({ success: true, results: cached });
     }
     const data = await extractTrending();
-    setCache(cacheKey, data);
+    setCache(cacheKey, data, TTL.trending);
     res.json({ success: true, results: data });
   } catch (error) {
     next(error);

src/controllers/trendingSidebar.controller.js

@@ -16,7 +16,7 @@
  */
 
 import { extractTrendingSidebar } from "../extractors/trendingSidebar.extractor.js";
-import { getCache, setCache } from "../helper/cache.helper.js";
+import { getCache, setCache, TTL } from "../helper/cache.helper.js";
 
 // ══════════════════════════════════════════════════════════════
 // CONTROLLER: TRENDING SIDEBAR
@@ -44,7 +44,7 @@ const getTrendingSidebar = async (req, res, next) => {
       return res.json({ success: true, results: cached });
     }
     const data = await extractTrendingSidebar();
-    setCache(cacheKey, data);
+    setCache(cacheKey, data, TTL.trending);
     res.json({ success: true, results: data });
   } catch (error) {
     next(error);

src/controllers/upcomingAnime.controller.js

@@ -0,0 +1,56 @@
+/*
+ * ======= • ======= • ======= • ======= • =======• =======
+ * AniKotoAPI — upcomingAnime.controller.js
+ * Repository: https://github.com/Shineii86/AniKotoAPI
+ *
+ * @description
+ *   Controller for upcoming anime section. Returns list of anime
+ *   scheduled for future release from the homepage.
+ *
+ * @exports
+ *   getUpcomingAnime - Express route handler for GET /api/upcoming
+ *
+ * @author  Shinei Nouzen
+ * @license MIT
+ * ======= • ======= • ======= • ======= • =======• =======
+ */
+
+import { extractUpcomingAnime } from "../extractors/upcomingAnime.extractor.js";
+import { getCache, setCache, TTL } from "../helper/cache.helper.js";
+
+// ══════════════════════════════════════════════════════════════
+// CONTROLLER: UPCOMING ANIME
+// ══════════════════════════════════════════════════════════════
+
+// ---- FEATURE: Upcoming anime endpoint ----
+/**
+ * Handles GET /api/upcoming requests. Returns list of anime
+ * scheduled for future release from the homepage section.
+ *
+ * @param {object} req - Express request object
+ * @param {object} res - Express response object
+ * @param {Function} next - Express next middleware function
+ * @returns {void} Sends JSON response with upcoming anime list
+ *
+ * @example
+ *   GET /api/upcoming
+ *   Response: { success: true, results: [...], ... }
+ */
+const getUpcomingAnime = async (req, res, next) => {
+  try {
+    const cacheKey = "upcoming";
+    const cached = getCache(cacheKey);
+    if (cached) {
+      return res.json({ success: true, results: cached });
+    }
+    const data = await extractUpcomingAnime();
+    setCache(cacheKey, data, TTL.default);
+    res.json({ success: true, results: data });
+  } catch (error) {
+    next(error);
+  }
+};
+
+export { getUpcomingAnime };
+
+// ══════════════════════════════════════════════════════════════ END: upcomingAnime.controller.js

src/controllers/watchOrder.controller.js

@@ -17,7 +17,7 @@
  */
 
 import { extractWatchOrder } from "../extractors/watchOrder.extractor.js";
-import { getCache, setCache } from "../helper/cache.helper.js";
+import { getCache, setCache, TTL } from "../helper/cache.helper.js";
 
 // ══════════════════════════════════════════════════════════════
 // CONTROLLER: WATCH ORDER
@@ -53,7 +53,7 @@ const getWatchOrder = async (req, res, next) => {
       return res.json({ success: true, results: cached });
     }
     const data = await extractWatchOrder(id);
-    setCache(cacheKey, data);
+    setCache(cacheKey, data, TTL.default);
     res.json({ success: true, results: data });
   } catch (error) {
     next(error);

src/controllers/watchPage.controller.js

@@ -17,7 +17,7 @@
  */
 
 import { extractWatchPage } from "../extractors/watchPage.extractor.js";
-import { getCache, setCache } from "../helper/cache.helper.js";
+import { getCache, setCache, TTL } from "../helper/cache.helper.js";
 
 // ══════════════════════════════════════════════════════════════
 // CONTROLLER: WATCH PAGE
@@ -54,7 +54,7 @@ const getWatchPage = async (req, res, next) => {
       return res.json({ success: true, results: cached });
     }
     const data = await extractWatchPage(slug, ep);
-    setCache(cacheKey, data);
+    setCache(cacheKey, data, TTL.stream);
     res.json({ success: true, results: data });
   } catch (error) {
     next(error);

src/extractors/animeInfo.extractor.js

@@ -17,9 +17,8 @@
  */
 
 import * as cheerio from "cheerio";
-import axios from "axios";
-import { headers } from "../configs/header.config.js";
 import { URLS } from "../configs/dataUrl.js";
+import { fetchWithMirror } from "../helper/mirror.helper.js";
 
 // ══════════════════════════════════════════════════════════════
 // ANIME INFO EXTRACTOR
@@ -41,64 +40,45 @@ import { URLS } from "../configs/dataUrl.js";
  */
 const extractAnimeInfo = async (slug) => {
   try {
-    const url = URLS.watch(slug);
+    const path = `/watch/${slug}`;
-    const { data } = await axios.get(url, { headers });
+    const { data } = await fetchWithMirror(path);
     const $ = cheerio.load(data);
 
-    // ---- FEATURE: Extract title and identification fields ----
-    // NOTE: itemprop='name' is used for schema.org microdata on the site
     const title = $("h1[itemprop='name'].title.d-title").text().trim() || "";
-    // NOTE: data-jp attribute holds the Japanese title variant
     const japaneseTitle = $("h1[itemprop='name'].title.d-title").attr("data-jp") || "";
     const altNames = $(".names.font-italic").text().trim() || "";
     const poster = $("img[itemprop='image']").attr("src") || "";
     const synopsis = $(".synopsis .content").text().trim() || "";
 
-    // ---- FEATURE: Extract rating and review metadata ----
-    // NOTE: Multiple rating selectors are checked — .score .value is the display score,
-    //       itemprop='ratingValue' is the microdata fallback
     const rating = $("#w-rating .score .value").text().trim() || "";
     const ratingValue = $("#w-rating span[itemprop='ratingValue']").text().trim() || "";
     const reviewCount = $("#w-rating span[itemprop='reviewCount']").text().trim() || "";
-    // NOTE: data-id on #watch-main is the internal anime ID used for AJAX calls
     const animeId = parseInt($("#watch-main").attr("data-id")) || 0;
 
-    // ---- FEATURE: Extract anime metadata (type, premiere, aired, status) ----
-    // NOTE: .bmeta contains the structured metadata block — first child holds basic info
     const type = $(".bmeta .meta:first-child > div:nth-child(1) span").text().trim() || "";
     const premiered = $(".bmeta .meta:first-child > div:nth-child(2) span").text().trim() || "";
     const aired = $(".bmeta .meta:first-child > div:nth-child(3) span").text().trim() || "";
     const status = $(".bmeta .meta:first-child > div:nth-child(4) span a").text().trim() || "";
 
-    // ---- FEATURE: Extract secondary metadata (MAL score, duration, episodes) ----
-    // NOTE: Second .meta child holds MAL-linked and production metadata
     const malScore = $(".bmeta .meta:nth-child(2) > div:nth-child(1) span").text().trim() || "";
     const duration = $(".bmeta .meta:nth-child(2) > div:nth-child(2) span").text().trim() || "";
     const episodes = $(".bmeta .meta:nth-child(2) > div:nth-child(3) span").text().trim() || "";
 
-    // ---- FEATURE: Extract studios list ----
-    // NOTE: itemprop='director' links on studio spans — itemprop='name' inside holds the name
     const studios = [];
     $(".bmeta .meta:nth-child(2) > div:nth-child(4) span a[itemprop='director'] span[itemprop='name']").each((i, el) => {
       studios.push($(el).text().trim());
     });
 
-    // ---- FEATURE: Extract producers list ----
-    // NOTE: Same selector pattern as studios but from the 5th child (producers row)
     const producers = [];
     $(".bmeta .meta:nth-child(2) > div:nth-child(5) span a[itemprop='director'] span[itemprop='name']").each((i, el) => {
       producers.push($(el).text().trim());
     });
 
-    // ---- FEATURE: Extract genres ----
-    // NOTE: Genre links contain '/genre/' in their href — filters out non-genre links
     const genres = [];
     $(".bmeta .meta:first-child > div:nth-child(5) span a[href*='/genre/']").each((i, el) => {
       genres.push($(el).text().trim());
     });
 
-    // ---- FEATURE: Extract background artwork from player element ----
-    // NOTE: The #player div has a CSS background-image set via inline style
     const backgroundImage = $("#player").css("background-image")?.match(/url\(['"]?(.+?)['"]?\)/)?.[1] || "";
 
     return {

src/extractors/azList.extractor.js

@@ -15,12 +15,10 @@
  * ======= • ======= • ======= • ======= • =======• =======
  */
 
-import * as cheerio from "cheerio";
-import axios from "axios";
-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 { parseListItems } from "../helper/parseListItem.helper.js";
 
 // ══════════════════════════════════════════════════════════════
 // A-Z LIST EXTRACTION
@@ -54,40 +52,10 @@ import { countPages } from "../helper/countPages.helper.js";
  */
 const extractAzList = async (letter = "all", page = 1) => {
   try {
-    // NOTE: URLS.azList generates the correct endpoint for the given letter
     const url = URLS.azList(letter);
     const $ = await extractPages(url, page);
     const totalPages = countPages($);
-
+    const results = parseListItems($);
-    const results = [];
-
-    // NOTE: Multiple selectors to handle different page layouts
-    $(".film_list-wrap .flw-item, .film-detail, .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() || "";
-      const japaneseTitle = $(el).find(".name.d-title").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(".meta .inner .right, .fdi-item:nth-child(2)").text().trim() || "";
-      const rating = $(el).find(".rating, .fdi-item:nth-child(3)").text().trim() || "";
-
-      // NOTE: Only include items with valid slugs
-      if (slug) {
-        results.push({
-          slug,
-          poster,
-          title,
-          japaneseTitle,
-          sub,
-          dub,
-          total,
-          type,
-          rating
-        });
-      }
-    });
 
     return { totalPages, letter, data: results };
   } catch (error) {

src/extractors/category.extractor.js

@@ -18,6 +18,7 @@
 import { URLS } from "../configs/dataUrl.js";
 import { countPages } from "../helper/countPages.helper.js";
 import { extractPages } from "../helper/extractPages.helper.js";
+import { parseListItems } from "../helper/parseListItem.helper.js";
 
 // ══════════════════════════════════════════════════════════════
 // CATEGORY FILTER EXTRACTION
@@ -53,53 +54,30 @@ import { extractPages } from "../helper/extractPages.helper.js";
  */
 const extractCategory = async (category, page = 1) => {
   try {
-    // NOTE: Category type is determined by prefix in the category string
     let url;
     if (category.startsWith("genre/")) {
       url = URLS.genre(category.replace("genre/", ""));
     } else if (category.startsWith("type/")) {
       url = URLS.type(category.replace("type/", ""));
     } else if (category.startsWith("status/")) {
-      url = URLS.status(category.replace("status/", ""));
+      // NOTE: Map short status names to full slugs used by the site
+      const statusSlug = category.replace("status/", "");
+      const statusMap = {
+        ongoing: "currently-airing",
+        airing: "currently-airing",
+        completed: "finished-airing",
+        finished: "finished-airing",
+        upcoming: "not-yet-aired"
+      };
+      const mapped = statusMap[statusSlug] || statusSlug;
+      url = URLS.status(mapped);
     } else {
-      // NOTE: Fallback to direct URL construction for unknown category types
       url = `${URLS.home}/${category}`;
     }
 
     const $ = await extractPages(url, page);
     const totalPages = countPages($);
-
+    const results = parseListItems($, "#list-items > .item", { includeAnimeId: true });
-    const results = [];
-
-    // NOTE: The list items are contained in #list-items container
-    $("#list-items > .item").each((i, el) => {
-      const slug = $(el).find("a").attr("href")?.split("/watch/").pop() || "";
-      const poster = $(el).find(".ani.poster.tip > a > img").attr("src") || "";
-      const title = $(el).find(".info .b1 a.name.d-title").text().trim() || "";
-      const japaneseTitle = $(el).find(".info .b1 a.name.d-title").attr("data-jp") || "";
-      const animeId = $(el).find(".ani.poster.tip").attr("data-tip") || "";
-      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(".info .meta .m-item:nth-child(2) label").text().trim() || "";
-      const rating = $(el).find(".info .meta .m-item.rated span").text().trim() || "";
-
-      // NOTE: Only include items with valid slugs
-      if (slug) {
-        results.push({
-          slug,
-          animeId,
-          poster,
-          title,
-          japaneseTitle,
-          sub,
-          dub,
-          total,
-          type,
-          rating
-        });
-      }
-    });
 
     return { totalPages, data: results };
   } catch (error) {

src/extractors/completedAnime.extractor.js

@@ -0,0 +1,77 @@
+/*
+ * ======= • ======= • ======= • ======= • =======• =======
+ * AniKotoAPI — completedAnime.extractor.js
+ * Repository: https://github.com/Shineii86/AniKotoAPI
+ *
+ * @description
+ *   Extracts completed anime from the homepage section.
+ *   Scrapes the completed tab/section for finished anime series.
+ *
+ * @exports
+ *   extractCompletedAnime
+ *
+ * @author  Shinei Nouzen
+ * @license MIT
+ * ======= • ======= • ======= • ======= • =======• =======
+ */
+
+import * as cheerio from "cheerio";
+import { fetchWithMirror } from "../helper/mirror.helper.js";
+
+// ══════════════════════════════════════════════════════════════
+// COMPLETED ANIME EXTRACTION
+// ══════════════════════════════════════════════════════════════
+
+// ---- FEATURE: Extract completed anime from homepage section ----
+/**
+ * Fetches and parses the completed anime section from the homepage.
+ * Returns a list of anime that have finished airing.
+ *
+ * @returns {Promise<Array<Object>>} Array of completed anime objects
+ * @returns {string} return[].slug - URL slug for the anime
+ * @returns {string} return[].poster - Poster image URL
+ * @returns {string} return[].title - English title
+ * @returns {string} return[].japaneseTitle - Japanese title
+ * @returns {number} return[].sub - Subbed episode count
+ * @returns {number} return[].dub - Dubbed episode count
+ * @returns {number} return[].total - Total episode count
+ * @returns {string} return[].type - Anime type
+ *
+ * @example
+ *   const completed = await extractCompletedAnime();
+ *   console.log(completed.length); // number of completed anime
+ *   console.log(completed[0].title); // first completed anime title
+ */
+const extractCompletedAnime = async () => {
+  try {
+    const { data } = await fetchWithMirror("/home");
+    const $ = cheerio.load(data);
+
+    const results = [];
+
+    // NOTE: completed section is inside .top-tables with data-name="completed"
+    // Items are <a class="item"> inside .scaff.items
+    $("section.top-table[data-name='completed'] .scaff.items a.item, .top-table[data-name='completed'] a.item").each((i, el) => {
+      const slug = $(el).attr("href")?.split("/watch/").pop() || "";
+      if (!slug) return;
+
+      const poster = $(el).find("img").attr("src") || "";
+      const title = $(el).find(".name").text().trim() || "";
+      const japaneseTitle = $(el).find(".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(".meta .dot:last-child").text().trim() || "";
+
+      results.push({ slug, poster, title, japaneseTitle, sub, dub, total, type });
+    });
+
+    return results;
+  } catch (error) {
+    throw error;
+  }
+};
+
+export { extractCompletedAnime };
+
+// ══════════════════════════════════════════════════════════════ END: completedAnime.extractor.js

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/episodeList.extractor.js

@@ -17,9 +17,9 @@
  */
 
 import * as cheerio from "cheerio";
-import axios from "axios";
 import { headers } from "../configs/header.config.js";
 import { URLS, BASE_URL } from "../configs/dataUrl.js";
+import { fetchWithMirror } from "../helper/mirror.helper.js";
 
 // ══════════════════════════════════════════════════════════════
 // EPISODE LIST EXTRACTOR
@@ -31,7 +31,7 @@ import { URLS, BASE_URL } from "../configs/dataUrl.js";
  * queries the AJAX episode list endpoint to get all episodes with their
  * metadata (ID, number, slug, title, active state, href).
  *
- * @param {string} slug - The anime slug identifier (e.g. "naruto-shippuden")
+ * @param {string} slugOrId - The anime slug or numeric ID (e.g. "naruto-shippuden" or "12345")
  * @returns {Promise<Object>} Object with animeId, slug, totalEpisodes, and episodes array
  *
  * @example
@@ -44,13 +44,11 @@ const extractEpisodeList = async (slugOrId) => {
     let animeId = 0;
     let resolvedSlug = slugOrId;
 
-    // NOTE: Accept either numeric anime ID or slug — if numeric, skip watch page fetch
     if (/^\d+$/.test(slugOrId)) {
       animeId = parseInt(slugOrId);
     } else {
-      // NOTE: Fetch the watch page to extract the internal anime ID from the slug
+      const path = `/watch/${slugOrId}`;
-      const infoUrl = URLS.watch(slugOrId);
+      const { data: infoData } = await fetchWithMirror(path);
-      const { data: infoData } = await axios.get(infoUrl, { headers });
       const $ = cheerio.load(infoData);
       animeId = parseInt($("#watch-main").attr("data-id")) || 0;
     }
@@ -60,21 +58,14 @@ const extractEpisodeList = async (slugOrId) => {
     }
 
     try {
-      // NOTE: AJAX endpoint requires X-Requested-With header to return HTML fragment
+      const ajaxPath = `/ajax/episode/list/${animeId}`;
-      const ajaxUrl = `${BASE_URL}/ajax/episode/list/${animeId}`;
+      const { data: ajaxRaw } = await fetchWithMirror(ajaxPath, {
-      const { data: ajaxRaw } = await axios.get(ajaxUrl, {
+        headers: { "X-Requested-With": "XMLHttpRequest" }
-        headers: {
-          ...headers,
-          "X-Requested-With": "XMLHttpRequest"
-        }
       });
 
-      // NOTE: AJAX response is JSON {status, result} where result is HTML
       const ajaxHtml = typeof ajaxRaw === "string" ? ajaxRaw : (ajaxRaw?.result || "");
       const $ep = cheerio.load(ajaxHtml);
 
-      // ---- FEATURE: Parse episode list from AJAX response HTML ----
-      // NOTE: Episode links have either data-num or data-ep-id attributes
       const episodes = [];
       $ep("a[data-num], a[data-ep-id], a[data-id]").each((i, el) => {
         const epId = $ep(el).attr("data-ep-id") || $ep(el).attr("data-id") || "";
@@ -83,9 +74,7 @@ const extractEpisodeList = async (slugOrId) => {
         const href = $ep(el).attr("href") || "";
         const epTitle = $ep(el).find(".ep-title, .ep-name").text().trim() || "";
         const isActive = $ep(el).hasClass("active") || false;
-        // NOTE: data-ids is the base64-encoded server ID string needed for /api/servers
         const serverIds = $ep(el).attr("data-ids") || "";
-        // NOTE: data-timestamp used for mapper API
         const timestamp = $ep(el).attr("data-timestamp") || "";
         const malId = $ep(el).attr("data-mal") || "";
 
@@ -109,7 +98,6 @@ const extractEpisodeList = async (slugOrId) => {
         episodes
       };
     } catch (ajaxError) {
-      // NOTE: Gracefully return empty list if AJAX call fails (e.g. network issue)
       return {
         animeId,
         slug: slugOrId,

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/filter.extractor.js

@@ -6,7 +6,7 @@
  * @description
  *   Provides advanced anime filtering on anikototv.to — supports filtering
  *   by genre, type, status, language, rating, sort order, season, year,
- *   and keyword with full pagination support.
+ *   source, episode range, and keyword with full pagination support.
  *
  * @exports
  *   extractFilter
@@ -16,9 +16,8 @@
  * ======= • ======= • ======= • ======= • =======• =======
  */
 
-import { headers } from "../configs/header.config.js";
 import { URLS } from "../configs/dataUrl.js";
-import { GENRE_IDS, TYPE_IDS, STATUS_IDS, RATING_IDS, SORT_IDS } from "../configs/ids.config.js";
+import { GENRE_IDS, TYPE_IDS, STATUS_IDS, RATING_IDS, SORT_IDS, SOURCE_IDS, SEASON_IDS } from "../configs/ids.config.js";
 import { countPages } from "../helper/countPages.helper.js";
 import { extractPages } from "../helper/extractPages.helper.js";
 
@@ -30,7 +29,7 @@ import { extractPages } from "../helper/extractPages.helper.js";
 /**
  * Builds a filter URL from the given parameters and fetches matching anime
  * from anikototv.to. Supports keyword, genre, type, status, language,
- * rating, sort, season, and year filters — all combinable.
+ * rating, sort, season, year, source, episode range, and exclude watchlist.
  *
  * @param {Object} params - Filter parameters object
  * @param {string} [params.keyword] - Search keyword to filter by name
@@ -39,9 +38,13 @@ import { extractPages } from "../helper/extractPages.helper.js";
  * @param {string} [params.status] - Comma-separated statuses (e.g. "airing,completed")
  * @param {string} [params.language] - Comma-separated languages (e.g. "sub,dub")
  * @param {string} [params.rating] - Comma-separated ratings (e.g. "pg-13,r")
- * @param {string} [params.sort] - Sort order key (e.g. "score", "name")
+ * @param {string} [params.sort] - Sort order key (e.g. "score", "name-az")
  * @param {string} [params.season] - Comma-separated seasons (e.g. "winter,spring")
  * @param {string} [params.year] - Comma-separated years (e.g. "2024,2025")
+ * @param {string} [params.source] - Comma-separated sources (e.g. "manga,light-novel")
+ * @param {number} [params.epMin] - Minimum episode count filter
+ * @param {number} [params.epMax] - Maximum episode count filter
+ * @param {boolean} [params.excludeWatchlist=false] - Exclude watchlisted anime
  * @param {number} [params.page=1] - Page number for pagination
  * @returns {Promise<Object>} Object with totalPages count and data array of results
  *
@@ -49,6 +52,17 @@ import { extractPages } from "../helper/extractPages.helper.js";
  *   const filtered = await extractFilter({ genre: "action", type: "tv", page: 1 });
  *   console.log(filtered.totalPages);
  *   console.log(filtered.data[0].title);
+ *
+ * @example
+ *   // Advanced filter with episode range
+ *   const filtered = await extractFilter({
+ *     genre: "comedy,slice-of-life",
+ *     type: "tv",
+ *     year: "2024",
+ *     epMin: 12,
+ *     epMax: 24,
+ *     sort: "score"
+ *   });
  */
 const extractFilter = async (params) => {
   try {
@@ -102,8 +116,8 @@ const extractFilter = async (params) => {
 
     // ---- FEATURE: Append season filter ----
     if (params.season) {
-      const seasons = params.season.split(",");
+      const seasons = params.season.split(",").map(s => SEASON_IDS[s.trim().toLowerCase()] || s.trim());
-      seasons.forEach(s => queryParams.append("season[]", s.trim()));
+      seasons.forEach(s => queryParams.append("season[]", s));
     }
 
     // ---- FEATURE: Append year filter ----
@@ -112,6 +126,28 @@ const extractFilter = async (params) => {
       years.forEach(y => queryParams.append("year[]", y.trim()));
     }
 
+    // ---- FEATURE: Append source filter ----
+    // NOTE: SOURCE_IDS maps source material types to numeric IDs
+    if (params.source) {
+      const sources = params.source.split(",").map(s => SOURCE_IDS[s.trim().toLowerCase()] || s.trim());
+      sources.forEach(s => queryParams.append("source[]", s));
+    }
+
+    // ---- FEATURE: Append episode range filter ----
+    // NOTE: epMin and epMax filter by total episode count range
+    if (params.epMin) {
+      queryParams.set("ep_min", params.epMin);
+    }
+    if (params.epMax) {
+      queryParams.set("ep_max", params.epMax);
+    }
+
+    // ---- FEATURE: Append exclude watchlist filter ----
+    // NOTE: Only works for logged-in users — ignores for guests
+    if (params.excludeWatchlist) {
+      queryParams.set("exclude_watchlist", "1");
+    }
+
     // NOTE: The filter URL is built by appending query params to the search base URL
     const filterUrl = `${URLS.search}?${queryParams.toString()}`;
     const $ = await extractPages(filterUrl, params.page || 1);

src/extractors/homeInfo.extractor.js

@@ -16,10 +16,7 @@
  */
 
 import * as cheerio from "cheerio";
-import axios from "axios";
+import { fetchWithMirror } from "../helper/mirror.helper.js";
-import { headers } from "../configs/header.config.js";
-import { URLS } from "../configs/dataUrl.js";
-import { getCache, setCache } from "../helper/cache.helper.js";
 
 // ══════════════════════════════════════════════════════════════
 // HOME INFO EXTRACTOR
@@ -37,27 +34,19 @@ import { getCache, setCache } from "../helper/cache.helper.js";
  *   console.log(home.spotlights.length); // number of spotlight items
  */
 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 ----
-    // NOTE: Swiper slides contain the hero carousel on the homepage
     const spotlights = [];
     $("#hotest .swiper-slide.item").each((i, el) => {
-      // NOTE: The play button's href contains the /watch/{slug} path
       const slug = $(el).find("a.play").attr("href")?.split("/watch/").pop() || "";
-      // NOTE: Poster is set as inline CSS background-image on a div inside .image
       const poster = $(el).find(".image div").attr("style")?.match(/url\(['"]?(.+?)['"]?\)/)?.[1] || "";
       const title = $(el).find("h2.title.d-title").text().trim() || "";
-      // NOTE: data-jp attribute holds the Japanese/romaji title variant
       const japaneseTitle = $(el).find("h2.title.d-title").attr("data-jp") || "";
       const description = $(el).find(".desc").text().trim() || "";
       const rating = $(el).find("i.rating").text().trim() || "";
       const quality = $(el).find("i.quality").text().trim() || "";
-      // NOTE: sub/dub counts are extracted as integers, defaulting to 0
       const sub = parseInt($(el).find("i.sub").text().trim()) || 0;
       const dub = parseInt($(el).find("i.dub").text().trim()) || 0;
       const date = $(el).find("i.date").text().trim() || "";
@@ -78,15 +67,12 @@ const extractHomeInfo = async () => {
       }
     });
 
-    // ---- FEATURE: Extract trending/recently-updated anime list ----
-    // NOTE: Combines both .section-updated and #recent-update containers for coverage
     const trending = [];
     $(".section-updated .item, #recent-update .item").each((i, el) => {
       const slug = $(el).find("a.name.d-title").attr("href")?.split("/watch/").pop() || "";
       const poster = $(el).find(".poster img").attr("src") || "";
       const title = $(el).find("a.name.d-title").text().trim() || "";
       const japaneseTitle = $(el).find("a.name.d-title").attr("data-jp") || "";
-      // NOTE: Episode counts are in .ep-status spans — sub, dub, and total
       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;
@@ -106,8 +92,6 @@ const extractHomeInfo = async () => {
       }
     });
 
-    // ---- FEATURE: Extract top airing anime of the day ----
-    // NOTE: Only the 'day' tab content is scraped from #top-anime
     const topAiring = [];
     $("#top-anime .tab-content[data-name='day'] a.item").each((i, el) => {
       const slug = $(el).attr("href")?.split("/watch/").pop() || "";
@@ -122,8 +106,6 @@ const extractHomeInfo = async () => {
       }
     });
 
-    // ---- FEATURE: Extract genre filter list from navigation menu ----
-    // NOTE: Only links containing /genre/ in href are considered valid genre entries
     const genres = [];
     $("#menu ul.c4 li a").each((i, el) => {
       const genre = $(el).text().trim();

src/extractors/newRelease.extractor.js

@@ -10,18 +10,17 @@
  * @exports
  *   extractNewRelease
  *   extractNewlyAdded
+ *   extractLatestUpdated
  *
  * @author  Shinei Nouzen
  * @license MIT
  * ======= • ======= • ======= • ======= • =======• =======
  */
 
-import * as cheerio from "cheerio";
-import axios from "axios";
-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 { parseListItems } from "../helper/parseListItem.helper.js";
 
 // ══════════════════════════════════════════════════════════════
 // NEW RELEASE EXTRACTION
@@ -53,39 +52,9 @@ import { countPages } from "../helper/countPages.helper.js";
  */
 const extractNewRelease = async (page = 1) => {
   try {
-    // NOTE: extractPages handles pagination and returns parsed Cheerio object
     const $ = await extractPages(URLS.newRelease, page);
     const totalPages = countPages($);
-
+    const results = parseListItems($);
-    const results = [];
-
-    // NOTE: Multiple selectors to handle different page layouts
-    $(".film_list-wrap .flw-item, .film-detail, .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() || "";
-      const japaneseTitle = $(el).find(".name.d-title").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(".meta .inner .right, .fdi-item:nth-child(2)").text().trim() || "";
-      const rating = $(el).find(".rating, .fdi-item:nth-child(3)").text().trim() || "";
-
-      // NOTE: Only include items with valid slugs
-      if (slug) {
-        results.push({
-          slug,
-          poster,
-          title,
-          japaneseTitle,
-          sub,
-          dub,
-          total,
-          type,
-          rating
-        });
-      }
-    });
 
     return { totalPages, data: results };
   } catch (error) {
@@ -122,37 +91,9 @@ const extractNewRelease = async (page = 1) => {
  */
 const extractNewlyAdded = async (page = 1) => {
   try {
-    // NOTE: The latestUpdated endpoint with sort=added returns recently added anime
     const $ = await extractPages(`${URLS.latestUpdated}?sort=added`, page);
     const totalPages = countPages($);
-
+    const results = parseListItems($);
-    const results = [];
-
-    // NOTE: Multiple selectors to handle different page layouts
-    $(".film_list-wrap .flw-item, .film-detail, .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() || "";
-      const japaneseTitle = $(el).find(".name.d-title").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(".meta .inner .right, .fdi-item:nth-child(2)").text().trim() || "";
-
-      // NOTE: Only include items with valid slugs
-      if (slug) {
-        results.push({
-          slug,
-          poster,
-          title,
-          japaneseTitle,
-          sub,
-          dub,
-          total,
-          type
-        });
-      }
-    });
 
     return { totalPages, data: results };
   } catch (error) {
@@ -160,6 +101,34 @@ 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 = parseListItems($, ".item");
+
+    return { totalPages, data: results };
+  } catch (error) {
+    throw error;
+  }
+};
+
+export { extractNewRelease, extractNewlyAdded, extractLatestUpdated };
 
 // ══════════════════════════════════════════════════════════════ END: newRelease.extractor.js

src/extractors/popular.extractor.js

@@ -15,10 +15,10 @@
  * ======= • ======= • ======= • ======= • =======• =======
  */
 
-import { headers } from "../configs/header.config.js";
 import { URLS } from "../configs/dataUrl.js";
 import { countPages } from "../helper/countPages.helper.js";
 import { extractPages } from "../helper/extractPages.helper.js";
+import { parseListItems } from "../helper/parseListItem.helper.js";
 
 // ══════════════════════════════════════════════════════════════
 // POPULAR EXTRACTION
@@ -51,42 +51,9 @@ import { extractPages } from "../helper/extractPages.helper.js";
  */
 const extractPopular = async (page = 1) => {
   try {
-    // NOTE: extractPages handles pagination and returns parsed Cheerio object
     const $ = await extractPages(URLS.mostViewed, page);
     const totalPages = countPages($);
-
+    const results = parseListItems($, "#list-items > .item", { includeAnimeId: true });
-    const results = [];
-
-    // NOTE: The list items are contained in #list-items container
-    $("#list-items > .item").each((i, el) => {
-      const slug = $(el).find("a").attr("href")?.split("/watch/").pop() || "";
-      const poster = $(el).find(".ani.poster.tip > a > img").attr("src") || "";
-      const title = $(el).find(".info .b1 a.name.d-title").text().trim() || "";
-      const japaneseTitle = $(el).find(".info .b1 a.name.d-title").attr("data-jp") || "";
-      const animeId = $(el).find(".ani.poster.tip").attr("data-tip") || "";
-      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(".info .meta .m-item:nth-child(2) label").text().trim() || "";
-      const rating = $(el).find(".info .meta .m-item.rated span").text().trim() || "";
-
-      // NOTE: Only include items with valid slugs
-      if (slug) {
-        results.push({
-          slug,
-          animeId,
-          poster,
-          title,
-          japaneseTitle,
-          sub,
-          dub,
-          total,
-          type,
-          rating
-        });
-      }
-    });
-
     return { totalPages, data: results };
   } catch (error) {
     throw error;

src/extractors/random.extractor.js

@@ -20,6 +20,7 @@ import * as cheerio from "cheerio";
 import axios from "axios";
 import { headers } from "../configs/header.config.js";
 import { URLS } from "../configs/dataUrl.js";
+import { fetchWithMirror } from "../helper/mirror.helper.js";
 
 // ══════════════════════════════════════════════════════════════
 // RANDOM ANIME EXTRACTOR
@@ -40,34 +41,26 @@ import { URLS } from "../configs/dataUrl.js";
  */
 const extractRandom = async () => {
   try {
-    // NOTE: maxRedirects=5 ensures we follow the random redirect chain
-    // NOTE: validateStatus allows any 2xx/3xx response without throwing
     const { data, request } = await axios.get(URLS.random, {
       headers,
       maxRedirects: 5,
       validateStatus: (status) => status < 400
     });
 
-    // NOTE: responseURL on the request object gives us the final resolved URL after redirects
     const finalUrl = request?.responseURL || URLS.random;
-    // NOTE: The slug is extracted from the /watch/{slug} path in the final URL
     const slug = finalUrl.split("/watch/").pop() || "";
 
     const $ = cheerio.load(data);
 
-    // ---- FEATURE: Extract anime title and identification ----
     const title = $("h1[itemprop='name'].title.d-title").text().trim() || "";
     const japaneseTitle = $("h1[itemprop='name'].title.d-title").attr("data-jp") || "";
     const poster = $("img[itemprop='image']").attr("src") || "";
 
-    // ---- FEATURE: Extract type, synopsis, rating, and anime ID ----
     const type = $(".bmeta .meta:first-child > div:nth-child(1) span").text().trim() || "";
     const synopsis = $(".synopsis .content").text().trim() || "";
     const rating = $("#w-rating .score .value").text().trim() || "";
     const animeId = parseInt($("#watch-main").attr("data-id")) || 0;
 
-    // ---- FEATURE: Extract genres ----
-    // NOTE: Genre links are identified by '/genre/' in their href attribute
     const genres = [];
     $(".bmeta .meta:first-child > div:nth-child(5) span a[href*='/genre/']").each((i, el) => {
       genres.push($(el).text().trim());

src/extractors/recentlyUpdatedTabs.extractor.js

@@ -0,0 +1,94 @@
+/*
+ * ======= • ======= • ======= • ======= • =======• =======
+ * AniKotoAPI — recentlyUpdatedTabs.extractor.js
+ * Repository: https://github.com/Shineii86/AniKotoAPI
+ *
+ * @description
+ *   Extracts recently updated anime from homepage with tab filtering.
+ *   Supports three tabs: all, dub, and sub for different update types.
+ *
+ * @exports
+ *   extractRecentlyUpdatedTabs
+ *
+ * @author  Shinei Nouzen
+ * @license MIT
+ * ======= • ======= • ======= • ======= • =======• =======
+ */
+
+import * as cheerio from "cheerio";
+import { fetchWithMirror } from "../helper/mirror.helper.js";
+
+// ══════════════════════════════════════════════════════════════
+// RECENTLY UPDATED TABS EXTRACTION
+// ══════════════════════════════════════════════════════════════
+
+// ---- FEATURE: Extract recently updated anime with tab filtering ----
+/**
+ * Fetches and parses the recently updated anime section from the homepage.
+ * Supports filtering by update type: all, dub, or sub.
+ *
+ * @param {string} tab - Tab filter: "all", "dub", or "sub" (default: "all")
+ * @returns {Promise<Array<Object>>} Array of recently updated anime objects
+ * @returns {string} return[].slug - URL slug for the anime
+ * @returns {string} return[].poster - Poster image URL
+ * @returns {string} return[].title - English title
+ * @returns {string} return[].japaneseTitle - Japanese title
+ * @returns {number} return[].sub - Subbed episode count
+ * @returns {number} return[].dub - Dubbed episode count
+ * @returns {number} return[].total - Total episode count
+ * @returns {string} return[].type - Anime type
+ * @returns {string} return[].episodeInfo - Latest episode info
+ *
+ * @example
+ *   const all = await extractRecentlyUpdatedTabs("all");
+ *   console.log(all.length); // number of updated anime
+ *
+ *   const dubOnly = await extractRecentlyUpdatedTabs("dub");
+ *   console.log(dubOnly[0].title); // first dubbed updated anime
+ */
+const extractRecentlyUpdatedTabs = async (tab = "all") => {
+  try {
+    const { data } = await fetchWithMirror("/home");
+    const $ = cheerio.load(data);
+
+    const results = [];
+
+    // NOTE: #recent-update has tabs (all/dub/sub/trending/random) but filtering is client-side
+    // Items are <div class="item"> inside #recent-update .ani.items
+    // Each item has .ani.poster with <a> link and .info .name.d-title
+    const allItems = $("#recent-update .ani.items .item");
+
+    allItems.each((i, el) => {
+      // NOTE: The item itself is a div, the link is inside .ani.poster a or .info a.name
+      const link = $(el).find(".ani.poster a").attr("href") || $(el).find(".info a.name").attr("href") || "";
+      const slug = link.split("/watch/").pop()?.split("/ep-")[0] || "";
+      if (!slug) return;
+
+      // NOTE: Check sub/dub status for tab filtering
+      const hasSub = $(el).find(".ep-status.sub").length > 0;
+      const hasDub = $(el).find(".ep-status.dub").length > 0;
+
+      // NOTE: Filter by tab if not "all" — since server-side rendering shows all items
+      if (tab === "dub" && !hasDub) return;
+      if (tab === "sub" && !hasSub) return;
+
+      const poster = $(el).find("img").attr("src") || "";
+      const title = $(el).find(".name").text().trim() || "";
+      const japaneseTitle = $(el).find(".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(".meta .right, .type").text().trim() || "";
+
+      results.push({ slug, poster, title, japaneseTitle, sub, dub, total, type });
+    });
+
+    return results;
+  } catch (error) {
+    throw error;
+  }
+};
+
+export { extractRecentlyUpdatedTabs };
+
+// ══════════════════════════════════════════════════════════════ END: recentlyUpdatedTabs.extractor.js

src/extractors/schedule.extractor.js

@@ -16,9 +16,8 @@
  */
 
 import * as cheerio from "cheerio";
-import axios from "axios";
-import { headers } from "../configs/header.config.js";
 import { URLS } from "../configs/dataUrl.js";
+import { fetchWithMirror } from "../helper/mirror.helper.js";
 
 // ══════════════════════════════════════════════════════════════
 // SCHEDULE EXTRACTION
@@ -43,21 +42,18 @@ import { URLS } from "../configs/dataUrl.js";
  */
 const extractSchedule = async (date) => {
   try {
-    // NOTE: The schedule is fetched by appending date parameter to homepage
+    const path = `/?date=${date}`;
-    const url = `${URLS.home}?date=${date}`;
+    const { data } = await fetchWithMirror(path);
-    const { data } = await axios.get(url, { headers });
     const $ = cheerio.load(data);
 
     const schedule = [];
 
-    // NOTE: Schedule items use different selectors depending on page structure
     $(".schedule-item, .anime-schedule .item").each((i, el) => {
       const slug = $(el).find("a").attr("href")?.split("/watch/").pop() || "";
       const title = $(el).find(".film-name a, .name").text().trim() || "";
       const time = $(el).find(".time, .schedule-time").text().trim() || "";
       const episodeNo = parseInt($(el).find(".episode-no, .ep-num").text().trim()) || 0;
 
-      // NOTE: Only include items with valid slugs
       if (slug) {
         schedule.push({
           slug,

src/extractors/search.extractor.js

@@ -16,11 +16,10 @@
  */
 
 import * as cheerio from "cheerio";
-import axios from "axios";
-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";
 
 // ══════════════════════════════════════════════════════════════
 // SEARCH RESULTS EXTRACTOR
@@ -42,27 +41,21 @@ import { countPages } from "../helper/countPages.helper.js";
  */
 const extractSearchResults = async (keyword, page = 1) => {
   try {
-    // WARNING: keyword param is required — omitting it may cause a 500 error from the source
     const url = `${URLS.search}?keyword=${encodeURIComponent(keyword)}`;
     const $ = await extractPages(url, page);
     const totalPages = countPages($);
 
     const results = [];
-    // NOTE: #list-items > .item is the standard result container on anikototv.to search pages
     $("#list-items > .item").each((i, el) => {
       const slug = $(el).find("a").attr("href")?.split("/watch/").pop() || "";
-      // NOTE: .ani.poster.tip is the poster container with tooltip data
       const poster = $(el).find(".ani.poster.tip > a > img").attr("src") || "";
       const title = $(el).find(".info .b1 a.name.d-title").text().trim() || "";
       const japaneseTitle = $(el).find(".info .b1 a.name.d-title").attr("data-jp") || "";
-      // NOTE: data-tip attribute on the poster container holds the animeId
       const animeId = $(el).find(".ani.poster.tip").attr("data-tip") || "";
       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;
-      // NOTE: Type is in the second .m-item label (e.g. TV, Movie, OVA)
       const type = $(el).find(".info .meta .m-item:nth-child(2) label").text().trim() || "";
-      // NOTE: Rating is in a dedicated .m-item.rated span
       const rating = $(el).find(".info .meta .m-item.rated span").text().trim() || "";
       const genres = [];
       $(el).find(".info .b1 .genre a").each((j, g) => {
@@ -110,8 +103,8 @@ const extractSearchResults = async (keyword, page = 1) => {
  */
 const extractSearchSuggestions = async (keyword) => {
   try {
-    const url = `${URLS.search}?keyword=${encodeURIComponent(keyword)}`;
+    const path = `/search?keyword=${encodeURIComponent(keyword)}`;
-    const { data } = await axios.get(url, { headers });
+    const { data } = await fetchWithMirror(path);
     const $ = cheerio.load(data);
 
     const suggestions = [];
@@ -126,7 +119,6 @@ const extractSearchSuggestions = async (keyword) => {
       }
     });
 
-    // NOTE: Limit to 10 suggestions to keep autocomplete payloads small
     return suggestions.slice(0, 10);
   } catch (error) {
     throw error;

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.
+ *   Extracts season information for a specific anime from the
- *   Returns season data from the internal API endpoint.
+ *   watch page HTML. Returns available seasons from the page
+ *   sidebar and metadata.
  *
  * @exports
  *   extractSeasons
@@ -15,44 +16,70 @@
  * ======= • ======= • ======= • ======= • =======• =======
  */
 
-import axios from "axios";
+import * as cheerio from "cheerio";
-import { headers } from "../configs/header.config.js";
+import { fetchWithMirror } from "../helper/mirror.helper.js";
-import { BASE_URL } from "../configs/dataUrl.js";
 
-// ══════════════════════════════════════════════════════════════
-// SEASONS API EXTRACTION
-// ══════════════════════════════════════════════════════════════
-
-// ---- FEATURE: Extract season data from internal API ----
 /**
- * Fetches season information for a specific anime from the internal API.
+ * Fetches and parses season information for an anime.
- * Returns an array of season objects or empty array on error.
+ * Extracts season data from the watch page sidebar.
  *
- * @param {string} animeId - The anime ID to fetch seasons for
+ * @param {string|number} slugOrId - The anime slug or numeric ID
- * @returns {Promise<Array<Object>>} Array of season objects or empty array
+ * @returns {Promise<Object>} Object with animeId, totalSeasons, and seasons array
  *
  * @example
- *   const seasons = await extractSeasons("12345");
+ *   const seasons = await extractSeasons("one-piece-odmau");
- *   console.log(seasons.length); // Number of seasons
+ *   console.log(seasons.totalSeasons);
  */
-const extractSeasons = async (animeId) => {
+const extractSeasons = async (slugOrId) => {
   try {
-    // NOTE: This is an internal API endpoint requiring X-Requested-With header
+    const path = /^\d+$/.test(slugOrId) ? `/watch/${slugOrId}` : `/watch/${slugOrId}`;
-    const url = `${BASE_URL}/api/seasons/${animeId}`;
+    const { data } = await fetchWithMirror(path);
-    const { data } = await axios.get(url, {
+
-      headers: {
+    const html = typeof data === "string" ? data : String(data);
-        ...headers,
+    const $ = cheerio.load(html);
-        "X-Requested-With": "XMLHttpRequest"
+
+    const animeId = parseInt($("#watch-main").attr("data-id")) || 0;
+    const seasons = [];
+
+    // NOTE: Extract seasons from #ani-seasons section (if populated)
+    $("#ani-seasons .swiper-slide, .seasons .item, #w-seasons .item").each((_, el) => {
+      const link = $(el).find("a").first();
+      const href = link.attr("href") || "";
+      const poster = $(el).find("img").attr("src") || "";
+      const title = $(el).find(".name, .title").text().trim() || link.text().trim() || "";
+      const slug = href.split("/watch/").pop() || "";
+
+      if (slug || title) {
+        seasons.push({ title, slug, poster, url: href });
       }
     });
 
-    return data || [];
+    // NOTE: If no dedicated seasons section, extract from episode list sidebar
+    if (seasons.length === 0) {
+      $(".w-side-section .item").each((_, el) => {
+        const link = $(el).find("a").first();
+        const href = link.attr("href") || "";
+        const poster = $(el).find("img").attr("src") || "";
+        const title = $(el).find(".name").text().trim() || "";
+        const slug = href.split("/watch/").pop() || "";
+        const score = $(el).find(".score").text().trim() || "";
+        const episodes = $(el).find(".meta .dot:last-child").text().trim() || "";
+
+        if (slug && slug !== slugOrId) {
+          seasons.push({ title, slug, poster, url: href, score, episodes });
+        }
+      });
+    }
+
+    return {
+      animeId,
+      slug: slugOrId,
+      totalSeasons: seasons.length,
+      seasons,
+    };
   } catch (error) {
-    // NOTE: Return empty array on error to maintain consistent API
     throw error;
   }
 };
 
 export { extractSeasons };
-
-// ══════════════════════════════════════════════════════════════ END: seasons.extractor.js

src/extractors/spotlight.extractor.js

@@ -16,9 +16,8 @@
  */
 
 import * as cheerio from "cheerio";
-import axios from "axios";
-import { headers } from "../configs/header.config.js";
 import { URLS } from "../configs/dataUrl.js";
+import { fetchWithMirror } from "../helper/mirror.helper.js";
 
 // ══════════════════════════════════════════════════════════════
 // SPOTLIGHT EXTRACTION
@@ -48,13 +47,11 @@ import { URLS } from "../configs/dataUrl.js";
  */
 const extractSpotlight = async () => {
   try {
-    // NOTE: The homepage contains the spotlight carousel in #hotest section
+    const { data } = await fetchWithMirror("/home");
-    const { data } = await axios.get(URLS.home, { headers });
     const $ = cheerio.load(data);
 
     const spotlights = [];
 
-    // NOTE: Each slide in the swiper carousel represents a featured anime
     $("#hotest .swiper-slide.item").each((i, el) => {
       const slug = $(el).find("a.play").attr("href")?.split("/watch/").pop() || "";
       const poster = $(el).find(".image div").attr("style")?.match(/url\(['"]?(.+?)['"]?\)/)?.[1] || "";
@@ -67,7 +64,6 @@ const extractSpotlight = async () => {
       const dub = parseInt($(el).find("i.dub").text().trim()) || 0;
       const date = $(el).find("i.date").text().trim() || "";
 
-      // NOTE: Only include items with valid slugs
       if (slug) {
         spotlights.push({
           slug,

src/extractors/status.extractor.js

@@ -15,12 +15,10 @@
  * ======= • ======= • ======= • ======= • =======• =======
  */
 
-import * as cheerio from "cheerio";
-import axios from "axios";
-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 { parseListItems } from "../helper/parseListItem.helper.js";
 
 // ══════════════════════════════════════════════════════════════
 // STATUS FILTER EXTRACTION
@@ -54,40 +52,10 @@ import { countPages } from "../helper/countPages.helper.js";
  */
 const extractStatus = async (status, page = 1) => {
   try {
-    // NOTE: URLS.status generates the correct endpoint for the given status
     const url = URLS.status(status);
     const $ = await extractPages(url, page);
     const totalPages = countPages($);
-
+    const results = parseListItems($);
-    const results = [];
-
-    // NOTE: Multiple selectors to handle different page layouts
-    $(".film_list-wrap .flw-item, .film-detail, .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() || "";
-      const japaneseTitle = $(el).find(".name.d-title").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(".meta .inner .right, .fdi-item:nth-child(2)").text().trim() || "";
-      const rating = $(el).find(".rating, .fdi-item:nth-child(3)").text().trim() || "";
-
-      // NOTE: Only include items with valid slugs
-      if (slug) {
-        results.push({
-          slug,
-          poster,
-          title,
-          japaneseTitle,
-          sub,
-          dub,
-          total,
-          type,
-          rating
-        });
-      }
-    });
 
     return { totalPages, status, data: results };
   } catch (error) {

src/extractors/streamInfo.extractor.js

@@ -17,9 +17,10 @@
  */
 
 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";
+import { normalizeServerName } from "./streamResolver.extractor.js";
 
 // ══════════════════════════════════════════════════════════════
 // STREAM INFO EXTRACTOR
@@ -28,37 +29,51 @@ import { BASE_URL } from "../configs/dataUrl.js";
 // ---- 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.
+ * First establishes a session by fetching the watch page, then queries
+ * the AJAX stream endpoint with proper session context.
  *
  * @param {string} linkId - The server link ID to resolve
- * @returns {Promise<Object>} Object with linkId, url, and skipData (intro/outro timestamps)
+ * @param {string} [watchSlug] - Optional watch page slug to establish session
+ * @returns {Promise<Object>} Object with linkId, url, type, skipData (intro/outro timestamps)
  *
  * @example
- *   const stream = await extractStreamInfo("abc123");
+ *   const stream = await extractStreamInfo("abc123", "one-piece-odmau");
  *   console.log(stream.url);      // direct video URL
  *   console.log(stream.skipData); // intro/outro skip ranges
  */
-const extractStreamInfo = async (linkId) => {
+const extractStreamInfo = async (linkId, watchSlug = null) => {
   try {
-    const url = `${BASE_URL}/ajax/server?get=${linkId}`;
+    // NOTE: Establish session by visiting watch page first (required for AJAX endpoints)
-    const { data } = await axios.get(url, {
+    if (watchSlug) {
-      headers: {
+      await fetchWithMirror(`/watch/${watchSlug}`);
-        ...headers,
+    }
-        "X-Requested-With": "XMLHttpRequest"
+
-      }
+    const path = `/ajax/server?get=${linkId}`;
+    const { data: raw } = await fetchWithMirror(path, {
+      headers: { "X-Requested-With": "XMLHttpRequest" }
     });
 
-    // NOTE: Response is JSON {status, result: {url, skip_data}}
+    // NOTE: Handle both string JSON and parsed object responses
+    let data = raw;
+    if (typeof raw === "string") {
+      try { data = JSON.parse(raw); } catch { data = {}; }
+    }
+
     if (!data || !data.result) {
-      return { linkId, url: null, skipData: null };
+      return { linkId, url: null, type: null, skipData: null };
     }
 
     const result = typeof data.result === "string" ? (() => { try { return JSON.parse(data.result); } catch { return {}; } })() : data.result;
 
+    const streamUrl = result.url || null;
+    const streamType = streamUrl?.includes(".m3u8") ? "hls" : streamUrl ? "mp4" : null;
+
     return {
       linkId,
-      url: result.url || null,
+      url: streamUrl,
-      skipData: result.skip_data || null
+      type: streamType,
+      skipData: result.skip_data || null,
+      backup: result.backup || null,
     };
   } catch (error) {
     throw error;
@@ -72,44 +87,50 @@ const extractStreamInfo = async (linkId) => {
 // ---- 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.
+ * First establishes a session by fetching the watch page, then queries
+ * the AJAX server list endpoint with proper session context.
  *
  * @param {string} episodeIds - Comma-separated or single episode ID string
- * @returns {Promise<Object>} Raw server list data from the AJAX response
+ * @param {string} [watchSlug] - Optional watch page slug to establish session
+ * @returns {Promise<Array>} Array of server objects with type, link_id, ep_id, etc.
  *
  * @example
- *   const servers = await extractServerList("12345");
+ *   const servers = await extractServerList("12345", "one-piece-odmau");
- *   // servers contains the server configuration for that episode
+ *   console.log(servers[0].link_id); // first server's link ID
  */
-const extractServerList = async (episodeIds) => {
+const extractServerList = async (episodeIds, watchSlug = null) => {
   try {
-    const url = `${BASE_URL}/ajax/server/list?servers=${episodeIds}`;
+    // NOTE: Establish session by visiting watch page first (required for AJAX endpoints)
-    const { data: raw } = await axios.get(url, {
+    if (watchSlug) {
-      headers: {
+      await fetchWithMirror(`/watch/${watchSlug}`);
-        ...headers,
+    }
-        "X-Requested-With": "XMLHttpRequest"
+
-      }
+    const path = `/ajax/server/list?servers=${episodeIds}`;
+    const { data: raw } = await fetchWithMirror(path, {
+      headers: { "X-Requested-With": "XMLHttpRequest" }
     });
 
-    // NOTE: Response is JSON {status, result} where result is HTML
     const html = typeof raw === "string" ? raw : (raw?.result || "");
     const $ = cheerio.load(html);
 
     const servers = [];
-    // NOTE: Servers are in .servers div, grouped by type (sub/dub)
+      $(".servers .type").each((_, typeEl) => {
-    $(".servers .type").each((_, typeEl) => {
+        const type = $(typeEl).attr("data-type") || "sub";
-      const type = $(typeEl).attr("data-type") || "sub";
+        const label = $(typeEl).find("label").text().trim() || type.toUpperCase();
-      $(typeEl).find("li[data-link-id]").each((__, li) => {
+        $(typeEl).find("li[data-link-id]").each((__, li) => {
-        servers.push({
+          const rawName = $(li).text().trim() || "";
-          type,
+          servers.push({
-          ep_id: $(li).attr("data-ep-id") || "",
+            type,
-          link_id: $(li).attr("data-link-id") || "",
+            typeLabel: label,
-          cmid: $(li).attr("data-cmid") || "",
+            ep_id: $(li).attr("data-ep-id") || "",
-          sv_id: $(li).attr("data-sv-id") || "",
+            link_id: $(li).attr("data-link-id") || "",
-          name: $(li).text().trim() || ""
+            cmid: $(li).attr("data-cmid") || "",
+            sv_id: $(li).attr("data-sv-id") || "",
+            name: rawName,
+            normalizedName: normalizeServerName(rawName),
+          });
         });
       });
-    });
 
     return servers;
   } catch (error) {
@@ -139,18 +160,17 @@ const extractServerList = async (episodeIds) => {
  */
 const extractMapperServers = async (malId, slug, timestamp) => {
   try {
-    // Validate and sanitize input to prevent SSRF
     if (!Number.isFinite(Number(malId))) throw new Error("Invalid malId");
     if (!/^[a-zA-Z0-9-]+$/.test(slug)) throw new Error("Invalid slug");
     if (!Number.isFinite(Number(timestamp))) throw new Error("Invalid timestamp");
-    const url = `https://mapper.nekostream.site/api/mal/${encodeURIComponent(malId)}/${encodeURIComponent(slug)}/${encodeURIComponent(timestamp)}`;
+
-    const { data } = await axios.get(url, { headers });
+    const path = `/ajax/mapper/${encodeURIComponent(malId)}/${encodeURIComponent(slug)}/${encodeURIComponent(timestamp)}`;
+    const { data } = await fetchWithMirror(path);
 
     const servers = [];
 
     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,
@@ -172,7 +192,6 @@ const extractMapperServers = async (malId, slug, timestamp) => {
 
     return servers;
   } catch (error) {
-    // NOTE: Returns empty array on failure — mapper API may be unavailable
     return [];
   }
 };

src/extractors/streamResolver.extractor.js

@@ -0,0 +1,307 @@
+/*
+ * ======= • ======= • ======= • ======= • =======• =======
+ * AniKotoAPI — streamResolver.extractor.js
+ * Repository: https://github.com/Shineii86/AniKotoAPI
+ *
+ * @description
+ *   Resolves actual streaming video URLs (m3u8/mp4) from embed player URLs.
+ *   Follows the chain: vidtube.site embed → megaplay API → m3u8 playlist.
+ *   Supports quality selection and subtitle extraction.
+ *
+ * @exports
+ *   resolveStreamUrl, resolveStreamUrls, parseM3u8Qualities
+ *
+ * @author  Shinei Nouzen
+ * @license MIT
+ * ======= • ======= • ======= • ======= • =======• =======
+ */
+
+import axios from "axios";
+import { headers } from "../configs/header.config.js";
+
+// ══════════════════════════════════════════════════════════════
+// STREAM RESOLVER
+// ══════════════════════════════════════════════════════════════
+
+// Server name normalization map
+const SERVER_NAME_MAP = {
+  "VidPlay-1": "vidplay",
+  "VidPlay-2": "vidplay",
+  "HD-1": "hd",
+  "HD-2": "hd",
+  "Vidstream-1": "vidstream",
+  "Vidstream-2": "vidstream",
+  "VidCloud-1": "vidcloud",
+  "VidCloud-2": "vidcloud",
+  "StreamTape-1": "streamtape",
+  "StreamTape-2": "streamtape",
+};
+
+// Embed domain to API domain mapping
+const EMBED_API_MAP = {
+  "vidtube.site": "megaplay-1.buzz",
+  "vidplay.site": "megaplay-1.buzz",
+  "megaplay.buzz": "megaplay-1.buzz",
+  "embed.bunkrerrer.com": "megaplay-1.buzz",
+};
+
+/**
+ * Normalizes server display names to clean identifiers
+ * @param {string} name - Raw server name (e.g., "VidPlay-1")
+ * @returns {string} Normalized name (e.g., "vidplay")
+ */
+const normalizeServerName = (name) => {
+  if (!name) return "unknown";
+  return SERVER_NAME_MAP[name] || name.toLowerCase().replace(/[-\s]+\d+$/, "").trim();
+};
+
+/**
+ * Resolves the actual video stream URL from an embed player page.
+ * Extracts data-id from the embed HTML, then queries the megaplay API.
+ *
+ * @param {string} embedUrl - The embed player URL (e.g., vidtube.site/stream/...)
+ * @param {object} [options] - Resolution options
+ * @param {boolean} [options.followRedirects=true] - Follow HTTP redirects
+ * @param {number} [options.timeout=10000] - Request timeout in ms
+ * @returns {Promise<Object>} Object with url, qualities, skipData, type
+ *
+ * @example
+ *   const resolved = await resolveStreamUrl("https://vidtube.site/stream/...");
+ *   console.log(resolved.url);      // m3u8 URL
+ *   console.log(resolved.qualities); // [{ label: "720p", url: "..." }]
+ */
+const resolveStreamUrl = async (embedUrl, options = {}) => {
+  const { followRedirects = true, timeout = 10000 } = options;
+
+  try {
+    // NOTE: Extract the embed page to find data-id and API domain
+    const embedResponse = await axios.get(embedUrl, {
+      headers: {
+        ...headers,
+        "Referer": "https://anikototv.to/",
+        "Origin": "https://anikototv.to",
+      },
+      timeout,
+      maxRedirects: followRedirects ? 5 : 0,
+    });
+
+    const embedHtml = typeof embedResponse.data === "string"
+      ? embedResponse.data
+      : String(embedResponse.data);
+
+    // NOTE: Extract data attributes from the player div
+    const dataId = embedHtml.match(/data-id="(\d+)"/)?.[1];
+    const realId = embedHtml.match(/data-realid="([^"]+)"/)?.[1];
+    const mediaId = embedHtml.match(/data-mediaid="([^"]+)"/)?.[1];
+
+    if (!dataId) {
+      return {
+        url: null,
+        qualities: [],
+        skipData: null,
+        type: null,
+        error: "Could not extract player data-id from embed page",
+      };
+    }
+
+    // NOTE: Determine API domain from embed URL or extract from page
+    const embedDomain = new URL(embedUrl).hostname;
+    const apiDomain = EMBED_API_MAP[embedDomain] || embedDomain;
+
+    // NOTE: Query the megaplay API for the actual stream URL
+    const apiResponse = await axios.get(
+      `https://${apiDomain}/ajax/sources/${dataId}`,
+      {
+        headers: {
+          ...headers,
+          "Referer": embedUrl,
+          "Origin": `https://${embedDomain}`,
+        },
+        timeout,
+      }
+    );
+
+    const apiData = typeof apiResponse.data === "string"
+      ? (() => { try { return JSON.parse(apiResponse.data); } catch { return {}; } })()
+      : apiResponse.data;
+
+    // NOTE: Extract stream URL from API response
+    const streamUrl = apiData?.source || apiData?.url || apiData?.file || null;
+    const streamType = apiData?.type || (streamUrl?.includes(".m3u8") ? "hls" : "mp4");
+
+    // NOTE: Parse m3u8 qualities if it's an HLS stream
+    let qualities = [];
+    if (streamUrl && streamType === "hls") {
+      qualities = await parseM3u8Qualities(streamUrl, {
+        headers: {
+          ...headers,
+          "Referer": embedUrl,
+        },
+        timeout,
+      });
+    }
+
+    // NOTE: Extract subtitles if available
+    const subtitles = extractSubtitles(apiData);
+
+    return {
+      url: streamUrl,
+      type: streamType,
+      qualities,
+      subtitles,
+      skipData: apiData?.skip_data || null,
+      dataId,
+      realId,
+      mediaId,
+      backup: apiData?.backup || null,
+    };
+  } catch (error) {
+    return {
+      url: null,
+      qualities: [],
+      skipData: null,
+      type: null,
+      error: error.message,
+    };
+  }
+};
+
+/**
+ * Resolves stream URLs for multiple episodes in batch
+ * @param {string} embedUrl - The embed player URL
+ * @param {object} [options] - Resolution options
+ * @returns {Promise<Object>} Batch resolution result
+ */
+const resolveStreamUrls = async (embedUrl, options = {}) => {
+  try {
+    const resolved = await resolveStreamUrl(embedUrl, options);
+    return resolved;
+  } catch (error) {
+    return { url: null, error: error.message };
+  }
+};
+
+// ══════════════════════════════════════════════════════════════
+// M3U8 PARSER
+// ══════════════════════════════════════════════════════════════
+
+/**
+ * Parses an M3U8 playlist to extract available quality options.
+ * Supports both master playlists (multiple qualities) and media playlists.
+ *
+ * @param {string} m3u8Url - URL of the M3U8 playlist
+ * @param {object} [options] - Fetch options
+ * @param {object} [options.headers] - Custom headers
+ * @param {number} [options.timeout=10000] - Request timeout
+ * @returns {Promise<Array<Object>>} Array of quality objects
+ *
+ * @example
+ *   const qualities = await parseM3u8Qualities("https://example.com/master.m3u8");
+ *   qualities.forEach(q => console.log(`${q.label}: ${q.url}`));
+ */
+const parseM3u8Qualities = async (m3u8Url, options = {}) => {
+  const { headers: customHeaders = {}, timeout = 10000 } = options;
+
+  try {
+    const response = await axios.get(m3u8Url, {
+      headers: { ...headers, ...customHeaders },
+      timeout,
+    });
+
+    const content = typeof response.data === "string"
+      ? response.data
+      : String(response.data);
+
+    const qualities = [];
+    const lines = content.split("\n").map((l) => l.trim());
+
+    // NOTE: Parse master playlist (contains #EXT-X-STREAM-INF)
+    for (let i = 0; i < lines.length; i++) {
+      if (lines[i].startsWith("#EXT-X-STREAM-INF:")) {
+        const attrs = lines[i].substring("#EXT-X-STREAM-INF:".length);
+        const bandwidth = parseInt(attrs.match(/BANDWIDTH=(\d+)/)?.[1] || "0");
+        const resolution = attrs.match(/RESOLUTION=(\d+x\d+)/)?.[1] || "";
+        const [width, height] = resolution.split("x").map(Number);
+        const nextLine = lines[i + 1];
+
+        if (nextLine && !nextLine.startsWith("#")) {
+          // NOTE: Resolve relative URLs against base M3U8 URL
+          const qualityUrl = nextLine.startsWith("http")
+            ? nextLine
+            : new URL(nextLine, m3u8Url).href;
+
+          qualities.push({
+            label: height ? `${height}p` : `${bandwidth}bps`,
+            width: width || 0,
+            height: height || 0,
+            bandwidth,
+            url: qualityUrl,
+          });
+        }
+      }
+    }
+
+    // NOTE: If no qualities found, it's likely a single-quality stream
+    if (qualities.length === 0 && content.includes("#EXTINF")) {
+      qualities.push({
+        label: "default",
+        width: 0,
+        height: 0,
+        bandwidth: 0,
+        url: m3u8Url,
+      });
+    }
+
+    // NOTE: Sort by resolution/bandwidth descending (highest first)
+    qualities.sort((a, b) => (b.height || b.bandwidth) - (a.height || a.bandwidth));
+
+    return qualities;
+  } catch (error) {
+    return [];
+  }
+};
+
+// ══════════════════════════════════════════════════════════════
+// SUBTITLE EXTRACTOR
+// ══════════════════════════════════════════════════════════════
+
+/**
+ * Extracts subtitle information from API response data
+ * @param {object} apiData - The megaplay API response
+ * @returns {Array<Object>} Array of subtitle objects
+ */
+const extractSubtitles = (apiData) => {
+  const subtitles = [];
+
+  // NOTE: Subtitles may be in different formats depending on the source
+  if (apiData?.subtitles && Array.isArray(apiData.subtitles)) {
+    for (const sub of apiData.subtitles) {
+      subtitles.push({
+        label: sub.label || sub.language || "Unknown",
+        language: sub.code || sub.language || "unknown",
+        url: sub.url || sub.file || null,
+        format: sub.format || "srt",
+      });
+    }
+  }
+
+  // NOTE: Some sources embed subtitles in tracks array
+  if (apiData?.tracks && Array.isArray(apiData.tracks)) {
+    for (const track of apiData.tracks) {
+      if (track.kind === "subtitles" || track.type === "subtitles") {
+        subtitles.push({
+          label: track.label || track.language || "Unknown",
+          language: track.srclang || track.language || "unknown",
+          url: track.file || track.src || null,
+          format: track.format || "srt",
+        });
+      }
+    }
+  }
+
+  return subtitles;
+};
+
+export { resolveStreamUrl, resolveStreamUrls, parseM3u8Qualities, normalizeServerName, extractSubtitles };
+
+// ══════════════════════════════════════════════════════════════ END: streamResolver.extractor.js

src/extractors/suggestion.extractor.js

@@ -16,9 +16,8 @@
  */
 
 import * as cheerio from "cheerio";
-import axios from "axios";
-import { headers } from "../configs/header.config.js";
 import { URLS } from "../configs/dataUrl.js";
+import { fetchWithMirror } from "../helper/mirror.helper.js";
 
 // ══════════════════════════════════════════════════════════════
 // SUGGESTION EXTRACTION
@@ -46,14 +45,12 @@ import { URLS } from "../configs/dataUrl.js";
  */
 const extractSuggestions = async (keyword) => {
   try {
-    // NOTE: The search endpoint requires the 'keyword' parameter
+    const path = `/search?keyword=${encodeURIComponent(keyword)}`;
-    const url = `${URLS.search}?keyword=${encodeURIComponent(keyword)}`;
+    const { data } = await fetchWithMirror(path);
-    const { data } = await axios.get(url, { headers });
     const $ = cheerio.load(data);
 
     const suggestions = [];
 
-    // NOTE: Search results use the same list structure as other pages
     $("#list-items > .item").each((i, el) => {
       const slug = $(el).find("a").attr("href")?.split("/watch/").pop() || "";
       const poster = $(el).find(".ani.poster.tip > a > img").attr("src") || "";
@@ -63,13 +60,11 @@ const extractSuggestions = async (keyword) => {
       const sub = parseInt($(el).find(".ep-status.sub span").text().trim()) || 0;
       const dub = parseInt($(el).find(".ep-status.dub span").text().trim()) || 0;
 
-      // NOTE: Only include items with valid slugs
       if (slug) {
         suggestions.push({ slug, poster, title, japaneseTitle, type, sub, dub });
       }
     });
 
-    // NOTE: Limit to 10 suggestions for autocomplete-style responses
     return suggestions.slice(0, 10);
   } catch (error) {
     throw error;

src/extractors/topAnimeRankings.extractor.js

@@ -0,0 +1,92 @@
+/*
+ * ======= • ======= • ======= • ======= • =======• =======
+ * AniKotoAPI — topAnimeRankings.extractor.js
+ * Repository: https://github.com/Shineii86/AniKotoAPI
+ *
+ * @description
+ *   Extracts top anime rankings from the homepage with sort options.
+ *   Supports both "top" (all-time) and "newest" ranking modes.
+ *   Parses ranked items with position numbers 1-9.
+ *
+ * @exports
+ *   extractTopAnimeRankings
+ *
+ * @author  Shinei Nouzen
+ * @license MIT
+ * ======= • ======= • ======= • ======= • =======• =======
+ */
+
+import * as cheerio from "cheerio";
+import { fetchWithMirror } from "../helper/mirror.helper.js";
+
+// ══════════════════════════════════════════════════════════════
+// TOP ANIME RANKINGS EXTRACTION
+// ══════════════════════════════════════════════════════════════
+
+// ---- FEATURE: Extract top anime rankings with sort option ----
+/**
+ * Fetches and parses the top anime rankings from the homepage.
+ * Supports switching between "top" (all-time) and "newest" rankings.
+ *
+ * @param {string} sort - Ranking sort mode: "top" or "newest" (default: "top")
+ * @returns {Promise<Array<Object>>} Array of ranked anime objects
+ * @returns {number} return[].rank - Ranking position (1-9)
+ * @returns {string} return[].slug - URL slug for the anime
+ * @returns {string} return[].poster - Poster image URL
+ * @returns {string} return[].title - Anime title
+ * @returns {string} return[].japaneseTitle - Japanese title
+ * @returns {number} return[].sub - Subbed episode count
+ * @returns {number} return[].dub - Dubbed episode count
+ * @returns {string} return[].type - Anime type
+ * @returns {string} return[].views - View count
+ *
+ * @example
+ *   const topAnime = await extractTopAnimeRankings("top");
+ *   console.log(topAnime[0].rank); // 1
+ *   console.log(topAnime[0].title); // #1 anime
+ *
+ *   const newest = await extractTopAnimeRankings("newest");
+ *   console.log(newest[0].title); // #1 newest anime
+ */
+const extractTopAnimeRankings = async (sort = "top") => {
+  try {
+    // NOTE: Homepage contains both top and newest rankings in tabbed sections
+    const { data } = await fetchWithMirror("/home");
+    const $ = cheerio.load(data);
+
+    const results = [];
+
+    // NOTE: Ranking items live inside #top-anime .tab-content .scaff.side.items
+    // Each item is an <a class="item rankN"> with rank classes rank1..rank9
+    // The data-name on .tab-content controls which tab: day/week/month
+    const tabSelector = sort === "week" ? "[data-name='week']"
+      : sort === "month" ? "[data-name='month']"
+      : "[data-name='day']";
+
+    $(`#top-anime .tab-content${tabSelector} a.item, #top-anime .scaff.side.items a.item`).each((i, el) => {
+      const slug = $(el).attr("href")?.split("/watch/").pop() || "";
+      if (!slug) return;
+
+      const poster = $(el).find("img").attr("src") || "";
+      const title = $(el).find(".name").text().trim() || "";
+      const japaneseTitle = $(el).find(".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 type = $(el).find(".meta .dot:last-child").text().trim() || "";
+
+      // NOTE: Rank is extracted from the rankN class on the <a> element
+      const rankClass = [...$(el).attr("class") || ""].join(" ").match(/rank(\d+)/);
+      const rank = rankClass ? parseInt(rankClass[1]) : i + 1;
+
+      results.push({ rank, slug, poster, title, japaneseTitle, sub, dub, type });
+    });
+
+    return results;
+  } catch (error) {
+    throw error;
+  }
+};
+
+export { extractTopAnimeRankings };
+
+// ══════════════════════════════════════════════════════════════ END: topAnimeRankings.extractor.js

src/extractors/topten.extractor.js

@@ -16,9 +16,8 @@
  */
 
 import * as cheerio from "cheerio";
-import axios from "axios";
-import { headers } from "../configs/header.config.js";
 import { URLS } from "../configs/dataUrl.js";
+import { fetchWithMirror } from "../helper/mirror.helper.js";
 
 // ══════════════════════════════════════════════════════════════
 // TOP TEN EXTRACTION
@@ -47,15 +46,13 @@ import { URLS } from "../configs/dataUrl.js";
  */
 const extractTopTen = async () => {
   try {
-    // NOTE: The top 10 section uses tabbed content with data-name attributes
+    const { data } = await fetchWithMirror("/home");
-    const { data } = await axios.get(URLS.home, { headers });
     const $ = cheerio.load(data);
 
     const today = [];
     const week = [];
     const month = [];
 
-    // NOTE: Each tab contains a list of anime items with ranking data
     $("#top-anime .tab-content[data-name='day'] a.item").each((i, el) => {
       const slug = $(el).attr("href")?.split("/watch/").pop() || "";
       const poster = $(el).find(".poster img").attr("src") || "";
@@ -65,13 +62,11 @@ const extractTopTen = async () => {
       const type = $(el).find(".type").text().trim() || "";
       const rank = i + 1;
 
-      // NOTE: Only include items with valid slugs
       if (slug) {
         today.push({ slug, rank, name, poster, sub, dub, type });
       }
     });
 
-    // NOTE: Weekly rankings follow the same structure as daily
     $("#top-anime .tab-content[data-name='week'] a.item").each((i, el) => {
       const slug = $(el).attr("href")?.split("/watch/").pop() || "";
       const poster = $(el).find(".poster img").attr("src") || "";
@@ -86,7 +81,6 @@ const extractTopTen = async () => {
       }
     });
 
-    // NOTE: Monthly rankings follow the same structure
     $("#top-anime .tab-content[data-name='month'] a.item").each((i, el) => {
       const slug = $(el).attr("href")?.split("/watch/").pop() || "";
       const poster = $(el).find(".poster img").attr("src") || "";

src/extractors/trending.extractor.js

@@ -16,9 +16,8 @@
  */
 
 import * as cheerio from "cheerio";
-import axios from "axios";
-import { headers } from "../configs/header.config.js";
 import { URLS } from "../configs/dataUrl.js";
+import { fetchWithMirror } from "../helper/mirror.helper.js";
 
 // ══════════════════════════════════════════════════════════════
 // TRENDING EXTRACTION
@@ -45,13 +44,11 @@ import { URLS } from "../configs/dataUrl.js";
  */
 const extractTrending = async () => {
   try {
-    // NOTE: Trending data is split across multiple sections on the homepage
+    const { data } = await fetchWithMirror("/home");
-    const { data } = await axios.get(URLS.home, { headers });
     const $ = cheerio.load(data);
 
     const trending = [];
 
-    // NOTE: This selector targets both the updated section and recent updates
     $(".section-updated .item, #recent-update .item").each((i, el) => {
       const slug = $(el).find("a.name.d-title").attr("href")?.split("/watch/").pop() || "";
       const poster = $(el).find(".poster img").attr("src") || "";
@@ -62,7 +59,6 @@ const extractTrending = async () => {
       const total = parseInt($(el).find(".ep-status.total span").text().trim()) || 0;
       const type = $(el).find(".meta .inner .right").text().trim() || "";
 
-      // NOTE: Only include items with valid slugs
       if (slug) {
         trending.push({
           slug,

src/extractors/trendingSidebar.extractor.js

@@ -16,9 +16,8 @@
  */
 
 import * as cheerio from "cheerio";
-import axios from "axios";
-import { headers } from "../configs/header.config.js";
 import { URLS } from "../configs/dataUrl.js";
+import { fetchWithMirror } from "../helper/mirror.helper.js";
 
 // ══════════════════════════════════════════════════════════════
 // TRENDING SIDEBAR EXTRACTION
@@ -49,15 +48,13 @@ import { URLS } from "../configs/dataUrl.js";
  */
 const extractTrendingSidebar = async () => {
   try {
-    // NOTE: The sidebar content is embedded in the homepage HTML
+    const { data } = await fetchWithMirror("/home");
-    const { data } = await axios.get(URLS.home, { headers });
     const $ = cheerio.load(data);
 
     const day = [];
     const week = [];
     const month = [];
 
-    // NOTE: Daily rankings use the 'day' tab content
     $("#top-anime .tab-content[data-name='day'] a.item").each((i, el) => {
       const slug = $(el).attr("href")?.split("/watch/").pop() || "";
       const poster = $(el).find(".poster img").attr("src") || "";
@@ -67,13 +64,11 @@ const extractTrendingSidebar = async () => {
       const type = $(el).find(".type").text().trim() || "";
       const rank = i + 1;
 
-      // NOTE: Only include items with valid slugs
       if (slug) {
         day.push({ slug, rank, name, poster, sub, dub, type });
       }
     });
 
-    // NOTE: Weekly rankings use the 'week' tab content
     $("#top-anime .tab-content[data-name='week'] a.item").each((i, el) => {
       const slug = $(el).attr("href")?.split("/watch/").pop() || "";
       const poster = $(el).find(".poster img").attr("src") || "";
@@ -88,7 +83,6 @@ const extractTrendingSidebar = async () => {
       }
     });
 
-    // NOTE: Monthly rankings use the 'month' tab content
     $("#top-anime .tab-content[data-name='month'] a.item").each((i, el) => {
       const slug = $(el).attr("href")?.split("/watch/").pop() || "";
       const poster = $(el).find(".poster img").attr("src") || "";
@@ -103,7 +97,6 @@ const extractTrendingSidebar = async () => {
       }
     });
 
-    // NOTE: Latest episodes section provides recently updated content
     const latestEpisodes = [];
     $("#recent-update .item, .section-updated .item").each((i, el) => {
       const slug = $(el).find("a.name.d-title").attr("href")?.split("/watch/").pop() || "";

src/extractors/upcomingAnime.extractor.js

@@ -0,0 +1,73 @@
+/*
+ * ======= • ======= • ======= • ======= • =======• =======
+ * AniKotoAPI — upcomingAnime.extractor.js
+ * Repository: https://github.com/Shineii86/AniKotoAPI
+ *
+ * @description
+ *   Extracts upcoming anime from the homepage section.
+ *   Scrapes the #upcoming-anime section for future releases.
+ *
+ * @exports
+ *   extractUpcomingAnime
+ *
+ * @author  Shinei Nouzen
+ * @license MIT
+ * ======= • ======= • ======= • ======= • =======• =======
+ */
+
+import * as cheerio from "cheerio";
+import { fetchWithMirror } from "../helper/mirror.helper.js";
+import { parseListItems } from "../helper/parseListItem.helper.js";
+
+// ══════════════════════════════════════════════════════════════
+// UPCOMING ANIME EXTRACTION
+// ══════════════════════════════════════════════════════════════
+
+// ---- FEATURE: Extract upcoming anime from homepage section ----
+/**
+ * Fetches and parses the upcoming anime section from the homepage.
+ * Returns a list of anime that are scheduled for future release.
+ *
+ * @returns {Promise<Array<Object>>} Array of upcoming anime objects
+ * @returns {string} return[].slug - URL slug for the anime
+ * @returns {string} return[].poster - Poster image URL
+ * @returns {string} return[].title - English title
+ * @returns {string} return[].japaneseTitle - Japanese title
+ * @returns {string} return[].type - Anime type (TV, Movie, etc.)
+ * @returns {string} return[].releaseDate - Expected release date
+ *
+ * @example
+ *   const upcoming = await extractUpcomingAnime();
+ *   console.log(upcoming.length); // number of upcoming anime
+ *   console.log(upcoming[0].title); // first upcoming anime title
+ */
+const extractUpcomingAnime = async () => {
+  try {
+    const { data } = await fetchWithMirror("/home");
+    const $ = cheerio.load(data);
+
+    const results = [];
+
+    // NOTE: upcoming-anime section contains future releases
+    $("#upcoming-anime .item, .upcoming .item").each((i, el) => {
+      const slug = $(el).find("a").attr("href")?.split("/watch/").pop() || "";
+      if (!slug) return;
+
+      const poster = $(el).find("img").attr("src") || "";
+      const title = $(el).find(".film-name a, .name.d-title, a.name").text().trim() || "";
+      const japaneseTitle = $(el).find(".name.d-title, a.name").attr("data-jp") || "";
+      const type = $(el).find(".type, .fdi-item:nth-child(2)").text().trim() || "";
+      const releaseDate = $(el).find(".date, .release-date").text().trim() || "";
+
+      results.push({ slug, poster, title, japaneseTitle, type, releaseDate });
+    });
+
+    return results;
+  } catch (error) {
+    throw error;
+  }
+};
+
+export { extractUpcomingAnime };
+
+// ══════════════════════════════════════════════════════════════ END: upcomingAnime.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.
+ *   Extracts watch order and related anime information from the
- *   Returns recommended viewing order from the internal API endpoint.
+ *   watch page sidebar. Returns trending/related anime with their
+ *   metadata for continuous viewing.
  *
  * @exports
  *   extractWatchOrder
@@ -15,44 +16,72 @@
  * ======= • ======= • ======= • ======= • =======• =======
  */
 
-import axios from "axios";
+import * as cheerio from "cheerio";
-import { headers } from "../configs/header.config.js";
+import { fetchWithMirror } from "../helper/mirror.helper.js";
-import { BASE_URL } from "../configs/dataUrl.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.
+ * Fetches and parses watch order / related anime for an anime.
- * Returns an array of watch order objects or empty array on error.
+ * Extracts related anime from the watch page sidebar.
  *
- * @param {string} animeId - The anime ID to fetch watch order for
+ * @param {string|number} slugOrId - The anime slug or numeric ID
- * @returns {Promise<Array<Object>>} Array of watch order objects or empty array
+ * @returns {Promise<Object>} Object with animeId, totalRelated, related array
  *
  * @example
- *   const watchOrder = await extractWatchOrder("12345");
+ *   const data = await extractWatchOrder("one-piece-odmau");
- *   console.log(watchOrder[0].title); // First anime in watch order
+ *   console.log(data.totalRelated);
  */
-const extractWatchOrder = async (animeId) => {
+const extractWatchOrder = async (slugOrId) => {
   try {
-    // NOTE: This is an internal API endpoint requiring X-Requested-With header
+    const path = /^\d+$/.test(slugOrId) ? `/watch/${slugOrId}` : `/watch/${slugOrId}`;
-    const url = `${BASE_URL}/api/watch-order/${animeId}`;
+    const { data } = await fetchWithMirror(path);
-    const { data } = await axios.get(url, {
+
-      headers: {
+    const html = typeof data === "string" ? data : String(data);
-        ...headers,
+    const $ = cheerio.load(html);
-        "X-Requested-With": "XMLHttpRequest"
+
+    const animeId = parseInt($("#watch-main").attr("data-id")) || 0;
+    const related = [];
+
+    // NOTE: Extract from #w-related section
+    $("#w-related .item, .w-side-section:has(.title:contains('Related')) .item").each((_, el) => {
+      const link = $(el).find("a").first();
+      const href = link.attr("href") || "";
+      const title = $(el).find(".name").text().trim() || "";
+      const poster = $(el).find("img").attr("src") || "";
+      const slug = href.split("/watch/").pop() || "";
+      const relation = $(el).find(".relation, .serieslabelitem").text().trim() || "related";
+
+      if (slug) {
+        related.push({ title, slug, poster, url: href, relation });
       }
     });
 
-    return data || [];
+    // NOTE: Also extract trending sidebar items as suggested watch order
+    if (related.length === 0) {
+      $(".w-side-section:has(.title:contains('Trending')) .item, .w-side-section:first .item").each((_, el) => {
+        const link = $(el).find("a").first();
+        const href = link.attr("href") || "";
+        const title = $(el).find(".name").text().trim() || "";
+        const poster = $(el).find("img").attr("src") || "";
+        const slug = href.split("/watch/").pop() || "";
+        const score = $(el).find(".score").text().trim() || "";
+        const type = $(el).find(".meta .dot:last-child").text().trim() || "";
+        const episodes = $(el).find(".meta .dot:first-child").text().trim() || "";
+
+        if (slug && slug !== slugOrId) {
+          related.push({ title, slug, poster, url: href, relation: "trending", score, type, episodes });
+        }
+      });
+    }
+
+    return {
+      animeId,
+      slug: slugOrId,
+      totalRelated: related.length,
+      related,
+    };
   } catch (error) {
-    // NOTE: Return empty array on error to maintain consistent API
     throw error;
   }
 };
 
 export { extractWatchOrder };
-
-// ══════════════════════════════════════════════════════════════ END: watchOrder.extractor.js

src/extractors/watchPage.extractor.js

@@ -16,9 +16,8 @@
  */
 
 import * as cheerio from "cheerio";
-import axios from "axios";
-import { headers } from "../configs/header.config.js";
 import { URLS, BASE_URL } from "../configs/dataUrl.js";
+import { fetchWithMirror } from "../helper/mirror.helper.js";
 
 // ══════════════════════════════════════════════════════════════
 // WATCH PAGE EXTRACTOR
@@ -41,54 +40,40 @@ import { URLS, BASE_URL } from "../configs/dataUrl.js";
  */
 const extractWatchPage = async (slug, ep) => {
   try {
-    const url = URLS.episode(slug, ep);
+    const path = `/watch/${slug}/ep-${ep}`;
-    const { data } = await axios.get(url, { headers });
+    const { data } = await fetchWithMirror(path);
     const $ = cheerio.load(data);
 
-    // ---- FEATURE: Extract anime identification and title ----
-    // NOTE: data-id on #watch-main is the internal anime ID for AJAX calls
     const animeId = parseInt($("#watch-main").attr("data-id")) || 0;
     const animeUrl = $("#watch-main").attr("data-url") || "";
     const title = $("h1[itemprop='name'].title.d-title").text().trim() || slug;
     const japaneseTitle = $("h1[itemprop='name'].title.d-title").attr("data-jp") || "";
     const episodeNumber = parseInt(ep) || 0;
 
-    // ---- FEATURE: Extract synopsis and rating ----
     const synopsis = $(".synopsis .content").text().trim() || "";
     const rating = $("#w-rating .score .value").text().trim() || "";
     const poster = $("img[itemprop='image']").attr("src") || "";
-    // NOTE: Background image is extracted from CSS background-image property on #player
     const backgroundImage = $("#player").css("background-image")?.match(/url\(['"]?(.+?)['"]?\)/)?.[1] || "";
 
-    // ---- FEATURE: Extract anime metadata (type, status, MAL score, duration, episodes) ----
     const type = $(".bmeta .meta:first-child > div:nth-child(1) span").text().trim() || "";
     const status = $(".bmeta .meta:first-child > div:nth-child(4) span a").text().trim() || "";
     const malScore = $(".bmeta .meta:nth-child(2) > div:nth-child(1) span").text().trim() || "";
     const duration = $(".bmeta .meta:nth-child(2) > div:nth-child(2) span").text().trim() || "";
     const episodes = $(".bmeta .meta:nth-child(2) > div:nth-child(3) span").text().trim() || "";
 
-    // ---- FEATURE: Extract genres ----
-    // NOTE: Genre links contain '/genre/' in href to distinguish from other links
     const genres = [];
     $(".bmeta .meta:first-child > div:nth-child(5) span a[href*='/genre/']").each((i, el) => {
       genres.push($(el).text().trim());
     });
 
-    // ---- FEATURE: Extract studios ----
-    // NOTE: Uses itemprop='director' links with itemprop='name' spans inside
     const studios = [];
     $(".bmeta .meta:nth-child(2) > div:nth-child(4) span a[itemprop='director'] span[itemprop='name']").each((i, el) => {
       studios.push($(el).text().trim());
     });
 
-    // ---- FEATURE: Extract next episode release info ----
-    // NOTE: .next-episode shows the countdown text, .count-down has data-target timestamp
     const nextEpisodeDate = $(".next-episode, .alert.next-episode").text().trim() || "";
     const nextEpisodeTimestamp = parseInt($(".count-down").attr("data-target")) || 0;
 
-    // ---- FEATURE: Extract available streaming servers ----
-    // NOTE: Each server li has data-link-id (unique), data-ep-id, data-cmid, data-sv-id
-    // NOTE: Server type (sub/dub) is derived from closest .type container's data-type attribute
     const servers = [];
     $("#w-servers .servers .type li, #w-servers li[data-link-id]").each((i, el) => {
       const linkId = $(el).attr("data-link-id") || "";
@@ -110,14 +95,11 @@ const extractWatchPage = async (slug, ep) => {
       }
     });
 
-    // ---- FEATURE: Extract trending/watch-order sidebar items ----
-    // NOTE: Grabs from both the first .w-side-section and #watch-order containers
     const trending = [];
     $(".w-side-section:first .scaff.side.items a.item, #watch-order a.item").each((i, el) => {
       const trendSlug = $(el).attr("href")?.split("/watch/").pop() || "";
       const trendPoster = $(el).find(".poster img").attr("src") || "";
       const trendTitle = $(el).find(".name").text().trim() || "";
-      // NOTE: .dot:last-child typically holds the type badge text
       const trendType = $(el).find(".dot:last-child").text().trim() || "";
       const trendScore = $(el).find(".score").text().trim() || "";
 
@@ -132,8 +114,6 @@ const extractWatchPage = async (slug, ep) => {
       }
     });
 
-    // ---- FEATURE: Extract recommended anime sidebar items ----
-    // NOTE: Targets the section with a title containing "Recommended", or the last sidebar
     const recommended = [];
     $(".w-side-section:has(.title:contains('Recommended')) a.item, aside.sidebar:last .w-side-section a.item").each((i, el) => {
       const recSlug = $(el).attr("href")?.split("/watch/").pop() || "";

src/helper/cache.helper.js

@@ -4,109 +4,117 @@
  * Repository: https://github.com/Shineii86/AniKotoAPI
  *
  * @description
- *   In-memory caching utility for storing and retrieving API responses.
+ *   In-memory LRU cache with configurable TTL per endpoint.
- *   Implements TTL-based cache invalidation to prevent stale data
+ *   Evicts least recently used entries when max size reached.
- *   while reducing unnecessary requests to the source site.
+ *   Supports cache statistics and manual invalidation.
  *
  * @exports
- *   getCache, setCache, clearCache
+ *   getCache, setCache, clearCache, getCacheStats, LRUCache
  *
  * @author  Shinei Nouzen
  * @license MIT
  * ======= • ======= • ======= • ======= • =======• =======
  */
 
-// ══════════════════════════════════════════════════════════════
+class LRUCache {
-// CACHE STORAGE & CONFIGURATION
+  constructor(maxSize = 100, defaultTTL = 300000) {
-// ══════════════════════════════════════════════════════════════
+    this.cache = new Map();
-
+    this.maxSize = maxSize;
-// ---- FEATURE: In-memory Map-based cache storage ----
+    this.defaultTTL = defaultTTL;
-/**
+    this.stats = { hits: 0, misses: 0, sets: 0, deletes: 0 };
- * Internal cache storage using JavaScript Map object.
- * Stores data with timestamps for TTL-based expiration.
- *
- * @type {Map<string, {data: any, timestamp: number}>}
- */
-const cache = new Map();
-
-// ---- FEATURE: Cache time-to-live configuration (5 minutes) ----
-/**
- * Cache TTL (Time-To-Live) in milliseconds.
- * Default: 5 minutes (300,000 ms).
- * After this duration, cached items are considered stale
- * and will be removed on next access.
- *
- * @type {number}
- * @default 300000
- */
-const CACHE_TTL = 5 * 60 * 1000;
-
-// ══════════════════════════════════════════════════════════════
-// CACHE OPERATIONS
-// ══════════════════════════════════════════════════════════════
-
-// ---- FEATURE: Retrieve cached data by key with TTL validation ----
-/**
- * Retrieves data from cache if it exists and hasn't expired.
- * Automatically removes stale entries on access.
- *
- * @param {string} key - The cache key to lookup
- * @returns {any|null} Cached data if valid, null if expired or missing
- *
- * @example
- *   // Get cached anime list
- *   const data = getCache("anime-list-action");
- *   if (data) {
- *     // Use cached data
- *   }
- */
-const getCache = (key) => {
-  const item = cache.get(key);
-  if (item && Date.now() - item.timestamp < CACHE_TTL) {
-    return item.data;
   }
-  cache.delete(key);
-  return null;
-};
 
-// ---- FEATURE: Store data in cache with current timestamp ----
+  get(key) {
-/**
+    if (!this.cache.has(key)) {
- * Stores data in cache with current timestamp for TTL tracking.
+      this.stats.misses++;
- * Overwrites any existing data for the same key.
+      return undefined;
- *
+    }
- * @param {string} key - The cache key to store under
+
- * @param {any} data - The data to cache (any serializable type)
+    const entry = this.cache.get(key);
- * @returns {void}
+    if (Date.now() > entry.expiresAt) {
- *
+      this.cache.delete(key);
- * @example
+      this.stats.misses++;
- *   // Cache anime search results
+      return undefined;
- *   setCache("search-one-piece", animeResults);
+    }
- */
+
-const setCache = (key, data) => {
+    this.stats.hits++;
-  // Evict oldest entries if cache is full
+    this.cache.delete(key);
-  if (cache.size >= MAX_CACHE_SIZE) {
+    this.cache.set(key, entry);
-    const oldestKey = cache.keys().next().value;
+    return entry.value;
-    cache.delete(oldestKey);
   }
-  cache.set(key, { data, timestamp: Date.now() });
+
+  set(key, value, ttl) {
+    if (this.cache.has(key)) {
+      this.cache.delete(key);
+    }
+
+    if (this.cache.size >= this.maxSize) {
+      const firstKey = this.cache.keys().next().value;
+      this.cache.delete(firstKey);
+    }
+
+    this.cache.set(key, {
+      value,
+      expiresAt: Date.now() + (ttl || this.defaultTTL)
+    });
+    this.stats.sets++;
+  }
+
+  delete(key) {
+    const existed = this.cache.delete(key);
+    if (existed) this.stats.deletes++;
+    return existed;
+  }
+
+  clear() {
+    const size = this.cache.size;
+    this.cache.clear();
+    return size;
+  }
+
+  getStats() {
+    const total = this.stats.hits + this.stats.misses;
+    return {
+      ...this.stats,
+      size: this.cache.size,
+      hitRate: total > 0 ? ((this.stats.hits / total) * 100).toFixed(2) + '%' : '0%'
+    };
+  }
+
+  has(key) {
+    if (!this.cache.has(key)) return false;
+    const entry = this.cache.get(key);
+    if (Date.now() > entry.expiresAt) {
+      this.cache.delete(key);
+      return false;
+    }
+    return true;
+  }
+}
+
+const TTL = {
+  home: 600000,
+  search: 300000,
+  info: 600000,
+  episodes: 300000,
+  servers: 600000,
+  stream: 180000,
+  spotlight: 600000,
+  trending: 600000,
+  schedule: 1800000,
+  genres: 3600000,
+  suggestions: 300000,
+  default: 300000
 };
 
-// ---- FEATURE: Clear all cached entries from memory ----
+const cache = new LRUCache(
-/**
+  parseInt(process.env.CACHE_MAX_SIZE) || 200,
- * Clears all entries from the cache. Use when:
+  parseInt(process.env.CACHE_DEFAULT_TTL) || 300000
- * - Memory cleanup is needed
+);
- * - Force-refreshing all data
- * - Application restart/reset
- *
- * @returns {void}
- *
- * @example
- *   // Force refresh all cached data
- *   clearCache();
- */
-const clearCache = () => {
-  cache.clear();
-};
 
-export { getCache, setCache, clearCache };
+const getCache = (key) => cache.get(key);
-// ══════════════════════════════════════════════════════════════ END: cache.helper.js
+const setCache = (key, data, ttl) => cache.set(key, data, ttl);
+const clearCache = () => cache.clear();
+const getCacheStats = () => cache.getStats();
+
+export { getCache, setCache, clearCache, getCacheStats, LRUCache, TTL };

src/helper/extractPages.helper.js

@@ -5,8 +5,8 @@
  *
  * @description
  *   HTTP client utility for fetching and parsing HTML content from
- *   paginated URLs. Uses axios for HTTP requests and Cheerio for
+ *   paginated URLs. Uses mirror fallback for resilience and Cheerio
- *   DOM parsing, with support for page-based pagination.
+ *   for DOM parsing, with support for page-based pagination.
  *
  * @exports
  *   extractPages
@@ -16,73 +16,39 @@
  * ======= • ======= • ======= • ======= • =======• =======
  */
 
-// ══════════════════════════════════════════════════════════════
-// DEPENDENCIES
-// ══════════════════════════════════════════════════════════════
-
-// ---- FEATURE: Cheerio HTML parser import ----
-/**
- * Cheerio library for server-side DOM manipulation.
- * Used to parse and query HTML content from fetched pages.
- *
- * @type {module:cheerio}
- */
 import * as cheerio from "cheerio";
+import { fetchWithMirror } from "./mirror.helper.js";
 
-// ---- FEATURE: Axios HTTP client import ----
 /**
- * Axios HTTP client for making requests to the source site.
+ * Fetches HTML content from a URL with pagination and mirror fallback.
- * Handles redirects, timeouts, and response parsing.
+ * Automatically tries alternative domains if primary fails.
  *
- * @type {module:axios}
+ * @param {string} url - Base URL path to fetch (e.g., "/filter?keyword=naruto")
- */
-import axios from "axios";
-
-// ---- FEATURE: Browser-mimicking headers import ----
-/**
- * Pre-configured HTTP headers to mimic browser requests.
- * Imported from header.config.js for consistent usage.
- *
- * @type {Object}
- */
-import { headers } from "../configs/header.config.js";
-
-// ══════════════════════════════════════════════════════════════
-// PAGE EXTRACTION FUNCTION
-// ══════════════════════════════════════════════════════════════
-
-// ---- FEATURE: Fetch and parse paginated URL content ----
-/**
- * Fetches HTML content from a URL with optional pagination support.
- * Appends page query parameter for pages > 1 and returns parsed
- * Cheerio instance for DOM querying.
- *
- * @param {string} url - Base URL to fetch (without page parameter)
  * @param {number} [page=1] - Page number to fetch (1-indexed)
  * @returns {Promise<CheerioAPI>} Parsed Cheerio instance of the page
- * @throws {Error} If HTTP request fails or returns non-2xx status
  *
  * @example
- *   // Fetch first page of search results
+ *   const $ = await extractPages("/filter?keyword=one-piece");
- *   const $ = await extractPages("https://anikototv.to/filter?keyword=one-piece");
+ *   const $page2 = await extractPages("/filter?keyword=one-piece", 2);
- *
- * @example
- *   // Fetch second page of genre listing
- *   const $ = await extractPages(genreUrl, 2);
- *
- * @note
- *   WARNING: The site may block requests without proper headers.
- *   Always use the imported headers configuration.
- *
- * @note
- *   TIP: Consider implementing retry logic for failed requests
- *   in production environments.
  */
 const extractPages = async (url, page = 1) => {
   try {
-    const separator = url.includes("?") ? "&" : "?";
+    // NOTE: Extract path from full URL if needed (e.g., "https://anikototv.to/filter" -> "/filter")
-    const finalUrl = page > 1 ? `${url}${separator}page=${page}` : url;
+    let path = url;
-    const { data } = await axios.get(finalUrl, { headers });
+    if (url.startsWith("http")) {
+      try {
+        const urlObj = new URL(url);
+        path = urlObj.pathname + urlObj.search;
+      } catch (e) {
+        // If URL parsing fails, try to extract path manually
+        const match = url.match(/https?:\/\/[^/]+(\/.*)/);
+        if (match) path = match[1];
+      }
+    }
+    
+    const separator = path.includes("?") ? "&" : "?";
+    const fullPath = page > 1 ? `${path}${separator}page=${page}` : path;
+    const { data } = await fetchWithMirror(fullPath);
     const $ = cheerio.load(data);
     return $;
   } catch (error) {
@@ -91,4 +57,3 @@ const extractPages = async (url, page = 1) => {
 };
 
 export { extractPages };
-// ══════════════════════════════════════════════════════════════ END: extractPages.helper.js

src/helper/mirror.helper.js

@@ -0,0 +1,262 @@
+/*
+ * ======= • ======= • ======= • ======= • =======• =======
+ * AniKotoAPI — mirror.helper.js
+ * Repository: https://github.com/Shineii86/AniKotoAPI
+ *
+ * @description
+ *   Multi-mirror fallback helper for resilient scraping.
+ *   Automatically tries alternative domains if primary is blocked/down.
+ *   Caches working mirror per session for faster subsequent requests.
+ *
+ * @exports
+ *   fetchWithMirror, getWorkingMirror, resetMirrorCache
+ *
+ * @author  Shinei Nouzen
+ * @license MIT
+ * ======= • ======= • ======= • ======= • =======• =======
+ */
+
+import axios from "axios";
+import { headers } from "../configs/header.config.js";
+import { getCache, setCache } from "./cache.helper.js";
+
+// ══════════════════════════════════════════════════════════════
+// MIRROR CONFIGURATION
+// ══════════════════════════════════════════════════════════════
+
+// Default mirrors with names and priority
+const DEFAULT_MIRRORS = [
+  { url: "https://anikototv.to", name: "Primary", priority: 1 },
+  { url: "https://anikoto.cz", name: "Regional CZ", priority: 2 },
+  { url: "https://anikoto.me", name: "Short TLD", priority: 3 },
+  { url: "https://anikoto.net", name: "Network", priority: 4 },
+  { url: "https://anikototv.se", name: "Nordic .se", priority: 5 },
+];
+
+// Parse custom mirrors from env or use defaults
+function parseMirrors() {
+  const envMirrors = process.env.MIRROR_DOMAINS;
+  if (!envMirrors) return DEFAULT_MIRRORS;
+  
+  return envMirrors.split(",").map((url, index) => ({
+    url: url.trim(),
+    name: `Mirror ${index + 1}`,
+    priority: index + 1
+  }));
+}
+
+const ALL_MIRRORS = parseMirrors();
+ALL_MIRRORS.sort((a, b) => a.priority - b.priority);
+
+// Cache key for working mirror
+const MIRROR_CACHE_KEY = "working_mirror";
+const MIRROR_CACHE_TTL = parseInt(process.env.MIRROR_CACHE_TTL) || 3600000;
+
+// ══════════════════════════════════════════════════════════════
+// MIRROR STATE
+// ══════════════════════════════════════════════════════════════
+
+let workingMirror = null;
+let failedMirrors = new Set();
+
+// ══════════════════════════════════════════════════════════════
+// HELPER FUNCTIONS
+// ══════════════════════════════════════════════════════════════
+
+/**
+ * Check if a mirror is accessible
+ * @param {string} baseUrl - Mirror base URL
+ * @returns {Promise<boolean>}
+ */
+async function checkMirror(baseUrl) {
+  try {
+    const response = await axios.get(`${baseUrl}/home`, {
+      headers,
+      timeout: 10000,
+      maxRedirects: 5,
+    });
+    return response.status === 200;
+  } catch (error) {
+    return false;
+  }
+}
+
+/**
+ * Get the best available mirror
+ * @returns {Promise<string>} Working mirror base URL
+ */
+async function getWorkingMirror() {
+  // Check cache first
+  const cached = getCache(MIRROR_CACHE_KEY);
+  if (cached && !failedMirrors.has(cached)) {
+    workingMirror = cached;
+    return workingMirror;
+  }
+
+  // Try mirrors in priority order
+  for (const mirror of ALL_MIRRORS) {
+    if (failedMirrors.has(mirror.url)) continue;
+
+    const isWorking = await checkMirror(mirror.url);
+    if (isWorking) {
+      workingMirror = mirror.url;
+      setCache(MIRROR_CACHE_KEY, mirror.url, MIRROR_CACHE_TTL);
+      console.log(`[MIRROR] Using: ${mirror.name} (${mirror.url})`);
+      return mirror.url;
+    } else {
+      failedMirrors.add(mirror.url);
+      console.log(`[MIRROR] Failed: ${mirror.name} (${mirror.url})`);
+    }
+  }
+
+  // All mirrors failed, reset and try again
+  failedMirrors.clear();
+  workingMirror = ALL_MIRRORS[0].url;
+  console.log(`[MIRROR] All failed, resetting to primary: ${workingMirror}`);
+  return workingMirror;
+}
+
+/**
+ * Reset mirror cache and failed state
+ */
+function resetMirrorCache() {
+  workingMirror = null;
+  failedMirrors.clear();
+  setCache(MIRROR_CACHE_KEY, null, 0);
+  console.log("[MIRROR] Cache reset");
+}
+
+/**
+ * Build URL with current mirror
+ * @param {string} path - URL path
+ * @param {string} baseUrl - Optional custom base URL
+ * @returns {string} Full URL
+ */
+function buildUrl(path, baseUrl = workingMirror) {
+  const base = baseUrl || ALL_MIRRORS[0].url;
+  return `${base}${path}`;
+}
+
+/**
+ * Fetch with automatic mirror fallback
+ * @param {string} path - URL path to fetch
+ * @param {object} options - Additional options
+ * @returns {Promise<{data: string, mirror: string}>}
+ */
+async function fetchWithMirror(path, options = {}) {
+  const { 
+    timeout = 15000, 
+    retries = 2,
+    returnType = "text",
+    headers: customHeaders = {}
+  } = options;
+
+  // Merge default headers with custom headers
+  const requestHeaders = { ...headers, ...customHeaders };
+
+  let lastError = null;
+
+  // Try cached working mirror first
+  const mirrorsToTry = [];
+  
+  if (workingMirror && !failedMirrors.has(workingMirror)) {
+    mirrorsToTry.push(workingMirror);
+  }
+
+  // Add remaining mirrors
+  for (const mirror of ALL_MIRRORS) {
+    if (!mirrorsToTry.includes(mirror.url) && !failedMirrors.has(mirror.url)) {
+      mirrorsToTry.push(mirror.url);
+    }
+  }
+
+  // If all failed, reset and try all
+  if (mirrorsToTry.length === 0) {
+    failedMirrors.clear();
+    mirrorsToTry.push(...ALL_MIRRORS.map(m => m.url));
+  }
+
+  for (const mirror of mirrorsToTry) {
+    const url = buildUrl(path, mirror);
+    
+    for (let attempt = 0; attempt <= retries; attempt++) {
+      try {
+        const response = await axios.get(url, {
+          headers: requestHeaders,
+          timeout,
+          responseType: returnType === "text" ? "text" : "json",
+        });
+
+        if (response.status === 200) {
+          // Update working mirror
+          if (mirror !== workingMirror) {
+            workingMirror = mirror;
+            setCache(MIRROR_CACHE_KEY, mirror, MIRROR_CACHE_TTL);
+            console.log(`[MIRROR] Switched to: ${mirror}`);
+          }
+          return { 
+            data: returnType === "text" ? response.data : response.data,
+            mirror 
+          };
+        }
+
+        // NOTE: 404 means endpoint doesn't exist, not mirror failure — don't retry
+        if (response.status === 404) {
+          throw new Error(`Endpoint not found: ${path}`);
+        }
+      } catch (error) {
+        lastError = error;
+        // NOTE: Don't retry on 404 — the endpoint simply doesn't exist on this mirror
+        if (error.message?.includes("Endpoint not found")) {
+          break;
+        }
+        if (attempt < retries) {
+          // Wait before retry
+          await new Promise(r => setTimeout(r, 500 * (attempt + 1)));
+        }
+      }
+    }
+
+    // NOTE: Only mark mirror as failed for connection errors, not endpoint 404s
+    if (!lastError.message?.includes("Endpoint not found")) {
+      failedMirrors.add(mirror);
+      console.log(`[MIRROR] Marked as failed: ${mirror}`);
+    }
+  }
+
+  throw new Error(`All mirrors failed. Last error: ${lastError?.message}`);
+}
+
+/**
+ * Get mirror status for all domains
+ * @returns {Promise<Array>}
+ */
+async function getMirrorStatus() {
+  const status = [];
+  
+  for (const mirror of ALL_MIRRORS) {
+    const start = Date.now();
+    const isWorking = await checkMirror(mirror.url);
+    const latency = Date.now() - start;
+    
+    status.push({
+      name: mirror.name,
+      url: mirror.url,
+      priority: mirror.priority,
+      status: isWorking ? "online" : "offline",
+      latency: `${latency}ms`,
+      isCurrent: mirror.url === workingMirror,
+    });
+  }
+  
+  return status;
+}
+
+export { 
+  fetchWithMirror, 
+  getWorkingMirror, 
+  resetMirrorCache, 
+  buildUrl,
+  getMirrorStatus,
+  ALL_MIRRORS
+};

src/helper/pagination.helper.js

@@ -0,0 +1,59 @@
+/*
+ * ======= • ======= • ======= • ======= • =======• =======
+ * AniKotoAPI — pagination.helper.js
+ * Repository: https://github.com/Shineii86/AniKotoAPI
+ *
+ * @description
+ *   Utility function to add pagination metadata to API responses.
+ *   Provides standardized pagination info for all paginated endpoints.
+ *
+ * @exports
+ *   addPaginationMeta
+ *
+ * @author  Shinei Nouzen
+ * @license MIT
+ * ======= • ======= • ======= • ======= • =======• =======
+ */
+
+/**
+ * Adds pagination metadata to a response object.
+ *
+ * @param {object} data - The data object containing `data` array and optionally `totalPages`
+ * @param {number} currentPage - Current page number (1-indexed)
+ * @param {number} [itemsPerPage=30] - Number of items per page
+ * @returns {object} Object with data and pagination metadata
+ *
+ * @example
+ *   const response = addPaginationMeta({ data: [...], totalPages: 5 }, 1, 30);
+ *   // response = {
+ *   //   data: [...],
+ *   //   pagination: {
+ *   //     currentPage: 1,
+ *   //     totalPages: 5,
+ *   //     totalItems: 150,
+ *   //     itemsPerPage: 30,
+ *   //     hasNext: true,
+ *   //     hasPrev: false
+ *   //   }
+ *   // }
+ */
+const addPaginationMeta = (data, currentPage, itemsPerPage = 30) => {
+  const totalPages = data.totalPages || 1;
+  const page = parseInt(currentPage) || 1;
+  const totalItems = data.data ? data.data.length * totalPages : 0;
+
+  return {
+    ...data,
+    pagination: {
+      currentPage: page,
+      totalPages: totalPages,
+      totalItems: totalItems,
+      itemsPerPage: itemsPerPage,
+      hasNext: page < totalPages,
+      hasPrev: page > 1,
+    },
+  };
+};
+
+export { addPaginationMeta };
+// ══════════════════════════════════════════════════════════════ END: pagination.helper.js

src/helper/parseListItem.helper.js

@@ -0,0 +1,111 @@
+/*
+ * ======= • ======= • ======= • ======= • =======• =======
+ * AniKotoAPI — parseListItem.helper.js
+ * Repository: https://github.com/Shineii86/AniKotoAPI
+ *
+ * @description
+ *   Shared helper for parsing anime list items from Cheerio DOM.
+ *   Eliminates code duplication across multiple extractors by
+ *   providing a unified parsing function for standard list items.
+ *
+ * @exports
+ *   parseListItems, parseListItem
+ *
+ * @author  Shinei Nouzen
+ * @license MIT
+ * ======= • ======= • ======= • ======= • =======• =======
+ */
+
+// ══════════════════════════════════════════════════════════════
+// SINGLE ITEM PARSER
+// ══════════════════════════════════════════════════════════════
+
+// ---- FEATURE: Parse a single anime list item from a Cheerio element ----
+/**
+ * Parses a single anime list item from a Cheerio element.
+ * Handles multiple CSS selector patterns for different page layouts
+ * by falling through comma-separated selectors until one matches.
+ *
+ * @param {CheerioAPI} $ - Cheerio instance with loaded HTML
+ * @param {CheerioElement} el - DOM element to parse
+ * @param {object} [options] - Parsing options
+ * @param {boolean} [options.includeAnimeId=false] - Include animeId field from data-tip attribute
+ * @param {boolean} [options.includeRating=true] - Include rating field from .rated span
+ * @returns {object|null} Parsed anime object or null if slug is missing (invalid item)
+ *
+ * @example
+ *   const item = parseListItem($, el, { includeAnimeId: true });
+ *   if (item) results.push(item);
+ */
+const parseListItem = ($, el, options = {}) => {
+  const { includeAnimeId = false, includeRating = true } = options;
+
+  // NOTE: slug is the primary key — skip items without a valid watch link
+  // NOTE: item may BE the <a> tag itself, so check both self and children
+  let slug = "";
+  if ($(el).is("a")) {
+    slug = $(el).attr("href")?.split("/watch/").pop() || "";
+  }
+  if (!slug) {
+    slug = $(el).find("a").attr("href")?.split("/watch/").pop() || "";
+  }
+  if (!slug) return null;
+
+  // NOTE: Multiple selectors handle different page layouts (#list-items vs .film_list-wrap vs .item)
+  const poster = $(el).find("img").attr("src") || "";
+  const title = $(el).find(".name").text().trim() || $(el).children(".info").find(".name").text().trim() || "";
+  const japaneseTitle = $(el).find(".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(".meta .dot:last-child, .fdi-item:nth-child(2)").text().trim() || "";
+
+  const item = { slug, poster, title, japaneseTitle, sub, dub, total, type };
+
+  // NOTE: animeId comes from data-tip on .ani.poster.tip — only present on some page layouts
+  if (includeAnimeId) {
+    item.animeId = $(el).find(".ani.poster.tip").attr("data-tip") || "";
+  }
+
+  // NOTE: Rating uses different selectors depending on whether it's a list page or detail page
+  if (includeRating) {
+    item.rating = $(el).find(".rated span, .rating, .fdi-item:nth-child(3)").text().trim() || "";
+  }
+
+  return item;
+};
+
+// ══════════════════════════════════════════════════════════════
+// MULTI-ITEM PARSER
+// ══════════════════════════════════════════════════════════════
+
+// ---- FEATURE: Parse multiple anime list items from a Cheerio instance ----
+/**
+ * Parses multiple anime list items from a Cheerio instance.
+ * Uses multiple CSS selectors to handle different page layouts,
+ * returning only items with valid slugs.
+ *
+ * @param {CheerioAPI} $ - Cheerio instance with loaded HTML
+ * @param {string} [selector] - CSS selector for list items (default: auto-detect all layouts)
+ * @param {object} [options] - Parsing options (passed to parseListItem)
+ * @returns {Array<object>} Array of parsed anime objects (empty if none found)
+ *
+ * @example
+ *   const $ = await extractPages("/most-popular");
+ *   const items = parseListItems($);
+ *   console.log(items.length); // Number of parsed items
+ */
+const parseListItems = ($, selector = "#list-items > .item, .film_list-wrap .flw-item, .film-detail, .item", options = {}) => {
+  const results = [];
+
+  $(selector).each((i, el) => {
+    const item = parseListItem($, el, options);
+    if (item) results.push(item);
+  });
+
+  return results;
+};
+
+export { parseListItems, parseListItem };
+
+// ══════════════════════════════════════════════════════════════ END: parseListItem.helper.js

src/middleware/creatorInfo.js

@@ -0,0 +1,75 @@
+/*
+ * ======= • ======= • ======= • ======= • =======• =======
+ * AniKotoAPI — creatorInfo.js
+ * Repository: https://github.com/Shineii86/AniKotoAPI
+ *
+ * @description
+ *   Express middleware that injects creator attribution metadata
+ *   into every JSON API response. Overrides res.json() to append
+ *   author details and a server-side timestamp, unless the
+ *   response already contains creator information.
+ *
+ * @exports
+ *   addCreatorInfo — Express middleware function
+ *   creatorInfo    — Static creator metadata object
+ *
+ * @author  Shinei Nouzen
+ * @license MIT
+ * ======= • ======= • ======= • ======= • =======• =======
+ */
+
+// ══════════════════════════════════════════════════════════════
+// CREATOR METADATA
+// ══════════════════════════════════════════════════════════════
+
+// NOTE: Injected into every response unless `data.creator` already exists
+const creatorInfo = {
+  creator: "Shinei Nouzen",
+  github: "https://github.com/Shineii86",
+  telegram: "https://telegram.me/Shineii86",
+  message: "Built with ❤️ by Shinei Nouzen",
+};
+
+// ══════════════════════════════════════════════════════════════
+// MIDDLEWARE
+// ══════════════════════════════════════════════════════════════
+
+/**
+ * Express middleware that enriches every JSON response with
+ * creator attribution and an IN-formatted timestamp.
+ *
+ * @param {import('express').Request}  req  - Express request object
+ * @param {import('express').Response} res  - Express response object
+ * @param {import('express').NextFunction} next - Passes control forward
+ * @returns {void}
+ *
+ * @example
+ *   app.use(addCreatorInfo);
+ *   res.json({ anime: [...] });
+ *   // Response includes creator, github, telegram, message, and timestamp
+ */
+const addCreatorInfo = (req, res, next) => {
+  // NOTE: Preserve the original json method so we can wrap it
+  const originalJson = res.json.bind(res);
+
+  // NOTE: Monkey-patch res.json to inject creator info
+  res.json = (data) => {
+    // NOTE: Only inject if data is a plain object and missing creator field
+    if (typeof data === "object" && data !== null && !data.creator) {
+      data = {
+        ...data,
+        creator: creatorInfo.creator,
+        github: creatorInfo.github,
+        telegram: creatorInfo.telegram,
+        message: creatorInfo.message,
+        timestamp: new Date().toLocaleString("en-IN", { timeZone: "Asia/Kolkata", hour12: true }),
+      };
+    }
+    return originalJson(data);
+  };
+
+  next();
+};
+
+export { addCreatorInfo, creatorInfo };
+// ══════════════════════════════════════════════════════════════ END: creatorInfo.js

src/routes/apiRoutes.js

@@ -1,8 +1,5 @@
 /*
  * ======= • ======= • ======= • ======= • =======• =======
-import { createRequire } from "module";
-const require = createRequire(import.meta.url);
-const { version } = require("../package.json");
  * AniKotoAPI — apiRoutes.js
  * Repository: https://github.com/Shineii86/AniKotoAPI
  *
@@ -18,6 +15,10 @@ const { version } = require("../package.json");
  * @license MIT
  * ======= • ======= • ======= • ======= • =======• =======
  */
+import { createRequire } from "module";
+const require = createRequire(import.meta.url);
+const { version } = require("../../package.json");
+
 
 import { getHomeInfo } from "../controllers/homeInfo.controller.js";
 import { getAnimeInfo } from "../controllers/animeInfo.controller.js";
@@ -25,6 +26,7 @@ import { getSearchResults, getSearchSuggestions } from "../controllers/search.co
 import { getEpisodeList } from "../controllers/episodeList.controller.js";
 import { getEpisodeListAjax } from "../controllers/episodeListAjax.controller.js";
 import { getStreamInfo, getServerList, getMapperServers } from "../controllers/streamInfo.controller.js";
+import { getResolvedStream, getStreamQualities } from "../controllers/streamResolver.controller.js";
 import { getSchedule } from "../controllers/schedule.controller.js";
 import { getSpotlight } from "../controllers/spotlight.controller.js";
 import { getTrending } from "../controllers/trending.controller.js";
@@ -35,12 +37,19 @@ import { getPopular } from "../controllers/popular.controller.js";
 import { getFilter } from "../controllers/filter.controller.js";
 import { getWatchPage } from "../controllers/watchPage.controller.js";
 import { getAzList } from "../controllers/azList.controller.js";
-import { getNewRelease, getNewlyAdded } from "../controllers/newRelease.controller.js";
+import { getNewRelease, getNewlyAdded, getLatestUpdated } from "../controllers/newRelease.controller.js";
 import { getStatus } from "../controllers/status.controller.js";
 import { getTrendingSidebar } from "../controllers/trendingSidebar.controller.js";
 import { getSeasons } from "../controllers/seasons.controller.js";
 import { getWatchOrder } from "../controllers/watchOrder.controller.js";
+import { getDownloadLinks } from "../controllers/download.controller.js";
+import { getUpcomingAnime } from "../controllers/upcomingAnime.controller.js";
+import { getTopAnimeRankings } from "../controllers/topAnimeRankings.controller.js";
+import { getRecentlyUpdatedTabs } from "../controllers/recentlyUpdatedTabs.controller.js";
+import { getCompletedAnime } from "../controllers/completedAnime.controller.js";
 import { categoryRoutes } from "./category.route.js";
+import { getMirrorStatus, resetMirrorCache } from "../helper/mirror.helper.js";
+import { getCacheStats } from "../helper/cache.helper.js";
 
 // ══════════════════════════════════════════════════════════════
 // ROUTE REGISTRATION
@@ -192,6 +201,115 @@ app.use((req, res, next) => {
     }
   });
 
+  // ---- FEATURE: Download links for episode ----
+  app.get("/api/download", async (req, res, next) => {
+    try {
+      await getDownloadLinks(req, res, next);
+    } catch (error) {
+      jsonError(res, error.message);
+    }
+  });
+
+  // ---- FEATURE: Resolve actual stream URL (m3u8/mp4) from link ID ----
+  app.get("/api/stream/resolve", async (req, res, next) => {
+    try {
+      await getResolvedStream(req, res, next);
+    } catch (error) {
+      jsonError(res, error.message);
+    }
+  });
+
+  // ---- FEATURE: Available quality options for a stream URL ----
+  app.get("/api/stream/qualities", async (req, res, next) => {
+    try {
+      await getStreamQualities(req, res, next);
+    } catch (error) {
+      jsonError(res, error.message);
+    }
+  });
+
+  // ---- FEATURE: M3U8 proxy — fetch and serve M3U8 playlists through API ----
+  app.get("/api/stream/proxy", async (req, res, next) => {
+    try {
+      const { url } = req.query;
+      if (!url) {
+        return res.status(400).json({ success: false, message: "M3U8 URL is required" });
+      }
+      // NOTE: Validate URL is from known streaming domains
+      const allowedDomains = ["vidtube.site", "vidplay.site", "megaplay.buzz", "megaplay-1.buzz", "cdn.anipixcdn.co"];
+      const urlObj = new URL(url);
+      const isAllowed = allowedDomains.some(d => urlObj.hostname.includes(d)) || urlObj.hostname.endsWith(".m3u8");
+
+      if (!isAllowed) {
+        return res.status(403).json({ success: false, message: "Domain not allowed for proxy" });
+      }
+
+      const axios = (await import("axios")).default;
+      const { headers: defaultHeaders } = await import("../configs/header.config.js");
+
+      const response = await axios.get(url, {
+        headers: {
+          ...defaultHeaders,
+          "Referer": "https://anikototv.to/",
+          "Origin": "https://anikototv.to",
+        },
+        timeout: 15000,
+        responseType: "text",
+      });
+
+      // NOTE: Rewrite relative URLs in M3U8 to proxy URLs
+      let content = typeof response.data === "string" ? response.data : String(response.data);
+      const baseUrl = url.substring(0, url.lastIndexOf("/") + 1);
+
+      content = content.replace(/(^(?!#).+\.m3u8.*$)/gm, (match) => {
+        const absoluteUrl = match.startsWith("http") ? match : new URL(match, baseUrl).href;
+        return `/api/stream/proxy?url=${encodeURIComponent(absoluteUrl)}`;
+      });
+
+      content = content.replace(/(^(?!#).+\.ts.*$)/gm, (match) => {
+        const absoluteUrl = match.startsWith("http") ? match : new URL(match, baseUrl).href;
+        return `/api/stream/ts-proxy?url=${encodeURIComponent(absoluteUrl)}`;
+      });
+
+      res.setHeader("Content-Type", "application/vnd.apple.mpegurl");
+      res.setHeader("Access-Control-Allow-Origin", "*");
+      res.setHeader("Cache-Control", "public, max-age=30");
+      res.send(content);
+    } catch (error) {
+      jsonError(res, error.message);
+    }
+  });
+
+  // ---- FEATURE: TS segment proxy for video segments ----
+  app.get("/api/stream/ts-proxy", async (req, res, next) => {
+    try {
+      const { url } = req.query;
+      if (!url) {
+        return res.status(400).json({ success: false, message: "TS URL is required" });
+      }
+
+      const axios = (await import("axios")).default;
+      const { headers: defaultHeaders } = await import("../configs/header.config.js");
+
+      const response = await axios.get(url, {
+        headers: {
+          ...defaultHeaders,
+          "Referer": "https://anikototv.to/",
+          "Origin": "https://anikototv.to",
+        },
+        timeout: 30000,
+        responseType: "arraybuffer",
+      });
+
+      res.setHeader("Content-Type", "video/mp2t");
+      res.setHeader("Access-Control-Allow-Origin", "*");
+      res.setHeader("Cache-Control", "public, max-age=3600");
+      res.send(Buffer.from(response.data));
+    } catch (error) {
+      jsonError(res, error.message);
+    }
+  });
+
   // ══════════════════════════════════════════════════════════════
   // SCHEDULE
   // ══════════════════════════════════════════════════════════════
@@ -294,6 +412,15 @@ app.use((req, res, next) => {
     }
   });
 
+  // ---- FEATURE: Recently updated anime (sorted by update time) ----
+  app.get("/api/latest-updated", async (req, res, next) => {
+    try {
+      await getLatestUpdated(req, res, next);
+    } catch (error) {
+      jsonError(res, error.message);
+    }
+  });
+
   // ══════════════════════════════════════════════════════════════
   // SIDEBAR
   // ══════════════════════════════════════════════════════════════
@@ -307,6 +434,58 @@ app.use((req, res, next) => {
     }
   });
 
+  // ══════════════════════════════════════════════════════════════
+  // UPCOMING ANIME
+  // ══════════════════════════════════════════════════════════════
+
+  // ---- FEATURE: Upcoming anime releases ----
+  app.get("/api/upcoming", async (req, res, next) => {
+    try {
+      await getUpcomingAnime(req, res, next);
+    } catch (error) {
+      jsonError(res, error.message);
+    }
+  });
+
+  // ══════════════════════════════════════════════════════════════
+  // TOP ANIME RANKINGS
+  // ══════════════════════════════════════════════════════════════
+
+  // ---- FEATURE: Top anime rankings with sort (top/newest) ----
+  app.get("/api/top-rankings", async (req, res, next) => {
+    try {
+      await getTopAnimeRankings(req, res, next);
+    } catch (error) {
+      jsonError(res, error.message);
+    }
+  });
+
+  // ══════════════════════════════════════════════════════════════
+  // RECENTLY UPDATED (TAB FILTERED)
+  // ══════════════════════════════════════════════════════════════
+
+  // ---- FEATURE: Recently updated anime with tab filter (all/dub/sub) ----
+  app.get("/api/recently-updated", async (req, res, next) => {
+    try {
+      await getRecentlyUpdatedTabs(req, res, next);
+    } catch (error) {
+      jsonError(res, error.message);
+    }
+  });
+
+  // ══════════════════════════════════════════════════════════════
+  // COMPLETED ANIME
+  // ══════════════════════════════════════════════════════════════
+
+  // ---- FEATURE: Completed anime series ----
+  app.get("/api/completed", async (req, res, next) => {
+    try {
+      await getCompletedAnime(req, res, next);
+    } catch (error) {
+      jsonError(res, error.message);
+    }
+  });
+
   // ══════════════════════════════════════════════════════════════
   // SEASONS & WATCH ORDER
   // ══════════════════════════════════════════════════════════════
@@ -397,12 +576,34 @@ app.get("/api/stats", (req, res) => {
         ttl: "5 minutes",
         description: "Map-based cache with TTL expiration",
       },
-      endpoints: 30,
+      endpoints: 38,
       timestamp: new Date().toISOString(),
     },
   });
 });
 
+// ---- FEATURE: Mirror status and health check ----
+app.get("/api/mirrors", async (req, res) => {
+  try {
+    const status = await getMirrorStatus();
+    res.json({ success: true, results: status });
+  } catch (error) {
+    jsonError(res, error.message);
+  }
+});
+
+// ---- FEATURE: Cache statistics ----
+app.get("/api/cache/stats", (req, res) => {
+  const stats = getCacheStats();
+  res.json({ success: true, results: stats });
+});
+
+// ---- FEATURE: Reset mirror cache ----
+app.post("/api/mirrors/reset", (req, res) => {
+  resetMirrorCache();
+  res.json({ success: true, message: "Mirror cache reset" });
+});
+
 // ---- FEATURE: OpenAPI specification ----
 app.get("/api/openapi", (req, res) => {
   res.json({
@@ -426,6 +627,7 @@ app.get("/api/openapi", (req, res) => {
       "/episodes/{id}": { get: { summary: "Episode list", tags: ["Episodes"] } },
       "/servers": { get: { summary: "Server list", tags: ["Streaming"] } },
       "/stream": { get: { summary: "Stream URL", tags: ["Streaming"] } },
+      "/download": { get: { summary: "Download links", tags: ["Streaming"] } },
       "/schedule": { get: { summary: "Anime schedule", tags: ["Schedule"] } },
       "/random": { get: { summary: "Random anime", tags: ["Discovery"] } },
       "/top-ten": { get: { summary: "Top 10 rankings", tags: ["Rankings"] } },
@@ -439,17 +641,28 @@ app.get("/api/openapi", (req, res) => {
       "/status/{name}": { get: { summary: "By status", tags: ["Categories"] } },
       "/health": { get: { summary: "Health check", tags: ["System"] } },
       "/stats": { get: { summary: "API statistics", tags: ["System"] } },
+      "/mirrors": { get: { summary: "Mirror status", tags: ["System"] } },
+      "/mirrors/reset": { post: { summary: "Reset mirror cache", tags: ["System"] } },
       "/openapi": { get: { summary: "OpenAPI spec", tags: ["System"] } },
       "/watch": { get: { summary: "Watch page data", tags: ["Streaming"] } },
+      "/stream/resolve": { get: { summary: "Resolve actual stream URL (m3u8/mp4)", tags: ["Streaming"] } },
+      "/stream/qualities": { get: { summary: "Available quality options for M3U8 stream", tags: ["Streaming"] } },
+      "/stream/proxy": { get: { summary: "M3U8 playlist proxy (rewrites URLs)", tags: ["Streaming"] } },
+      "/stream/ts-proxy": { get: { summary: "TS video segment proxy", tags: ["Streaming"] } },
       "/search/suggest": { get: { summary: "Search suggestions", tags: ["Search"] } },
       "/episodes-ajax/{id}": { get: { summary: "AJAX episode list", tags: ["Episodes"] } },
       "/mapper-servers": { get: { summary: "Mapper servers", tags: ["Streaming"] } },
       "/newly-added": { get: { summary: "Newly added", tags: ["Releases"] } },
+      "/latest-updated": { get: { summary: "Recently updated", tags: ["Releases"] } },
       "/trending-sidebar": { get: { summary: "Trending sidebar", tags: ["Discovery"] } },
       "/seasons/{id}": { get: { summary: "Season data", tags: ["Anime"] } },
       "/watch-order/{id}": { get: { summary: "Watch order", tags: ["Anime"] } },
       "/az-list/{letter}": { get: { summary: "A-Z listing", tags: ["Discovery"] } },
       "/suggestions": { get: { summary: "Anime suggestions", tags: ["Search"] } },
+      "/upcoming": { get: { summary: "Upcoming anime", tags: ["Discovery"] } },
+      "/top-rankings": { get: { summary: "Top anime rankings (top/newest)", tags: ["Rankings"] } },
+      "/recently-updated": { get: { summary: "Recently updated (all/dub/sub tabs)", tags: ["Releases"] } },
+      "/completed": { get: { summary: "Completed anime series", tags: ["Rankings"] } },
     },
     tags: [
       { name: "Home", description: "Homepage data" },

test.js

@@ -4,8 +4,9 @@
  * Repository: https://github.com/Shineii86/AniKotoAPI
  *
  * @description
- *   Integration test suite for AniKotoAPI endpoints.
+ *   Comprehensive integration test suite for AniKotoAPI endpoints.
- *   Tests all major endpoints for correct response format.
+ *   Tests all major endpoints for correct response format, status codes,
+ *   error handling, and performance benchmarks.
  *
  * @author  Shinei Nouzen
  * @license MIT
@@ -15,85 +16,165 @@
 const BASE = process.env.API_URL || "https://anikototvapi.vercel.app/api";
 
 const tests = [
-  { name: "Home", url: "/" },
+  // Core endpoints
-  { name: "Search", url: "/search?keyword=naruto" },
+  { name: "Home", url: "/", check: (d) => d.results?.spotlights || d.results?.trending },
-  { name: "Info", url: "/info?id=road-of-naruto-ggjw8" },
+  { name: "Search", url: "/search?keyword=naruto", check: (d) => d.results?.data },
-  { name: "Episodes", url: "/episodes/road-of-naruto-ggjw8" },
+  { name: "Info", url: "/info?id=one-piece-odmau", check: (d) => d.results?.title },
-  { name: "Suggestions", url: "/suggestions?keyword=naruto" },
+  { name: "Episodes", url: "/episodes/one-piece-odmau", check: (d) => d.results?.episodes },
-  { name: "Spotlight", url: "/spotlight" },
+  { name: "Servers", url: "/servers?ids=1", check: (d) => d.results },
-  { name: "Trending", url: "/trending" },
+  // Streaming
-  { name: "Top 10", url: "/top-ten" },
+  { name: "Stream", url: "/watch?slug=one-piece-odmau&ep=1", check: (d) => d.results?.servers || d.results?.episodeNumber },
-  { name: "Random", url: "/random" },
+  { name: "Stream Resolve", url: "/stream/resolve?id=MTF1dkFtaW9BRTZPbzJJRElFZUZrNHVJWFRVWWRWdU5JYnhuaU95bVRYSzk1Z0lVVjJha2FnSE95U3F4M1RsaXNCSnlnd05rTTlBUldTZGZxZjQzajVxcXVDRVY5bjBocnRCV2tkNnNzaXFnc3c5M1JJWjRnNmt5bDNPdm1TczlvVXdwWGplKzFmQmZJMlp0OTBNTXd3PT0&slug=one-piece-odmau", check: (d) => d.results?.url, optional: true },
-  { name: "Most Popular", url: "/most-popular" },
+
-  { name: "New Release", url: "/new-release" },
+  // Discovery endpoints
-  { name: "Schedule", url: "/schedule" },
+  { name: "Suggestions", url: "/suggestions?keyword=naruto", check: (d) => d.results },
-  { name: "Genre", url: "/genre/action" },
+  { name: "Spotlight", url: "/spotlight", check: (d) => d.results },
-  { name: "Type", url: "/type/tv" },
+  { name: "Trending", url: "/trending", check: (d) => d.results },
-  { name: "Status", url: "/status/airing" },
+  { name: "Top 10", url: "/top-ten", check: (d) => d.results },
-  { name: "Health", url: "/health" },
+  { name: "Random", url: "/random", check: (d) => d.results },
-  { name: "Stats", url: "/stats" },
+  { name: "Most Popular", url: "/most-popular", check: (d) => d.results },
-  { name: "OpenAPI", url: "/openapi" },
+  { name: "Upcoming", url: "/upcoming", check: (d) => Array.isArray(d.results) },
-  { name: "Watch", url: "/watch?slug=road-of-naruto-ggjw8&ep=1" },
+  { name: "Top Rankings", url: "/top-rankings", check: (d) => Array.isArray(d.results) },
-  { name: "Search Suggest", url: "/search/suggest?keyword=naruto" },
+  { name: "Recently Updated", url: "/recently-updated", check: (d) => Array.isArray(d.results) },
-  { name: "Episodes Ajax", url: "/episodes-ajax/road-of-naruto-ggjw8" },
+  { name: "Completed", url: "/completed", check: (d) => Array.isArray(d.results) },
-  { name: "Newly Added", url: "/newly-added" },
+
-  { name: "Trending Sidebar", url: "/trending-sidebar" },
+  // Release lists
-  { name: "Seasons", url: "/seasons/road-of-naruto-ggjw8" },
+  { name: "New Release", url: "/new-release", check: (d) => d.results },
-  { name: "Watch Order", url: "/watch-order/road-of-naruto-ggjw8" },
+  { name: "Newly Added", url: "/newly-added", check: (d) => d.results },
-  { name: "AZ List", url: "/az-list/a" },
+  { name: "Latest Updated", url: "/latest-updated", check: (d) => d.results },
-  { name: "Filter", url: "/filter?keyword=&genre[]=1" },
+
-  { name: "Episodes By ID", url: "/episodes/1" },
+  // Category endpoints
-  { name: "Servers", url: "/servers?ids=1" },
+  { name: "Genre", url: "/genre/action", check: (d) => d.results },
-  { name: "Mapper Servers", url: "/mapper-servers?malId=21&slug=one-piece-100&timestamp=1234567890" },
+  { name: "Type", url: "/type/tv", check: (d) => d.results },
+  { name: "Status", url: "/status/airing", check: (d) => d.results },
+  { name: "AZ List", url: "/az-list/a", check: (d) => d.results },
+  { name: "Filter", url: "/filter?keyword=naruto", check: (d) => d.results },
+
+  // Search variants
+  { name: "Search Suggest", url: "/search/suggest?keyword=naruto", check: (d) => d.results },
+  { name: "Episodes Ajax", url: "/episodes-ajax/one-piece-odmau", check: (d) => d.results },
+  { name: "Trending Sidebar", url: "/trending-sidebar", check: (d) => d.results },
+
+  // Anime detail
+  { name: "Seasons", url: "/seasons/one-piece-odmau", check: (d) => d.results?.seasons || d.results?.totalSeasons, optional: true },
+  { name: "Watch Order", url: "/watch-order/one-piece-odmau", check: (d) => d.results?.related || d.results?.totalRelated, optional: true },
+  { name: "Download", url: "/download?slug=one-piece-odmau&ep=1", check: (d) => d.results, optional: true },
+
+  // Utility endpoints
+  { name: "Health", url: "/health", check: (d) => d.results?.status === "healthy" },
+  { name: "Stats", url: "/stats", check: (d) => d.results?.endpoints },
+  { name: "Cache Stats", url: "/cache/stats", check: (d) => d.results?.hits !== undefined },
+  { name: "Mirrors", url: "/mirrors", check: (d) => Array.isArray(d.results) },
+  { name: "OpenAPI", url: "/openapi", check: (d) => d.openapi === "3.0.3" },
 ];
 
 let passed = 0;
 let failed = 0;
+let skipped = 0;
+let total = 0;
+const results = [];
 
 async function runTest(test) {
+  total++;
+  const start = Date.now();
+  
   try {
     const res = await fetch(`${BASE}${test.url}`);
+    const duration = Date.now() - start;
+    
     if (!res.ok) {
-      console.log(`❌ ${test.name} - HTTP ${res.status}`);
+      if (test.optional && (res.status === 404 || res.status === 500)) {
+        console.log(`⏭️  ${test.name} - Skipped (HTTP ${res.status}) (${duration}ms)`);
+        skipped++;
+        results.push({ name: test.name, status: "SKIP", httpStatus: res.status, duration });
+        return;
+      }
+      console.log(`❌ ${test.name} - HTTP ${res.status} (${duration}ms)`);
       failed++;
+      results.push({ name: test.name, status: "FAIL", httpStatus: res.status, duration });
       return;
     }
-    const data = await res.json();
+    
-    if (data.success === true && data.results) {
-      console.log(`✅ ${test.name}`);
-      passed++;
-    } else {
-      console.log(`❌ ${test.name} - Invalid response format`);
-      failed++;
-    }
-  } catch (error) {
-    console.log(`❌ ${test.name} - ${error.message}`);
-    failed++;
-  }
-}
     const data = await res.json();
     
-    if (data.success === true && data.results) {
+    if (!data.success) {
-      console.log(`✅ ${test.name}`);
+      if (test.optional) {
-      passed++;
+        console.log(`⏭️  ${test.name} - Skipped (success=false) (${duration}ms)`);
-    } else {
+        skipped++;
-      console.log(`❌ ${test.name} - Invalid response format`);
+        results.push({ name: test.name, status: "SKIP", reason: "success=false", duration });
+        return;
+      }
+      console.log(`❌ ${test.name} - success=false (${duration}ms)`);
       failed++;
+      results.push({ name: test.name, status: "FAIL", reason: "success=false", duration });
+      return;
     }
+    
+    // Check custom validation
+    if (test.check && !test.check(data)) {
+      if (test.optional) {
+        console.log(`⏭️  ${test.name} - Skipped (validation failed) (${duration}ms)`);
+        skipped++;
+        results.push({ name: test.name, status: "SKIP", reason: "Validation failed", duration });
+        return;
+      }
+      console.log(`❌ ${test.name} - Validation failed (${duration}ms)`);
+      failed++;
+      results.push({ name: test.name, status: "FAIL", reason: "Validation failed", duration });
+      return;
+    }
+    
+    console.log(`✅ ${test.name} (${duration}ms)`);
+    passed++;
+    results.push({ name: test.name, status: "PASS", duration });
+    
   } catch (error) {
-    console.log(`❌ ${test.name} - ${error.message}`);
+    const duration = Date.now() - start;
+    if (test.optional) {
+      console.log(`⏭️  ${test.name} - Skipped (${error.message}) (${duration}ms)`);
+      skipped++;
+      results.push({ name: test.name, status: "SKIP", reason: error.message, duration });
+      return;
+    }
+    console.log(`❌ ${test.name} - ${error.message} (${duration}ms)`);
     failed++;
+    results.push({ name: test.name, status: "FAIL", reason: error.message, duration });
   }
 }
 
 async function runAll() {
   console.log(`\n🧪 Running ${tests.length} tests...\n`);
+  console.log(`📡 API: ${BASE}\n`);
   
+  // Run tests sequentially to avoid rate limiting
   for (const test of tests) {
     await runTest(test);
   }
   
-  console.log(`\n📊 Results: ${passed} passed, ${failed} failed, ${tests.length} total\n`);
+  console.log(`\n${"=".repeat(50)}`);
+  console.log(`📊 Results: ${passed} passed, ${failed} failed, ${skipped} skipped, ${total} total`);
+  console.log(`${"=".repeat(50)}`);
+  
+  // Performance summary
+  const durations = results.filter(r => r.status === "PASS").map(r => r.duration);
+  if (durations.length > 0) {
+    const avgDuration = durations.reduce((a, b) => a + b, 0) / durations.length;
+    const maxDuration = Math.max(...durations);
+    const minDuration = Math.min(...durations);
+    
+    console.log(`\n⚡ Performance:`);
+    console.log(`   Average: ${avgDuration.toFixed(0)}ms`);
+    console.log(`   Min: ${minDuration}ms`);
+    console.log(`   Max: ${maxDuration}ms`);
+  }
+  
+  // Detailed results
+  console.log(`\n📋 Detailed Results:`);
+  results.forEach(r => {
+    const icon = r.status === "PASS" ? "✅" : r.status === "SKIP" ? "⏭️" : "❌";
+    console.log(`   ${icon} ${r.name} - ${r.status} (${r.duration}ms)${r.reason ? ` - ${r.reason}` : ""}`);
+  });
+  
   process.exit(failed > 0 ? 1 : 0);
 }