diff --git a/sdk/vyla-sdk/contributing.md b/sdk/vyla-sdk/contributing.md index 15c7836..258632a 100644 --- a/sdk/vyla-sdk/contributing.md +++ b/sdk/vyla-sdk/contributing.md @@ -1,30 +1,35 @@ # Contributing a Source Provider -

Technical guide for authoring, testing, and contributing a new video scraping resolver to the Vyla SDK.

+

Technical guide for authoring, testing, and registering a new video scraping resolver or embed entry in the Vyla SDK.

## Overview -The Vyla SDK uses independent provider scrapers located in `src/sources/`. We welcome contributions that expand coverage for movies and television series. +The Vyla SDK uses independent provider scrapers located in `src/sources/` and embed player templates in `src/embed_config.js`. We welcome contributions that expand coverage for movies and television series. --- ## Scraper Contract -Every provider module is an ES Module exporting a single function: +Every provider module is an ES Module exporting a `getStream` function: ```typescript -export async function getStream(args: StreamArgs): Promise +export async function getStream(args: StreamArgs): Promise ``` ### Context Arguments (`args`) +`createStreamArgs()` in `src/utils/helpers.js` passes the following properties to `getStream`: + - `id` *(string | number)* — TMDB numeric ID or string IMDb ID. - `s` *(number | null)* — Season number for television series (or `null` for movies). - `e` *(number | null)* — Episode number for television series (or `null` for movies). - `clientIP` *(string | null)* — Client IP address forwarded for geo-token generation. -- `fetch` *(Function)* — Pre-configured fetch wrapper with timeout controls. -- `imdbId` *(string | null)* — Auto-resolved IMDb ID. -- `title` *(string | null)* — Verified title string. -- `year` *(number | null)* — Media release year. +- `absoluteBase` *(string | null)* — Base URL prefix when running behind a local proxy. +- `audio` *('sub' | 'dub')* — Audio preference inferred from the source key. +- `sdk` *(VylaSDK)* — The active `VylaSDK` instance. +- `config` *(SourceConfig)* — The matching entry from `src/config.js`. +- `tmdbApiKey` *(string)* — Resolved TMDB API key. + +If your source needs title, year, or IMDb ID metadata, call `getTmdbMetadata(id, isTv, tmdbApiKey)` or `resolveImdbId(id, isTv, tmdbApiKey)` from `../utils/helpers.js`. --- @@ -34,43 +39,57 @@ export async function getStream(args: StreamArgs): Promise.js`: ```javascript +import { USER_AGENT } from '../utils/helpers.js'; + const BASE_URL = 'https://provider-domain.example.com'; const DEFAULT_HEADERS = { - 'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36', - 'Referer': `${BASE_URL}/`, - 'Origin': BASE_URL + 'User-Agent': USER_AGENT, + Referer: `${BASE_URL}/`, + Origin: BASE_URL }; -export async function getStream({ id, s, e, imdbId }) { +export async function getStream(args) { + const { id, s, e, config } = args || {}; + if (!id) return null; + const isTv = s != null && e != null; const endpoint = isTv ? `${BASE_URL}/api/tv/${id}/${s}/${e}` : `${BASE_URL}/api/movie/${id}`; - const response = await fetch(endpoint, { - headers: DEFAULT_HEADERS - }); + try { + const response = await fetch(endpoint, { + headers: DEFAULT_HEADERS, + signal: AbortSignal.timeout(config?.timeout || 15000) + }); - if (!response.ok) { - throw new Error(`Upstream returned HTTP ${response.status}`); + if (!response.ok) return null; + + const data = await response.json(); + if (!data?.streamUrl) return null; + + const allUrls = [ + { + url: data.streamUrl, + headers: { + ...DEFAULT_HEADERS, + Referer: data.referer || DEFAULT_HEADERS.Referer + }, + server: 'MySource - Primary', + quality: data.quality || '1080p', + type: data.streamUrl.includes('.m3u8') ? 'hls' : 'mp4' + } + ]; + + return { + url: allUrls[0].url, + headers: allUrls[0].headers, + allUrls + }; + } catch { + return null; } - - const data = await response.json(); - if (!data.streamUrl) { - throw new Error('No stream found in upstream response'); - } - - return { - url: data.streamUrl, - headers: { - ...DEFAULT_HEADERS, - 'Referer': data.referer || DEFAULT_HEADERS.Referer - }, - server: 'MySource-Primary', - quality: data.quality || '1080p', - type: data.streamUrl.includes('.m3u8') ? 'hls' : 'mp4' - }; } ``` @@ -78,7 +97,7 @@ export async function getStream({ id, s, e, imdbId }) { ### 2. Register in `src/config.js` -Add the source configuration: +Add the source configuration object to `SOURCES`. Set `dedicated: true` if the source is a single-host/dedicated catalog rather than a multi-provider aggregator: ```javascript { @@ -86,25 +105,54 @@ Add the source configuration: label: 'My Source', sourceFile: 'mysource', proxyParam: 'ms', - timeout: 12000, - jitter: 400, - retries: 1, - multiUrl: false, - skipProxy: false, - skipVerify: false + timeout: 25000, + jitter: 500, + retries: 2, + multiUrl: true, + dedicated: true, + cdnHeaders: [{ + pattern: /provider-domain\.example\.com/i, + headers: { + Referer: 'https://provider-domain.example.com/', + Origin: 'https://provider-domain.example.com', + }, + }], } ``` **Key Fields:** - `key`: Lowercase identifier without spaces (e.g. `mysource`). - `label`: Clean display label for client UIs. +- `sourceFile`: Filename inside `src/sources/` (without `.js`). - `proxyParam`: Unique 2-to-4 character query flag for the HLS proxy. -- `timeout`: Maximum execution budget in ms (typically 8,000–15,000). +- `timeout`: Maximum execution budget in ms (typically 20,000–35,000). - `jitter`: Random delay ceiling in ms (typically 300–500). +- `retries`: Number of retry attempts during health probing. +- `multiUrl`: Whether the source returns multiple stream candidates in `allUrls`. +- `dedicated`: Set to `true` for dedicated single-host sources; omit or set `false` for aggregators. +- `disabled`: Optional boolean to exclude the source from active loading and probing. --- -### 3. Local Testing +### 3. Register an Embed Player in `src/embed_config.js` (Optional) + +If the provider offers a standalone iframe embed player, add an entry to `EMBEDS` in `src/embed_config.js` using `{id}`, `{s}`, and `{e}` placeholders: + +```javascript +{ + key: 'mysource', + label: 'My Source', + movie: 'https://provider-domain.example.com/embed/movie/{id}', + tv: 'https://provider-domain.example.com/embed/tv/{id}/{s}/{e}', + ads: false, +} +``` + +Set `ads: false` only when the embed is verified ad-free. + +--- + +### 4. Local Testing Run your scraper against known TMDB titles: @@ -114,10 +162,10 @@ node test/index.js mysource 1396 1 1 ``` Verify that: -1. A valid URL is returned. -2. The format is correctly identified as `hls` or `mp4`. +1. A valid `url` and `allUrls` array are returned (or `null` when unavailable). +2. The format `type` is correctly identified (`hls`, `dash`, `mp4`, or `mkv`). 3. Required upstream headers (`Referer`, `Origin`, `User-Agent`) are included. -4. An invalid ID throws a clean error without crashing. +4. Invalid IDs or network timeouts return `null` cleanly without throwing uncaught exceptions. --- @@ -127,4 +175,4 @@ Verify that: - [ ] No hardcoded personal API keys or credentials. - [ ] No untrusted `eval()` or un-sanitized script execution. - [ ] Upstream stream candidate URLs are verified for playback. -- [ ] Descriptive errors are thrown with `throw new Error(...)`. +- [ ] Timeouts (`AbortSignal.timeout`) are applied to all network requests. \ No newline at end of file diff --git a/sdk/vyla-sdk/index.md b/sdk/vyla-sdk/index.md index b97a061..6fd04e0 100644 --- a/sdk/vyla-sdk/index.md +++ b/sdk/vyla-sdk/index.md @@ -1,12 +1,12 @@ # Vyla SDK (`@vyla-entertainment/sdk`) -

