documentation/sdk/vyla-sdk/reference.md

# Vyla SDK API Reference

<p class="page-description">Complete technical reference for the `@vyla-entertainment/sdk` package: classes, methods, parameters, interfaces, and TypeScript definitions.</p>

## Class: `VylaSDK`

The primary entry point of the package. Instantiated to manage scraper execution, health probing, subtitle retrieval, downloads, and manga discovery.

```typescript
import VylaSDK from '@vyla-entertainment/sdk';
```

---

### Constructor

```typescript
constructor(options?: VylaSDKOptions)
```

Creates a new instance of `VylaSDK`.

#### Parameters
| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `options.tmdbApiKey` | `string` | Optional | `null` | Your TMDB v3 API Key. Highly recommended; required by sources that query metadata by IMDb ID or episode name. |
| `options.penguManifest` | `any` | Optional | `null` | Custom manifest definition for the Pengu provider source. |

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

---

### `getSources(excludeDisabled?)`

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

Returns the registered list of provider scraper configurations.

#### Parameters
| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `excludeDisabled` | `boolean` | Optional | `false` | When `true`, filters out providers marked with `disabled: true`. |

#### Returns
Array of [`SourceConfig`](#interface-sourceconfig) objects.

#### Example
```javascript
const activeSources = sdk.getSources(true);
console.log(`Available active providers: ${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 the scraper module for a specified provider and resolves streaming candidate URLs.

#### Parameters
| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `key` | `string` | Required | — | The source key identifier (e.g. `'vidlink'`, `'vixsrc'`). |
| `id` | `string \| number` | Required | — | Numeric TMDB ID or string IMDb ID (for movies and TV shows). |
| `s` | `number \| null` | Optional | `null` | Season number (required for TV episodes). |
| `e` | `number \| null` | Optional | `null` | Episode number (required for TV episodes). |
| `clientIP` | `string \| null` | Optional | `null` | Client IP address passed for upstream geo-token generation. |

#### Returns
A Promise resolving to a [`StreamResult`](#interface-streamresult) object, or `{ allUrls: StreamResult[] }` if the source supports multi-URL extraction.

#### Throws
- `Error('Source with key "..." not found')` if the key does not exist.
- `Error('Source module for key "..." not found')` if the source module is disabled or failed to import.
- Upstream network errors or scraper extraction errors if the title cannot be found.

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

Discovers and parses all available subtitle tracks for a movie or TV episode.

#### Parameters
| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `id` | `string \| number` | Required | — | TMDB media identifier. |
| `s` | `number \| null` | Optional | `null` | Season number (TV shows). |
| `e` | `number \| null` | Optional | `null` | Episode number (TV shows). |

#### Returns
A Promise resolving to an 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
A Promise resolving to an array of [`DownloadResult`](#interface-downloadresult) objects.

---

### `probeSource(key)`

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

Sends a lightweight probe request against the designated source to measure responsiveness and availability.

#### Parameters
| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `key` | `string` | Required | The provider key to probe. |

#### Returns
A Promise resolving to a [`ProbeResult`](#interface-proberesult) object: `{ ok: boolean, ms: number | null }`.

---

### `probeAllSources()`

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

Concurrently probes all active (non-disabled) sources and compiles a live health map.

#### Returns
A Promise resolving to a [`ProbeAllResult`](#type-probeallresult) dictionary mapping source keys to their probe results.

---

### 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. Returns paginated title listings.

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

#### `getMangaChapter(mangaId, chapterId)`
```typescript
async getMangaChapter(mangaId: string, chapterId: string): Promise<any>
```
Resolves ordered image URLs, dimensions, and aspect ratios for all pages in a given 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>;
```