wsper-js 0.1.0 → 0.1.1-wc2

package/README.md

@@ -1,1616 +1,741 @@
-<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
-```
+<h1 align="center">
+  <img alt="ShikanokoBail banner" src="https://i.pinimg.com/736x/0c/ff/62/0cff624a04a81495f4b8e69bcedd34aa.jpg" width="100%"/>
+</h1>
 
-Dependency eksternal yang dibutuhkan untuk fitur tertentu:
+<div align="center">
 
-| Fitur | Dependency |
-|---|---|
-| YouTube download / audio | `yt-dlp` (install terpisah) |
-| Video export, GIF ↔ MP4 | `ffmpeg` di PATH atau `C:\ffmpeg\ffmpeg.exe` |
+[![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-383%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.
 
-## Quick Start
+The package is ESM-only and targets Node.js 18 or newer.
 
-```ts
-import { WsperScraper, BratGenerator, ChartGenerator } from "wsper";
+## Features
 
-// Semua scraper dalam satu kelas
-const wsper = new WsperScraper();
+- 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.
 
-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/...");
+## Installation
 
-// 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",
-});
+```bash
+npm install wsper-js
 ```
 
----
-
-## WsperScraper — Kelas Utama
-
-```ts
-import { WsperScraper } from "wsper";
-
-const wsper = new WsperScraper(config?: WsperScraperConfig);
+```bash
+pnpm add wsper-js
 ```
 
-### 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;
-}
+```bash
+yarn add wsper-js
 ```
 
-### 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 |
+Some optional capabilities need external binaries:
 
----
+| Feature | External tool |
+| --- | --- |
+| YouTube and Spotify media enrichment/download helpers | `yt-dlp` |
+| Video export and GIF/MP4 conversion | `ffmpeg` in `PATH` or configured path |
 
-## Response Structure
-
-Semua scraper mengembalikan `WsperResponse<T>`:
+## Quick Start
 
 ```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;
-  };
-}
-```
-
-**Pattern penggunaan:**
+import { LyricsScraper } from "wsper-js";
 
-```ts
-const res = await wsper.instagram.getProfile("username");
+const lyrics = new LyricsScraper();
+const result = await lyrics.search("after hours the weeknd");
 
-if (res.ok) {
-  console.log(res.data.username);
-  console.log(res.meta.durationMs, "ms");
-} else {
-  console.error(res.error?.code, res.error?.message);
+if (!result.ok) {
+  throw new Error(`${result.error?.code}: ${result.error?.message}`);
 }
-```
-
----
 
-## Scrapers
-
----
-
-### Instagram
-
-```ts
-import { InstagramScraper } from "wsper";
-const ig = new InstagramScraper(options?: InstagramScraperOptions);
-```
-
-#### `getProfile(username)` → `WsperResponse<InstagramProfile>`
-
-```ts
-await ig.getProfile("charli_xcx")
+console.log(result.statusCode);
+console.log(result.data?.title);
+console.log(result.data?.lyrics);
 ```
 
-```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;
-}
-```
-
-#### `getFeed(username, options?)` → `WsperResponse<InstagramFeed>`
+You can also use `WsperScraper` for the aggregate social/media scraper entrypoint:
 
 ```ts
-await ig.getFeed("charli_xcx", { count: 12, maxId: "cursor" })
-```
+import { WsperScraper } from "wsper-js";
 
-```ts
-interface InstagramFeed {
-  items:     InstagramMediaItem[];
-  nextMaxId: string | null;
-  hasMore:   boolean;
-}
+const wsper = new WsperScraper({
+  queue: { concurrency: 1, minDelayMs: 500, maxDelayMs: 1500 },
+});
 
-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 track = await wsper.spotify.search("never gonna give you up", { limit: 3 });
+const video = await wsper.youtube.getVideo("dQw4w9WgXcQ");
 
