@xbibzlibrary/telebibz 0.1.19 → 0.2.1

package/dist-cjs/src/state/forms.js

@@ -3,32 +3,35 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.validators = exports.Form = void 0;
 class Form {
     fields = new Map();
-    values = {};
     field(definition) { this.fields.set(definition.name, definition); return this; }
-    async parse(input) { const issues = []; for (const [name, field] of this.fields) {
-        const raw = input[name];
-        if ((raw === undefined || raw === null || raw === "") && field.required) {
-            issues.push({ path: name, message: "Field is required", code: "required" });
-            continue;
+    async parse(input) {
+        const issues = [];
+        const values = {};
+        for (const [name, field] of this.fields) {
+            const raw = input[name];
+            if ((raw === undefined || raw === null || raw === "") && field.required) {
+                issues.push({ path: name, message: "Field is required", code: "required" });
+                continue;
+            }
+            if (raw === undefined || raw === null || raw === "")
+                continue;
+            try {
+                let value = field.parse(raw);
+                if (field.transform)
+                    value = await field.transform(value);
+                const error = await field.validate?.(value);
+                if (error)
+                    issues.push({ path: name, message: error, code: "invalid" });
+                else
+                    values[name] = value;
+            }
+            catch (error) {
+                issues.push({ path: name, message: error instanceof Error ? error.message : "Invalid value", code: "parse" });
+            }
         }
-        if (raw === undefined || raw === null || raw === "")
-            continue;
-        try {
-            let value = field.parse(raw);
-            if (field.transform)
-                value = await field.transform(value);
-            const error = await field.validate?.(value);
-            if (error)
-                issues.push({ path: name, message: error, code: "invalid" });
-            else
-                this.values[name] = value;
-        }
-        catch (error) {
-            issues.push({ path: name, message: error instanceof Error ? error.message : "Invalid value", code: "parse" });
-        }
-    } return issues.length ? { success: false, issues } : { success: true, data: this.values }; }
-    reset() { for (const key of Object.keys(this.values))
-        delete this.values[key]; }
+        return issues.length ? { success: false, issues } : { success: true, data: values };
+    }
+    reset() { }
 }
 exports.Form = Form;
 exports.validators = { string: (value) => { if (typeof value !== "string")

package/dist-cjs/src/storage/storage.js

@@ -23,6 +23,20 @@ class MemoryStorage {
         }
         return entry.value;
     }
+    /**
+     * Reads the raw entry including expiry metadata. Intended for storage adapters
+     * (such as `JsonFileStorage`) that need to persist TTL information across restarts.
+     */
+    async readEntry(key) {
+        const entry = this.valuesMap.get(key);
+        if (!entry)
+            return undefined;
+        if (entry.expiresAt !== undefined && entry.expiresAt <= Date.now()) {
+            this.valuesMap.delete(key);
+            return undefined;
+        }
+        return entry.expiresAt === undefined ? { value: entry.value } : { value: entry.value, expiresAt: entry.expiresAt };
+    }
     async set(key, value, options = {}) {
         const expiresAt = expiration(options.ttlMs);
         this.valuesMap.set(key, expiresAt === undefined ? { value } : { value, expiresAt });
@@ -84,8 +98,12 @@ class JsonFileStorage {
         await this.ready;
         this.writeChain = this.writeChain.then(async () => {
             const output = {};
-            for await (const [key, value] of this.memory.entries())
-                output[key] = { value };
+            for await (const key of this.memory.keys()) {
+                const entry = await this.memory.readEntry(key);
+                if (entry === undefined)
+                    continue;
+                output[key] = entry.expiresAt === undefined ? { value: entry.value } : { value: entry.value, expiresAt: entry.expiresAt };
+            }
             await (0, promises_1.mkdir)((0, node_path_1.dirname)(this.filePath), { recursive: true });
             const temporary = `${this.filePath}.${process.pid}.tmp`;
             await (0, promises_1.writeFile)(temporary, JSON.stringify(output, null, 2), "utf8");

package/dist-cjs/src/webhook/handler.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createWebhookHandler = createWebhookHandler;
+exports.webhookCallback = webhookCallback;
 const node_crypto_1 = require("node:crypto");
 function createWebhookHandler(bot, options = {}) {
     const maxBodyBytes = options.maxBodyBytes ?? 1_048_576;
@@ -31,6 +32,91 @@ function createWebhookHandler(bot, options = {}) {
         }
     };
 }
+function webhookCallback(bot, _framework = "express", options = {}) {
+    const maxBodyBytes = options.maxBodyBytes ?? 1_048_576;
+    return async (req, res) => {
+        const rawReq = req;
+        const rawRes = res;
+        const sendResponse = (status, message) => {
+            if (rawRes && typeof rawRes.writeHead === "function" && typeof rawRes.end === "function") {
+                rawRes.writeHead(status, { "Content-Type": "text/plain" });
+                rawRes.end(message);
+                return;
+            }
+            const expressLike = rawRes;
+            if (typeof expressLike?.status === "function" && typeof expressLike.send === "function") {
+                expressLike.status(status).send(message);
+                return;
+            }
+            const koaLike = rawRes;
+            if (koaLike !== undefined) {
+                koaLike.status = status;
+                koaLike.body = message;
+            }
+        };
+        if (rawReq.method !== "POST") {
+            sendResponse(405, "Method Not Allowed");
+            return;
+        }
+        if (options.secretToken) {
+            if (!secureEqual(readHeader(rawReq, "x-telegram-bot-api-secret-token"), options.secretToken)) {
+                sendResponse(401, "Unauthorized");
+                return;
+            }
+        }
+        try {
+            let update;
+            if (typeof rawReq.arrayBuffer === "function") {
+                // Web-standard Request objects (e.g. Deno, Bun, WinterCG runtimes, or
+                // a converted fetch Request) expose the body through arrayBuffer().
+                // Checked before `body` because a Request's `body` is a ReadableStream.
+                const raw = await rawReq.arrayBuffer();
+                if (raw.byteLength > maxBodyBytes) {
+                    sendResponse(413, "Payload Too Large");
+                    return;
+                }
+                update = JSON.parse(new TextDecoder().decode(raw));
+            }
+            else if (rawReq.body && typeof rawReq.body === "object") {
+                update = rawReq.body;
+            }
+            else {
+                const chunks = [];
+                let totalBytes = 0;
+                for await (const chunk of rawReq) {
+                    const buffer = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+                    totalBytes += buffer.length;
+                    if (totalBytes > maxBodyBytes) {
+                        sendResponse(413, "Payload Too Large");
+                        return;
+                    }
+                    chunks.push(buffer);
+                }
+                const raw = Buffer.concat(chunks).toString("utf8");
+                update = JSON.parse(raw);
+            }
+            if (!Number.isInteger(update?.update_id)) {
+                sendResponse(400, "Bad Request");
+                return;
+            }
+            await bot.handleUpdate(update);
+            sendResponse(200, "OK");
+        }
+        catch (error) {
+            await options.onError?.(error);
+            sendResponse(500, "Internal Server Error");
+        }
+    };
+}
+function readHeader(req, name) {
+    const headers = req.headers;
+    if (!headers || typeof headers !== "object")
+        return "";
+    if (typeof headers.get === "function")
+        return headers.get(name) ?? "";
+    const value = headers[name];
+    return Array.isArray(value) ? value[0] ?? "" : value ?? "";
+}
 function secureEqual(left, right) {
     const leftBuffer = Buffer.from(left, "utf8");
     const rightBuffer = Buffer.from(right, "utf8");

package/docs/API.id.md

@@ -68,6 +68,7 @@ type BotStatus =
 | `transportOptions` | `Omit<FetchTransportOptions, "baseUrl">` | `{}` | Timeout, retry, backoff, jitter, headers, dan fetch implementation. |
 | `session` | `Storage<string, S>` | storage baru | Penyimpanan session berdasarkan kunci chat/user; dapat memakai adapter persistent. |
 | `services` | `Record<string, unknown>` | `{}` | Dependency/service yang tersedia melalui `ctx.services`. |
+| `branding` | `boolean` | `true` | Pengalaman startup terminal: efek ketik, glass progress bar, banner rainbow animasi `Tele Bibz`, dan baris update yang mudah dibaca. Hanya dirender pada TTY interaktif. |
 | `polling.timeout` | `number` | `30` | Long-poll timeout dalam detik untuk `getUpdates`. |
 | `polling.limit` | `number` | `100` | Jumlah maksimum update per request polling. |
 | `polling.allowedUpdates` | `string[]` | `[]` | Filter update Telegram. |
@@ -140,6 +141,30 @@ onRegex(expression: RegExp, handler: Middleware<Context<S>>): this
 
 Menangani message text menggunakan `RegExp`. Parameter route tidak diekstrak otomatis ke `ctx.params`; gunakan predicate atau middleware custom jika memerlukan ekstraksi.
 
+### `bot.on(filter, handler)`
+
+```ts
+on(filter: UpdateFilter | UpdateFilter[], handler: Middleware<Context<S>>): this
+```
+
+Mendaftarkan handler untuk tipe update, opsional dipersempit dengan field payload. Contoh: `"message"`, `"message:text"`, `"message:photo"`, `"edited_message"`, `"channel_post"`, `"callback_query"`, `"callback_query:data"`, `"inline_query"`, `"chat_member"`, `"message_reaction"`, atau array seperti `["message:text", "callback_query:data"]`. Tipe update tidak valid melempar `TypeError` saat registrasi.
+
+### `bot.hears(trigger, handler)`
+
+```ts
+hears(trigger: string | RegExp, handler: Middleware<Context<S>>): this
+```
+
+Menangani message text yang sama persis (string) atau yang cocok dengan `RegExp`.
+
+### `bot.catch(handler)`
+
+```ts
+catch(handler: (error: unknown, ctx: Context<S>) => void | Promise<void>): this
+```
+
+Mendaftarkan error boundary untuk handler update. Jika dipasang, kegagalan handler dicatat, dipancarkan sebagai `update:error`/`bot:error`, dan diteruskan ke handler ini alih-alih menolak `handleUpdate()` — webhook menjawab `200` dan polling berlanjut. Tanpa boundary, error dilempar ulang.
+
 ### `bot.usePlugin(plugin)`
 
 ```ts
@@ -633,6 +658,22 @@ new Context<S>(options: ContextOptions<S>): Context<S>
 | `send` | `send(text, extra?): Promise<Message>` | Mengirim message ke chat update tanpa reply reference. |
 | `edit` | `edit(text, extra?): Promise<Message \| true>` | Mengedit message update menggunakan `editMessageText`. |
 | `delete` | `delete(): Promise<true>` | Menghapus message update. |
+| `replyWithHTML` | `replyWithHTML(text, extra?): Promise<Message>` | Membalas dengan `parse_mode: "HTML"`. |
+| `replyWithMarkdown` | `replyWithMarkdown(text, extra?): Promise<Message>` | Membalas dengan `parse_mode: "MarkdownV2"`. |
+| `replyWithPhoto` | `replyWithPhoto(photo, extra?): Promise<Message>` | Mengirim `sendPhoto` dengan quote-reply otomatis. |
+| `replyWithDocument` | `replyWithDocument(document, extra?): Promise<Message>` | Mengirim `sendDocument` dengan quote-reply otomatis. |
+| `replyWithAudio` | `replyWithAudio(audio, extra?): Promise<Message>` | Mengirim `sendAudio` dengan quote-reply otomatis. |
+| `replyWithVideo` | `replyWithVideo(video, extra?): Promise<Message>` | Mengirim `sendVideo` dengan quote-reply otomatis. |
+| `replyWithVoice` | `replyWithVoice(voice, extra?): Promise<Message>` | Mengirim `sendVoice` dengan quote-reply otomatis. |
+| `replyWithAnimation` | `replyWithAnimation(animation, extra?): Promise<Message>` | Mengirim `sendAnimation` dengan quote-reply otomatis. |
+| `replyWithVideoNote` | `replyWithVideoNote(videoNote, extra?): Promise<Message>` | Mengirim `sendVideoNote` dengan quote-reply otomatis. |
+| `replyWithSticker` | `replyWithSticker(sticker, extra?): Promise<Message>` | Mengirim `sendSticker` dengan quote-reply otomatis. |
+| `replyWithMediaGroup` | `replyWithMediaGroup(media, extra?): Promise<Message[]>` | Mengirim album via `sendMediaGroup` dengan quote-reply otomatis. |
+| `replyWithLocation` | `replyWithLocation(latitude, longitude, extra?): Promise<Message>` | Mengirim `sendLocation` dengan quote-reply otomatis. |
+| `replyWithVenue` | `replyWithVenue(latitude, longitude, title, address, extra?): Promise<Message>` | Mengirim `sendVenue` dengan quote-reply otomatis. |
+| `replyWithContact` | `replyWithContact(phoneNumber, firstName, extra?): Promise<Message>` | Mengirim `sendContact` dengan quote-reply otomatis. |
+| `replyWithPoll` | `replyWithPoll(question, options, extra?): Promise<Message>` | Mengirim `sendPoll` dengan quote-reply otomatis. |
+| `replyWithDice` | `replyWithDice(emoji?, extra?): Promise<Message>` | Mengirim `sendDice` dengan quote-reply otomatis. |
 | `copy` | `copy(fromChatId, messageId, extra?): Promise<unknown>` | Memanggil `copyMessage` ke chat context. |
 | `forward` | `forward(fromChatId, messageId, extra?): Promise<Message>` | Memanggil `forwardMessage` ke chat context. |
 | `pin` | `pin(messageId?, extra?): Promise<true>` | Memanggil `pinChatMessage`, default message id dari context. |
@@ -645,7 +686,7 @@ new Context<S>(options: ContextOptions<S>): Context<S>
 | `getFile` | `getFile(fileId): Promise<unknown>` | Mengambil file berdasarkan id. |
 | `withReplyMarkup` | `withReplyMarkup(markup): this` | Menyimpan markup di `ctx.state.reply_markup` dan mengembalikan context. Metode ini tidak otomatis mengirim message. |
 
-`reply`, `send`, `getChat`, dan beberapa helper lain melempar error ketika update tidak memiliki chat yang diperlukan. `edit` dan `delete` membutuhkan chat serta message.
+Semua pengirim `replyWith*` menerima parameter native Telegram sebagai `extra` dan otomatis me-quote message yang masuk. `reply_parameters` pada `extra` digabung dengan `message_id` otomatis, bukan menggantikannya. `reply`, `send`, `getChat`, dan beberapa helper lain melempar error ketika update tidak memiliki chat yang diperlukan. `edit` dan `delete` membutuhkan chat serta message.
 
 ---
 
@@ -1263,7 +1304,20 @@ new Menu(id: string): Menu
 
 ## 12. Logging Terminal
 
-This package starts directly after Telegram API connectivity is established. The terminal prints a boxed telebibz attribution, an animated startup status when attached to a TTY, and structured colorful logs for lifecycle, API, polling, webhook, and update events. Set logger format to `json` for machine ingestion.
+Saat stdout adalah TTY interaktif, setiap `bot.start()` / `bot.launch()` 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>`.
+
+Setiap update yang ditangani bot dicatat dalam baris yang mudah dibaca:
+
+```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
+```
+
+Teks pesan/command dibatasi 50 karakter; data tombol callback ditampilkan penuh. Error dicetak merah lengkap dengan stack. Nonaktifkan dengan `branding: false` pada `Bot`, atau set `logger.format: "json"` untuk log terstruktur — pada mode itu update masuk dikeluarkan sebagai entry `update.received`. Stdout non-interaktif (pipe, Docker, CI) otomatis fallback ke teks polos tanpa animasi.
+
+Helper branding tambahan yang diekspor untuk aplikasi: `runStartupSequence()`, `startTeleBibzBanner()`, `printTeleBibzBanner()`, `paintRainbow()`, dan `printStatusLine()`.
 
 ## 13. Utilitas Teks
 
@@ -1691,7 +1745,7 @@ Package memvendorkan declaration Telegram berlisensi MIT dan mengeksposnya sebag
 
 ## 19. Kompatibilitas dan batasan yang perlu diketahui
 
-Perpustakaan menargetkan Node.js `>=20`, menggunakan ESM sebagai module utama, serta menyediakan build CommonJS. Webhook membutuhkan runtime yang menyediakan Web `Request`, `Response`, `Headers`, `FormData`, `Blob`, dan `AbortController`; Node.js modern menyediakannya secara native.
+Perpustakaan menargetkan Node.js `>=22`, menggunakan ESM sebagai module utama, serta menyediakan build CommonJS. Webhook membutuhkan runtime yang menyediakan Web `Request`, `Response`, `Headers`, `FormData`, `Blob`, dan `AbortController`; Node.js modern menyediakannya secara native.
 
 Daftar method yang dihasilkan API dan peta method API bukanlah hal yang sama. `TelegramMethodName` mencakup 184 nama runtime, tetapi `TelegramMethodMap` hanya memiliki parameter/hasil yang bertipe khusus untuk subset yang tercantum pada bagian API client. Untuk method lain, gunakan `api.raw()` atau tambahkan deklarasi tipe di sisi aplikasi.
 

package/docs/API.md

@@ -67,6 +67,7 @@ type BotStatus =
 | `transportOptions` | `Omit<FetchTransportOptions, "baseUrl">` | `{}` | Timeout, retry, backoff, jitter, headers, and fetch implementation. |
 | `session` | `Storage<string, S>` | new storage | Session storage keyed by chat/user; any storage adapter may be used. |
 | `services` | `Record<string, unknown>` | `{}` | Dependencies/services available via `ctx.services`. |
+| `branding` | `boolean` | `true` | Terminal startup experience: typing effect, glass progress bar, animated rainbow "Tele Bibz" banner, and human-readable update lines. Only renders on an interactive TTY. |
 | `polling.timeout` | `number` | `30` | Long-poll timeout in seconds for `getUpdates`. |
 | `polling.limit` | `number` | `100` | Maximum number of updates per polling request. |
 | `polling.allowedUpdates` | `string[]` | `[]` | Telegram update filters. |
@@ -139,6 +140,30 @@ onRegex(expression: RegExp, handler: Middleware<Context<S>>): this
 
 Handles message text using a `RegExp`. Route parameters are not automatically extracted into `ctx.params`; use a predicate or custom middleware if extraction is needed.
 
+### `bot.on(filter, handler)`
+
+```ts
+on(filter: UpdateFilter | UpdateFilter[], handler: Middleware<Context<S>>): this
+```
+
+Registers a handler for update types, optionally narrowed by a payload field. Examples: `"message"`, `"message:text"`, `"message:photo"`, `"edited_message"`, `"channel_post"`, `"callback_query"`, `"callback_query:data"`, `"inline_query"`, `"chat_member"`, `"message_reaction"`, or an array such as `["message:text", "callback_query:data"]`. Invalid update types throw a `TypeError` at registration time.
+
+### `bot.hears(trigger, handler)`
+
+```ts
+hears(trigger: string | RegExp, handler: Middleware<Context<S>>): this
+```
+
+Handles exact message text (string) or message text matching a `RegExp`.
+
+### `bot.catch(handler)`
+
+```ts
+catch(handler: (error: unknown, ctx: Context<S>) => void | Promise<void>): this
+```
+
+Registers the error boundary for update handlers. When set, a handler failure is logged, emitted as `update:error`/`bot:error`, and passed to this handler instead of rejecting `handleUpdate()` — webhook requests answer `200` and polling continues. Without a boundary, the error is rethrown.
+
 ### `bot.usePlugin(plugin)`
 
 ```ts
@@ -650,6 +675,23 @@ new Context<S>(options: ContextOptions<S>): Context<S>
 | `send` | `send(text, extra?): Promise<Message>` | Sends a message to the update chat without a reply reference. |
 | `edit` | `edit(text, extra?): Promise<Message \| true>` | Edits the update message using `editMessageText`. |
 | `delete` | `delete(): Promise<true>` | Deletes the update message. |
+| `replyWithHTML` | `replyWithHTML(text, extra?): Promise<Message>` | Replies with `parse_mode: "HTML"`. |
+| `replyWithMarkdown` | `replyWithMarkdown(text, extra?): Promise<Message>` | Replies with `parse_mode: "MarkdownV2"`. |
+| `replyWithPhoto` | `replyWithPhoto(photo, extra?): Promise<Message>` | Sends `sendPhoto` with automatic quote-reply. |
+| `replyWithDocument` | `replyWithDocument(document, extra?): Promise<Message>` | Sends `sendDocument` with automatic quote-reply. |
+| `replyWithAudio` | `replyWithAudio(audio, extra?): Promise<Message>` | Sends `sendAudio` with automatic quote-reply. |
+| `replyWithVideo` | `replyWithVideo(video, extra?): Promise<Message>` | Sends `sendVideo` with automatic quote-reply. |
+| `replyWithVoice` | `replyWithVoice(voice, extra?): Promise<Message>` | Sends `sendVoice` with automatic quote-reply. |
+| `replyWithAnimation` | `replyWithAnimation(animation, extra?): Promise<Message>` | Sends `sendAnimation` with automatic quote-reply. |
+| `replyWithVideoNote` | `replyWithVideoNote(videoNote, extra?): Promise<Message>` | Sends `sendVideoNote` with automatic quote-reply. |
+| `replyWithSticker` | `replyWithSticker(sticker, extra?): Promise<Message>` | Sends `sendSticker` with automatic quote-reply. |
+| `replyWithMediaGroup` | `replyWithMediaGroup(media, extra?): Promise<Message[]>` | Sends an album via `sendMediaGroup` with automatic quote-reply. |
+| `replyWithLocation` | `replyWithLocation(latitude, longitude, extra?): Promise<Message>` | Sends `sendLocation` with automatic quote-reply. |
+| `replyWithVenue` | `replyWithVenue(latitude, longitude, title, address, extra?): Promise<Message>` | Sends `sendVenue` with automatic quote-reply. |
+| `replyWithContact` | `replyWithContact(phoneNumber, firstName, extra?): Promise<Message>` | Sends `sendContact` with automatic quote-reply. |
+| `replyWithPoll` | `replyWithPoll(question, options, extra?): Promise<Message>` | Sends `sendPoll` with automatic quote-reply. |
+| `replyWithDice` | `replyWithDice(emoji?, extra?): Promise<Message>` | Sends `sendDice` with automatic quote-reply. |
+| `sendChatAction` | `sendChatAction(action, extra?): Promise<true>` | Sends a chat action such as `typing`. |
 | `copy` | `copy(fromChatId, messageId, extra?): Promise<unknown>` | Calls `copyMessage` to the context chat. |
 | `forward` | `forward(fromChatId, messageId, extra?): Promise<Message>` | Calls `forwardMessage` to the context chat. |
 | `pin` | `pin(messageId?, extra?): Promise<true>` | Calls `pinChatMessage`; defaults to the context message id. |
@@ -662,7 +704,7 @@ new Context<S>(options: ContextOptions<S>): Context<S>
 | `getFile` | `getFile(fileId): Promise<unknown>` | Fetches a file by id. |
 | `withReplyMarkup` | `withReplyMarkup(markup): this` | Stores markup in `ctx.state.reply_markup` and returns the context. This method does not automatically send a message. |
 
-`reply`, `send`, `getChat`, and some other helpers throw an error when the update does not have the required chat. `edit` and `delete` require both chat and message.
+All `replyWith*` senders accept the native Telegram parameters as `extra` and automatically quote the incoming message. Passing `reply_parameters` in `extra` merges with the automatic `message_id` instead of replacing it. `reply`, `send`, `getChat`, and some other helpers throw an error when the update does not have the required chat. `edit` and `delete` require both chat and message.
 
 ---
 
@@ -1281,11 +1323,23 @@ new Menu(id: string): Menu
 
 ## 12. Terminal Logging
 
-The CLI prints a colored Unicode attribution box and an animated startup status when attached to a TTY. The default logger emits compact, readable terminal lines with colored levels and structured context. Use `format: "json"` for machine ingestion, `includeUpdateContent: true` when message text or callback data is explicitly required, and a custom `sink` for application monitoring.
+When stdout is an interactive TTY, every `bot.start()` / `bot.launch()` 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>`.
+
+Every update the bot handles is logged on a human-readable line:
+
+```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
+```
+
+Message and command text is truncated to 50 characters; callback button data is shown in full. Errors are printed in red and include the full stack. Pass `branding: false` to `Bot` to disable the startup sequence, and set `logger.format: "json"` for machine ingestion — in that mode incoming updates are emitted as structured `update.received` entries. Non-interactive stdout (pipes, Docker, CI) automatically falls back to plain, uncolored output without animations.
 
 ```ts
 const bot = new Bot({
   token: process.env.TELEGRAM_BOT_TOKEN!,
+  branding: false, // turn off the startup sequence
   logger: {
     level: "debug",
     format: "pretty",
@@ -1295,6 +1349,8 @@ const bot = new Bot({
 });
 ```
 
+Additional branding helpers exported for applications: `runStartupSequence()`, `startTeleBibzBanner()`, `printTeleBibzBanner()`, `paintRainbow()`, and `printStatusLine()`.
+
 ---
 
 ## 13. Text Utilities
@@ -1723,7 +1779,7 @@ The package vendors MIT-licensed Telegram declarations and exposes them as type-
 ---
 ## 19. Compatibility and limitations to be aware of
 
-The library targets Node.js `>=20`, uses ESM as the primary module, and also provides a CommonJS build. Webhooks require a runtime that provides Web `Request`, `Response`, `Headers`, `FormData`, `Blob`, and `AbortController`; modern Node.js provides these natively.
+The library targets Node.js `>=22`, uses ESM as the primary module, and also provides a CommonJS build. Webhooks require a runtime that provides Web `Request`, `Response`, `Headers`, `FormData`, `Blob`, and `AbortController`; modern Node.js provides these natively.
 
 The list of generated API methods and the API method map are not the same. `TelegramMethodName` includes 184 runtime names, but `TelegramMethodMap` only has specially-typed parameters/results for the subset listed in the API client section. For other methods, use `api.raw()` or add a type declaration on the application side.
 

package/docs/API.zh-CN.md

@@ -68,6 +68,7 @@ type BotStatus =
 | `transportOptions` | `Omit<FetchTransportOptions, "baseUrl">` | `{}` | 超时、重试、退避、jitter、headers 和 fetch 实现。 |
 | `session` | `Storage<string, S>` | 新的存储 | 基于 chat/user key 的会话存储，可使用持久化适配器。 |
 | `services` | `Record<string, unknown>` | `{}` | 通过 `ctx.services` 可用的依赖/服务。 |
+| `branding` | `boolean` | `true` | 终端启动体验：打字效果、glass 进度条、动画彩虹 `Tele Bibz` 横幅以及易读的 update 日志行。仅在交互式 TTY 上渲染。 |
 | `polling.timeout` | `number` | `30` | 用于 `getUpdates` 的长轮询超时（秒）。 |
 | `polling.limit` | `number` | `100` | 每次轮询请求的最大 update 数量。 |
 | `polling.allowedUpdates` | `string[]` | `[]` | Telegram 更新过滤器。 |
@@ -140,6 +141,30 @@ onRegex(expression: RegExp, handler: Middleware<Context<S>>): this
 
 使用 `RegExp` 处理消息文本。路由参数不会自动提取到 `ctx.params`；如需提取请使用 predicate 或自定义 middleware。
 
+### `bot.on(filter, handler)`
+
+```ts
+on(filter: UpdateFilter | UpdateFilter[], handler: Middleware<Context<S>>): this
+```
+
+按更新类型注册处理器，并可用 payload 字段收窄。示例：`"message"`、`"message:text"`、`"message:photo"`、`"edited_message"`、`"channel_post"`、`"callback_query"`、`"callback_query:data"`、`"inline_query"`、`"chat_member"`、`"message_reaction"`，或数组如 `["message:text", "callback_query:data"]`。无效的更新类型会在注册时抛出 `TypeError`。
+
+### `bot.hears(trigger, handler)`
+
+```ts
+hears(trigger: string | RegExp, handler: Middleware<Context<S>>): this
+```
+
+处理完全匹配的文本（string）或匹配 `RegExp` 的消息文本。
+
+### `bot.catch(handler)`
+
+```ts
+catch(handler: (error: unknown, ctx: Context<S>) => void | Promise<void>): this
+```
+
+注册更新处理器的错误边界。设置后，处理器失败会被记录、以 `update:error`/`bot:error` 事件发出，并转发给该 handler，而不是让 `handleUpdate()` 拒绝 —— webhook 返回 `200`，轮询继续。未设置边界时错误会被重新抛出。
+
 ### `bot.usePlugin(plugin)`
 
 ```ts
@@ -633,6 +658,22 @@ new Context<S>(options: ContextOptions<S>): Context<S>
 | `send` | `send(text, extra?): Promise<Message>` | 向更新的聊天发送消息，不带回复引用. |
 | `edit` | `edit(text, extra?): Promise<Message \| true>` | 使用 `editMessageText` 编辑更新的消息. |
 | `delete` | `delete(): Promise<true>` | 删除更新的消息. |
+| `replyWithHTML` | `replyWithHTML(text, extra?): Promise<Message>` | 以 `parse_mode: "HTML"` 回复. |
+| `replyWithMarkdown` | `replyWithMarkdown(text, extra?): Promise<Message>` | 以 `parse_mode: "MarkdownV2"` 回复. |
+| `replyWithPhoto` | `replyWithPhoto(photo, extra?): Promise<Message>` | 发送 `sendPhoto`，自动引用回复. |
+| `replyWithDocument` | `replyWithDocument(document, extra?): Promise<Message>` | 发送 `sendDocument`，自动引用回复. |
+| `replyWithAudio` | `replyWithAudio(audio, extra?): Promise<Message>` | 发送 `sendAudio`，自动引用回复. |
+| `replyWithVideo` | `replyWithVideo(video, extra?): Promise<Message>` | 发送 `sendVideo`，自动引用回复. |
+| `replyWithVoice` | `replyWithVoice(voice, extra?): Promise<Message>` | 发送 `sendVoice`，自动引用回复. |
+| `replyWithAnimation` | `replyWithAnimation(animation, extra?): Promise<Message>` | 发送 `sendAnimation`，自动引用回复. |
+| `replyWithVideoNote` | `replyWithVideoNote(videoNote, extra?): Promise<Message>` | 发送 `sendVideoNote`，自动引用回复. |
+| `replyWithSticker` | `replyWithSticker(sticker, extra?): Promise<Message>` | 发送 `sendSticker`，自动引用回复. |
+| `replyWithMediaGroup` | `replyWithMediaGroup(media, extra?): Promise<Message[]>` | 通过 `sendMediaGroup` 发送相册，自动引用回复. |
+| `replyWithLocation` | `replyWithLocation(latitude, longitude, extra?): Promise<Message>` | 发送 `sendLocation`，自动引用回复. |
+| `replyWithVenue` | `replyWithVenue(latitude, longitude, title, address, extra?): Promise<Message>` | 发送 `sendVenue`，自动引用回复. |
+| `replyWithContact` | `replyWithContact(phoneNumber, firstName, extra?): Promise<Message>` | 发送 `sendContact`，自动引用回复. |
+| `replyWithPoll` | `replyWithPoll(question, options, extra?): Promise<Message>` | 发送 `sendPoll`，自动引用回复. |
+| `replyWithDice` | `replyWithDice(emoji?, extra?): Promise<Message>` | 发送 `sendDice`，自动引用回复. |
 | `copy` | `copy(fromChatId, messageId, extra?): Promise<unknown>` | 向上下文聊天调用 `copyMessage`. |
 | `forward` | `forward(fromChatId, messageId, extra?): Promise<Message>` | 向上下文聊天调用 `forwardMessage`. |
 | `pin` | `pin(messageId?, extra?): Promise<true>` | 调用 `pinChatMessage`，默认消息 ID 来自上下文. |
@@ -1257,7 +1298,20 @@ new Menu(id: string): Menu
 
 ## 12. Terminal Logging
 
-This package starts directly after Telegram API connectivity is established. The terminal prints a boxed telebibz attribution, an animated startup status when attached to a TTY, and structured colorful logs for lifecycle, API, polling, webhook, and update events. Set logger format to `json` for machine ingestion.
+当 stdout 是交互式 TTY 时，每次 `bot.start()` / `bot.launch()` 都会播放启动序列：`Installing Dependencies......` 打字效果、带扫过高光的 glass 进度条，以及动画彩虹 ASCII 横幅 `Tele Bibz`（figlet `Speed` 字体）——持续流动直到 bot 连接成功，随后定格为 `✓ Connected as @<username>`。
+
+bot 处理的每条 update 都会以易读的行格式记录：
+
+```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
+```
+
+普通消息与命令文本截断为 50 个字符；回调按钮数据完整显示。错误以红色打印并附带完整堆栈。向 `Bot` 传入 `branding: false` 可关闭启动序列；设置 `logger.format: "json"` 时，进入的 update 会作为结构化 `update.received` entry 输出。非交互 stdout（管道、Docker、CI）自动回退为无动画的纯文本。
+
+面向应用导出的附加 branding helper：`runStartupSequence()`、`startTeleBibzBanner()`、`printTeleBibzBanner()`、`paintRainbow()` 和 `printStatusLine()`。
 
 ## 13. 文本工具
 
@@ -1685,7 +1739,7 @@ Package 内置 MIT 许可的 Telegram declaration，并通过 type-only export
 
 ## 19. 兼容性和需要注意的限制
 
-Library menargetkan Node.js `>=20`，使用 ESM 作为主要模块，并提供 CommonJS 构建。Webhook 需要运行时提供 Web `Request`、`Response`、`Headers`、`FormData`、`Blob` 和 `AbortController`；现代 Node.js 原生提供了这些。
+本库面向 Node.js `>=22`，使用 ESM 作为主要模块，并提供 CommonJS 构建。Webhook 需要运行时提供 Web `Request`、`Response`、`Headers`、`FormData`、`Blob` 和 `AbortController`；现代 Node.js 原生提供了这些。
 
 API 生成的方法列表（generated method list）和 API 方法映射（API method map）并不相同。`TelegramMethodName` 包含 184 个运行时名称，但 `TelegramMethodMap` 仅对 API 客户端部分列出的子集提供了带类型的参数/结果。对于其他方法，使用 `api.raw()` 或在应用端添加类型声明。
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xbibzlibrary/telebibz",
-  "version": "0.1.19",
-  "description": "Production-grade Telegram Bot framework for Node.js and TypeScript with typed API, routing, webhooks, keyboards, conversations, plugins, queues, and colorful CLI logs.",
+  "version": "0.2.1",
+  "description": "Telegram Bot framework for Node.js and TypeScript with a typed API client, routing, middleware, webhooks, keyboards, conversations, plugins, queues, and a polished terminal experience.",
   "keywords": [
     "telegram",
     "telegram-bot",
@@ -32,7 +32,7 @@
     "url": "https://github.com/XbibzOfficial777/telebibz/issues"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "scripts": {
     "generate": "node scripts/generate-api.mjs",