badan-ser/README.md

external functions for zoe

# Utils Toolkit

A Node.js toolkit to:
- Search YouTube without using the official API
- Download YouTube videos (MP4) and audio (MP3)
- Take advanced screenshots of web pages using Puppeteer
- Load `.env` variables without using external dotenv packages

---

## 🚀 Features

- 🔍 **YouTube Search** (No API key required)
- 🎵 **YouTube to MP3** conversion
- 🎥 **YouTube to MP4** download (multiple quality options)
- 📸 **Advanced Web Screenshot** with Puppeteer:
  - Full page
  - Specific region
  - DOM element
- 🔧 Lightweight `.env` loader

---

## 📦 Installation

```bash
npm install badan-ser
```

---

## 🛠️ Usage

### 1. Load Environment Variables
```js
const { loadEnv } = require('badan-ser');
loadEnv(); // Loads .env from project root
```

### 2. YouTube Search

```js
const { yts } = require('badan-ser');

(async () => {
  const results = await yts("lofi music");
  console.log(results);
})();
```

### 3. Download YouTube as MP3

```js
const { ytdls } = require('badan-ser');

(async () => {
  const result = await ytdls.mp3('https://youtu.be/exampleID');
  console.log(result);
})();
```

### 4. Download YouTube as MP4 (480p, 720p, 1080p, etc.)

```js
const { ytdls } = require('badan-ser');

(async () => {
  const result = await ytdls.mp4('https://youtu.be/exampleID', '720');
  console.log(result);
})();
```

### 5. Take Screenshot of a Web Page

```js
const { ss } = require('badan-ser');

(async () => {
  await ss({
    url: 'https://example.com',
    output: 'screenshot.png',
    type: 'element',
    selector: '#main'
  });
})();
```

---

## 📘 API Overview

### `loadEnv(filePath = '.env')`
Loads `.env` variables into `process.env`.

---

### `yts(query)`
Search YouTube and return metadata for top videos.

---

### `ytdls.mp3(url)`
Convert and download YouTube video as MP3.

---

### `ytdls.mp4(url, quality)`
Download YouTube video as MP4. Supported qualities:
- `360`, `480`, `720`, `1080`
- `"audio"` for MP3

---

### `ss(options)`
Take a screenshot of a URL.
- `url` — required
- `output` — filename
- `type` — `'full'`, `'region'`, `'element'`, `'viewport'`
- `selector` — DOM selector (if type = `element`)
- `region` — `{ x, y, width, height }` (if type = `region`)
- `viewport` — `{ width, height }`
- `delay` — ms to wait before capture

---

## 🧱 Dependencies

- [`puppeteer`](https://www.npmjs.com/package/puppeteer)
- [`axios`](https://www.npmjs.com/package/axios)
- [`cheerio`](https://www.npmjs.com/package/cheerio)
- [`form-data`](https://www.npmjs.com/package/form-data)
- Built-in: `fs`, `path`

---

## 📄 License

MIT License

---

## 👨‍💻 Author

Made with ❤️ by [Badan Ser](https://github.com/Kingbadan321)