-interface InstagramCarouselItem {
-  id:           string;
-  mediaType:    number;
-  thumbnailUrl: string | null;
-  videoUrl:     string | null;
-}
+console.log(track.ok, video.ok);
 ```
 
-#### `getPost(input)` → `WsperResponse<InstagramMediaItem>`
-
-```ts
-await ig.getPost("https://www.instagram.com/p/AbCdEfG/")
-await ig.getPost("AbCdEfG")   // shortcode langsung
-```
+`WsperScraper` currently exposes `spotify`, `twitter`, `threads`, `instagram`, `pinterest`, `youtube`, and `cai`. Other scrapers are exported as named classes.
 
-#### `getProfileWithFeed(username, options?)` → `WsperResponse<InstagramProfileWithFeed>`
+## Response Shape
 
-```ts
-await ig.getProfileWithFeed("charli_xcx", { count: 6 })
-```
+Scraper methods return `WsperResponse<TData>`:
 
 ```ts
-interface InstagramProfileWithFeed {
-  profile:   InstagramProfile;
-  items:     InstagramMediaItem[];
-  nextMaxId: string | null;
-  hasMore:   boolean;
+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;
 }
-```
-
-#### `downloadPost(input)` → `WsperResponse<InstagramDownloadResult>`
-
-```ts
-await ig.downloadPost({
-  postUrl:         "https://www.instagram.com/p/AbCdEfG/",
-  outputDir:       "./downloads/instagram",
-  includeMetadata: true,
-})
-```
 
-```ts
-interface InstagramDownloadResult {
-  sourceUrl:    string;
-  outputDir:    string;
-  metadataPath: string | null;
-  assets: Array<{
-    url:        string;
-    outputPath: string;
-    type:       "image" | "video";
-    index:      number;
-  }>;
+export interface WsperResponseMeta {
+  statusCode: number;
+  sourceUrl: string;
+  fetchedAt: string;
+  durationMs: number;
 }
 ```
 
-#### `downloadProfile(input)` → `WsperResponse<InstagramDownloadResult>`
-
-```ts
-await ig.downloadProfile({
-  usernameOrUrl:         "charli_xcx",
-  outputDir:             "./downloads/instagram",
-  feedCount:             9,
-  includeProfilePicture: true,
-  includeInitialPosts:   true,
-  includeMetadata:       true,
-})
-```
-
----
-
-### Spotify
-
-```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 })
-```
+Recommended handling:
 
 ```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;
-}
+const response = await scraper.search("query");
 
-// Meta tambahan untuk track
-interface SpotifyTrackMeta extends WsperResponseMeta {
-  externalSourceUrl: string | null;
+if (response.ok && response.data !== null) {
+  console.log(response.data);
+} else {
+  console.error(response.statusCode, response.error?.code, response.error?.message);
 }
 ```
 
-#### `getAlbum(input, options?)` → `WsperResponse<SpotifyAlbumWithTracks>`
+## Usage Examples
 
-```ts
-await spotify.getAlbum("https://open.spotify.com/album/...")
-```
-
-```ts
-interface SpotifyAlbumWithTracks {
-  album:  NormalizedSpotifyAlbum;
-  tracks: NormalizedSpotifyTrack[];
-}
+The examples below use public exports from `src/index.ts` and representative response fields from implementation and tests.
 
-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;
-}
-```
+### Public-Link Examples
 
-#### `getPlaylist(input)` → `WsperResponse<NormalizedSpotifyPlaylist>`
+Some scrapers need live public targets. The bundled examples avoid dummy URLs:
 
-```ts
-await spotify.getPlaylist("https://open.spotify.com/playlist/...")
+```bash
+npx tsx examples/gdrive.example.ts
+npx tsx examples/foreign-news.example.ts
+npx tsx examples/pubgmobile.example.ts
+npx tsx examples/soundcloud.example.ts
 ```
 
-#### `search(query, options?)` → `WsperResponse<SpotifySearchResult>`
-
-```ts
-await spotify.search("charli xcx brat", { limit: 10, type: ["track", "album"] })
-```
+`GDriveScraper` defaults to a verified public Google Drive PDF in the example. `ForeignNewsScraper` uses the BBC World RSS feed. `PubgMobileScraper` uses the official server-rendered announcement list because the public `news.shtml` page is a client-rendered shell. Scrapers that commonly require a valid session or cookie, such as TeraBox, Pixiv, and Xiaohongshu, require an explicit URL/ID in their examples instead of using placeholder links.
 