The official Node.js scraping and resolver library for movies, television series, subtitles, downloads, and manga.

+

The official Node.js scraping and resolver library for movies, television series, embed configurations, subtitles, downloads, and manga.

Vyla SDK developer tools ## Overview -`@vyla-entertainment/sdk` is the core media resolver engine for Vyla. It runs in Node.js (ES Modules) to query 60+ streaming scrapers, extract subtitles, find media downloads, and browse manga archives. +`@vyla-entertainment/sdk` is the core media resolver engine for Vyla. It runs in Node.js (ES Modules) to query 65+ streaming scrapers, expose dedicated vs. aggregator source lists, provide pre-configured embed player URL templates, extract subtitles, find media downloads, and browse manga archives. --- @@ -24,10 +24,12 @@ npm install @vyla-entertainment/sdk ## Capabilities -- **Streaming**: Resolve direct MP4 and adaptive HLS (`.m3u8`) links with `getStream()`, `getSources()`, and `probeSource()`. +- **Streaming**: Resolve direct MP4, MKV, DASH (`.mpd`), and adaptive HLS (`.m3u8`) links with `getStream()`, `getSources()`, and `probeSource()`. +- **Source Categorization**: Separate single-host providers (`DEDICATED_SOURCES`) from multi-provider scrapers (`AGGREGATOR_SOURCES`) via `config.js`. +- **Embed Configuration**: Pre-mapped movie and TV embed URL templates with `ads: false` tagging in `embed_config.js` (`EMBEDS` / `EMBED_MAP`). - **Subtitles**: Fetch `.vtt` and `.srt` subtitle tracks with `getSubtitles()`. -- **Downloads**: Find direct video files with file size metadata using `getDownloads()`. -- **Manga**: Search titles, list chapters, and fetch page images with `searchManga()` and `getMangaChapter()`. +- **Downloads**: Find direct `.mp4` download links using `getDownloads()`. +- **Manga**: Search titles, list chapters, and fetch page images with `searchManga()`, `getManga()`, and `getMangaChapter()`. --- @@ -35,21 +37,26 @@ npm install @vyla-entertainment/sdk ```javascript import VylaSDK from '@vyla-entertainment/sdk'; +import EMBEDS from '@vyla-entertainment/sdk/src/embed_config.js'; const sdk = new VylaSDK({ tmdbApiKey: process.env.TMDB_API_KEY }); const sources = sdk.getSources(true); -console.log(`Active sources: ${sources.length}`); +const dedicated = sources.filter(s => s.dedicated); +console.log(`Active sources: ${sources.length} (${dedicated.length} dedicated)`); try { const stream = await sdk.getStream('vidlink', 155); - console.log(stream.url, stream.type); + console.log(stream.url, stream.allUrls); } catch (err) { console.error(err.message); } +const adFreeEmbeds = EMBEDS.filter(e => e.ads === false); +console.log(`Ad-free embeds: ${adFreeEmbeds.length}`); + const subtitles = await sdk.getSubtitles(155); console.log(`Subtitles found: ${subtitles.length}`); ``` @@ -58,7 +65,7 @@ console.log(`Subtitles found: ${subtitles.length}`); ## Documentation Sections -- **[Quickstart](quickstart.md)** — Step-by-step tutorial for movies, TV episodes, and error handling. -- **[API Reference](reference.md)** — Complete methods, arguments, return shapes, and TypeScript types. +- **[Quickstart](quickstart.md)** — Step-by-step tutorial for movies, TV episodes, embeds, and error handling. +- **[API Reference](reference.md)** — Complete methods, config exports, return shapes, and TypeScript types. - **[Manga Module](manga.md)** — Manga search, chapter indexes, and page loading. -- **[Contributing Scrapers](contributing.md)** — How to write and test new source scrapers. +- **[Contributing Scrapers](contributing.md)** — How to write and register new source and embed scrapers. \ No newline at end of file diff --git a/sdk/vyla-sdk/manga.md b/sdk/vyla-sdk/manga.md index 2ada00b..ce9c923 100644 --- a/sdk/vyla-sdk/manga.md +++ b/sdk/vyla-sdk/manga.md @@ -34,8 +34,8 @@ const sdk = new VylaSDK(); const searchResult = await sdk.searchManga('Chainsaw Man', 1, 10); console.log(`Total results: ${searchResult.total}`); -searchResult.items.forEach((manga) => { - console.log(`[ID: ${manga.id}] ${manga.title} - ${manga.latestChapter}`); +searchResult.results.forEach((manga) => { + console.log(`[ID: ${manga.id}] ${manga.title} (${manga.status})`); }); ``` @@ -43,15 +43,22 @@ searchResult.items.forEach((manga) => { ```json { "page": 1, - "perPage": 10, "total": 42, - "items": [ + "results": [ { "id": "chainsaw-man", "title": "Chainsaw Man", - "cover": "https://cdn.atsu.moe/covers/chainsaw-man.webp", + "englishTitle": "Chainsaw Man", + "authors": ["Tatsuki Fujimoto"], + "type": "Manga", + "medium": "MANGA", "status": "Ongoing", - "latestChapter": "Chapter 180" + "year": 2018, + "rating": 8.7, + "popularity": 120000, + "poster": "https://cdn.atsu.moe/static/covers/chainsaw-man.webp", + "posterSmall": "https://cdn.atsu.moe/static/covers/chainsaw-man-sm.webp", + "posterMedium": "https://cdn.atsu.moe/static/covers/chainsaw-man-md.webp" } ] } @@ -61,18 +68,18 @@ searchResult.items.forEach((manga) => { ### 2. Fetching Manga Details & Chapters -Retrieve full metadata, descriptions, genres, and the complete chapter index: +Retrieve full metadata, synopsis, genres, and the complete chapter index: ```javascript const mangaDetails = await sdk.getManga('chainsaw-man'); console.log('Title:', mangaDetails.title); -console.log('Synopsis:', mangaDetails.description); +console.log('Synopsis:', mangaDetails.synopsis); console.log('Genres:', mangaDetails.genres.join(', ')); console.log('Available Chapters:', mangaDetails.chapters.length); const latest = mangaDetails.chapters[0]; -console.log(`Latest Chapter: ${latest.chapterNumber} (ID: ${latest.id})`); +console.log(`Latest Chapter: ${latest.number} (ID: ${latest.id})`); ``` --- @@ -85,23 +92,31 @@ To render the reader view, fetch the ordered page image assets for a specific ch const mangaId = 'chainsaw-man'; const chapterId = 'chapter-1'; -const pages = await sdk.getMangaChapter(mangaId, chapterId); +const chapter = await sdk.getMangaChapter(mangaId, chapterId); -console.log(`Chapter contains ${pages.length} pages.`); +console.log(`Chapter ${chapter.number} contains ${chapter.pages.length} pages.`); -pages.forEach((page, index) => { - console.log(`Page ${index + 1}: ${page.url} [${page.width}x${page.height}]`); +chapter.pages.forEach((page) => { + console.log(`Page ${page.number}: ${page.url} [${page.width}x${page.height}]`); }); ``` -#### Page Object Structure +#### Chapter Response Structure ```json { - "index": 1, - "url": "https://cdn.atsu.moe/data/.../01.webp", - "width": 1080, - "height": 1600, - "aspectRatio": 0.675 + "id": "chapter-1", + "number": 1, + "title": "Dog & Chainsaw", + "scanlatorId": null, + "pages": [ + { + "number": 1, + "url": "https://cdn.atsu.moe/static/data/.../01.webp", + "width": 1080, + "height": 1600, + "aspectRatio": 0.675 + } + ] } ``` @@ -113,4 +128,4 @@ When rendering manga pages in a frontend reader: 1. **Prevent Cumulative Layout Shift (CLS)**: Use the provided `aspectRatio` or `width`/`height` in CSS (`aspect-ratio: attr(width) / attr(height);`) to reserve vertical scroll space before each image finishes downloading. 2. **Preload Neighboring Pages**: Implement a 2-page lookahead preloader so viewers turning pages experience instantaneous transitions. -3. **Session Cleanup**: In long-running background tasks, invoke `cleanup()` from the module when closing reader sessions to terminate idle TLS sockets. +3. **Session Cleanup**: In long-running background tasks, invoke `cleanup()` from `src/manga/atsu.js` when closing reader sessions to terminate idle TLS sockets. \ No newline at end of file diff --git a/sdk/vyla-sdk/quickstart.md b/sdk/vyla-sdk/quickstart.md index 924037d..8bd7bf3 100644 --- a/sdk/vyla-sdk/quickstart.md +++ b/sdk/vyla-sdk/quickstart.md @@ -1,6 +1,6 @@ # Vyla SDK Quickstart -

