wsper-js 0.1.1 → 0.1.2-wc2

package/README.md

@@ -1,4 +1,3 @@
-
 <h1 align="center">
   <img alt="ShikanokoBail banner" src="https://i.pinimg.com/736x/0c/ff/62/0cff624a04a81495f4b8e69bcedd34aa.jpg" width="100%"/>
 </h1>
@@ -8,98 +7,126 @@
 [![npm](https://img.shields.io/npm/v/wsper-js?label=npm)](https://www.npmjs.com/package/wsper-js)
 ![TypeScript](https://img.shields.io/badge/TypeScript-5.8-blue)
 ![Node](https://img.shields.io/badge/Node-%3E%3D18.0.0-green)
-![Tests](https://img.shields.io/badge/tests-314%20passed-brightgreen)
+![Tests](https://img.shields.io/badge/tests-441%20passed-brightgreen)
 ![License](https://img.shields.io/badge/license-GPL--3.0--or--later-blue)
 </div>
 
-# wsper-js
-`wsper-js` is a TypeScript-first scraper toolkit for building reusable, typed, and testable scrapers across multiple public platforms. It provides platform-specific scraper classes, shared HTTP and queue primitives, safe downloader utilities, parser helpers, media utilities, and runnable examples for controlled and ethical data access.
-
-The package is ESM-only and targets Node.js 18 or newer.
-
-## Features
-
-- Modular scraper architecture under `src/scrapers/`.
-- TypeScript strict mode with exported response, option, and scraper data types.
-- Standard `WsperResponse<T>` shape for scraper results.
-- Shared HTTP client with timeouts, bounded retries, redirects, URL safety checks, browser-compatible public headers, and optional request queue pacing.
-- Unit-tested scraper behavior and parser behavior.
-- `examples/alllexamp.ts` runner for direct scraper demos and subprocess example checks.
-- Local mock server support for testing WordPress-style endpoints, AI tools, and Fandom API responses without depending on live external services.
-- Public API integrations where available, including LRCLIB, Wallhaven, Fandom MediaWiki, Spotify Web API, BMKG, npm registry, and BiliBili APIs.
-- Cookie or credential support for platforms that legitimately require authenticated sessions, including Instagram, Twitter/X, Threads, Pinterest, BiliBili, and Spotify credentials.
-- Additional modules for downloads, Brat image/GIF/video generation, and analytics chart image generation.
-
-## Installation
+# wsper-js: Developer User Manual & API Guide
+
+`wsper-js` is an enterprise-grade, TypeScript-first scraper and media generation toolkit. It provides structured scrapers for over 80 public and credentialed services, a deterministic canvas-based rendering engine, a stylized text-to-sticker generator, a secure file downloader, and request-pacing queues designed to interact ethically and robustly with public endpoints.
+
+---
+
+## Table of Contents
+1. [Prerequisites & Installation](#prerequisites--installation)
+2. [Quick Start](#quick-start)
+3. [Core Concepts & Architecture](#core-concepts--architecture)
+   - [Unified WsperResponse Envelope](#unified-wsperresponse-envelope)
+   - [Request Pacing & Rate Limiting](#request-pacing--rate-limiting)
+   - [Safe HTTP Client & Rotation](#safe-http-client--rotation)
+   - [Credentials Configuration](#credentials-configuration)
+4. [In-Depth Feature Modules](#in-depth-feature-modules)
+   - [Brat Generator (Stickers & Media)](#1-brat-generator-stickers--media)
+   - [Analytics Chart Image Generator](#2-analytics-chart-image-generator)
+   - [Safe Downloader Primitive](#3-safe-downloader-primitive)
+5. [Scrapers Usage Catalog](#scrapers-usage-catalog)
+   - [Social Media & AI Messaging](#social-media--ai-messaging)
+   - [Streaming & Media Resolvers](#streaming--media-resolvers)
+   - [Indonesian Reference Services](#indonesian-reference-services)
+   - [Global Reference & Search APIs](#global-reference--search-apis)
+   - [Scholarly & Academic Metadata](#scholarly--academic-metadata)
+   - [Developer Registry & Package APIs](#developer-registry--package-apis)
+   - [Utility, AI & Conversion Resolvers](#utility-ai--conversion-resolvers)
+6. [Sandbox & Mock Server Usage](#sandbox--mock-server-usage)
+7. [Error Handling & Exceptions](#error-handling--exceptions)
+
+---
+
+## Prerequisites & Installation
+
+Install the package via your preferred package manager:
 
 ```bash
 npm install wsper-js
-```
-
-```bash
+# or
 pnpm add wsper-js
-```
-
-```bash
+# or
 yarn add wsper-js
 ```
 
-Some optional capabilities need external binaries:
+### External Dependencies
+Some optional modules require external binaries in your system `PATH`:
 
-| Feature | External tool |
-| --- | --- |
-| YouTube and Spotify media enrichment/download helpers | `yt-dlp` |
-| Video export and GIF/MP4 conversion | `ffmpeg` in `PATH` or configured path |
+| Feature | External Binary | Notes |
+| --- | --- | --- |
+| YouTube/Spotify Media Downloads | `yt-dlp` | Must be executable in your `PATH` |
+| Brat Video/GIF Conversion | `ffmpeg` | Required for converting canvas streams to MP4/GIF |
+
+---
 
 ## Quick Start
 
+### Basic Scraper Class (Direct Usage)
+Every scraper in the library is exported as a standalone class. 
+
 ```ts
 import { LyricsScraper } from "wsper-js";
 
-const lyrics = new LyricsScraper();
-const result = await lyrics.search("after hours the weeknd");
+const lyricsScraper = new LyricsScraper();
+const response = await lyricsScraper.search("after hours the weeknd");
 
-if (!result.ok) {
-  throw new Error(`${result.error?.code}: ${result.error?.message}`);
+if (response.ok && response.data) {
+  console.log(`Title: ${response.data.title}`);
+  console.log(`Lyrics: ${response.data.lyrics}`);
+} else {
+  console.error(`Error [${response.error?.code}]: ${response.error?.message}`);
 }
-
-console.log(result.statusCode);
-console.log(result.data?.title);
-console.log(result.data?.lyrics);
 ```
 
-You can also use `WsperScraper` for the aggregate social/media scraper entrypoint:
+### Aggregated Entrypoint (`WsperScraper`)
+For larger architectures, you can use the unified `WsperScraper` client to access primary social and media scrapers with shared request-pacing configurations.
 
 ```ts
 import { WsperScraper } from "wsper-js";
 
+// Initialize with shared pacing options
 const wsper = new WsperScraper({
-  queue: { concurrency: 1, minDelayMs: 500, maxDelayMs: 1500 },
+  queue: {
+    concurrency: 2,
+    minDelayMs: 1000,
+    maxDelayMs: 3000,
+  },
+  debug: true
 });
 
-const track = await wsper.spotify.search("never gonna give you up", { limit: 3 });
-const video = await wsper.youtube.getVideo("dQw4w9WgXcQ");
+// Run parallel requests through the rate-limited queue
+const [spotifyTrack, ytVideo] = await Promise.all([
+  wsper.spotify.search("never gonna give you up", { limit: 1 }),
+  wsper.youtube.getVideo("dQw4w9WgXcQ")
+]);
 
-console.log(track.ok, video.ok);
+console.log("Spotify Search Result:", spotifyTrack.ok);
+console.log("YouTube Video Result:", ytVideo.ok);
 ```
 
-`WsperScraper` currently exposes `spotify`, `twitter`, `threads`, `instagram`, `pinterest`, and `youtube`. Other scrapers are exported as named classes.
+---
 
-## Response Shape
+## Core Concepts & Architecture
 
-Scraper methods return `WsperResponse<TData>`:
+### Unified WsperResponse Envelope
+Every public scraper method returns a standard `WsperResponse<TData>` envelope. This prevents uncaught runtime errors and simplifies error checks.
 
 ```ts
 export interface WsperResponse<TData, TMeta extends WsperResponseMeta = WsperResponseMeta> {
-  ok: boolean;
-  statusCode: number;
-  data: TData | null;
-  error: {
+  ok: boolean;          // True if request succeeded and parsing completed
+  statusCode: number;  // HTTP response code (or internal fallback: 400, 422, 500)
+  data: TData | null;  // Type-safe payload on success; null on error
+  error: {             // Normalized error details on failure; null on success
     code: string;
     message: string;
     details?: Record<string, unknown>;
   } | null;
-  meta: TMeta;
+  meta: TMeta;         // Operational metadata
 }
 
 export interface WsperResponseMeta {
@@ -110,570 +137,751 @@ export interface WsperResponseMeta {
 }
 ```
 
-Recommended handling:
-
+#### Recommended Code Pattern:
 ```ts
-const response = await scraper.search("query");
+const result = await scraper.search("query");
 
-if (response.ok && response.data !== null) {
-  console.log(response.data);
+if (!result.ok) {
+  // Gracefully handle failures without try-catch blocks
+  console.error(`Scraper failed: ${result.error?.code} - ${result.error?.message}`);
+  if (result.error?.details) {
+    console.error("Debug Context:", result.error.details);
+  }
 } else {
-  console.error(response.statusCode, response.error?.code, response.error?.message);
+  // Safely consume data
+  console.log("Scraped Data:", result.data);
 }
 ```
 
-## Usage Examples
+### Request Pacing & Rate Limiting
+To respect external platform policies and prevent IP bans, `wsper-js` integrates a rate-limited task queue (`p-queue`) directly into the HTTP layer.
+
+Configure queue parameters in `QueueOptions` at scraper construction:
+
+```ts
+import { SpotifyScraper } from "wsper-js";
+
+const scraper = new SpotifyScraper({
+  queue: {
+    concurrency: 1,      // Max active parallel connections
+    intervalMs: 1000,    // Rate-limiting window
+    intervalCap: 3,      // Max requests allowed per window (3 requests/sec)
+    minDelayMs: 500,     // Minimum random delay (jitter) before each request
+    maxDelayMs: 1500,    // Maximum random delay (jitter) before each request
+    timeoutMs: 30000,    // Max request lifetime before abortion
+    retries: 3           // Bounded retries for retryable status codes (e.g. 429, 503)
+  }
+});
+```
+
+### Safe HTTP Client & Rotation
+All HTTP tasks execute through a customized `HttpClient` wrapper around Axios. It features:
+* **Browser Profile Rotation**: Automatically rotates randomized, realistic HTTP headers and User-Agent strings.
+* **SSRF Protections**: Restricts destination URLs to standard protocols (`http:`, `https:`). Block private networks (`127.0.0.1`, `10.0.0.0/8`, etc.) by default. Set `allowPrivateNetwork: true` strictly during local testing or mock server environments.
+* **Retry-After Compliance**: Automatically parses `Retry-After` response headers on HTTP 429 and delays subsequent queued requests.
+
+### Credentials & Authentication Configuration
+
+Every scraper in `wsper-js` is designed to run in **public mode** by default. However, many platforms require active session cookies, API tokens, or keys to fetch data successfully. 
+
+The library resolves credentials sequentially per scraper instance:
+1. **Constructor Options** (Highest priority, recommended)
+2. **Environment Variables** (System fallback)
 
-The examples below use public exports from `src/index.ts` and representative response fields from implementation and tests.
+---
 
-### LyricsScraper
+#### 1. Input Formats: Raw Cookie String vs. Structured Object
 
-Source: LRCLIB JSON API at `https://lrclib.net/api/search`.
+When initializing a scraper, the `credentials` option accepts either a **raw cookie string** or a **structured object** (`WsperCredentials`):
 
+##### A. Raw Cookie String Shortcut (Convenient)
+If you pass a string directly to `credentials`, the library automatically normalizes it into a `{ cookie: string }` object and extracts properties like CSRF tokens.
 ```ts
-import { LyricsScraper } from "wsper-js";
+const instagram = new InstagramScraper({
+  credentials: "sessionid=12345678%3Aabcde...; csrftoken=xyz...; ds_user_id=87654321"
+});
+```
+
+##### B. Structured Object Config (Granular)
+For advanced configurations, pass an object containing explicit fields:
+```ts
+const twitter = new TwitterScraper({
+  credentials: {
+    cookie: "auth_token=abc123xyz...; ct0=def456...",
+    csrfToken: "def456...", // Optional: explicitly provide the csrfToken (X-CSRFToken header)
+    userAgent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) ..." // Override the default user-agent profile
+  }
+});
+```
+
+---
 
-const scraper = new LyricsScraper();
-const result = await scraper.search("after hours the weeknd");
+#### 2. Platform-by-Platform Credentials Guide
 
-console.log(result.data);
+Below are the exact options and code structures for initializing each credentialed scraper:
+
+##### Instagram Scraper (`InstagramScraper`)
+* **Required Credential**: Legitimate session cookie.
+* **Auto-Extraction**: The client automatically parses `csrftoken` out of the cookie string and injects it as the `X-IG-App-ID` and `X-CSRFToken` headers.
+```ts
+import { InstagramScraper } from "wsper-js";
+
+const instagram = new InstagramScraper({
+  credentials: {
+    cookie: "sessionid=YOUR_INSTAGRAM_SESSION_ID; csrftoken=YOUR_CSRF_TOKEN;",
+    userAgent: "Mozilla/5.0 (iPhone; CPU iPhone OS 17_4 like Mac OS X) ..." // Recommended mobile profile
+  }
+});
 ```
 
-Representative output:
+##### Twitter/X Scraper (`TwitterScraper`)
+* **Required Credential**: Session cookies containing `auth_token` and `ct0` (CSRF token).
+* **Usage**:
+```ts
+import { TwitterScraper } from "wsper-js";
 
-```json
-{
-  "title": "After Hours",
-  "lyrics": "Oh, baby, where are you now?",
-  "link": "https://lrclib.net/api/get/98765"
-}
+const twitter = new TwitterScraper({
+  credentials: {
+    cookie: "auth_token=YOUR_AUTH_TOKEN; ct0=YOUR_CSRF_TOKEN;",
+    csrfToken: "YOUR_CSRF_TOKEN" // Must match the value in the cookie (ct0)
+  }
+});
 ```
 
-### WallpaperScraper
+##### Character.AI Scraper (`CaiScraper`)
+* **Required Credential**: Bearer Auth Token.
+* **Usage**:
+```ts
+import { CaiScraper } from "wsper-js";
 
-Source: Wallhaven search API at `https://wallhaven.cc/api/v1/search`.
+const cai = new CaiScraper({
+  credentials: {
+    bearerToken: "YOUR_CHARACTER_AI_API_TOKEN" // Injected as "Authorization: Bearer <token>"
+  }
+});
+```
 
+##### Spotify Scraper (`SpotifyScraper`)
+* **Required Credential**: Spotify Developer Client ID and Secret (from developer.spotify.com).
+* **Usage**: Configure via the dedicated `spotifyCredentials` object in the options.
 ```ts
-import { WallpaperScraper } from "wsper-js";
+import { SpotifyScraper } from "wsper-js";
+
+const spotify = new SpotifyScraper({
+  spotifyCredentials: {
+    clientId: "YOUR_SPOTIFY_CLIENT_ID",
+    clientSecret: "YOUR_SPOTIFY_CLIENT_SECRET",
+    callbackUrl: "http://localhost:3000/callback", // Optional
+    market: "ID"                                 // Optional: country ISO code
+  }
+});
+```
 
-const scraper = new WallpaperScraper();
-const result = await scraper.search("cyberpunk");
+##### YouTube Scraper (`YouTubeScraper`)
+* **Configuration**: Requires paths to system binaries rather than typical session credentials.
+* **Factory Method**: Use `YouTubeScraper.create` to automatically search `PATH` or Python virtual environments for `yt-dlp` and `ffmpeg`.
+```ts
+import { YouTubeScraper } from "wsper-js";
+
+// Manual configuration
+const yt = new YouTubeScraper({
+  ytdlpPath: "C:\\tools\\yt-dlp.exe",
+  ffmpegPath: "C:\\tools\\ffmpeg.exe",
+  ffprobePath: "C:\\tools\\ffprobe.exe",
+  outputDir: "./downloads/vids"
+});
 
-console.log(result.data?.total);
-console.log(result.data?.results[0]);
+// Auto-detection factory method (Recommended)
+const ytAuto = await YouTubeScraper.create({
+  pythonPath: "python3", // Tries "python3 -m yt_dlp" fallback if not in PATH
+  outputDir: "./downloads/vids"
+});
 ```
 
-Representative output:
+##### remove.bg Scraper (`RemovebgScraper`)
+* **Required Credential**: Official remove.bg API key.
+* **Usage**:
+```ts
+import { RemovebgScraper } from "wsper-js";
 
-```json
-{
-  "total": 1,
-  "results": [
-    {
-      "title": "Wallpaper sky123",
-      "resolution": "1920x1080",
-      "image": "https://w.wallhaven.cc/full/sky123.jpg",
-      "page": "https://wallhaven.cc/w/sky123"
-    }
-  ]
-}
+const removebg = new RemovebgScraper({
+  credentials: {
+    apiKey: "YOUR_REMOVE_BG_API_KEY"
+  }
+});
 ```
 
-### WwCharScraper
+---
+
+#### 3. Configuring Credentials in the Unified `WsperScraper`
 
-Source: Wuthering Waves Fandom MediaWiki parse API.
+The aggregate entrypoint class `WsperScraper` exposes a nested configuration layout, allowing you to bootstrap all credential-requiring scrapers simultaneously:
 
 ```ts
-import { WwCharScraper } from "wsper-js";
+import { WsperScraper } from "wsper-js";
 
-const scraper = new WwCharScraper();
-const result = await scraper.getCharacter("Jin Hsi");
+const wsper = new WsperScraper({
+  // 1. Spotify developer credentials (dedicated object)
+  spotifyCredentials: {
+    clientId: "YOUR_SPOTIFY_CLIENT_ID",
+    clientSecret: "YOUR_SPOTIFY_CLIENT_SECRET",
+  },
+  // 2. Platform-specific session credentials
+  credentials: {
+    instagram: "sessionid=IG_SESSION_COOKIE; csrftoken=IG_CSRF_TOKEN",
+    twitter: {
+      cookie: "auth_token=X_AUTH_COOKIE; ct0=X_CSRF_COOKIE",
+      csrfToken: "X_CSRF_COOKIE"
+    },
+    cai: {
+      bearerToken: "CHARACTER_AI_WS_TOKEN"
+    },
+    threads: "sessionid=THREADS_SESSION_COOKIE; csrftoken=THREADS_CSRF_TOKEN",
+    pinterest: "sessionid=PINTEREST_SESSION_COOKIE"
+  },
+  // 3. YouTube binary paths configuration
+  youtube: {
+    ytdlpPath: "yt-dlp",
+    ffmpegPath: "ffmpeg"
+  }
+});
 
-console.log(result.data);
+// Access child clients directly
+const isIgOk = (await wsper.instagram.getUserProfile("some_user")).ok;
 ```
 
-Representative output:
+---
 
-```json
-{
-  "title": "Jiyan",
-  "slug": "Jin_Hsi",
-  "url": "https://wutheringwaves.fandom.com/wiki/Jin_Hsi",
-  "bio": "Bio karakter.",
-  "profile": {},
-  "images": []
-}
-```
+#### 4. Environment Variables Configuration
 
-### HokInfoScraper
+If you do not pass credentials in the constructor, `wsper-js` will check your system environment variables. You can store these in a `.env` file in the root of your application.
 
-Source: Honor of Kings Fandom MediaWiki parse API.
+> [!WARNING]
+> The library itself does **not** load `.env` files automatically to avoid side-effects. You must import `dotenv` or run your Node.js application with the `--env-file` flag (Node 20.6+).
 
-```ts
-import { HokInfoScraper } from "wsper-js";
+##### Node.js 20.6+ Native Env Loading:
+```bash
+node --env-file=.env index.js
+```
 
-const scraper = new HokInfoScraper();
-const result = await scraper.getCharacter("Angela");
+##### Standard dotenv Import:
+```ts
+import "dotenv/config";
+import { WsperScraper } from "wsper-js";
 
-console.log(result.data?.profile);
+const wsper = new WsperScraper(); // Reads WSPER_* environment variables automatically
 ```
 
-Representative output:
+##### Supported Env Keys reference:
+```ini
+# Spotify Developer API
+WSPER_SPOTIFY_CLIENT_ID=your_client_id
+WSPER_SPOTIFY_CLIENT_SECRET=your_client_secret
+WSPER_SPOTIFY_CALLBACK_URL=http://localhost:3000/callback
+WSPER_SPOTIFY_MARKET=US
 
-```json
-{
-  "title": "Sun Wukong",
-  "image": null,
-  "profile": {
-    "Role": "Fighter"
-  },
-  "bio": "Bio singkat karakter.",
-  "skills": [],
-  "lore": null,
-  "url": "https://honor-of-kings.fandom.com/wiki/Sun%20Wukong"
-}
+# Social Media Session Cookies
+WSPER_INSTAGRAM_COOKIE="sessionid=ig_cookie_val; csrftoken=ig_csrf_val;"
+WSPER_THREADS_COOKIE="sessionid=threads_cookie_val; csrftoken=threads_csrf_val;"
+WSPER_TWITTER_COOKIE="auth_token=twitter_cookie_val; ct0=twitter_csrf_val;"
+WSPER_PINTEREST_COOKIE="sessionid=pinterest_cookie_val;"
+WSPER_TIKTOK_COOKIE="sessionid=tiktok_cookie_val;"
+WSPER_FACEBOOK_COOKIE="c_user=fb_cookie_val; xs=fb_xs_val;"
+WSPER_BILIBILI_COOKIE="SESSDATA=bili_cookie_val;"
+
+# Character.AI Auth
+WSPER_CAI_TOKEN=your_cai_bearer_token
+
+# AI Tools API Keys
+REMOVEBG_API_KEY=your_remove_bg_api_key
 ```
 
-### CapCutScraper
+---
+
+## In-Depth Feature Modules
 
-Source: WordPress-style resolver endpoint, defaulting to `https://capdownloader.com/wp-json/aio-dl/video-data/`.
+### 1. Brat Generator (Stickers & Media)
+The Brat module provides programmatic text-to-media rendering, applying the classic green-and-black aesthetic (popularized by Charli XCX) or customized styles.
 
+#### Generate static Brat Images (PNG/JPG/WEBP)
 ```ts
-import { CapCutScraper } from "wsper-js";
+import { BratGenerator } from "wsper-js";
+
+const brat = new BratGenerator();
 
-const scraper = new CapCutScraper();
-const result = await scraper.download("https://www.capcut.com/t/Zs82gHj1a/");
+const imageResult = await brat.generate({
+  canvas: { preset: "1:1", width: 1024 }, // Aspect presets: "1:1", "9:16", "16:9"
+  text: {
+    value: "kamu pas kecil pernah nelen magnet ya? menarik banget soalnya",
+    align: "justify", // "left" | "center" | "right" | "justify"
+    color: "#111111",
+    blur: 0,           // >0 to blur only the text pixels
+  },
+  background: { type: "solid", color: "#8ace00" }, // or "linear-gradient" / "radial-gradient"
+  backgroundBlur: 0,   // blur radius for background layout (frosted-glass)
+  output: {
+    type: "image",
+    format: "png",
+    path: "./downloads/brat.png"
+  }
+});
 
-console.log(result.data);
+console.log("Saved static Brat image to:", imageResult.path);
+```
+
+#### Generate Animated Brat GIFs & Videos
+```ts
+const gifResult = await brat.generate({
+  text: {
+    value: "charli xcx is so brat i can't even",
+    align: "center"
+  },
+  background: { type: "solid", color: "#8ace00" },
+  animation: {
+    enabled: true,
+    mode: "word",       // "word" (appear word-by-word) or "character" (typewriter effect)
+    direction: "left-to-right",
+    fps: 15,            // frame rate
+    textSpeed: 120,     // milliseconds delay per word/character
+  },
+  output: {
+    type: "gif",
+    path: "./downloads/animated_brat.gif"
+  }
+});
 ```
 
-Representative output:
+#### WhatsApp Sticker Generation & Media Format Conversion
+```ts
+// 1. Convert image buffer to WhatsApp-compliant sticker (512x512 WebP with overlays)
+const stickerBuffer = await brat.imageToSticker(imageResult.buffer, {
+  size: 512,
+  format: "webp",
+  top: "BRAT ENERGY",
+  bottom: "2026",
+});
 
-```json
-{
-  "videoUrl": "https://cdn.example/video.mp4"
-}
+// 2. Transcode formats (requires ffmpeg)
+const mp4Buffer = await brat.gifToMp4("./downloads/animated_brat.gif", "./downloads/brat.mp4", { fps: 24 });
+const webmBuffer = await brat.gifToWebm("./downloads/animated_brat.gif", "./downloads/brat.webm");
+const reassembledGif = await brat.mp4ToGif("./downloads/brat.mp4", "./downloads/transcoded.gif");
 ```
 
-### ImgUpscalerScraper
+---
 
-Source: `https://get1.imglarger.com` upload and status endpoints.
+### 2. Analytics Chart Image Generator
+The `ChartGenerator` creates high-resolution visual statistics cards, posters, and dashboard widgets containing comparative group-and-user trends using `@napi-rs/canvas`.
 
 ```ts
-import { readFile } from "node:fs/promises";
-import { ImgUpscalerScraper } from "wsper-js";
+import { ChartGenerator, MonthlyPoint, WeeklyPoint } from "wsper-js";
+
+const chart = new ChartGenerator();
+
+const monthlyData: MonthlyPoint[] = [
+  { label: "JAN", group: 120, user: 90 },
+  { label: "FEB", group: 150, user: 110 },
+  { label: "MAR", group: 240, user: 180 },
+];
+
+const weeklyData: WeeklyPoint[] = [
+  { label: "MON", group: 40, user: 20 },
+  { label: "TUE", group: 35, user: 25 },
+  { label: "WED", group: 50, user: 30 },
+];
+
+const chartImageBuffer = await chart.generateAnalyticsStatsImage({
+  title: "Application Traffic Report",
+  subtitle: "Comparison: System Group vs Active Users",
+  monthly: monthlyData,
+  weekly: weeklyData,
+  width: 1024,
+  height: 1024,
+  output: "./downloads/traffic_report.png",
+  footer: "Generated via wsper-js Analytics module",
+  // Choose model style: "vintage-poster" | "modern-dashboard" | "minimal-report" | "dark-neon" | "compact-card"
+  model: "modern-dashboard",
+  theme: {
+    // Optionally override specific theme colors
+    background: "#0f172a",
+    ink: "#ffffff",
+    groupLine: "#38bdf8",
+    userLine: "#34d399",
+  }
+});
+```
 
-const image = await readFile("./photo.jpg");
-const scraper = new ImgUpscalerScraper();
-const result = await scraper.upscaleBuffer(image, "photo.jpg", 4);
+---
 
-console.log(result.data);
-```
+### 3. Safe Downloader Primitive
+The `Downloader` class allows developers to download files to local filesystems, enforcing safe paths, restricting traversal, and asserting file sizes.
 
-Representative output:
+```ts
+import { Downloader } from "wsper-js";
+
+// Initialize and bind to a specific safe download directory
+const downloader = new Downloader("./downloads/sandbox");
 
-```json
-{
-  "originalPath": null,
-  "outputPath": null,
-  "resultUrl": "https://cdn.test/out.jpg",
-  "scale": 4
+try {
+  const downloadResult = await downloader.download(
+    "https://example.com/large-assets.zip",
+    "archives/assets.zip", // Saved relatively inside './downloads/sandbox'
+    {
+      overwrite: true,
+      maxSizeBytes: 100 * 1024 * 1024,       // Limit files to 100MB
+      allowedMimeTypes: ["application/zip"], // Whitelist content-type headers
+      timeoutMs: 60000                       // Set download timeout
+    }
+  );
+  console.log("Download complete:", downloadResult.outputPath);
+} catch (err) {
+  console.error("Secure download failed:", err.message);
 }
 ```
 
-### PhotoAiScraper
+---
+
+## Scrapers Usage Catalog
 
-Source: `https://photoai.imglarger.com`.
+### Social Media & AI Messaging
+
+#### Character.AI (`CaiScraper`)
+Integrates search, Chat-V2, and TTS (Text-to-Speech) generation with session reuse.
 
 ```ts
-import { readFile } from "node:fs/promises";
-import { PhotoAiScraper } from "wsper-js";
+import { CaiScraper } from "wsper-js";
+
+const cai = new CaiScraper({ credentials: { bearerToken: "YOUR_CAI_TOKEN" } });
+
+// Search for a character
+const search = await cai.searchCharacters("Mario");
+const marioId = search.data?.[0]?.externalId;
+
+// Send chat message and generate TTS Audio URL
+if (marioId) {
+  const reply = await cai.chat({
+    characterId: marioId,
+    message: "It's-a me, who are you?",
+    voiceId: "4fdd6bc1-c659-4587-b462-53f569b39078" // Optional voice ID
+  });
 
-const image = await readFile("./portrait.jpg");
-const scraper = new PhotoAiScraper();
+  console.log("Response text:", reply.data?.text);
+  console.log("TTS audio URL:", reply.data?.audioUrl);
 
-const upload = await scraper.uploadBuffer(image, "portrait.jpg");
-if (upload.ok && upload.data !== null) {
-  const status = await scraper.checkStatus(upload.data.code);
-  console.log(status.data);
+  // Clean up WebSocket session
+  await cai.disconnectCharacterSession(marioId);
 }
 ```
 
-Representative output:
+#### Instagram (`InstagramScraper`)
+Fetches profile endpoints and user posts. Requires a legitimate authenticated session cookie.
 
-```json
-{
-  "status": "success",
-  "downloadUrl": "https://cdn.test/out.jpg",
-  "raw": {
-    "status": "success",
-    "downloadUrl": "https://cdn.test/out.jpg"
-  }
-}
+```ts
+import { InstagramScraper } from "wsper-js";
+
+const ig = new InstagramScraper({ credentials: "sessionid=YOUR_COOKIE..." });
+
+const profile = await ig.getUserProfile("charlixcx");
+console.log("Bio:", profile.data?.bio);
+
+const posts = await ig.getUserPosts("charlixcx", { limit: 12 });
+```
+
+#### Twitter/X (`TwitterScraper`)
+Reads user timelines and tweets. Custom `csrfToken` is extracted automatically if cookies are passed.
+
+```ts
+import { TwitterScraper } from "wsper-js";
+
+const x = new TwitterScraper({ credentials: "auth_token=YOUR_TOKEN..." });
+
+const tweets = await x.getUserTimeline("elonmusk");
+const singleTweet = await x.getTweetDetail("1234567890");
 ```
 
-### FaceswapScraper
+---
+
+### Streaming & Media Resolvers
 
-Source: `https://api.lovefaceswap.com`.
+#### Spotify (`SpotifyScraper`)
+Retrieves tracks, albums, playlists, and downloads MP3 wrappers (using external `yt-dlp` enrichment).
 
 ```ts
-import { readFile } from "node:fs/promises";
-import { FaceswapScraper } from "wsper-js";
+import { SpotifyScraper } from "wsper-js";
 
-const [source, target] = await Promise.all([
-  readFile("./source-face.jpg"),
-  readFile("./target.jpg"),
-]);
+const spotify = new SpotifyScraper(); // Can take optional spotifyCredentials
 
-const scraper = new FaceswapScraper();
-const result = await scraper.process(source, target);
+// Get enriched metadata
+const track = await spotify.getTrack("4PTG3Z6ehGkBF3zI7Ywtqs", { enrichYtDlp: true });
+console.log("Spotify Title:", track.data?.name);
+console.log("Associated YT Link:", track.data?.enriched?.youtubeUrl);
 
-console.log(result.data);
+// Download track locally (saves artwork and MP3 file)
+const download = await spotify.downloadPost({
+  trackUrlOrId: "4PTG3Z6ehGkBF3zI7Ywtqs",
+  outputDir: "./downloads/music",
+  audioFormat: "mp3",
+  includeMetadata: true
+});
 ```
 
-Representative output:
+#### YouTube (`YouTubeScraper`)
+Queries search, scrapes playlists, and triggers local transcode scripts.
 
-```json
-{
-  "job_id": "job-1",
-  "image": "https://cdn.test/out.jpg"
-}
+```ts
+import { YouTubeScraper } from "wsper-js";
+
+const yt = new YouTubeScraper();
+
+const video = await yt.getVideo("dQw4w9WgXcQ");
+const search = await yt.searchVideos("lofi beats", { limit: 5 });
+
+// Downloads video/audio (requires yt-dlp in PATH)
+await yt.downloadVideo("dQw4w9WgXcQ", { outputDir: "./downloads/vids" });
+await yt.downloadAudio("dQw4w9WgXcQ", { outputDir: "./downloads/vids", audioFormat: "mp3" });
 ```
 
-### UpscalerScraper
+---
 
-Source: `https://aienhancer.ai`.
+### Indonesian Reference Services
+
+#### Prayer Times (`BimasIslamScraper`)
+Fetches official prayer schedules for provinces and cities in Indonesia from Kemenag.
 
 ```ts
-import { readFile } from "node:fs/promises";
-import { UpscalerScraper } from "wsper-js";
+import { BimasIslamScraper } from "wsper-js";
+
+const kemenag = new BimasIslamScraper();
 
-const image = await readFile("./photo.jpg");
-const scraper = new UpscalerScraper();
-const result = await scraper.upscaleBuffer(image, "image/jpeg");
+const provinces = await kemenag.getProvinces();
+const cities = await kemenag.getCities(provinces.data?.[0]?.id || "");
 
-console.log(result.data);
+// Fetch prayer schedules for specific region (Jakarta ID=18), June 2026
+const schedule = await kemenag.getPrayerTimes("18", "18", 6, 2026);
+console.log("Prayer Times for June 1st:", schedule.data?.[0]);
 ```
 
-Representative output:
+#### Earthquake & Weather (`BMKGScraper` & `CuacaScraper`)
+Retrieves BMKG meteorological data feeds.
 
-```json
-{
-  "id": "task-1",
-  "input": "https://cdn.test/in.jpg",
-  "output": "https://cdn.test/out.jpg"
-}
+```ts
+import { BMKGScraper, CuacaScraper } from "wsper-js";
+
+const bmkg = new BMKGScraper();
+const cuaca = new CuacaScraper();
+
+// 1. Get recent earthquake alerts
+const earthquakes = await bmkg.getRecentEarthquakes();
+console.log("Recent Gempa:", earthquakes.data?.gempaTerbuka);
+
+// 2. Get local weather forecast by latitude & longitude
+const localWeather = await cuaca.getWeatherByCoordinate(-6.2, 106.8);
 ```
 
-### StalkScraper
+---
 
-Source: npm registry API at `https://registry.npmjs.org`.
+### Global Reference & Search APIs
+
+#### Rest Countries (`RestCountriesScraper`)
+Provides country profiles. Use standard bounds to prevent unbounded HTTP payloads.
 
 ```ts
-import { StalkScraper } from "wsper-js";
+import { RestCountriesScraper } from "wsper-js";
 
-const scraper = new StalkScraper();
-const result = await scraper.getNpmPackage("axios");
-
-console.log(result.data?.title);
-console.log(result.data?.install);
-```
-
-Representative output:
-
-```json
-{
-  "title": "@scope/pkg",
-  "language": "",
-  "publish": "2026-05-01T00:00:00.000Z",
-  "readme": "",
-  "explore": "https://www.npmjs.com/package/@scope/pkg",
-  "dependencies": "0",
-  "dependents": "0",
-  "version_count": "1",
-  "keywords": [],
-  "install": "npm install @scope/pkg",
-  "info": [],
-  "collaborator": []
-}
+const rest = new RestCountriesScraper();
+
+// Explicitly choose required fields for performance
+const countries = await rest.getAll(["name", "cca2", "population", "flags"]);
+const indonesia = await rest.getByName("Indonesia");
+```
+
+#### Wikipedia (`WikipediaScraper`)
+Search and summarize wiki entries.
+
+```ts
+import { WikipediaScraper } from "wsper-js";
+
+const wiki = new WikipediaScraper();
+
+const summary = await wiki.getSummary("Artificial Intelligence", "en");
+console.log("Excerpt:", summary.data?.extract);
 ```
 
-### MediafireScraper
+#### OpenMeteo (`OpenMeteoScraper`)
+Queries forecasts and current weather parameters.
+
+```ts
+import { OpenMeteoScraper } from "wsper-js";
+
+const weather = new OpenMeteoScraper();
+const forecast = await weather.getForecast(-6.2, 106.8, { hourly: "temperature_2m" });
+```
 
-Source: Mediafire public file page HTML.
+#### USGS Earthquakes (`UsgsEarthquakeScraper`)
+Reads active seismic activity feeds.
 
 ```ts
-import { MediafireScraper } from "wsper-js";
+import { UsgsEarthquakeScraper } from "wsper-js";
+
+const usgs = new UsgsEarthquakeScraper();
+const feed = await usgs.getSummary("all_day"); // "all_hour" | "all_day" | "all_week"
+```
+
+---
+
+### Scholarly & Academic Metadata
+
+#### Crossref (`CrossrefScraper`)
+Search academic DOI indexes.
 
-const scraper = new MediafireScraper();
-const result = await scraper.getLink(
-  "https://www.mediafire.com/file/ipnyzofjcwri357/test-10mb.bin/file",
-);
+```ts
+import { CrossrefScraper } from "wsper-js";
 
-console.log(result.data);
+// Politeness parameter provides an email to target servers
+const crossref = new CrossrefScraper({ politeMailTo: "developer@example.com" });
+const paper = await crossref.getWorkByDoi("10.1038/nature14539");
 ```
 
-Representative output:
+#### OpenAlex (`OpenAlexScraper`)
+Queries scholarly graphs, works, institutions, and authors.
 
-```json
-{
-  "downloadUrl": "https://download.example/myfile.zip",
-  "fileName": "My_File.zip",
-  "fileSize": "50 MB",
-  "fileType": "ZIP"
-}
+```ts
+import { OpenAlexScraper } from "wsper-js";
+
+const openAlex = new OpenAlexScraper();
+const searchWorks = await openAlex.searchWorks("machine learning", { limit: 10 });
 ```
 
-## Available Scrapers
-
-| Scraper | Purpose | Source/API | Auth/Cookie required? | Example file | Notes |
-| --- | --- | --- | --- | --- | --- |
-| `AlkitabScraper` | Bible verse search | `alkitab.me` | No | `examples/alkitab.example.ts` | `search(query)` |
-| `AnimeQuoteScraper` | Random anime quote | `otakotaku.com` | No | `examples/anime-quote.example.ts` | `getRandom()` |
-| `AnimeRandomScraper` | Random anime character image | GitHub raw anime dataset | No | `examples/anime-random.example.ts` | `getImage(character)`, `random()` |
-| `BiliBiliScraper` | BiliBili search and video info | `api.bilibili.com` | Optional cookie | `examples/bilibili.example.ts` | Cookie may unlock authenticated stream access |
-| `BMKGScraper` | Indonesian earthquake and weather feeds | `data.bmkg.go.id`, `nowcasting.bmkg.go.id` | No | `examples/bmkg.example.ts` | Autogempa, gempa dirasakan, nowcasting, forecast |
-| `CapCutScraper` | Resolve CapCut template video URL | `capdownloader.com/wp-json/aio-dl/video-data/` | No | `examples/capcut.example.ts` | Mocked in example runner |
-| `CuacaScraper` | Indonesian weather by location/coordinate | BMKG weather APIs | Optional API key for warnings | `examples/cuaca.example.ts` | Reads optional `BMKG_WARNING_API_KEY` in example |
-| `DrakorScraper` | Korean drama search/list/detail | `drakorkita30.kita.baby` | No | `examples/drakor.example.ts` | `search`, `detail`, `ongoing`, `getAll` |
-| `DramaboxScraper` | Dramabox search | `dramabox.com` | No | `examples/dramabox.example.ts` | `search(query)` |
-| `FaceswapScraper` | Face-swap image processing | `api.lovefaceswap.com` | No | `examples/faceswap.example.ts` | Mocked in example runner |
-| `HokInfoScraper` | Honor of Kings character info | Fandom MediaWiki parse API | No | `examples/hok-info.example.ts` | Uses `api.php?action=parse` |
-| `HtmlToJpgScraper` | HTML file to JPG conversion | `api.freeconvert.com` | No credential in code | `examples/html-to-jpg.example.ts` | File-based conversion; skipped in runner without fixture |
-| `IkiruMangaScraper` | Manga search | `02.ikiru.wtf` | No | `examples/ikiru-manga.example.ts` | Mock server fallback available |
-| `ImageScraper` | Safebooru image search | `safebooru.org` | No | `examples/image.example.ts` | Current site type: `safebooru` |
-| `ImgUpscalerScraper` | Image upscaling | `get1.imglarger.com` | No | `examples/img-upscaler.example.ts` | Mocked in example runner |
-| `InstagramScraper` | Profile, feed, post, download | `instagram.com` web/API endpoints | Internal defaults; custom cookie supported | `examples/instagram.example.ts` | Use only legitimate session cookies |
-| `KomikindoScraper` | Manga search/detail | `komikindo.ch` | No | `examples/komikindo.example.ts` | `search`, `getDetail` |
-| `LyricsScraper` | Lyrics search | `lrclib.net` JSON API | No | `examples/lyrics.example.ts` | Replaced blocked HTML scraping with API integration |
-| `MConverterScraper` | File conversion helpers | `mconverter.eu` | No | `examples/mconverter.example.ts` | `getTargets`, `convert`, `convertBuffer` |
-| `McAddonScraper` | Minecraft addon search/detail | `mmcreviews.com` | No | `examples/mcaddon.example.ts` | `search`, `getDetail`, `getAddon` |
-| `MediafireScraper` | Resolve Mediafire download link | Mediafire public HTML page | No | `examples/mediafire.example.ts` | Default example uses active 10MB test file |
-| `ModAndroidScraper` | Android APK/mod search aggregations | `an1.com`, `modyolo.com`, `aptoide.com`, `uptodown.com` | No | `examples/mod-android.example.ts` | `android1`, `modyolo`, `aptoide`, `uptodown`, `searchAll` |
-| `OcrScraper` | OCR image scan | `newocr.com` | No | `examples/ocr.example.ts` | File/buffer based |
-| `PhotoAiScraper` | Photo AI upload/status | `photoai.imglarger.com` | No | `examples/photo-ai.example.ts` | Mocked in example runner |
-| `PinterestScraper` | Pin search, detail, download | `pinterest.com` | Internal defaults; custom cookie supported | `examples/pinterest.example.ts` | Supports `credentials` option |
-| `PlayStoreScraper` | Google Play app search | `play.google.com` | No | `examples/playstore.example.ts` | `search(query, limit)` |
-| `ResepScraper` | Recipe search | `cookpad.com` | No | `examples/resep.example.ts` | Returns recipe items |
-| `SakuraNovelScraper` | Novel search/detail/chapter | `sakuranovel.id` | No | `examples/sakura-novel.example.ts` | Mock server fallback available |
-| `SpotifyScraper` | Spotify track, album, playlist, search, downloads | Spotify Web API and Accounts API | Internal defaults; custom client credentials supported | `examples/spotify.example.ts` | Partial custom credentials are rejected |
-| `StalkScraper` | npm package metadata lookup | `registry.npmjs.org` | No | `examples/stalk.example.ts` | Default example query is `axios` |
-| `ThreadsScraper` | Threads profile, post, search, download | `threads.net` web/API endpoints | Internal defaults; custom cookie supported | `examples/threads.example.ts` | Use only legitimate session cookies |
-| `TopAnimeScraper` | MyAnimeList top anime list | `myanimelist.net` | No | `examples/top-anime.example.ts` | `getTopAnime(limit)` |
-| `TwitterScraper` | Tweet, profile, search, timeline, downloads | `x.com/i/api/graphql` | Cookie/CSRF commonly required | `examples/twitter.example.ts` | Supports `credentials` option |
-| `UguuScraper` | Temporary file upload | `uguu.se/upload` | No | `examples/uguu.example.ts` | `upload(buffer, filename)` |
-| `UpscalerScraper` | Image enhancement | `aienhancer.ai` | No | `examples/upscaler.example.ts` | Rejects remote URL string input |
-| `VideyScraper` | Video upload | `videy.co/api/upload` | No | `examples/videy.example.ts` | `upload`, `uploadBuffer` |
-| `WallpaperScraper` | Wallpaper search | `wallhaven.cc/api/v1/search` | No | `examples/wallpaper.example.ts` | Replaced blocked HTML scraping with API integration |
-| `Webp2Mp4Scraper` | WebP to MP4/PNG conversion | `ezgif.com` | No | `examples/webp2mp4.example.ts` | `toMp4`, `toPng` |
-| `WwCharScraper` | Wuthering Waves character info | Fandom MediaWiki parse API | No | `examples/ww-char.example.ts` | Uses `api.php?action=parse` |
-| `YouTubeScraper` | YouTube metadata, search, playlist, channel, downloads | `yt-dlp`, `play-dl`, YouTube pages | No cookie option exposed in current scraper options | `examples/youtube.example.ts` | Media download features need external tools |
-
-## What's New
-
-The latest scraper reliability pass fixed 12 failing scraper functions and their corresponding tests.
-
-- `LyricsScraper` now uses LRCLIB's public JSON API instead of a Cloudflare-protected Musixmatch HTML page.
-- `WallpaperScraper` now uses Wallhaven's public search API instead of a Cloudflare-protected Wallpaperflare HTML page.
-- `WwCharScraper` and `HokInfoScraper` now use Fandom's MediaWiki parse API (`api.php?action=parse`) and prepend a synthetic `#firstHeading` node before running the existing parsers.
-- `examples/mock-server.ts` now covers WordPress resolver routes, AI tool polling/upload routes, and Fandom API responses.
-- `examples/alllexamp.ts` starts and stops the mock server during the runner lifecycle.
-- `WSPER_MOCK_BASE_URL` is injected into spawned example subprocesses so individual examples can use the local mock endpoint automatically.
-- Default example inputs were updated: `StalkScraper` uses `axios`, `MediafireScraper` uses an active 10MB test file URL, and `HokInfoScraper` uses `Angela`.
-- Verification recorded in `walkthrough.md`: 82 test files passed, 314 tests passed, and the examples runner reported 83 OK, 0 FAIL, 2 SKIP.
-
-## Mock Server and Testing
-
-`examples/mock-server.ts` is a local HTTP server used by the examples runner to provide deterministic responses for endpoints that are rate-limited, depend on third-party availability, or are inconvenient to call during automated checks.
-
-Currently mocked routes include:
-
-| Area | Routes |
-| --- | --- |
-| CapCut | `/wp-json/aio-dl/video-data/` |
-| ImgUpscaler | `/api/UpscalerNew/UploadNew`, `/api/UpscalerNew/CheckStatusNew` |
-| PhotoAi | `/api/PhoAi/Upload`, `/api/PhoAi/CheckStatus` |
-| Faceswap | `/api/face-swap/create-poll`, `/api/common/get` |
-| Upscaler | `/api/v1/r/image-enhance/create`, `/api/v1/r/image-enhance/result` |
-| Fandom Wiki | `/api.php` |
-| WordPress search fixtures | `/wp-admin/admin-ajax.php` |
-
-`examples/alllexamp.ts` starts the mock server, sets `process.env.WSPER_MOCK_BASE_URL`, routes direct scraper demos to the mock server with `http: { allowPrivateNetwork: true }` where needed, runs individual example files as subprocesses, then closes the mock server.
-
-This keeps example validation safer and more repeatable. It avoids making every test depend on live third-party services, Cloudflare-protected HTML pages, or rate-limited AI tool endpoints.
-
-## Running Examples
-
-Run all direct scraper demos and individual example files:
+---
 
-```bash
-npx tsx examples/alllexamp.ts
+### Developer Registry & Package APIs
+
+#### Python Package Index (`PypiScraper`)
+Retrieves package releases and upload history mappings.
+
+```ts
+import { PypiScraper } from "wsper-js";
+
+const pypi = new PypiScraper();
+const pkg = await pypi.getPackage("requests");
+const release = await pypi.getRelease("requests", "2.31.0");
 ```
 
-The runner writes scraper JSON results to `downloads/output/scrapers/` and subprocess logs to `downloads/output/examples/`.
+#### npm Registry (`StalkScraper`)
+Resolves npm package metadata.
 
-Summary fields:
+```ts
+import { StalkScraper } from "wsper-js";
 
-| Field | Meaning |
-| --- | --- |
-| `OK` | The scraper/example returned a successful result. |
-| `FAIL` | The scraper/example returned a failed response or subprocess exit. Auth-required scrapers may fail without valid credentials. |
-| `SKIP` | The runner intentionally skipped an entry, usually because a local fixture is unavailable. |
+const stalk = new StalkScraper();
+const pkg = await stalk.getNpmPackage("axios");
+```
+
+#### OSV Vulnerability Database (`OsvScraper`)
+Find open source package vulnerabilities.
 
-Recorded walkthrough result:
+```ts
+import { OsvScraper } from "wsper-js";
 
-```txt
-OK   : 83
-FAIL : 0
-SKIP : 2
-Total: 85
+const osv = new OsvScraper();
+const query = await osv.queryPackage({ ecosystem: "PyPI", name: "requests", version: "2.20.0" });
 ```
 
-Individual examples can also be run directly:
+---
 
-```bash
-npx tsx examples/lyrics.example.ts "after hours the weeknd"
-npx tsx examples/wallpaper.example.ts cyberpunk
-npx tsx examples/stalk.example.ts axios
-npx tsx examples/mediafire.example.ts "https://www.mediafire.com/file/ipnyzofjcwri357/test-10mb.bin/file"
-npx tsx examples/upscaler.example.ts testassets/photo.jpg
-```
-
-For scrapers that support cookies or credentials, use only accounts and sessions you are authorized to access. Do not hardcode real cookies, tokens, client secrets, or API keys in source files.
-
-## Running Tests and Validation
-
-Package scripts from `package.json`:
-
-| Command | Purpose |
-| --- | --- |
-| `npm run test` | Run all Vitest tests once. |
-| `npm run test:watch` | Run Vitest in watch mode. |
-| `npm run typecheck` | Run TypeScript with `--noEmit`. |
-| `npm run build` | Build production ESM output through `script/build.mjs`. |
-| `npm run build:dev` | Build development output. |
-| `npm run build:prod` | Build production output. |
-| `npm run build:bytecode` | Build bytecode output with `script/build-bytecode.mjs`. |
-| `npm run build:all` | Build production output and bytecode. |
-| `npm run test:instagram` | Run Instagram tests only. |
-| `npm run test:spotify` | Run Spotify tests only. |
-| `npm run test:youtube` | Run YouTube tests only. |
-| `npm run test:threads` | Run Threads tests only. |
-| `npm run test:pinterest` | Run Pinterest tests only. |
-| `npm run test:brat` | Run Brat tests only. |
-
-Recommended validation before publishing or changing behavior:
+### Utility, AI & Conversion Resolvers
 
-```bash
-npm run typecheck
-npm run test
-npm run build
-npx tsx examples/alllexamp.ts
-```
-
-## Project Structure
-
-```txt
-src/
-  index.ts                 Public package exports
-  WsperScraper.ts          Aggregate scraper entrypoint
-  core/
-    credentials/           Credential normalization and platform headers
-    error/                 WsperError, ValidationError, HttpError, ParseError, DownloadError, ScraperError
-    http/                  HTTP client, retries, timeouts, safe URL validation
-    parser/                Shared HTML and JSON parser helpers
-    queue/                 Request pacing and concurrency control
-  modules/
-    brat/                  Brat image/GIF/video generator and converters
-    chart/                 Analytics image generator
-    download/              Safe downloader primitives
-  scrapers/                Platform-specific scraper implementations
-  types/                   Shared response, option, and common types
-  utils/                   Sleep, URL, validation, browser-profile, and helper utilities
-examples/
-  alllexamp.ts             Full example runner
-  mock-server.ts           Local deterministic mock server
-  *.example.ts             Individual runnable examples
-tests/
-  */*.test.ts              Unit and parser tests
-dist/                      Build output only; do not edit manually
-```
-
-## Environment Variables
-
-These variables appear in the repository:
-
-| Variable | Used by | Required? | Notes |
-| --- | --- | --- | --- |
-| `WSPER_MOCK_BASE_URL` | `examples/alllexamp.ts`, AI tool examples | No | Set by the all-examples runner for subprocesses. Points examples to the local mock server. |
-| `BMKG_WARNING_API_KEY` | `examples/cuaca.example.ts` | No | Optional warning API key passed to `CuacaScraper({ warningApiKey })`. |
-| `INSTAGRAM_COOKIE` | `examples/instagram.example.ts` comments | No | Optional example input for constructor credentials. Use `<YOUR_COOKIE_HERE>` style placeholders in docs and never commit real cookies. |
-| `INSTAGRAM_CSRF_TOKEN` | `examples/instagram.example.ts` comments | No | Optional example input for constructor credentials. |
-| `BILI_COOKIE` | `examples/bilibili.example.ts` | No | Optional BiliBili cookie for authenticated stream access. |
-| `WSPER_COOKIE` | `tests/core/credentials.test.ts` | No | Test-only variable proving runtime credential resolution does not read env credentials automatically. |
-
-Credential configuration is constructor-based. The library does not rely on `.env` files for runtime credentials.
+#### GDrive (`GDriveScraper`)
+Finds direct download paths and confirms token attributes of shared files.
 
 ```ts
-import { WsperScraper } from "wsper-js";
+import { GDriveScraper } from "wsper-js";
 
-const wsper = new WsperScraper({
-  spotifyCredentials: {
-    clientId: "your-client-id",
-    clientSecret: "your-client-secret",
-  },
-  credentials: {
-    twitter: {
-      cookie: "<YOUR_COOKIE_HERE>",
-      csrfToken: "<YOUR_CSRF_TOKEN_HERE>",
-    },
-    instagram: {
-      cookie: "<YOUR_COOKIE_HERE>",
-      csrfToken: "<YOUR_CSRF_TOKEN_HERE>",
-    },
-  },
-});
+const gdrive = new GDriveScraper();
+const file = await gdrive.getFileInfo("https://drive.google.com/file/d/SHARED_ID/view");
 ```
 
-Spotify custom credentials must include both `clientId` and `clientSecret`. Partial custom Spotify credentials are rejected with `ValidationError`.
+#### AI Image Enhancer (`UpscalerScraper`)
+Uploads buffers to aienhancer APIs and awaits polling queues.
+
+```ts
+import { UpscalerScraper } from "wsper-js";
+import { readFile } from "node:fs/promises";
+
+const upscaler = new UpscalerScraper();
+const buffer = await readFile("photo.jpg");
 
-## Cloudflare, Rate Limits, and Reliability
+const result = await upscaler.upscaleBuffer(buffer, "image/jpeg");
+if (result.ok && result.data) {
+  console.log("Upscaled Image CDN Link:", result.data.output);
+}
+```
 
-Some websites protect HTML pages with Cloudflare, require active authenticated sessions, or apply strict rate limits. `wsper-js` favors public APIs when they are available and documented by implementation, such as LRCLIB, Wallhaven, Fandom MediaWiki, Spotify, BMKG, BiliBili, and npm registry endpoints.
+---
 
-The mock server exists to make tests and examples deterministic. It should be used for local validation of rate-limited, Cloudflare-protected, or external-service-dependent flows instead of repeatedly hitting live services.
+## Sandbox & Mock Server Usage
 
-This project does not provide CAPTCHA bypass logic, credential harvesting, session theft, anti-bot evasion, or rate-limit abuse. Use cookies only for accounts and sessions you legitimately control, respect platform terms, and keep request pacing conservative.
+To prevent outbound requests to live websites during automated tests or local script iterations, `wsper-js` packages a local mock server under `examples/mock-server.ts`.
 
-## Contributing
+### Running the Mock Server
+Start the server in a terminal window:
 
 ```bash
-git clone <repository-url>
-cd wsper
-npm install
-npm run typecheck
-npm run test
+npx tsx examples/mock-server.ts
+```
+
+This boots an express-like mock instance at `http://localhost:3000`.
+
+### Consuming Mocks in your Code
+To route scrapers to the local mock base rather than live platform servers:
+
+```ts
+const scraper = new SpotifyScraper({
+  baseUrl: "http://localhost:3000",
+  http: {
+    allowPrivateNetwork: true // Required: permits localhost requests through the validation guard
+  }
+});
 ```
 
-When adding or changing a scraper:
+Alternatively, set the environment variable:
+```bash
+WSPER_MOCK_BASE_URL="http://localhost:3000"
+```
 
-1. Keep scraper-specific logic under `src/scrapers/<name>/`.
-2. Export the scraper from `src/scrapers/<name>/index.ts` and `src/scrapers/index.ts`.
-3. Return typed `WsperResponse<T>` results.
-4. Keep HTTP, parsing, queueing, and file download responsibilities separated.
-5. Add or update parser and scraper tests under `tests/`.
-6. Add or update a runnable example under `examples/`.
-7. Use the mock server for flows that should not depend on live third-party behavior in default tests.
-8. Update this README when public API, usage, behavior, examples, or validation results change.
+---
 
-## Security
+## Error Handling & Exceptions
 
-- Validate and normalize user-provided URLs before requesting them.
-- Use only `http:` and `https:` unless a module explicitly supports something else.
-- Keep SSRF protections enabled; private network requests require explicit `allowPrivateNetwork: true` and should be reserved for local mocks or trusted endpoints.
-- Do not log secrets, cookies, client secrets, authorization headers, access tokens, refresh tokens, or raw credential objects.
-- Do not commit credentials, cookies, tokens, private fixtures, or real session material.
+All errors thrown internally inherit from `WsperError`. You can import and catch specific exceptions for granular error handling:
 
-## License
+```ts
+import { WsperError, HttpError, ParseError, ValidationError, DownloadError } from "wsper-js";
+
+try {
+  await scraper.search("");
+} catch (err) {
+  if (err instanceof ValidationError) {
+    console.error("Validation failed. Incorrect fields:", err.details);
+  } else if (err instanceof HttpError) {
+    console.error(`HTTP Status Error ${err.statusCode} on URL ${err.url}`);
+    if (err.details?.preview) {
+      console.error("Server raw response preview:", err.details.preview);
+    }
+  } else if (err instanceof ParseError) {
+    console.error("Target HTML/JSON parser format changed:", err.message);
+  } else if (err instanceof WsperError) {
+    console.error(`Generic Wsper error [${err.code}]:`, err.message);
+  }
+}
+```
 
-GPL-3.0-or-later. See `LICENSE` for the full license text.
+### Exception Hierarchy
+```
+Error (Node.js)
+  └── WsperError
+        ├── HttpError        (Thrown on HTTP failures >= 400 or timeouts)
+        ├── ParseError       (Thrown when DOM scraper or JSON parsing fails)
+        ├── ValidationError  (Thrown when argument formatting is incorrect)
+        ├── DownloadError    (Thrown by the Downloader on sizes/mime violations)
+        └── ScraperError     (Thrown by custom scraper-specific subroutines)
+```