@xbibzlibrary/telebibz 0.4.5 → 3.1.1

package/README.md

@@ -1,315 +1,641 @@
-# telebibz
+<div align="center">
+
+[🇬🇧 **English**](README.md) · [🇮 **Indonesia**](README.id.md)
+
+<br>
+
+<a href="https://www.npmjs.com/package/@xbibzlibrary/telebibz" title="Open telebibz on npm">
+  <img src="https://imgbs.com/uploads/telebibz-d7b30671.png" alt="telebibz — Telegram Bot Library" width="560">
+</a>
+
+<br><br>
+
+**The easiest Telegram bot library for Node.js — full feature set on par with grammY.**<br>
+A standalone recode of [grammY](https://grammy.dev)'s elegant architecture, with production
+dependencies that are *actually used*, and an Indonesia-first community.
+
+<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=downloads%2Fmonth)](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/tests-30%2F30%20passing-brightgreen?style=for-the-badge&logo=checkmarx&logoColor=white)](#-testing--live-proof)
+[![size](https://img.shields.io/badge/code-1.7k%20lines-orange?style=for-the-badge&logo=codeigniter&logoColor=white)](#-analytics--statistics)
+[![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=repo+views)](https://github.com/XbibzOfficial777/telebibz)
+
+<br>
+
+`//—Xbibz Official—//`
+
+</div>
+
+---
+
+## 📑 Table of Contents
+
+| | | |
+|---|---|---|
+| ⚡ [Why telebibz?](#why) | 📊 [Feature matrix vs grammY](#matrix) | 📥 [Installation & requirements](#install) |
+| 🚀 [Quick start](#quickstart) | 🧠 [How it works (architecture)](#architecture) | 📖 [Full documentation](#docs) |
+| 🎛️ [Handlers & filters](#handlers) | 💬 [Context shortcuts](#context) | 🔘 [Keyboards & buttons](#keyboards) |
+| ️ [Interactive menus](#menus) | 🧙 [Wizard (forms + buttons + edit/delete)](#wizard) | ❓ [Inline mode](#inline) |
+| 📣 [Broadcast](#broadcast) | 📎 [Files & media](#files) | 🛡️ [Reliability & rate limiting](#ratelimit) |
+| 🗃️ [Sessions](#sessions) | 🇮🇩 [Human-readable errors](#errors) | 🕸️ [Webhooks & serverless](#webhook) |
+| 🔌 [Proxy transport](#proxy) | 🧪 [Transformers](#transformers) | 📈 [Analytics & statistics](#analytics) |
+| 🧩 [Examples](#examples) | 🔬 [Testing](#testing) | 📂 [Repo structure](#structure) |
+| 🕐 [Changelog](#changelog) | 📄 [License](#license) | |
+
+<a id="why"></a>
+## ⚡ Why telebibz?
+
+> [!TIP]
+> **One principle:** every feature that needs a plugin in grammY is **built in** here —
+> wizard, menus, rate limiting, broadcast, file download — and polling that *never dies* on 409.
+
+- 🧠 **The grammY API you already know** — `bot.cmd()`, `bot.hears()`, `ctx.reply()`, middleware, transformers
+- 🧙 **Built-in Wizard v3.1** — question-and-answer forms with **choice buttons** (reply/inline) and **edit/delete** message modes
+- 🛡️ **Bulletproof** — 429 auto-retry, throttler, per-user limiter, polling auto-retry on 409 conflict
+- 🇮🇩 **Human-readable errors** — every Telegram error is translated into a plain-language suggestion
+- 🔌 **Proxy API for any method** — `api.anyMethod({...})` works automatically, even for methods not released yet
+- 🪶 **Light & honest** — 4 dependencies, all genuinely used and tested
+
+<a id="matrix"></a>
+## 📊 Feature Matrix — grammY parity
+
+| Feature | grammY | telebibz |
+|---|:---:|:---:|
+| Proxy API for **any method** (auto-generated) | ✅ | ✅ |
+| ~60 typed shortcuts (sendMessage, banChatMember…) | ✅ | ✅ |
+| Full Context (~70 shortcuts reply/edit/admin/react) | ✅ | ✅ |
+| Business flavor (`business_connection_id` automatic) | plugin | ✅ built-in |
+| Filters `on('message:photo' / ':text' / 'chat_type:private' …)` | ✅ | ✅ |
+| `cmd / hears / action / inlineQuery` | ✅ | ✅ (+ inlineQuery matcher) |
+| `branch / filter / drop / route / lazy / fork` | ✅ | ✅ |
+| Error boundary + catch | ✅ | ✅ (all shortcuts auto-protected) |
+| Session + swappable storage | ✅ | ✅ |
+| Transformer API (`api.config.use`) | ✅ | ✅ |
+| `auto-retry` on 429 honoring `retry_after` | plugin | ✅ built-in `autoRetry()` |
+| Throttler queue | plugin | ✅ built-in `throttler()` |
+| Per-user rate limit | plugin | ✅ built-in `limiter()` |
+| `InputFile` Buffer/path/stream + multipart `attach://` | ✅ | ✅ |
+| `InputMedia` builder + media groups | ✅ | ✅ `InputMediaBuilder` |
+| File download (`getFile`/`downloadFile`) | plugin | ✅ built-in |
+| Keyboard & InlineKeyboard fluent classes | ✅ | ✅ |
+| Interactive menus | plugin | ✅ built-in `Menu/MenuContainer` |
+| Wizard/conversations | plugin | ✅ built-in — **+ choice buttons & `edit`/`delete` modes** |
+| 409-resilient long polling | ❌ (fatal crash) | ✅ built-in (auto-retry 5 s) |
+| Broadcast ready to use | ❌ | ✅ `bot.broadcast()` |
+| Humanized errors + suggestions | ❌ | ✅ `humanize()` |
+| Boot banner + debug logging | ❌ | ✅ (`DEBUG=telebibz*`) |
+| HTTP(S) proxy for VPS | ⚠️ manual | ✅ `proxy` transport option |
+| TypeScript | ✅ full | loose d.ts (JS-first) |
+| Documentation language | en | **🇬🇧 + 🇮🇩** |
+
+<a id="install"></a>
+## 📥 Installation & Requirements
+
+**Requirements:** Node.js ≥ 18 (uses global `FormData`/`Blob` for uploads).
 
-![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)
-
-**`@xbibzlibrary/telebibz`** is a Telegram Bot SDK and framework for Node.js and TypeScript. It provides a typed API client, polling, routing, middleware, context helpers, keyboard builders, state/session primitives, webhooks, queues, scheduling, caching, plugin lifecycle, colorful terminal logging, CLI tooling, and testing utilities.
+```bash
+npm install @xbibzlibrary/telebibz
+# or
+yarn add @xbibzlibrary/telebibz
+# or
+pnpm add @xbibzlibrary/telebibz
+```
 
-## Documentation languages
+**Runtime dependencies (all used, all tested):**
 
-**English (default)** · [Bahasa Indonesia](README.id.md) · [简体中文](README.zh-CN.md)
+| Package | Purpose |
+|---|---|
+| `axios ^1.20` | keep-alive transport + streaming `downloadFile` |
+| `mime-types ^3.0` | content-type detection for uploads |
+| `https-proxy-agent ^9.1` | VPS proxy transport option |
+| `debug ^4.4` | logging via `DEBUG=telebibz:net,telebibz:ratelimit` |
 
-Complete API references: [English](docs/API.md) · [Indonesia](docs/API.id.md) · [中文](docs/API.zh-CN.md)
+Get your bot token from **@BotFather** → `/newbot`. The constructor validates the token
+format (`123456:ABC…`) and throws a helpful error if it's wrong.
 
-GitHub Packages guide: [English](docs/GITHUB_PACKAGES.md) · [Bahasa Indonesia](docs/GITHUB_PACKAGES.id.md) · [简体中文](docs/GITHUB_PACKAGES.zh-CN.md)
+<a id="quickstart"></a>
+## 🚀 Quick Start
 
-Storage quick start (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');
 
-Getting started: [English](docs/GETTING_STARTED.md) · [Bahasa Indonesia](docs/GETTING_STARTED.id.md) · [简体中文](docs/GETTING_STARTED.zh-CN.md)
+const bot = new TeleBibz('TOKEN_FROM_BOTFATHER');
 
-Files (upload & download): [English](docs/FILES.md) · [Bahasa Indonesia](docs/FILES.id.md) · [简体中文](docs/FILES.zh-CN.md)
+bot.cmd('start', (ctx) => ctx.reply('Hello!'));
+bot.hears(/hello|hi/i, (ctx) => ctx.reply('hello there 👋'));
+bot.hears('ping', (ctx) => ctx.reply('pong 🏓'));
 
-Errors & rate limits: [English](docs/ERRORS.md) · [Bahasa Indonesia](docs/ERRORS.id.md) · [简体中文](docs/ERRORS.zh-CN.md)
+bot.launch();
+```
 
-Webhook deployment: [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 with MockTransport): [English](docs/TESTING.md) · [Bahasa Indonesia](docs/TESTING.id.md) · [简体中文](docs/TESTING.zh-CN.md)
+```
+┌──────────────────────────────────┐
+│  🤖 TeleBibz ON                   │
+│  bot      : @yourbot (id 123456) │
+│  mode     : long-polling          │
+│  library  : telebibz 3.1.0        │
+│  brand    : //—Xbibz Official—//  │
+└──────────────────────────────────┘
+✔ waiting for updates… (Ctrl+C to stop)
+```
 
-Migrating from Telegraf: [English](docs/MIGRATION_TELEGRAF.md) · [Bahasa Indonesia](docs/MIGRATION_TELEGRAF.id.md) · [简体中文](docs/MIGRATION_TELEGRAF.zh-CN.md)
+> [!NOTE]
+> **On a VPS:** if another bot instance is still polling (409 Conflict — e.g. double
+> deploy or a hosting restart), telebibz **auto-retries every 5 seconds without
+> crashing** and boots the moment the lane is free. No PM2 babysitting needed.
 
-Production cookbook (13 recipes): [English](docs/COOKBOOK.md) · [Bahasa Indonesia](docs/COOKBOOK.id.md) · [简体中文](docs/COOKBOOK.zh-CN.md)
+<a id="architecture"></a>
+## 🧠 How It Works (Architecture)
 
-Full documentation catalog: [docs/README.md](docs/README.md)
+```
+                       ┌─────────────────────────────────────────────┐
+ Telegram Bot API ────►│  long polling (lib/runner.js)               │
+                       │  or webhook / handleUpdate (lib/telebibz.js)│
+                       └──────────────────┬──────────────────────────┘
+                                          │ raw update (JSON)
+                                          ▼
+                       Context(update, api, me)          lib/context.js
+                                          │
+             ┌────────────────────────────▼───────────────────────────┐
+             │  Middleware tree `_root` (fixed order):                │
+             │  1. session()                 lib/session.js           │
+             │  2. wizard.middleware()       lib/wizard.js            │
+             │  3. errorBoundary(reporter)                            │
+             │       └─► your handlers: use/cmd/hears/action/on/      │
+             │           inlineQuery/Menu/wizard      lib/composer.js │
+             └────────────────────────────┬───────────────────────────┘
+                                          │ ctx.reply / ctx.api.*
+                                          ▼
+             ApiBase + Proxy + transformer pipeline        lib/api.js
+             (api.config.use → autoRetry / throttler)
+                                          │
+                                          ▼
+             axios transport: JSON or multipart attach://  lib/net.js
+                                          │
+                                          ▼
+                                 https://api.telegram.org
+```
 
-Community showcase: [SHOWCASE.md](SHOWCASE.md)
+**Lifecycle of one update** (e.g. `/start`): `getUpdates` → `pollLoop` →
+`handleUpdate` → new `Context` → session loads → wizard middleware (no active
+wizard → pass) → error boundary → your matched handler runs → `ctx.reply()` →
+transformer pipeline → axios → Telegram. Any thrown error becomes a `BotError`
+and flows to `opts.onError` or the humanized reporter.
+
+<a id="docs"></a>
+## 📖 Full Documentation
+
+### 🏗️ Constructor & options
+
+```js
+const bot = new TeleBibz('TOKEN', {
+  allowedUpdates: [...],   // limit update types (default: common + Business types)
+  onError: (err, ctx) {},  // custom error handler (default: humanized reporter)
+  silent: false,           // hide boot banner
+  dropPending: false,      // discard old updates on start
+  session: { ... },        // { initial, getKey, storage } — see Sessions
+  transport: fn,           // inject custom transport (testing / proxy)
+});
+```
 
-![telebibz overview](https://cdn.jsdelivr.net/npm/@xbibzlibrary/telebibz@latest/assets/telebibz-readme-preview.png)
+<a id="handlers"></a>
+### 🎛️ Handlers & filters
+
+```js
+bot.cmd('ping',           (ctx) => ctx.reply('pong'));     // /ping
+bot.cmd(['a', 'b'],       handler);                        // /a OR /b
+bot.start('Welcome!');    // shortcut: registers /start
+bot.hears('daftar',       handler);   // exact text "daftar" (case-insensitive)
+bot.hears(/kitt?y/i,      handler);   // any regex
+bot.on('message:photo',   handler);   // grammY-style filters
+bot.on([':text', 'chat_type:private'], handler);
+bot.action('menu:premium', handler);  // callback_query data (string or RegExp)
+bot.inlineQuery(/kucing/i, handler);  // inline mode (regex / string / '*')
+bot.use(middleware);                  // manual middleware
+```
 
-## Installation
+Composer combinators (grammY semantics):
 
-```bash
-npm install @xbibzlibrary/telebibz
+```js
+bot.branch(pred, ifTrue, ifFalse);  // pick a subtree by predicate
+bot.filter(pred, ...mw);            // run only when pred(ctx) is true
+bot.drop(pred, ...mw);              // skip when pred(ctx) is true
+bot.route('chat.type', { private: mwA, group: mwB });       // map ctx→handler
+bot.lazy((ctx) => ctx.from.is_bot ? botMw : userMw);        // build mw per update
+bot.fork(slowMw);                   // run in background, doesn't block next()
 ```
 
-Node.js **22 or newer** is required.
+Filters supported by `on()`: update fields (`message`, `edited_message`,
+`callback_query`, `inline_query`, `my_chat_member`, …), message props
+(`message:photo`, `message:text`, `:caption`, `:document`, `:sticker`, `:media`, …),
+chat types (`chat_type:private/group/supergroup/channel`), plus
+`callback_query:data`, payments, reactions, join requests.
 
-## Minimal bot
+Command handlers receive arguments in `ctx.match`:
 
-```ts
-import { Bot } from "@xbibzlibrary/telebibz";
+```js
+bot.cmd('echo', (ctx) => ctx.reply(`args: ${ctx.match}`)); // /echo hello → "hello"
+```
 
-const bot = new Bot(process.env.TELEGRAM_BOT_TOKEN!);
+<a id="context"></a>
+### 💬 Context shortcuts
 
-bot.command("start", async (ctx) => { await ctx.reply("Bot is active."); });
-bot.onText("ping", async (ctx) => { await ctx.reply("pong"); });
+`ctx` wraps every update kind (message, edited, channel, business, callback,
+inline…) with unified accessors: `chat`, `from`, `chatId`, `msgId`, `msg`,
+`senderChat`, `inlineMessageId`, `businessConnectionId`.
 
-await bot.start();
+| Category | Shortcuts |
+|---|---|
+| **Reply** | `reply`, `replyWithHTML`, `replyWithMarkdown`, `replyWithPhoto/Video/Audio/Document/Animation/Voice/VideoNote/Sticker/MediaGroup/Location/Venue/Contact/Poll/Dice/Invoice/ChatAction` |
+| **Edit & delete** | `editMessageText/Caption/Media/ReplyMarkup`, `deleteMessage`, `deleteMessages` — callback-aware & inline-message aware |
+| **React** | `react('👍')` |
+| **Forward/copy** | `forwardMessage(to)`, `copyMessage(to)` (defaults to current msg) |
+| **Callbacks & inline** | `answerCallbackQuery` (string or object), `answerInlineQuery` |
+| **Admin** | `banChatMember`, `restrictChatMember`, `promoteChatMember`, `banAuthor`, `restrictAuthor`, `getChat*`, `getAuthor`, `leaveChat`, `setChatTitle/Description`, `pin/unpinChatMessage` |
+| **Files** | `getFile()` (smart: largest photo), `downloadFile(dest)` |
+
+Business accounts: replies inside a business context automatically carry
+`business_connection_id`.
+
+<a id="keyboards"></a>
+### 🔘 Keyboards & buttons
+
+```js
+const { btn, url, webApp, copy, kb, InlineKeyboard, Keyboard } = require('@xbibzlibrary/telebibz');
+
+bot.cmd('menu', (ctx) =>
+  ctx.reply('Pick:', kb([
+    [btn('💎 Premium', 'prem', 'primary'),      // blue/purple
+     btn('✅ Register', 'reg', 'success')],     // green
+    [url('🌐 Web', 'https://yoursite.com')],
+    [btn('❌ Close', 'close', 'danger', '5408846744727334338')], // red + ANIMATED ICON
+  ])));
 ```
 
-`Bot.start()` runs long polling. For manual lifecycle control, use `init()`, `launch({ mode: "polling" })`, `health()`, `stop()`, or `restart()`.
+- 🎨 `style` colors (`primary`/`success`/`danger`) need Telegram apps from Feb 2026+ — older apps render plain buttons, never an error.
+- ✨ `icon_custom_emoji_id` needs a Premium bot owner or a Fragment username.
+- Helpers: `copy(text, value)` (copy-to-clipboard), `webApp(text, link)`, `kb.confirm(yesData, noData)`, `kb.markup(rows)`.
+- Fluent classes: `new InlineKeyboard().text(...).url(...).row().text(...).build()` and `new Keyboard().text(...).requestContact(...).resized().build()` (real reply keyboards).
 
-## Official starter examples
+<a id="menus"></a>
+### 🍽️ Interactive menus
 
-The repository includes runnable starters for a minimal bot, a multi-step registration wizard, and a Node.js webhook server. Browse [`examples/README.md`](examples/README.md), or run the minimal starter after setting `TELEGRAM_BOT_TOKEN`:
+```js
+const { Menu, MenuContainer } = require('@xbibzlibrary/telebibz');
 
-```bash
-export TELEGRAM_BOT_TOKEN="<your-bot-token>"
-npx tsx examples/minimal.ts
+const mc = new MenuContainer();
+const main = mc.create('main'), more = mc.create('more');
+
+main.text('🔔 Toggle', async (ctx) => ctx.answerCallbackQuery('toggled!'))
+    .row()
+    .url('🌐 Web', 'https://x.com')
+    .submenu('More ▶', 'more');
+more.back('◀️ Back', 'main');
+
+bot.use(mc); // button handlers registered automatically
+bot.cmd('cfg', (ctx) => ctx.reply('Menu:', { reply_markup: main.render(ctx) }));
 ```
 
-The examples are typechecked in CI with `npm run test:examples` and never contain real credentials.
+Submenus swap the keyboard in place via `editMessageReplyMarkup`; stale button
+presses are answered with a friendly alert instead of crashing.
 
-## Router and middleware
+<a id="wizard"></a>
+### 🧙 Wizard — conversation forms, zero boilerplate
 
-```ts
-bot.use(async (ctx, next) => {
-  const started = Date.now();
-  await next();
-  console.log(`processed in ${Date.now() - started}ms`);
+```js
+bot.wizard('register', {
+  steps: [
+    { key: 'name', ask: 'What is your name?' },
+    { key: 'age', ask: 'Age?', parse: Number,
+      validate: (n) => (n > 0 && n < 120 ? null : 'Numbers only, please:') },
+  ],
+  done: async (ans, ctx) => ctx.reply(`Done ${ans.name} (${ans.age})!`),
 });
+// user runs /register → the bot asks until finished.
+// typing "cancel" / "batal" stops any time. Session is active automatically.
+```
+
+`bot.wizard(id, def, bindCommand = true)` also binds `/id` as the trigger; use
+`bot.wizardStart(ctx, id)` from any handler (button, menu, …).
+
+#### 🆕 v3.1 — choice buttons + `edit`/`delete` modes
+
+```js
+bot.wizard('survey', {
+  mode: 'edit',        // 'send' (default) | 'edit' | 'delete'
+  steps: [
+    // reply keyboard — user taps, no typing
+    { key: 'gender', ask: 'Gender?', buttons: ['👨 Male', '👩 Female'], onlyButtons: true },
+
+    // inline keyboard (callback) — value may differ from label
+    { key: 'island', ask: 'Which island?', inline: true, onlyButtons: true,
+      buttons: [[{ text: '🌋 Java', value: 'java' }, { text: '🌴 Sumatra', value: 'sumatra' }]] },
 
-bot.command("help", async (ctx) => { await ctx.reply("Help is available."); });
-bot.onRegex(/^order:(\d+)$/, async (ctx) => { await ctx.reply("Order received."); });
-bot.callback("profile:*", async (ctx) => { await ctx.answerCallbackQuery("Opened."); });
-bot.action("menu:open", async (ctx) => { await ctx.answerCallbackQuery("Menu opened."); });
-bot.on("message:photo", async (ctx) => { await ctx.reply("Nice photo."); });
-bot.on(["message:text", "callback_query:data"], async (ctx) => { await ctx.reply("Got it."); });
-bot.hears("ping", async (ctx) => { await ctx.reply("pong"); });
-bot.catch(async (error, ctx) => { await ctx.reply("Something went wrong."); });
+    // free typing with validation (mode can be overridden per step)
+    { key: 'age', ask: 'Age?', parse: Number, mode: 'send',
+      validate: (n) => (n > 0 && n < 120 ? null : 'Numbers only:') },
+  ],
+  done: async (ans, ctx) => ctx.reply(`Saved: ${JSON.stringify(ans)}`),
+});
 ```
 
-The router supports commands, exact text, regular expressions, callback patterns, update-type filters (`on`), custom predicates, nested routers, per-route middleware, and route priority. `bot.catch()` registers an error boundary: handler failures are routed there instead of rejecting the update.
+| Option | Level | Purpose |
+|---|:---:|---|
+| `buttons` | step | `['A','B']`, `[{text,value}]`, or explicit rows `[['A'],['B','C']]` |
+| `inline` | step | `true` → callback buttons (click = value, no typing) |
+| `onlyButtons` | step | `true`/string → reject free typing, must pick a button |
+| `mode` | def/step | `'send'` new message · `'edit'` one message edited in place · `'delete'` old question deleted first |
+| `cleanup` | def | delete the last question when done (default on with mode `'delete'`) |
+| `removeKeyboard` | def | dismiss the reply keyboard when done (default `true` if one was shown) |
+
+Programmatic helpers: `bot.wizardCancel(ctx)`, `bot.wizardEdit(ctx, text)`,
+`bot.wizardDelete(ctx)`, plus module `wizard` (`cancel/editAsk/deleteAsk`).
+Stale buttons (clicked after the wizard advanced/ended) get a safe alert —
+the bot never crashes. `parse`/`validate` also apply to button values.
+
+<a id="inline"></a>
+### ❓ Inline mode
+
+```js
+const { iq } = require('@xbibzlibrary/telebibz');
+
+bot.inlineQuery(/cat/i, async (ctx) => {
+  await ctx.answerInlineQuery([
+    iq.article('1', 'A cat fact', { message_text: 'meong!' }),
+    iq.photo('2', 'https://x/1.jpg'),
+  ], { cache_time: 0 });
+});
+```
 
-## Telegram API
+Builders: `iq.article/photo/gif/video/audio/location/sticker`.
 
-Generated method access and raw access are available through the API client:
+<a id="broadcast"></a>
+### 📣 Broadcast (rate-limit safe)
 
-```ts
-await bot.api.methods.getMe();
-await bot.api.methods.sendMessage({ chat_id: 123456789, text: "Hello." });
-await bot.api.call("sendMessage", { chat_id: 123456789, text: "Hello." });
-await bot.api.raw("futureTelegramMethod", { value: true });
+```js
+const result = await bot.broadcast([111, 222, 333], 'Announcement!', { delay: 35 });
+// → { terkirim: 3, gagal: 0, errors: [] }  (blocked users are listed in errors)
 ```
 
-The built-in transport uses `fetch`, timeouts, retries, exponential backoff, JSON payloads, and multipart upload.
+`pesan` may be a string, a `sendMessage` payload object, or a function
+`(chatId) => payload` for per-recipient personalization. Default pacing is
+35 ms (≈28 msg/s, safely under Telegram limits).
+
+<a id="files"></a>
+### 📎 Files & 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: 'two' }),
+]));
+bot.on('message:photo', async (ctx) => {
+  const f = await ctx.getFile();        // largest photo size, automatic
+  await ctx.downloadFile('./foto.jpg'); // streams to disk
+});
+```
 
-## Keyboard builders
+`InputFile` accepts Buffer / Uint8Array / file path / fs stream / async
+iterable; uploads are sent as `multipart` with `attach://` anywhere in the
+payload (media groups, thumbnails, …). `api.downloadFile(file_id, dest)` works
+standalone too.
 
-```ts
-import { InlineKeyboard } from "@xbibzlibrary/telebibz";
+<a id="ratelimit"></a>
+### 🛡️ Reliability & rate limiting
 
-const keyboard = new InlineKeyboard()
-  .text("Profile", "profile")
-  .url("Documentation", "https://core.telegram.org/bots/api")
-  .build();
+```js
+const { autoRetry, throttler, limiter } = require('@xbibzlibrary/telebibz');
 
-await ctx.reply("Choose an option:", { reply_markup: keyboard });
+bot.api.config.use(autoRetry());            // retry 429, honor retry_after (max 5)
+bot.api.config.use(throttler());            // global queue ≤ 28 calls/second
+bot.use(limiter({ windowMs: 2000, limit: 3, onExceeded })); // per-user anti-spam
 ```
 
-Builders produce native Telegram keyboard payloads. HTML/CSS interfaces require a separate Mini App or Web App.
+Long polling is resilient by default: 409 conflicts retry every 5 s
+(`launch({ conflictDelay: 5000 })` to tune), network hiccups back off 1 s,
+`stop()` exits cleanly (`await bot.runPromise`).
 
-## Colorful runtime logging
+<a id="sessions"></a>
+### 🗃️ Sessions
 
-The logger emits compact, readable terminal lines with colored levels and structured context. Log levels are `silent`, `error`, `warn`, `info`, `debug`, and `trace`; sensitive values are redacted; errors print in red with the full stack. Use `format: "json"` for machine ingestion and `includeUpdateContent: true` only when message text or callback data is explicitly required.
+```js
+const { session } = require('@xbibzlibrary/telebibz');
 
-```ts
-const bot = new Bot({
-  token: process.env.TELEGRAM_BOT_TOKEN!,
-  logger: { level: "debug", format: "pretty", color: true },
+const bot = new TeleBibz(token, {
+  session: {
+    initial: () => ({ count: 0 }),
+    getKey: (ctx) => `${ctx.from?.id}:${ctx.chat?.id}`,   // default
+    storage: myRedisAdapter,   // { read(k), write(k,v), delete(k) } — default: in-memory Map
+  },
 });
+
+bot.on(':text', (ctx) => { ctx.session.count++; });
 ```
 
+`ctx.session` is always present, even without configuration.
+
+<a id="errors"></a>
+### 🇮🇩 Human-readable errors
 
-## Wizards and multi-step conversations
+Every error is reported with an actionable suggestion:
 
-Use `Wizard` with `bot.useWizard()` so every subsequent text reply from the same chat/user is routed to the active step automatically. The key is generated from the Telegram chat and sender; no manual key is required.
+```
+✖ Telegram error (403): Forbidden: bot was blocked by the user
+  💡 saran: Bot diblokir pengguna — jangan kirim ulang, hapus dari daftar broadcast.
+```
 
-```ts
-import { Bot, Wizard } from "@xbibzlibrary/telebibz";
+`humanize(err)` returns `{ pesan, saran, method, code }` covering 15+ common
+Telegram errors (bad token, chat not found, rights, parse errors, rate limits,
+stale callbacks, oversize files, …). Override with
+`new TeleBibz(token, { onError: (err, ctx) => {} })`.
 
-const wizard = new Wizard()
-  .step({ id: "prompt-name", run: async (flow) => { flow.next(); await flow.ctx.reply("What is your name?"); } })
-  .step({ id: "name", run: async (flow) => { flow.set("name", flow.ctx.message?.text?.trim()); flow.next(); await flow.ctx.reply("How old are you?"); } })
-  .step({ id: "age", run: (flow) => { const age = Number(flow.ctx.message?.text?.trim()); if (!Number.isInteger(age)) return; flow.set("age", age); flow.next(); } });
+<a id="webhook"></a>
+### 🕸️ Webhooks & serverless
 
-const bot = new Bot(process.env.TELEGRAM_BOT_TOKEN!);
-bot.useWizard(wizard);
-bot.command("start", async (ctx) => { await wizard.run(ctx); });
-await bot.start();
+```js
+const http = require('http');
+http.createServer((req, res) =>
+  req.url === '/tg' ? bot.webhook()(req, res) : res.end('ok')
+).listen(8443);
+
+// any framework (Express/Fastify/Hono): mount the (req, res) handler from bot.webhook()
+// or serverless, directly:
+await bot.handleUpdate(req.body);   // one raw update in → full pipeline
 ```
 
-`Wizard` keeps its default `ConversationManager` across updates and marks the conversation completed immediately after the final step. Use `/cancel` to cancel an active wizard.
+Remember `await bot.init()` first when you don't call `launch()` (it fetches
+bot info), and `setWebhook(url)` via `bot.api.setWebhook({ url })`.
+
+<a id="proxy"></a>
+### 🔌 Proxy transport (VPS behind a 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 })` also lets you
+point at a local Bot API server.
 
-```ts
-import { Bot, createWebhookHandler } from "@xbibzlibrary/telebibz";
+<a id="transformers"></a>
+### 🧪 Transformers (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);           // observe/modify every Bot API call
+  return prev(method, payload);
 });
+
+// any method, even unreleased ones (Proxy magic):
+await bot.api.sendDiceCustom({ chat_id: 1, emoji: '🎲' });
 ```
 
-`createWebhookHandler` accepts a standard Web `Request` and returns a `Response`. It verifies the optional secret token, body size, JSON payload, and update shape before calling `bot.handleUpdate()`.
+<a id="analytics"></a>
+## 📈 Analytics & Statistics
 
-## High-load updates and broadcast
+### 📊 This repo in numbers
 
-telebibz is built for bursts of 1000+ messages with no artificial cooldown:
+| Metric | Value |
+|---|---|
+| 📦 Source modules | **16 files** in `lib/` |
+| 📝 Total lines of code | **~1,700** (no build step) |
+| 🔌 Bot API methods | **90+** — 75 typed shortcuts + unbounded Proxy |
+| ⌨️ Context shortcuts | **50+** (reply/edit/delete/admin/react…) |
+| 🧪 Offline tests | **30/30 passing**, zero network |
+| 🧩 Ready examples | **7** in `examples/` |
+| 📦 Runtime dependencies | **4** — all used, all tested |
 
-- **Parallel across chats, ordered per chat.** Every `getUpdates` batch (and every webhook request) is processed concurrently — updates from different chats never queue behind each other, while updates from the same chat keep their arrival order so sessions, wizards, and conversations stay correct and session writes are never lost. A concurrent burst triggers exactly one `getMe` initialization. Feed pre-fetched batches yourself with `bot.handleUpdates()` when you own the polling loop.
-- **No proactive throttling.** Outgoing requests are never delayed by the library. When Telegram answers 429, the transport waits exactly the `retry_after` window Telegram ordered (a global "flood gate" protects all in-flight traffic) and retries automatically — so bursts deliver completely instead of failing. For your own downstream limits, `Limiter` and `mapWithConcurrency()` rate-shape any workload.
-- **Broadcast to 1000+ users at once.** `bot.broadcast()` attempts every chat immediately, retries 429s per Telegram's own `retry_after`, and returns a full report.
-- **Graceful shutdown.** `bot.stop()` first waits for in-flight handlers to finish (bounded by `handlerTimeout`) and only then stops the plugin manager — active conversations are never truncated mid-write.
+### ⬇️ Downloads & popularity (live from 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} delivered`) },
-);
-console.log(`Delivered ${report.delivered}/${report.total} in ${report.durationMs}ms`);
-```
+[![per day](https://img.shields.io/npm/dd/@xbibzlibrary/telebibz?style=flat-square&label=day&color=informational)](https://www.npmjs.com/package/@xbibzlibrary/telebibz)
+[![per week](https://img.shields.io/npm/dw/@xbibzlibrary/telebibz?style=flat-square&label=week&color=informational)](https://www.npmjs.com/package/@xbibzlibrary/telebibz)
+[![per month](https://img.shields.io/npm/dm/@xbibzlibrary/telebibz?style=flat-square&label=month&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)
 
-Cap simultaneous work with `new Bot({ ..., updates: { concurrency: 64 } })` or `broadcast(..., { concurrency: 64 })` when your own downstream (database, API) needs it — by default both run fully parallel.
+### 📏 Module size map (lines of code)
 
-## Full Telegraf parity on the context surface
+```
+wizard.js      █████████████████████████ 247  ← forms + buttons + edit/delete
+telebibz.js    ███████████████████▎      193  ← main class & lifecycle
+context.js     ███████████████████       190  ← ctx + 50-ish shortcuts
+composer.js    █████████████████▍        174  ← middleware engine & filters
+api.js         ███████████████▍          154  ← 75 shortcuts + Proxy + transformers
+net.js         ███████████▌              115  ← axios transport + multipart
+menus.js       █████████                  90  ← Menu/MenuContainer
+keyboard.js    ████████▎                  83  ← btn/url/kb + fluent classes
+ratelimit.js   ██████                     61  ← autoRetry · throttler · limiter
+runner.js      ████▌                      45  ← 409-resilient polling
+file.js        ████                       41  ← InputFile + InputMediaBuilder
+logger.js      ███▊                       38  ← logs + banner
+session.js     ███▌                       36  ← swappable sessions
+errors.js      ███▌                       35  ← humanized errors 🇮
+broadcast.js   ███                       35  ← rate-limit-safe blast
+inline-query.js██▊                        28  ← matcher + result builders
+```
 
-Every Telegraf context shortcut is available, plus additions that cover what the Telegraf core leaves to its plugin ecosystem:
+### 🗺️ Repo health
 
-- **Moderation & admin** — `ctx.banChatMember`, `ctx.unbanChatMember`, `ctx.restrictChatMember`, `ctx.promoteChatMember`, `ctx.banChatSenderChat`, `ctx.unbanChatSenderChat`
-- **Chat management** — `ctx.setChatTitle/Description/Photo`, `ctx.setChatPermissions`, `ctx.leaveChat`, `ctx.unpinAllChatMessages`, `ctx.setChatStickerSet`, `ctx.deleteChatStickerSet`
-- **Info** — `ctx.getChatAdministrators`, `ctx.getChatMemberCount`, `ctx.getChatMember`
-- **Invite links & join requests** — `ctx.exportChatInviteLink`, `ctx.createChatInviteLink`, `ctx.editChatInviteLink`, `ctx.revokeChatInviteLink`, `ctx.approveChatJoinRequest`, `ctx.declineChatJoinRequest`
-- **Polls, games, payments** — `ctx.replyWithQuiz`, `ctx.stopPoll`, `ctx.editMessageLiveLocation`, `ctx.stopMessageLiveLocation`, `ctx.replyWithGame`, `ctx.setGameScore`, `ctx.getGameHighScores`, `ctx.replyWithInvoice`
-- **Forum topics** — `ctx.createForumTopic`, `ctx.closeForumTopic`, `ctx.editGeneralForumTopic`, and nine more
-- **Launch options** — `handlerTimeout` (default 90s, like Telegraf) rejects hung updates with `UpdateTimeoutError` while the handler keeps running; `0` disables the timeout; `contextType` plugs in your own `Context` subclass; `dropPendingUpdates` on `start()/launch()`
-- **Webhook replies** — opt-in `webhookReply: true` answers the first API call through the webhook HTTP response itself (Telegraf-style), with the lazy `getMe` never claiming the slot
-- **Drop-in handler aliases** — `bot.action(...)` registers a callback-query handler just like `bot.callback(...)`, so handlers written for Telegraf migrate unchanged
+<div align="center">
 
-## State, queue, scheduler, and cache
+[![repo card](https://github-readme-stats.vercel.app/api/pin/?username=XbibzOfficial777&repo=telebibz&show_owner=false)](https://github.com/XbibzOfficial777/telebibz)
 
-The package provides `MemoryStorage` with TTL and serialized per-key updates, `JsonFileStorage`, `RedisStorage`, `SqlStorage`, `MongoStorage`, persistent application state storage, bot sessions, storage-backed conversations and forms, permission-aware menus, `MenuController` pagination, `MemoryCache`, a token-bucket limiter, a task queue with retry/backoff/concurrency/delay/cancel, and schedulers for intervals, one-shot tasks, and full five-field cron expressions. Redis, SQL, and Mongo adapters use small driver interfaces so the core package remains free of vendor runtime dependencies.
+</div>
 
-## Terminal experience
+<details>
+<summary>📅 Star history (click to open)</summary>
 
-When the bot starts on an interactive terminal (`npm start`, `node index.js`, `telebibz start`), telebibz plays a startup sequence: a typing effect for `Installing Dependencies......`, a glass progress bar with a sweeping highlight, and the animated rainbow ASCII banner **Tele Bibz** (figlet `Speed` font) that keeps flowing until the bot connects, then freezes with `✓ Connected as @<username>`.
+![Star History](https://api.star-history.com/svg?repos=XbibzOfficial777/telebibz&type=Date)
 
-Afterwards, every incoming update is logged on a human-readable line, and errors are printed in red with the full stack:
+</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="examples"></a>
+## 🧩 Ready Examples (`examples/`)
 
-Message and command text is truncated to 50 characters; callback button data is shown in full. Pass `branding: false` to `Bot` to disable the sequence, or set `logger.format: "json"` for structured log ingestion. Non-interactive stdout (pipes, Docker, CI) automatically falls back to plain output without animations.
+| File | Content |
+|---|---|
+| `01-quickstart.js` | bot up in 6 lines |
+| `02-menu-tombol.js` | colored keyboard + animated icons |
+| `03-wizard.js` | registration form + **buttons + edit mode** |
+| `04-broadcast.js` | admin blast |
+| `05-kirim-file.js` | photos & documents from buffers |
+| `06-menu.js` | interactive menus + submenus |
+| `07-inline-query.js` | inline mode with result builders |
 
-## CLI
+Run any of them with `BOT_TOKEN=123:abc node examples/01-quickstart.js`.
 
-CLI commands such as `telebibz doctor`, `init`, and `webhook` start with the rainbow `Tele Bibz` banner. Startup animation automatically falls back to clean static output when stdout is not a TTY.
+<a id="testing"></a>
+## 🔬 Testing & Live Proof
 
 ```bash
-npm start
-npx telebibz init my-bot
-npx telebibz doctor
-npx telebibz build
-npx telebibz test
+npm test   # 30 cases, NO network (transport injected)
 ```
 
-Applications can print the same terminal branding explicitly:
+Validated **30/30 offline + 10 live** on the production bot `@xbibzrat_bot`:
+getMe · colored keyboards & real animated icons · multipart uploads
+(photo+document) · keyboard editing · broadcast · deleteMessage · polling 409
+retry · wizard buttons & edit/delete.
 
-```ts
-import { printTeleBibzBanner, printTerminalBranding } from "@xbibzlibrary/telebibz";
+Debug logging: `DEBUG=telebibz:net,telebibz:ratelimit node yourbot.js`.
 
-printTeleBibzBanner({ subtitle: "My bot" });
-printTerminalBranding();
-```
+<a id="structure"></a>
+## 📂 Repo Structure (16 core files)
 
-## Testing
+| File | Role |
+|---|---|
+| `lib/net.js` | axios keep-alive transport + multipart `attach://` |
+| `lib/api.js` | Bot API methods + any-method Proxy + transformers |
+| `lib/composer.js` | middleware, `on('message:photo')` filters, `errorBoundary` |
+| `lib/context.js` | ctx object + 50-ish reply/edit/delete/callback shortcuts |
+| `lib/session.js` | per user:chat sessions (swappable storage) |
+| `lib/runner.js` | long polling: 409 retry, network backoff, drop pending |
+| `lib/wizard.js` | conversation forms + choice buttons + edit/delete modes |
+| `lib/menus.js` | `Menu`/`MenuContainer` interactive menus |
+| `lib/keyboard.js` | button builders + fluent `InlineKeyboard`/`Keyboard` |
+| `lib/ratelimit.js` | `autoRetry` 429 · `throttler` queue · per-user `limiter` |
+| `lib/broadcast.js` | rate-limit-safe blast |
+| `lib/file.js` | `File`/`InputFile` (Buffer/path/stream) + `InputMediaBuilder` |
+| `lib/inline-query.js` | query matcher + inline result builders |
+| `lib/errors.js` | humanized errors + suggestions |
+| `lib/logger.js` | framed logs + boot banner |
+| `index.js` / `index.d.ts` | export door + TypeScript types |
 
-```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
 
-Real Telegram E2E tests require `TELEGRAM_BOT_TOKEN` and `TELEGRAM_TEST_CHAT_ID`. Without credentials, E2E tests are skipped and are not counted as passing.
+- **3.1.0** — wizard: choice buttons (reply/inline), `edit`/`delete` modes, auto cleanup, programmatic helpers · tests 24 → 30
+- **3.0.0** — production-grade grammY parity: axios keep-alive, transformers, menus, inline query, limiter
+- **2.0.0** — engine rewritten from scratch, multipart transport, native Node webhook
+- **1.0.0** — grammY architecture recode
 
-## Web Apps and payments
+> Full details in [`CHANGELOG.md`](CHANGELOG.md). Deep architecture study (🇮): [`ANALISIS-telebibz.md`](ANALISIS-telebibz.md).
 
-`validateWebAppInitData()` verifies Telegram Web App signatures and expiration. `PaymentsClient` provides wrappers for invoice links, invoices, pre-checkout answers, Web App query answers, Stars transactions, and Stars refunds. Use `TelegramTypes` and aliases such as `TelegramUser`, `TelegramMessage`, and `TelegramUpdate` for the vendored full Telegram declaration surface.
+<a id="license"></a>
+## 📄 License
 
-## API surface
+**MIT** © Xbibz Official — architecture inspired by [grammY](https://grammy.dev) (MIT, see [`NOTICE.md`](NOTICE.md)).
 
-Everything below ships from the package entry point unless a subpath is given. Full signatures for every export are documented in [docs/API.md](docs/API.md) (also [docs/API.id.md](docs/API.id.md) and [docs/API.zh-CN.md](docs/API.zh-CN.md)).
+---
 
-| Area | Exports |
-|---|---|
-| Bot & lifecycle | `Bot` with `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`, `contextType` launch option; ~80 shortcuts on `ctx` for replies, admin actions, chat management, invite links, polls, games, payments, and forum topics |
-| Telegram API | `ApiClient` with `call()`, `request()`, `raw()`, `downloadFile()`, and `methods` (all generated Bot API methods); `FetchTransport` with automatic 429/5xx retries, a global flood gate, multipart uploads (Blob/bytes/path/streams), and file downloads |
-| Errors | `TelegramError` with a `kind` taxonomy (`retryable`, `rate-limit`, `authentication`, `validation`, `network`, `server`, `unknown`) and `retryAfter`, plus `TelegramRateLimitError`, `TelegramAuthError`, `TelegramValidationError`, `TelegramNetworkError` |
-| Router & middleware | `Router`, `compose`, 24 update filters (`message:photo`, `callback_query:data`, …), `matchMode` (`first`/`all`) |
-| Keyboards | `InlineKeyboard`, `ReplyKeyboard`, `removeKeyboard()`, `forceReply()` |
-| Storage | `MemoryStorage` (TTL, per-key serialization), `JsonFileStorage`, `RedisStorage`, `SqlStorage`, `MongoStorage`, plus the small driver interfaces they build on |
-| Cache & limiting | `MemoryCache`, `TokenBucketLimiter`, `Limiter`, `mapWithConcurrency()` |
-| Queue & scheduler | `TaskQueue` (priority, retry, backoff, delay, cancel), `Scheduler` (intervals, one-shot, cron), `parseCronExpression()`, `nextCronOccurrence()` |
-| State & dialogs | `Wizard`, `ConversationManager`, `ConversationFlow`, `Form` with `validators`, permission-aware `Menu`, `MenuController`, `paginate()` |
-| Webhook | `createWebhookHandler()` (Web `Request`/`Response`), `webhookCallback()` for Express/Koa/Fastify/Node `http`, `runWithWebhookReply()`, `claimWebhookReply()` |
-| Web Apps & payments | `parseWebAppInitData()`, `validateWebAppInitData()`, `PaymentsClient`, `TelegramTypes` (vendored Telegram declarations) |
-| Observability | `Logger` (levels, redaction, JSON format), `EventBus` with the `update:*`, `bot:*`, and `broadcast:*` event maps, `redact()` |
-| Terminal | `printTeleBibzBanner()`, `printTerminalBranding()`, `buildTerminalBranding()`, `runStartupSequence()`, `startTeleBibzBanner()`, `paintRainbow()`, `printStatusLine()` |
-| Text utilities | `splitMessage()`, `splitCaption()`, `escapeMarkdownV2()`, `escapeHtml()`, `md`, `html`, `template()` |
-| File utilities | `validateUpload()`, `assertValidUpload()`, `UploadValidationError` (size, MIME, extension rules) |
-| Testing (`@xbibzlibrary/telebibz/testing`) | `MockTransport` (with mock downloads), `createTestBot()`, `createMockUpdate()`, `createMockCallbackUpdate()`, `createMockContext()` |
-| CLI (`telebibz …`) | `init`, `doctor`, `build`, `test`, `start`, `webhook`, `generate` |
-
-## API targets and limitations
-
-The generated method list is derived from the Telegram Bot API schema when it is updated. Runtime access is available for detected official methods, while specialized request/result inference remains concentrated on the core method map. The complete vendored Telegram object, union, enum, and method declarations are available through `TelegramTypes`. See [FEATURE_MATRIX.md](FEATURE_MATRIX.md) for implementation status and [docs/API.md](docs/API.md) for the complete API reference.
-
-For every exported class, function, method, type, error, lifecycle hook, CLI command, and generated Telegram method, see the [complete English API reference](docs/API.md).
-
-## Release automation
-
-The GitHub repository includes CI and an auto-publish workflow. A push to `main` runs the quality gates and derives the next version from the pushed Conventional Commits: `feat:` commits and breaking changes bump the minor version while the package is pre-1.0 (`BREAKING-CHANGE` footers or `type!:` subjects bump the major from 1.0.0 onward), everything else bumps the patch version. A version already declared in `package.json` ahead of npm publishes exactly as declared, and the workflow never publishes a version at or below the latest npm release. The workflow commits the version, creates the tag, publishes to npm (with provenance disabled via `--provenance=false`), and creates a GitHub Release. Commits containing `[skip release]` do not trigger a publication. Configure the `NPM_TOKEN` GitHub Actions secret before relying on automatic publication. See [RELEASE_AUTOMATION.md](RELEASE_AUTOMATION.md).
-
-## Project policies and contribution
-
-| Document | Purpose |
-|---|---|
-| [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) | Community behavior, enforcement, reporting, and appeals. |
-| [CONTRIBUTING.md](CONTRIBUTING.md) | Local setup, branch/commit rules, tests, review, and release workflow. |
-| [CONTRIBUTION_RULES.md](CONTRIBUTION_RULES.md) | API, compatibility, testing, dependency, security, and release requirements. |
-| [GOVERNANCE.md](GOVERNANCE.md) | Roles, decision-making, triage, repository protection, and amendments. |
-| [SECURITY.md](SECURITY.md) | Private vulnerability reporting, threat boundaries, and credential rotation. |
-| [SUPPORT.md](SUPPORT.md) | Support channels, safe-reporting rules, and request expectations. |
-| [RELEASE_AUTOMATION.md](RELEASE_AUTOMATION.md) | GitHub-to-npm automation and required `NPM_TOKEN` setup. |
-| [RELEASE_POLICY.md](RELEASE_POLICY.md) | Immutable release and hardening controls. |
-| [NOTICE.md](NOTICE.md) | Third-party declaration attribution. |
+<div align="center">
+
+**Made with ❤️ by //—Xbibz Official—//**
 
-Never commit Telegram tokens or npm credentials. Use environment variables or a secret manager. See [SECURITY.md](SECURITY.md) and [RELEASE_POLICY.md](RELEASE_POLICY.md) for security and release hardening policies.
+If telebibz helps you, a ⭐ on this repo means a lot.
 
-## License
+[![repo views](https://komarev.com/ghpvc/?username=XbibzOfficial777&repo=telebibz&style=flat-square&color=blueviolet&label=repo+views)](https://github.com/XbibzOfficial777/telebibz)
 
-MIT. See [LICENSE](LICENSE).
+</div>