-#### `downloadPost(input)` / `downloadProfile(input)`
+When a live endpoint returns HTTP 200 but no parseable data, these scrapers return `ok: false` with a parser error code instead of returning `ok: true` with empty data.
 
-```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 }
-
-await spotify.exchangeCode(code)    // → SpotifyOAuthToken
-await spotify.refreshToken(token)   // → SpotifyOAuthToken
-await spotify.getAccessToken()      // → string
-spotify.invalidateToken()           // → void
-```
+import { LyricsScraper } from "wsper-js";
 
----
-
-### YouTube
-
-```ts
-import { YouTubeScraper } from "wsper";
-const yt = new YouTubeScraper(options?: YouTubeScraperOptions);
-```
+const scraper = new LyricsScraper();
+const result = await scraper.search("after hours the weeknd");
 
-```ts
-interface YouTubeScraperOptions {
-  debug?:       boolean;
-  ytdlpPath?:   string;   // path ke yt-dlp binary
-  ffmpegPath?:  string;
-  ffprobePath?: string;
-  outputDir?:   string;
-  searchLimit?: number;
-}
+console.log(result.data);
 ```
 
-#### `getVideo(input)` → `WsperResponse<YoutubeVideoMetadata>`
+Representative output:
 
-```ts
-await yt.getVideo("https://youtu.be/dQw4w9WgXcQ")
-```
-
-```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 }
-```
-
----
-
-### Minecraft Addon
-
-```ts
-import { McAddonScraper } from "wsper";
-const mc = new McAddonScraper();
-
-await mc.search("texture pack")
-// → WsperResponse<McAddonSearchItem[]>
-
-await mc.getDetail("https://mcpedl.com/addon/...")
-// → WsperResponse<McAddonDetail>
-// data: { title, description, downloadLinks[], images[], author }
-```
-
----
-
-### 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>
-
-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>
-```
-
----
+### WallpaperScraper
 
-### Drakor
+Source: Wallhaven search API at `https://wallhaven.cc/api/v1/search`.
 
 ```ts
-import { DrakorScraper } from "wsper";
-const drakor = new DrakorScraper();
-
-await drakor.search("undercover")
-// -> WsperResponse<DrakorList>
+import { WallpaperScraper } from "wsper-js";
 
-await drakor.detail("undercover-miss-hong")
-// -> WsperResponse<DrakorDetail>
+const scraper = new WallpaperScraper();
+const result = await scraper.search("cyberpunk");
 
-await drakor.ongoing()
-// -> WsperResponse<DrakorList>
-
-await drakor.getAll(1)
-// -> WsperResponse<DrakorList>
+console.log(result.data?.total);
+console.log(result.data?.results[0]);
 ```
 
----
-
-### Dramabox
+Representative output:
 
-```ts
-import { DramaboxScraper } from "wsper";
-const dramabox = new DramaboxScraper();
-
-await dramabox.search("romance")
-// -> WsperResponse<DramaboxResult>
+```json
+{
+  "total": 1,
+  "results": [
+    {
+      "title": "Wallpaper sky123",
+      "resolution": "1920x1080",
+      "image": "https://w.wallhaven.cc/full/sky123.jpg",
+      "page": "https://wallhaven.cc/w/sky123"
+    }
+  ]
+}
 ```
 
----
+### WwCharScraper
 
-### SakuraNovel
+Source: Wuthering Waves Fandom MediaWiki parse API.
 
 ```ts
-import { SakuraNovelScraper } from "wsper";
-const sakura = new SakuraNovelScraper();
+import { WwCharScraper } from "wsper-js";
 
-await sakura.search("isekai")
-// -> WsperResponse<SakuraNovelSearchItem[]>
+const scraper = new WwCharScraper();
+const result = await scraper.getCharacter("Jin Hsi");
 