Get up and running with the Vyla SDK in under five minutes. Learn how to resolve movies, television episodes, subtitles, and downloads.

+

Get up and running with the Vyla SDK in under five minutes. Learn how to resolve movies, television episodes, embed URLs, subtitles, and downloads.

## Prerequisites @@ -49,9 +49,8 @@ const tmdbId = 155; try { const result = await sdk.getStream(sourceKey, tmdbId); console.log('Stream Candidate URL:', result.url); - console.log('Container Type:', result.type); - console.log('Video Quality:', result.quality); - console.log('Upstream Server:', result.server); + console.log('All Candidates:', result.allUrls.length); + console.log('Headers:', result.headers); } catch (error) { console.error(`Failed to resolve ${sourceKey}:`, error.message); } @@ -78,7 +77,24 @@ try { --- -## 4. Multi-Source Concurrent Resolution with Fallbacks +## 4. Filtering Dedicated vs. Aggregator Sources + +Sources in `config.js` mark single-host/dedicated providers with `dedicated: true`, while multi-provider aggregators omit it: + +```javascript +import { DEDICATED_SOURCES, AGGREGATOR_SOURCES } from '@vyla-entertainment/sdk/src/config.js'; + +const activeSources = sdk.getSources(true); +const dedicatedActive = activeSources.filter(cfg => cfg.dedicated); +const aggregatorActive = activeSources.filter(cfg => !cfg.dedicated); + +console.log(`Dedicated: ${DEDICATED_SOURCES.length}, Aggregators: ${AGGREGATOR_SOURCES.length}`); +console.log(`Active Dedicated: ${dedicatedActive.length}, Active Aggregators: ${aggregatorActive.length}`); +``` + +--- + +## 5. Multi-Source Concurrent Resolution with Fallbacks In production, you should query multiple active providers concurrently and select the fastest viable stream: @@ -90,10 +106,11 @@ async function resolveFastestStream(tmdbId, s = null, e = null) { try { const stream = await Promise.race([ sdk.getStream(cfg.key, tmdbId, s, e), - new Promise((_, reject) => + new Promise((_, reject) => setTimeout(() => reject(new Error('Timeout')), cfg.timeout || 10000) ) ]); + if (!stream?.url) return null; return { source: cfg.key, label: cfg.label, stream }; } catch { return null; @@ -117,9 +134,39 @@ console.log('Primary Source:', sources[0].label, sources[0].stream.url); --- -## 5. Fetching Subtitles and Downloads +## 6. Using Embed Player Configurations -Subtitles and direct download links can be fetched in parallel: +Use `EMBEDS` or `EMBED_MAP` from `embed_config.js` to build iframe player URLs for movies and TV episodes, and filter by `ads === false` when you only want ad-free embeds: + +```javascript +import EMBEDS, { EMBED_MAP } from '@vyla-entertainment/sdk/src/embed_config.js'; + +const adFreeEmbeds = EMBEDS.filter(embed => embed.ads === false); +console.log('Ad-free embeds:', adFreeEmbeds.map(e => e.label).join(', ')); + +function buildEmbedUrl(key, tmdbId, season = null, episode = null) { + const cfg = EMBED_MAP[key]; + if (!cfg) return null; + + if (season != null && episode != null) { + return cfg.tv + .replace('{id}', encodeURIComponent(tmdbId)) + .replace('{s}', encodeURIComponent(season)) + .replace('{e}', encodeURIComponent(episode)); + } + + return cfg.movie.replace('{id}', encodeURIComponent(tmdbId)); +} + +console.log('Movie Embed:', buildEmbedUrl('cinezo', 155)); +console.log('TV Embed:', buildEmbedUrl('cinesrc', 1396, 1, 1)); +``` + +--- + +## 7. Fetching Subtitles and Downloads + +Subtitles and direct MP4 download links can be fetched in parallel: ```javascript const [subtitles, downloads] = await Promise.all([ @@ -132,15 +179,15 @@ subtitles.slice(0, 5).forEach((sub) => { console.log(`[${sub.type.toUpperCase()}] ${sub.label}: ${sub.file}`); }); -console.log('--- Download Packages ---'); +console.log('--- Download Links ---'); downloads.forEach((dl) => { - console.log(`[${dl.quality}] Size: ${dl.size ? (dl.size / (1024**3)).toFixed(2) + ' GB' : 'Unknown'} -> ${dl.url}`); + console.log(`[${dl.source}] ${dl.label} -> ${dl.url}`); }); ``` --- -## 6. Live Source Health Probing +## 8. Live Source Health Probing To check which providers are operational in your network environment: @@ -149,7 +196,7 @@ const healthReport = await sdk.probeAllSources(); for (const [key, status] of Object.entries(healthReport)) { const icon = status.ok ? 'OK' : 'FAIL'; - console.log(`[${icon}] ${key}: ${status.ok ? status.ms + 'ms' : 'offline'}`); + console.log(`[${icon}] ${key}: ${status.ok ? `${status.ms}ms (movie=${status.movie}, tv=${status.tv})` : 'offline'}`); } ``` @@ -157,6 +204,6 @@ for (const [key, status] of Object.entries(healthReport)) { ## Next Steps -- Consult the [Complete API Reference](reference.md) for exhaustive class and method parameters. +- Consult the [Complete API Reference](reference.md) for exhaustive class, config, and method parameters. - Learn how to integrate manga reading with the [Manga SDK Guide](manga.md). -- Deploy an HTTP/SSE bridge with the [Stream API Guide](../../stream-api/overview/index.md). +- Deploy an HTTP/SSE bridge with the [Stream API Guide](../../stream-api/overview) \ No newline at end of file diff --git a/sdk/vyla-sdk/reference.md b/sdk/vyla-sdk/reference.md index 9c411e1..3619066 100644 --- a/sdk/vyla-sdk/reference.md +++ b/sdk/vyla-sdk/reference.md @@ -1,6 +1,6 @@ # Vyla SDK API Reference -

