wsper-js 0.1.0 → 0.1.1

package/README.md

@@ -1,1616 +1,679 @@
-<img src="https://i.pinimg.com/736x/9a/d3/8c/9ad38cbf49e39e599102b3021b2e88d5.jpg" alt="" align="center" width="1000">
-
-
-# wsper
-
-library berikut saya buat untuk mempermudah kalian membuat sebuah bot whatsapp, dengan ini anda tidak perlu lagi untuk menambah code yang tidak jelas dan sering error awookawoka
-
----
-
-## Daftar Isi
-
-- [Instalasi](#instalasi)
-- [Quick Start](#quick-start)
-- [WsperScraper — Kelas Utama](#wsperscraper--kelas-utama)
-- [Response Structure](#response-structure)
-- [Scrapers](#scrapers)
-  - [Instagram](#instagram)
-  - [Spotify](#spotify)
-  - [YouTube](#youtube)
-  - [Threads](#threads)
-  - [Twitter / X](#twitter--x)
-  - [Pinterest](#pinterest)
-  - [BiliBili](#bilibili)
-  - [CapCut](#capcut)
-  - [Komikindo](#komikindo)
-  - [Mediafire](#mediafire)
-  - [Play Store](#play-store)
-  - [Minecraft Addon](#minecraft-addon)
-  - [Alkitab](#alkitab)
-  - [BMKG](#bmkg)
-  - [Cuaca](#cuaca)
-  - [Drakor](#drakor)
-  - [Dramabox](#dramabox)
-  - [SakuraNovel](#sakuranovel)
-  - [Uguu](#uguu)
-  - [HokInfo](#hokinfo)
-  - [IkiruManga](#ikirumanga)
-  - [Wallpaper](#wallpaper)
-  - [WwChar](#wwchar)
-  - [Videy](#videy)
-  - [OCR](#ocr)
-  - [Webp2Mp4](#webp2mp4)
-  - [MConverter](#mconverter)
-  - [HtmlToJpg](#htmltojpg)
-  - [Stalk](#stalk)
-  - [ModAndroid](#modandroid)
-  - [Upscaler](#upscaler)
-  - [Image](#image)
-  - [ImgUpscaler](#imgupscaler)
-  - [Faceswap](#faceswap)
-  - [PhotoAi](#photoai)
-  - [Lyrics](#lyrics)
-  - [Resep](#resep)
-  - [Top Anime](#top-anime)
-  - [Anime Quote](#anime-quote)
-  - [Anime Random](#anime-random)
-- [Brat Generator](#brat-generator)
-  - [generate — Image](#generate--image)
-  - [generate — GIF](#generate--gif)
-  - [generate — Video](#generate--video)
-  - [withPreset](#withpreset)
-  - [imageToSticker](#imagetosticker)
-  - [MP4 ↔ GIF Conversion](#mp4--gif-conversion)
-  - [convertImage](#convertimage)
-  - [Background Config](#background-config)
-  - [Text Config](#text-config)
-  - [Canvas Config](#canvas-config)
-  - [Animation Config](#animation-config)
-  - [Output Config](#output-config)
-- [Chart Image Generator](#chart-image-generator)
-- [Credentials](#credentials)
-- [HTTP & Queue Options](#http--queue-options)
-- [Download Outputs](#download-outputs)
-
----
-
-## Instalasi
 
-```bash
-npm install wsper
-```
-
-Dependency eksternal yang dibutuhkan untuk fitur tertentu:
-
-| Fitur | Dependency |
-|---|---|
-| YouTube download / audio | `yt-dlp` (install terpisah) |
-| Video export, GIF ↔ MP4 | `ffmpeg` di PATH atau `C:\ffmpeg\ffmpeg.exe` |
+<h1 align="center">
+  <img alt="ShikanokoBail banner" src="https://i.pinimg.com/736x/0c/ff/62/0cff624a04a81495f4b8e69bcedd34aa.jpg" width="100%"/>
+</h1>
 
----
+<div align="center">
 
-## Quick Start
-
-```ts
-import { WsperScraper, BratGenerator, ChartGenerator } from "wsper";
+[![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)
+![License](https://img.shields.io/badge/license-GPL--3.0--or--later-blue)
+</div>
 
-// Semua scraper dalam satu kelas
-const wsper = new WsperScraper();
+# 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.
 
-const profile = await wsper.instagram.getProfile("charli_xcx");
-const track   = await wsper.spotify.getTrack("https://open.spotify.com/track/...");
-const video   = await wsper.youtube.getVideo("https://youtu.be/...");
+The package is ESM-only and targets Node.js 18 or newer.
 
-// Brat Generator
-const brat   = new BratGenerator();
-const result = await brat.generate({
-  text:       { value: "brat summer" },
-  background: { type: "solid", color: "#8ace00" },
-  output:     { type: "image", format: "png", path: "./brat.png" },
-});
-
-// Chart Generator
-const chart = new ChartGenerator();
-await chart.generateStatsImage({
-  model:  "modern-dashboard",
-  output: "./analytics.png",
-});
-```
-
----
-
-## WsperScraper — Kelas Utama
-
-```ts
-import { WsperScraper } from "wsper";
-
-const wsper = new WsperScraper(config?: WsperScraperConfig);
-```
-
-### WsperScraperConfig
-
-```ts
-interface WsperScraperConfig {
-  debug?: boolean;
-  spotifyCredentials?: {
-    clientId:    string;
-    clientSecret: string;
-    callbackUrl?: string;
-    market?:      string;
-  };
-  credentials?: {
-    instagram?: { cookie?: string; csrfToken?: string };
-    threads?:   { cookie?: string; csrfToken?: string };
-    twitter?:   { cookie?: string; csrfToken?: string };
-    pinterest?: { cookie?: string; csrfToken?: string };
-  };
-  http?:    HttpOptions;
-  queue?:   QueueOptions;
-  youtube?: YouTubeScraperOptions;
-}
-```
-
-### Properties
-
-| Property | Type | Deskripsi |
-|---|---|---|
-| `wsper.instagram` | `InstagramScraper` | Instagram scraper |
-| `wsper.spotify` | `SpotifyScraper` | Spotify scraper |
-| `wsper.youtube` | `YouTubeScraper` | YouTube scraper |
-| `wsper.threads` | `ThreadsScraper` | Threads scraper |
-| `wsper.twitter` | `TwitterScraper` | Twitter/X scraper |
-| `wsper.pinterest` | `PinterestScraper` | Pinterest scraper |
-
----
-
-## Response Structure
-
-Semua scraper mengembalikan `WsperResponse<T>`:
-
-```ts
-interface WsperResponse<T, Meta = WsperResponseMeta> {
-  ok:    boolean;
-  data:  T | null;
-  error: { code: string; message: string; details?: Record<string, unknown> } | null;
-  meta:  Meta & {
-    statusCode: number;
-    sourceUrl:  string;
-    fetchedAt:  string;    // ISO timestamp
-    durationMs: number;
-  };
-}
-```
+## Features
 
-**Pattern penggunaan:**
+- 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.
 
-```ts
-const res = await wsper.instagram.getProfile("username");
+## Installation
 
-if (res.ok) {
-  console.log(res.data.username);
-  console.log(res.meta.durationMs, "ms");
-} else {
-  console.error(res.error?.code, res.error?.message);
-}
+```bash
+npm install wsper-js
 ```
 
----
-
-## Scrapers
-
----
-
-### Instagram
-
-```ts
-import { InstagramScraper } from "wsper";
-const ig = new InstagramScraper(options?: InstagramScraperOptions);
+```bash
+pnpm add wsper-js
 ```
 
-#### `getProfile(username)` → `WsperResponse<InstagramProfile>`
-
-```ts
-await ig.getProfile("charli_xcx")
+```bash
+yarn add wsper-js
 ```
 
-```ts
-interface InstagramProfile {
-  id:              string;
-  username:        string;
-  fullName:        string;
-  biography:       string;
-  profilePicUrl:   string;
-  profilePicUrlHd: string | null;
-  followersCount:  number;
-  followingCount:  number;
-  mediaCount:      number;
-  isPrivate:       boolean;
-  isVerified:      boolean;
-  externalUrl:     string | null;
-}
-```
+Some optional capabilities need external binaries:
 
-#### `getFeed(username, options?)` → `WsperResponse<InstagramFeed>`
+| Feature | External tool |
+| --- | --- |
+| YouTube and Spotify media enrichment/download helpers | `yt-dlp` |
+| Video export and GIF/MP4 conversion | `ffmpeg` in `PATH` or configured path |
 
-```ts
-await ig.getFeed("charli_xcx", { count: 12, maxId: "cursor" })
-```
+## Quick Start
 
 ```ts
-interface InstagramFeed {
-  items:     InstagramMediaItem[];
-  nextMaxId: string | null;
-  hasMore:   boolean;
-}
+import { LyricsScraper } from "wsper-js";
 
-interface InstagramMediaItem {
-  id:           string;
-  shortcode:    string;
-  mediaType:    number;        // 1=image  2=video  8=carousel
-  productType:  string | null;
-  caption:      string | null;
-  takenAt:      number | null;
-  likeCount:    number | null;
-  commentCount: number | null;
-  thumbnailUrl: string | null;
-  videoUrl:     string | null;
-  carousel:     InstagramCarouselItem[] | null;
-}
+const lyrics = new LyricsScraper();
+const result = await lyrics.search("after hours the weeknd");
 
-interface InstagramCarouselItem {
-  id:           string;
-  mediaType:    number;
-  thumbnailUrl: string | null;
-  videoUrl:     string | null;
+if (!result.ok) {
+  throw new Error(`${result.error?.code}: ${result.error?.message}`);
 }
-```
-
-#### `getPost(input)` → `WsperResponse<InstagramMediaItem>`
-
-```ts
-await ig.getPost("https://www.instagram.com/p/AbCdEfG/")
-await ig.getPost("AbCdEfG")   // shortcode langsung
-```
 
-#### `getProfileWithFeed(username, options?)` → `WsperResponse<InstagramProfileWithFeed>`
-
-```ts
-await ig.getProfileWithFeed("charli_xcx", { count: 6 })
-```
-
-```ts
-interface InstagramProfileWithFeed {
-  profile:   InstagramProfile;
-  items:     InstagramMediaItem[];
-  nextMaxId: string | null;
-  hasMore:   boolean;
-}
+console.log(result.statusCode);
+console.log(result.data?.title);
+console.log(result.data?.lyrics);
 ```
 
-#### `downloadPost(input)` → `WsperResponse<InstagramDownloadResult>`
+You can also use `WsperScraper` for the aggregate social/media scraper entrypoint:
 
 ```ts
-await ig.downloadPost({
-  postUrl:         "https://www.instagram.com/p/AbCdEfG/",
-  outputDir:       "./downloads/instagram",
-  includeMetadata: true,
-})
-```
+import { WsperScraper } from "wsper-js";
 
-```ts
-interface InstagramDownloadResult {
-  sourceUrl:    string;
-  outputDir:    string;
-  metadataPath: string | null;
-  assets: Array<{
-    url:        string;
-    outputPath: string;
-    type:       "image" | "video";
-    index:      number;
-  }>;
-}
-```
+const wsper = new WsperScraper({
+  queue: { concurrency: 1, minDelayMs: 500, maxDelayMs: 1500 },
+});
 
-#### `downloadProfile(input)` → `WsperResponse<InstagramDownloadResult>`
+const track = await wsper.spotify.search("never gonna give you up", { limit: 3 });
+const video = await wsper.youtube.getVideo("dQw4w9WgXcQ");
 
-```ts
-await ig.downloadProfile({
-  usernameOrUrl:         "charli_xcx",
-  outputDir:             "./downloads/instagram",
-  feedCount:             9,
-  includeProfilePicture: true,
-  includeInitialPosts:   true,
-  includeMetadata:       true,
-})
+console.log(track.ok, video.ok);
 ```
 
----
+`WsperScraper` currently exposes `spotify`, `twitter`, `threads`, `instagram`, `pinterest`, and `youtube`. Other scrapers are exported as named classes.
 
-### Spotify
+## Response Shape
 
-```ts
-import { SpotifyScraper } from "wsper";
-const spotify = new SpotifyScraper(options?: SpotifyScraperOptions);
-```
-
-#### `getTrack(input, options?)` → `WsperResponse<NormalizedSpotifyTrack, SpotifyTrackMeta>`
-
-```ts
-await spotify.getTrack("https://open.spotify.com/track/4iV5W9uYEdYUVa79Axb7Rh")
-await spotify.getTrack("4iV5W9uYEdYUVa79Axb7Rh", { enrichYtDlp: true })
-```
+Scraper methods return `WsperResponse<TData>`:
 
 ```ts
-interface NormalizedSpotifyTrack {
-  id:             string;
-  name:           string;
-  uri:            string;
-  url:            string | null;
-  durationMs:     number;
-  durationString: string | null;
-  explicit:       boolean;
-  trackNumber:    number | null;
-  discNumber:     number | null;
-  popularity:     number | null;
-  isPlayable:     boolean | null;
-  previewUrl:     string | null;
-  artists:        NormalizedSpotifyArtist[];
-  album:          NormalizedSpotifyAlbum;
-  externalIds:    Record<string, string>;
-  externalSource: ExternalSource | null;   // yt-dlp enrichment (jika enrichYtDlp: true)
-  download:       DownloadInfo | null;
+export interface WsperResponse<TData, TMeta extends WsperResponseMeta = WsperResponseMeta> {
+  ok: boolean;
+  statusCode: number;
+  data: TData | null;
+  error: {
+    code: string;
+    message: string;
+    details?: Record<string, unknown>;
+  } | null;
+  meta: TMeta;
 }
 
-// Meta tambahan untuk track
-interface SpotifyTrackMeta extends WsperResponseMeta {
-  externalSourceUrl: string | null;
+export interface WsperResponseMeta {
+  statusCode: number;
+  sourceUrl: string;
+  fetchedAt: string;
+  durationMs: number;
 }
 ```
 
-#### `getAlbum(input, options?)` → `WsperResponse<SpotifyAlbumWithTracks>`
-
-```ts
-await spotify.getAlbum("https://open.spotify.com/album/...")
-```
+Recommended handling:
 
 ```ts
-interface SpotifyAlbumWithTracks {
-  album:  NormalizedSpotifyAlbum;
-  tracks: NormalizedSpotifyTrack[];
-}
+const response = await scraper.search("query");
 
-interface NormalizedSpotifyAlbum {
-  id:                   string;
-  name:                 string;
-  albumType:            string | null;
-  uri:                  string;
-  url:                  string | null;
-  releaseDate:          string | null;
-  totalTracks:          number | null;
-  images:               SpotifyImage[];
-  artists:              NormalizedSpotifyArtist[];
-  copyrights:           Array<{ text: string; type: string }>;
-  label:                string | null;
-  popularity:           number | null;
+if (response.ok && response.data !== null) {
+  console.log(response.data);
+} else {
+  console.error(response.statusCode, response.error?.code, response.error?.message);
 }
 ```
 
-#### `getPlaylist(input)` → `WsperResponse<NormalizedSpotifyPlaylist>`
-
-```ts
-await spotify.getPlaylist("https://open.spotify.com/playlist/...")
-```
-
-#### `search(query, options?)` → `WsperResponse<SpotifySearchResult>`
-
-```ts
-await spotify.search("charli xcx brat", { limit: 10, type: ["track", "album"] })
-```
+## Usage Examples
 
-#### `downloadPost(input)` / `downloadProfile(input)`
+The examples below use public exports from `src/index.ts` and representative response fields from implementation and tests.
 
-```ts
-await spotify.downloadPost({
-  trackUrl:  "https://open.spotify.com/track/...",
-  outputDir: "./downloads/spotify",
-  format:    "mp3",
-})
-// → WsperResponse<SpotifyDownloadResult>
-```
+### LyricsScraper
 
-#### OAuth helpers
+Source: LRCLIB JSON API at `https://lrclib.net/api/search`.
 
 ```ts
-spotify.createAuthUrl({ state: "xyz", scopes: ["user-read-private"] })
-// → { state: string; url: string }
+import { LyricsScraper } from "wsper-js";
 
-await spotify.exchangeCode(code)    // → SpotifyOAuthToken
-await spotify.refreshToken(token)   // → SpotifyOAuthToken
-await spotify.getAccessToken()      // → string
-spotify.invalidateToken()           // → void
-```
-
----
+const scraper = new LyricsScraper();
+const result = await scraper.search("after hours the weeknd");
 
-### YouTube
-
-```ts
-import { YouTubeScraper } from "wsper";
-const yt = new YouTubeScraper(options?: YouTubeScraperOptions);
+console.log(result.data);
 ```
 
-```ts
-interface YouTubeScraperOptions {
-  debug?:       boolean;
-  ytdlpPath?:   string;   // path ke yt-dlp binary
-  ffmpegPath?:  string;
-  ffprobePath?: string;
-  outputDir?:   string;
-  searchLimit?: number;
-}
-```
-
-#### `getVideo(input)` → `WsperResponse<YoutubeVideoMetadata>`
-
-```ts
-await yt.getVideo("https://youtu.be/dQw4w9WgXcQ")
-```
+Representative output:
 
-```ts
-interface YoutubeVideoMetadata {
-  provider:        "youtube";
-  id:              string;
-  title:           string;
-  url:             string;
-  durationSeconds: number | null;
-  durationString:  string | null;
-  isLive:          boolean;
-  uploadDate:      string | null;
-  description:     string | null;
-  thumbnail:       string | null;
-  thumbnails:      Array<{ url: string; width: number | null; height: number | null }>;
-  channel: {
-    id:            string | null;
-    name:          string | null;
-    url:           string | null;
-    handle:        string | null;
-    isVerified:    boolean | null;
-    followerCount: number | null;
-  };
-  stats: {
-    viewCount:    number | null;
-    likeCount:    number | null;
-    commentCount: number | null;
-  };
-  formats: {
-    audio: YoutubeAudioFormat[];
-    video: YoutubeVideoFormat[];
-  };
-  download: YoutubeDownloadInfo;
+```json
+{
+  "title": "After Hours",
+  "lyrics": "Oh, baby, where are you now?",
+  "link": "https://lrclib.net/api/get/98765"
 }
 ```
 
-#### `searchVideos(query, options?)` → `WsperResponse<YoutubeSearchResult>`
-
-```ts
-await yt.searchVideos("charli xcx brat", { limit: 5 })
-// data: { query, total, items: YoutubeVideoMetadata[] }
-```
-
-#### `downloadVideo(input, options?)` → `WsperResponse<YoutubeDownloadResult>`
-
-```ts
-await yt.downloadVideo("https://youtu.be/...", {
-  outputDir: "./downloads",
-  fileName:  "video",
-  format:    "mp4",
-})
-// data: { sourceUrl, outputDir, format, type: "video", command }
-```
-
-#### `downloadAudio(input, options?)` → `WsperResponse<YoutubeDownloadResult>`
-
-```ts
-await yt.downloadAudio("https://youtu.be/...", {
-  outputDir:   "./downloads",
-  audioFormat: "mp3",    // "mp3" | "m4a" | "opus" | "flac" | "wav"
-})
-// data: { sourceUrl, outputDir, format, type: "audio", command }
-```
-
-#### `extractAudio(inputPath, options?)` → `WsperResponse<YoutubeAudioExtractResult>`
-
-```ts
-await yt.extractAudio("./video.mp4", {
-  outputPath:   "./audio.mp3",
-  audioFormat:  "mp3",
-  audioBitrate: "192k",
-})
-// data: { inputPath, outputPath, format, bitrate }
-```
-
-#### `getPlaylist(input)` → `WsperResponse<YoutubePlaylistData>`
-
-```ts
-await yt.getPlaylist("https://www.youtube.com/playlist?list=...")
-// data: { id, title, url, uploader, channel, entriesTotal, entries[] }
-```
-
-#### `getChannel(input)` → `WsperResponse<YoutubeChannelData>`
-
-```ts
-await yt.getChannel("https://www.youtube.com/@channelname")
-// data: { id, title, channel, channelId, entriesTotal, entries[] }
-```
-
----
-
-### Threads
-
-```ts
-import { ThreadsScraper } from "wsper";
-const threads = new ThreadsScraper(options?: ScraperOptions);
-```
-
-#### `getProfile(usernameOrUrl)` → `WsperResponse<ThreadsProfile>`
-
-```ts
-await threads.getProfile("zuck")
-await threads.getProfile("https://www.threads.net/@zuck")
-```
-
-#### `getPost(input)` → `WsperResponse<ThreadsPost>`
-
-```ts
-await threads.getPost("https://www.threads.net/@user/post/CgXxXxXxX")
-```
-
-#### Search methods → `WsperResponse<ThreadsSearchResult>`
-
-```ts
-await threads.search("brat summer")
-await threads.searchByTag("bratstyle")
-await threads.searchUsers("charli")
-```
-
-#### `downloadPost(input)` / `downloadProfile(input)` → `WsperResponse<ThreadsDownloadResult>`
-
-```ts
-await threads.downloadPost({
-  postUrl:   "https://www.threads.net/@user/post/...",
-  outputDir: "./downloads/threads",
-})
-```
-
----
-
-### Twitter / X
-
-```ts
-import { TwitterScraper } from "wsper";
-const twitter = new TwitterScraper(options?: ScraperOptions);
-```
-
-> Sebagian besar endpoint membutuhkan `cookie` + `csrfToken` karena API Twitter memerlukan auth.
-
-#### `getTweet(input)` → `WsperResponse<TwitterTweetDetail>`
-
-```ts
-await twitter.getTweet({ tweetId: "1234567890" })
-await twitter.getTweet({ url: "https://x.com/user/status/1234567890" })
-```
-
-#### `searchTweets(query, options?)` → `WsperResponse<TwitterSearchResult>`
-
-```ts
-await twitter.searchTweets("brat summer", { limit: 20 })
-```
-
-#### Other search methods
-
-```ts
-await twitter.searchByTag("bratstyle")             // → WsperResponse<TwitterSearchResult>
-await twitter.searchTrend("brat")                  // → WsperResponse<TwitterSearchResult>
-await twitter.searchUsers("charli xcx")            // → WsperResponse<TwitterUserSearchResult>
-```
-
-#### `getProfile(usernameOrUrl)` → `WsperResponse<TwitterUser>`
-
-```ts
-await twitter.getProfile("charli_xcx")
-```
-
----
-
-### Pinterest
-
-```ts
-import { PinterestScraper } from "wsper";
-const pinterest = new PinterestScraper(options?: ScraperOptions);
-```
-
-#### `getPin(input)` → `WsperResponse<PinterestPin>`
-
-```ts
-await pinterest.getPin("https://www.pinterest.com/pin/1234567890/")
-```
-
-#### `searchPins(query, options?)` → `WsperResponse<PinterestSearchResult>`
-
-```ts
-await pinterest.searchPins("brat aesthetic", { limit: 20 })
-```
-
-#### `downloadPin(input)` → `WsperResponse<PinterestDownloadResult>`
-
-```ts
-await pinterest.downloadPin({
-  pinUrl:    "https://www.pinterest.com/pin/...",
-  outputDir: "./downloads/pinterest",
-})
-```
-
----
-
-### BiliBili
-
-```ts
-import { BiliBiliScraper } from "wsper";
-const bili = new BiliBiliScraper();
-
-await bili.getVideoInfo("https://www.bilibili.com/video/BV...")
-// → WsperResponse<BiliBiliResult>
-// data: { title, cover, duration, author, views, plays, streams[] }
-```
-
----
-
-### CapCut
-
-```ts
-import { CapCutScraper } from "wsper";
-const capcut = new CapCutScraper();
-
-await capcut.download("https://www.capcut.com/t/...")
-// → WsperResponse<CapCutDownloadResult>
-// data: { title, coverUrl, videoUrl, authorName }
-```
-
----
-
-### Komikindo
-
-```ts
-import { KomikindoScraper } from "wsper";
-const komik = new KomikindoScraper();
-
-await komik.search("one piece")
-// → WsperResponse<KomikindoSearchItem[]>
-// data[]: { title, url, cover, type, status, rating, latestChapter }
-
-await komik.getDetail("https://komikindo.tv/manga/...")
-// → WsperResponse<KomikindoDetail>
-// data: { title, cover, synopsis, chapters[], genres[] }
-```
-
----
-
-### Mediafire
-
-```ts
-import { MediafireScraper } from "wsper";
-const mf = new MediafireScraper();
-
-await mf.getLink("https://www.mediafire.com/file/.../file")
-// → WsperResponse<MediafireResult>
-// data: { fileName, fileSize, downloadUrl, uploadDate }
-```
-
----
-
-### Play Store
-
-```ts
-import { PlayStoreScraper } from "wsper";
-const store = new PlayStoreScraper();
-
-await store.search("spotify", 5)
-// → WsperResponse<PlayStoreApp[]>
-// data[]: { name, packageId, developer, rating, downloads, iconUrl, url }
-```
-
----
+### WallpaperScraper
 
-### Minecraft Addon
+Source: Wallhaven search API at `https://wallhaven.cc/api/v1/search`.
 
 ```ts
-import { McAddonScraper } from "wsper";
-const mc = new McAddonScraper();
+import { WallpaperScraper } from "wsper-js";
 
-await mc.search("texture pack")
-// → WsperResponse<McAddonSearchItem[]>
+const scraper = new WallpaperScraper();
+const result = await scraper.search("cyberpunk");
 
-await mc.getDetail("https://mcpedl.com/addon/...")
-// → WsperResponse<McAddonDetail>
-// data: { title, description, downloadLinks[], images[], author }
+console.log(result.data?.total);
+console.log(result.data?.results[0]);
 ```
 
----
-
-### Alkitab
-
-```ts
-import { AlkitabScraper } from "wsper";
-const alkitab = new AlkitabScraper();
-
-await alkitab.search("yohanes 3:16")
-// → WsperResponse<AlkitabVerse[]>
-// data[]: { reference, text, book, chapter, verse }
-```
-
----
-
-### BMKG
-
-```ts
-import { BMKGScraper } from "wsper";
-const bmkg = new BMKGScraper();
-
-await bmkg.getAutogempa()
-// -> WsperResponse<BMKGEarthquakeFeed>
-
-await bmkg.getGempaDirasakan()
-// -> WsperResponse<BMKGEarthquakeFeed>
-
-await bmkg.getCuacaNowcasting(0, 100)
-// -> WsperResponse<BMKGNowcasting>
-
-await bmkg.getPrakiraanCuaca("31")
-// -> WsperResponse<BMKGForecast>
-
-await bmkg.downloadShakemap("kode-shakemap", "./downloads")
-// -> WsperResponse<BMKGShakemapDownload>
+Representative output:
 
-bmkg.getKodeProvinsi()
-// -> WsperResponse<Record<string, string>>
-```
-
----
-
-### Cuaca
-
-```ts
-import { CuacaScraper } from "wsper";
-const cuaca = new CuacaScraper({
-  warningApiKey: process.env.BMKG_WARNING_API_KEY,
-});
-
-await cuaca.searchLocation("bandung")
-// -> WsperResponse<CuacaSearchResult[]>
-
-await cuaca.getWeather("bandung")
-// -> WsperResponse<CuacaResult>
-
-await cuaca.getWeatherByCoord(-6.9175, 107.6191)
-// -> WsperResponse<CuacaResult>
-```
-
----
-
-### Drakor
-
-```ts
-import { DrakorScraper } from "wsper";
-const drakor = new DrakorScraper();
-
-await drakor.search("undercover")
-// -> WsperResponse<DrakorList>
-
-await drakor.detail("undercover-miss-hong")
-// -> WsperResponse<DrakorDetail>
-
-await drakor.ongoing()
-// -> WsperResponse<DrakorList>
-
-await drakor.getAll(1)
-// -> WsperResponse<DrakorList>
-```
-
----
-
-### Dramabox
-
-```ts
-import { DramaboxScraper } from "wsper";
-const dramabox = new DramaboxScraper();
-
-await dramabox.search("romance")
-// -> WsperResponse<DramaboxResult>
-```
-
----
-
-### SakuraNovel
-
-```ts
-import { SakuraNovelScraper } from "wsper";
-const sakura = new SakuraNovelScraper();
-
-await sakura.search("isekai")
-// -> WsperResponse<SakuraNovelSearchItem[]>
-
-await sakura.getDetail("/series/example/")
-// -> WsperResponse<SakuraNovelDetail>
-
-await sakura.getChapter("/chapter/example-1/")
-// -> WsperResponse<SakuraNovelChapterContent>
-```
-
----
-
-### Uguu
-
-```ts
-import { UguuScraper } from "wsper";
-const uguu = new UguuScraper();
-
-await uguu.upload(Buffer.from("hello"), "hello.txt")
-// -> WsperResponse<UguuUploadResult>
-// data: { url }
-```
-
----
-
-### HokInfo
-
-```ts
-import { HokInfoScraper } from "wsper";
-const hok = new HokInfoScraper();
-
-await hok.getCharacter("Sun Wukong")
-// -> WsperResponse<HokInfoResult>
-```
-
----
-
-### IkiruManga
-
-```ts
-import { IkiruMangaScraper } from "wsper";
-const ikiru = new IkiruMangaScraper();
-
-await ikiru.search("solo leveling")
-// -> WsperResponse<IkiruMangaResult>
-```
-
----
-
-### Wallpaper
-
-```ts
-import { WallpaperScraper } from "wsper";
-const wallpaper = new WallpaperScraper();
-
-await wallpaper.search("blue sky")
-// -> WsperResponse<WallpaperResult>
-```
-
----
-
-### WwChar
-
-```ts
-import { WwCharScraper } from "wsper";
-const ww = new WwCharScraper();
-
-await ww.getCharacter("Jin Hsi")
-// -> WsperResponse<WwCharResult>
-```
-
----
-
-### Videy
-
-```ts
-import { VideyScraper } from "wsper";
-const videy = new VideyScraper();
-
-await videy.upload("./video.mp4")
-// -> WsperResponse<VideyUploadResult>
-```
-
----
-
-### OCR
-
-```ts
-import { OcrScraper } from "wsper";
-const ocr = new OcrScraper();
-
-await ocr.scan(imageBuffer)
-// -> WsperResponse<OcrScanResult>
-```
-
----
-
-### Webp2Mp4
-
-```ts
-import { Webp2Mp4Scraper } from "wsper";
-const converter = new Webp2Mp4Scraper();
-
-await converter.toMp4(webpBuffer)
-// -> WsperResponse<Webp2Mp4Result>
-
-await converter.toPng("https://example.com/image.webp")
-// -> WsperResponse<Webp2Mp4Result>
-```
-
----
-
-### MConverter
-
-```ts
-import { MConverterScraper } from "wsper";
-const converter = new MConverterScraper();
-
-await converter.getTargets("image.webp")
-// -> WsperResponse<MConverterTargetsResult>
-
-await converter.convertBuffer(imageBuffer, "image.webp", "png")
-// -> WsperResponse<MConverterConvertResult>
+```json
+{
+  "total": 1,
+  "results": [
+    {
+      "title": "Wallpaper sky123",
+      "resolution": "1920x1080",
+      "image": "https://w.wallhaven.cc/full/sky123.jpg",
+      "page": "https://wallhaven.cc/w/sky123"
+    }
+  ]
+}
 ```
 
----
+### WwCharScraper
 
-### HtmlToJpg
+Source: Wuthering Waves Fandom MediaWiki parse API.
 
 ```ts
-import { HtmlToJpgScraper } from "wsper";
-const converter = new HtmlToJpgScraper();
-
-await converter.convertBuffer(htmlBuffer, "page.html")
-// -> WsperResponse<HtmlToJpgResult>
-```
+import { WwCharScraper } from "wsper-js";
 
----
+const scraper = new WwCharScraper();
+const result = await scraper.getCharacter("Jin Hsi");
 
-### Stalk
-
-```ts
-import { StalkScraper } from "wsper";
-const stalk = new StalkScraper();
-
-await stalk.getNpmPackage("wsper")
-// -> WsperResponse<NpmPackage>
+console.log(result.data);
 ```
 
----
-
-### ModAndroid
+Representative output:
 
-```ts
-import { ModAndroidScraper } from "wsper";
-const modAndroid = new ModAndroidScraper();
-
-await modAndroid.aptoide("maps")
-// -> WsperResponse<AptoideResult>
+```json
+{
+  "title": "Jiyan",
+  "slug": "Jin_Hsi",
+  "url": "https://wutheringwaves.fandom.com/wiki/Jin_Hsi",
+  "bio": "Bio karakter.",
+  "profile": {},
+  "images": []
+}
 ```
 
----
+### HokInfoScraper
 
-### Upscaler
+Source: Honor of Kings Fandom MediaWiki parse API.
 
 ```ts
-import { UpscalerScraper } from "wsper";
-const upscaler = new UpscalerScraper();
+import { HokInfoScraper } from "wsper-js";
 
-await upscaler.upscaleBuffer(imageBuffer, "image/jpeg")
-// -> WsperResponse<UpscalerResult>
-```
+const scraper = new HokInfoScraper();
+const result = await scraper.getCharacter("Angela");
 
----
-
-### Image
-
-```ts
-import { ImageScraper } from "wsper";
-const image = new ImageScraper();
-
-await image.safebooru("blue_sky", 0, 10)
-// -> WsperResponse<ImageSearchResult>
+console.log(result.data?.profile);
 ```
 
----
-
-### ImgUpscaler
-
-```ts
-import { ImgUpscalerScraper } from "wsper";
-const upscaler = new ImgUpscalerScraper();
+Representative output:
 
-await upscaler.upscaleBuffer(imageBuffer, "image.jpg", 2)
-// -> WsperResponse<ImgUpscalerResult>
+```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"
+}
 ```
 
----
+### CapCutScraper
 
-### Faceswap
+Source: WordPress-style resolver endpoint, defaulting to `https://capdownloader.com/wp-json/aio-dl/video-data/`.
 
 ```ts
-import { FaceswapScraper } from "wsper";
-const faceswap = new FaceswapScraper();
-
-await faceswap.process(sourceImageBuffer, targetImageBuffer)
-// -> WsperResponse<FaceswapResult>
-```
-
----
+import { CapCutScraper } from "wsper-js";
 
-### PhotoAi
-
-```ts
-import { PhotoAiScraper } from "wsper";
-const photoAi = new PhotoAiScraper();
+const scraper = new CapCutScraper();
+const result = await scraper.download("https://www.capcut.com/t/Zs82gHj1a/");
 
-await photoAi.uploadBuffer(imageBuffer, "image.jpg")
-// -> WsperResponse<PhotoAiUploadResult>
+console.log(result.data);
 ```
 
----
+Representative output:
 
-### Lyrics
-
-```ts
-import { LyricsScraper } from "wsper";
-const lyrics = new LyricsScraper();
-
-await lyrics.search("brat charli xcx")
-// → WsperResponse<LyricsResult>
-// data: { title, artist, lyrics, sourceUrl }
+```json
+{
+  "videoUrl": "https://cdn.example/video.mp4"
+}
 ```
 
----
+### ImgUpscalerScraper
 
-### Resep
+Source: `https://get1.imglarger.com` upload and status endpoints.
 
 ```ts
-import { ResepScraper } from "wsper";
-const resep = new ResepScraper();
-
-await resep.search("nasi goreng")
-// → WsperResponse<ResepItem[]>
-// data[]: { title, url, imageUrl, author, servings, cookTime, ingredients[], steps[] }
-```
+import { readFile } from "node:fs/promises";
+import { ImgUpscalerScraper } from "wsper-js";
 
----
+const image = await readFile("./photo.jpg");
+const scraper = new ImgUpscalerScraper();
+const result = await scraper.upscaleBuffer(image, "photo.jpg", 4);
 
-### Top Anime
-
-```ts
-import { TopAnimeScraper } from "wsper";
-const anime = new TopAnimeScraper();
-
-await anime.getTopAnime(25)
-// → WsperResponse<TopAnimeItem[]>
-// data[]: { rank, title, url, imageUrl, score, type, episodes, members }
+console.log(result.data);
 ```
 
----
-
-### Anime Quote
+Representative output:
 
-```ts
-import { AnimeQuoteScraper } from "wsper";
-const quote = new AnimeQuoteScraper();
-
-await quote.getRandom()
-// → WsperResponse<AnimeQuoteItem>
-// data: { quote, character, anime, imageUrl }
-```
-
----
-
-### Anime Random
-
-```ts
-import { AnimeRandomScraper, ANIME_CHARACTERS } from "wsper";
-const random = new AnimeRandomScraper();
-
-await random.getImage("nezuko")
-// → WsperResponse<AnimeRandomResult>
-// data: { character, imageUrl, sourceUrl }
-
-console.log(ANIME_CHARACTERS);
-// ["nezuko", "zero-two", "rem", "miku", ...]
+```json
+{
+  "originalPath": null,
+  "outputPath": null,
+  "resultUrl": "https://cdn.test/out.jpg",
+  "scale": 4
+}
 ```
 
----
-
-## Brat Generator
+### PhotoAiScraper
 
-Generator konten visual bergaya **brat** — teks besar di atas background minimalis. Bisa diekspor sebagai gambar statis, GIF animasi kata per kata, atau video MP4/WebM.
+Source: `https://photoai.imglarger.com`.
 
 ```ts
-import { BratGenerator, generateBrat, bratGenerator } from "wsper";
-
-const brat = new BratGenerator();
-
-// Atau gunakan singleton global:
-// bratGenerator.generate(...)
-
-// Atau shorthand function:
-// await generateBrat(config)
-```
-
----
+import { readFile } from "node:fs/promises";
+import { PhotoAiScraper } from "wsper-js";
 
-### generate — Image
+const image = await readFile("./portrait.jpg");
+const scraper = new PhotoAiScraper();
 
-```ts
-const result = await brat.generate({
-  canvas:     { preset: "1:1" },
-  background: { type: "solid", color: "#ffffff" },
-  text: {
-    value: "kamu pas kecil pernah nelen magnet ya? menarik banget soalnya",
-    align: "justify",
-  },
-  output: { type: "image", format: "png", path: "./brat.png" },
-});
-
-// → BratResult
-interface BratResult {
-  buffer: Buffer;        // konten file dalam memory
-  format: string;        // "png" | "jpg" | "webp"
-  path?:  string;        // path file jika output.path diisi
+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);
 }
 ```
 
-**Format yang didukung:** `png`, `jpg`, `webp`
-
----
-
-### generate — GIF
-
-```ts
-const result = await brat.generate({
-  text: {
-    value: "charli xcx is so brat i can't even",
-    align: "justify",
-  },
-  background: { type: "solid", color: "#8ace00" },
-  animation: {
-    enabled:   true,
-    direction: "left-to-right",
-    mode:      "word",
-    fps:       12,
-    textSpeed: 150,   // ms per kata — prioritas di atas duration
-    duration:  3000,  // ms total — fallback jika textSpeed tidak diset
-  },
-  output: { type: "gif", path: "./brat.gif" },
-});
-
-// result.buffer → Buffer GIF
-// result.format → "gif"
-```
-
----
-
-### generate — Video
+Representative output:
 
-```ts
-const result = await brat.generate({
-  text: { value: "brat video" },
-  animation: { enabled: true, mode: "word", fps: 30 },
-  output: {
-    type:   "video",
-    format: "mp4",         // "mp4" | "webm"
-    codec:  "libx264",     // optional
-    path:   "./brat.mp4",
-  },
-});
-
-// result.buffer → Buffer MP4/WebM
-// result.format → "mp4" | "webm"
+```json
+{
+  "status": "success",
+  "downloadUrl": "https://cdn.test/out.jpg",
+  "raw": {
+    "status": "success",
+    "downloadUrl": "https://cdn.test/out.jpg"
+  }
+}
 ```
 
-> Membutuhkan FFmpeg (`C:\ffmpeg\ffmpeg.exe` atau di PATH).
+### FaceswapScraper
 
----
-
-### withPreset
-
-Terapkan style preset ke config:
+Source: `https://api.lovefaceswap.com`.
 
 ```ts
-const cfg = brat.withPreset("brat-green", {
-  text:   { value: "brat summer" },
-  output: { type: "image", format: "png", path: "./out.png" },
-});
-
-await brat.generate(cfg);
-```
-
-| Preset | Background | Text Color | Text Blur |
-|---|---|---|---|
-| `classic` | `#ffffff` | `#111111` | 0 |
-| `blurred` | `#ffffff` | `#111111` | 2 |
-| `brat-green` | `#8ace00` | `#111111` | 1 |
-| `clean` | `#f5f5f5` | `#000000` | 0 |
-
----
+import { readFile } from "node:fs/promises";
+import { FaceswapScraper } from "wsper-js";
 
-### imageToSticker
+const [source, target] = await Promise.all([
+  readFile("./source-face.jpg"),
+  readFile("./target.jpg"),
+]);
 
-Konversi gambar apa pun menjadi sticker format Telegram/WhatsApp (512×512 WebP):
+const scraper = new FaceswapScraper();
+const result = await scraper.process(source, target);
 
-```ts
-// Dari file path
-const buf = await brat.imageToSticker("./photo.jpg", {
-  size:        512,      // ukuran sticker px (default 512)
-  format:      "webp",   // "webp" | "png"
-  quality:     90,       // kualitas WebP 1-100
-  top:         "BRAT",   // caption atas (otomatis uppercase)
-  bottom:      "2025",   // caption bawah
-  color:       "#ffffff",
-  strokeColor: "#000000",
-});
-// → Buffer WebP/PNG
-
-// Dari Buffer
-const buf2 = await brat.imageToSticker(pngBuffer, { size: 512, format: "webp" });
-
-// Langsung simpan ke file
-await brat.saveSticker("./photo.jpg", "./sticker.webp", {
-  size: 512, top: "TOP", bottom: "BOTTOM",
-});
-// → void
+console.log(result.data);
 ```
 
----
-
-### MP4 ↔ GIF Conversion
-
-#### GIF → MP4
+Representative output:
 
-```ts
-const mp4Buffer = await brat.gifToMp4("./brat.gif", "./brat.mp4", {
-  fps:   24,
-  width: 720,   // optional resize
-});
-// → Buffer MP4
+```json
+{
+  "job_id": "job-1",
+  "image": "https://cdn.test/out.jpg"
+}
 ```
 
-#### GIF → WebM
-
-```ts
-const webmBuffer = await brat.gifToWebm("./brat.gif", "./brat.webm", { fps: 24 });
-// → Buffer WebM
-```
+### UpscalerScraper
 
-#### MP4 → GIF
+Source: `https://aienhancer.ai`.
 
 ```ts
-const gifBuffer = await brat.mp4ToGif("./clip.mp4", "./clip.gif", {
-  fps:       10,    // frame rate GIF (default 10)
-  width:     480,   // lebar output GIF (default 480)
-  loop:      0,     // 0 = infinite loop
-  startTime: 5,     // mulai dari detik ke-5
-  duration:  3,     // ambil 3 detik saja
-});
-// → Buffer GIF (two-pass palette encoding untuk kualitas warna lebih baik)
-```
+import { readFile } from "node:fs/promises";
+import { UpscalerScraper } from "wsper-js";
 
----
+const image = await readFile("./photo.jpg");
+const scraper = new UpscalerScraper();
+const result = await scraper.upscaleBuffer(image, "image/jpeg");
 
-### convertImage
-
-Konversi format gambar tanpa teks/canvas:
-
-```ts
-const webpBuf = await brat.convertImage("./photo.png", "webp", "./photo.webp");
-const jpgBuf  = await brat.convertImage(pngBuffer, "jpg");
-// → Buffer dalam format target
+console.log(result.data);
 ```
 
----
-
-### Background Config
-
-```ts
-// Solid color
-background: { type: "solid", color: "#8ace00" }
-background: { type: "solid", color: "white" }
-
-// Linear gradient
-background: {
-  type:      "linear-gradient",
-  colors:    ["#b7ff00", "#ffffff"],
-  direction: "to-bottom-right",
-  //   "to-top" | "to-bottom" | "to-left" | "to-right"
-  //   "to-bottom-right" | "to-bottom-left" | "to-top-right" | "to-top-left"
-}
+Representative output:
 
-// Radial gradient
-background: {
-  type:     "radial-gradient",
-  colors:   ["#ffffff", "#d9d9d9"],
-  position: "center",
-  //   "center" | "top" | "bottom" | "left" | "right"
-  //   "top-left" | "top-right" | "bottom-left" | "bottom-right"
-  //   { x: 50, y: 50 }   ← posisi custom dalam persen (0-100)
+```json
+{
+  "id": "task-1",
+  "input": "https://cdn.test/in.jpg",
+  "output": "https://cdn.test/out.jpg"
 }
 ```
 
----
+### StalkScraper
 
-### Text Config
+Source: npm registry API at `https://registry.npmjs.org`.
 
 ```ts
-text: {
-  value:       "teks yang ingin ditampilkan",
+import { StalkScraper } from "wsper-js";
 
-  align:       "justify",    // "left" | "right" | "center" | "justify"
+const scraper = new StalkScraper();
+const result = await scraper.getNpmPackage("axios");
 
-  fontSize:    "auto",       // atau angka: 48 — "auto" menyesuaikan ukuran canvas
-  minFontSize: 20,           // batas bawah auto fit (default 20)
-  maxFontSize: 180,          // batas atas auto fit (default 180)
-
-  fontFamily:  '"Arial Black", sans-serif',
-  fontWeight:  900,          // atau string: "bold"
+console.log(result.data?.title);
+console.log(result.data?.install);
+```
 
-  lineHeight:  1.05,         // default 1.05 — rapat khas brat style
-  color:       "#111111",
+Representative output:
 
-  blur:        2,            // blur teks 0–8 (0 = tidak ada, default 0)
+```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": []
 }
 ```
 
----
+### MediafireScraper
 
-### Canvas Config
+Source: Mediafire public file page HTML.
 
 ```ts
-// Preset aspect ratio
-canvas: { preset: "1:1" }       // 1080 × 1080
-canvas: { preset: "9:16" }      // 1080 × 1920  (portrait / story)
-canvas: { preset: "16:9" }      // 1920 × 1080  (landscape / widescreen)
-
-// Preset nama
-canvas: { preset: "square" }    // 1024 × 1024
-canvas: { preset: "story" }     // 1080 × 1920
-canvas: { preset: "post" }      // 1080 × 1350
-canvas: { preset: "landscape" } // 1920 × 1080
-
-// Ukuran manual
-canvas: { width: 1200, height: 800 }
-
-// Aspect ratio + satu dimensi → dimensi lain dihitung otomatis
-canvas: { aspectRatio: "4:3", width: 1200 }   // → height 900
-canvas: { aspectRatio: "16:9", height: 720 }  // → width 1280
-canvas: { aspectRatio: "4:3" }                // → 1080 × 810 (base 1080)
-```
+import { MediafireScraper } from "wsper-js";
 
-**Padding:**
+const scraper = new MediafireScraper();
+const result = await scraper.getLink(
+  "https://www.mediafire.com/file/ipnyzofjcwri357/test-10mb.bin/file",
+);
 
-```ts
-layout: { padding: 64 }
-layout: { padding: { top: 80, right: 64, bottom: 80, left: 64 } }
+console.log(result.data);
 ```
 
----
+Representative output:
 
-### Animation Config
-
-```ts
-animation: {
-  enabled:   true,
-  direction: "left-to-right",   // "left-to-right" | "right-to-left"
-  mode:      "word",            // "word" | "line" | "character"
-  fps:       12,
-
-  // Pilih satu untuk kecepatan:
-  textSpeed: 150,    // ms per step — prioritas utama
-  duration:  3000,   // ms total dibagi rata ke semua step — fallback
+```json
+{
+  "downloadUrl": "https://download.example/myfile.zip",
+  "fileName": "My_File.zip",
+  "fileSize": "50 MB",
+  "fileType": "ZIP"
 }
 ```
 
-| Mode | Deskripsi |
-|---|---|
-| `word` | Kata muncul satu per satu — cocok untuk brat GIF |
-| `line` | Baris muncul satu per satu — lebih dramatis |
-| `character` | Huruf muncul satu per satu — paling smooth |
-
----
+## 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:
 
-### Output Config
-
-```ts
-// Image
-output: { type: "image", format: "png",  path: "./out.png" }
-output: { type: "image", format: "jpg" }
-output: { type: "image", format: "webp" }
-
-// GIF
-output: { type: "gif", path: "./out.gif" }
-
-// Video
-output: { type: "video", format: "mp4",  path: "./out.mp4" }
-output: { type: "video", format: "webm", path: "./out.webm" }
-output: { type: "video", format: "mp4",  codec: "libx264", path: "./out.mp4" }
+```bash
+npx tsx examples/alllexamp.ts
 ```
 
-> `path` opsional. Jika tidak diisi, file tidak disimpan ke disk — hanya `buffer` yang dikembalikan di `BratResult`.
-
----
+The runner writes scraper JSON results to `downloads/output/scrapers/` and subprocess logs to `downloads/output/examples/`.
 
-## Chart Image Generator
+Summary fields:
 
-Generator chart analytics berbasis canvas. Default-nya memakai model poster vintage dari `analytics-stat-image`, tetapi tersedia beberapa model dan bisa di-override per render.
-
-```ts
-import {
-  ChartGenerator,
-  generateAnalyticsStatsImage,
-  getAnalyticsChartModels,
-} from "wsper";
-
-const chart = new ChartGenerator();
-
-await chart.generateStatsImage({
-  model: "modern-dashboard",
-  title: "Group Analytics Report",
-  subtitle: "Monthly and weekly usage overview",
-  monthly: [
-    { label: "JAN", group: 1200, user: 810 },
-    { label: "FEB", group: 980, user: 760 },
-    { label: "MAR", group: 1600, user: 920 },
-  ],
-  weekly: [
-    { label: "MON", group: 320, user: 120 },
-    { label: "TUE", group: 210, user: 90 },
-    { label: "WED", group: 450, user: 170 },
-  ],
-  output: "./analytics.png",
-});
+| 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. |
 
-await generateAnalyticsStatsImage({ model: "compact-card" });
+Recorded walkthrough result:
 
-console.log(getAnalyticsChartModels());
+```txt
+OK   : 83
+FAIL : 0
+SKIP : 2
+Total: 85
 ```
 
-Model bawaan:
+Individual examples can also be run directly:
 
-| Model | Layout | Cocok untuk |
-|---|---|---|
-| `vintage-poster` | poster statistik vintage | report visual penuh |
-| `modern-dashboard` | dashboard KPI | ringkasan operasional |
-| `minimal-report` | report bersih | dokumen atau lampiran |
-| `dark-neon` | dark analytics | preview sosial atau tema gelap |
-| `compact-card` | kartu ringkas | thumbnail dan summary kecil |
-
-Kustomisasi fleksibel:
-
-```ts
-await generateAnalyticsStatsImage({
-  model: "modern-dashboard",
-  modelOverrides: {
-    monthlyChart: "grouped-bars",
-    weeklyChart: "radial-bars",
-    showAnnotations: true,
-    theme: {
-      background: "#ffffff",
-      groupLine: "#111827",
-      userLine: "#0f766e",
-    },
-  },
-});
-```
-
-`monthly` dan `weekly` opsional. Jika tidak diisi, generator memakai data demo internal agar output tetap valid.
-
----
-
-## Credentials
-
-Credential tidak dibaca dari `.env`. Dua cara konfigurasi:
+```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:
 
-```ts
-// 1. Tanpa credential → library pakai internal defaults
-const wsper = new WsperScraper();
+```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.
+
+```ts
+import { WsperScraper } from "wsper-js";
 
-// 2. Custom credential per platform
 const wsper = new WsperScraper({
   spotifyCredentials: {
-    clientId:     "your-client-id",
+    clientId: "your-client-id",
     clientSecret: "your-client-secret",
   },
   credentials: {
     twitter: {
-      cookie:    "auth_token=xxx; ct0=yyy",
-      csrfToken: "yyy",
+      cookie: "<YOUR_COOKIE_HERE>",
+      csrfToken: "<YOUR_CSRF_TOKEN_HERE>",
     },
-    threads: {
-      cookie:    "sessionid=xxx",
-      csrfToken: "zzz",
+    instagram: {
+      cookie: "<YOUR_COOKIE_HERE>",
+      csrfToken: "<YOUR_CSRF_TOKEN_HERE>",
     },
   },
 });
 ```
 
-> Jangan pernah commit cookie, token, atau secret ke repository.
+Spotify custom credentials must include both `clientId` and `clientSecret`. Partial custom Spotify credentials are rejected with `ValidationError`.
 
----
+## Cloudflare, Rate Limits, and Reliability
 
-## HTTP & Queue Options
+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.
 
-```ts
-interface HttpOptions {
-  timeoutMs?:       number;   // default 30000
-  retries?:         number;   // default 3
-  retryDelayMs?:    number;
-  maxRetryAfterMs?: number;
-  maxRedirects?:    number;
-  headers?:         Record<string, string>;
-  userAgent?:       string;
-}
+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.
 
-interface QueueOptions {
-  concurrency?: number;   // default 1
-  intervalMs?:  number;
-  intervalCap?: number;
-  minDelayMs?:  number;
-  maxDelayMs?:  number;
-}
-```
+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.
 
-Contoh konfigurasi rate-limit:
+## Contributing
 
-```ts
-const wsper = new WsperScraper({
-  http:  { timeoutMs: 20000, retries: 2 },
-  queue: { concurrency: 1, minDelayMs: 3000, maxDelayMs: 7000 },
-});
+```bash
+git clone <repository-url>
+cd wsper
+npm install
+npm run typecheck
+npm run test
 ```
 
----
-
-## Download Outputs
+When adding or changing a scraper:
 
-File yang didownload disimpan ke direktori yang ditentukan di tiap method:
+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.
 
-```
-downloads/
-├── instagram/
-│   └── charli_xcx/
-│       ├── post_AbCdEfG_0.mp4
-│       ├── post_AbCdEfG_1.jpg
-│       └── metadata.json
-├── spotify/
-│   └── track_4iV5W9.mp3
-├── youtube/
-│   └── video_dQw4w9.mp4
-├── threads/
-│   └── post_CgXxXxX_0.mp4
-└── brat/
-    ├── brat.png
-    ├── brat-green.png
-    ├── brat.gif
-    ├── brat.mp4
-    └── brat.sticker.webp
-```
+## Security
 
-**CLI examples:**
-
-```bash
-npx tsx examples/instagram.example.ts <username> 6 <post-url>
-npx tsx examples/spotify.example.ts   <track-url> "" "" "" downloads/spotify
-npx tsx examples/threads.example.ts   <username-or-url> <post-url>
-npx tsx examples/twitter.example.ts   <tweet-url> <username-or-url>
-npx tsx examples/brat.example.ts
-```
+- 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.
 
-## READ THIS INFORMATION
+## License
 
-baca rek!!
-kalo ada bug gabung aja ke trus bilang ke ke yang buat lib 
+GPL-3.0-or-later. See `LICENSE` for the full license text.