-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 }
+console.log(result.data);
 ```
 
----
+Representative output:
 
-### HokInfo
-
-```ts
-import { HokInfoScraper } from "wsper";
-const hok = new HokInfoScraper();
-
-await hok.getCharacter("Sun Wukong")
-// -> WsperResponse<HokInfoResult>
+```json
+{
+  "title": "Jiyan",
+  "slug": "Jin_Hsi",
+  "url": "https://wutheringwaves.fandom.com/wiki/Jin_Hsi",
+  "bio": "Bio karakter.",
+  "profile": {},
+  "images": []
+}
 ```
 
----
+### HokInfoScraper
 
-### IkiruManga
+Source: Honor of Kings Fandom MediaWiki parse API.
 
 ```ts
-import { IkiruMangaScraper } from "wsper";
-const ikiru = new IkiruMangaScraper();
-
-await ikiru.search("solo leveling")
-// -> WsperResponse<IkiruMangaResult>
-```
-
----
+import { HokInfoScraper } from "wsper-js";
 
-### Wallpaper
+const scraper = new HokInfoScraper();
+const result = await scraper.getCharacter("Angela");
 
-```ts
-import { WallpaperScraper } from "wsper";
-const wallpaper = new WallpaperScraper();
-
-await wallpaper.search("blue sky")
-// -> WsperResponse<WallpaperResult>
+console.log(result.data?.profile);
 ```
 
----
+Representative output:
 
-### WwChar
-
-```ts
-import { WwCharScraper } from "wsper";
-const ww = new WwCharScraper();
-
-await ww.getCharacter("Jin Hsi")
-// -> WsperResponse<WwCharResult>
+```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
 
-### Videy
+Source: WordPress-style resolver endpoint, defaulting to `https://capdownloader.com/wp-json/aio-dl/video-data/`.
 
 ```ts
-import { VideyScraper } from "wsper";
-const videy = new VideyScraper();
+import { CapCutScraper } from "wsper-js";
 
-await videy.upload("./video.mp4")
-// -> WsperResponse<VideyUploadResult>
-```
-
----
+const scraper = new CapCutScraper();
+const result = await scraper.download("https://www.capcut.com/t/Zs82gHj1a/");
 
-### OCR
-
-```ts
-import { OcrScraper } from "wsper";
-const ocr = new OcrScraper();
-
-await ocr.scan(imageBuffer)
-// -> WsperResponse<OcrScanResult>
+console.log(result.data);
 ```
 
----
-
-### Webp2Mp4
-
-```ts
-import { Webp2Mp4Scraper } from "wsper";
-const converter = new Webp2Mp4Scraper();
-
-await converter.toMp4(webpBuffer)
-// -> WsperResponse<Webp2Mp4Result>
+Representative output:
 
-await converter.toPng("https://example.com/image.webp")
-// -> WsperResponse<Webp2Mp4Result>
+```json
+{
+  "videoUrl": "https://cdn.example/video.mp4"
+}
 ```
 
----
+### ImgUpscalerScraper
 
-### MConverter
+Source: `https://get1.imglarger.com` upload and status endpoints.
 
 ```ts
-import { MConverterScraper } from "wsper";
-const converter = new MConverterScraper();
+import { readFile } from "node:fs/promises";
+import { ImgUpscalerScraper } from "wsper-js";
 
-await converter.getTargets("image.webp")
-// -> WsperResponse<MConverterTargetsResult>
+const image = await readFile("./photo.jpg");
+const scraper = new ImgUpscalerScraper();
+const result = await scraper.upscaleBuffer(image, "photo.jpg", 4);
 
-await converter.convertBuffer(imageBuffer, "image.webp", "png")
-// -> WsperResponse<MConverterConvertResult>
+console.log(result.data);
 ```
 
----
-
-### HtmlToJpg
+Representative output:
 
