npm package: @luciusexe10/onyx-dl
Description: Unified intelligent downloader for videos and images from all major social media platforms
Author: Lucius
Latest version: 1.1.1

# @luciusexe10/onyx-dl

Unified intelligent downloader for videos and images from all major social media platforms.

## Installation

```bash
npm install @luciusexe10/onyx-dl
```

## Quick Start

```typescript
import { alldl } from '@luciusexe10/onyx-dl';

const result = await alldl('https://www.instagram.com/p/xyz');

if (result.success) {
  console.log(result.downloads);
}
```

## Supported Platforms

Instagram • TikTok • YouTube • Facebook • Twitter/X • Pinterest • Threads • SoundCloud • Spotify • Douyin • Xiaohongshu • SnackVideo • Cocofun • CapCut • Google Drive • MediaFire

## API

### `alldl(url)`

Main unified endpoint. Automatically detects platform and downloads media.

**Response:**
```typescript
{
  success: boolean;
  platform: string;
  metadata?: {
    title?: string;
    author?: string;
    thumbnail?: string;
    duration?: string | number;
  };
  downloads?: Array<{
    type: 'video' | 'image' | 'audio';
    url: string;
    quality?: string;
  }>;
  error?: string;
}
```

### `detectPlatform(url)`

Detects platform from URL.

### `isValidUrl(url)`

Validates URL format.

## Examples

### Basic Usage

```typescript
import { alldl } from '@luciusexe10/onyx-dl';

const result = await alldl('https://www.instagram.com/p/xyz');

if (result.success) {
  result.downloads?.forEach(item => {
    console.log(`${item.type}: ${item.url}`);
  });
}
```

### Multiple URLs

```typescript
import { alldl } from '@luciusexe10/onyx-dl';

const urls = [
  'https://instagram.com/p/xyz',
  'https://tiktok.com/@user/video/123',
  'https://youtube.com/watch?v=abc'
];

const results = await Promise.all(urls.map(url => alldl(url)));
```

### Express.js Server

```typescript
import express from 'express';
import { alldl } from '@luciusexe10/onyx-dl';

const app = express();
app.use(express.json());

app.all('/download', async (req, res) => {
  const url = req.method === 'GET' ? req.query.url : req.body.url;
  
  if (!url) {
    return res.status(400).json({ success: false, error: 'URL required' });
  }
  
  const result = await alldl(url as string);
  res.json(result);
});

app.listen(3000);
```

### Browser Usage

```html
<!DOCTYPE html>
<html>
<head>
  <title>@luciusexe10/onyx-dl Demo</title>
</head>
<body>
  <input id="url" placeholder="Paste URL">
  <button onclick="download()">Download</button>
  <div id="result"></div>

  <script src="https://cdn.jsdelivr.net/npm/@luciusexe10/onyx-dl/dist/browser/index.min.js"></script>
  <script>
    async function download() {
      const url = document.getElementById('url').value;
      const result = await window.OnyxDL.alldl(url);
      
      if (result.success) {
        document.getElementById('result').innerHTML = 
          result.downloads.map(d => `<a href="${d.url}">${d.type}</a>`).join('<br>');
      } else {
        document.getElementById('result').textContent = result.error;
      }
    }
  </script>
</body>
</html>
```

### Error Handling

```typescript
import { alldl } from '@luciusexe10/onyx-dl';

try {
  const result = await alldl(url);
  
  if (!result.success) {
    console.error(result.error);
    return;
  }
  
  // Process downloads
  result.downloads?.forEach(item => {
    console.log(item.url);
  });
} catch (error) {
  console.error('Request failed:', error);
}
```

### TypeScript

```typescript
import { alldl, type UnifiedResponse } from '@luciusexe10/onyx-dl';

async function download(url: string): Promise<UnifiedResponse> {
  const result = await alldl(url);
  
  if (result.success && result.downloads) {
    result.downloads.forEach(d => {
      console.log(d.type); // 'video' | 'image' | 'audio'
      console.log(d.url);
    });
  }
  
  return result;
}
```

### Platform Detection

```typescript
import { detectPlatform, isValidUrl } from '@luciusexe10/onyx-dl';

const url = 'https://instagram.com/p/xyz';

if (isValidUrl(url)) {
  const platform = detectPlatform(url);
  console.log(platform); // 'instagram'
}
```

## Response Examples

### Success

```json
{
  "success": true,
  "platform": "instagram",
  "metadata": {
    "title": "Photo",
    "author": "user"
  },
  "downloads": [
    {
      "type": "image",
      "url": "https://..."
    }
  ]
}
```

### Error

```json
{
  "success": false,
  "platform": "unknown",
  "error": "Invalid URL"
}
```

## CDN

```html
<!-- unpkg -->
<script src="https://unpkg.com/@luciusexe10/onyx-dl/dist/browser/index.min.js"></script>

<!-- jsDelivr -->
<script src="https://cdn.jsdelivr.net/npm/@luciusexe10/onyx-dl/dist/browser/index.min.js"></script>

<script>
  const { alldl } = window.OnyxDL;
  alldl('https://instagram.com/p/xyz').then(console.log);
</script>
```

## Legacy API

Individual platform functions available for backward compatibility:

```typescript
import { igdl, ttdl, youtube } from '@luciusexe10/onyx-dl';

const ig = await igdl('https://instagram.com/p/xyz');
const tt = await ttdl('https://tiktok.com/@user/video/123');
const yt = await youtube('https://youtube.com/watch?v=xyz');
```

## Notes

- Only download public media or content you have permission to access
- Respect platform rate limits and terms of service
- Not affiliated with any social media platform

## Credits

### Original API Backend
**[@prm2.0](https://github.com/hostinger-bot)** (Tio)
- Created btch-downloader package
- Developed all platform-specific download APIs
- Maintains backend infrastructure at https://backend1.tioo.eu.org

### Unified Wrapper
**Lucius**
- Wrapped APIs into single unified endpoint
- Added intelligent platform detection
- Standardized response format
- Created TypeScript definitions

This package wraps the excellent btch-downloader APIs by @prm2.0 into a unified interface.

## License

MIT