# Vyla SDK API Reference
Technical reference for `@vyla-entertainment/sdk`: classes, methods, config exports, parameters, and TypeScript definitions.
## 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
```
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
```
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
```
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
```
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
```
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
```
Queries the manga catalog via `atsu.moe` using Chrome 131 TLS fingerprinting.
#### `getManga(id)`
```typescript
async getManga(id: string): Promise
```
Retrieves full manga details, authors, genres, tags, and chapter list.
#### `getMangaChapter(mangaId, chapterId)`
```typescript
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
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;
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;
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;
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;
```
### `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[];
}
```