-```ts
-import { HtmlToJpgScraper } from "wsper";
-const converter = new HtmlToJpgScraper();
-
-await converter.convertBuffer(htmlBuffer, "page.html")
-// -> WsperResponse<HtmlToJpgResult>
+```json
+{
+  "originalPath": null,
+  "outputPath": null,
+  "resultUrl": "https://cdn.test/out.jpg",
+  "scale": 4
+}
 ```
 
----
+### PhotoAiScraper
 
-### Stalk
+Source: `https://photoai.imglarger.com`.
 
 ```ts
-import { StalkScraper } from "wsper";
-const stalk = new StalkScraper();
+import { readFile } from "node:fs/promises";
+import { PhotoAiScraper } from "wsper-js";
 
-await stalk.getNpmPackage("wsper")
-// -> WsperResponse<NpmPackage>
-```
-
----
+const image = await readFile("./portrait.jpg");
+const scraper = new PhotoAiScraper();
 
-### ModAndroid
-
-```ts
-import { ModAndroidScraper } from "wsper";
-const modAndroid = new ModAndroidScraper();
-
-await modAndroid.aptoide("maps")
-// -> WsperResponse<AptoideResult>
+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);
+}
 ```
 
----
-
-### Upscaler
+Representative output:
 
-```ts
-import { UpscalerScraper } from "wsper";
-const upscaler = new UpscalerScraper();
-
-await upscaler.upscaleBuffer(imageBuffer, "image/jpeg")
-// -> WsperResponse<UpscalerResult>
+```json
+{
+  "status": "success",
+  "downloadUrl": "https://cdn.test/out.jpg",
+  "raw": {
+    "status": "success",
+    "downloadUrl": "https://cdn.test/out.jpg"
+  }
+}
 ```
 
----
+### FaceswapScraper
 
-### Image
+Source: `https://api.lovefaceswap.com`.
 
 ```ts
-import { ImageScraper } from "wsper";
-const image = new ImageScraper();
+import { readFile } from "node:fs/promises";
+import { FaceswapScraper } from "wsper-js";
 
-await image.safebooru("blue_sky", 0, 10)
-// -> WsperResponse<ImageSearchResult>
-```
+const [source, target] = await Promise.all([
+  readFile("./source-face.jpg"),
+  readFile("./target.jpg"),
+]);
 
----
-
-### ImgUpscaler
-
-```ts
-import { ImgUpscalerScraper } from "wsper";
-const upscaler = new ImgUpscalerScraper();
+const scraper = new FaceswapScraper();
+const result = await scraper.process(source, target);
 
-await upscaler.upscaleBuffer(imageBuffer, "image.jpg", 2)
-// -> WsperResponse<ImgUpscalerResult>
+console.log(result.data);
 ```
 
----
+Representative output:
 
-### Faceswap
-
-```ts
-import { FaceswapScraper } from "wsper";
-const faceswap = new FaceswapScraper();
-
-await faceswap.process(sourceImageBuffer, targetImageBuffer)
-// -> WsperResponse<FaceswapResult>
+```json
+{
+  "job_id": "job-1",
+  "image": "https://cdn.test/out.jpg"
+}
 ```
 
----
+### UpscalerScraper
 
-### PhotoAi
+Source: `https://aienhancer.ai`.
 
 ```ts
-import { PhotoAiScraper } from "wsper";
-const photoAi = new PhotoAiScraper();
-
-await photoAi.uploadBuffer(imageBuffer, "image.jpg")
-// -> WsperResponse<PhotoAiUploadResult>
-```
-
----
+import { readFile } from "node:fs/promises";
+import { UpscalerScraper } from "wsper-js";
 
-### Lyrics
+const image = await readFile("./photo.jpg");
+const scraper = new UpscalerScraper();
+const result = await scraper.upscaleBuffer(image, "image/jpeg");
 
-```ts
-import { LyricsScraper } from "wsper";
-const lyrics = new LyricsScraper();
-
-await lyrics.search("brat charli xcx")
-// → WsperResponse<LyricsResult>
-// data: { title, artist, lyrics, sourceUrl }
+console.log(result.data);
 ```
 
