mirror of
https://github.com/Shineii86/MiruroAPI.git
synced 2026-10-22 18:25:11 +00:00
docs: rewrite all files with AniKotoAPI documentation style
- Box-style file headers (======= border, @description, @exports, @author, @license) - Section headers (═════════════════════════════════════════) - Function-level JSDoc comments with @param, @returns, @example - Inline notes for non-obvious logic (lazy eviction, pipe decoding, slug resolution) - Feature markers (---- FEATURE: description ----) - Footer on every module (═══════════ END: filename ═══════════) - Added /stats and /openapi endpoints to router
This commit is contained in:
Sʜɪɴᴇɪ Nᴏᴜᴢᴇɴ
+229
-22
@@ -1,7 +1,50 @@
|
||||
/*
|
||||
* ======= • ======= • ======= • ======= • =======• =======
|
||||
* MiruroAPI — anilist.js
|
||||
* Repository: https://github.com/Shineii86/MiruroAPI
|
||||
*
|
||||
* @description
|
||||
* AniList GraphQL API integration module. Provides functions for
|
||||
* searching anime, fetching details, browsing collections, and
|
||||
* querying the AniList GraphQL API. All metadata (titles, covers,
|
||||
* genres, scores, characters, relations) comes from AniList.
|
||||
*
|
||||
* @exports
|
||||
* searchAnime, getSuggestions, getAnimeInfo, getAnimeCharacters,
|
||||
* getAnimeRelations, getAnimeRecommendations, getCollection,
|
||||
* getSpotlight, getSchedule, filterAnime
|
||||
*
|
||||
* @author Shinei Nouzen
|
||||
* @license MIT
|
||||
* ======= • ======= • ======= • ======= • =======• =======
|
||||
*/
|
||||
|
||||
const axios = require("axios");
|
||||
|
||||
// ══════════════════════════════════════════════════════════════
|
||||
// ANILIST API CONFIGURATION
|
||||
// ══════════════════════════════════════════════════════════════
|
||||
|
||||
/**
|
||||
* AniList GraphQL API endpoint.
|
||||
* Used for all metadata queries (search, trending, info, filter).
|
||||
*
|
||||
* @type {string}
|
||||
*/
|
||||
const ANILIST_URL = "https://graphql.anilist.co";
|
||||
|
||||
// ══════════════════════════════════════════════════════════════
|
||||
// GRAPHQL FRAGMENTS
|
||||
// ══════════════════════════════════════════════════════════════
|
||||
|
||||
// ---- FEATURE: Media list fields fragment (used in collections/search) ----
|
||||
/**
|
||||
* Standard set of fields for anime list responses.
|
||||
* Used in trending, popular, search, filter, and schedule endpoints.
|
||||
* Includes titles, cover, format, scores, genres, studios, and airing info.
|
||||
*
|
||||
* @type {string}
|
||||
*/
|
||||
const MEDIA_LIST_FIELDS = `
|
||||
id
|
||||
title { romaji english native }
|
||||
@@ -27,6 +70,14 @@ const MEDIA_LIST_FIELDS = `
|
||||
endDate { year month day }
|
||||
`;
|
||||
|
||||
// ---- FEATURE: Media full fields fragment (used in info endpoint) ----
|
||||
/**
|
||||
* Extended set of fields for detailed anime info responses.
|
||||
* Includes everything in MEDIA_LIST_FIELDS plus characters, staff,
|
||||
* relations, recommendations, trailer, stats, and external links.
|
||||
*
|
||||
* @type {string}
|
||||
*/
|
||||
const MEDIA_FULL_FIELDS = `
|
||||
id
|
||||
idMal
|
||||
@@ -109,17 +160,53 @@ const MEDIA_FULL_FIELDS = `
|
||||
}
|
||||
`;
|
||||
|
||||
async function anilistQuery(query, variables = {}) {
|
||||
// ══════════════════════════════════════════════════════════════
|
||||
// CORE QUERY FUNCTION
|
||||
// ══════════════════════════════════════════════════════════════
|
||||
|
||||
// ---- FEATURE: Execute AniList GraphQL query ----
|
||||
/**
|
||||
* Executes a GraphQL query against the AniList API.
|
||||
* Handles request formatting and error checking.
|
||||
*
|
||||
* @param {string} query - The GraphQL query string
|
||||
* @param {object} [variables={}] - Query variables
|
||||
* @returns {Promise<object>} The `data` field from the AniList response
|
||||
* @throws {Error} If the AniList API returns a non-200 status
|
||||
*
|
||||
* @example
|
||||
* const data = await anilistQuery(MEDIA_LIST_FIELDS, { search: "naruto" });
|
||||
*/
|
||||
const anilistQuery = async (query, variables = {}) => {
|
||||
const body = { query, variables };
|
||||
const res = await axios.post(ANILIST_URL, body, {
|
||||
headers: { "Content-Type": "application/json" },
|
||||
timeout: 15000,
|
||||
});
|
||||
|
||||
if (res.status !== 200) throw new Error("AniList query failed");
|
||||
return res.data.data;
|
||||
}
|
||||
};
|
||||
|
||||
async function searchAnime(query, page = 1, perPage = 20) {
|
||||
// ══════════════════════════════════════════════════════════════
|
||||
// SEARCH ENDPOINTS
|
||||
// ══════════════════════════════════════════════════════════════
|
||||
|
||||
// ---- FEATURE: Full-text anime search with pagination ----
|
||||
/**
|
||||
* Searches AniList for anime matching the given query.
|
||||
* Returns paginated results with full metadata per result.
|
||||
*
|
||||
* @param {string} query - The search query string
|
||||
* @param {number} [page=1] - Page number for pagination
|
||||
* @param {number} [perPage=20] - Results per page (max 50)
|
||||
* @returns {Promise<object>} Paginated search results with page, perPage, total, hasNextPage, results[]
|
||||
*
|
||||
* @example
|
||||
* const results = await searchAnime("naruto", 1, 10);
|
||||
* console.log(results.total); // 5000+
|
||||
*/
|
||||
const searchAnime = async (query, page = 1, perPage = 20) => {
|
||||
const gql = `
|
||||
query ($search: String, $page: Int, $perPage: Int) {
|
||||
Page(page: $page, perPage: $perPage) {
|
||||
@@ -132,6 +219,7 @@ async function searchAnime(query, page = 1, perPage = 20) {
|
||||
`;
|
||||
const data = await anilistQuery(gql, { search: query, page, perPage });
|
||||
const pageData = data.Page;
|
||||
|
||||
return {
|
||||
page: pageData.pageInfo.currentPage,
|
||||
perPage: pageData.pageInfo.perPage,
|
||||
@@ -139,9 +227,21 @@ async function searchAnime(query, page = 1, perPage = 20) {
|
||||
hasNextPage: pageData.pageInfo.hasNextPage,
|
||||
results: pageData.media,
|
||||
};
|
||||
}
|
||||
};
|
||||
|
||||
async function getSuggestions(query) {
|
||||
// ---- FEATURE: Lightweight autocomplete suggestions (max 8) ----
|
||||
/**
|
||||
* Fetches search suggestions for autocomplete dropdowns.
|
||||
* Returns minimal data (id, title, poster, format, status, year).
|
||||
*
|
||||
* @param {string} query - The search query string
|
||||
* @returns {Promise<Array>} Array of up to 8 suggestion objects
|
||||
*
|
||||
* @example
|
||||
* const suggestions = await getSuggestions("one piece");
|
||||
* console.log(suggestions[0].title); // "ONE PIECE"
|
||||
*/
|
||||
const getSuggestions = async (query) => {
|
||||
const gql = `
|
||||
query ($search: String) {
|
||||
Page(page: 1, perPage: 8) {
|
||||
@@ -158,6 +258,7 @@ async function getSuggestions(query) {
|
||||
}
|
||||
`;
|
||||
const data = await anilistQuery(gql, { search: query });
|
||||
|
||||
return data.Page.media.map((item) => ({
|
||||
id: item.id,
|
||||
title: item.title.english || item.title.romaji,
|
||||
@@ -168,9 +269,26 @@ async function getSuggestions(query) {
|
||||
year: item.startDate?.year,
|
||||
episodes: item.episodes,
|
||||
}));
|
||||
}
|
||||
};
|
||||
|
||||
async function getAnimeInfo(id) {
|
||||
// ══════════════════════════════════════════════════════════════
|
||||
// ANIME DETAILS
|
||||
// ══════════════════════════════════════════════════════════════
|
||||
|
||||
// ---- FEATURE: Complete anime info by AniList ID ----
|
||||
/**
|
||||
* Fetches full anime metadata including characters, staff,
|
||||
* relations, recommendations, trailer, stats, and external links.
|
||||
*
|
||||
* @param {number} id - AniList anime ID
|
||||
* @returns {Promise<object>} Complete anime metadata object
|
||||
* @throws {Error} If anime is not found
|
||||
*
|
||||
* @example
|
||||
* const info = await getAnimeInfo(20); // Naruto
|
||||
* console.log(info.title.romaji); // "NARUTO"
|
||||
*/
|
||||
const getAnimeInfo = async (id) => {
|
||||
const gql = `
|
||||
query ($id: Int) {
|
||||
Media(id: $id, type: ANIME) {
|
||||
@@ -180,9 +298,19 @@ async function getAnimeInfo(id) {
|
||||
`;
|
||||
const data = await anilistQuery(gql, { id });
|
||||
return data.Media;
|
||||
}
|
||||
};
|
||||
|
||||
async function getAnimeCharacters(id, page = 1, perPage = 25) {
|
||||
// ---- FEATURE: Paginated character list with voice actors ----
|
||||
/**
|
||||
* Fetches paginated character list for an anime.
|
||||
* Each character includes name, image, role, and Japanese voice actors.
|
||||
*
|
||||
* @param {number} id - AniList anime ID
|
||||
* @param {number} [page=1] - Page number
|
||||
* @param {number} [perPage=25] - Results per page (max 50)
|
||||
* @returns {Promise<object>} Paginated character list
|
||||
*/
|
||||
const getAnimeCharacters = async (id, page = 1, perPage = 25) => {
|
||||
const gql = `
|
||||
query ($id: Int, $page: Int, $perPage: Int) {
|
||||
Media(id: $id, type: ANIME) {
|
||||
@@ -201,6 +329,7 @@ async function getAnimeCharacters(id, page = 1, perPage = 25) {
|
||||
`;
|
||||
const data = await anilistQuery(gql, { id, page, perPage });
|
||||
if (!data.Media) throw new Error("Anime not found");
|
||||
|
||||
const chars = data.Media.characters;
|
||||
return {
|
||||
page: chars.pageInfo.currentPage,
|
||||
@@ -209,9 +338,17 @@ async function getAnimeCharacters(id, page = 1, perPage = 25) {
|
||||
hasNextPage: chars.pageInfo.hasNextPage,
|
||||
characters: chars.edges,
|
||||
};
|
||||
}
|
||||
};
|
||||
|
||||
async function getAnimeRelations(id) {
|
||||
// ---- FEATURE: Related anime (sequels, prequels, spin-offs) ----
|
||||
/**
|
||||
* Fetches all related media for an anime — sequels, prequels,
|
||||
* side stories, spin-offs, and source material.
|
||||
*
|
||||
* @param {number} id - AniList anime ID
|
||||
* @returns {Promise<object>} Relations with id, title, and relations[]
|
||||
*/
|
||||
const getAnimeRelations = async (id) => {
|
||||
const gql = `
|
||||
query ($id: Int) {
|
||||
Media(id: $id, type: ANIME) {
|
||||
@@ -231,14 +368,25 @@ async function getAnimeRelations(id) {
|
||||
`;
|
||||
const data = await anilistQuery(gql, { id });
|
||||
if (!data.Media) throw new Error("Anime not found");
|
||||
|
||||
return {
|
||||
id: data.Media.id,
|
||||
title: data.Media.title,
|
||||
relations: data.Media.relations.edges,
|
||||
};
|
||||
}
|
||||
};
|
||||
|
||||
async function getAnimeRecommendations(id, page = 1, perPage = 10) {
|
||||
// ---- FEATURE: Community recommendations sorted by rating ----
|
||||
/**
|
||||
* Fetches paginated community recommendations for an anime.
|
||||
* "If you liked X, you'll like Y" — sorted by highest rating.
|
||||
*
|
||||
* @param {number} id - AniList anime ID
|
||||
* @param {number} [page=1] - Page number
|
||||
* @param {number} [perPage=10] - Results per page (max 25)
|
||||
* @returns {Promise<object>} Paginated recommendations
|
||||
*/
|
||||
const getAnimeRecommendations = async (id, page = 1, perPage = 10) => {
|
||||
const gql = `
|
||||
query ($id: Int, $page: Int, $perPage: Int) {
|
||||
Media(id: $id, type: ANIME) {
|
||||
@@ -259,6 +407,7 @@ async function getAnimeRecommendations(id, page = 1, perPage = 10) {
|
||||
`;
|
||||
const data = await anilistQuery(gql, { id, page, perPage });
|
||||
if (!data.Media) throw new Error("Anime not found");
|
||||
|
||||
const recs = data.Media.recommendations;
|
||||
return {
|
||||
page: recs.pageInfo.currentPage,
|
||||
@@ -267,9 +416,24 @@ async function getAnimeRecommendations(id, page = 1, perPage = 10) {
|
||||
hasNextPage: recs.pageInfo.hasNextPage,
|
||||
recommendations: recs.nodes,
|
||||
};
|
||||
}
|
||||
};
|
||||
|
||||
async function getCollection(sortType, status = null, page = 1, perPage = 20) {
|
||||
// ══════════════════════════════════════════════════════════════
|
||||
// COLLECTIONS
|
||||
// ══════════════════════════════════════════════════════════════
|
||||
|
||||
// ---- FEATURE: Generic collection fetcher with sort and status ----
|
||||
/**
|
||||
* Internal helper for fetching anime collections (trending, popular, etc.).
|
||||
* Builds a dynamic GraphQL query based on sort type and optional status filter.
|
||||
*
|
||||
* @param {string} sortType - AniList sort enum (e.g., "TRENDING_DESC", "POPULARITY_DESC")
|
||||
* @param {string|null} status - Optional status filter (e.g., "RELEASING", "NOT_YET_RELEASED")
|
||||
* @param {number} [page=1] - Page number
|
||||
* @param {number} [perPage=20] - Results per page
|
||||
* @returns {Promise<object>} Paginated collection results
|
||||
*/
|
||||
const getCollection = async (sortType, status = null, page = 1, perPage = 20) => {
|
||||
const statusFilter = status ? `, status: ${status}` : "";
|
||||
const gql = `
|
||||
query ($page: Int, $perPage: Int) {
|
||||
@@ -283,6 +447,7 @@ async function getCollection(sortType, status = null, page = 1, perPage = 20) {
|
||||
`;
|
||||
const data = await anilistQuery(gql, { page, perPage });
|
||||
const pageData = data.Page;
|
||||
|
||||
return {
|
||||
page: pageData.pageInfo.currentPage,
|
||||
perPage: pageData.pageInfo.perPage,
|
||||
@@ -290,9 +455,16 @@ async function getCollection(sortType, status = null, page = 1, perPage = 20) {
|
||||
hasNextPage: pageData.pageInfo.hasNextPage,
|
||||
results: pageData.media,
|
||||
};
|
||||
}
|
||||
};
|
||||
|
||||
async function getSpotlight() {
|
||||
// ---- FEATURE: Spotlight/featured anime (top 10 trending + popular) ----
|
||||
/**
|
||||
* Fetches the top 10 trending + popular anime for hero banners.
|
||||
* Combines TRENDING_DESC and POPULARITY_DESC sorts.
|
||||
*
|
||||
* @returns {Promise<Array>} Array of up to 10 anime objects
|
||||
*/
|
||||
const getSpotlight = async () => {
|
||||
const gql = `
|
||||
query {
|
||||
Page(page: 1, perPage: 10) {
|
||||
@@ -304,9 +476,18 @@ async function getSpotlight() {
|
||||
`;
|
||||
const data = await anilistQuery(gql);
|
||||
return data.Page.media;
|
||||
}
|
||||
};
|
||||
|
||||
async function getSchedule(page = 1, perPage = 20) {
|
||||
// ---- FEATURE: Airing schedule with timestamps ----
|
||||
/**
|
||||
* Fetches upcoming anime episodes with UNIX timestamps.
|
||||
* Each result includes next_episode number, airingAt, and timeUntilAiring.
|
||||
*
|
||||
* @param {number} [page=1] - Page number
|
||||
* @param {number} [perPage=20] - Results per page
|
||||
* @returns {Promise<object>} Paginated schedule with airing timestamps
|
||||
*/
|
||||
const getSchedule = async (page = 1, perPage = 20) => {
|
||||
const gql = `
|
||||
query ($page: Int, $perPage: Int) {
|
||||
Page(page: $page, perPage: $perPage) {
|
||||
@@ -322,12 +503,14 @@ async function getSchedule(page = 1, perPage = 20) {
|
||||
`;
|
||||
const data = await anilistQuery(gql, { page, perPage });
|
||||
const pageData = data.Page;
|
||||
|
||||
const results = pageData.airingSchedules.map((item) => ({
|
||||
...item.media,
|
||||
next_episode: item.episode,
|
||||
airingAt: item.airingAt,
|
||||
timeUntilAiring: item.timeUntilAiring,
|
||||
}));
|
||||
|
||||
return {
|
||||
page: pageData.pageInfo.currentPage,
|
||||
perPage: pageData.pageInfo.perPage,
|
||||
@@ -335,9 +518,29 @@ async function getSchedule(page = 1, perPage = 20) {
|
||||
hasNextPage: pageData.pageInfo.hasNextPage,
|
||||
results,
|
||||
};
|
||||
}
|
||||
};
|
||||
|
||||
async function filterAnime({ genre, tag, year, season, format, status, sort = "POPULARITY_DESC", page = 1, perPage = 20 }) {
|
||||
// ---- FEATURE: Advanced anime filter with multiple parameters ----
|
||||
/**
|
||||
* Advanced anime filter supporting genre, tag, year, season,
|
||||
* format, status, and sort. All parameters are optional.
|
||||
*
|
||||
* @param {object} options - Filter options
|
||||
* @param {string} [options.genre] - Genre name (e.g., "Action", "Romance")
|
||||
* @param {string} [options.tag] - Tag name (e.g., "Isekai", "Time Skip")
|
||||
* @param {number} [options.year] - Season year (e.g., 2025)
|
||||
* @param {string} [options.season] - Season (WINTER, SPRING, SUMMER, FALL)
|
||||
* @param {string} [options.format] - Format (TV, MOVIE, OVA, ONA, SPECIAL)
|
||||
* @param {string} [options.status] - Status (RELEASING, FINISHED, NOT_YET_RELEASED)
|
||||
* @param {string} [options.sort="POPULARITY_DESC"] - Sort order
|
||||
* @param {number} [options.page=1] - Page number
|
||||
* @param {number} [options.perPage=20] - Results per page
|
||||
* @returns {Promise<object>} Paginated filtered results
|
||||
*/
|
||||
const filterAnime = async ({
|
||||
genre, tag, year, season, format, status,
|
||||
sort = "POPULARITY_DESC", page = 1, perPage = 20,
|
||||
}) => {
|
||||
const SORT_MAP = {
|
||||
SCORE_DESC: "SCORE_DESC",
|
||||
POPULARITY_DESC: "POPULARITY_DESC",
|
||||
@@ -347,6 +550,7 @@ async function filterAnime({ genre, tag, year, season, format, status, sort = "P
|
||||
UPDATED_AT_DESC: "UPDATED_AT_DESC",
|
||||
};
|
||||
|
||||
// NOTE: Build dynamic GraphQL arguments based on provided filters
|
||||
const args = ["type: ANIME", `sort: [${SORT_MAP[sort] || "POPULARITY_DESC"}]`];
|
||||
const variables = { page, perPage };
|
||||
const varTypes = ["$page: Int", "$perPage: Int"];
|
||||
@@ -370,6 +574,7 @@ async function filterAnime({ genre, tag, year, season, format, status, sort = "P
|
||||
`;
|
||||
const data = await anilistQuery(gql, variables);
|
||||
const pageData = data.Page;
|
||||
|
||||
return {
|
||||
page: pageData.pageInfo.currentPage,
|
||||
perPage: pageData.pageInfo.perPage,
|
||||
@@ -377,7 +582,7 @@ async function filterAnime({ genre, tag, year, season, format, status, sort = "P
|
||||
hasNextPage: pageData.pageInfo.hasNextPage,
|
||||
results: pageData.media,
|
||||
};
|
||||
}
|
||||
};
|
||||
|
||||
module.exports = {
|
||||
anilistQuery,
|
||||
@@ -394,3 +599,5 @@ module.exports = {
|
||||
MEDIA_LIST_FIELDS,
|
||||
MEDIA_FULL_FIELDS,
|
||||
};
|
||||
|
||||
// ══════════════════════════════════════════════════════════════ END: anilist.js
|
||||
|
||||
+107
-9
@@ -1,27 +1,125 @@
|
||||
/*
|
||||
* ======= • ======= • ======= • ======= • =======• =======
|
||||
* MiruroAPI — cache.js
|
||||
* Repository: https://github.com/Shineii86/MiruroAPI
|
||||
*
|
||||
* @description
|
||||
* In-memory caching utility for storing and retrieving API responses.
|
||||
* Implements TTL-based cache invalidation to prevent stale data
|
||||
* while reducing unnecessary requests to AniList/Miruro backends.
|
||||
*
|
||||
* @exports
|
||||
* getCached, setCache, clearCache
|
||||
*
|
||||
* @author Shinei Nouzen
|
||||
* @license MIT
|
||||
* ======= • ======= • ======= • ======= • =======• =======
|
||||
*/
|
||||
|
||||
// ══════════════════════════════════════════════════════════════
|
||||
// CACHE STORAGE & CONFIGURATION
|
||||
// ══════════════════════════════════════════════════════════════
|
||||
|
||||
// ---- FEATURE: In-memory Map-based cache storage ----
|
||||
/**
|
||||
* Internal cache storage using JavaScript Map object.
|
||||
* Stores data with expiry timestamps for TTL-based expiration.
|
||||
*
|
||||
* @type {Map<string, {data: any, expiry: number}>}
|
||||
*/
|
||||
const cache = new Map();
|
||||
const MAX_CACHE_SIZE = 100;
|
||||
|
||||
// ---- FEATURE: Cache time-to-live configuration (1 minute) ----
|
||||
/**
|
||||
* Default cache TTL (Time-To-Live) in milliseconds.
|
||||
* Default: 1 minute (60,000 ms).
|
||||
* After this duration, cached items are considered stale
|
||||
* and will be removed on next access.
|
||||
*
|
||||
* @type {number}
|
||||
* @default 60000
|
||||
*/
|
||||
const DEFAULT_TTL = 60 * 1000;
|
||||
|
||||
function getCached(key) {
|
||||
// ---- FEATURE: Maximum cache size limit ----
|
||||
/**
|
||||
* Maximum number of entries allowed in the cache.
|
||||
* When exceeded, the oldest entry is evicted (FIFO).
|
||||
* Prevents unbounded memory growth on long-running instances.
|
||||
*
|
||||
* @type {number}
|
||||
* @default 100
|
||||
*/
|
||||
const MAX_CACHE_SIZE = 100;
|
||||
|
||||
// ══════════════════════════════════════════════════════════════
|
||||
// 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 (lazy eviction).
|
||||
*
|
||||
* @param {string} key - The cache key to lookup
|
||||
* @returns {any|null} Cached data if valid, null if expired or missing
|
||||
*
|
||||
* @example
|
||||
* const data = getCached("search:naruto:1:20");
|
||||
* if (data) {
|
||||
* // Use cached data
|
||||
* }
|
||||
*/
|
||||
const getCached = (key) => {
|
||||
const entry = cache.get(key);
|
||||
if (!entry) return null;
|
||||
|
||||
// NOTE: Lazy eviction — delete stale entries on access
|
||||
if (Date.now() > entry.expiry) {
|
||||
cache.delete(key);
|
||||
return null;
|
||||
}
|
||||
return entry.data;
|
||||
}
|
||||
|
||||
function setCache(key, data, ttl = DEFAULT_TTL) {
|
||||
return entry.data;
|
||||
};
|
||||
|
||||
// ---- FEATURE: Store data in cache with TTL expiry ----
|
||||
/**
|
||||
* Stores data in cache with TTL-based expiry.
|
||||
* Evicts oldest entry if cache is at max capacity (FIFO).
|
||||
*
|
||||
* @param {string} key - The cache key to store under
|
||||
* @param {any} data - The data to cache (any serializable type)
|
||||
* @param {number} [ttl=DEFAULT_TTL] - Time-to-live in milliseconds
|
||||
* @returns {void}
|
||||
*
|
||||
* @example
|
||||
* // Cache search results for 2 minutes
|
||||
* setCache("search:one-piece", results, 120000);
|
||||
*/
|
||||
const setCache = (key, data, ttl = DEFAULT_TTL) => {
|
||||
// NOTE: FIFO eviction — remove oldest entry when cache is full
|
||||
if (cache.size >= MAX_CACHE_SIZE) {
|
||||
const firstKey = cache.keys().next().value;
|
||||
cache.delete(firstKey);
|
||||
}
|
||||
cache.set(key, { data, expiry: Date.now() + ttl });
|
||||
}
|
||||
|
||||
function clearCache() {
|
||||
cache.set(key, { data, expiry: Date.now() + ttl });
|
||||
};
|
||||
|
||||
// ---- FEATURE: Clear all cached entries from memory ----
|
||||
/**
|
||||
* Clears all entries from the cache. Use when:
|
||||
* - Memory cleanup is needed
|
||||
* - Force-refreshing all data
|
||||
* - Application restart/reset
|
||||
*
|
||||
* @returns {void}
|
||||
*/
|
||||
const clearCache = () => {
|
||||
cache.clear();
|
||||
}
|
||||
};
|
||||
|
||||
module.exports = { getCached, setCache, clearCache };
|
||||
|
||||
// ══════════════════════════════════════════════════════════════ END: cache.js
|
||||
|
||||
+204
-21
@@ -1,20 +1,85 @@
|
||||
/*
|
||||
* ======= • ======= • ======= • ======= • =======• =======
|
||||
* MiruroAPI — pipe.js
|
||||
* Repository: https://github.com/Shineii86/MiruroAPI
|
||||
*
|
||||
* @description
|
||||
* Miruro streaming pipe integration. Handles encoding/decoding
|
||||
* of the secure/pipe tunnel that Miruro uses for episode lists
|
||||
* and streaming sources. Decodes base64+gzip responses and
|
||||
* injects simplified slug-based episode IDs.
|
||||
*
|
||||
* @exports
|
||||
* getEpisodes, getSources, getWatchSources
|
||||
*
|
||||
* @author Shinei Nouzen
|
||||
* @license MIT
|
||||
* ======= • ======= • ======= • ======= • =======• =======
|
||||
*/
|
||||
|
||||
const axios = require("axios");
|
||||
const { Buffer } = require("buffer");
|
||||
const zlib = require("zlib");
|
||||
|
||||
// ══════════════════════════════════════════════════════════════
|
||||
// MIRURO PIPE CONFIGURATION
|
||||
// ══════════════════════════════════════════════════════════════
|
||||
|
||||
/**
|
||||
* Miruro's secure pipe endpoint URL.
|
||||
* All streaming requests go through this base64+gzip encoded tunnel.
|
||||
*
|
||||
* @type {string}
|
||||
*/
|
||||
const MIRURO_PIPE_URL = "https://www.miruro.tv/api/secure/pipe";
|
||||
|
||||
/**
|
||||
* Request headers mimicking a browser.
|
||||
* Referer is required for the pipe endpoint to accept requests.
|
||||
*
|
||||
* @type {object}
|
||||
*/
|
||||
const HEADERS = {
|
||||
"User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/137.0.0.0 Safari/537.36",
|
||||
Referer: "https://www.miruro.tv/",
|
||||
};
|
||||
|
||||
function encodePipeRequest(payload) {
|
||||
// ══════════════════════════════════════════════════════════════
|
||||
// ENCODING / DECODING UTILITIES
|
||||
// ══════════════════════════════════════════════════════════════
|
||||
|
||||
// ---- FEATURE: Base64url encode pipe request payload ----
|
||||
/**
|
||||
* Encodes a JSON payload into the base64url format expected by the pipe endpoint.
|
||||
* Used for all pipe API requests (episodes, sources).
|
||||
*
|
||||
* @param {object} payload - The request payload to encode
|
||||
* @returns {string} Base64url-encoded string (no padding)
|
||||
*
|
||||
* @example
|
||||
* const encoded = encodePipeRequest({ path: "episodes", method: "GET", query: { anilistId: 20 } });
|
||||
*/
|
||||
const encodePipeRequest = (payload) => {
|
||||
const json = JSON.stringify(payload);
|
||||
return Buffer.from(json).toString("base64url");
|
||||
}
|
||||
};
|
||||
|
||||
function decodePipeResponse(encodedStr) {
|
||||
// ---- FEATURE: Decode base64+gzip pipe response ----
|
||||
/**
|
||||
* Decodes a pipe response from base64url + gzip format into a plain object.
|
||||
* The Miruro pipe returns all responses in this compressed format.
|
||||
*
|
||||
* @param {string} encodedStr - The base64url-encoded gzipped response
|
||||
* @returns {object} Decoded JSON object
|
||||
* @throws {Error} If decoding or decompression fails
|
||||
*
|
||||
* @example
|
||||
* const data = decodePipeResponse(res.text);
|
||||
* console.log(data.providers); // { kiwi: {...}, bee: {...} }
|
||||
*/
|
||||
const decodePipeResponse = (encodedStr) => {
|
||||
try {
|
||||
// NOTE: Add padding if necessary (base64url may omit trailing =)
|
||||
const padded = encodedStr + "=".repeat((4 - (encodedStr.length % 4)) % 4);
|
||||
const compressed = Buffer.from(padded, "base64url");
|
||||
const decompressed = zlib.gunzipSync(compressed);
|
||||
@@ -22,20 +87,41 @@ function decodePipeResponse(encodedStr) {
|
||||
} catch (e) {
|
||||
throw new Error("Failed to decode pipe response: " + e.message);
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
function translateId(encodedId) {
|
||||
// ---- FEATURE: Decode base64 episode ID to plain text ----
|
||||
/**
|
||||
* Decodes a base64-encoded episode ID back to plain text.
|
||||
* Episode IDs from the pipe are base64-encoded with ":" separators.
|
||||
*
|
||||
* @param {string} encodedId - The base64url-encoded episode ID
|
||||
* @returns {string} Decoded plain text ID, or original if decoding fails
|
||||
*
|
||||
* @example
|
||||
* const decoded = translateId("YW5pbWVwaGU6MjA6c3ViOjE=");
|
||||
* // returns "animepahe:20:sub:1"
|
||||
*/
|
||||
const translateId = (encodedId) => {
|
||||
try {
|
||||
const padded = encodedId + "=".repeat((4 - (encodedId.length % 4)) % 4);
|
||||
const decoded = Buffer.from(padded, "base64url").toString("utf-8");
|
||||
// NOTE: Only return decoded value if it looks like a valid ID (contains ":")
|
||||
if (decoded.includes(":")) return decoded;
|
||||
return encodedId;
|
||||
} catch {
|
||||
return encodedId;
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
function deepTranslate(obj) {
|
||||
// ---- FEATURE: Recursively decode all base64 IDs in a nested object ----
|
||||
/**
|
||||
* Walks a JSON structure and decodes any base64 "id" fields.
|
||||
* Handles nested objects and arrays of objects.
|
||||
*
|
||||
* @param {object|Array} obj - The object or array to process
|
||||
* @returns {object|Array} The same object with decoded IDs (mutated in place)
|
||||
*/
|
||||
const deepTranslate = (obj) => {
|
||||
if (obj && typeof obj === "object") {
|
||||
for (const key of Object.keys(obj)) {
|
||||
if (key === "id" && typeof obj[key] === "string") {
|
||||
@@ -46,33 +132,73 @@ function deepTranslate(obj) {
|
||||
}
|
||||
}
|
||||
return obj;
|
||||
}
|
||||
};
|
||||
|
||||
function injectSourceSlugs(data, anilistId) {
|
||||
// ══════════════════════════════════════════════════════════════
|
||||
// EPISODE ID INJECTION
|
||||
// ══════════════════════════════════════════════════════════════
|
||||
|
||||
// ---- FEATURE: Transform episode IDs into simplified path-based slugs ----
|
||||
/**
|
||||
* Converts raw pipe episode IDs into clean slug format:
|
||||
* watch/{provider}/{anilistId}/{category}/{prefix}-{number}
|
||||
*
|
||||
* This makes episode IDs human-readable and URL-safe for the /watch endpoint.
|
||||
*
|
||||
* @param {object} data - Raw pipe response with providers
|
||||
* @param {number} anilistId - The AniList anime ID
|
||||
* @returns {object} Modified data with slug-based episode IDs
|
||||
*
|
||||
* @example
|
||||
* // Before: "animepahe:20:sub:1"
|
||||
* // After: "watch/kiwi/20/sub/animepahe-1"
|
||||
*/
|
||||
const injectSourceSlugs = (data, anilistId) => {
|
||||
const providers = data.providers || {};
|
||||
|
||||
for (const [provName, provData] of Object.entries(providers)) {
|
||||
if (!provData || typeof provData !== "object") continue;
|
||||
|
||||
let episodes = provData.episodes;
|
||||
if (!episodes) continue;
|
||||
|
||||
// NOTE: Some providers return a flat array — wrap it in { sub: [...] }
|
||||
if (Array.isArray(episodes)) {
|
||||
provData.episodes = { sub: episodes };
|
||||
episodes = provData.episodes;
|
||||
}
|
||||
|
||||
for (const [category, epList] of Object.entries(episodes)) {
|
||||
if (!Array.isArray(epList)) continue;
|
||||
|
||||
for (const ep of epList) {
|
||||
if (ep.id && ep.number) {
|
||||
const origId = ep.id;
|
||||
// NOTE: Take only the prefix before ":" for the slug
|
||||
const prefix = origId.includes(":") ? origId.split(":")[0] : origId;
|
||||
ep.id = `watch/${provName}/${anilistId}/${category}/${prefix}-${ep.number}`;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
return data;
|
||||
}
|
||||
|
||||
async function fetchRawEpisodes(anilistId) {
|
||||
return data;
|
||||
};
|
||||
|
||||
// ══════════════════════════════════════════════════════════════
|
||||
// PIPE API FUNCTIONS
|
||||
// ══════════════════════════════════════════════════════════════
|
||||
|
||||
// ---- FEATURE: Fetch raw decoded episode data from Miruro pipe ----
|
||||
/**
|
||||
* Internal helper to fetch and decode raw episode data from the pipe.
|
||||
* Sends a base64-encoded request and decodes the gzipped response.
|
||||
*
|
||||
* @param {number} anilistId - The AniList anime ID
|
||||
* @returns {Promise<object>} Decoded episode data with providers
|
||||
* @throws {Error} If the pipe request fails
|
||||
*/
|
||||
const fetchRawEpisodes = async (anilistId) => {
|
||||
const payload = {
|
||||
path: "episodes",
|
||||
method: "GET",
|
||||
@@ -80,29 +206,60 @@ async function fetchRawEpisodes(anilistId) {
|
||||
body: null,
|
||||
version: "0.1.0",
|
||||
};
|
||||
|
||||
const encodedReq = encodePipeRequest(payload);
|
||||
const res = await axios.get(`${MIRURO_PIPE_URL}?e=${encodedReq}`, {
|
||||
headers: HEADERS,
|
||||
timeout: 15000,
|
||||
});
|
||||
|
||||
if (res.status !== 200) throw new Error(`Pipe request failed: ${res.status}`);
|
||||
const data = decodePipeResponse(res.text || res.data);
|
||||
return deepTranslate(data);
|
||||
}
|
||||
};
|
||||
|
||||
async function getEpisodes(anilistId) {
|
||||
// ---- FEATURE: Get episodes with slug-based IDs ----
|
||||
/**
|
||||
* Fetches the full episode list for an anime from all providers.
|
||||
* Returns episodes with simplified slug-based IDs for the /watch endpoint.
|
||||
*
|
||||
* @param {number} anilistId - The AniList anime ID
|
||||
* @returns {Promise<object>} Episode data with providers and mappings
|
||||
*
|
||||
* @example
|
||||
* const episodes = await getEpisodes(20); // Naruto
|
||||
* console.log(Object.keys(episodes.providers)); // ["kiwi", "bee", "bonk", ...]
|
||||
*/
|
||||
const getEpisodes = async (anilistId) => {
|
||||
const data = await fetchRawEpisodes(anilistId);
|
||||
const result = injectSourceSlugs(data, anilistId);
|
||||
// Ensure mappings field is present (like Walter's API)
|
||||
|
||||
// NOTE: Ensure mappings field is present (like Walter's API)
|
||||
if (!result.mappings) {
|
||||
result.mappings = { anilistId };
|
||||
if (result.malId) result.mappings.malId = result.malId;
|
||||
if (result.kitsuId) result.mappings.kitsuId = result.kitsuId;
|
||||
}
|
||||
return result;
|
||||
}
|
||||
|
||||
async function getSources(episodeId, provider, anilistId, category = "sub") {
|
||||
return result;
|
||||
};
|
||||
|
||||
// ---- FEATURE: Get streaming sources (detailed endpoint) ----
|
||||
/**
|
||||
* Fetches M3U8 streaming sources for a specific episode.
|
||||
* This is the detailed/manual endpoint — use /watch for simpler access.
|
||||
*
|
||||
* @param {string} episodeId - The raw episode ID from the pipe
|
||||
* @param {string} provider - Provider name (e.g., "kiwi", "bee", "bonk")
|
||||
* @param {number} anilistId - The AniList anime ID
|
||||
* @param {string} [category="sub"] - Audio category ("sub" or "dub")
|
||||
* @returns {Promise<object>} Streaming sources with M3U8 URLs, subtitles, timestamps
|
||||
*
|
||||
* @example
|
||||
* const sources = await getSources("animepahe:20:sub:1", "kiwi", 20, "sub");
|
||||
* console.log(sources.streams[0].url); // "https://.../master.m3u8"
|
||||
*/
|
||||
const getSources = async (episodeId, provider, anilistId, category = "sub") => {
|
||||
const encId = Buffer.from(episodeId).toString("base64url");
|
||||
const payload = {
|
||||
path: "sources",
|
||||
@@ -111,33 +268,57 @@ async function getSources(episodeId, provider, anilistId, category = "sub") {
|
||||
body: null,
|
||||
version: "0.1.0",
|
||||
};
|
||||
|
||||
const encodedReq = encodePipeRequest(payload);
|
||||
const res = await axios.get(`${MIRURO_PIPE_URL}?e=${encodedReq}`, {
|
||||
headers: HEADERS,
|
||||
timeout: 15000,
|
||||
});
|
||||
|
||||
if (res.status !== 200) throw new Error(`Pipe sources request failed: ${res.status}`);
|
||||
return deepTranslate(decodePipeResponse(res.text || res.data));
|
||||
}
|
||||
};
|
||||
|
||||
async function getWatchSources(provider, anilistId, category, slug) {
|
||||
// ---- FEATURE: Get streaming sources (simple slug-based endpoint) ----
|
||||
/**
|
||||
* Resolves a slug-based episode ID and fetches its streaming sources.
|
||||
* This is the recommended endpoint — just pass the slug from /episodes.
|
||||
*
|
||||
* @param {string} provider - Provider name (e.g., "kiwi", "bee")
|
||||
* @param {number} anilistId - The AniList anime ID
|
||||
* @param {string} category - Audio category ("sub" or "dub")
|
||||
* @param {string} slug - Episode slug (e.g., "animepahe-1")
|
||||
* @returns {Promise<object>} Streaming sources with M3U8 URLs, subtitles, timestamps
|
||||
* @throws {Error} If provider or episode slug is not found
|
||||
*
|
||||
* @example
|
||||
* const sources = await getWatchSources("kiwi", 20, "sub", "animepahe-1");
|
||||
* console.log(sources.streams[0].url); // "https://.../master.m3u8"
|
||||
*/
|
||||
const getWatchSources = async (provider, anilistId, category, slug) => {
|
||||
const data = await fetchRawEpisodes(anilistId);
|
||||
const provData = (data.providers || {})[provider];
|
||||
|
||||
if (!provData) throw new Error(`Provider ${provider} not found`);
|
||||
|
||||
const episodes = provData.episodes?.[category] || [];
|
||||
let targetId = null;
|
||||
|
||||
// NOTE: Resolve slug back to the original pipe episode ID
|
||||
for (const ep of episodes) {
|
||||
const origId = ep.id || "";
|
||||
const prefix = origId.includes(":") ? origId.split(":")[0] : origId;
|
||||
const generated = `${prefix}-${ep.number}`;
|
||||
|
||||
if (generated === slug) {
|
||||
targetId = origId;
|
||||
break;
|
||||
}
|
||||
}
|
||||
|
||||
if (!targetId) throw new Error(`Episode slug '${slug}' not found for provider ${provider}`);
|
||||
return getSources(targetId, provider, anilistId, category);
|
||||
}
|
||||
};
|
||||
|
||||
module.exports = {
|
||||
getEpisodes,
|
||||
@@ -149,3 +330,5 @@ module.exports = {
|
||||
deepTranslate,
|
||||
injectSourceSlugs,
|
||||
};
|
||||
|
||||
// ══════════════════════════════════════════════════════════════ END: pipe.js
|
||||
|
||||
Reference in New Issue
Block a user