@xbibzlibrary/telebibz 0.1.19 → 0.3.1

package/CHANGELOG.md

@@ -1,20 +1,54 @@
 # Changelog
 
-## Unreleased
+## 0.3.0 — 2026-08-29
+
+### Added
+
+- Concurrent update processing built for 1000+ message bursts: updates run in parallel across chats while staying ordered within a single chat, so a slow handler never blocks other chats, sessions never lose writes, and a concurrent burst triggers exactly one `getMe` initialization. `bot.handleUpdates(updates)` processes a whole batch at once and the polling loop uses it for every `getUpdates` batch. Cap simultaneous work with `updates: { concurrency }` (default `Infinity`).
+- `bot.broadcast(chatIds, send, options)` for sending to 1000+ users at once: every chat is attempted immediately (no proactive cooldown, configurable `concurrency`), 429 answers are retried automatically after exactly the `retry_after` delay Telegram ordered, and the returned `BroadcastReport` lists delivered/failed counts with per-chat failure details plus `onProgress` streaming.
+- `FetchTransport` flood gate (`floodGate`, default on): when Telegram answers 429, new requests wait out the `retry_after` window Telegram ordered — the only delay ever introduced, never a proactive cooldown.
+- `Limiter` and `mapWithConcurrency` concurrency primitives (promise semaphore and ordered concurrent mapping) exported for applications.
 
 ### Fixed
 
-- Callback-query contexts now resolve `message` and `chat` from `callback_query.message`, so `ctx.reply()`, `ctx.edit()`, and `ctx.delete()` work for button callbacks.
-- Router matching is first-match by default; explicit `matchMode: "all"` preserves deliberate fan-out without accidental double replies.
-- Polling isolates handler failures per update, continues the remainder of a batch, emits `update:error`, and uses abortable reconnect backoff.
-- Regex matchers reset `lastIndex` before reuse.
+- A burst of concurrent updates no longer races `init()`: initialization is memoized, so 1000 simultaneous updates trigger exactly one `getMe` call instead of one per update.
+- Session writes are no longer lost when one chat sends several messages at once: same-chat updates are serialized in arrival order, so each update reads the session state written by the previous one.
+
+## 0.2.1 — 2026-08-29
+
+### Breaking
+
+- Node.js 22 is now the minimum supported runtime (`engines.node: ">=22"`); CI tests Node 22 and 24. The TypeScript target moves to ES2023.
 
 ### Added
 
-- JSON-file, Redis, SQL-driver, Mongo-driver, and persistent approval storage adapters.
+- `bot.on(filter, handler)` update-type filters with payload narrowing: `bot.on("message:photo")`, `bot.on("callback_query:data")`, or an array like `["message:text", "callback_query:data"]`. Invalid filters throw at registration time.
+- `bot.hears(trigger, handler)` for exact text or `RegExp` message matching.
+- `bot.catch(handler)` error boundary: handler failures are logged, emitted as `update:error`/`bot:error`, and routed to the handler instead of rejecting `handleUpdate()`; webhooks answer `200` and polling continues.
+- Extended context senders with automatic quote-reply: `replyWithAnimation`, `replyWithVideoNote`, `replyWithSticker`, `replyWithMediaGroup`, `replyWithLocation`, `replyWithVenue`, `replyWithContact`, `replyWithPoll`, and `replyWithDice`.
+- Animated terminal startup experience (on by default, `branding: false` to disable): 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 flows until the bot connects and then freezes with `✓ Connected as @<username>`.
+- Human-readable incoming update logs: `[ => ] Message From {id} {nickname} {dd/mm/yyyy} {hh:mm:ss}` plus an indented content line. Regular message/command text is truncated to 50 characters; callback button data is shown in full. Errors print in red with the full stack. Non-interactive stdout falls back to plain output; `logger.format: "json"` emits structured `update.received` entries instead.
+- Branding helpers exported for applications: `runStartupSequence()`, `startTeleBibzBanner()`, `printTeleBibzBanner()`, `paintRainbow()`, `printStatusLine()`, plus `Logger.incoming()` and `describeIncomingUpdate()`.
+- `TransportRequest.timeoutMs` for per-request timeouts, honored by `FetchTransport` and `ApiClient.request()`.
 - Storage-backed conversations, full five-field cron parsing, scheduler error hooks, permission-aware menus, `MenuController`, Web App init-data validation, PaymentsClient, and vendored Telegram declarations.
