@xbibzlibrary/telebibz 0.4.5 → 3.1.1

package/README.id.md

@@ -1,306 +1,642 @@
-# telebibz
+<div align="center">
+
+[🇬 **English**](README.md) · [🇮 **Indonesia**](README.id.md)
+
+<br>
+
+<a href="https://www.npmjs.com/package/@xbibzlibrary/telebibz" title="Buka telebibz di npm">
+  <img src="https://imgbs.com/uploads/telebibz-d7b30671.png" alt="telebibz — Telegram Bot Library" width="560">
+</a>
+
+<br><br>
+
+**Library Telegram paling gampang untuk Node.js — set fitur penuh setara grammY.**<br>
+Recode mandiri atas arsitektur elegan [grammY](https://grammy.dev), dengan dependency
+produksi yang *benar-benar dipakai*, dokumentasi 🇮🇩 Indonesia-first, dan nol drama.
+
+<br>
+
+[![npm version](https://img.shields.io/npm/v/@xbibzlibrary/telebibz?style=for-the-badge&logo=npm&logoColor=white&color=CB3837&label=telebibz)](https://www.npmjs.com/package/@xbibzlibrary/telebibz)
+[![downloads](https://img.shields.io/npm/dm/@xbibzlibrary/telebibz?style=for-the-badge&logo=npm&logoColor=white&color=green&label=unduh%2Fbulan)](https://www.npmjs.com/package/@xbibzlibrary/telebibz)
+[![node](https://img.shields.io/node/v/@xbibzlibrary/telebibz?style=for-the-badge&logo=node.js&logoColor=white&color=339933&label=node)](https://nodejs.org)
+[![tests](https://img.shields.io/badge/test-30%2F30%20lulus-brightgreen?style=for-the-badge&logo=checkmarx&logoColor=white)](#-test--bukti-live)
+[![size](https://img.shields.io/badge/kode-1.7k%20baris-orange?style=for-the-badge&logo=codeigniter&logoColor=white)](#-analitik--statistik)
+[![license](https://img.shields.io/npm/l/@xbibzlibrary/telebibz?style=for-the-badge&color=blue)](LICENSE)
+[![views](https://komarev.com/ghpvc/?username=XbibzOfficial777&repo=telebibz&style=for-the-badge&color=blueviolet&label=kunjungan+repo)](https://github.com/XbibzOfficial777/telebibz)
+
+<br>
+
+`//—Xbibz Official—//`
+
+</div>
+
+---
+
+## 📑 Daftar Isi
+
+| | | |
+|---|---|---|
+| ⚡ [Kenapa telebibz?](#kenapa) | 📊 [Matriks fitur vs grammY](#matriks) | 📥 [Instalasi & persyaratan](#instalasi) |
+| 🚀 [Mulai cepat](#mulai) | 🧠 [Cara kerja (arsitektur)](#arsitektur) | 📖 [Dokumentasi lengkap](#dokumentasi) |
+| 🎛️ [Handler & filter](#handler) | 💬 [Shortcut Context](#context) | 🔘 [Keyboard & tombol](#keyboard) |
+| 🍽️ [Menu interaktif](#menu) | 🧙 [Wizard (form + tombol + edit/delete)](#wizard) | ❓ [Mode inline](#inline) |
+| 📣 [Broadcast](#broadcast) | 📎 [File & media](#file) | 🛡️ [Keandalan & rate limit](#ratelimit) |
+| 🗃️ [Session](#session) | 🇮🇩 [Error manusiawi](#error) | 🕸️ [Webhook & serverless](#webhook) |
+| 🔌 [Transport proxy](#proxy) | 🧪 [Transformer](#transformer) | 📈 [Analitik & statistik](#analitik) |
+| 🧩 [Contoh siap jalan](#contoh) | 🔬 [Test & bukti live](#test) | 📂 [Struktur repo](#struktur) |
+| 🕐 [Changelog](#changelog) | 📄 [Lisensi](#lisensi) | |
+
+<a id="kenapa"></a>
+## ⚡ Kenapa telebibz?
+
+> [!TIP]
+> **Satu prinsip:** semua fitur yang di grammY butuh plugin, di telebibz sudah
+> **bawaan** — wizard, menu, rate-limit, broadcast, download file — dan polling
+> yang *tidak mati* kena 409.
+
+- 🧠 **API grammY yang sudah kamu kenal** — `bot.cmd()`, `bot.hears()`, `ctx.reply()`, middleware, transformer
+- 🧙 **Wizard bawaan v3.1** — form tanya-jawab dengan **tombol pilihan** (reply/inline) dan mode **edit/delete** pesan
+- 🛡️ **Tahan banting** — auto-retry 429, throttler, limiter anti-spam, polling retry saat konflik 409
+- 🇮🇩 **Error manusiawi** — setiap error Telegram diterjemahkan + dikasih saran penyelesaian
+- 🔌 **Proxy API segala metode** — `api.metodeApaPun({...})` otomatis tersedia, bahkan untuk metode yang belum rilis
+- 🪶 **Ringan & jujur** — 4 dependency, semuanya terpakai nyata dan ter-test
+
+<a id="matriks"></a>
+## 📊 Matriks Fitur — parity grammY
+
+| Fitur | grammY | telebibz |
+|---|:---:|:---:|
+| Proxy API **segala metode** (auto-generated) | ✅ | ✅ |
+| ~60 shortcut bertipe (sendMessage, banChatMember…) | ✅ | ✅ |
+| Context lengkap (~70 pintasan reply/edit/admin/react) | ✅ | ✅ |
+| Context flavor business (`business_connection_id` otomatis) | plugin | ✅ bawaan |
+| Filter `on('message:photo' / ':text' / 'chat_type:private' …)` | ✅ | ✅ |
+| `cmd / hears / action / inlineQuery` | ✅ | ✅ (+ inlineQuery matcher) |
+| `branch / filter / drop / route / lazy / fork` | ✅ | ✅ |
+| Error boundary + catch | ✅ | ✅ (semua shortcut otomatis terlindungi) |
+| Session + storage swappable | ✅ | ✅ |
+| Transformer API (`api.config.use`) | ✅ | ✅ |
+| `auto-retry` 429 hormati `retry_after` | plugin | ✅ bawaan `autoRetry()` |
+| Throttler antre-rate-limit | plugin | ✅ bawaan `throttler()` |
+| Rate limit per-user | plugin | ✅ bawaan `limiter()` |
+| `InputFile` Buffer/path/stream + multipart `attach://` | ✅ | ✅ |
+| `InputMedia` builder + media group | ✅ | ✅ `InputMediaBuilder` |
+| Download file (`getFile`/`downloadFile`) | plugin | ✅ bawaan |
+| Keyboard & InlineKeyboard fluent class | ✅ | ✅ |
+| Menu interaktif | plugin | ✅ bawaan `Menu/MenuContainer` |
+| Wizard/percakapan | plugin | ✅ bawaan — **+ tombol pilihan & mode `edit`/`delete`** |
+| Long polling tahan-409 | ❌ (fatal crash) | ✅ bawaan (auto-retry 5 dtk) |
+| Broadcast siap pakai | ❌ | ✅ `bot.broadcast()` |
+| Humanisasi error + saran (🇮🇩) | ❌ | ✅ `humanize()` |
+| Banner boot + log debug | ❌ | ✅ (`DEBUG=telebibz*`) |
+| Proxy HTTP(S) untuk VPS | ⚠️ manual | ✅ opsi `proxy` transport |
+| TypeScript | ✅ full | d.ts longgar (JS-first) |
+| Bahasa dokumentasi | en | **🇬🇧 + 🇮🇩** |
+
+<a id="instalasi"></a>
+## 📥 Instalasi & Persyaratan
+
+**Persyaratan:** Node.js ≥ 18 (memakai `FormData`/`Blob` global untuk upload).
 
-![telebibz logo](https://imgbs.com/uploads/telebibz-d7b30671.png)
-
-[![CI](https://github.com/XbibzOfficial777/telebibz/actions/workflows/ci.yml/badge.svg)](https://github.com/XbibzOfficial777/telebibz/actions/workflows/ci.yml)
-[![npm version](https://img.shields.io/npm/v/@xbibzlibrary/telebibz)](https://www.npmjs.com/package/@xbibzlibrary/telebibz)
-[![npm downloads](https://img.shields.io/npm/dm/@xbibzlibrary/telebibz)](https://www.npmjs.com/package/@xbibzlibrary/telebibz)
-[![Node.js](https://img.shields.io/node/v/@xbibzlibrary/telebibz)](https://www.npmjs.com/package/@xbibzlibrary/telebibz)
+```bash
+npm install @xbibzlibrary/telebibz
+# atau
+yarn add @xbibzlibrary/telebibz
+# atau
+pnpm add @xbibzlibrary/telebibz
+```
 
-**`@xbibzlibrary/telebibz`** adalah SDK dan framework Telegram Bot untuk Node.js dan TypeScript. Paket ini menyediakan API client, polling, router, middleware, context, keyboard builder, state/session, webhook handler, queue, scheduler, cache, plugin lifecycle, CLI, dan utilitas pengujian.
+**Dependency runtime (semuanya dipakai & ter-test):**
 
-[English](README.md) · **Bahasa Indonesia** · [简体中文](README.zh-CN.md)
+| Paket | Untuk |
+|---|---|
+| `axios ^1.20` | transport keep-alive + streaming `downloadFile` |
+| `mime-types ^3.0` | deteksi content-type upload |
+| `https-proxy-agent ^9.1` | opsi proxy transport VPS |
+| `debug ^4.4` | log `DEBUG=telebibz:net,telebibz:ratelimit` |
 
-Referensi API lengkap: [English](docs/API.md) · **Indonesia** · [中文](docs/API.zh-CN.md)
+Ambil token bot dari **@BotFather** → `/newbot`. Konstruktor memvalidasi format
+token (`123456:ABC…`) dan melempar error yang jelas kalau salah.
 
-Panduan GitHub Packages: [English](docs/GITHUB_PACKAGES.md) · [Bahasa Indonesia](docs/GITHUB_PACKAGES.id.md) · [简体中文](docs/GITHUB_PACKAGES.zh-CN.md)
+<a id="mulai"></a>
+## 🚀 Mulai Cepat
 
-Panduan cepat storage (Memory/JSON/Redis/SQL/Mongo): [English](docs/STORAGE.md) · [Bahasa Indonesia](docs/STORAGE.id.md) · [简体中文](docs/STORAGE.zh-CN.md)
+```js
+const { TeleBibz } = require('@xbibzlibrary/telebibz');
 
-Panduan mulai: [English](docs/GETTING_STARTED.md) · [Bahasa Indonesia](docs/GETTING_STARTED.id.md) · [简体中文](docs/GETTING_STARTED.zh-CN.md)
+const bot = new TeleBibz('TOKEN_DARI_BOTFATHER');
 
-File (upload & download): [English](docs/FILES.md) · [Bahasa Indonesia](docs/FILES.id.md) · [简体中文](docs/FILES.zh-CN.md)
+bot.cmd('start', (ctx) => ctx.reply('Halo!'));
+bot.hears(/halo|hai/i, (ctx) => ctx.reply('halo juga 👋'));
+bot.hears('ping', (ctx) => ctx.reply('pong 🏓'));
 
-Error & rate limit: [English](docs/ERRORS.md) · [Bahasa Indonesia](docs/ERRORS.id.md) · [简体中文](docs/ERRORS.zh-CN.md)
+bot.launch();
+```
 
-Deployment webhook: [English](docs/WEBHOOK.md) · [Bahasa Indonesia](docs/WEBHOOK.id.md) · [简体中文](docs/WEBHOOK.zh-CN.md)
+```bash
+BOT_TOKEN=123:abc node index.js
+```
 
-Testing (offline dengan MockTransport): [English](docs/TESTING.md) · [Bahasa Indonesia](docs/TESTING.id.md) · [简体中文](docs/TESTING.zh-CN.md)
+```
+┌──────────────────────────────────┐
+│  🤖 TeleBibz ON                   │
+│  bot      : @botkamu (id 123456) │
+│  mode     : long-polling          │
+│  library  : telebibz 3.1.0        │
+│  brand    : //—Xbibz Official—//  │
+└──────────────────────────────────┘
+✔ menunggu update… (Ctrl+C untuk berhenti)
+```
 
-Migrasi dari Telegraf: [English](docs/MIGRATION_TELEGRAF.md) · [Bahasa Indonesia](docs/MIGRATION_TELEGRAF.id.md) · [简体中文](docs/MIGRATION_TELEGRAF.zh-CN.md)
+> [!NOTE]
+> **Hidup di VPS:** kalau ada instance bot lain yang masih polling (409 Conflict —
+> misal deploy ganda atau hosting restart), telebibz **otomatis retry tiap 5 detik
+> tanpa crash** dan menyala begitu jalur bebas. Tidak perlu PM2 babysitter.
 
-Cookbook produksi (13 resep): [English](docs/COOKBOOK.md) · [Bahasa Indonesia](docs/COOKBOOK.id.md) · [简体中文](docs/COOKBOOK.zh-CN.md)
+<a id="arsitektur"></a>
+## 🧠 Cara Kerja (Arsitektur)
 
-Katalog dokumentasi lengkap: [docs/README.md](docs/README.md)
+```
+                       ┌─────────────────────────────────────────────┐
+ Telegram Bot API ────►│  long polling (lib/runner.js)               │
+                       │  atau webhook / handleUpdate (lib/telebibz) │
+                       └──────────────────┬──────────────────────────┘
+                                          │ update JSON mentah
+                                          ▼
+                       Context(update, api, me)          lib/context.js
+                                          │
+             ┌────────────────────────────▼───────────────────────────┐
+             │  Pohon middleware `_root` (urutan tetap):              │
+             │  1. session()                 lib/session.js           │
+             │  2. wizard.middleware()       lib/wizard.js            │
+             │  3. errorBoundary(reporter)                             │
+             │       └─► handler kamu: use/cmd/hears/action/on/       │
+             │           inlineQuery/Menu/wizard      lib/composer.js │
+             └────────────────────────────┬───────────────────────────┘
+                                          │ ctx.reply / ctx.api.*
+                                          ▼
+             ApiBase + Proxy + pipeline transformer        lib/api.js
+             (api.config.use → autoRetry / throttler)
+                                          │
+                                          ▼
+             transport axios: JSON atau multipart attach:// lib/net.js
+                                          │
+                                          ▼
+                                 https://api.telegram.org
+```
 
-Showcase komunitas: [SHOWCASE.md](SHOWCASE.md)
+**Lifecycle satu update** (mis. `/start`): `getUpdates` → `pollLoop` →
+`handleUpdate` → `Context` baru → session dimuat → middleware wizard (tak ada
+wizard aktif → lanjut) → error boundary → handler kamu yang cocok jalan →
+`ctx.reply()` → pipeline transformer → axios → Telegram. Error yang dilempar
+jadi `BotError` dan mengalir ke `opts.onError` atau reporter manusiawi.
+
+<a id="dokumentasi"></a>
+## 📖 Dokumentasi Lengkap
+
+### 🏗️ Konstruktor & opsi
+
+```js
+const bot = new TeleBibz('TOKEN', {
+  allowedUpdates: [...],   // batasi tipe update (default: tipe umum + Business)
+  onError: (err, ctx) {},  // handle error sendiri (default: reporter manusiawi)
+  silent: false,           // tanpa banner boot
+  dropPending: false,      // buang update lama saat start
+  session: { ... },        // { initial, getKey, storage } — lihat bagian Session
+  transport: fn,           // suntik transport custom (test / proxy)
+});
+```
 
-![overview telebibz](https://cdn.jsdelivr.net/npm/@xbibzlibrary/telebibz@latest/assets/telebibz-readme-preview.png)
+<a id="handler"></a>
+### 🎛️ Handler & filter
+
+```js
+bot.cmd('ping',           (ctx) => ctx.reply('pong'));     // /ping
+bot.cmd(['a', 'b'],       handler);                        // /a ATAU /b
+bot.start('Selamat datang!');   // shortcut: daftarkan /start
+bot.hears('daftar',       handler);   // teks persis "daftar" (case-insensitive)
+bot.hears(/kuc?ing/i,     handler);   // regex bebas
+bot.on('message:photo',   handler);   // filter gaya grammY
+bot.on([':text', 'chat_type:private'], handler);
+bot.action('menu:premium', handler);  // callback_query data (string / RegExp)
+bot.inlineQuery(/kucing/i, handler);  // mode inline (regex / string / '*')
+bot.use(middleware);                  // middleware manual
+```
 
-## Instalasi
+Kombinator composer (semantik grammY):
 
-```bash
-npm install @xbibzlibrary/telebibz
+```js
+bot.branch(pred, kalauYa, kalauTidak);   // pilih subpohon berdasar predikat
+bot.filter(pred, ...mw);                 // jalan hanya jika pred(ctx) true
+bot.drop(pred, ...mw);                   // dilewati jika pred(ctx) true
+bot.route('chat.type', { private: mwA, group: mwB });  // petakan ctx → handler
+bot.lazy((ctx) => ctx.from.is_bot ? mwBot : mwUser);   // bangun mw per update
+bot.fork(mwLambat);                      // jalan di latar, tidak menahan next()
 ```
 
-Node.js **22 atau lebih baru** diperlukan.
+Filter yang didukung `on()`: field update (`message`, `edited_message`,
+`callback_query`, `inline_query`, `my_chat_member`, …), properti pesan
+(`message:photo`, `message:text`, `:caption`, `:document`, `:sticker`, `:media`, …),
+tipe chat (`chat_type:private/group/supergroup/channel`), plus
+`callback_query:data`, payment, reaksi, join request.
 
-## Bot sederhana
+Handler perintah menerima argumen di `ctx.match`:
 
-```ts
-import { Bot } from "@xbibzlibrary/telebibz";
+```js
+bot.cmd('echo', (ctx) => ctx.reply(`argumen: ${ctx.match}`)); // /echo halo → "halo"
+```
 
-const bot = new Bot(process.env.TELEGRAM_BOT_TOKEN!);
+<a id="context"></a>
+### 💬 Shortcut Context
 
-bot.command("start", async (ctx) => { await ctx.reply("Bot aktif."); });
-bot.onText("ping", async (ctx) => { await ctx.reply("pong"); });
+`ctx` membungkus semua jenis update (message, edited, channel, business,
+callback, inline…) dengan accessor seragam: `chat`, `from`, `chatId`, `msgId`,
+`msg`, `senderChat`, `inlineMessageId`, `businessConnectionId`.
 
-await bot.start();
+| Kategori | Shortcut |
+|---|---|
+| **Balasan** | `reply`, `replyWithHTML`, `replyWithMarkdown`, `replyWithPhoto/Video/Audio/Document/Animation/Voice/VideoNote/Sticker/MediaGroup/Location/Venue/Contact/Poll/Dice/Invoice/ChatAction` |
+| **Edit & hapus** | `editMessageText/Caption/Media/ReplyMarkup`, `deleteMessage`, `deleteMessages` — sadar callback & inline-message |
+| **Reaksi** | `react('👍')` |
+| **Teruskan/salin** | `forwardMessage(tujuan)`, `copyMessage(tujuan)` (default pesan saat ini) |
+| **Callback & inline** | `answerCallbackQuery` (string atau objek), `answerInlineQuery` |
+| **Admin** | `banChatMember`, `restrictChatMember`, `promoteChatMember`, `banAuthor`, `restrictAuthor`, `getChat*`, `getAuthor`, `leaveChat`, `setChatTitle/Description`, `pin/unpinChatMessage` |
+| **File** | `getFile()` (pintar: photo terbesar), `downloadFile(dest)` |
+
+Akun business: balasan dalam konteks business otomatis menyertakan
+`business_connection_id`.
+
+<a id="keyboard"></a>
+### 🔘 Keyboard & tombol
+
+```js
+const { btn, url, webApp, copy, kb, InlineKeyboard, Keyboard } = require('@xbibzlibrary/telebibz');
+
+bot.cmd('menu', (ctx) =>
+  ctx.reply('Pilih:', kb([
+    [btn('💎 Premium', 'prem', 'primary'),                // biru/ungu
+     btn('✅ Daftar', 'reg', 'success')],                 // hijau
+    [url('🌐 Web', 'https://situsmu.com')],
+    [btn('❌ Tutup', 'close', 'danger', '5408846744727334338')], // merah + IKON ANIMASI
+  ])));
 ```
 
-`Bot.start()` menjalankan long polling. Untuk siklus hidup manual, gunakan `init()`, `launch({ mode: "polling" })`, `health()`, `stop()`, atau `restart()`.
+- 🎨 Warna `style` (`primary`/`success`/`danger`) butuh aplikasi Telegram rilis ≥ Feb 2026 — versi lama tampil biasa, tidak error.
+- ✨ `icon_custom_emoji_id` butuh **owner bot ber-Premium** atau username Fragment.
+- Helper: `copy(text, nilai)` (salin ke clipboard), `webApp(text, link)`, `kb.confirm(yaData, tidakData)`, `kb.markup(rows)`.
+- Kelas fluent: `new InlineKeyboard().text(...).url(...).row().text(...).build()` dan `new Keyboard().text(...).requestContact(...).resized().build()` (reply keyboard asli).
 
-## Starter resmi
+<a id="menu"></a>
+### 🍽️ Menu interaktif
 
-Repository menyediakan starter yang bisa langsung dijalankan untuk bot minimal, registration wizard multi-langkah, dan webhook Node.js. Lihat [`examples/README.md`](examples/README.md), atau jalankan starter minimal setelah mengatur `TELEGRAM_BOT_TOKEN`:
+```js
+const { Menu, MenuContainer } = require('@xbibzlibrary/telebibz');
 
-```bash
-export TELEGRAM_BOT_TOKEN="<token-bot-kamu>"
-npx tsx examples/minimal.ts
+const mc = new MenuContainer();
+const utama = mc.create('utama'), lanjut = mc.create('lanjut');
+
+utama.text('🔔 Notif', async (ctx) => ctx.answerCallbackQuery('dinyalakan!'))
+     .row()
+     .url('🌐 Web', 'https://x.com')
+     .submenu('Lanjut ▶', 'lanjut');
+lanjut.back('◀️ Kembali', 'utama');
+
+bot.use(mc); // handler tombol terdaftar otomatis
+bot.cmd('cfg', (ctx) => ctx.reply('Menu:', { reply_markup: utama.render(ctx) }));
 ```
 
-Semua examples di-typecheck oleh CI melalui `npm run test:examples` dan tidak berisi credential asli.
+Submenu menukar keyboard di tempat lewat `editMessageReplyMarkup`; tombol usang
+dijawab alert ramah, bukan crash.
 
-## Router dan middleware
+<a id="wizard"></a>
+### 🧙 Wizard — form percakapan, nol boilerplate
 
-```ts
-bot.use(async (ctx, next) => {
-  const started = Date.now();
-  await next();
-  console.log(`processed in ${Date.now() - started}ms`);
+```js
+bot.wizard('daftar', {
+  steps: [
+    { key: 'nama', ask: 'Siapa namamu?' },
+    { key: 'umur', ask: 'Umur?', parse: Number,
+      validate: (n) => (n > 0 && n < 120 ? null : 'Angka saja ya:') },
+  ],
+  done: async (ans, ctx) => ctx.reply(`Oke ${ans.nama} (${ans.umur})!`),
 });
+// user tinggal /daftar → bot bertanya sampai selesai.
+// ketik "batal" / "cancel" kapan pun untuk berhenti. Sesi otomatis aktif.
+```
+
+`bot.wizard(id, def, bindCommand = true)` otomatis mengikat `/id` sebagai
+pemicu; pakai `bot.wizardStart(ctx, id)` dari handler mana pun (tombol, menu, …).
+
+#### 🆕 v3.1 — tombol pilihan + mode `edit`/`delete`
+
+```js
+bot.wizard('survey', {
+  mode: 'edit',        // 'send' (default) | 'edit' | 'delete'
+  steps: [
+    // reply keyboard — user ketuk, tak perlu mengetik
+    { key: 'jk', ask: 'Jenis kelamin?', buttons: ['👨 Laki-laki', '👩 Perempuan'], onlyButtons: true },
 
-bot.command("help", async (ctx) => { await ctx.reply("Bantuan tersedia."); });
-bot.onRegex(/^order:(\d+)$/, async (ctx) => { await ctx.reply("Order diterima."); });
-bot.callback("profile:*", async (ctx) => { await ctx.answerCallbackQuery("Dibuka."); });
-bot.action("menu:open", async (ctx) => { await ctx.answerCallbackQuery("Menu dibuka."); });
-bot.on("message:photo", async (ctx) => { await ctx.reply("Foto yang bagus."); });
-bot.on(["message:text", "callback_query:data"], async (ctx) => { await ctx.reply("Diterima."); });
-bot.hears("ping", async (ctx) => { await ctx.reply("pong"); });
-bot.catch(async (error, ctx) => { await ctx.reply("Terjadi kesalahan."); });
+    // inline keyboard (callback) — nilai boleh beda dari label
+    { key: 'pulau', ask: 'Domisili pulau?', inline: true, onlyButtons: true,
+      buttons: [[{ text: '🌋 Jawa', value: 'jawa' }, { text: '🌴 Sumatera', value: 'sumatera' }]] },
+
+    // ketikan bebas dengan validasi (mode bisa di-override per langkah)
+    { key: 'umur', ask: 'Umur?', parse: Number, mode: 'send',
+      validate: (n) => (n > 0 && n < 120 ? null : 'Angka saja ya:') },
+  ],
+  done: async (ans, ctx) => ctx.reply(`Tersimpan: ${JSON.stringify(ans)}`),
+});
 ```
 
-Router mendukung command, text, regex, pola callback, filter tipe update (`on`), predikat kustom, router bersarang, middleware per rute, dan prioritas rute. `bot.catch()` mendaftarkan error boundary: kegagalan handler diarahkan ke sana alih-alih menolak update.
+| Opsi | Level | Fungsi |
+|---|:---:|---|
+| `buttons` | step | `['A','B']`, `[{text,value}]`, atau baris eksplisit `[['A'],['B','C']]` |
+| `inline` | step | `true` → tombol callback (klik = nilai, tanpa mengetik) |
+| `onlyButtons` | step | `true`/string → tolak ketikan bebas, wajib pilih tombol |
+| `mode` | def/step | `'send'` pesan baru · `'edit'` satu pesan diedit terus · `'delete'` pesan lama dihapus dulu |
+| `cleanup` | def | hapus pesan tanya terakhir saat selesai (default aktif pada mode `'delete'`) |
+| `removeKeyboard` | def | singkirkan reply keyboard saat selesai (default `true` bila sempat dipakai) |
+
+Helper programatis: `bot.wizardCancel(ctx)`, `bot.wizardEdit(ctx, teks)`,
+`bot.wizardDelete(ctx)`, plus modul `wizard` (`cancel/editAsk/deleteAsk`).
+Tombol usang (diklik setelah wizard pindah/selesai) dijawab alert aman — bot
+tidak pernah crash. `parse`/`validate` juga berlaku untuk nilai tombol.
+
+<a id="inline"></a>
+### ❓ Mode inline
+
+```js
+const { iq } = require('@xbibzlibrary/telebibz');
+
+bot.inlineQuery(/kucing/i, async (ctx) => {
+  await ctx.answerInlineQuery([
+    iq.article('1', 'Fakta kucing', { message_text: 'meong!' }),
+    iq.photo('2', 'https://x/1.jpg'),
+  ], { cache_time: 0 });
+});
+```
+
+Builder hasil: `iq.article/photo/gif/video/audio/location/sticker`.
 
-## Telegram API
+<a id="broadcast"></a>
+### 📣 Broadcast (aman rate-limit)
 
-Generated method access dan raw access tersedia melalui API client:
+```js
+const hasil = await bot.broadcast([111, 222, 333], 'Pengumuman!', { delay: 35 });
+// → { terkirim: 3, gagal: 0, errors: [] }  (yang memblokir tercatat di errors)
+```
 
-```ts
-await bot.api.methods.getMe();
-await bot.api.methods.sendMessage({ chat_id: 123456789, text: "Halo." });
-await bot.api.call("sendMessage", { chat_id: 123456789, text: "Halo." });
-await bot.api.raw("futureTelegramMethod", { value: true });
+`pesan` boleh string, objek payload `sendMessage`, atau fungsi
+`(chatId) => payload` untuk personalisasi per penerima. Pacing default 35 ms
+(≈28 pesan/detik, aman di bawah limit Telegram).
+
+<a id="file"></a>
+### 📎 File & media
+
+```js
+const { InputFile, InputMediaBuilder } = require('@xbibzlibrary/telebibz');
+
+bot.cmd('foto', (ctx) => ctx.replyWithPhoto(new InputFile(buffer, 'x.jpg')));
+bot.cmd('dok',  (ctx) => ctx.replyWithDocument(new InputFile('/path/file.pdf')));
+bot.cmd('album', (ctx) => ctx.replyWithMediaGroup([
+  InputMediaBuilder.photo('https://a/1.jpg'),
+  InputMediaBuilder.photo('https://a/2.jpg', { caption: 'dua' }),
+]));
+bot.on('message:photo', async (ctx) => {
+  const f = await ctx.getFile();          // ukuran photo terbesar, otomatis
+  await ctx.downloadFile('./foto.jpg');   // streaming ke disk
+});
 ```
 
-Transport bawaan menggunakan `fetch`, timeout, retry, exponential backoff, JSON payload, dan multipart upload.
+`InputFile` menerima Buffer / Uint8Array / path file / stream fs / async
+iterable; upload dikirim sebagai `multipart` dengan `attach://` di mana pun
+dalam payload (media group, thumbnail, …). `api.downloadFile(file_id, dest)`
+juga bisa berdiri sendiri.
+
+<a id="ratelimit"></a>
+### 🛡️ Keandalan & rate limit
+
+```js
+const { autoRetry, throttler, limiter } = require('@xbibzlibrary/telebibz');
+
+bot.api.config.use(autoRetry());            // retry 429, hormati retry_after (maks 5)
+bot.api.config.use(throttler());            // antrean global ≤ 28 panggilan/detik
+bot.use(limiter({ windowMs: 2000, limit: 3, onExceeded })); // anti-spam per-user
+```
 
-Referensi API lengkap untuk setiap class, function, method, type, error, lifecycle, CLI command, dan generated Telegram method tersedia di [`docs/API.id.md`](docs/API.id.md).
+Long polling tahan banting secara default: konflik 409 retry tiap 5 detik
+(atur via `launch({ conflictDelay: 5000 })`), gangguan jaringan backoff 1
+detik, `stop()` keluar dengan bersih (`await bot.runPromise`).
 
-## Keyboard
+<a id="session"></a>
+### 🗃️ Session
 
-```ts
-import { InlineKeyboard } from "@xbibzlibrary/telebibz";
+```js
+const { session } = require('@xbibzlibrary/telebibz');
 
-const keyboard = new InlineKeyboard()
-  .text("Profil", "profile")
-  .url("Dokumentasi", "https://core.telegram.org/bots/api")
-  .build();
+const bot = new TeleBibz(token, {
+  session: {
+    initial: () => ({ hitung: 0 }),
+    getKey: (ctx) => `${ctx.from?.id}:${ctx.chat?.id}`,  // default
+    storage: adapterRedisKu,  // { read(k), write(k,v), delete(k) } — default: Map memori
+  },
+});
 
-await ctx.reply("Pilih menu:", { reply_markup: keyboard });
+bot.on(':text', (ctx) => { ctx.session.hitung++; });
 ```
 
-Builder hanya menghasilkan payload keyboard native Telegram. UI HTML/CSS memerlukan Mini App atau Web App terpisah.
+`ctx.session` selalu ada bahkan tanpa konfigurasi apa pun.
 
-## Startup dan log terminal
+<a id="error"></a>
+### 🇮🇩 Error yang bisa dibaca manusia
 
-Logger mengeluarkan baris terminal yang ringkas dan mudah dibaca dengan level berwarna serta konteks terstruktur. Level log: `silent`, `error`, `warn`, `info`, `debug`, dan `trace`; nilai sensitif di-redact; error dicetak merah lengkap dengan stack. Gunakan `format: "json"` untuk log terstruktur, dan `includeUpdateContent: true` hanya bila teks pesan atau data callback memang diperlukan.
+Setiap error dilaporkan dengan saran yang bisa ditindaklanjuti:
 
-## Wizard dan conversation multi-langkah
+```
+✖ Telegram error (403): Forbidden: bot was blocked by the user
+  💡 saran: Bot diblokir pengguna — jangan kirim ulang, hapus dari daftar broadcast.
+```
 
-Gunakan `Wizard` bersama `bot.useWizard()` sehingga setiap balasan teks berikutnya dari chat/user yang sama otomatis diarahkan ke langkah yang sedang aktif. Key dihasilkan dari chat dan pengirim Telegram; tidak perlu key manual.
+`humanize(err)` mengembalikan `{ pesan, saran, method, code }` untuk 15+ error
+Telegram umum (token salah, chat not found, hak admin, parse error, rate
+limit, callback basi, file kegedean, …). Override lewat
+`new TeleBibz(token, { onError: (err, ctx) => {} })`.
 
-```ts
-import { Bot, Wizard } from "@xbibzlibrary/telebibz";
+<a id="webhook"></a>
+### 🕸️ Webhook & serverless
 
-const wizard = new Wizard()
-  .step({ id: "prompt-name", run: async (flow) => { flow.next(); await flow.ctx.reply("Siapa nama kamu?"); } })
-  .step({ id: "name", run: async (flow) => { flow.set("name", flow.ctx.message?.text?.trim()); flow.next(); await flow.ctx.reply("Berapa umur kamu?"); } })
-  .step({ id: "age", run: (flow) => { const age = Number(flow.ctx.message?.text?.trim()); if (!Number.isInteger(age)) return; flow.set("age", age); flow.next(); } });
+```js
+const http = require('http');
+http.createServer((req, res) =>
+  req.url === '/tg' ? bot.webhook()(req, res) : res.end('ok')
+).listen(8443);
 
-const bot = new Bot(process.env.TELEGRAM_BOT_TOKEN!);
-bot.useWizard(wizard);
-bot.command("start", async (ctx) => { await wizard.run(ctx); });
-await bot.start();
+// framework apa pun (Express/Fastify/Hono): pasang handler (req, res) dari bot.webhook()
+// — atau serverless, langsung:
+await bot.handleUpdate(req.body);   // satu update mentah → pipeline penuh
 ```
 
-`Wizard` mempertahankan `ConversationManager` defaultnya antar update dan menandai conversation selesai tepat setelah langkah terakhir. Gunakan `/cancel` untuk membatalkan wizard yang sedang berjalan.
+Jangan lupa `await bot.init()` dulu kalau tidak memakai `launch()` (untuk
+mengambil info bot), dan pasang webhook via `bot.api.setWebhook({ url })`.
+
+<a id="proxy"></a>
+### 🔌 Transport proxy (VPS di balik proxy)
+
+```js
+const { TeleBibz, createTransport } = require('@xbibzlibrary/telebibz');
+const bot = new TeleBibz(token, {
+  transport: createTransport(token, { proxy: 'http://user:pass@proxy:8080' }),
+});
+```
 
-## Webhook
+`createTransport(token, { apiRoot, proxy, timeoutMs, headers })` juga bisa
+diarahkan ke Bot API server lokal.
 
-```ts
-import { Bot, createWebhookHandler } from "@xbibzlibrary/telebibz";
+<a id="transformer"></a>
+### 🧪 Transformer (escape hatch)
 
-const bot = new Bot(process.env.TELEGRAM_BOT_TOKEN!);
-const handler = createWebhookHandler(bot, {
-  secretToken: process.env.TELEGRAM_WEBHOOK_SECRET,
+```js
+bot.api.config.use(async (prev, method, payload) => {
+  console.log('→', method);          // lihat/modifikasi semua panggilan Bot API
+  return prev(method, payload);
 });
+
+// metode apa pun, bahkan yang belum rilis (sihir Proxy):
+await bot.api.sendDiceCustom({ chat_id: 1, emoji: '🎲' });
 ```
 
-`createWebhookHandler` menerima Request Web standar dan menghasilkan Response. Secret token, ukuran body, parsing JSON, dan penanganan update duplikat diverifikasi oleh handler.
+<a id="analitik"></a>
+## 📈 Analitik & Statistik
 
-## Update beban tinggi dan broadcast
+### 📊 Repo ini dalam angka
 
-telebibz dibangun untuk burst 1000+ pesan tanpa cooldown buatan:
+| Metrik | Nilai |
+|---|---|
+| 📦 Modul sumber | **16 file** di `lib/` |
+| 📝 Total baris kode | **±1.700** (tanpa build step) |
+| 🔌 Metode Bot API | **90+** — 75 shortcut bertipe + Proxy tanpa batas |
+| ⌨️ Shortcut Context | **50+** (reply/edit/delete/admin/react…) |
+| 🧪 Test offline | **30/30 lulus**, tanpa jaringan |
+| 🧩 Contoh siap jalan | **7** di `examples/` |
+| 📦 Dependency runtime | **4** — semuanya terpakai & ter-test |
 
-- **Paralel antar chat, berurutan per chat.** Setiap batch `getUpdates` (dan setiap request webhook) diproses secara konkuren — update dari chat berbeda tidak pernah saling mengantre, sementara update dari chat yang sama menjaga urutan kedatangannya sehingga session, wizard, dan conversation tetap benar dan penulisan session tidak pernah hilang. Burst konkuren hanya memicu satu inisialisasi `getMe`. Jika Anda mengelola loop polling sendiri, umpankan batch yang sudah diambil lewat `bot.handleUpdates()`.
-- **Tidak ada throttling proaktif.** Permintaan keluar tidak pernah ditunda oleh library. Ketika Telegram menjawab 429, transport menunggu tepat jendela `retry_after` yang diperintahkan Telegram ("flood gate" global melindungi seluruh trafik) lalu otomatis retry — sehingga burst tetap terkirim lengkap, bukan gagal. Untuk batasan downstream Anda sendiri, `Limiter` dan `mapWithConcurrency()` mengatur laju beban kerja apa pun.
-- **Broadcast ke 1000+ user sekaligus.** `bot.broadcast()` langsung mencoba semua chat, me-retry 429 sesuai `retry_after` dari Telegram sendiri, dan mengembalikan laporan lengkap.
-- **Shutdown yang anggun.** `bot.stop()` lebih dulu menunggu handler yang sedang berjalan selesai (dibatasi `handlerTimeout`) dan baru kemudian menghentikan plugin manager — conversation yang aktif tidak pernah terpotong di tengah penulisan.
+### ⬇️ Download & popularitas (live dari npm)
 
-```ts
-const report = await bot.broadcast(
-  subscriberIds,
-  (chatId) => bot.api.methods.sendMessage({ chat_id: chatId, text: "Newsletter #42" }),
-  { onProgress: (p) => console.log(`${p.delivered}/${p.total} terkirim`) },
-);
-console.log(`Terkirim ${report.delivered}/${report.total} dalam ${report.durationMs}ms`);
-```
+[![per hari](https://img.shields.io/npm/dd/@xbibzlibrary/telebibz?style=flat-square&label=hari&color=informational)](https://www.npmjs.com/package/@xbibzlibrary/telebibz)
+[![per minggu](https://img.shields.io/npm/dw/@xbibzlibrary/telebibz?style=flat-square&label=minggu&color=informational)](https://www.npmjs.com/package/@xbibzlibrary/telebibz)
+[![per bulan](https://img.shields.io/npm/dm/@xbibzlibrary/telebibz?style=flat-square&label=bulan&color=informational)](https://www.npmjs.com/package/@xbibzlibrary/telebibz)
+[![total](https://img.shields.io/npm/dt/@xbibzlibrary/telebibz?style=flat-square&label=total&color=informational)](https://www.npmjs.com/package/@xbibzlibrary/telebibz)
 
-Batasi pekerjaan simultan dengan `new Bot({ ..., updates: { concurrency: 64 } })` atau `broadcast(..., { concurrency: 64 })` jika downstream Anda (database, API) membutuhkannya — secara default keduanya berjalan sepenuhnya paralel.
+### 📏 Peta ukuran modul (baris kode)
 
-## Paritas penuh Telegraf di permukaan context
+```
+wizard.js      █████████████████████████ 247  ← form + tombol + edit/delete
+telebibz.js    ███████████████████▎      193  ← kelas utama & siklus hidup
+context.js     ███████████████████       190  ← ctx + 50-an shortcut
+composer.js    █████████████████▍        174  ← mesin middleware & filter
+api.js         ███████████████▍          154  ← 75 shortcut + Proxy + transformer
+net.js         ███████████▌              115  ← transport axios + multipart
+menus.js       █████████                  90  ← Menu/MenuContainer
+keyboard.js    ████████▎                  83  ← btn/url/kb + kelas fluent
+ratelimit.js   ██████                     61  ← autoRetry · throttler · limiter
+runner.js      ████▌                      45  ← polling tahan-409
+file.js        ████                       41  ← InputFile + InputMediaBuilder
+logger.js      ███▊                       38  ← log + banner
+session.js     ███▌                       36  ← session swappable
+errors.js      ███▌                       35  ← humanize error 🇮
+broadcast.js   ███▌                       35  ← blast aman rate-limit
+inline-query.js██▊                        28  ← matcher + builder hasil
+```
 
-Semua shortcut context Telegraf tersedia, ditambah tambahan yang menutupi apa yang oleh inti Telegraf diserahkan ke ekosistem plugin-nya:
+### 🗺️ Kesehatan repo
 
-- **Moderasi & admin** — `ctx.banChatMember`, `ctx.unbanChatMember`, `ctx.restrictChatMember`, `ctx.promoteChatMember`, `ctx.banChatSenderChat`, `ctx.unbanChatSenderChat`
-- **Manajemen chat** — `ctx.setChatTitle/Description/Photo`, `ctx.setChatPermissions`, `ctx.leaveChat`, `ctx.unpinAllChatMessages`, `ctx.setChatStickerSet`, `ctx.deleteChatStickerSet`
-- **Info** — `ctx.getChatAdministrators`, `ctx.getChatMemberCount`, `ctx.getChatMember`
-- **Invite link & join request** — `ctx.exportChatInviteLink`, `ctx.createChatInviteLink`, `ctx.editChatInviteLink`, `ctx.revokeChatInviteLink`, `ctx.approveChatJoinRequest`, `ctx.declineChatJoinRequest`
-- **Poll, game, pembayaran** — `ctx.replyWithQuiz`, `ctx.stopPoll`, `ctx.editMessageLiveLocation`, `ctx.stopMessageLiveLocation`, `ctx.replyWithGame`, `ctx.setGameScore`, `ctx.getGameHighScores`, `ctx.replyWithInvoice`
-- **Forum topic** — `ctx.createForumTopic`, `ctx.closeForumTopic`, `ctx.editGeneralForumTopic`, dan sembilan lainnya
-- **Opsi launch** — `handlerTimeout` (default 90 detik, seperti Telegraf) melempar `UpdateTimeoutError` untuk update yang menggantung sementara handler tetap berjalan; `0` menonaktifkan timeout; `contextType` memasang subclass `Context` Anda sendiri; `dropPendingUpdates` di `start()`/`launch()`
-- **Webhook reply** — opt-in `webhookReply: true` menjawab panggilan API pertama lewat respons HTTP webhook itu sendiri (ala Telegraf), dengan `getMe` malas yang tidak pernah mengklaim slot
-- **Alias handler drop-in** — `bot.action(...)` mendaftarkan handler callback query sama seperti `bot.callback(...)`, sehingga handler yang ditulis untuk Telegraf bisa dipindahkan tanpa perubahan
+<div align="center">
 
-## State, queue, scheduler, dan cache
+[![kartu repo](https://github-readme-stats.vercel.app/api/pin/?username=XbibzOfficial777&repo=telebibz&show_owner=false)](https://github.com/XbibzOfficial777/telebibz)
 
-Paket menyediakan `MemoryStorage` dengan TTL dan pembaruan atomik, `JsonFileStorage`, `RedisStorage`, `SqlStorage`, `MongoStorage`, persistent application state storage, session bot, conversation dan form berbasis Storage, menu berbasis permission, pagination `MenuController`, `MemoryCache`, token-bucket limiter, task queue dengan retry/backoff/concurrency/delay/cancel, serta scheduler interval, one-shot, dan cron lima field lengkap. Adapter Redis, SQL, dan Mongo memakai driver kecil sehingga core package tetap tanpa runtime dependency vendor.
+</div>
 
-## Pengalaman terminal
+<details>
+<summary>📅 Riwayat bintang (klik untuk buka)</summary>
 
-Saat bot dinyalakan di terminal interaktif (`npm start`, `node index.js`, `telebibz start`), telebibz memainkan urutan startup: efek ketik `Installing Dependencies......`, glass progress bar dengan kilau menyapu, dan banner ASCII rainbow animasi **Tele Bibz** (font figlet `Speed`) yang terus mengalir sampai bot terhubung, lalu diam dengan `✓ Connected as @<username>`.
+![Star History](https://api.star-history.com/svg?repos=XbibzOfficial777/telebibz&type=Date)
 
-Setelah itu, setiap update yang masuk ditampilkan dalam baris log yang mudah dibaca, dan error otomatis berwarna merah lengkap dengan stack-nya:
+</details>
 
-```text
-[ => ] Message From 123456789 John Doe 29/08/2026 15:04:05
-        ↳ Text: /start
-[ => ] Callback From 123456789 John Doe 29/08/2026 15:04:07
-        ↳ Data: menu:open
-```
+<a id="contoh"></a>
+## 🧩 Contoh Siap Jalan (`examples/`)
 
-Teks pesan/command biasa dibatasi 50 karakter; data tombol callback ditampilkan penuh. Matikan dengan `branding: false` pada `Bot`, atau pakai `logger.format: "json"` untuk log terstruktur. Output non-interaktif (pipe, Docker, CI) otomatis fallback ke teks polos tanpa animasi.
+| File | Isi |
+|---|---|
+| `01-quickstart.js` | bot jalan dalam 6 baris |
+| `02-menu-tombol.js` | keyboard berwarna + ikon animasi |
+| `03-wizard.js` | form pendaftaran + **tombol + mode edit** |
+| `04-broadcast.js` | blast admin |
+| `05-kirim-file.js` | foto & dokumen dari buffer |
+| `06-menu.js` | menu interaktif + submenu |
+| `07-inline-query.js` | mode inline dengan builder hasil |
 
-## CLI
+Jalankan dengan `BOT_TOKEN=123:abc node examples/01-quickstart.js`.
 
-Command CLI seperti `telebibz doctor`, `init`, dan `webhook` diawali banner rainbow `Tele Bibz`. Animasi startup otomatis fallback ke output statis bersih saat stdout bukan TTY.
+<a id="test"></a>
+## 🔬 Test & Bukti Live
 
 ```bash
-npx telebibz init my-bot
-npx telebibz doctor
-npx telebibz build
-npx telebibz test
+npm test   # 30 kasus, TANPA jaringan (transport disuntik)
 ```
 
-Branding terminal juga dapat dicetak dari aplikasi:
+Tervalidasi **30/30 offline + 10 live** pada bot produksi `@xbibzrat_bot`:
+getMe · keyboard berwarna & ikon animasi asli · upload multipart
+(photo+document) · edit keyboard · broadcast · deleteMessage · polling 409
+retry · wizard tombol & edit/delete.
 
-```ts
-import { printTeleBibzBanner, printTerminalBranding } from "@xbibzlibrary/telebibz";
+Log debug: `DEBUG=telebibz:net,telebibz:ratelimit node botkamu.js`.
 
-printTeleBibzBanner({ subtitle: "Bot saya" });
-printTerminalBranding();
-```
+<a id="struktur"></a>
+## 📂 Struktur Repo (16 file inti)
 
-## Testing
+| File | Peran |
+|---|---|
+| `lib/net.js` | transport axios keep-alive + multipart `attach://` |
+| `lib/api.js` | metode Bot API + Proxy segala metode + transformer |
+| `lib/composer.js` | middleware, filter `on('message:photo')`, `errorBoundary` |
+| `lib/context.js` | objek ctx + 50-an pintasan reply/edit/delete/callback |
+| `lib/session.js` | sesi per user:chat (storage swappable) |
+| `lib/runner.js` | long polling: retry 409, backoff jaringan, drop pending |
+| `lib/wizard.js` | form percakapan + tombol pilihan + mode edit/delete |
+| `lib/menus.js` | menu interaktif `Menu`/`MenuContainer` |
+| `lib/keyboard.js` | builder tombol + kelas fluent `InlineKeyboard`/`Keyboard` |
+| `lib/ratelimit.js` | `autoRetry` 429 · antre `throttler` · `limiter` per-user |
+| `lib/broadcast.js` | blast aman rate-limit |
+| `lib/file.js` | `File`/`InputFile` (Buffer/path/stream) + `InputMediaBuilder` |
+| `lib/inline-query.js` | matcher query + builder hasil inline |
+| `lib/errors.js` | humanisasi error + saran |
+| `lib/logger.js` | log berbingkai + banner boot |
+| `index.js` / `index.d.ts` | pintu ekspor + tipe TypeScript |
 
-```bash
-npm run typecheck
-npm run test:types
-npm run lint
-npm test
-npm run build
-npm run security
-npm run release:check
-```
+<a id="changelog"></a>
+## 🕐 Changelog
 
-E2E Telegram nyata memerlukan `TELEGRAM_BOT_TOKEN` dan `TELEGRAM_TEST_CHAT_ID`. Tanpa kredensial, E2E akan dilewati dan tidak dihitung sebagai lulus.
+- **3.1.0** — wizard: tombol pilihan (reply/inline), mode `edit`/`delete`, cleanup otomatis, helper programatis · test 24 → 30
+- **3.0.0** — parity grammY production-grade: axios keep-alive, transformer, menu, inline query, limiter
+- **2.0.0** — engine ditulis ulang dari nol, transport multipart, webhook Node murni
+- **1.0.0** — recode arsitektur grammY
 
-## Web App dan pembayaran
+> Detail lengkap di [`CHANGELOG.md`](CHANGELOG.md). Studi arsitektur mendalam: [`ANALISIS-telebibz.md`](ANALISIS-telebibz.md).
 
-`validateWebAppInitData()` memverifikasi signature dan expiration Telegram Web App. `PaymentsClient` menyediakan wrapper invoice link, invoice, jawaban pre-checkout, jawaban Web App query, transaksi Stars, dan refund Stars. Gunakan `TelegramTypes` serta alias seperti `TelegramUser`, `TelegramMessage`, dan `TelegramUpdate` untuk full Telegram declaration surface yang divendor.
+<a id="lisensi"></a>
+## 📄 Lisensi
 
-## Permukaan API
+**MIT** © Xbibz Official — arsitektur terinspirasi [grammY](https://grammy.dev) (MIT, lihat [`NOTICE.md`](NOTICE.md)).
 
-Semua yang tercantum di bawah diekspor dari entry point package kecuali disebutkan subpath-nya. Signature lengkap setiap export terdokumentasi di [docs/API.id.md](docs/API.id.md) (juga [docs/API.md](docs/API.md) dan [docs/API.zh-CN.md](docs/API.zh-CN.md)).
+---
 
-| Area | Export |
-|---|---|
-| Bot & lifecycle | `Bot` dengan `on`, `onText`, `onRegex`, `command`, `hears`, `callback`, `action`, `catch`, `use`, `usePlugin`, `useWizard`, `handleUpdate`, `handleUpdates`, `start`/`launch`, `stop`, `restart`, `init`, `health`, `broadcast`, `getMe`, `setCommands`, `deleteCommands`, `downloadFile`; `UpdateTimeoutError` |
-| Context | `Context`, `ContextOptions`, opsi launch `contextType`; ~80 shortcut di `ctx` untuk balasan, aksi admin, manajemen chat, invite link, poll, game, pembayaran, dan forum topic |
-| Telegram API | `ApiClient` dengan `call()`, `request()`, `raw()`, `downloadFile()`, dan `methods` (seluruh generated Bot API method); `FetchTransport` dengan retry 429/5xx otomatis, flood gate global, upload multipart (Blob/byte/path/stream), dan unduhan file |
-| Error | `TelegramError` dengan taksonomi `kind` (`retryable`, `rate-limit`, `authentication`, `validation`, `network`, `server`, `unknown`) dan `retryAfter`, plus `TelegramRateLimitError`, `TelegramAuthError`, `TelegramValidationError`, `TelegramNetworkError` |
-| Router & middleware | `Router`, `compose`, 24 filter update (`message:photo`, `callback_query:data`, …), `matchMode` (`first`/`all`) |
-| Keyboard | `InlineKeyboard`, `ReplyKeyboard`, `removeKeyboard()`, `forceReply()` |
-| Storage | `MemoryStorage` (TTL, serialisasi per-key), `JsonFileStorage`, `RedisStorage`, `SqlStorage`, `MongoStorage`, beserta driver interface kecil yang menjadi dasarnya |
-| Cache & limiting | `MemoryCache`, `TokenBucketLimiter`, `Limiter`, `mapWithConcurrency()` |
-| Queue & scheduler | `TaskQueue` (prioritas, retry, backoff, delay, cancel), `Scheduler` (interval, one-shot, cron), `parseCronExpression()`, `nextCronOccurrence()` |
-| State & dialog | `Wizard`, `ConversationManager`, `ConversationFlow`, `Form` dengan `validators`, `Menu` berbasis permission, `MenuController`, `paginate()` |
-| Webhook | `createWebhookHandler()` (Request/Response Web), `webhookCallback()` untuk Express/Koa/Fastify/Node `http`, `runWithWebhookReply()`, `claimWebhookReply()` |
-| Web App & pembayaran | `parseWebAppInitData()`, `validateWebAppInitData()`, `PaymentsClient`, `TelegramTypes` (deklarasi Telegram yang dibundel) |
-| Observability | `Logger` (level, redaction, format JSON), `EventBus` dengan event map `update:*`, `bot:*`, `broadcast:*`, `redact()` |
-| Terminal | `printTeleBibzBanner()`, `printTerminalBranding()`, `buildTerminalBranding()`, `runStartupSequence()`, `startTeleBibzBanner()`, `paintRainbow()`, `printStatusLine()` |
-| Utilitas teks | `splitMessage()`, `splitCaption()`, `escapeMarkdownV2()`, `escapeHtml()`, `md`, `html`, `template()` |
-| Utilitas file | `validateUpload()`, `assertValidUpload()`, `UploadValidationError` (aturan ukuran, MIME, ekstensi) |
-| Testing (`@xbibzlibrary/telebibz/testing`) | `MockTransport` (dengan unduhan mock), `createTestBot()`, `createMockUpdate()`, `createMockCallbackUpdate()`, `createMockContext()` |
-| CLI (`telebibz …`) | `init`, `doctor`, `build`, `test`, `start`, `webhook`, `generate` |
-
-## API target dan batasan
-
-Daftar method dihasilkan dari dokumentasi Telegram Bot API saat skema diperbarui. Akses runtime tersedia untuk method resmi yang terdeteksi, sedangkan inferensi parameter/result khusus dipusatkan pada core method map. Full declaration Telegram untuk object, union, enum, dan method tersedia melalui `TelegramTypes`. Lihat [FEATURE_MATRIX.md](FEATURE_MATRIX.md) untuk status implementasi dan `docs/API.id.md` untuk referensi API lengkap.
-
-## Otomatisasi release
-
-Repository GitHub menyediakan CI dan workflow auto-publish. Setiap push ke `main` menjalankan quality gates lalu menurunkan versi berikutnya dari Conventional Commits yang didorong: commit `feat:` dan breaking change menaikkan minor selama package belum 1.0 (footer `BREAKING-CHANGE` atau subjek `type!:` menaikkan major mulai 1.0.0), sisanya menaikkan patch. Versi yang sudah dideklarasikan di `package.json` lebih tinggi dari npm diterbitkan persis apa adanya, dan workflow tidak pernah menerbitkan versi yang kurang dari atau sama dengan rilis npm terbaru. Workflow membuat commit versi, tag, menerbitkan ke npm (dengan provenance dinonaktifkan lewat `--provenance=false`), lalu membuat GitHub Release. Commit yang memuat `[skip release]` tidak memicu penerbitan. Konfigurasikan secret `NPM_TOKEN` pada GitHub Actions sebelum mengandalkan publish otomatis. Lihat [RELEASE_AUTOMATION.md](RELEASE_AUTOMATION.md) dan panduan [GitHub Packages](docs/GITHUB_PACKAGES.id.md).
-
-## Policy project dan kontribusi
-
-| Dokumen | Tujuan |
-|---|---|
-| [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) | Perilaku komunitas, penegakan, pelaporan, dan banding. |
-| [CONTRIBUTING.md](CONTRIBUTING.md) | Setup lokal, branch/commit, test, review, dan release workflow. |
-| [CONTRIBUTION_RULES.md](CONTRIBUTION_RULES.md) | Aturan API, compatibility, testing, dependency, security, dan release. |
-| [GOVERNANCE.md](GOVERNANCE.md) | Peran, pengambilan keputusan, triage, perlindungan repository, dan perubahan aturan. |
-| [SECURITY.md](SECURITY.md) | Pelaporan vulnerability privat, batas security, dan rotasi credential. |
-| [SUPPORT.md](SUPPORT.md) | Channel support, aturan laporan aman, dan ekspektasi response. |
-| [RELEASE_AUTOMATION.md](RELEASE_AUTOMATION.md) | Automation GitHub-to-npm dan setup `NPM_TOKEN`. |
-| [RELEASE_POLICY.md](RELEASE_POLICY.md) | Kontrol immutable release dan hardening. |
-| [NOTICE.md](NOTICE.md) | Atribusi declaration pihak ketiga. |
+<div align="center">
 
-## Keamanan
+**Dibuat dengan ❤️ oleh //—Xbibz Official—//**
 
-Jangan commit token Telegram atau npm. Gunakan variabel lingkungan atau secret manager. Untuk kebijakan keamanan dan peningkatan keamanan rilis, lihat [SECURITY.md](SECURITY.md) dan [RELEASE_POLICY.md](RELEASE_POLICY.md).
+Kalau telebibz membantumu, bintang ⭐ repo ini sangat berarti.
 
-## Lisensi
+[![kunjungan repo](https://komarev.com/ghpvc/?username=XbibzOfficial777&repo=telebibz&style=flat-square&color=blueviolet&label=kunjungan+repo)](https://github.com/XbibzOfficial777/telebibz)
 
-MIT. Lihat [LICENSE](LICENSE).
+</div>