documentation/sdk/vyla-sdk/contributing.md

# Contributing to Sources

<p class="page-description">Help maintain, fix broken scrapers, and add new video or download providers to the Vyla SDK.</p>

Third-party streaming and scraping endpoints frequently change their DOM layout, API endpoints, tokens, and CDN protections. Community contributions are vital to keeping providers operational.

---

### Thank You

If you’re a developer or just want to help test and fix sources, feel free to contribute! If you get a source working, send me the updated version.

As a thank-you, contributors will receive the Contributor role and credit directly in the code for their contribution, along with a custom message of your choice and your Discord username.

Any help is appreciated! ❤️

## Getting Started

### 1. Clone the repository

Clone the SDK repository to your local machine:

```bash
git clone https://gitlab.com/vyla-entertainment/sdk.git
cd sdk
```

### 2. Install dependencies

Ensure you are running Node.js 18 or newer:

```bash
npm install
```

### 3. Environment configuration

Copy the example environment file and add your TMDB API key:

```bash
cp .env.example .env
```

Open `.env` and set your key:

```ini
TMDB_API_KEY=your_actual_tmdb_api_key_here
```

---

## Project Structure

- `src/sources/`: Scraper implementations for each provider.
- `src/manga/`: Manga catalog search and reader page resolvers.
- `src/config.js`: Source registry containing timeouts, retries, headers, and proxy flags.
- `src/downloads/downloads.js`: Downloader resolver extracting direct MP4 streams.
- `src/subtitles.js`: Subtitle mirror aggregation endpoints.
- `test/index.js`: Test runner for testing streams, subtitles, downloads, and manga.

---

## Testing Sources

Testing is driven by `test/index.js`. Open the file and update `CONFIG` to target the source you are fixing or adding:

```javascript
const CONFIG = {
    DEBUG: true,

    MOVIE_ID: "936075",
    TV_ID: "37854",
    TV_SEASON: "1",
    TV_EPISODE: "1",
    STREAM_SOURCE: "vidrock",

    TEST_SUBTITLE: false,
    TEST_DOWNLOAD: false,
    TEST_MOVIE: true,
    TEST_TV: true,

    EXTRA_SDK_PARAMS: {}
};
```

Run the test suite:

```bash
npm test
```

When `DEBUG: true` is enabled, all outbound fetch calls, headers, request payloads, and raw responses will be logged to your terminal and saved to `test/debug-output.json`.

---

## Fixing or Adding a Source

### 1. Source Resolver

All source files are located in `src/sources/`. Each module must export an asynchronous `getStream` function:

```javascript
export async function getStream({ id, s, e, clientIP, audio, sdk, config }) {
    const isTv = Boolean(s && e);
    const mediaId = id;

    const streamUrl = "https://example-cdn.com/stream/playlist.m3u8";

    return {
        url: streamUrl,
        quality: "auto",
        isM3U8: true,
        headers: {
            Referer: "https://example-provider.to/",
            Origin: "https://example-provider.to"
        },
        allUrls: [
            {
                url: streamUrl,
                quality: "1080p",
                isM3U8: true
            }
        ]
    };
}
```

### 2. Registering in `src/config.js`

Add or update the source entry inside the `SOURCES` array in `src/config.js`:

```javascript
{
    key: 'mysource',
    label: 'MySource',
    sourceFile: 'mysource',
    proxyParam: 'ms',
    timeout: 25000,
    jitter: 500,
    retries: 2,
    multiUrl: true,
    skipProxy: true,
    cdnHeaders: [{
        pattern: /cdn\.mysource\.to/i,
        headers: {
            Referer: 'https://mysource.to/',
            Origin: 'https://mysource.to',
        },
    }],
}
```

- `skipProxy`: Set to `true` if the stream plays directly in client players without server-side proxying.
- `multiUrl`: Set to `true` if the scraper provides multiple resolutions or fallback mirrors.
- `cdnHeaders`: Include custom headers required by the upstream CDN to avoid HTTP 403 Forbidden responses.

---

## Download Providers

Downloads are handled automatically by `src/downloads/downloads.js`. The downloader queries active sources that have `skipProxy: true` enabled and inspects returned streams:

- URLs ending in `.mp4` or containing `.mp4` queries are automatically extracted.
- `.m3u8` streams are filtered out because they are HLS segment playlists rather than direct file downloads.
- If you are implementing a provider that supplies raw MP4 video files, return them in `allUrls` or `url` with `skipProxy: true` in `src/config.js`.

To verify download resolution in `test/index.js`, toggle:

```javascript
TEST_DOWNLOAD: true
```

---

## Submitting Pull Requests

1. Verify that your updated source passes tests for both movies (`TEST_MOVIE: true`) and TV shows (`TEST_TV: true`).
2. Ensure you have not committed your `.env` file or personal TMDB API keys.
3. Push your branch and open a Merge Request on GitLab.