-- Callback-update test fixtures and expanded failure-path/regression coverage.
-- Code of Conduct, Contributing Guide, Contribution Rules, Governance, Support Policy, expanded Security Policy, third-party Notice, CODEOWNERS, Dependabot configuration, and complete GitHub issue/PR templates.
+
+### Fixed
+
+- Restored a green build: `npm run typecheck`, `lint`, `test:types`, `test:examples`, and `build` failed under TypeScript 5.9 with `exactOptionalPropertyTypes` (`Context.me` assignment, `RoutableContext.me` index-signature constraint, and an invalid `webhookCallback` cast).
+- The published `telebibz` CLI binary crashed with `MODULE_NOT_FOUND` because `bin/telebibz.mjs` imported `../dist/cli.js`; the build emits `dist/src/cli.js`. `release:check` now verifies every bin import resolves inside the tarball.
+- Long polling no longer races its own transport timeout: `getUpdates` now uses a per-request timeout of the polling timeout plus a 10-second buffer instead of the flat 30s transport default, which aborted healthy connections the moment Telegram responded.
+- `bot.stop()` now aborts the in-flight long-poll request (the polling `AbortSignal` is passed through to the transport), so shutdown no longer blocks for up to the full polling timeout.
+- `JsonFileStorage` now persists `expiresAt` metadata, so values written with a TTL no longer silently become permanent after a restart.
+- `webhookCallback` now actually supports Koa-style contexts (`status`/`body`), reads secret-token headers from fetch `Request` header maps, and parses bodies from web-standard `Request` objects instead of misreading their `ReadableStream` `body` as a pre-parsed update.
+- Passing `reply_parameters` in `extra` no longer discards the automatic quote `message_id`; user options now merge with it across all `reply`/`replyWith*` senders.
+- Plugins install exactly once; `bot.restart()` no longer double-registers plugin middleware and routes.
+- Callback-query contexts resolve `message` and `chat` from `callback_query.message`, so `ctx.reply()`, `ctx.edit()`, and `ctx.delete()` work for button callbacks.
+- Router matching is first-match by default; explicit `matchMode: "all"` preserves deliberate fan-out without accidental double replies.
+- Polling isolates handler failures per update, continues the remainder of a batch, emits `update:error`, and uses abortable reconnect backoff.
+
+### Removed
+
+- Development report files (`TELEBIBZ_FINAL_REPORT.md`, `TELEBIBZ_E2E_REPORT.md`, `NPM_RELEASE_REPORT.md`) and the feature-matrix row for an approval gate that was never part of the source tree.
 
 ## 0.1.2 — 2026-08-19
 

package/CONTRIBUTING.md

@@ -10,7 +10,7 @@ Check existing issues and pull requests before opening a new one. For a defect,
 
 ## Local setup
 
-The project requires Node.js `>=20` and uses npm for release-compatible commands. Install dependencies and run the baseline checks:
+The project requires Node.js `>=22` and uses npm for release-compatible commands. Install dependencies and run the baseline checks:
 
 ```bash
 npm ci
@@ -32,7 +32,7 @@ Create a focused branch from `main`. Keep unrelated refactors out of a feature o
 
 ## Implementation expectations
 
-Public behavior must be implemented in TypeScript with strict typing. Do not add fake responses, silent stubs, undocumented breaking behavior, or untested branches. Preserve ESM and CommonJS builds, zero runtime vendor dependencies in the core package, Node.js `>=20` compatibility, and the existing package export map.
+Public behavior must be implemented in TypeScript with strict typing. Do not add fake responses, silent stubs, undocumented breaking behavior, or untested branches. Preserve ESM and CommonJS builds, zero runtime vendor dependencies in the core package, Node.js `>=22` compatibility, and the existing package export map.
 
 Changes to routing, context, lifecycle, transport, storage, queue, scheduler, approval, generated API declarations, or release automation require regression tests. Changes to a public function, class, method, option, error, event, or generated method require a corresponding API documentation update. Changes to examples require `npm run test:examples` and must use placeholders instead of credentials. Changes that affect package contents must pass `release:check` and `npm pack --dry-run`.
 

package/README.id.md

@@ -27,7 +27,7 @@ Showcase komunitas: [SHOWCASE.md](SHOWCASE.md)
 npm install @xbibzlibrary/telebibz
 ```
 
