# Contributing a Source Provider

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

## Overview The Vyla SDK uses independent provider scrapers located in `src/sources/`. We welcome contributions that expand coverage for movies and television series. --- ## Scraper Contract Every provider module is an ES Module exporting a single function: ```typescript export async function getStream(args: StreamArgs): Promise ``` ### Context Arguments (`args`) - `id` *(string | number)* — TMDB numeric ID or string IMDb ID. - `s` *(number | null)* — Season number for television series (or `null` for movies). - `e` *(number | null)* — Episode number for television series (or `null` for movies). - `clientIP` *(string | null)* — Client IP address forwarded for geo-token generation. - `fetch` *(Function)* — Pre-configured fetch wrapper with timeout controls. - `imdbId` *(string | null)* — Auto-resolved IMDb ID. - `title` *(string | null)* — Verified title string. - `year` *(number | null)* — Media release year. --- ## Implementation Steps ### 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' }; } ``` --- ### 2. Register in `src/config.js` Add the source configuration: ```javascript { key: 'mysource', label: 'My Source', sourceFile: 'mysource', proxyParam: 'ms', timeout: 12000, jitter: 400, retries: 1, multiUrl: false, skipProxy: false, skipVerify: false } ``` **Key Fields:** - `key`: Lowercase identifier without spaces (e.g. `mysource`). - `label`: Clean display label for client UIs. - `proxyParam`: Unique 2-to-4 character query flag for the HLS proxy. - `timeout`: Maximum execution budget in ms (typically 8,000–15,000). - `jitter`: Random delay ceiling in ms (typically 300–500). --- ### 3. Local Testing Run your scraper against known TMDB titles: ```bash node test/index.js mysource 155 node test/index.js mysource 1396 1 1 ``` Verify that: 1. A valid URL is returned. 2. The format is correctly identified as `hls` or `mp4`. 3. Required upstream headers (`Referer`, `Origin`, `User-Agent`) are included. 4. An invalid ID throws a clean error without crashing. --- ## Contribution Checklist - [ ] Code is formatted with clean ES Module syntax. - [ ] No hardcoded personal API keys or credentials. - [ ] No untrusted `eval()` or un-sanitized script execution. - [ ] Upstream stream candidate URLs are verified for playback. - [ ] Descriptive errors are thrown with `throw new Error(...)`.