wsper-js 0.1.0

package/README.md

@@ -0,0 +1,1616 @@
+<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` |
+
+---
+
+## Quick Start
+
+```ts
+import { WsperScraper, BratGenerator, ChartGenerator } from "wsper";
+
+// Semua scraper dalam satu kelas
+const wsper = new WsperScraper();
+
+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/...");
+
+// 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;
+  };
+}
+```
+
+**Pattern penggunaan:**
+
+```ts
+const res = await wsper.instagram.getProfile("username");
+
+if (res.ok) {
+  console.log(res.data.username);
+  console.log(res.meta.durationMs, "ms");
+} else {
+  console.error(res.error?.code, res.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")
+```
+
+```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>`
+
+```ts
+await ig.getFeed("charli_xcx", { count: 12, maxId: "cursor" })
+```
+
+```ts
+interface InstagramFeed {
+  items:     InstagramMediaItem[];
+  nextMaxId: string | null;
+  hasMore:   boolean;
+}
+
+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;
+}
+
+interface InstagramCarouselItem {
+  id:           string;
+  mediaType:    number;
+  thumbnailUrl: string | null;
+  videoUrl:     string | null;
+}
+```
+
+#### `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;
+}
+```
+
+#### `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;
+  }>;
+}
+```
+
+#### `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 })
+```
+
+```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;
+}
+
+// Meta tambahan untuk track
+interface SpotifyTrackMeta extends WsperResponseMeta {
+  externalSourceUrl: string | null;
+}
+```
+
+#### `getAlbum(input, options?)` → `WsperResponse<SpotifyAlbumWithTracks>`
+
+```ts
+await spotify.getAlbum("https://open.spotify.com/album/...")
+```
+
+```ts
+interface SpotifyAlbumWithTracks {
+  album:  NormalizedSpotifyAlbum;
+  tracks: NormalizedSpotifyTrack[];
+}
+
+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;
+}
+```
+
+#### `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"] })
+```
+
+#### `downloadPost(input)` / `downloadProfile(input)`
+
+```ts
+await spotify.downloadPost({
+  trackUrl:  "https://open.spotify.com/track/...",
+  outputDir: "./downloads/spotify",
+  format:    "mp3",
+})
+// → WsperResponse<SpotifyDownloadResult>
+```
+
+#### OAuth helpers
+
+```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
+```
+
+---
+
+### YouTube
+
+```ts
+import { YouTubeScraper } from "wsper";
+const yt = new YouTubeScraper(options?: YouTubeScraperOptions);
+```
+
+```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")
+```
+
+```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;
+}
+```
+
+#### `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>
+```
+
+---
+
+### 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>
+```
+
+---
+
+### HtmlToJpg
+
+```ts
+import { HtmlToJpgScraper } from "wsper";
+const converter = new HtmlToJpgScraper();
+
+await converter.convertBuffer(htmlBuffer, "page.html")
+// -> WsperResponse<HtmlToJpgResult>
+```
+
+---
+
+### Stalk
+
+```ts
+import { StalkScraper } from "wsper";
+const stalk = new StalkScraper();
+
+await stalk.getNpmPackage("wsper")
+// -> WsperResponse<NpmPackage>
+```
+
+---
+
+### ModAndroid
+
+```ts
+import { ModAndroidScraper } from "wsper";
+const modAndroid = new ModAndroidScraper();
+
+await modAndroid.aptoide("maps")
+// -> WsperResponse<AptoideResult>
+```
+
+---
+
+### Upscaler
+
+```ts
+import { UpscalerScraper } from "wsper";
+const upscaler = new UpscalerScraper();
+
+await upscaler.upscaleBuffer(imageBuffer, "image/jpeg")
+// -> WsperResponse<UpscalerResult>
+```
+
+---
+
+### Image
+
+```ts
+import { ImageScraper } from "wsper";
+const image = new ImageScraper();
+
+await image.safebooru("blue_sky", 0, 10)
+// -> WsperResponse<ImageSearchResult>
+```
+
+---
+
+### ImgUpscaler
+
+```ts
+import { ImgUpscalerScraper } from "wsper";
+const upscaler = new ImgUpscalerScraper();
+
+await upscaler.upscaleBuffer(imageBuffer, "image.jpg", 2)
+// -> WsperResponse<ImgUpscalerResult>
+```
+
+---
+
+### Faceswap
+
+```ts
+import { FaceswapScraper } from "wsper";
+const faceswap = new FaceswapScraper();
+
+await faceswap.process(sourceImageBuffer, targetImageBuffer)
+// -> WsperResponse<FaceswapResult>
+```
+
+---
+
+### PhotoAi
+
+```ts
+import { PhotoAiScraper } from "wsper";
+const photoAi = new PhotoAiScraper();
+
+await photoAi.uploadBuffer(imageBuffer, "image.jpg")
+// -> WsperResponse<PhotoAiUploadResult>
+```
+
+---
+
+### Lyrics
+
+```ts
+import { LyricsScraper } from "wsper";
+const lyrics = new LyricsScraper();
+
+await lyrics.search("brat charli xcx")
+// → WsperResponse<LyricsResult>
+// data: { title, artist, lyrics, sourceUrl }
+```
+
+---
+
+### Resep
+
+```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[] }
+```
+
+---
+
+### 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 }
+```
+
+---
+
+### Anime Quote
+
+```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", ...]
+```
+
+---
+
+## Brat Generator
+
+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.
+
+```ts
+import { BratGenerator, generateBrat, bratGenerator } from "wsper";
+
+const brat = new BratGenerator();
+
+// Atau gunakan singleton global:
+// bratGenerator.generate(...)
+
+// Atau shorthand function:
+// await generateBrat(config)
+```
+
+---
+
+### 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" },
+});
+
+// → BratResult
+interface BratResult {
+  buffer: Buffer;        // konten file dalam memory
+  format: string;        // "png" | "jpg" | "webp"
+  path?:  string;        // path file jika output.path diisi
+}
+```
+
+**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
+
+```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"
+```
+
+> 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
+
+```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
+});
+// → 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)
+}
+```
+
+---
+
+### 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 } }
+```
+
+---
+
+### 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
+}
+```
+
+| 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
+
+```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" }
+```
+
+> `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());
+```
+
+Model bawaan:
+
+| 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:
+
+```ts
+// 1. Tanpa credential → library pakai internal defaults
+const wsper = new WsperScraper();
+
+// 2. Custom credential per platform
+const wsper = new WsperScraper({
+  spotifyCredentials: {
+    clientId:     "your-client-id",
+    clientSecret: "your-client-secret",
+  },
+  credentials: {
+    twitter: {
+      cookie:    "auth_token=xxx; ct0=yyy",
+      csrfToken: "yyy",
+    },
+    threads: {
+      cookie:    "sessionid=xxx",
+      csrfToken: "zzz",
+    },
+  },
+});
+```
+
+> Jangan pernah commit cookie, token, atau secret ke repository.
+
+---
+
+## HTTP & Queue Options
+
+```ts
+interface HttpOptions {
+  timeoutMs?:       number;   // default 30000
+  retries?:         number;   // default 3
+  retryDelayMs?:    number;
+  maxRetryAfterMs?: number;
+  maxRedirects?:    number;
+  headers?:         Record<string, string>;
+  userAgent?:       string;
+}
+
+interface QueueOptions {
+  concurrency?: number;   // default 1
+  intervalMs?:  number;
+  intervalCap?: number;
+  minDelayMs?:  number;
+  maxDelayMs?:  number;
+}
+```
+
+Contoh konfigurasi rate-limit:
+
+```ts
+const wsper = new WsperScraper({
+  http:  { timeoutMs: 20000, retries: 2 },
+  queue: { concurrency: 1, minDelayMs: 3000, maxDelayMs: 7000 },
+});
+```
+
+---
+
+## Download Outputs
+
+File yang didownload disimpan ke direktori yang ditentukan di tiap method:
+
+```
+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
+```
+
+**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
+```
+
+## READ THIS INFORMATION
+
+baca rek!!
+kalo ada bug gabung aja ke trus bilang ke ke yang buat lib