tk4-downloader/DOCS.md

Modern TikTok video downloader with FHD quality and no watermark

# TK4 Downloader Library Documentation

<div align="center">

![TK4 Library Banner](https://your-banner-image-url.png)

**Advanced TikTok Video Downloader Library**  
*Version 1.6.0*

</div>

## Table of Contents

- [Installation](#installation)
- [Quick Start](#quick-start)
- [Advanced Usage](#advanced-usage)
- [Configuration Options](#configuration-options)
- [API Reference](#api-reference)
- [Events](#events)
- [Statistics & Monitoring](#statistics--monitoring)
- [Error Handling](#error-handling)
- [Best Practices](#best-practices)
- [Examples](#examples)
- [Troubleshooting](#troubleshooting)

## Installation

```bash
npm install tk4-downloader
# or
yarn add tk4-downloader
```

## Quick Start

```javascript
import TikTokDownloader from 'tk4-downloader';

// Initialize the downloader
const downloader = new TikTokDownloader();

// Basic usage
async function downloadVideo() {
    try {
        const result = await downloader.downloadVideo('https://www.tiktok.com/@user/video/1234567890');
        console.log(`Video downloaded: ${result.url}`);
    } catch (error) {
        console.error('Download failed:', error.message);
    }
}
```

## Advanced Usage

### With Custom Configuration

```javascript
const downloader = new TikTokDownloader({
    preferredQuality: 'high',
    maxRetries: 5,
    cacheResults: true,
    debug: true,
    parallelDownloads: 3
});

// Add event listeners
downloader.on('progress', ({status, message}) => {
    console.log(`Progress: ${message}`);
});

downloader.on('success', (info) => {
    console.log(`Downloaded from ${info.source} in ${info.duration}ms`);
});

// Download with monitoring
async function downloadWithMonitoring(url) {
    const result = await downloader.downloadVideo(url);
    const stats = downloader.getDetailedStats();
    console.log(`Success rate: ${stats.successRate}%`);
}
```

## Configuration Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `preferredQuality` | string | 'high' | Video quality ('high', 'medium', 'low') |
| `maxRetries` | number | 3 | Maximum retry attempts |
| `timeout` | number | 10000 | Request timeout in milliseconds |
| `cacheResults` | boolean | true | Enable result caching |
| `maxCacheAge` | number | 3600000 | Cache duration in milliseconds |
| `parallelDownloads` | number | 3 | Number of concurrent downloads |
| `outputFormat` | string | 'mp4' | Output video format |
| `includeAudio` | boolean | true | Include audio in download |
| `debug` | boolean | false | Enable debug logging |
| `proxyUrl` | string | null | Proxy server URL |
| `customFileName` | string | null | Custom filename pattern |
| `downloadPath` | string | process.cwd() | Download directory path |

## API Reference

### Core Methods

#### `downloadVideo(url: string, options?: object): Promise<object>`
Downloads a TikTok video.
```javascript
const result = await downloader.downloadVideo(url);
// Returns: { url, author, description, quality, source }
```

#### `getDetailedStats(): object`
Get detailed download statistics.
```javascript
const stats = downloader.getDetailedStats();
// Returns comprehensive statistics object
```

#### `resetStats(): void`
Reset all statistics counters.
```javascript
downloader.resetStats();
```

### Advanced Methods

#### `getVideoMetadata(url: string): Promise<object>`
Fetch video metadata from multiple sources.
```javascript
const metadata = await downloader.getVideoMetadata(url);
```

#### `selectBestQuality(results: Array): object`
Select best quality version from available sources.
```javascript
const bestQuality = downloader.selectBestQuality(results);
```

## Events

### Available Events

| Event | Description | Payload |
|-------|-------------|---------|
| `start` | Download started | `{ url, timestamp }` |
| `progress` | Download progress | `{ status, message }` |
| `success` | Download completed | `