made sdk docs up to date

This commit is contained in:
2026-11-15 21:05:56 -08:00
parent 03d468cb8a
commit cd487cb189
5 changed files with 370 additions and 125 deletions

View File

@@ -1,30 +1,35 @@
# Contributing a Source Provider # Contributing a Source Provider
<p class="page-description">Technical guide for authoring, testing, and contributing a new video scraping resolver to the Vyla SDK.</p> <p class="page-description">Technical guide for authoring, testing, and registering a new video scraping resolver or embed entry in the Vyla SDK.</p>
## Overview ## 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 ## 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 ```typescript
export async function getStream(args: StreamArgs): Promise<StreamResult | { allUrls: StreamResult[] }> export async function getStream(args: StreamArgs): Promise<StreamResult | null>
``` ```
### Context Arguments (`args`) ### 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. - `id` *(string | number)* — TMDB numeric ID or string IMDb ID.
- `s` *(number | null)* — Season number for television series (or `null` for movies). - `s` *(number | null)* — Season number for television series (or `null` for movies).
- `e` *(number | null)* — Episode 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. - `clientIP` *(string | null)* — Client IP address forwarded for geo-token generation.
- `fetch` *(Function)* — Pre-configured fetch wrapper with timeout controls. - `absoluteBase` *(string | null)* — Base URL prefix when running behind a local proxy.
- `imdbId` *(string | null)* — Auto-resolved IMDb ID. - `audio` *('sub' | 'dub')* — Audio preference inferred from the source key.
- `title` *(string | null)* — Verified title string. - `sdk` *(VylaSDK)* — The active `VylaSDK` instance.
- `year` *(number | null)* — Media release year. - `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<StreamResult | { allU
Create a new file in `src/sources/<source_name>.js`: Create a new file in `src/sources/<source_name>.js`:
```javascript ```javascript
import { USER_AGENT } from '../utils/helpers.js';
const BASE_URL = 'https://provider-domain.example.com'; const BASE_URL = 'https://provider-domain.example.com';
const DEFAULT_HEADERS = { 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', 'User-Agent': USER_AGENT,
'Referer': `${BASE_URL}/`, Referer: `${BASE_URL}/`,
'Origin': 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 isTv = s != null && e != null;
const endpoint = isTv const endpoint = isTv
? `${BASE_URL}/api/tv/${id}/${s}/${e}` ? `${BASE_URL}/api/tv/${id}/${s}/${e}`
: `${BASE_URL}/api/movie/${id}`; : `${BASE_URL}/api/movie/${id}`;
const response = await fetch(endpoint, { try {
headers: DEFAULT_HEADERS const response = await fetch(endpoint, {
}); headers: DEFAULT_HEADERS,
signal: AbortSignal.timeout(config?.timeout || 15000)
});
if (!response.ok) { if (!response.ok) return null;
throw new Error(`Upstream returned HTTP ${response.status}`);
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` ### 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 ```javascript
{ {
@@ -86,25 +105,54 @@ Add the source configuration:
label: 'My Source', label: 'My Source',
sourceFile: 'mysource', sourceFile: 'mysource',
proxyParam: 'ms', proxyParam: 'ms',
timeout: 12000, timeout: 25000,
jitter: 400, jitter: 500,
retries: 1, retries: 2,
multiUrl: false, multiUrl: true,
skipProxy: false, dedicated: true,
skipVerify: false cdnHeaders: [{
pattern: /provider-domain\.example\.com/i,
headers: {
Referer: 'https://provider-domain.example.com/',
Origin: 'https://provider-domain.example.com',
},
}],
} }
``` ```
**Key Fields:** **Key Fields:**
- `key`: Lowercase identifier without spaces (e.g. `mysource`). - `key`: Lowercase identifier without spaces (e.g. `mysource`).
- `label`: Clean display label for client UIs. - `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. - `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). - `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: Run your scraper against known TMDB titles:
@@ -114,10 +162,10 @@ node test/index.js mysource 1396 1 1
``` ```
Verify that: Verify that:
1. A valid URL is returned. 1. A valid `url` and `allUrls` array are returned (or `null` when unavailable).
2. The format is correctly identified as `hls` or `mp4`. 2. The format `type` is correctly identified (`hls`, `dash`, `mp4`, or `mkv`).
3. Required upstream headers (`Referer`, `Origin`, `User-Agent`) are included. 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 hardcoded personal API keys or credentials.
- [ ] No untrusted `eval()` or un-sanitized script execution. - [ ] No untrusted `eval()` or un-sanitized script execution.
- [ ] Upstream stream candidate URLs are verified for playback. - [ ] 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.

View File

@@ -1,12 +1,12 @@
# Vyla SDK (`@vyla-entertainment/sdk`) # Vyla SDK (`@vyla-entertainment/sdk`)
<p class="page-description">The official Node.js scraping and resolver library for movies, television series, subtitles, downloads, and manga.</p> <p class="page-description">The official Node.js scraping and resolver library for movies, television series, embed configurations, subtitles, downloads, and manga.</p>
<img class="vyla-banner" src="/src/assets/images/devices.webp" alt="Vyla SDK developer tools" loading="lazy" decoding="async" fetchpriority="low" /> <img class="vyla-banner" src="/src/assets/images/devices.webp" alt="Vyla SDK developer tools" loading="lazy" decoding="async" fetchpriority="low" />
## Overview ## 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 ## 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()`. - **Subtitles**: Fetch `.vtt` and `.srt` subtitle tracks with `getSubtitles()`.
- **Downloads**: Find direct video files with file size metadata using `getDownloads()`. - **Downloads**: Find direct `.mp4` download links using `getDownloads()`.
- **Manga**: Search titles, list chapters, and fetch page images with `searchManga()` and `getMangaChapter()`. - **Manga**: Search titles, list chapters, and fetch page images with `searchManga()`, `getManga()`, and `getMangaChapter()`.
--- ---
@@ -35,21 +37,26 @@ npm install @vyla-entertainment/sdk
```javascript ```javascript
import VylaSDK from '@vyla-entertainment/sdk'; import VylaSDK from '@vyla-entertainment/sdk';
import EMBEDS from '@vyla-entertainment/sdk/src/embed_config.js';
const sdk = new VylaSDK({ const sdk = new VylaSDK({
tmdbApiKey: process.env.TMDB_API_KEY tmdbApiKey: process.env.TMDB_API_KEY
}); });
const sources = sdk.getSources(true); 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 { try {
const stream = await sdk.getStream('vidlink', 155); const stream = await sdk.getStream('vidlink', 155);
console.log(stream.url, stream.type); console.log(stream.url, stream.allUrls);
} catch (err) { } catch (err) {
console.error(err.message); 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); const subtitles = await sdk.getSubtitles(155);
console.log(`Subtitles found: ${subtitles.length}`); console.log(`Subtitles found: ${subtitles.length}`);
``` ```
@@ -58,7 +65,7 @@ console.log(`Subtitles found: ${subtitles.length}`);
## Documentation Sections ## Documentation Sections
- **[Quickstart](quickstart.md)** — Step-by-step tutorial for movies, TV episodes, and error handling. - **[Quickstart](quickstart.md)** — Step-by-step tutorial for movies, TV episodes, embeds, and error handling.
- **[API Reference](reference.md)** — Complete methods, arguments, return shapes, and TypeScript types. - **[API Reference](reference.md)** — Complete methods, config exports, return shapes, and TypeScript types.
- **[Manga Module](manga.md)** — Manga search, chapter indexes, and page loading. - **[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.

View File

@@ -34,8 +34,8 @@ const sdk = new VylaSDK();
const searchResult = await sdk.searchManga('Chainsaw Man', 1, 10); const searchResult = await sdk.searchManga('Chainsaw Man', 1, 10);
console.log(`Total results: ${searchResult.total}`); console.log(`Total results: ${searchResult.total}`);
searchResult.items.forEach((manga) => { searchResult.results.forEach((manga) => {
console.log(`[ID: ${manga.id}] ${manga.title} - ${manga.latestChapter}`); console.log(`[ID: ${manga.id}] ${manga.title} (${manga.status})`);
}); });
``` ```
@@ -43,15 +43,22 @@ searchResult.items.forEach((manga) => {
```json ```json
{ {
"page": 1, "page": 1,
"perPage": 10,
"total": 42, "total": 42,
"items": [ "results": [
{ {
"id": "chainsaw-man", "id": "chainsaw-man",
"title": "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", "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 ### 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 ```javascript
const mangaDetails = await sdk.getManga('chainsaw-man'); const mangaDetails = await sdk.getManga('chainsaw-man');
console.log('Title:', mangaDetails.title); console.log('Title:', mangaDetails.title);
console.log('Synopsis:', mangaDetails.description); console.log('Synopsis:', mangaDetails.synopsis);
console.log('Genres:', mangaDetails.genres.join(', ')); console.log('Genres:', mangaDetails.genres.join(', '));
console.log('Available Chapters:', mangaDetails.chapters.length); console.log('Available Chapters:', mangaDetails.chapters.length);
const latest = mangaDetails.chapters[0]; 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 mangaId = 'chainsaw-man';
const chapterId = 'chapter-1'; 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) => { chapter.pages.forEach((page) => {
console.log(`Page ${index + 1}: ${page.url} [${page.width}x${page.height}]`); console.log(`Page ${page.number}: ${page.url} [${page.width}x${page.height}]`);
}); });
``` ```
#### Page Object Structure #### Chapter Response Structure
```json ```json
{ {
"index": 1, "id": "chapter-1",
"url": "https://cdn.atsu.moe/data/.../01.webp", "number": 1,
"width": 1080, "title": "Dog & Chainsaw",
"height": 1600, "scanlatorId": null,
"aspectRatio": 0.675 "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. 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. 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.

View File

@@ -1,6 +1,6 @@
# Vyla SDK Quickstart # Vyla SDK Quickstart
<p class="page-description">Get up and running with the Vyla SDK in under five minutes. Learn how to resolve movies, television episodes, subtitles, and downloads.</p> <p class="page-description">Get up and running with the Vyla SDK in under five minutes. Learn how to resolve movies, television episodes, embed URLs, subtitles, and downloads.</p>
## Prerequisites ## Prerequisites
@@ -49,9 +49,8 @@ const tmdbId = 155;
try { try {
const result = await sdk.getStream(sourceKey, tmdbId); const result = await sdk.getStream(sourceKey, tmdbId);
console.log('Stream Candidate URL:', result.url); console.log('Stream Candidate URL:', result.url);
console.log('Container Type:', result.type); console.log('All Candidates:', result.allUrls.length);
console.log('Video Quality:', result.quality); console.log('Headers:', result.headers);
console.log('Upstream Server:', result.server);
} catch (error) { } catch (error) {
console.error(`Failed to resolve ${sourceKey}:`, error.message); 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: 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 { try {
const stream = await Promise.race([ const stream = await Promise.race([
sdk.getStream(cfg.key, tmdbId, s, e), sdk.getStream(cfg.key, tmdbId, s, e),
new Promise((_, reject) => new Promise((_, reject) =>
setTimeout(() => reject(new Error('Timeout')), cfg.timeout || 10000) setTimeout(() => reject(new Error('Timeout')), cfg.timeout || 10000)
) )
]); ]);
if (!stream?.url) return null;
return { source: cfg.key, label: cfg.label, stream }; return { source: cfg.key, label: cfg.label, stream };
} catch { } catch {
return null; 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 ```javascript
const [subtitles, downloads] = await Promise.all([ 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(`[${sub.type.toUpperCase()}] ${sub.label}: ${sub.file}`);
}); });
console.log('--- Download Packages ---'); console.log('--- Download Links ---');
downloads.forEach((dl) => { 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: 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)) { for (const [key, status] of Object.entries(healthReport)) {
const icon = status.ok ? 'OK' : 'FAIL'; 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 ## 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). - 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)

View File

@@ -1,6 +1,6 @@
# Vyla SDK API Reference # Vyla SDK API Reference
<p class="page-description">Technical reference for `@vyla-entertainment/sdk`: classes, methods, parameters, and TypeScript definitions.</p> <p class="page-description">Technical reference for `@vyla-entertainment/sdk`: classes, methods, config exports, parameters, and TypeScript definitions.</p>
## Class: `VylaSDK` ## Class: `VylaSDK`
@@ -20,7 +20,7 @@ constructor(options?: VylaSDKOptions)
**Parameters:** **Parameters:**
- `options.tmdbApiKey` *(string, optional)* — TMDB v3 API Key for metadata lookups. - `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 ```javascript
const sdk = new VylaSDK({ const sdk = new VylaSDK({
@@ -36,7 +36,7 @@ const sdk = new VylaSDK({
getSources(excludeDisabled?: boolean): SourceConfig[] getSources(excludeDisabled?: boolean): SourceConfig[]
``` ```
Returns registered provider scraper configurations. Returns registered provider scraper configurations from `SOURCES`.
**Parameters:** **Parameters:**
- `excludeDisabled` *(boolean, optional)* — When `true`, filters out scrapers with `disabled: true`. Default: `false`. - `excludeDisabled` *(boolean, optional)* — When `true`, filters out scrapers with `disabled: true`. Default: `false`.
@@ -45,7 +45,8 @@ Returns registered provider scraper configurations.
```javascript ```javascript
const activeSources = sdk.getSources(true); 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, s?: number | null,
e?: number | null, e?: number | null,
clientIP?: string | null clientIP?: string | null
): Promise<StreamResult | { allUrls: StreamResult[] }> ): Promise<StreamResponse | null>
``` ```
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:** **Parameters:**
- `key` *(string, required)* — Provider key (e.g. `'vidlink'`, `'vixsrc'`). - `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`. - `e` *(number, optional)* — Episode number (for TV series). Default: `null`.
- `clientIP` *(string, optional)* — Client IP address passed for upstream geo-token generation. 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 ```javascript
const movieStream = await sdk.getStream('vidlink', 155); const movieStream = await sdk.getStream('vidlink', 155);
@@ -90,7 +91,7 @@ async getSubtitles(
): Promise<SubtitleResult[]> ): Promise<SubtitleResult[]>
``` ```
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:** **Parameters:**
- `id` *(string | number, required)* — TMDB media ID. - `id` *(string | number, required)* — TMDB media ID.
@@ -111,7 +112,7 @@ async getDownloads(
): Promise<DownloadResult[]> ): Promise<DownloadResult[]>
``` ```
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. **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<ProbeResult> async probeSource(key: string): Promise<ProbeResult>
``` ```
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:** **Parameters:**
- `key` *(string, required)* — Provider key to probe. - `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<ProbeAllResult> async probeAllSources(): Promise<ProbeAllResult>
``` ```
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?)` #### `searchManga(query, page?, perPage?)`
```typescript ```typescript
async searchManga(query: string, page?: number, perPage?: number): Promise<any> async searchManga(query: string, page?: number, perPage?: number): Promise<MangaSearchResult>
``` ```
Queries the manga catalog via `atsu.moe` using Chrome 131 TLS fingerprinting. Queries the manga catalog via `atsu.moe` using Chrome 131 TLS fingerprinting.
#### `getManga(id)` #### `getManga(id)`
```typescript ```typescript
async getManga(id: string): Promise<any> async getManga(id: string): Promise<MangaDetails>
``` ```
Retrieves full manga details, author, genres, and chapter list. Retrieves full manga details, authors, genres, tags, and chapter list.
#### `getMangaChapter(mangaId, chapterId)` #### `getMangaChapter(mangaId, chapterId)`
```typescript ```typescript
async getMangaChapter(mangaId: string, chapterId: string): Promise<any> async getMangaChapter(mangaId: string, chapterId: string): Promise<MangaChapterPages>
``` ```
Resolves ordered image URLs and dimensions for all pages in a chapter. 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 ## TypeScript Interfaces
### `Interface: VylaSDKOptions`
```typescript
export interface VylaSDKOptions {
tmdbApiKey?: string | null;
penguManifest?: string | null;
}
```
### `Interface: SourceConfig` ### `Interface: SourceConfig`
```typescript ```typescript
@@ -177,38 +217,58 @@ export interface SourceConfig {
timeout: number; timeout: number;
jitter: number; jitter: number;
retries: number; retries: number;
multiUrl: boolean; multiUrl?: boolean;
dedicated?: boolean;
skipProxy?: boolean; skipProxy?: boolean;
skipVerify?: boolean; skipVerify?: boolean;
verifyHeaders?: boolean; verifyHeaders?: Record<string, string>;
disabled?: boolean; disabled?: boolean;
sourcesTimeout?: number; sourcesTimeout?: number;
cdnHeaders?: { cdnHeaders?: {
pattern: RegExp; pattern: RegExp;
headers: { headers: {
Referer: string; Referer?: string;
Origin: string; Origin?: string;
[key: string]: string | undefined;
}; };
}[]; }[];
} }
``` ```
### `Interface: StreamResult` ### `Interface: EmbedConfig`
```typescript ```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; url: string;
headers: { headers?: Record<string, string>;
"User-Agent": string;
Referer: string;
Origin: string;
[key: string]: string;
};
server: string; server: string;
quality: string; quality: string;
type: "mp4" | "hls"; type: "mp4" | "hls" | "dash" | "mkv" | string;
skipVerify?: boolean; label?: string;
skipProxy?: boolean; skipProxy?: boolean;
skipVerify?: boolean;
audio?: string;
}
export interface StreamResponse {
url: string;
headers?: Record<string, string>;
server?: string;
quality?: string;
type?: string;
allUrls: StreamCandidate[];
} }
``` ```
@@ -219,7 +279,7 @@ export interface SubtitleResult {
label: string; label: string;
file: string; file: string;
type: "vtt" | "srt"; type: "vtt" | "srt";
source: string; source: "v1" | "v2" | "opensubtitles" | "febbox" | string;
} }
``` ```
@@ -227,11 +287,9 @@ export interface SubtitleResult {
```typescript ```typescript
export interface DownloadResult { export interface DownloadResult {
source: string;
label: string;
url: string; url: string;
quality: string;
size: number | null;
type: "mkv";
active: boolean;
} }
``` ```
@@ -240,8 +298,78 @@ export interface DownloadResult {
```typescript ```typescript
export interface ProbeResult { export interface ProbeResult {
ok: boolean; ok: boolean;
movie?: boolean;
tv?: boolean;
ms: number | null; ms: number | null;
} }
export type ProbeAllResult = Record<string, ProbeResult>; export type ProbeAllResult = Record<string, ProbeResult>;
``` ```
### `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[];
}
```