mirror of
https://gitlab.com/vyla-entertainment/documentation.git
synced 2026-11-17 07:57:23 -05:00
huge rewrite
This commit is contained in:
276
sdk/vyla-sdk/reference.md
Normal file
276
sdk/vyla-sdk/reference.md
Normal file
@@ -0,0 +1,276 @@
|
||||
# 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>;
|
||||
```
|
||||
Reference in New Issue
Block a user