mirror of
https://gitlab.com/vyla-entertainment/documentation.git
synced 2026-11-16 15:37:23 -05:00
375 lines
8.8 KiB
Markdown
375 lines
8.8 KiB
Markdown
# Vyla SDK API Reference
|
|
|
|
<p class="page-description">Technical reference for `@vyla-entertainment/sdk`: classes, methods, config exports, parameters, and TypeScript definitions.</p>
|
|
|
|
## Class: `VylaSDK`
|
|
|
|
The primary entry point for media scraping, subtitle retrieval, downloads, and manga discovery.
|
|
|
|
```typescript
|
|
import VylaSDK from '@vyla-entertainment/sdk';
|
|
```
|
|
|
|
---
|
|
|
|
### Constructor
|
|
|
|
```typescript
|
|
constructor(options?: VylaSDKOptions)
|
|
```
|
|
|
|
**Parameters:**
|
|
- `options.tmdbApiKey` *(string, optional)* — TMDB v3 API Key for metadata lookups.
|
|
- `options.penguManifest` *(string, optional)* — Custom Stremio manifest URL for the Pengu provider source.
|
|
|
|
```javascript
|
|
const sdk = new VylaSDK({
|
|
tmdbApiKey: '9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d'
|
|
});
|
|
```
|
|
|
|
---
|
|
|
|
### `getSources(excludeDisabled?)`
|
|
|
|
```typescript
|
|
getSources(excludeDisabled?: boolean): SourceConfig[]
|
|
```
|
|
|
|
Returns registered provider scraper configurations from `SOURCES`.
|
|
|
|
**Parameters:**
|
|
- `excludeDisabled` *(boolean, optional)* — When `true`, filters out scrapers with `disabled: true`. Default: `false`.
|
|
|
|
**Returns:** Array of [`SourceConfig`](#interface-sourceconfig) objects.
|
|
|
|
```javascript
|
|
const activeSources = sdk.getSources(true);
|
|
const dedicatedActive = activeSources.filter(s => s.dedicated);
|
|
const aggregatorActive = activeSources.filter(s => !s.dedicated);
|
|
```
|
|
|
|
---
|
|
|
|
### `getStream(key, id, s?, e?, clientIP?)`
|
|
|
|
```typescript
|
|
async getStream(
|
|
key: string,
|
|
id: string | number,
|
|
s?: number | null,
|
|
e?: number | null,
|
|
clientIP?: string | null
|
|
): Promise<StreamResponse | null>
|
|
```
|
|
|
|
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'`).
|
|
- `id` *(string | number, required)* — TMDB ID or IMDb ID.
|
|
- `s` *(number, optional)* — Season 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`.
|
|
|
|
**Returns:** A Promise resolving to a [`StreamResponse`](#interface-streamresponse) object or `null`.
|
|
|
|
```javascript
|
|
const movieStream = await sdk.getStream('vidlink', 155);
|
|
const episodeStream = await sdk.getStream('vixsrc', 1396, 1, 1);
|
|
```
|
|
|
|
---
|
|
|
|
### `getSubtitles(id, s?, e?)`
|
|
|
|
```typescript
|
|
async getSubtitles(
|
|
id: string | number,
|
|
s?: number | null,
|
|
e?: number | null
|
|
): Promise<SubtitleResult[]>
|
|
```
|
|
|
|
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.
|
|
- `s` *(number, optional)* — Season number. Default: `null`.
|
|
- `e` *(number, optional)* — Episode number. Default: `null`.
|
|
|
|
**Returns:** Array of [`SubtitleResult`](#interface-subtitleresult) objects.
|
|
|
|
---
|
|
|
|
### `getDownloads(id, s?, e?)`
|
|
|
|
```typescript
|
|
async getDownloads(
|
|
id: string | number,
|
|
s?: number | null,
|
|
e?: number | null
|
|
): Promise<DownloadResult[]>
|
|
```
|
|
|
|
Resolves direct `.mp4` download URLs from active sources configured with `skipProxy: true`, deduplicated by URL.
|
|
|
|
**Returns:** Array of [`DownloadResult`](#interface-downloadresult) objects.
|
|
|
|
---
|
|
|
|
### `probeSource(key)`
|
|
|
|
```typescript
|
|
async probeSource(key: string): Promise<ProbeResult>
|
|
```
|
|
|
|
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, movie: boolean, tv: boolean, ms: number | null }`.
|
|
|
|
---
|
|
|
|
### `probeAllSources()`
|
|
|
|
```typescript
|
|
async probeAllSources(): Promise<ProbeAllResult>
|
|
```
|
|
|
|
Concurrently probes all active (non-disabled) sources and returns a health map keyed by source `key`.
|
|
|
|
---
|
|
|
|
### Manga Methods
|
|
|
|
#### `searchManga(query, page?, perPage?)`
|
|
```typescript
|
|
async searchManga(query: string, page?: number, perPage?: number): Promise<MangaSearchResult>
|
|
```
|
|
Queries the manga catalog via `atsu.moe` using Chrome 131 TLS fingerprinting.
|
|
|
|
#### `getManga(id)`
|
|
```typescript
|
|
async getManga(id: string): Promise<MangaDetails>
|
|
```
|
|
Retrieves full manga details, authors, genres, tags, and chapter list.
|
|
|
|
#### `getMangaChapter(mangaId, chapterId)`
|
|
```typescript
|
|
async getMangaChapter(mangaId: string, chapterId: string): Promise<MangaChapterPages>
|
|
```
|
|
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
|
|
export interface SourceConfig {
|
|
key: string;
|
|
label: string;
|
|
sourceFile: string;
|
|
proxyParam: string;
|
|
timeout: number;
|
|
jitter: number;
|
|
retries: number;
|
|
multiUrl?: boolean;
|
|
dedicated?: boolean;
|
|
skipProxy?: boolean;
|
|
skipVerify?: boolean;
|
|
verifyHeaders?: Record<string, string>;
|
|
disabled?: boolean;
|
|
sourcesTimeout?: number;
|
|
cdnHeaders?: {
|
|
pattern: RegExp;
|
|
headers: {
|
|
Referer?: string;
|
|
Origin?: string;
|
|
[key: string]: string | undefined;
|
|
};
|
|
}[];
|
|
}
|
|
```
|
|
|
|
### `Interface: EmbedConfig`
|
|
|
|
```typescript
|
|
export interface EmbedConfig {
|
|
key: string;
|
|
label: string;
|
|
movie: string;
|
|
tv: string;
|
|
ads?: boolean;
|
|
}
|
|
```
|
|
|
|
### `Interface: StreamCandidate` & `StreamResponse`
|
|
|
|
```typescript
|
|
export interface StreamCandidate {
|
|
url: string;
|
|
headers?: Record<string, string>;
|
|
server: string;
|
|
quality: string;
|
|
type: "mp4" | "hls" | "dash" | "mkv" | string;
|
|
label?: string;
|
|
skipProxy?: boolean;
|
|
skipVerify?: boolean;
|
|
audio?: string;
|
|
}
|
|
|
|
export interface StreamResponse {
|
|
url: string;
|
|
headers?: Record<string, string>;
|
|
server?: string;
|
|
quality?: string;
|
|
type?: string;
|
|
allUrls: StreamCandidate[];
|
|
}
|
|
```
|
|
|
|
### `Interface: SubtitleResult`
|
|
|
|
```typescript
|
|
export interface SubtitleResult {
|
|
label: string;
|
|
file: string;
|
|
type: "vtt" | "srt";
|
|
source: "v1" | "v2" | "opensubtitles" | "febbox" | string;
|
|
}
|
|
```
|
|
|
|
### `Interface: DownloadResult`
|
|
|
|
```typescript
|
|
export interface DownloadResult {
|
|
source: string;
|
|
label: string;
|
|
url: string;
|
|
}
|
|
```
|
|
|
|
### `Interface: ProbeResult` & `ProbeAllResult`
|
|
|
|
```typescript
|
|
export interface ProbeResult {
|
|
ok: boolean;
|
|
movie?: boolean;
|
|
tv?: boolean;
|
|
ms: number | null;
|
|
}
|
|
|
|
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[];
|
|
}
|
|
``` |