----
-
-### Resep
+Representative output:
 
-```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[] }
+```json
+{
+  "id": "task-1",
+  "input": "https://cdn.test/in.jpg",
+  "output": "https://cdn.test/out.jpg"
+}
 ```
 
----
+### StalkScraper
 
-### Top Anime
+Source: npm registry API at `https://registry.npmjs.org`.
 
 ```ts
-import { TopAnimeScraper } from "wsper";
-const anime = new TopAnimeScraper();
+import { StalkScraper } from "wsper-js";
 
-await anime.getTopAnime(25)
-// → WsperResponse<TopAnimeItem[]>
-// data[]: { rank, title, url, imageUrl, score, type, episodes, members }
-```
-
----
+const scraper = new StalkScraper();
+const result = await scraper.getNpmPackage("axios");
 
-### Anime Quote
-
-```ts
-import { AnimeQuoteScraper } from "wsper";
-const quote = new AnimeQuoteScraper();
-
-await quote.getRandom()
-// → WsperResponse<AnimeQuoteItem>
-// data: { quote, character, anime, imageUrl }
+console.log(result.data?.title);
+console.log(result.data?.install);
 ```
 
----
-
-### Anime Random
-
-```ts
-import { AnimeRandomScraper, ANIME_CHARACTERS } from "wsper";
-const random = new AnimeRandomScraper();
-
-await random.getImage("nezuko")
-// → WsperResponse<AnimeRandomResult>
-// data: { character, imageUrl, sourceUrl }
+Representative output:
 
-console.log(ANIME_CHARACTERS);
-// ["nezuko", "zero-two", "rem", "miku", ...]
+```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": []
+}
 ```
 
----
-
-## Brat Generator
+### MediafireScraper
 
-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: Mediafire public file page HTML.
 
 ```ts
-import { BratGenerator, generateBrat, bratGenerator } from "wsper";
+import { MediafireScraper } from "wsper-js";
 
-const brat = new BratGenerator();
+const scraper = new MediafireScraper();
+const result = await scraper.getLink(
+  "https://www.mediafire.com/file/ipnyzofjcwri357/test-10mb.bin/file",
+);
 
-// Atau gunakan singleton global:
-// bratGenerator.generate(...)
-
-// Atau shorthand function:
-// await generateBrat(config)
+console.log(result.data);
 ```
 
----
-
-### generate — Image
-
-```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" },
-});
+Representative output:
 
