diff --git a/README.md b/README.md index b74a106..bc0e437 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,15 @@
- +

- Stars - Forks + Stars + Forks Issues - Pull Requests - Last Commit + Pull Requests + Last Commit License

@@ -19,13 +19,13 @@ AniList GraphQL Vercel License - Version - Endpoints + Version + Endpoints Providers

- Free RESTful API for anime streaming data powered by AniList GraphQL and Miruro providers.
+ A complete RESTful API for anime streaming data powered by AniList GraphQL and Miruro providers
Search, browse, filter, watch β€” every endpoint returns fresh data with smart caching.
18 endpoints, 12 streaming providers, M3U8 URLs with subtitles and skip timestamps.

@@ -41,7 +41,7 @@ --- -> ## Disclaimer +> ## ⚠️ Disclaimer > > 1. This `API` does not store any files β€” it only links to media hosted on 3rd party services. > 2. This `API` is explicitly made for **educational purposes only** and not for commercial usage. This repo will not be responsible for any misuse of it. @@ -49,7 +49,7 @@ --- -## Table of Contents +## πŸ“– Table of Contents - [Overview](#-overview) - [Features](#-features) @@ -61,73 +61,81 @@ - [Configuration](#-configuration) - [API Endpoints](#-api-endpoints) - [Streaming Flow](#-streaming-flow) -- [Response Schema](#-response-schema) +- [API Response Schema](#-api-response-schema) - [Deployment](#-deployment) +- [Available Scripts](#-available-scripts) - [Performance](#-performance) +- [Changelog Highlights](#-changelog-highlights) +- [Troubleshooting](#-troubleshooting) - [FAQ](#-faq) +- [Roadmap](#-roadmap) - [Contributing](#-contributing) +- [Acknowledgements](#-acknowledgements) - [License](#-license) - [Author](#-author) +- [Star History](#-star-history) --- -## Overview +## 🌸 Overview **MiruroAPI** is a serverless anime data API that fetches real-time information from **AniList GraphQL** and streaming data from **Miruro providers** β€” including anime details, episode lists, M3U8 streaming URLs with subtitles and skip timestamps, search, filtering, characters, and more β€” all through a clean REST API with zero database. -> No database, no auth, no complex setup. Just deploy to Vercel and you have a production API. +> πŸ’‘ No database, no auth, no complex setup. Just deploy to Vercel and you have a production API. ### Why MiruroAPI? -- **18 Endpoints** β€” Complete anime data coverage -- **AniList GraphQL** β€” Rich metadata: scores, characters, relations, recommendations -- **12 Streaming Providers** β€” kiwi, pewe, bee, bonk, bun, ally, nun, twin, cog, moo, hop, telli -- **M3U8 URLs** β€” Direct streaming links with resolution, codec, fansub info -- **Skip Timestamps** β€” OP/ED skip data for supported anime -- **Smart Caching** β€” In-memory Map with TTL reduces API load -- **CORS Enabled** β€” Works from any frontend, no proxy needed -- **Swagger UI** β€” Interactive API documentation at `/docs` -- **Docker Ready** β€” One-command containerized deployment +- 🎬 **18 Endpoints** β€” Complete anime data coverage +- πŸ” **Full-Text Search** β€” Search anime by keyword with suggestions +- 🎭 **Characters & Voice Actors** β€” Full character data from AniList +- 🎯 **Advanced Filtering** β€” Genre, year, season, format, sort +- πŸ† **Trending & Popular** β€” Discover what's hot right now +- πŸ“… **Airing Schedule** β€” See what's airing on any date +- πŸ“‘ **12 Streaming Providers** β€” M3U8 streaming sources +- ⏭️ **Skip Timestamps** β€” OP/ED skip data +- ⚑ **Smart Caching** β€” In-memory Map with configurable TTL +- πŸ”’ **CORS Enabled** β€” Works from any frontend, no proxy needed +- πŸš€ **Zero-Config Deploy** β€” One click to Vercel, or run standalone with Express ### How It Works ```mermaid flowchart TD - A["Client Request
(Browser / App / curl)"] --> B["Express Server
CORS - Security Headers"] - B --> C{"Cache Check
(In-Memory Map)"} - C -- HIT --> D["Return Cached
~50ms"] - C -- MISS --> E{"Which Source?"} - - E -- Metadata --> F["AniList GraphQL
graphql.anilist.co"] - E -- Streaming --> G["Miruro Pipe
miruro.tv/api/secure/pipe"] - + A["🌐 Client Request
(Browser / App / curl)"] --> B["πŸ›‘οΈ Express Server
CORS Β· Security Headers Β· Rate Limiting"] + B --> C{"πŸ’Ύ Cache Check
(In-Memory Map)"} + C -- HIT --> D["⚑ Return Cached Response
~50ms"] + C -- MISS --> E{"πŸ” Which Source?"} + + E -- Metadata --> F["πŸ“‘ AniList GraphQL
graphql.anilist.co"] + E -- Streaming --> G["πŸ“Ί Miruro Pipe
miruro.tv/api/secure/pipe"] + F --> H["AniList Response
JSON"] G --> I["Pipe Response
base64url + gzip"] - - H --> J["Cache + Respond"] + + H --> J["Cache + Respond
JSON"] I --> J - - style A fill:#0f172a,stroke:#38bdf8,color:#e2e8f0 - style B fill:#0f172a,stroke:#818cf8,color:#e2e8f0 - style C fill:#0f172a,stroke:#f43f5e,color:#e2e8f0 - style D fill:#0f172a,stroke:#22c55e,color:#e2e8f0 - style E fill:#0f172a,stroke:#a855f7,color:#e2e8f0 - style F fill:#0f172a,stroke:#02a6e4,color:#e2e8f0 - style G fill:#0f172a,stroke:#eab308,color:#e2e8f0 - style H fill:#0f172a,stroke:#06b6d4,color:#e2e8f0 - style I fill:#0f172a,stroke:#eab308,color:#e2e8f0 - style J fill:#0f172a,stroke:#22c55e,color:#e2e8f0 + + 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 F fill:#1e1e2e,stroke:#06b6d4,color:#f1f5f9 + style G fill:#1e1e2e,stroke:#eab308,color:#f1f5f9 + style H fill:#1e1e2e,stroke:#06b6d4,color:#f1f5f9 + style I fill:#1e1e2e,stroke:#eab308,color:#f1f5f9 + style J fill:#1e1e2e,stroke:#22c55e,color:#f1f5f9 ``` --- -## Features +## ✨ Features
-### Core +### ⚑ Core - **AniList GraphQL** for rich metadata - **Miruro pipe** for streaming sources - **Smart caching** with configurable TTL @@ -138,7 +146,7 @@ flowchart TD -### Data +### πŸ” Data - **Full-text search** with pagination - **Autocomplete suggestions** for search - **Advanced filtering** β€” genre, year, season, format, sort @@ -151,7 +159,7 @@ flowchart TD
-### Streaming +### πŸ“‘ Streaming - **Episode lists** from 12 providers - **M3U8 streaming URLs** with resolution info - **Skip timestamps** (OP/ED) @@ -162,7 +170,7 @@ flowchart TD -### Reliability +### πŸ›‘οΈ Reliability - **CORS enabled** β€” works from any frontend - **Error responses** with descriptive messages - **Input validation** β€” required params checked @@ -174,209 +182,226 @@ flowchart TD
-### Feature Highlights +### 🌟 Feature Highlights | Feature | Description | Status | |:---|:---|:---:| -| 18 API Endpoints | Complete anime data coverage | Done | -| AniList GraphQL | Rich metadata from AniList | Done | -| 12 Streaming Providers | M3U8 streaming sources | Done | -| Full-Text Search | Keyword search with pagination | Done | -| Autocomplete Suggestions | Fast search suggestions | Done | -| Advanced Filtering | Genre, year, season, format, sort | Done | -| Characters + Voice Actors | Full character data from AniList | Done | -| Relations & Recommendations | Related anime discovery | Done | -| Skip Timestamps | OP/ED skip data | Done | -| Smart Caching | In-memory Map with TTL | Done | -| Swagger UI Docs | Interactive API documentation | Done | -| Docker Support | Containerized deployment | Done | +| 🎬 18 API Endpoints | Complete anime data coverage | βœ… | +| πŸ” Full-Text Search | Keyword search with pagination | βœ… | +| πŸ’‘ Search Suggestions | Fast autocomplete | βœ… | +| 🎯 Advanced Filtering | Genre, year, season, format, sort | βœ… | +| 🎭 Characters + Voice Actors | Full character data from AniList | βœ… | +| πŸ”— Relations & Recommendations | Related anime discovery | βœ… | +| ⏭️ Skip Timestamps | OP/ED skip data | βœ… | +| πŸ“‘ 12 Streaming Providers | M3U8 streaming sources | βœ… | +| πŸ”„ Smart Caching | In-memory Map with TTL | βœ… | +| πŸš€ One-Click Deploy | Vercel button deployment | βœ… | +| πŸ—οΈ Express Mode | Standalone server with `npm start` | βœ… | +| 🐳 Docker Support | Containerized deployment | βœ… | --- -## Data Sources +## πŸ—žοΈ Data Sources ### Metadata Source | Source | API | Data | |:---|:---|:---| -| **AniList** | `graphql.anilist.co` | Search, info, characters, relations, recommendations, filter, schedule | +| 🌸 **AniList** | `graphql.anilist.co` | Search, info, characters, relations, recommendations, filter, schedule | ### Streaming Source | Source | Domain | Data | |:---|:---|:---| -| **Miruro** | `miruro.tv` | Episodes, streaming sources (M3U8 URLs) | -| **Miruro** | `miruro.to` | Mirror domain | -| **Miruro** | `miruro.bz` | Mirror domain | -| **Miruro** | `miruro.ru` | Mirror domain | +| πŸ“Ί **Miruro** | `miruro.tv` | Episodes, streaming sources (M3U8 URLs) | +| πŸ“Ί **Miruro** | `miruro.to` | Mirror domain | +| πŸ“Ί **Miruro** | `miruro.bz` | Mirror domain | +| πŸ“Ί **Miruro** | `miruro.ru` | Mirror domain | -### Streaming Providers +### 🎬 Streaming Providers | Provider | Provider | Provider | Provider | |:---|:---|:---|:---| -| kiwi | pewe | bee | bonk | -| bun | ally | nun | twin | -| cog | moo | hop | telli | +| πŸ₯ kiwi | 🐝 pewe | 🐻 bee | 🍯 bonk | +| 🍌 bun | 🀝 ally | πŸ¦„ nun | πŸ‘― twin | +| βš™οΈ cog | πŸ„ moo | 🐰 hop | πŸ“Ί telli | --- -## Tech Stack +## πŸ› οΈ Tech Stack -| Technology | Purpose | Version | -|:---|:---|:---| -| [Node.js](https://nodejs.org/) | JavaScript runtime | >= 20 | -| [Express](https://expressjs.com/) | HTTP server framework | 4.21 | -| [AniList GraphQL](https://anilist.gitbook.io/anilist-apiv2-docs/) | Anime metadata API | β€” | -| [Axios](https://axios-http.com/) | HTTP client | 1.8 | -| [Vercel Functions](https://vercel.com/docs/functions) | Serverless deployment | β€” | -| [cors](https://github.com/expressjs/cors) | CORS middleware | 2.8 | -| [dotenv](https://github.com/motdotla/dotenv) | Environment variables | 16.4 | +| Technology | Purpose | Version | Documentation | +|:---|:---|:---|:---| +| 🟒 [Node.js](https://nodejs.org/) | JavaScript runtime | >= 20 | [Docs](https://nodejs.org/docs/) | +| ⚑ [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) | +| 🌸 [AniList GraphQL](https://anilist.gitbook.io/anilist-apiv2-docs/) | Anime metadata API | β€” | [Docs](https://anilist.gitbook.io/anilist-apiv2-docs/) | +| 🌐 [Axios](https://axios-http.com/) | HTTP client | 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) | -### Dependencies +### πŸ“¦ Key Dependencies ```json { - "express": "^4.21.0", - "axios": "^1.8.0", - "cors": "^2.8.5", - "dotenv": "^16.4.0" + "express": "^4.21.0", // HTTP server + "axios": "^1.8.0", // HTTP client + "cors": "^2.8.5", // CORS middleware + "dotenv": "^16.4.0" // Environment variables } ``` --- -## Architecture +## πŸ—οΈ Architecture ### Request Flow | Stage | Component | Description | -|:---:|-----------|-------------| +|:-----:|-----------|-------------| | 1 | **Client** | Browser, app, or `curl` sends request | | 2 | **Express Server** | Routes request, applies CORS + security headers + rate limiting | | 3 | **Cache Check** | In-memory Map with TTL β€” hit = instant response | | 4 | **Fetch Data** | AniList GraphQL or Miruro pipe endpoint | -| 5 | **Decode** | Pipe responses decoded: base64url -> gunzip -> JSON | +| 5 | **Decode** | Pipe responses decoded: base64url β†’ gunzip β†’ JSON | | 6 | **Cache + Respond** | Store in cache, return JSON response | ### Caching Architecture -| Cache Type | TTL | Max Size | Eviction | -|:---|:---|:---|:---| -| Search results | 1 min | 100 entries | FIFO | -| Collection lists | 2-5 min | 100 entries | FIFO | -| Episode lists | 2 min | 100 entries | FIFO | -| Streaming sources | 1 min | 100 entries | FIFO | +```mermaid +flowchart TD + A["πŸ“₯ Request"] --> B{"🧠 Memory Cache
(Map + TTL)"} + B -- HIT --> C["⚑ Return Cached
~50ms"] + B -- MISS --> D["πŸ“‘ Fetch from
AniList / Miruro"] + D --> E["πŸ” Decode
base64url + gzip"] + E --> F["πŸ’Ύ Cache Result
(1-5 min TTL)"] + F --> G["πŸ“€ Return Fresh"] -> Serverless functions have read-only filesystems except `/tmp`. The cache uses in-memory `Map` which survives across warm invocations. + style A fill:#1e1e2e,stroke:#a78bfa,color:#f1f5f9 + style B fill:#1e1e2e,stroke:#f43f8e,color:#f1f5f9 + style C fill:#1e1e2e,stroke:#22c55e,color:#f1f5f9 + style D fill:#1e1e2e,stroke:#6366f1,color:#f1f5f9 + style E fill:#1e1e2e,stroke:#06b6d4,color:#f1f5f9 + style F fill:#1e1e2e,stroke:#a855f7,color:#f1f5f9 + 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. --- -## Project Structure +## πŸ“ Project Structure ``` MiruroAPI/ -β”œβ”€β”€ public/ # Static files -β”‚ β”œβ”€β”€ index.html # Premium landing page -β”‚ β”œβ”€β”€ docs.html # Swagger UI documentation -β”‚ β”œβ”€β”€ openapi.json # OpenAPI 3.0 spec -β”‚ β”œβ”€β”€ icon-dark.svg # Miruro dark mode favicon -β”‚ β”œβ”€β”€ icon-light.svg # Miruro light mode favicon -β”‚ β”œβ”€β”€ icon-512x512.png # Miruro app icon -β”‚ β”œβ”€β”€ favicon.ico # Classic favicon -β”‚ β”œβ”€β”€ apple-touch-icon-180x180.png # iOS home screen icon -β”‚ └── og-image.png # OG/Twitter share image +β”œβ”€β”€ πŸ“‚ public/ # 🌐 Static files +β”‚ β”œβ”€β”€ πŸ“„ index.html # πŸ“– Premium landing page (real Miruro icons) +β”‚ β”œβ”€β”€ πŸ“„ docs.html # πŸ“˜ Swagger UI interactive documentation +β”‚ β”œβ”€β”€ πŸ“„ openapi.json # πŸ“‹ OpenAPI 3.0 spec +β”‚ β”œβ”€β”€ πŸ“„ icon-dark.svg # πŸŒ™ Miruro dark mode favicon +β”‚ β”œβ”€β”€ πŸ“„ icon-light.svg # β˜€οΈ Miruro light mode favicon +β”‚ β”œβ”€β”€ πŸ“„ icon-512x512.png # πŸ“± Miruro app icon +β”‚ β”œβ”€β”€ πŸ“„ favicon.ico # πŸ”– Classic favicon +β”‚ β”œβ”€β”€ πŸ“„ apple-touch-icon-180x180.png # 🍎 iOS home screen icon +β”‚ └── πŸ“„ og-image.png # πŸ–ΌοΈ OG/Twitter share image β”‚ -β”œβ”€β”€ assets/ # Scraped Miruro assets -β”‚ β”œβ”€β”€ favicons/ # All favicon variants -β”‚ β”œβ”€β”€ logos/ # Status page logo -β”‚ β”œβ”€β”€ fonts/ # Inter + FontAwesome -β”‚ └── media/ # Testimonial avatars +β”œβ”€β”€ πŸ“‚ assets/ # 🎨 Scraped Miruro assets +β”‚ β”œβ”€β”€ πŸ“‚ favicons/ # πŸ”– All favicon variants +β”‚ β”œβ”€β”€ πŸ“‚ logos/ # 🏷️ Status page logo +β”‚ β”œβ”€β”€ πŸ“‚ fonts/ # πŸ”€ Inter + FontAwesome +β”‚ └── πŸ“‚ media/ # πŸ–ΌοΈ Testimonial avatars β”‚ -β”œβ”€β”€ src/ -β”‚ β”œβ”€β”€ helpers/ -β”‚ β”‚ β”œβ”€β”€ anilist.js # AniList GraphQL integration -β”‚ β”‚ β”œβ”€β”€ pipe.js # Miruro pipe integration -β”‚ β”‚ └── cache.js # In-memory cache with TTL -β”‚ └── routes/ -β”‚ └── apiRoutes.js # All 18 route definitions +β”œβ”€β”€ πŸ“‚ src/ # βš™οΈ Core logic +β”‚ β”œβ”€β”€ πŸ“‚ helpers/ # πŸ› οΈ Integration modules +β”‚ β”‚ β”œβ”€β”€ πŸ“„ anilist.js # 🌸 AniList GraphQL integration +β”‚ β”‚ β”œβ”€β”€ πŸ“„ pipe.js # πŸ“Ί Miruro pipe integration +β”‚ β”‚ └── πŸ“„ cache.js # πŸ’Ύ In-memory cache with TTL +β”‚ β”‚ +β”‚ └── πŸ“‚ routes/ # πŸ›€οΈ Express routes +β”‚ └── πŸ“„ apiRoutes.js # 🌐 Main API routes (18 endpoints) β”‚ -β”œβ”€β”€ server.js # Express server entry point -β”œβ”€β”€ package.json # Dependencies & scripts -β”œβ”€β”€ vercel.json # Vercel routing config -β”œβ”€β”€ Dockerfile # Docker support -β”œβ”€β”€ CHANGELOG.md # Version history -└── README.md # This file +β”œβ”€β”€ πŸ“„ server.js # πŸš€ Express server entry point +β”œβ”€β”€ πŸ“„ package.json # πŸ“¦ Dependencies & scripts +β”œβ”€β”€ πŸ“„ vercel.json # β–² Vercel routing config +β”œβ”€β”€ πŸ“„ Dockerfile # 🐳 Docker support +β”œβ”€β”€ πŸ“„ .dockerignore # 🐳 Docker ignore +β”œβ”€β”€ πŸ“„ CHANGELOG.md # πŸ“ Version history +└── πŸ“„ README.md # πŸ“– This file ``` --- -## Quick Start +## πŸš€ Quick Start ### Prerequisites | Requirement | Minimum | Recommended | |:---|:---|:---| -| Node.js | 20.x | 20.x LTS | -| npm | 9.0+ | 10.x | +| πŸ“¦ Node.js | 20.x | 20.x LTS | +| πŸ“¦ npm | 9.0+ | 10.x | +| πŸ’» OS | Windows, macOS, Linux | Any | -### Installation +### πŸ”§ Installation ```bash -# 1. Clone the repository +# 1️⃣ Clone the repository git clone https://github.com/Shineii86/MiruroAPI.git cd MiruroAPI -# 2. Install dependencies +# 2️⃣ Install dependencies npm install -# 3. Start development server +# 3️⃣ Start development server npm run dev ``` -> Open [http://localhost:3000](http://localhost:3000) in your browser. +> 🌐 Open [http://localhost:3000](http://localhost:3000) in your browser. -### Production +### πŸ—οΈ Build for Production ```bash +# Start production server npm start ``` -### Alternative Package Managers +### 🐳 Alternative Package Managers ```bash -# yarn -yarn install && yarn dev +# Using yarn +yarn install +yarn dev -# pnpm -pnpm install && pnpm dev +# Using pnpm +pnpm install +pnpm dev -# bun -bun install && bun dev +# Using bun +bun install +bun dev ``` --- -## Configuration +## βš™οΈ Configuration ### Environment Variables | Variable | Default | Description | |:---|:---|:---| -| `PORT` | `3000` | Server port | +| `PORT` | `3000` | Server port (Express mode only) | | `ALLOWED_ORIGINS` | `*` | Comma-separated allowed origins | ### Vercel Configuration -The `vercel.json` handles: +The `vercel.json` file handles: - **Builds** β€” Maps `server.js` to `@vercel/node` - **Routes** β€” All requests forwarded to Express --- -## API Endpoints +## πŸ“‘ API Endpoints ### Base URL - ``` https://mirurotvapi.vercel.app/api ``` @@ -384,7 +409,6 @@ https://mirurotvapi.vercel.app/api ### Response Format All endpoints return: - ```json { "success": true, @@ -392,20 +416,65 @@ All endpoints return: } ``` ---- +### Streaming Flow -### Health Check +To get a stream URL, follow these 3 steps: ```bash -GET /api/health +# Step 1: Get episodes (returns provider slugs) +curl "https://mirurotvapi.vercel.app/api/episodes/20" + +# Step 2: Get streaming sources (pass provider + anilistId + category + slug) +curl "https://mirurotvapi.vercel.app/api/watch/kiwi/20/sub/animepahe-1" + +# Step 3: Play M3U8 in any HLS player +# Use hls.js, video.js, or native