# 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[]; } ```