# Contributing a Source Provider

Complete technical guide for authoring, testing, and contributing a new video scraping resolver to the Vyla SDK.

## Overview The Vyla SDK maintains its high reliability through a distributed collection of independent provider scrapers located in `src/sources/`. We welcome contributions of new sources that expand coverage for movies, television, and international content. --- ## Scraper Architecture Every provider module is a self-contained ES Module adhering to a single exported contract: ```typescript export async function getStream(args: StreamArgs): Promise ``` ### The `args` Object When your scraper's `getStream()` is invoked, the SDK passes a normalized `args` context containing: | Field | Type | Description | | :--- | :--- | :--- | | `id` | `string \| number` | The TMDB numeric media ID or string IMDb ID. | | `s` | `number \| null` | Season number for television episodes (or `null` for movies). | | `e` | `number \| null` | Episode number for television episodes (or `null` for movies). | | `clientIP` | `string \| null` | The viewer's client IP address (if passed from an upstream proxy). | | `fetch` | `Function` | Node.js fetch wrapper pre-configured with timeout controls. | | `imdbId` | `string \| null` | Automatically resolved IMDb ID (if TMDB API key is configured). | | `title` | `string \| null` | Verified media title string. | | `year` | `number \| null` | Media release year. | --- ## Step-by-Step Implementation Guide ### Step 1: Create the Scraper Module Create a new file in `src/sources/.js`: ```javascript const BASE_URL = 'https://provider-domain.example.com'; const DEFAULT_HEADERS = { 'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36', 'Referer': `${BASE_URL}/`, 'Origin': BASE_URL, }; export async function getStream({ id, s, e, imdbId }) { const isTv = s != null && e != null; const endpoint = isTv ? `${BASE_URL}/api/tv/${id}/${s}/${e}` : `${BASE_URL}/api/movie/${id}`; const response = await fetch(endpoint, { headers: DEFAULT_HEADERS }); if (!response.ok) { throw new Error(`Upstream returned HTTP ${response.status}`); } const data = await response.json(); if (!data.streamUrl) { throw new Error('No stream found in upstream response'); } return { url: data.streamUrl, headers: { ...DEFAULT_HEADERS, 'Referer': data.referer || DEFAULT_HEADERS.Referer }, server: 'MySource-Primary', quality: data.quality || '1080p', type: data.streamUrl.includes('.m3u8') ? 'hls' : 'mp4' }; } ``` --- ### Step 2: Register in `src/config.js` Add your provider configuration to the `SOURCES` array in `src/config.js`: ```javascript { key: 'mysource', label: 'My Source', sourceFile: 'mysource', proxyParam: 'ms', timeout: 12000, jitter: 400, retries: 1, multiUrl: false, skipProxy: false, skipVerify: false } ``` #### Configuration Field Guidelines: - `key`: Lowercase alphanumeric identifier without spaces (e.g. `vidlink`, `cinecat`). - `label`: Clean display title shown in UI menus. - `proxyParam`: Unique 2-to-4 character query flag used by the Stream API HLS proxy (must not collide with existing flags). - `timeout`: Maximum execution budget before aborting (typically 8,000ms–15,000ms). - `jitter`: Random delay ceiling (typically 300ms–500ms) to avoid server burst locks. --- ### Step 3: Local Testing Run your scraper against known TMDB titles using the test runner: ```bash # Test a known movie (The Dark Knight - TMDB 155) node test/index.js mysource 155 # Test a known TV episode (Breaking Bad S01E01 - TMDB 1396) node test/index.js mysource 1396 1 1 ``` Verify that: 1. A valid URL is printed. 2. The `type` is correctly identified as `'hls'` or `'mp4'`. 3. Required upstream headers (`Referer`, `Origin`, `User-Agent`) are included. 4. Testing an invalid ID throws a clean error without crashing the process. --- ## Contribution Rules & Checklist Before submitting a Pull Request to the GitLab repository: - [ ] Code is formatted with clean ES Module syntax. - [ ] No hardcoded personal API keys or credentials. - [ ] Provider does not execute external untrusted `eval()` or un-sanitized script execution. - [ ] Upstream stream candidate URLs must be verified for playback. - [ ] Errors are thrown with informative messages (`throw new Error(...)`).