Technical reference for `@vyla-entertainment/sdk`: classes, methods, parameters, and TypeScript definitions.

+

Technical reference for `@vyla-entertainment/sdk`: classes, methods, config exports, parameters, and TypeScript definitions.

## Class: `VylaSDK` @@ -20,7 +20,7 @@ constructor(options?: VylaSDKOptions) **Parameters:** - `options.tmdbApiKey` *(string, optional)* — TMDB v3 API Key for metadata lookups. -- `options.penguManifest` *(any, optional)* — Custom manifest for the Pengu provider source. +- `options.penguManifest` *(string, optional)* — Custom Stremio manifest URL for the Pengu provider source. ```javascript const sdk = new VylaSDK({ @@ -36,7 +36,7 @@ const sdk = new VylaSDK({ getSources(excludeDisabled?: boolean): SourceConfig[] ``` -Returns registered provider scraper configurations. +Returns registered provider scraper configurations from `SOURCES`. **Parameters:** - `excludeDisabled` *(boolean, optional)* — When `true`, filters out scrapers with `disabled: true`. Default: `false`. @@ -45,7 +45,8 @@ Returns registered provider scraper configurations. ```javascript const activeSources = sdk.getSources(true); -console.log(activeSources.map(s => s.key).join(', ')); +const dedicatedActive = activeSources.filter(s => s.dedicated); +const aggregatorActive = activeSources.filter(s => !s.dedicated); ``` --- @@ -59,10 +60,10 @@ async getStream( s?: number | null, e?: number | null, clientIP?: string | null -): Promise +): Promise ``` -Executes a provider scraper module to resolve candidate stream URLs. +Executes a provider scraper module to resolve candidate stream URLs. Any `subtitles` field on the raw source response is stripped; use `getSubtitles()` for subtitle tracks. **Parameters:** - `key` *(string, required)* — Provider key (e.g. `'vidlink'`, `'vixsrc'`). @@ -71,7 +72,7 @@ Executes a provider scraper module to resolve candidate stream URLs. - `e` *(number, optional)* — Episode number (for TV series). Default: `null`. - `clientIP` *(string, optional)* — Client IP address passed for upstream geo-token generation. Default: `null`. -**Returns:** A Promise resolving to a [`StreamResult`](#interface-streamresult) object. +**Returns:** A Promise resolving to a [`StreamResponse`](#interface-streamresponse) object or `null`. ```javascript const movieStream = await sdk.getStream('vidlink', 155); @@ -90,7 +91,7 @@ async getSubtitles( ): Promise ``` -Retrieves parsed subtitle tracks for a movie or TV episode. +Retrieves subtitle tracks from configured subtitle providers (`sub.vdrk.site` and `opensubtitles-v3.strem.io`) for a movie or TV episode. **Parameters:** - `id` *(string | number, required)* — TMDB media ID. @@ -111,7 +112,7 @@ async getDownloads( ): Promise ``` -Resolves direct media download packages and torrent/debrid links. +Resolves direct `.mp4` download URLs from active sources configured with `skipProxy: true`, deduplicated by URL. **Returns:** Array of [`DownloadResult`](#interface-downloadresult) objects. @@ -123,12 +124,12 @@ Resolves direct media download packages and torrent/debrid links. async probeSource(key: string): Promise ``` -Sends a probe request against a single provider to check responsiveness. +Probes a single provider against a test movie (`936075`) and TV episode (`37854` S01E01) to check responsiveness. **Parameters:** - `key` *(string, required)* — Provider key to probe. -**Returns:** `{ ok: boolean, ms: number | null }`. +**Returns:** `{ ok: boolean, movie: boolean, tv: boolean, ms: number | null }`. --- @@ -138,7 +139,7 @@ Sends a probe request against a single provider to check responsiveness. async probeAllSources(): Promise ``` -Concurrently probes all active sources and returns a health map. +Concurrently probes all active (non-disabled) sources and returns a health map keyed by source `key`. --- @@ -146,26 +147,65 @@ Concurrently probes all active sources and returns a health map. #### `searchManga(query, page?, perPage?)` ```typescript -async searchManga(query: string, page?: number, perPage?: number): Promise +async searchManga(query: string, page?: number, perPage?: number): Promise ``` Queries the manga catalog via `atsu.moe` using Chrome 131 TLS fingerprinting. #### `getManga(id)` ```typescript -async getManga(id: string): Promise +async getManga(id: string): Promise ``` -Retrieves full manga details, author, genres, and chapter list. +Retrieves full manga details, authors, genres, tags, and chapter list. #### `getMangaChapter(mangaId, chapterId)` ```typescript -async getMangaChapter(mangaId: string, chapterId: string): Promise +async getMangaChapter(mangaId: string, chapterId: string): Promise ``` Resolves ordered image URLs and dimensions for all pages in a chapter. --- +## Config & Embed Exports + +### `src/config.js` + +```javascript +import SOURCES, { + SOURCE_MAP, + DEDICATED_SOURCES, + AGGREGATOR_SOURCES, + HEALTH_PROBE_ID +} from '@vyla-entertainment/sdk/src/config.js'; +``` + +- `SOURCES` (`default`) — Full array of [`SourceConfig`](#interface-sourceconfig) objects. +- `SOURCE_MAP` — Lookup object mapping `source.key` to its `SourceConfig`. +- `DEDICATED_SOURCES` — Filtered array of entries where `dedicated` is truthy. +- `AGGREGATOR_SOURCES` — Filtered array of entries where `dedicated` is falsy/omitted. +- `HEALTH_PROBE_ID` — Default TMDB probe ID (`'155'`). + +### `src/embed_config.js` + +```javascript +import EMBEDS, { EMBED_MAP } from '@vyla-entertainment/sdk/src/embed_config.js'; +``` + +- `EMBEDS` (`default`) — Array of [`EmbedConfig`](#interface-embedconfig) objects containing movie and TV URL templates (`{id}`, `{s}`, `{e}`). +- `EMBED_MAP` — Lookup object mapping `embed.key` to its `EmbedConfig`. + +--- + ## TypeScript Interfaces +### `Interface: VylaSDKOptions` + +```typescript +export interface VylaSDKOptions { + tmdbApiKey?: string | null; + penguManifest?: string | null; +} +``` + ### `Interface: SourceConfig` ```typescript @@ -177,38 +217,58 @@ export interface SourceConfig { timeout: number; jitter: number; retries: number; - multiUrl: boolean; + multiUrl?: boolean; + dedicated?: boolean; skipProxy?: boolean; skipVerify?: boolean; - verifyHeaders?: boolean; + verifyHeaders?: Record; disabled?: boolean; sourcesTimeout?: number; cdnHeaders?: { pattern: RegExp; headers: { - Referer: string; - Origin: string; + Referer?: string; + Origin?: string; + [key: string]: string | undefined; }; }[]; } ``` -### `Interface: StreamResult` +### `Interface: EmbedConfig` ```typescript -export interface StreamResult { +export interface EmbedConfig { + key: string; + label: string; + movie: string; + tv: string; + ads?: boolean; +} +``` + +### `Interface: StreamCandidate` & `StreamResponse` + +```typescript +export interface StreamCandidate { url: string; - headers: { - "User-Agent": string; - Referer: string; - Origin: string; - [key: string]: string; - }; + headers?: Record; server: string; quality: string; - type: "mp4" | "hls"; - skipVerify?: boolean; + type: "mp4" | "hls" | "dash" | "mkv" | string; + label?: string; skipProxy?: boolean; + skipVerify?: boolean; + audio?: string; +} + +export interface StreamResponse { + url: string; + headers?: Record; + server?: string; + quality?: string; + type?: string; + allUrls: StreamCandidate[]; } ``` @@ -219,7 +279,7 @@ export interface SubtitleResult { label: string; file: string; type: "vtt" | "srt"; - source: string; + source: "v1" | "v2" | "opensubtitles" | "febbox" | string; } ``` @@ -227,11 +287,9 @@ export interface SubtitleResult { ```typescript export interface DownloadResult { + source: string; + label: string; url: string; - quality: string; - size: number | null; - type: "mkv"; - active: boolean; } ``` @@ -240,8 +298,78 @@ export interface DownloadResult { ```typescript export interface ProbeResult { ok: boolean; + movie?: boolean; + tv?: boolean; ms: number | null; } export type ProbeAllResult = Record; ``` + +### `Interfaces: Manga` + +```typescript +export interface MangaSearchItem { + id: string; + title: string; + englishTitle: string | null; + authors: string[]; + type: string; + medium: string; + status: string; + year: number | null; + rating: number | null; + popularity: number | null; + poster: string | null; + posterSmall: string | null; + posterMedium: string | null; +} + +export interface MangaSearchResult { + page: number; + total: number; + results: MangaSearchItem[]; +} + +export interface MangaChapterSummary { + id: string; + number: number; + title: string; + pageCount: number; + createdAt: string | null; +} + +export interface MangaDetails { + id: string; + title: string; + englishTitle: string | null; + synopsis: string | null; + status: string; + type: string; + medium: string; + rating: number | null; + views: number | null; + authors: string[]; + genres: string[]; + tags: string[]; + poster: string | null; + totalChapters: number; + chapters: MangaChapterSummary[]; +} + +export interface MangaPage { + number: number; + url: string | null; + width: number; + height: number; + aspectRatio: number; +} + +export interface MangaChapterPages { + id: string; + number: number; + title: string; + scanlatorId: string | null; + pages: MangaPage[]; +} +``` \ No newline at end of file