v2.3.0: Update docs with streaming status, bump version, add solutions

CHANGELOG.md

@@ -5,6 +5,24 @@ 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.3.0] - 2026-08-14
+
+### Added
+- **Streaming Status Warning**: Added ⚠️ Streaming Status section to README documenting which endpoints work vs which are blocked by upstream anti-bot protection
+- **Streaming Fix Solutions**: Added SCRAPER_API_KEY and FLARESOLVERR_URL environment variable solutions to README for bypassing Cloudflare bot protection
+- **Upstream Error Detection**: Added detection of upstream API error responses (`status >= 400`) in `streamInfo.extractor.js` — returns HTTP 502 with descriptive error instead of silently returning null URL
+- **Cookie-Aware Session Establishment**: Added session cookie fetching in `extractStreamInfo` and `extractServerList` — fetches watch/home page to capture `set-cookie` headers before AJAX requests
+- **Optional Slug Parameter**: `getStreamInfo` controller now accepts optional `?slug=` query parameter for session establishment
+
+### Changed
+- **Version**: Bumped to 2.3.0
+- **README**: Updated version badge from 2.2.1 to 2.3.0
+- **README**: Added streaming status warning with solutions table
+- **Docs**: Updated index.md, endpoints.md, streaming.md with streaming status warnings and v2.3.0 references
+
+### Fixed
+- **CRITICAL**: Fixed `/api/stream` returning `null` URL — upstream AJAX endpoints (`/ajax/server?get=`, `/ajax/server/list?servers=`) require session cookies; now properly detects upstream 500 errors and returns HTTP 502 with error message
+
 ## [2.2.2] - 2026-08-14
 
 ### Fixed

README.md

@@ -22,7 +22,7 @@
   <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-2.2.1-f43f8e?style=flat-square&logoColor=white" alt="Version"/>
+  <img src="https://img.shields.io/badge/Version-2.3.0-f43f8e?style=flat-square&logoColor=white" alt="Version"/>
   <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>

docs/architecture.md

