shishantbiswas/AniKotoAPI
1
0
Fork 0
mirror of https://github.com/Shineii86/AniKotoAPI.git synced 2026-10-22 02:45:10 +00:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
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
This commit is contained in:
Shinei Nouzen
2026-07-28 21:01:43 +05:30
parent d391908467
commit fb62184688
9 changed files with 478 additions and 49 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CHANGELOG.md
+15 -1
View File
@@ -10,6 +10,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### 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)
@@ -33,11 +35,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- **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 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
@@ -45,6 +53,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- **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)
README.md
+188 -21
View File
@@ -22,8 +22,8 @@
<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.1.0-f43f8e?style=flat-square&logoColor=white" alt="Version"/>
<img src="https://img.shields.io/badge/Endpoints-33-6366f1?style=flat-square&logoColor=white" alt="Endpoints"/>
<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-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>
@@ -87,7 +87,7 @@
### Why AniKotoAPI?
- 🎬 **33 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
@@ -162,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>
@@ -186,18 +189,20 @@ flowchart TD
| Feature | Description | Status |
|:---|:---|:---:|
| 🎬 33 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 | 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 | ✅ |
---
@@ -233,7 +238,6 @@ flowchart TD
| 🔍 [Cheerio](https://cheerio.js.org/) | HTML parsing & scraping | 1.0 | [Docs](https://cheerio.js.org/docs/) |
| 🌐 [Axios](https://axios-http.com/) | HTTP client for scraping | 1.8 | [Docs](https://axios-http.com/docs/intro) |
| 🔧 [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) |
### 📦 Key Dependencies
@@ -242,7 +246,6 @@ flowchart TD
"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
}
@@ -303,8 +306,8 @@ AniKotoAPI/
│ │
│ ├── 📂 docs/ # 📚 API documentation
│ │ ├── 📄 index.md # Overview, quick start
│ │ ├── 📄 endpoints.md # Full API reference (33 endpoints)
│ │ ├── 📄 streaming.md # Streaming flow guide
│ │ ├── 📄 endpoints.md # Full API reference (38 endpoints)
│ │ ├── 📄 streaming.md # Streaming flow guide + proxy
│ │ ├── 📄 examples.md # Code examples (cURL, JS, Python)
│ │ └── 📄 architecture.md # Project structure, tech stack
│ │
@@ -313,41 +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
│ │ ├── 📄 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 (33 endpoints)
│ ├── 📄 apiRoutes.js # 🌐 Main API routes (38 endpoints)
│ └── 📄 category.route.js # 🏷️ Category routes
│
├── 📄 server.js # 🚀 Express server entry point
@@ -451,6 +460,21 @@ curl "https://anikototvapi.vercel.app/api/servers?ids=dXNCT3hNQzk3THhSTW8ySnM5..
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
Servers have a `type` field — use it to pick sub or dub:
@@ -1977,6 +2001,144 @@ 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
@@ -2025,7 +2187,7 @@ All list endpoints include pagination metadata in the response:
| `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`
**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
@@ -2154,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 |
@@ -2265,21 +2428,25 @@ The API can access 10,000+ anime titles from anikototv.to. The most-popular endp
### ✅ Completed
- [x] 🎬 33 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] 📅 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
---
agents/api-tester.md
+3 -3
View File
@@ -1,18 +1,18 @@
---
name: API Tester
description: API testing specialist for AniKotoAPI — validates all 36 endpoints, streaming flow, mirror fallback, cache behavior, and error handling
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 36 endpoints, the 3-step streaming flow, mirror fallback behavior, LRU cache, rate limiting, and error responses.
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` (36 tests, run with `node test.js`)
- **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
agents/performance-benchmarker.md
+1 -1
View File
@@ -133,7 +133,7 @@ compression({
## What You Do
1. **Benchmark endpoints** — Measure response times for all 36 endpoints
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
agents/technical-writer.md
+2 -2
View File
@@ -24,7 +24,7 @@ AniKotoAPI/
├── CONTRIBUTING.md # Contribution guidelines
├── docs/
│ ├── index.md # Overview, quick start
│ ├── endpoints.md # Full API reference (36 endpoints)
│ ├── 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
@@ -140,7 +140,7 @@ flowchart TD
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 36 endpoints
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
docs/architecture.md
+43 -20
View File
@@ -21,8 +21,8 @@ AniKotoAPI/
│
├── docs/ # API documentation
│ ├── index.md # Overview, quick start, features
│ ├── endpoints.md # Full API reference (33 endpoints)
│ ├── streaming.md # Streaming flow guide (3-step)
│ ├── endpoints.md # Full API reference (38 endpoints)
│ ├── streaming.md # Streaming flow guide + resolver/proxy
│ ├── examples.md # cURL, JavaScript, Python, Node.js
│ └── architecture.md # This file
│
@@ -30,65 +30,76 @@ 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 + OpenAPI spec
│ │ ├── 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 + Latest Updated
│ │ ├── popular.controller.js # Most popular
│ │ ├── category.controller.js # Genre filter
│ │ ├── category.controller.js # Type filter
│ │ ├── category.controller.js # Status filter
│ │ ├── category.controller.js # Genre/Type/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 + Latest Updated
│ │ ├── mostPopular.extractor.js # Most popular
│ │ ├── genre.extractor.js # Genre filter
│ │ ├── type.extractor.js # Type filter
│ │ ├── status.extractor.js # Status filter
│ │ ├── filter.extractor.js # Advanced filter
│ │ ├── filter.extractor.js # Advanced filter (with source/season params)
│ │ ├── suggestion.extractor.js # Suggestions
│ │ ├── seasons.extractor.js # Seasons/OVAs/movies
│ │ ├── watchOrder.extractor.js # Watch order
│ │ ├── seasons.extractor.js # Seasons from watch page sidebar
│ │ ├── watchOrder.extractor.js # Watch order from watch page sidebar
│ │ └── download.extractor.js # Download links
│ │
│ └── helper/
│ ├── cache.helper.js # LRU cache with configurable TTL
│ ├── mirror.helper.js # Multi-mirror fallback (5 domains)
│ ├── 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 (27 tests)
├── test.js # Test suite (38 tests)
├── agents/ # AI agent prompts (6 agents)
└── CHANGELOG.md # Version history
```
@@ -150,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
@@ -229,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
+130
View File
@@ -666,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
+37
View File
@@ -427,3 +427,40 @@ async function getDownloadLinks(slug, episode) {
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/streaming.md
+59 -1
View File
@@ -251,7 +251,65 @@ player.source = {
| "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
---