# 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, and downloads. ```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`. --- ## 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; ```