@@ -1,8 +1,8 @@
 /**
  * ============================================================================
  *  AniKotoAPI — Architecture Document
- *  Version : 2.2.1
+ *  Version : 2.3.0
- *  Generated: 2026-07-30
+ *  Generated: 2026-08-14
  * ============================================================================
  *
  *  Free REST API for scraping anime data from anikototv.to
@@ -832,7 +832,7 @@
  *  │  VERSION HISTORY                                                     │
  *  ├──────────────────────────────────────────────────────────────────────┤
  *  │                                                                      │
- *  │  v2.2.1  (Current)                                                  │
+ *  │  v2.3.0  (Current)                                                  │
  *  │    • 28 endpoints, 28 extractors                                    │
  *  │    • LRU cache with per-endpoint TTL                                │
  *  │    • 5-mirror failover system                                       │

docs/endpoints.md

@@ -4,6 +4,31 @@ Base URL: `https://anikototvapi.vercel.app/api`
 
 ---
 
+## ⚠️ Streaming Status
+
+> **Streaming endpoints (`/api/servers`, `/api/stream`, `/api/stream/resolve`) return errors when anikototv.to blocks AJAX requests from server-side IPs.**
+
+| What Works | What's Blocked |
+|:---|:---|
+| Home, spotlight, trending | `/api/servers` — server list |
+| Search, suggestions, filter | `/api/stream` — embed URLs |
+| Info, episodes, schedule | `/api/stream/resolve` — m3u8/mp4 |
+| Top 10, most popular, new release | `/api/mapper-servers` — gogoanime servers |
+| AZ list, random, genre list | All AJAX-dependent endpoints |
+| All HTML-scraped endpoints | |
+
+**To fix streaming**, set one of these environment variables:
+
+```bash
+# Option 1: ScraperAPI (requires premium plan — $49/month)
+SCRAPER_API_KEY=your_scraperapi_key
+
+# Option 2: FlareSolverr (self-hosted, unlimited)
+FLARESOLVERR_URL=http://your-flaresolverr-host:8191
+```
+
+---
+
 ## Pagination
 
 Most list endpoints return a `totalPages` field for pagination:
@@ -859,7 +884,7 @@ curl "https://anikototvapi.vercel.app/api/health"
   "success": true,
   "results": {
     "status": "healthy",
-    "version": "2.2.1",
+    "version": "2.3.0",
     "uptime": "0h 1m 21s",
     "uptimeSeconds": 81,
     "timestamp": "2026-07-30T02:20:46.153Z",

docs/examples.md

@@ -26,7 +26,7 @@ curl -s "https://anikototvapi.vercel.app/api/health" | python3 -m json.tool
   "success": true,
   "results": {
     "status": "healthy",
-    "version": "2.2.1",
+    "version": "2.3.0",
     "uptime": "0h 1m 21s",
     "uptimeSeconds": 81,
     "timestamp": "2026-07-30T02:20:46.153Z",
@@ -2036,7 +2036,7 @@ curl -s "https://anikototvapi.vercel.app/api/health" | python3 -m json.tool
   "success": true,
   "results": {
     "status": "healthy",
-    "version": "2.2.1",
+    "version": "2.3.0",
     "uptime": "0h 1m 21s",
     "uptimeSeconds": 81,
     "timestamp": "2026-07-30T02:20:46.153Z",

docs/index.md

@@ -1,11 +1,11 @@
 # // === HEADER ===
-# AniKotoAPI v2.2.1
+# AniKotoAPI v2.3.0
 # Free REST API for Anime Data
 # Scraping anikototv.to with Cheerio
 
 ---
 
-![AniKotoAPI](https://img.shields.io/badge/AniKotoAPI-v2.2.1-blue)
+![AniKotoAPI](https://img.shields.io/badge/AniKotoAPI-v2.3.0-blue)
 ![License](https://img.shields.io/badge/License-MIT-green)
 ![Endpoints](https://img.shields.io/badge/Endpoints-38+-orange)
 ![Node.js](https://img.shields.io/badge/Node.js-18+-brightgreen)
@@ -15,6 +15,31 @@
 
 ---
 
+## // === STREAMING STATUS ===
+
+> **Streaming endpoints (`/api/servers`, `/api/stream`, `/api/stream/resolve`) return errors when anikototv.to blocks AJAX requests from server-side IPs.**
+
+| What Works | What's Blocked |
+|:---|:---|
+| Home, spotlight, trending | `/api/servers` — server list |
+| Search, suggestions, filter | `/api/stream` — embed URLs |
+| Info, episodes, schedule | `/api/stream/resolve` — m3u8/mp4 |
+| Top 10, most popular, new release | `/api/mapper-servers` — gogoanime servers |
+| AZ list, random, genre list | All AJAX-dependent endpoints |
+| All HTML-scraped endpoints | |
+
+**To fix streaming**, set one of these environment variables:
+
+```bash
+# Option 1: ScraperAPI (requires premium plan — $49/month)
+SCRAPER_API_KEY=your_scraperapi_key
+
+# Option 2: FlareSolverr (self-hosted, unlimited)
+FLARESOLVERR_URL=http://your-flaresolverr-host:8191
+```
+
+---
+
 ## // === QUICK START ===
 
 ### Get started in 3 steps:

docs/streaming.md

@@ -12,6 +12,31 @@ This document covers the complete streaming workflow for AniKotoAPI — from sea
 
 ---
 
+## ⚠️ Streaming Status
+
+> **Streaming endpoints (`/api/servers`, `/api/stream`, `/api/stream/resolve`) return errors when anikototv.to blocks AJAX requests from server-side IPs.**
+
+| What Works | What's Blocked |
+|:---|:---|
+| Home, spotlight, trending | `/api/servers` — server list |
+| Search, suggestions, filter | `/api/stream` — embed URLs |
+| Info, episodes, schedule | `/api/stream/resolve` — m3u8/mp4 |
+| Top 10, most popular, new release | `/api/mapper-servers` — gogoanime servers |
+| AZ list, random, genre list | All AJAX-dependent endpoints |
+| All HTML-scraped endpoints | |
+
+**To fix streaming**, set one of these environment variables:
+
+```bash
+# Option 1: ScraperAPI (requires premium plan — $49/month)
+SCRAPER_API_KEY=your_scraperapi_key
+
+# Option 2: FlareSolverr (self-hosted, unlimited)
+FLARESOLVERR_URL=http://your-flaresolverr-host:8191
+```
+
+---
+
 ## Table of Contents
 
 1. [Architecture Overview](#architecture-overview)

package.json

@@ -1,6 +1,6 @@
 {
   "name": "AniKotoAPI",
-  "version": "2.2.1",
+  "version": "2.3.0",
   "description": "A restful API to provide all information about anime from anikototv.to",
   "main": "./server.js",
   "scripts": {