-// → BratResult
-interface BratResult {
-  buffer: Buffer;        // konten file dalam memory
-  format: string;        // "png" | "jpg" | "webp"
-  path?:  string;        // path file jika output.path diisi
+```json
+{
+  "downloadUrl": "https://download.example/myfile.zip",
+  "fileName": "My_File.zip",
+  "fileSize": "50 MB",
+  "fileType": "ZIP"
 }
 ```
 
-**Format yang didukung:** `png`, `jpg`, `webp`
-
----
+### CaiScraper
 
-### generate — GIF
+Source: Character.AI WebSocket & API integrations.
 
 ```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" },
-});
+import { CaiScraper } from "wsper-js";
 
-// result.buffer → Buffer GIF
-// result.format → "gif"
-```
-
----
-
-### generate — Video
-
-```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",
+const scraper = new CaiScraper({
+  credentials: {
+    bearerToken: "YOUR_CHARACTER_AI_TOKEN",
   },
 });
 
-// result.buffer → Buffer MP4/WebM
-// result.format → "mp4" | "webm"
-```
-
-> Membutuhkan FFmpeg (`C:\ffmpeg\ffmpeg.exe` atau di PATH).
-
----
-
-### withPreset
-
-Terapkan style preset ke config:
-
-```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 |
-
----
-
-### imageToSticker
-
-Konversi gambar apa pun menjadi sticker format Telegram/WhatsApp (512×512 WebP):
-
-```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
-```
-
----
-
-### MP4 ↔ GIF Conversion
-
-#### GIF → MP4
-
-```ts
-const mp4Buffer = await brat.gifToMp4("./brat.gif", "./brat.mp4", {
-  fps:   24,
-  width: 720,   // optional resize
-});
-// → Buffer MP4
-```
-
-#### GIF → WebM
+// 1. Search for a character
+const search = await scraper.searchCharacters("Mario");
+console.log(search.data?.[0]);
 
-```ts
-const webmBuffer = await brat.gifToWebm("./brat.gif", "./brat.webm", { fps: 24 });
-// → Buffer WebM
-```
-
-#### MP4 → GIF
-
-```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
+// 2. Chat with a character (optionally using a custom voice ID)
+const chat = await scraper.chat({
+  characterId: "rGKdvZewGUZEJFEQPEBMS5JLQOTOrxi-8ByLFsGmgQM",
+  message: "Hello Mario!",
+  voiceId: "4fdd6bc1-c659-4587-b462-53f569b39078",
 });
-// → Buffer GIF (two-pass palette encoding untuk kualitas warna lebih baik)
-```
-
----
-
-### 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
-```
-
----
-
-### 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"
-}
-
-// 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)
-}
-```
-
----
+console.log(chat.data?.text);
+console.log(chat.data?.audioUrl); // Generated TTS audio URL
 
-### Text Config
-
-```ts
-text: {
-  value:       "teks yang ingin ditampilkan",
-
-  align:       "justify",    // "left" | "right" | "center" | "justify"
-
-  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"
-
-  lineHeight:  1.05,         // default 1.05 — rapat khas brat style
-  color:       "#111111",
-
-  blur:        2,            // blur teks 0–8 (0 = tidak ada, default 0)
-}
-```
-
----
-
-### Canvas Config
-
-```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)
-```
-
-**Padding:**
-
-```ts
-layout: { padding: 64 }
-layout: { padding: { top: 80, right: 64, bottom: 80, left: 64 } }
+// Chat sessions stay connected per character and are reused by later chat()
+// calls. Disconnect them when your app is done with the character.
+await scraper.disconnectCharacterSession("rGKdvZewGUZEJFEQPEBMS5JLQOTOrxi-8ByLFsGmgQM");
+// Or:
+await scraper.disconnectAllCharacterSessions();
 ```
 
----
-
-### Animation Config
+Representative output:
 
-```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
+{
+  "text": "It's-a me, Mario!",
+  "audioUrl": "https://storage.googleapis.com/.../voice.mp3",
+  "raw": { ... }
 }
 ```
 
-| 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 |
-
----
-
-### Output Config
+## 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 |
+| `CaiScraper` | Character.AI search, chat, and voice details | `neo.character.ai` API & WebSockets | Yes (Token required) | `examples/cai.example.ts` | `searchCharacters`, `chat`, `getVoice` |
+| `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:
 
-```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`.
-
----
-
-## Chart Image Generator
-
-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",
-});
-
-await generateAnalyticsStatsImage({ model: "compact-card" });
-
-console.log(getAnalyticsChartModels());
-```
+The runner writes scraper JSON results to `downloads/output/scrapers/` and subprocess logs to `downloads/output/examples/`.
 
-Model bawaan:
+Summary fields:
 
-| 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 |
+| 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. |
 
-Kustomisasi fleksibel:
+Recorded walkthrough result:
 
-```ts
-await generateAnalyticsStatsImage({
-  model: "modern-dashboard",
-  modelOverrides: {
-    monthlyChart: "grouped-bars",
-    weeklyChart: "radial-bars",
-    showAnnotations: true,
-    theme: {
-      background: "#ffffff",
-      groupLine: "#111827",
-      userLine: "#0f766e",
-    },
-  },
-});
+```txt
+OK   : 83
+FAIL : 0
+SKIP : 2
+Total: 85
 ```
 
-`monthly` dan `weekly` opsional. Jika tidak diisi, generator memakai data demo internal agar output tetap valid.
-
----
+Individual examples can also be run directly:
 
-## 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: {
+    cai: {
+      bearerToken: "<YOUR_TOKEN_HERE>",
+    },
     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.