@xbibzlibrary/telebibz 0.1.19 → 0.3.1

package/docs/API.md

@@ -67,11 +67,13 @@ 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. |
 | `polling.retryDelayMs` | `number` | `500` | Initial delay when polling fails. |
 | `polling.maxRetryDelayMs` | `number` | `30000` | Maximum reconnect delay. |
+| `updates.concurrency` | `number` | `Infinity` | Cap on how many updates are processed at the same time. Updates always run in parallel across chats and stay ordered within a single chat, so bursts of 1000+ messages are handled at once. |
 
 ### Constructor `Bot`
 
@@ -139,6 +141,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
@@ -193,7 +219,7 @@ launch(options?: {
 }): Promise<void>
 ```
 
-Runs the bot in polling mode. On start, the lifecycle moves through `starting` to `running`, then the `getUpdates()` loop processes each update sequentially. Polling failures emit `polling:reconnect` and use exponential backoff.
+Runs the bot in polling mode. On start, the lifecycle moves through `starting` to `running`, then the `getUpdates()` loop processes each batch of updates concurrently: updates for different chats run in parallel while updates for the same chat keep their arrival order. Polling failures emit `polling:reconnect` and use exponential backoff.
 
 Modes other than `"polling"` throw an error and suggest using `createWebhookHandler()` for webhooks.
 
@@ -270,8 +296,54 @@ handleUpdate(update: Update): Promise<void>
 
 Processes a single update manually. The method determines the session key from `chat.id` and `from.id`, creates a `Context`, emits `update` and `message` events, runs middleware then the router, and saves the session after the pipeline completes.
 
+Updates for different chats are processed in parallel; updates for the same chat are serialized in arrival order, so sessions, wizards, and conversations never interleave and session writes are never lost. A burst of concurrent updates triggers exactly one `getMe` initialization.
+
 Pipeline errors set the bot status to `error`, emit `bot:error`, and then rethrow the error.
 
+### `bot.handleUpdates(updates)`
+
+```ts
+handleUpdates(updates: readonly Update[]): Promise<void>
+```
+
+Handles a whole batch of updates at once: every chat in the batch is processed immediately — parallel across chats, ordered per chat — so a burst of 1000 messages is never stuck behind one slow handler. Individual handler failures are logged, emitted as `update:error`, and passed to the `catch()` error boundary; they never reject this promise. The polling loop uses this method for every `getUpdates` batch.
+
+### `bot.broadcast(chatIds, send, options?)`
+
+```ts
+broadcast(
+  chatIds: readonly ChatId[],
+  send: (chatId: ChatId) => Promise<unknown>,
+  options?: BroadcastOptions,
+): Promise<BroadcastReport>
+```
+
+Sends to many chats in parallel — built for broadcasts to 1000+ users. There is no proactive cooldown: every chat is attempted at once (up to `options.concurrency`, default `Infinity`). When Telegram answers 429, the send is retried automatically after exactly the `retry_after` delay Telegram ordered (up to `options.maxAttempts`, default `10`), so bursts deliver completely instead of failing. Non-retryable errors (for example, a chat the bot cannot message) are recorded per chat in the returned report.
+
+```ts
+const report = await bot.broadcast(
+  subscriberIds,
+  (chatId) => bot.api.methods.sendMessage({ chat_id: chatId, text: "Newsletter #42" }),
+  { onProgress: (progress) => console.log(`${progress.delivered}/${progress.total} delivered`) },
+);
+console.log(`Delivered ${report.delivered} of ${report.total} in ${report.durationMs}ms`);
+for (const failure of report.failures) console.warn(`Failed: ${failure.chatId} — ${failure.error}`);
+```
+
+#### `BroadcastOptions` and `BroadcastReport`
+
+| Property | Type | Default | Description |
+|---|---|---:|---|
+| `BroadcastOptions.concurrency` | `number` | `Infinity` | How many chats are messaged at the same time. |
+| `BroadcastOptions.maxAttempts` | `number` | `10` | Attempts per chat when Telegram answers 429. |
+| `BroadcastOptions.onProgress` | `(progress: BroadcastProgress) => void` | — | Called after each chat settles. |
+| `BroadcastOptions.signal` | `AbortSignal` | — | Aborts pending sends; delivered messages stay delivered. |
+| `BroadcastReport.total` | `number` | — | Chats in the run. |
+| `BroadcastReport.delivered` | `number` | — | Chats that received the message. |
+| `BroadcastReport.failed` | `number` | — | Chats that did not. |
+| `BroadcastReport.durationMs` | `number` | — | Wall-clock duration of the run. |
+| `BroadcastReport.failures` | `BroadcastFailure[]` | — | Per-chat `{ chatId, attempts, error, errorKind }` records. |
+
 ### Minimal bot example
 
 ```ts
