documentation/sdk/vyla-sdk/reference.md

# Vyla SDK API Reference

<p class="page-description">Technical reference for `@vyla-entertainment/sdk`: classes, methods, 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` *(any, optional)* — Custom manifest for the Pengu provider source.

```javascript
const sdk = new VylaSDK({
  tmdbApiKey: '9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d'
});
```

---

### `getSources(excludeDisabled?)`

```typescript
getSources(excludeDisabled?: boolean): SourceConfig[]
```

Returns registered provider scraper configurations.

**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);
console.log(activeSources.map(s => s.key).join(', '));
```

---

### `getStream(key, id, s?, e?, clientIP?)`

```typescript
async getStream(
    key: string,
    id: string | number,
    s?: number | null,
    e?: number | null,
    clientIP?: string | null
): Promise<StreamResult | { allUrls: StreamResult[] }>
```

Executes a provider scraper module to resolve candidate stream URLs.

**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 [`StreamResult`](#interface-streamresult) object.

```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 parsed subtitle tracks 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 media download packages and torrent/debrid links.

**Returns:** Array of [`DownloadResult`](#interface-downloadresult) objects.

---

### `probeSource(key)`

```typescript
async probeSource(key: string): Promise<ProbeResult>
```

Sends a probe request against a single provider to check responsiveness.

**Parameters:**
- `key` *(string, required)* — Provider key to probe.

**Returns:** `{ ok: boolean, ms: number | null }`.

---

### `probeAllSources()`

```typescript
async probeAllSources(): Promise<ProbeAllResult>
```

Concurrently probes all active sources and returns a health map.

---

### Manga Methods

#### `searchManga(query, page?, perPage?)`
```typescript
async searchManga(query: string, page?: number, perPage?: number): Promise<any>
```
Queries the manga catalog via `atsu.moe` using Chrome 131 TLS fingerprinting.

#### `getManga(id)`
```typescript
async getManga(id: string): Promise<any>
```
Retrieves full manga details, author, genres, and chapter list.

#### `getMangaChapter(mangaId, chapterId)`
```typescript
async getMangaChapter(mangaId: string, chapterId: string): Promise<any>
```
Resolves ordered image URLs and dimensions for all pages in a chapter.

---

## TypeScript Interfaces

### `Interface: SourceConfig`

```typescript
export interface SourceConfig {
    key: string;
    label: string;
    sourceFile: string;
    proxyParam: string;
    timeout: number;
    jitter: number;
    retries: number;
    multiUrl: boolean;
    skipProxy?: boolean;
    skipVerify?: boolean;
    verifyHeaders?: boolean;
    disabled?: boolean;
    sourcesTimeout?: number;
    cdnHeaders?: {
        pattern: RegExp;
        headers: {
            Referer: string;
            Origin: string;
        };
    }[];
}
```

### `Interface: StreamResult`

```typescript
export interface StreamResult {
    url: string;
    headers: {
        "User-Agent": string;
        Referer: string;
        Origin: string;
        [key: string]: string;
    };
    server: string;
    quality: string;
    type: "mp4" | "hls";
    skipVerify?: boolean;
    skipProxy?: boolean;
}
```

### `Interface: SubtitleResult`

```typescript
export interface SubtitleResult {
    label: string;
    file: string;
    type: "vtt" | "srt";
    source: string;
}
```

### `Interface: DownloadResult`

```typescript
export interface DownloadResult {
    url: string;
    quality: string;
    size: number | null;
    type: "mkv";
    active: boolean;
}
```

### `Interface: ProbeResult` & `ProbeAllResult`

```typescript
export interface ProbeResult {
    ok: boolean;
    ms: number | null;
}

export type ProbeAllResult = Record<string, ProbeResult>;
```