-Node.js **20 atau lebih baru** diperlukan.
+Node.js **22 atau lebih baru** diperlukan.
 
 ## Bot sederhana
 
@@ -67,9 +67,13 @@ bot.use(async (ctx, next) => {
 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.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."); });
 ```
 
-Router mendukung command, text, regex, pola callback, predikat kustom, router bersarang, middleware per rute, dan prioritas rute.
+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.
 
 ## Telegram API
 
@@ -103,7 +107,7 @@ Builder hanya menghasilkan payload keyboard native Telegram. UI HTML/CSS memerlu
 
 ## Startup dan log 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.
+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.
 
 ## Webhook
 
@@ -118,13 +122,47 @@ const handler = createWebhookHandler(bot, {
 
 `createWebhookHandler` menerima Request Web standar dan menghasilkan Response. Secret token, ukuran body, parsing JSON, dan penanganan update duplikat diverifikasi oleh handler.
 
+## Update beban tinggi dan broadcast
+
+telebibz dibangun untuk burst 1000+ pesan tanpa cooldown buatan:
+
+- **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`.
+- **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.
+- **Broadcast ke 1000+ user sekaligus.** `bot.broadcast()` langsung mencoba semua chat, me-retry 429 sesuai `retry_after` dari Telegram sendiri, dan mengembalikan laporan lengkap.
+
+```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`);
+```
+
+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.
+
 ## State, queue, scheduler, dan cache
 
 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.
 
+## Pengalaman terminal
+
+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>`.
+
+Setelah itu, setiap update yang masuk ditampilkan dalam baris log yang mudah dibaca, dan error otomatis berwarna merah lengkap dengan stack-nya:
+
+```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 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.
+
 ## CLI
 
-Setiap command `telebibz` menampilkan kotak branding Unicode berwarna dengan tulisan `Library Bot Telegram By @xbibzofficial`. CLI tidak mencetak target developer.
+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.
 
 ```bash
 npx telebibz init my-bot
@@ -136,8 +174,9 @@ npx telebibz test
 Branding terminal juga dapat dicetak dari aplikasi:
 
 ```ts
-import { printTerminalBranding } from "@xbibzlibrary/telebibz";
+import { printTeleBibzBanner, printTerminalBranding } from "@xbibzlibrary/telebibz";
 
+printTeleBibzBanner({ subtitle: "Bot saya" });
 printTerminalBranding();
 ```
 

package/README.md

@@ -7,7 +7,7 @@
 [![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 full-scale 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.
+**`@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.
 
 ## Documentation languages
 
@@ -29,7 +29,7 @@ Community showcase: [SHOWCASE.md](SHOWCASE.md)
 npm install @xbibzlibrary/telebibz
 ```
 
-Node.js **20 or newer** is required.
+Node.js **22 or newer** is required.
 
 ## Minimal bot
 
@@ -69,9 +69,13 @@ bot.use(async (ctx, next) => {
 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.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."); });
 ```
 
-The router supports commands, exact text, regular expressions, callback patterns, custom predicates, nested routers, per-route middleware, and route priority.
+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.
 
 ## Telegram API
 
@@ -103,7 +107,7 @@ Builders produce native Telegram keyboard payloads. HTML/CSS interfaces require
 
 ## Colorful runtime logging
 
-Runtime logging is enabled by default. The CLI prints a colored boxed attribution, an animated startup status on TTY terminals, and compact structured lines for lifecycle, API, polling, webhook, and update events. Log levels are `silent`, `error`, `warn`, `info`, `debug`, and `trace`; sensitive values are redacted. Use `format: "json"` for machine ingestion and `includeUpdateContent: true` only when message text or callback data is explicitly required.
+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.
 
 ```ts
 const bot = new Bot({
@@ -146,13 +150,47 @@ const handler = createWebhookHandler(bot, {
 
 `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()`.
 
+## High-load updates and broadcast
+
+telebibz is built for bursts of 1000+ messages with no artificial cooldown:
+
+- **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.
+- **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.
+- **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.
+
+```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`);
+```
+
+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.
+
 ## State, queue, scheduler, and cache
 
 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.
 
+## Terminal experience
+
+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>`.
+
+Afterwards, every incoming update is logged on a human-readable line, and errors are printed in red with the full stack:
+
+```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. 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.
+
 ## CLI
 
-Every `telebibz` CLI command starts with a colored Unicode branding box containing `Library Bot Telegram By @xbibzofficial`. Startup animation automatically falls back to clean static output when stdout is not a TTY.
+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.
 
 ```bash
 npm start
@@ -165,8 +203,9 @@ npx telebibz test
 Applications can print the same terminal branding explicitly:
 
 ```ts
-import { printTerminalBranding } from "@xbibzlibrary/telebibz";
+import { printTeleBibzBanner, printTerminalBranding } from "@xbibzlibrary/telebibz";
 
+printTeleBibzBanner({ subtitle: "My bot" });
 printTerminalBranding();
 ```
 

package/README.zh-CN.md

@@ -27,7 +27,7 @@ GitHub Packages 指南：[English](docs/GITHUB_PACKAGES.md) · [Bahasa Indonesia
 npm install @xbibzlibrary/telebibz
 ```
 
-需要 Node.js **20 或更高版本**。
+需要 Node.js **22 或更高版本**。
 
 ## 简单机器人
 
@@ -67,9 +67,13 @@ bot.use(async (ctx, next) => {
 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.on("message:photo", async (ctx) => { await ctx.reply("照片不错。"); });
+bot.on(["message:text", "callback_query:data"], async (ctx) => { await ctx.reply("收到。"); });
+bot.hears("ping", async (ctx) => { await ctx.reply("pong"); });
+bot.catch(async (error, ctx) => { await ctx.reply("出错了。"); });
 ```
 
-路由器支持命令、文本、正则、回调模式、自定义谓词、嵌套路由器、每条路由的中间件，以及路由优先级。
+路由器支持命令、文本、正则、回调模式、更新类型过滤器（`on`）、自定义谓词、嵌套路由器、每条路由的中间件，以及路由优先级。`bot.catch()` 注册错误边界：处理器失败会转发到那里，而不是拒绝整个 update。
 
 ## Telegram API
 
@@ -103,7 +107,7 @@ await ctx.reply("Pilih menu:", { reply_markup: keyboard });
 
 ## Startup and terminal logs
 
-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.
+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.
 
 ## Webhook
 
@@ -118,13 +122,47 @@ const handler = createWebhookHandler(bot, {
 
 `createWebhookHandler` 接受标准 Web `Request` 并返回 `Response`。处理程序会验证 secret token、body 大小、JSON 解析以及重复更新处理。
 
+## 高负载更新与广播
+
+telebibz 为 1000+ 条消息的突发场景而生，没有任何人为冷却：
+
+- **跨 chat 并行，同一 chat 内按序。** 每个 `getUpdates` 批次（以及每个 webhook 请求）都并发处理——不同 chat 的 update 不会互相排队，而同一 chat 的 update 保持到达顺序，因此会话、wizard 和 conversation 始终正确，会话写入永不丢失。并发突发只触发一次 `getMe` 初始化。
+- **没有主动限流。** 库永远不会延迟外发请求。当 Telegram 返回 429 时，transport 会严格按照 Telegram 指定的 `retry_after` 窗口等待（全局 "flood gate" 保护所有进行中的流量）并自动重试——因此突发流量会完整送达而不是失败。
+- **一次性向 1000+ 用户广播。** `bot.broadcast()` 立即尝试所有 chat，按照 Telegram 自己的 `retry_after` 重试 429，并返回完整报告。
+
+```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`);
+```
+
+当你自己的下游（数据库、API）需要时，可以用 `new Bot({ ..., updates: { concurrency: 64 } })` 或 `broadcast(..., { concurrency: 64 })` 限制并发——默认情况下两者都完全并行。
+
 ## 状态、队列、调度器和缓存
 
 该包提供带 TTL 和原子更新的 `MemoryStorage`、`JsonFileStorage`、`RedisStorage`、`SqlStorage`、`MongoStorage`、bot session、基于 Storage 的 conversation/form、基于 permission 的菜单、`MenuController` 分页、`MemoryCache`、令牌桶限流器、支持重试/退避/并发/延迟/取消的任务队列，以及间隔、一次性和完整五字段 cron 的调度器。Redis、SQL 和 Mongo 适配器使用小型 driver interface，因此 core package 不需要 vendor runtime dependency。
 
+## 终端体验
+
+当 bot 在交互式终端启动时（`npm start`、`node index.js`、`telebibz start`），telebibz 会播放启动序列：`Installing Dependencies......` 打字效果、带扫过高光的 glass 进度条，以及动画彩虹 ASCII 横幅 **Tele Bibz**（figlet `Speed` 字体）——彩虹持续流动直到 bot 连接成功，随后定格并显示 `✓ Connected as @<username>`。
+
+之后，每一条进入的 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"` 获取结构化日志。非交互 stdout（管道、Docker、CI）会自动回退到无动画的纯文本输出。
+
 ## CLI
 
-每个 `telebibz` command 都会显示带颜色的 Unicode branding box，其中包含 `Library Bot Telegram By @xbibzofficial`。CLI 不会打印 developer target。
+`telebibz doctor`、`init`、`webhook` 等 CLI command 以彩虹 `Tele Bibz` 横幅开始。当 stdout 不是 TTY 时，启动动画自动回退为干净的静态输出。
 
 ```bash
 npx telebibz init my-bot
@@ -136,8 +174,9 @@ npx telebibz test
 也可以在应用中打印相同的 terminal branding：
 
 ```ts
-import { printTerminalBranding } from "@xbibzlibrary/telebibz";
+import { printTeleBibzBanner, printTerminalBranding } from "@xbibzlibrary/telebibz";
 
+printTeleBibzBanner({ subtitle: "My bot" });
 printTerminalBranding();
 ```
 

package/RELEASE_AUTOMATION.md

@@ -8,17 +8,29 @@ Setiap push ke branch `main` menjalankan workflow `.github/workflows/auto-publis
 
 | Tahap | Perilaku |
 |---|---|
-| Checkout | Mengambil seluruh history agar tag dapat dibuat dengan benar. |
+| Checkout | Mengambil seluruh history beserta tag (`fetch-depth: 0` + `fetch-tags: true`) agar analisis commit dan pembuatan tag akurat. |
 | Install | Menjalankan `npm ci --ignore-scripts`. |
-| Version | Membaca versi dari `package.json`, membaca versi latest npm, lalu memilih patch version berikutnya yang lebih tinggi dari keduanya. |
+| Version | Membaca versi `package.json`, versi latest npm, dan commit sejak tag release terakhir, lalu memilih versi berikutnya (lihat aturan di bawah). |
 | Verification | Menjalankan typecheck, type-level tests, lint, runtime tests, build ESM/CommonJS, security audit, dan release check. |
 | Immutable guard | Menolak publish jika versi target sudah ada di npmjs. |
-| Git sync | Commit otomatis `chore(release): vX.Y.Z [skip release]`, membuat annotated tag `vX.Y.Z`, lalu push commit dan tag ke GitHub. |
+| Git sync | Commit otomatis `chore(release): vX.Y.Z [skip release]` (dilewati bila `package.json` sudah berada di versi target), membuat annotated tag `vX.Y.Z`, lalu push commit dan tag ke GitHub. |
 | npmjs publish | Menerbitkan package public menggunakan `NPM_TOKEN`; provenance dinonaktifkan karena npm menolak provenance dari source repository private. |
 | GitHub Release | Membuat GitHub Release dengan generated notes. |
 
 Push commit version otomatis tidak memicu release kedua karena mengandung `[skip release]`. Workflow menggunakan concurrency sehingga release berjalan satu per satu.
 
+## Aturan penomoran versi
+
+Versi berikutnya dihitung dari `max(package.json, npm latest)` dengan bump berdasarkan Conventional Commits sejak tag release terakhir:
+
+| Commit sejak tag terakhir | 0.x | >=1.0.0 |
+|---|---|---|
+| `BREAKING CHANGE:` atau `feat!:` / `fix!:` | minor (`0.1.19` → `0.2.0`) | major (`1.2.3` → `2.0.0`) |
+| `feat:` / `feat(scope):` | minor | minor |
+| lainnya (`fix:`, `docs:`, `chore:`, …) | patch | patch |
+
+Jika `package.json` sudah dideklarasikan lebih tinggi daripada versi npm (misalnya dipersiapkan manual untuk `0.2.0`), workflow memakai versi tersebut apa adanya. Hasil perhitungan tidak pernah boleh lebih rendah daripada versi npm yang sudah terbit; jika demikian, workflow gagal dengan pesan yang jelas.
+
 ## Secret dan permission yang wajib tersedia
 
 Workflow membutuhkan `contents: write` untuk version bump, tag, dan GitHub Release. Buka repository GitHub, kemudian masuk ke **Settings → Secrets and variables → Actions** dan tambahkan repository atau environment secret berikut:
@@ -33,9 +45,9 @@ Jangan menyimpan token di repository, `.npmrc`, source code, issue, commit, atau
 
 ## Aturan penggunaan
 
-Perubahan source biasa dapat dipush ke `main`; workflow akan menghasilkan patch release baru setelah seluruh quality gates lulus. Karena versi npm immutable, workflow tidak pernah menimpa versi yang telah ada.
+Perubahan source biasa dapat dipush ke `main`; workflow menghitung versi baru berdasarkan Conventional Commits (`feat:` → minor, `fix:`/lainnya → patch, `feat!:`/`BREAKING CHANGE:` → minor pada 0.x / major pada 1.x) setelah seluruh quality gates lulus. Karena versi npm immutable, workflow tidak pernah menimpa versi yang telah ada.
 
-Untuk perubahan besar, ubah `package.json` ke major/minor version yang diinginkan sebelum push. Workflow tetap memastikan hasil akhir lebih tinggi daripada versi npm yang sudah terbit, lalu menaikkan patch dari versi tertinggi tersebut.
+Untuk rilis yang dipersiapkan secara eksplisit (misalnya `0.2.0` atau `1.0.0`), deklarasikan versi tersebut langsung di `package.json` sebelum push; workflow akan memakainya apa adanya selama lebih tinggi daripada versi npm yang sudah terbit.
 
 Untuk perubahan dokumentasi atau perubahan internal yang tidak boleh menerbitkan npm, gunakan commit message yang memuat marker berikut:
 

package/bin/telebibz.mjs

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-import { main } from "../dist/cli.js";
+import { main } from "../dist/src/cli.js";
 await main();

package/dist/src/api/client.d.ts

@@ -26,7 +26,9 @@ export declare class ApiClient {
     private readonly hooks;
     constructor(options: ApiClientOptions);
     call<M extends TelegramMethodName>(method: M, ...args: ApiCallArgs<M>): Promise<ApiResult<M>>;
-    request<M extends TelegramMethodName>(method: M, payload?: ApiParams<M>, signal?: AbortSignal): Promise<ApiResult<M>>;
+    request<M extends TelegramMethodName>(method: M, payload?: ApiParams<M>, signal?: AbortSignal, options?: {
+        timeoutMs?: number;
+    }): Promise<ApiResult<M>>;
     raw(method: string, payload?: Record<string, unknown>, signal?: AbortSignal): Promise<unknown>;
 }
 //# sourceMappingURL=client.d.ts.map

package/dist/src/api/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/api/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyB,KAAK,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAExF,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACtF,OAAO,KAAK,EAAE,SAAS,EAAoB,MAAM,gBAAgB,CAAC;AAElE,MAAM,WAAW,cAAc;IAAG,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE;AACnK,MAAM,WAAW,gBAAgB;IAAG,SAAS,EAAE,SAAS,CAAC;IAAC,KAAK,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QAAC,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,CAAA;CAAE;AAClQ,MAAM,MAAM,UAAU,GAAG;KAAG,CAAC,IAAI,kBAAkB,GAAG,CAAC,GAAG,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;CAAE,CAAC;AAE3G,qBAAa,SAAS;IACpB,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAyC;gBACnD,OAAO,EAAE,gBAAgB;IAa/B,IAAI,CAAC,CAAC,SAAS,kBAAkB,EAAE,MAAM,EAAE,CAAC,EAAE,GAAG,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IAC7F,OAAO,CAAC,CAAC,SAAS,kBAAkB,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IAqBrH,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC;CAQrG"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/api/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyB,KAAK,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAExF,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACtF,OAAO,KAAK,EAAE,SAAS,EAAoB,MAAM,gBAAgB,CAAC;AAElE,MAAM,WAAW,cAAc;IAAG,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE;AACnK,MAAM,WAAW,gBAAgB;IAAG,SAAS,EAAE,SAAS,CAAC;IAAC,KAAK,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QAAC,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,CAAA;CAAE;AAClQ,MAAM,MAAM,UAAU,GAAG;KAAG,CAAC,IAAI,kBAAkB,GAAG,CAAC,GAAG,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;CAAE,CAAC;AAE3G,qBAAa,SAAS;IACpB,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAyC;gBACnD,OAAO,EAAE,gBAAgB;IAa/B,IAAI,CAAC,CAAC,SAAS,kBAAkB,EAAE,MAAM,EAAE,CAAC,EAAE,GAAG,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IAC7F,OAAO,CAAC,CAAC,SAAS,kBAAkB,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IAsBvJ,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC;CAQrG"}

package/dist/src/api/client.js

@@ -21,7 +21,7 @@ export class ApiClient {
         });
     }
     async call(method, ...args) { return this.request(method, args[0]); }
-    async request(method, payload, signal) {
+    async request(method, payload, signal, options) {
         const context = { method, payload, startedAt: Date.now() };
         await this.hooks.onRequest?.(context);
         try {
@@ -30,6 +30,8 @@ export class ApiClient {
                 request.payload = payload;
             if (signal !== undefined)
                 request.signal = signal;
+            if (options?.timeoutMs !== undefined)
+                request.timeoutMs = options.timeoutMs;
             const response = await this.transport.request(request);
             context.durationMs = Date.now() - context.startedAt;
             context.response = response.data;

package/dist/src/api/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../../../src/api/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../../src/api/client.ts"],"names":[],"mappings":"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"}

package/dist/src/api/transport.d.ts

@@ -3,6 +3,8 @@ export interface TransportRequest {
     method: string;
     payload?: Record<string, unknown>;
     signal?: AbortSignal;
+    /** Per-request timeout in milliseconds; overrides the transport default. */
+    timeoutMs?: number;
 }
 export interface TransportResponse<T = unknown> {
     status: number;
@@ -21,6 +23,14 @@ export interface FetchTransportOptions {
     maxBackoffMs?: number;
     jitter?: number;
     headers?: HeadersInit;
+    /**
+     * When Telegram answers 429 (rate limit), pause NEW requests until the
+     * `retry_after` window Telegram ordered has elapsed. Default `true`.
+     * This is never a proactive cooldown: the only waiting ever done is the
+     * delay Telegram itself demands, so a flood on one method protects the rest
+     * of the traffic instead of every request hitting the same 429 wall.
+     */
+    floodGate?: boolean;
 }
 export declare class FetchTransport implements Transport {
     private readonly baseUrl;
@@ -31,7 +41,14 @@ export declare class FetchTransport implements Transport {
     private readonly maxBackoffMs;
     private readonly jitter;
     private readonly headers;
+    private readonly floodGate;
+    /** Timestamp (ms) until which Telegram asked us to stop sending. */
+    private floodUntil;
     constructor(options?: FetchTransportOptions);
-    request<T>({ method, payload, signal }: TransportRequest): Promise<TransportResponse<T>>;
+    /** Waits out the remainder of a Telegram-ordered flood window, if any. */
+    private waitForFloodWindow;
+    /** Extends the flood window when Telegram answers 429 or sends retry_after. */
+    private recordFloodWindow;
+    request<T>({ method, payload, signal, timeoutMs }: TransportRequest): Promise<TransportResponse<T>>;
 }
 //# sourceMappingURL=transport.d.ts.map

package/dist/src/api/transport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../../src/api/transport.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAa,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAG9D,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB,CAAC,CAAC,GAAG,OAAO;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAAC;CAC3B;AAED,MAAM,WAAW,SAAS;IACxB,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC;CACtE;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,WAAW,CAAC;CACvB;AAED,qBAAa,cAAe,YAAW,SAAS;IAC9C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA0B;IACpD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAc;gBAE1B,OAAO,GAAE,qBAA0B;IAYzC,OAAO,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,OAAY,EAAE,MAAM,EAAE,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC;CA8EpG"}
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../../src/api/transport.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAa,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAG9D,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB,CAAC,CAAC,GAAG,OAAO;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAAC;CAC3B;AAED,MAAM,WAAW,SAAS;IACxB,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC;CACtE;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,qBAAa,cAAe,YAAW,SAAS;IAC9C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA0B;IACpD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAc;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAU;IACpC,oEAAoE;IACpE,OAAO,CAAC,UAAU,CAAK;gBAEX,OAAO,GAAE,qBAA0B;IAa/C,0EAA0E;YAC5D,kBAAkB;IAMhC,+EAA+E;IAC/E,OAAO,CAAC,iBAAiB;IAOnB,OAAO,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,OAAY,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC;CAiF/G"}

package/dist/src/api/transport.js

@@ -10,6 +10,9 @@ export class FetchTransport {
     maxBackoffMs;
     jitter;
     headers;
+    floodGate;
+    /** Timestamp (ms) until which Telegram asked us to stop sending. */
+    floodUntil = 0;
     constructor(options = {}) {
         this.baseUrl = (options.baseUrl ?? "https://api.telegram.org").replace(/\/$/, "");
         this.fetchImpl = options.fetch ?? globalThis.fetch;
@@ -21,8 +24,27 @@ export class FetchTransport {
         this.maxBackoffMs = options.maxBackoffMs ?? 8_000;
         this.jitter = options.jitter ?? 0.2;
         this.headers = options.headers ?? {};
+        this.floodGate = options.floodGate ?? true;
     }
-    async request({ method, payload = {}, signal }) {
+    /** Waits out the remainder of a Telegram-ordered flood window, if any. */
+    async waitForFloodWindow() {
+        if (!this.floodGate)
+            return;
+        const waitMs = this.floodUntil - Date.now();
+        if (waitMs > 0)
+            await new Promise((resolve) => setTimeout(resolve, waitMs));
+    }
+    /** Extends the flood window when Telegram answers 429 or sends retry_after. */
+    recordFloodWindow(data) {
+        if (!this.floodGate)
+            return;
+        if (data.ok || (data.error_code !== 429 && data.parameters?.retry_after === undefined))
+            return;
+        const retryAfterMs = Math.max(0, (data.parameters?.retry_after ?? 0) * 1000);
+        this.floodUntil = Math.max(this.floodUntil, Date.now() + retryAfterMs);
+    }
+    async request({ method, payload = {}, signal, timeoutMs }) {
+        const effectiveTimeoutMs = timeoutMs ?? this.timeoutMs;
         const hasUpload = await containsUpload(payload);
         let body;
         const headers = new Headers(this.headers);
@@ -38,9 +60,10 @@ export class FetchTransport {
         }
         let attempt = 0;
         while (true) {
+            await this.waitForFloodWindow();
             let responseStatus;
             const controller = new AbortController();
-            const timeout = setTimeout(() => controller.abort(new Error(`Request timed out after ${this.timeoutMs}ms`)), this.timeoutMs);
+            const timeout = setTimeout(() => controller.abort(new Error(`Request timed out after ${effectiveTimeoutMs}ms`)), effectiveTimeoutMs);
             const onAbort = () => controller.abort(signal?.reason);
             signal?.addEventListener("abort", onAbort, { once: true });
             try {
@@ -64,6 +87,7 @@ export class FetchTransport {
                     throw error;
                 }
                 const data = await response.json();
+                this.recordFloodWindow(data);
                 if (!data.ok && isRetryableResponse(response.status, data) && attempt < this.retries) {
                     const retryAfterMs = data.parameters?.retry_after === undefined ? undefined : Math.max(0, data.parameters.retry_after * 1000);
                     await waitBeforeRetry(attempt, this.backoffMs, this.maxBackoffMs, this.jitter, retryAfterMs);