@@ -409,6 +481,7 @@ interface Transport {
 | `maxBackoffMs` | `8000` | Transport delay cap. |
 | `jitter` | `0.2` | Random variation ±20% of the exponential delay. |
 | `headers` | `{}` | Additional headers. |
+| `floodGate` | `true` | When Telegram answers 429, pauses NEW requests until the `retry_after` window Telegram ordered has elapsed. Never a proactive cooldown — the only waiting done is what Telegram itself demands. |
 
 ### `new FetchTransport(options?)`
 
@@ -650,6 +723,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 +752,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.
 
 ---
 
@@ -973,6 +1063,20 @@ new Scheduler(): Scheduler
 
 The full cron format is not supported by the built-in scheduler. Expressions other than `*/N` throw an `Error`.
 
+### `Limiter` and `mapWithConcurrency`
+
+```ts
+new Limiter(limit: number): Limiter
+
+mapWithConcurrency<T, R>(
+  items: readonly T[],
+  limit: number,
+  worker: (item: T, index: number) => Promise<R>,
+): Promise<R[]>
+```
+
+`Limiter` is a promise semaphore: tasks run immediately while a slot is free and queue FIFO beyond that. `limit` accepts any positive integer or `Infinity` (fully parallel — the library default). `mapWithConcurrency` maps items through an async worker with the same cap while preserving result order; results and errors behave like `Promise.all` mapped arrays. These primitives add no delays of their own — they only bound how many tasks run at the same time. `Limiter` exposes `activeCount` and `queuedCount` for observability.
+
 ## 9. Plugins and services
 
 ### `Plugin<Context>`
@@ -1281,11 +1385,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 +1411,8 @@ const bot = new Bot({
 });
 ```
 
+Additional branding helpers exported for applications: `runStartupSequence()`, `startTeleBibzBanner()`, `printTeleBibzBanner()`, `paintRainbow()`, and `printStatusLine()`.
+
 ---
 
 ## 13. Text Utilities
@@ -1723,7 +1841,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,11 +68,13 @@ 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 更新过滤器。 |
 | `polling.retryDelayMs` | `number` | `500` | 轮询失败时的初始延迟（毫秒）。 |
 | `polling.maxRetryDelayMs` | `number` | `30000` | 重连延迟的最大值（毫秒）。 |
+| `updates.concurrency` | `number` | `Infinity` | 同时处理的 update 数量上限。不同 chat 的 update 始终并行，同一 chat 内保持顺序，因此 1000+ 条消息的突发可一次性处理。 |
 
 ### `Bot` constructor
 
@@ -140,6 +142,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
@@ -176,7 +202,7 @@ launch(options?: {
 }): Promise<void>
 ```
 
-以 polling 模式运行 bot。启动时生命周期依次变为 `starting` 然后 `running`，之后 `getUpdates()` 循环按顺序处理每个 update。轮询失败会触发 `polling:reconnect` 并使用指数退避。
+以 polling 模式运行 bot。启动时生命周期依次变为 `starting` 然后 `running`，之后 `getUpdates()` 循环并发处理每一批 update：不同 chat 的 update 并行执行，同一 chat 的 update 保持到达顺序。轮询失败会触发 `polling:reconnect` 并使用指数退避。
 
 除 `"polling"` 外的模式会抛出错误，并建议对 webhook 使用 `createWebhookHandler()`。
 
@@ -253,8 +279,54 @@ handleUpdate(update: Update): Promise<void>
 
 手动处理单个 update。该方法根据 `chat.id` 和 `from.id` 确定会话 key，创建 `Context`，触发 `update` 和 `message` 事件，执行 middleware 然后路由器，并在流水线完成后保存会话。
 
+不同 chat 的 update 并行处理；同一 chat 的 update 按到达顺序串行处理，因此会话、wizard 和 conversation 永远不会交错，会话写入也不会丢失。并发的 update 突发只会触发一次 `getMe` 初始化。
+
 流水线错误会将 bot 状态置为 `error`，触发 `bot:error`，然后重新抛出错误。
 
+### `bot.handleUpdates(updates)`
+
+```ts
+handleUpdates(updates: readonly Update[]): Promise<void>
+```
+
+一次性处理整批 update：批次中的每个 chat 立即处理——跨 chat 并行、同一 chat 内按序——因此 1000 条消息的突发绝不会卡在某个慢速 handler 后面。单个 handler 的失败会记录日志、以 `update:error` 触发事件并交给 `catch()` 错误边界；它们永远不会让该 promise 被 reject。轮询循环对每个 `getUpdates` 批次都使用此方法。
+
+### `bot.broadcast(chatIds, send, options?)`
+
+```ts
+broadcast(
+  chatIds: readonly ChatId[],
+  send: (chatId: ChatId) => Promise<unknown>,
+  options?: BroadcastOptions,
+): Promise<BroadcastReport>
+```
+
+并行向大量 chat 发送消息——专为向 1000+ 用户广播而设计。没有主动冷却：所有 chat（至多 `options.concurrency`，默认 `Infinity`）同时尝试发送。当 Telegram 返回 429 时，会严格按照 Telegram 指定的 `retry_after` 延迟自动重试（至多 `options.maxAttempts` 次，默认 `10`），因此突发流量会完整送达而不是失败。不可重试的错误（例如 bot 无法发送的 chat）会按 chat 记录在返回的报告中。
+
+```ts
+const report = await bot.broadcast(
+  subscriberIds,
+  (chatId) => bot.api.methods.sendMessage({ chat_id: chatId, text: "Newsletter #42" }),
+  { onProgress: (progress) => console.log(`${progress.delivered}/${progress.total} delivered`) },
+);
+console.log(`Delivered ${report.delivered} of ${report.total} in ${report.durationMs}ms`);
+for (const failure of report.failures) console.warn(`Failed: ${failure.chatId} — ${failure.error}`);
+```
+
+#### `BroadcastOptions` 和 `BroadcastReport`
+
+| 属性 | 类型 | 默认值 | 说明 |
+|---|---|---:|---|
+| `BroadcastOptions.concurrency` | `number` | `Infinity` | 同时向多少个 chat 发送消息。 |
+| `BroadcastOptions.maxAttempts` | `number` | `10` | Telegram 返回 429 时每个 chat 的尝试次数。 |
+| `BroadcastOptions.onProgress` | `(progress: BroadcastProgress) => void` | — | 每个 chat 结束后调用。 |
+| `BroadcastOptions.signal` | `AbortSignal` | — | 中止待发送的消息；已送达的消息保持送达。 |
+| `BroadcastReport.total` | `number` | — | 本次广播的 chat 总数。 |
+| `BroadcastReport.delivered` | `number` | — | 成功收到消息的 chat 数。 |
+| `BroadcastReport.failed` | `number` | — | 未收到消息的 chat 数。 |
+| `BroadcastReport.durationMs` | `number` | — | 本次广播的实际耗时（毫秒）。 |
+| `BroadcastReport.failures` | `BroadcastFailure[]` | — | 按 chat 记录的 `{ chatId, attempts, error, errorKind }`。 |
+
 ### 最小 bot 示例
 
 ```ts
@@ -391,6 +463,7 @@ interface Transport {
 | `backoffMs` | `250` | 初始指数退避延迟（毫秒）。 |
 | `maxBackoffMs` | `8000` | 传输延迟上限（毫秒）。 |
 | `jitter` | `0.2` | 对指数延迟的随机抖动，范围为 ±20%。 |
+| `floodGate` | `true` | 当 Telegram 返回 429 时，暂停新的请求直到 Telegram 指定的 `retry_after` 窗口结束。这不是主动冷却——唯一的等待就是 Telegram 自己要求的等待。 |
 | `headers` | `{}` | 额外的请求头。 |
 
 ### `new FetchTransport(options?)`
@@ -633,6 +706,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 来自上下文. |
@@ -948,6 +1037,20 @@ new Scheduler(): Scheduler
 
 内置调度器不支持完整的 cron 格式。除 `*/N` 外的表达式会抛出 `Error`。
 
+### `Limiter` 和 `mapWithConcurrency`
+
+```ts
+new Limiter(limit: number): Limiter
+
+mapWithConcurrency<T, R>(
+  items: readonly T[],
+  limit: number,
+  worker: (item: T, index: number) => Promise<R>,
+): Promise<R[]>
+```
+
+`Limiter` 是一个 promise 信号量：有空闲槽位时任务立即执行，超出后按 FIFO 排队。`limit` 接受任意正整数或 `Infinity`（完全并行——即本库的默认值）。`mapWithConcurrency` 以相同的并发上限让 item 通过 async worker 映射，同时保持结果顺序。这些原语自身不会添加任何延迟——它们只限制同时运行的任务数量。`Limiter` 暴露 `activeCount` 和 `queuedCount` 用于可观测性。
+
 ---
 
 ## 9. 插件与服务
@@ -1257,7 +1360,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 +1801,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.3.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",