@xbibzlibrary/telebibz 0.4.5 → 3.1.1

package/docs/API.zh-CN.md

@@ -1,1929 +0,0 @@
-# telebibz API 参考 — 简体中文
-
-[English](API.md) · [Bahasa Indonesia](API.id.md) · **简体中文**
-
-![telebibz 概览](https://cdn.jsdelivr.net/npm/@xbibzlibrary/telebibz@latest/assets/telebibz-readme-preview.png)
-
-本文件是当前发布的 `@xbibzlibrary/telebibz` API 参考。此处描述的所有签名和行为均映射自该包导出的 TypeScript 源代码。如果某个 Telegram 类型尚未有特定的参数/结果映射，该包仍通过动态 API 提供运行时访问，但其参数类型仍为通用类型。
-
-> **实现状态。** 本文档说明当前版本中可用的功能。`JsonFileStorage`、基于 driver 的 Redis/SQL/Mongo storage、基于 Storage 的 session/conversation、完整五字段 cron、`MenuController`、带 branding 的 terminal status output、带 redaction 的 structured logging、Web App 验证、`PaymentsClient` 和 `TelegramTypes` declaration 均已提供。core method map 仍主要为特定 request/result inference 提供类型，未来 Telegram method 可通过 `api.raw()` 访问。
-
-## 安装与导入
-
-```bash
-npm install @xbibzlibrary/telebibz
-```
-
-ESM：
-
-```ts
-import {
-  Bot,
-  InlineKeyboard,
-  compose,
-  escapeHtml,
-  type Context,
-} from "@xbibzlibrary/telebibz";
-```
-
-CommonJS：
-
-```js
-const { Bot, InlineKeyboard } = require("@xbibzlibrary/telebibz");
-```
-
-可用的子路径导出如下：
-
-| 子路径 | 内容 |
-|---|---|
-| `@xbibzlibrary/telebibz` | 来自 `src/index.ts` 的全部主要公共 API |
-| `@xbibzlibrary/telebibz/api` | Client、transport、errors，以及所有 Telegram API 类型 |
-| `@xbibzlibrary/telebibz/keyboard` | `InlineKeyboard`、`ReplyKeyboard` 以及键盘辅助函数 |
-| `@xbibzlibrary/telebibz/testing` | `MockTransport` 以及测试工厂 |
-
----
-
-## 1. 核心 Bot
-
-### `BotStatus`
-
-```ts
-type BotStatus =
-  | "created"
-  | "initialized"
-  | "starting"
-  | "running"
-  | "stopping"
-  | "stopped"
-  | "error";
-```
-
-### `BotOptions<S>`
-
-| 属性 | 类型 | 默认 | 说明 |
-|---|---|---:|---|
-| `token` | `string` | 必需 | Token BotFather dengan format `<digits>:<token>`. |
-| `apiBaseUrl` | `string` | `https://api.telegram.org` | Telegram API 的基础 URL。结尾的 `/` 会被自动移除。 |
-| `transport` | `Transport` | `FetchTransport` | 用于 mock、proxy 或其他实现的自定义 transport。 |
-| `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+ 条消息的突发可一次性处理。 |
-| `handlerTimeout` | `number` | `90000` | 单个 update 的处理超时（毫秒，`Infinity` 表示禁用）。超时后走 update 错误流程（`update:error`、`bot:error`、`catch()` 边界），`handleUpdate()` 以 `UpdateTimeoutError` 拒绝，而 handler 仍在后台继续运行直至完成。 |
-| `contextType` | `new (options: ContextOptions<S>) => Context<S>` | `Context` | 为每个 update 实例化的自定义 `Context` 子类（Telegraf 的 `contextType`）。 |
-
-### `Bot` constructor
-
-```ts
-new Bot<S extends object = Record<string, unknown>>(
-  options: string | BotOptions<S>,
-): Bot<S>
-```
-
-Jika argumen berupa string, string tersebut dianggap sebagai token. Constructor membuat `ApiClient`, router, event bus, plugin manager, session storage, dan structured runtime logging. Constructor langsung memancarkan event `bot:created` secara asynchronous.
-
-Constructor melempar `Error` jika token kosong atau tidak sesuai pola token Telegram.
-
-### `Bot` 的属性和 getter
-
-| API | 类型 | 描述 |
-|---|---|---|
-| `api` | `ApiClient` | 类型化/动态的 Telegram 客户端。 |
-| `router` | `Router<Context<S>>` | bot 的主路由器。 |
-| `events` | `EventBus<EventMap>` | 生命周期、update、API、webhook 和 polling 的事件总线。 |
-| `plugins` | `PluginManager<Context<S>>` | 插件的生命周期管理器。 |
-| `session` | `Storage<string, S>` | bot 的会话存储，可使用持久化适配器。 |
-| `services` | `Record<string, unknown>` | 构造函数提供的 service 的拷贝。 |
-| `token` | `string` | 客户端使用的 bot token。 |
-| `status` | `BotStatus` | 当前生命周期状态。 |
-| `botInfo` | `User \| undefined` | 最近一次 `getMe()` 的结果。 |
-
-### `bot.use(...middleware)`
-
-```ts
-use(...middleware: Middleware<Context<S>>[]): this
-```
-
-添加全局 middleware。middleware 在每个 update 的 router 之前执行，按注册顺序。返回 bot 实例以便链式调用。
-
-### `bot.command(name, handler)`
-
-```ts
-command(name: string, handler: Middleware<Context<S>>): this
-```
-
-注册 Telegram 命令，可带或不带前导 `/`。匹配时取 `/` 之后的第一个 token，并忽略 `@` 后的 bot mention。例如 `/start@my_bot` 会匹配 `"start"`。
-
-### `bot.callback(pattern, handler)`
-
-```ts
-callback(pattern: string | RegExp, handler: Middleware<Context<S>>): this
-```
-
-callback query 路由的快捷方式。以 `*` 结尾的字符串表示前缀匹配；其他字符串必须完全相等。
-
-### `bot.onText(text, handler)`
-
-```ts
-onText(text: string, handler: Middleware<Context<S>>): this
-```
-
-处理 `message.text` 与 `text` 完全相同的消息。
-
-### `bot.onRegex(expression, handler)`
-
-```ts
-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
-usePlugin(plugin: Plugin<Context<S>>): this
-```
-
-注册插件。插件名称必须唯一。
-
-### `bot.init()`
-
-```ts
-init(): Promise<this>
-```
-
-调用 `getMe()`，保存 bot 信息，初始化插件，并返回可用于 polling 或手动处理 update 的 bot。
-
-`init()` 在状态已为 `initialized` 或 `running` 时是幂等的。
-
-### `bot.start()`
-
-```ts
-start(): Promise<void>
-```
-
-是 `launch({ mode: "polling" })` 的快捷方式。此方法开始 long polling 并等待直到轮询被停止或发生致命错误。
-
-### `bot.launch(options?)`
-
-```ts
-launch(options?: {
-  mode: "polling";
-  timeout?: number;
-  allowedUpdates?: string[];
-  dropPendingUpdates?: boolean;
-}): Promise<void>
-```
-
-以 polling 模式运行 bot。启动时生命周期依次变为 `starting` 然后 `running`，之后 `getUpdates()` 循环并发处理每一批 update：不同 chat 的 update 并行执行，同一 chat 的 update 保持到达顺序。轮询失败会触发 `polling:reconnect` 并使用指数退避。`dropPendingUpdates: true`（`bot.start()` 同样支持）会在第一次 `getUpdates` 之前丢弃 Telegram 为该 bot 持有的全部更新，使用与 Telegraf 相同的 `deleteWebhook({ drop_pending_updates: true })` 机制。
-
-除 `"polling"` 外的模式会抛出错误，并建议对 webhook 使用 `createWebhookHandler()`。
-
-### `bot.stop()`
-
-```ts
-stop(): Promise<void>
-```
-
-通过 `AbortController` 停止轮询，调用 `plugins.dispose()`，将状态设置为 `stopped`，并触发 stopping/stopped 事件。当状态为 `created` 或 `stopped` 时调用不会有任何效果。
-
-### `bot.restart()`
-
-```ts
-restart(): Promise<void>
-```
-
-先运行 `stop()` 然后 `start()`。
-
-### `bot.health()`
-
-```ts
-health(): Promise<HealthStatus>
-```
-
-调用 `getMe()` 检查 API 可达性。请求失败不会抛出错误；失败会以 `apiReachable: false` 和错误信息的形式返回。
-
-```ts
-interface HealthStatus {
-  status: BotStatus;
-  apiReachable: boolean;
-  bot?: User;
-  checkedAt: string; // ISO timestamp
-  error?: string;
-}
-```
-
-### `bot.getMe()`
-
-```ts
-getMe(): Promise<User>
-```
-
-从 Telegram 获取 bot 数据并更新 `botInfo`。
-
-### `bot.setCommands(commands, scope?, languageCode?)`
-
-```ts
-setCommands(
-  commands: BotCommand[],
-  scope?: BotCommandScope,
-  languageCode?: string,
-): Promise<true>
-```
-
-相当于 `setMyCommands` 的快捷方式。`languageCode` 会映射为 Telegram 的 `language_code` 字段。
-
-### `bot.deleteCommands(scope?, languageCode?)`
-
-```ts
-deleteCommands(
-  scope?: BotCommandScope,
-  languageCode?: string,
-): Promise<true>
-```
-
-相当于 `deleteMyCommands` 的快捷方式。
-
-### `bot.downloadFile(fileId, options?)`
-
-```ts
-downloadFile(
-  fileId: string,
-  options?: { signal?: AbortSignal; destination?: string },
-): Promise<DownloadedFile>
-```
-
-通过 `getFile` 解析 `fileId`，再经由 transport 的下载端点获取原始字节。传入 `destination` 可同时把字节保存到本地文件路径（结果中的 `savedTo` 会被填充）。当 Telegram 未返回 `file_path` 或 transport 不支持下载时抛出 `TelegramError`（kind 为 `validation`）；下载失败时抛出 `TelegramNetworkError`。Telegram 限制单次下载 20 MB；返回的 `url` 至少一小时内有效。
-
-```ts
-const file = await bot.downloadFile(photoFileId, { destination: "downloads/photo.jpg" });
-console.log(file.fileName, file.sizeBytes, file.url, file.savedTo);
-```
-
-### `bot.handleUpdate(update)`
-
-```ts
-handleUpdate(update: Update, options?: { webhookReply?: WebhookReplySink }): Promise<void>
-```
-
-手动处理单个 update。该方法根据 `chat.id` 和 `from.id` 确定会话 key，创建 `Context`（由配置的 `contextType` 实例化），触发 `update` 和 `message` 事件，执行 middleware 然后路由器，并在流水线完成后保存会话。
-
-不同 chat 的 update 并行处理；同一 chat 的 update 按到达顺序串行处理，因此会话、wizard 和 conversation 永远不会交错，会话写入也不会丢失。并发的 update 突发只会触发一次 `getMe` 初始化。整个单 update 流程受 `handlerTimeout` 保护（默认 90 秒，与 Telegraf 一致）：超时后错误会流经 `update:error`/`bot:error` 和 `catch()` 边界，`handleUpdate()` 以 `UpdateTimeoutError` 拒绝，而 handler 仍在后台继续运行。
-
-`options.webhookReply` 安装一个 Telegraf 风格的响应器：该 update 期间第一个外发 API 调用通过 webhook HTTP 响应本身来应答（而不是单独发请求），并且以 `true` resolve（Telegram 从不把方法结果发回 webhook 响应）。
-
-流水线错误会将 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 }`。 |
-
-### `UpdateTimeoutError` 与 webhook-reply 辅助函数
-
-```ts
-class UpdateTimeoutError extends Error {
-  readonly name = "UpdateTimeoutError";
-  readonly updateId: number;
-}
-```
-
-当单个 update 超过 `handlerTimeout` 时由 `handleUpdate()` 拒绝抛出。handler 本身继续运行；错误同样会流经 `update:error`、`bot:error` 和 `catch()` 边界。
-
-```ts
-type WebhookReplySink = (payload: Record<string, unknown>) => void;
-runWithWebhookReply(sink, fn): Promise<T>   // 为 fn 内的所有 API 调用设置响应器
-runWithoutWebhookReply(fn): Promise<T>      // 永不占用槽位的库内部调用
-```
-
-导出这些函数，让自定义 webhook 服务器能够以与 `createWebhookHandler` 相同的方式接入 webhook 应答。
-
-### 最小 bot 示例
-
-```ts
-import { Bot, InlineKeyboard } from "@xbibzlibrary/telebibz";
-
-const bot = new Bot({
-  token: process.env.TELEGRAM_BOT_TOKEN!,
-  polling: { allowedUpdates: ["message", "callback_query"] },
-});
-
-bot.command("start", async (ctx) => {
-  await ctx.reply("来自 telebibz 的问候", {
-    reply_markup: new InlineKeyboard()
-      .text("状态", "status")
-      .build(),
-  });
-});
-
-bot.callback("status", async (ctx) => {
-  await ctx.answerCallbackQuery("机器人已激活");
-  await ctx.reply("状态：running");
-});
-
-await bot.start();
-```
-
----
-
-## 2. 事件总线
-
-### `EventMap`
-
-| 事件 | 负载 |
-|---|---|
-| `bot:created` | `{ bot: unknown }` |
-| `bot:initialized` | `{ bot: unknown }` |
-| `bot:starting` | `{ bot: unknown }` |
-| `bot:started` | `{ bot: unknown }` |
-| `bot:stopping` | `{ bot: unknown }` |
-| `bot:stopped` | `{ bot: unknown }` |
-| `bot:error` | `{ bot: unknown; error: unknown }` |
-| `update` | `{ update: unknown }` |
-| `message` | `{ message: unknown }` |
-| `command` | `{ name: string; update: unknown }` |
-| `callback` | `{ data: string; update: unknown }` |
-| `api:request` | `{ method: string; payload: unknown }` |
-| `api:response` | `{ method: string; durationMs: number; response: unknown }` |
-| `api:error` | `{ method: string; durationMs: number; error: unknown }` |
-| `webhook:request` | `{ update: unknown }` |
-| `polling:reconnect` | `{ error: unknown; attempt: number }` |
-
-### `EventBus<Events>`
-
-```ts
-new EventBus<Events extends Record<string, unknown> = EventMap>()
-```
-
-| 方法 | 签名 | 行为 |
-|---|---|---|
-| `on` | `on<K>(event: K, listener: (payload: Events[K]) => void \| Promise<void>): () => void` | 添加监听器并返回取消订阅函数。 |
-| `once` | `once<K>(event: K, listener: ...): () => void` | 监听器仅调用一次，然后被移除。 |
-| `off` | `off<K>(event: K, listener: ...): void` | 移除指定的监听器。 |
-| `emit` | `emit<K>(event: K, payload: Events[K]): Promise<void>` | 依次调用监听器并等待每个完成。 |
-| `removeAllListeners` | `removeAllListeners(): void` | 移除所有监听器。 |
-| `listenerCount` | `listenerCount<K>(event: K): number` | 返回事件的监听器数量。 |
-
-```ts
-const unsubscribe = bot.events.on("bot:error", ({ error }) => {
-  console.error(error);
-});
-unsubscribe();
-```
-
----
-
-## 3. API 客户端、传输 与 错误
-
-### 基本类型
-
-```ts
-type ChatId = number | string;
-type ParseMode = "Markdown" | "MarkdownV2" | "HTML";
-type InputFile =
-  | string
-  | Uint8Array
-  | ArrayBuffer
-  | Blob
-  | NodeJS.ReadableStream
-  | { source: string | Uint8Array | ArrayBuffer | Blob | NodeJS.ReadableStream; filename?: string };
-```
-
-`InputFile` string 可以是普通字符串，或在作为 upload 对象中的 `source` 时为文件路径。在 Node.js 中，绝对路径、`./...` 和 `../...` 会被 `FetchTransport` 读取，然后作为 multipart 文件发送。
-
-### `TelegramResponse<T>`
-
-```ts
-interface TelegramResponse<T> {
-  ok: boolean;
-  result?: T;
-  description?: string;
-  error_code?: number;
-  parameters?: ResponseParameters;
-}
-```
-
-### `TransportRequest`, `TransportResponse`, 和 `Transport`
-
-```ts
-interface TransportRequest {
-  method: string;
-  payload?: Record<string, unknown>;
-  signal?: AbortSignal;
-}
-
-interface TransportResponse<T = unknown> {
-  status: number;
-  headers: Headers;
-  data: TelegramResponse<T>;
-}
-
-interface Transport {
-  request<T>(request: TransportRequest): Promise<TransportResponse<T>>;
-}
-```
-
-### `FetchTransportOptions`
-
-| 属性 | 默认 | 描述 |
-|---|---:|---|
-| `baseUrl` | `https://api.telegram.org` | 在 `/<method>` 之前的 URL 前缀。 |
-| `fetch` | `globalThis.fetch` | 自定义 fetch 实现。 |
-| `timeoutMs` | `30000` | 每次尝试的超时（毫秒）。 |
-| `retries` | `2` | 初始尝试后的网络错误重试次数。 |
-| `backoffMs` | `250` | 初始指数退避延迟（毫秒）。 |
-| `maxBackoffMs` | `8000` | 传输延迟上限（毫秒）。 |
-| `jitter` | `0.2` | 对指数延迟的随机抖动，范围为 ±20%。 |
-| `floodGate` | `true` | 当 Telegram 返回 429 时，暂停新的请求直到 Telegram 指定的 `retry_after` 窗口结束。这不是主动冷却——唯一的等待就是 Telegram 自己要求的等待。 |
-| `headers` | `{}` | 额外的请求头。 |
-
-### `new FetchTransport(options?)`
-
-```ts
-new FetchTransport(options?: FetchTransportOptions): FetchTransport
-```
-
-内置的 transport 基于 `fetch`。不含上传的 payload 会以 JSON 发送。包含 `Uint8Array`、`ArrayBuffer`、`Blob` 或嵌套上传的 payload 会使用 `FormData` 作为 `multipart/form-data` 发送。
-
-### `fetchTransport.request(request)`
-
-```ts
-request<T>(request: TransportRequest): Promise<TransportResponse<T>>
-```
-
-发送 POST 到 `${baseUrl}/${method}`。以 `/` 开头的 method 会被正规化。外部的 AbortSignal 会转发到内部的 controller。被判定为可重试的网络错误会按指数退避并加抖动进行重试；当重试耗尽时，错误会被封装为 `TelegramNetworkError`。
-
-### `ApiHookContext`, `ApiClientOptions`, dan `ApiMethods`
-
-```ts
-interface ApiHookContext {
-  method: string;
-  payload: unknown;
-  startedAt: number;
-  durationMs?: number;
-  response?: TelegramResponse<unknown>;
-  error?: unknown;
-}
-
-interface ApiClientOptions {
-  transport: Transport;
-  hooks?: {
-    onRequest?: (context: ApiHookContext) => void | Promise<void>;
-    onResponse?: (context: ApiHookContext) => void | Promise<void>;
-    onError?: (context: ApiHookContext) => void | Promise<void>;
-  };
-}
-```
-
-`ApiMethods` 是基于 184 个 `TelegramMethodName` 的映射类型：
-
-```ts
-type ApiMethods = {
-  [M in TelegramMethodName]:
-    (...args: ApiCallArgs<M>) => Promise<ApiResult<M>>;
-};
-```
-
-### `new ApiClient(options)`
-
-```ts
-new ApiClient(options: ApiClientOptions): ApiClient
-```
-
-在 `client.methods` 上创建动态方法代理。Hook `onRequest` 在调用 transport 之前触发，`onResponse` 在收到响应后触发，`onError` 在请求失败或 Telegram 返回 `ok: false` 时触发。
-
-### `api.methods.<method>(params?)`
-
-动态方法可以直接调用。无参数的方法（如 `getMe()`）无需传入参数；其他方法接受单个对象参数。
-
-```ts
-const me = await bot.api.methods.getMe();
-const chat = await bot.api.methods.getChat({ chat_id: "@channel" });
-const message = await bot.api.methods.sendMessage({
-  chat_id: 123456789,
-  text: "你好",
-});
-```
-
-### `api.call(method, ...args)`
-
-```ts
-call<M extends TelegramMethodName>(
-  method: M,
-  ...args: ApiCallArgs<M>
-): Promise<ApiResult<M>>
-```
-
-用于基于字符串字面量调用方法的类型化形式。
-
-### `api.request(method, payload?, signal?)`
-
-```ts
-request<M extends TelegramMethodName>(
-  method: M,
-  payload?: ApiParams<M>,
-  signal?: AbortSignal,
-): Promise<ApiResult<M>>
-```
-
-低层请求方法，允许显式传入 `AbortSignal`。
-
-### `api.raw(method, payload?, signal?)`
-
-```ts
-raw(
-  method: string,
-  payload?: Record<string, unknown>,
-  signal?: AbortSignal,
-): Promise<unknown>
-```
-
-在 transport 上调用任意字符串方法。用于调用尚未包含在 `TelegramMethodMap` 的新的 Telegram 方法或参数。即使响应为 `ok: false`，也会被转换为 `TelegramError`。
-
-### `api.downloadFile(fileId, options?)`
-
-```ts
-downloadFile(fileId: string, options?: { signal?: AbortSignal }): Promise<DownloadedFile>
-```
-
-`bot.downloadFile` 的 API 客户端核心：解析 `getFile`、校验返回了 `file_path`，然后通过 transport 下载字节。
-
-### `DownloadedFile`
-
-```ts
-interface DownloadedFile {
-  file: File;            // getFile 返回的 Telegram File 对象
-  bytes: Uint8Array;     // 原始字节（Telegram 上限 20 MB）
-  filePath: string;      // 用于下载的 file_path
-  url: string;           // 直接下载 URL，至少一小时内有效
-  fileName: string;      // filePath 的最后一段
-  sizeBytes: number;     // bytes 的字节长度
-  savedTo?: string;      // 当 Bot.downloadFile 把文件写入磁盘时填充
-}
-```
-
-### `fetchTransport.fileUrl(filePath)` 与 `fetchTransport.download(filePath, signal?)`
-
-```ts
-fileUrl(filePath: string): string
-download(filePath: string, signal?: AbortSignal): Promise<Uint8Array>
-```
-
-`FetchTransport` 把 `/bot<token>` 基础 URL 映射为 `/file/bot<token>` 下载端点；`download` 以 GET 获取字节（大文件的 timeout 下限为 120 秒），HTTP 失败时抛出 `TelegramNetworkError`。两者都是 `Transport` 接口的可选成员，自定义 transport 可以省略 —— 此时 `downloadFile` 会以明确的校验错误失败，而不是崩溃。
-
-### 可用的类型化参数和返回值
-
-以下类型在此发布版本中已被映射：
-
-| 方法 | 参数 | 返回值 |
-|---|---|---|
-| `getMe` | 无 | `User` |
-| `getUpdates` | `GetUpdatesParams` | `Update[]` |
-| `setWebhook` | `SetWebhookParams` | `boolean` |
-| `deleteWebhook` | `{ drop_pending_updates?: boolean }` | `boolean` |
-| `getWebhookInfo` | 无 | `WebhookInfo` |
-| `sendMessage` | `SendMessageParams` | `Message` |
-| `editMessageText` | `EditMessageTextParams` | `Message \| true` |
-| `deleteMessage` | `DeleteMessageParams` | `true` |
-| `answerCallbackQuery` | `AnswerCallbackQueryParams` | `true` |
-| `getChat` | `GetChatParams` | `Chat` |
-| `getFile` | `GetFileParams` | `File` |
-| `getUserProfilePhotos` | `{ user_id: number; offset?: number; limit?: number }` | `UserProfilePhotos` |
-| `sendPhoto` | `SendPhotoParams` | `Message` |
-| `sendDocument` | `SendDocumentParams` | `Message` |
-
-可用的附加参数类型包括 `ReplyParameters`、`LinkPreviewOptions`、`InlineKeyboardButton`、`ReplyMarkup`、`BotCommand`、`BotCommandScope`，以及从 `api/types.ts` 导出的所有 Telegram update 类型。
-
-### API 错误
-
-```ts
-type TelegramErrorKind =
-  | "retryable"
-  | "rate-limit"
-  | "authentication"
-  | "validation"
-  | "network"
-  | "server"
-  | "unknown";
-```
-
-#### `TelegramError`
-
-```ts
-new TelegramError(message: string, options: {
-  method: string;
-  payload: unknown;
-  errorCode?: number;
-  parameters?: ResponseParameters;
-  status?: number;
-  kind?: TelegramErrorKind;
-  cause?: unknown;
-})
-```
-
-公开属性有 `kind`、`errorCode`、`parameters`、`method`、`payload` 和 `status`。Getter `retryAfter` 读取 `parameters.retry_after`；getter `migrateToChatId` 读取 `parameters.migrate_to_chat_id`。
-
-#### 错误子类
-
-| 类 | `name` | 强制的 `kind` |
-|---|---|---|
-| `TelegramRateLimitError` | `TelegramRateLimitError` | `rate-limit` |
-| `TelegramAuthError` | `TelegramAuthError` | `authentication` |
-| `TelegramValidationError` | `TelegramValidationError` | `validation` |
-| `TelegramNetworkError` | `TelegramNetworkError` | `network` |
-
-这四个子类使用与 `TelegramError` 相同的构造器选项。
-
-#### `classifyTelegramError(errorCode?, status?)`
-
-```ts
-classifyTelegramError(
-  errorCode?: number,
-  status?: number,
-): TelegramErrorKind
-```
-
-实际分类：`429` 映射为 `rate-limit`；错误 `401` 或 HTTP `401/403` 映射为 `authentication`；错误代码 `400–499` 映射为 `validation`；HTTP `500+` 映射为 `server`；其他为 `unknown`。
-
-#### `telegramErrorFromResponse(response, context)`
-
-```ts
-telegramErrorFromResponse<T>(
-  response: TelegramResponse<T>,
-  context: { method: string; payload: unknown; status?: number },
-): TelegramError
-```
-
-将失败的 Telegram 响应转换为相应的子类。`429`、认证和验证错误会产生相应的子类；其他错误会生成普通的 `TelegramError`。
-
----
-
-## 4. 上下文
-
-### `ContextOptions<S>`
-
-```ts
-interface ContextOptions<S extends object = Record<string, unknown>> {
-  update: Update;
-  api: ApiClient;
-  session: S;
-  services: Record<string, unknown>;
-}
-```
-
-### `Context<S>` 属性
-
-| 属性 | 内容 |
-|---|---|
-| `update` | Telegram 的原始 Update. |
-| `api` | 机器人 `ApiClient`. |
-| `session` | 当前 update key 的可变 session 对象. |
-| `state` | 每个上下文的临时对象，不会自动保存到 session. |
-| `services` | 通过 `BotOptions.services` 提供的服务. |
-| `params` | 路由参数对象；内置路由器目前不会自动填充. |
-| `message` | 来自 message/edited/channel/business/guest 更新的主要 message. |
-| `chat` | 若可用则为 `message.chat`. |
-| `from` / `sender` | 来自 message、callback query 或 inline query 的用户. |
-| `callbackQuery` | `update.callback_query`. |
-| `inlineQuery` | `update.inline_query`. |
-| `poll` | `update.poll`. |
-| `pollAnswer` | `update.poll_answer`. |
-| `chatMember` | `update.chat_member`. |
-| `myChatMember` | `update.my_chat_member`. |
-| `chatJoinRequest` | `update.chat_join_request`. |
-| `reaction` | `update.message_reaction`. |
-| `boost` | `chat_boost` 或 `removed_chat_boost`. |
-
-### `new Context(options)`
-
-```ts
-new Context<S>(options: ContextOptions<S>): Context<S>
-```
-
-### Context 消息方法
-
-| 方法 | 签名 | 行为 |
-|---|---|---|
-| `reply` | `reply(text, extra?): Promise<Message>` | 将消息发送到更新的聊天，并在存在消息时设置 `reply_parameters.message_id`. |
-| `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 来自上下文. |
-| `unpin` | `unpin(messageId?, extra?): Promise<true>` | 调用 `unpinChatMessage`，默认消息 ID 来自上下文. |
-| `react` | `react(reaction, extra?): Promise<true>` | 调用 `setMessageReaction`. |
-| `answerCallbackQuery` | `answerCallbackQuery(text?, extra?): Promise<true>` | 回答活动的回调查询。如果不是回调更新则抛出错误. |
-| `answerInlineQuery` | `answerInlineQuery(results, extra?): Promise<true>` | 回答活动的内联查询。如果不是内联更新则抛出错误. |
-| `getChat` | `getChat(): Promise<Chat>` | 获取上下文聊天的详细信息. |
-| `getUserProfilePhotos` | `getUserProfilePhotos(userId?, extra?): Promise<unknown>` | 获取上下文用户的头像照片. |
-| `getFile` | `getFile(fileId): Promise<unknown>` | 根据 ID 获取文件. |
-| `withReplyMarkup` | `withReplyMarkup(markup): this` | 将标记保存到 `ctx.state.reply_markup` 并返回上下文。此方法不会自动发送消息. |
-
-`reply`、`send`、`getChat` 以及其他一些辅助方法在更新缺少所需聊天时会抛出错误。`edit` 和 `delete` 需要同时有聊天和消息。
-
-### Context 管理员、聊天与论坛方法（与 Telegraf 完全对齐）
-
-以下方法均作用于本次更新的聊天（`ctx.chat`），并通过 `extra` 接受原生 Telegram 参数；当更新没有聊天时都会抛出清晰的错误。要操作其他聊天请使用 `ctx.api.methods.*`。
-
-| 分组 | 方法 |
-|---|---|
-| 管理/封禁 | `banChatMember(userId, untilDate?, extra?)`、`unbanChatMember(userId, onlyIfBanned?, extra?)`、`restrictChatMember(userId, permissions, untilDate?, extra?)`、`promoteChatMember(userId, extra?)`、`banChatSenderChat(senderChatId, extra?)`、`unbanChatSenderChat(senderChatId, extra?)` |
-| 聊天管理 | `setChatTitle(title)`、`setChatDescription(description?)`、`setChatPhoto(photo)`、`deleteChatPhoto()`、`setChatPermissions(permissions, extra?)`、`leaveChat()`、`unpinAllChatMessages(extra?)`、`setChatStickerSet(name)`、`deleteChatStickerSet()` |
-| 聊天与成员信息 | `getChatAdministrators(): Promise<ChatMember[]>`、`getChatMemberCount(): Promise<number>`、`getChatMember(userId): Promise<ChatMember>` |
-| 邀请链接 | `exportChatInviteLink(): Promise<string>`、`createChatInviteLink(extra?)`、`editChatInviteLink(inviteLink, extra?)`、`revokeChatInviteLink(inviteLink)` |
-| 加群申请 | `approveChatJoinRequest(userId)`、`declineChatJoinRequest(userId)` |
-| 投票与实时位置 | `replyWithQuiz(question, options, extra?)`（`type: "quiz"` 的 sendPoll）、`stopPoll(messageId?, extra?)`、`editMessageLiveLocation(latitude?, longitude?, extra?)`、`stopMessageLiveLocation(extra?)` |
-| 游戏与支付 | `replyWithGame(gameShortName, extra?)`、`setGameScore(userId, score, extra?)`、`getGameHighScores(userId?, extra?)`、`replyWithInvoice(title, description, payload, providerToken, currency, prices, extra?)` |
-| 论坛主题 | `createForumTopic(name, extra?)`、`editForumTopic(extra?)`、`closeForumTopic(threadId?)`、`reopenForumTopic(threadId?)`、`deleteForumTopic(threadId?)`、`unpinAllForumTopicMessages(threadId?)`、`getForumTopicIconStickers()`、`editGeneralForumTopic(name)`、`closeGeneralForumTopic()`、`reopenGeneralForumTopic()`、`hideGeneralForumTopic()`、`unhideGeneralForumTopic()` |
-
-`threadId` 默认取上下文消息的 `message_thread_id`。`replyWithQuiz`、`replyWithGame` 和 `replyWithInvoice` 与所有 `replyWith*` 发送者一样自动引用回复。
-
----
-
-## 5. 中间件与路由器
-
-### Middleware types
-
-```ts
-type Next = () => Promise<void>;
-type Middleware<Context> = (ctx: Context, next: Next) => void | Promise<void>;
-```
-
-以洋葱模型（onion pattern）组合中间件。`next()` 会执行下一个中间件。如果同一个中间件多次调用 `next()`，`compose` 会抛出 `Error("next() called multiple times")`。
-
-### `middleware(handler)`
-
-```ts
-middleware<Context>(handler: Middleware<Context>): Middleware<Context>
-```
-
-用于为中间件提供注解/类型推导的标识辅助函数。
-
-### `RoutableContext`
-
-路由器所需的最小上下文：`update`、`message`、`callbackQuery` 和 `params`。
-
-### `Router<Context>`
-
-```ts
-new Router<Context extends RoutableContext>(): Router<Context>
-```
-
-路由按照优先级和注册顺序处理。匹配的路由不会自动阻止后续路由；所有匹配的路由都可以被执行。如果没有任何路由匹配，则在 `handle` 上的 `terminal` 会被调用。
-
-| 方法 | 签名 | 匹配 |
-|---|---|---|
-| `use` | `use(...middleware): this` | 全局路由中间件，具有最高优先级，先执行。 |
-| `route` | `route(matcher, ...middleware): this` | 布尔或异步的自定义匹配器。 |
-| `command` | `command(name: string \| RegExp, ...middleware): this` | 以 `/` 开头的消息文本的第一个命令。 |
-| `text` | `text(value: string, ...middleware): this` | 精确文本匹配。 |
-| `regex` | `regex(expression: RegExp, ...middleware): this` | 对消息文本或空字符串使用 `RegExp.test`。 |
-| `callback` | `callback(pattern: string \| RegExp, ...middleware): this` | 对 callback 数据进行精确匹配、以 `*` 结尾作为前缀匹配，或使用正则匹配。 |
-| `chat` | `chat(chatId: number \| string, ...middleware): this` | 匹配 `message.chat.id`，数值或字符串等价。 |
-| `predicate` | `predicate(matcher, ...middleware): this` | 自定义 matcher 的语义别名。 |
-| `nest` | `nest(child: Router<Context>): this` | 将子路由作为嵌套路由运行。 |
-| `handle` | `handle(ctx, terminal?): Promise<void>` | 评估并执行所有匹配的路由。 |
-
-```ts
-const router = new Router<Context>();
-router.use(async (ctx, next) => {
-  console.log("before");
-  await next();
-});
-router.callback("page:*", async (ctx) => {
-  await ctx.answerCallbackQuery();
-});
-router.predicate((ctx) => Boolean(ctx.from?.id), async (ctx) => {
-  await ctx.reply("Authenticated update");
-});
-```
-
-**RegExp 注意事项。** 路由器直接调用 `.test()`。对于带有 `g` 或 `y` 标志的表达式，JavaScript 中有状态的 `lastIndex` 可能会影响重复匹配。
-
----
-
-## 6. Keyboard builders
-
-### `InlineKeyboard`
-
-```ts
-new InlineKeyboard(): InlineKeyboard
-InlineKeyboard.from(rows: InlineKeyboardButton[][]): InlineKeyboard
-```
-
-构建器以可变方式保存 `rows`，并且所有构建器方法都返回 `this`。
-
-| Method | Signature | 描述 |
-|---|---|---|
-| `from` | `static from(rows): InlineKeyboard` | 从 `rows` 创建键盘并复制每一行。 |
-| `text` | `text(text, callbackData): this` | 回调按钮。 |
-| `url` | `url(text, url): this` | URL 按钮。 |
-| `webApp` | `webApp(text, url): this` | Web 应用按钮。 |
-| `pay` | `pay(text = "Pay"): this` | 支付按钮。 |
-| `copy` | `copy(text, copiedText): this` | 复制文本按钮。 |
-| `button` | `button(button): this` | 将一个按钮添加到最后一行，或创建第一行。 |
-| `row` | `row(...buttons): this` | 添加新行。 |
-| `conditional` | `conditional(condition, factory): this` | 仅当 condition 为 true 时执行 factory。 |
-| `grid` | `grid(buttons, columns): this` | 将按钮按列数分配到各行。 |
-| `build` | `build(): InlineKeyboardMarkup` | 生成新的 markup。 |
-| `asReplyMarkup` | `asReplyMarkup(): InlineKeyboardMarkup` | `build` 的别名。 |
-
-每个 inline 按钮必须有 text 并且恰好一个 action。回调数据限制为最多 64 字节 UTF-8；超出会抛出 `RangeError`。
-
-```ts
-const keyboard = new InlineKeyboard()
-  .text("允许", "approve:123")
-  .url("文档", "https://example.com")
-  .row(
-    { text: "A", callback_data: "a" },
-    { text: "B", callback_data: "b" },
-  )
-  .build();
-```
-
-### `ReplyKeyboard`
-
-```ts
-new ReplyKeyboard(): ReplyKeyboard
-```
-
-| Method | Signature | 描述 |
-|---|---|---|
-| `text` | `text(text): this` | 普通文本按钮。 |
-| `contact` | `contact(text): this` | 请求联系人。 |
-| `location` | `location(text): this` | 请求位置。 |
-| `poll` | `poll(text, type?): this` | 请求投票，类型为 `quiz` 或 `regular`。 |
-| `webApp` | `webApp(text, url): this` | Web 应用按钮。 |
-| `button` | `button(button): this` | 将一个按钮添加到最后一行。 |
-| `row` | `row(...buttons): this` | 添加新行。 |
-| `grid` | `grid(buttons, columns): this` | 将按钮划分为网格。 |
-| `build` | `build(options?): ReplyKeyboardMarkup` | 生成 markup 并合并 options。 |
-| `asReplyMarkup` | `asReplyMarkup(): ReplyKeyboardMarkup` | `build()` 的别名，不带 options。 |
-
-columns 必须为正整数；否则，`grid` 会抛出 `RangeError`。
-
-### `removeKeyboard(selective?)`
-
-```ts
-removeKeyboard(selective = false): ReplyMarkup
-```
-
-生成 `{ remove_keyboard: true }`，如果请求则包含 `selective: true`。
-
-### `forceReply(placeholder?, selective?)`
-
-```ts
-forceReply(placeholder?: string, selective = false): ReplyMarkup
-```
-
-生成 ForceReply。仅当 placeholder 为 truthy 时才会添加占位符。
-
----
-
-## 7. 存储与缓存
-
-### `Storage<K, V>`
-
-```ts
-interface Storage<K, V> {
-  get(key: K): Promise<V | undefined>;
-  set(key: K, value: V, options?: { ttlMs?: number }): Promise<void>;
-  delete(key: K): Promise<boolean>;
-  has(key: K): Promise<boolean>;
-  clear(): Promise<void>;
-  keys(): AsyncIterable<K>;
-  values(): AsyncIterable<V>;
-  entries(): AsyncIterable<[K, V]>;
-  update<T extends V>(
-    key: K,
-    updater: (current: V | undefined) => T | Promise<T>,
-    options?: { ttlMs?: number },
-  ): Promise<T>;
-}
-```
-
-### `MemoryStorage<K, V>`
-
-```ts
-new MemoryStorage<K, V>(): MemoryStorage<K, V>
-```
-
-基于 `Map` 的内存实现。TTL 在读取或迭代键时惰性清理；没有后台定时器。`update` 使得每个键的 updater 操作串行执行，从而避免对同一键的并发更新出现意外覆盖。
-
-```ts
-const sessions = new MemoryStorage<string, { count: number }>();
-await sessions.set("user:1", { count: 0 }, { ttlMs: 60_000 });
-await sessions.update("user:1", (current) => ({
-  count: (current?.count ?? 0) + 1,
-}));
-```
-
-### `Cache<K, V>`
-
-```ts
-interface Cache<K = string, V = unknown> {
-  get(key: K): Promise<V | undefined>;
-  set(key: K, value: V, ttlMs?: number): Promise<void>;
-  delete(key: K): Promise<boolean>;
-  invalidate(prefix?: string): Promise<void>;
-  getOrSet(key: K, factory: () => V | Promise<V>, ttlMs?: number): Promise<V>;
-}
-```
-
-### `MemoryCache`
-
-```ts
-new MemoryCache(namespace = "telebibz"): MemoryCache
-```
-
-对字符串键的缓存，会对每个 key 在内部添加命名空间。
-
-| Method | 行为 |
-|---|---|
-| `get` | 获取 value 或 `undefined`。 |
-| `set` | 存储 value 并可选 TTL。 |
-| `delete` | 删除 key 并返回布尔值。 |
-| `invalidate(prefix = "")` | 删除命名空间中以 prefix 开头的所有 key。 |
-| `getOrSet` | 返回缓存命中；若未命中，执行 factory，存储结果后返回。 |
-
-`getOrSet` 不使用去重锁；当 key 还不存在且并发调用时，factory 可能会被执行多次。
-
-### `RateLimitResult`
-
-```ts
-interface RateLimitResult {
-  allowed: boolean;
-  remaining: number;
-  resetAt: number;
-  retryAfterMs?: number;
-}
-```
-
-### `TokenBucketLimiter`
-
-```ts
-new TokenBucketLimiter(
-  capacity: number,
-  refillPerSecond: number,
-): TokenBucketLimiter
-```
-
-构造函数在任一参数非正时抛出 `RangeError`。`consume(key, cost = 1)` 在有可用令牌时扣减；若令牌不足，返回 `allowed: false` 并给出估计的 `retryAfterMs`。`clear(key?)` 删除单个桶或全部桶。
-
----
-
-## 8. 队列和调度器
-
-### `Job<T>` 和 `QueueOptions`
-
-```ts
-interface Job<T = unknown> {
-  id: string;
-  data: T;
-  attempts: number;
-  priority: number;
-  runAt: number;
-  status: "queued" | "running" | "completed" | "failed" | "cancelled";
-  error?: unknown;
-}
-
-interface QueueOptions {
-  concurrency?: number;
-  retries?: number;
-  backoffMs?: number;
-  maxBackoffMs?: number;
-}
-```
-
-### `TaskQueue<T>`
-
-```ts
-new TaskQueue<T>(
-  worker: (job: Job<T>, signal: AbortSignal) => Promise<void>,
-  options?: QueueOptions,
-): TaskQueue<T>
-```
-
-| 方法 | 签名 | 描述 |
-|---|---|---|
-| `add` | `add(data, options?): Job<T>` | 添加作业；options 包含 `id`, `priority`, `delayMs`。作业会立即被调度。 |
-| `get` | `get(id): Job<T> \| undefined` | 返回作业状态的副本。 |
-| `cancel` | `cancel(id): boolean` | 取消处于 queued 或 running 状态的作业并中止 worker 的 signal。 |
-| `onIdle` | `onIdle(): Promise<void>` | 等待直到 pending 和 active 为空。 |
-| `close` | `close(): Promise<void>` | 停止新的排空并取消活动的控制器。 |
-
-优先级更高的作业先执行；若相同，则较早的 `runAt` 先执行。重试会一直进行直到超过 `retries`。重试延迟为指数增长，`maxBackoffMs` 的默认上限为 30 秒。
-
-### `ScheduledJob`
-
-```ts
-interface ScheduledJob {
-  id: string;
-  cancel: () => void;
-}
-```
-
-### `Scheduler`
-
-```ts
-new Scheduler(): Scheduler
-```
-
-| 方法 | 签名 | 描述 |
-|---|---|---|
-| `every` | `every(id, intervalMs, task): ScheduledJob` | 使用 `setInterval` 运行任务。使用相同 id 替换定时器。 |
-| `after` | `after(id, delayMs, task): ScheduledJob` | 使用 `setTimeout` 执行一次任务。 |
-| `cron` | `cron(id, expression, task): ScheduledJob` | 支持分钟字段的简单格式 `*/N`，等同于间隔 `N * 60_000`。 |
-| `cancel` | `cancel(id): boolean` | 取消定时器。 |
-| `clear` | `clear(): void` | 取消所有定时器。 |
-
-内置调度器不支持完整的 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. 插件与服务
-
-### `Plugin<Context>`
-
-```ts
-interface Plugin<Context = unknown> {
-  name: string;
-  version?: string;
-  install?: (api: PluginApi<Context>) => void | Promise<void>;
-  setup?: (api: PluginApi<Context>) => void | Promise<void>;
-  onStart?: (api: PluginApi<Context>) => void | Promise<void>;
-  onUpdate?: (context: Context) => void | Promise<void>;
-  onStop?: (api: PluginApi<Context>) => void | Promise<void>;
-  dispose?: (api: PluginApi<Context>) => void | Promise<void>;
-}
-```
-
-### `PluginApi<Context>`
-
-```ts
-interface PluginApi<Context> {
-  bot: unknown;
-  services: ServiceContainer;
-  registerMiddleware: (middleware: unknown) => void;
-  registerRoute: (route: unknown) => void;
-}
-```
-
-在此发行版中，`registerMiddleware` 和 `registerRoute` 可作为 hook API 提供，但实现管理器尚未将它们自动连接到 bot/router。插件可以直接使用 `api.bot` 和 `api.services`。
-
-### `ServiceContainer`
-
-```ts
-new ServiceContainer(): ServiceContainer
-```
-
-| 方法 | 签名 | 描述 |
-|---|---|---|
-| `register` | `register<T>(name: string \| symbol, value: T): this` | 存储服务并支持链式调用。 |
-| `get` | `get<T>(name: string \| symbol): T` | 获取服务；如果未注册则抛出错误。 |
-| `has` | `has(name: string \| symbol): boolean` | 检查服务是否存在。 |
-| `delete` | `delete(name: string \| symbol): boolean` | 删除服务。 |
-
-### `PluginManager<Context>`
-
-```ts
-new PluginManager<Context>(bot: unknown): PluginManager<Context>
-```
-
-| 方法 | 行为 |
-|---|---|
-| `use(plugin)` | 添加插件；重复名称会抛出错误。 |
-| `setup()` | 对每个插件先执行 `install` 然后 `setup`。 |
-| `start()` | 按注册顺序执行 `onStart`。 |
-| `update(context)` | 按注册顺序执行 `onUpdate`。 |
-| `stop()` | 执行 `onStop`。 |
-| `dispose()` | 按相反的注册顺序执行 `dispose`。 |
-| `list()` | 返回只读的插件列表。 |
-
-`Bot.handleUpdate()` 在此发行版中不会自动调用 `plugins.update()`；如果插件需要 update 生命周期，请显式调用管理器。
-
----
-
-## 10. Webhook
-
-### `WebhookOptions`
-
-```ts
-interface WebhookOptions {
-  secretToken?: string;
-  maxBodyBytes?: number;
-  onError?: (error: unknown) => void | Promise<void>;
-  webhookReply?: boolean;
-}
-```
-
-`webhookReply`（默认 `false`）启用 Telegraf 风格的 webhook 应答：处理 update 期间，第一个外发 API 调用直接通过 webhook HTTP 响应本身应答（`{"method":"sendMessage", ...}`），Telegram 因此无需第二次请求即可执行该方法。该调用以 `true` resolve，因为 Telegram 从不把方法结果发回 webhook 响应；之后的每个调用都照常走 transport。懒加载的 `getMe` 初始化永远不会占用该槽位。与 Telegraf 不同，此功能为 opt-in，已有的 webhook 部署行为保持完全不变。
-
-### `createWebhookHandler(bot, options?)`
-
-```ts
-createWebhookHandler<S extends object>(
-  bot: Bot<S>,
-  options?: WebhookOptions,
-): (request: Request) => Promise<Response>
-```
-
-处理程序接收标准的 Web `Request` 并返回 `Response`。
-
-| 情况 | 响应 |
-|---|---|
-| 方法不是 POST | `405 Method Not Allowed`, header `allow: POST` |
-| Secret 头部不匹配 | `401 Unauthorized` |
-| `Content-Length` 或 body 超过限制 | `413 Payload Too Large` |
-| JSON 无效或 `update_id` 不是整数 | 对于 update id 返回 `400 Bad Request`; 解析时的异常返回 `500` |
-| `bot.handleUpdate` 成功 | `200 OK`，body 为 `OK` |
-| 其他异常 | `500 Internal Server Error` 并调用 `onError` |
-
-默认 `maxBodyBytes` 为 `1_048_576` bytes。Telegram 的 secret 从 header `x-telegram-bot-api-secret-token` 读取。
-
-```ts
-import { Bot, createWebhookHandler } from "@xbibzlibrary/telebibz";
-
-const bot = new Bot(process.env.TELEGRAM_BOT_TOKEN!);
-const handler = createWebhookHandler(bot, {
-  secretToken: process.env.TELEGRAM_WEBHOOK_SECRET,
-});
-
-export default { fetch: handler };
-```
-
----
-
-## 11. 会话、向导、表单和菜单
-
-### Conversation
-
-```ts
-interface ConversationState {
-  name: string;
-  step: number;
-  values: Record<string, unknown>;
-  status: "active" | "completed" | "cancelled";
-  updatedAt: number;
-}
-```
-
-#### `ConversationFlow<S>`
-
-```ts
-new ConversationFlow(ctx: Context<S>, state: ConversationState)
-```
-
-| 方法/属性 | 签名 | 描述 |
-|---|---|---|
-| `ctx` | `Context<S>` | 当前的更新上下文。 |
-| `state` | `ConversationState` | 可变的会话状态。 |
-| `values` | `Record<string, unknown>` | 是 `state.values` 的别名。 |
-| `set` | `set<T>(key, value): this` | 保存值并更新 `updatedAt`。 |
-| `get` | `get<T>(key): T \| undefined` | 获取类型化的值。 |
-| `next` | `next(): this` | 将 step 增加 1。 |
-| `previous` | `previous(): this` | 将 step 减少，但最低为 0。 |
-| `complete` | `complete(): void` | 将状态置为 `completed`。 |
-| `cancel` | `cancel(): void` | 将状态置为 `cancelled`。 |
-
-#### `ConversationManager<S>`
-
-```ts
-new ConversationManager<S>(): ConversationManager<S>
-```
-
-| 方法 | 签名 | 描述 |
-|---|---|---|
-| `start` | `start(key, name, values?): ConversationState` | 创建或替换会话状态。 |
-| `get` | `get(key): ConversationState \| undefined` | 获取活动状态。 |
-| `cancel` | `cancel(key): boolean` | 如果存在则标记为 cancelled。 |
-| `clearExpired` | `clearExpired(maxAgeMs): number` | 删除 `updatedAt` 早于阈值的状态。 |
-| `run` | `run(ctx, key, name, steps): Promise<ConversationState>` | 根据 `state.step` 运行对应的步骤；如果没有步骤，则状态为 completed。 |
-
-```ts
-const conversations = new ConversationManager();
-await conversations.run(ctx, "chat:1", "profile", [
-  async (flow) => {
-    flow.set("name", ctx.message?.text);
-    flow.next();
-  },
-  async (flow) => {
-    await flow.ctx.reply(`Nama: ${flow.get<string>("name")}`);
-    flow.complete();
-  },
-]);
-```
-
-#### `Wizard<S>` dan `WizardStep<S>`
-
-```ts
-interface WizardStep<S> {
-  id: string;
-  run: (flow: ConversationFlow<S>) => void | Promise<void>;
-  optional?: boolean;
-}
-
-new Wizard<S>()
-```
-
-| 方法/属性 | 描述 |
-|---|---|
-| `step(definition)` | 添加步骤并返回 wizard。`optional` 保存在定义中，但 runner 还没有特殊处理。 |
-| `run(ctx, key, manager?)` | 通过 `ConversationManager` 使用 name 为 `"wizard"` 运行 wizard 的步骤。 |
-| `steps` | 只读的步骤列表。 |
-
-### 表单
-
-```ts
-interface ValidationIssue {
-  path: string;
-  message: string;
-  code?: string;
-}
-
-interface Field<T> {
-  name: string;
-  parse: (input: unknown) => T;
-  validate?: (value: T) => string | undefined | Promise<string | undefined>;
-  transform?: (value: T) => T | Promise<T>;
-  required?: boolean;
-}
-```
-
-#### `Form<T>`
-
-```ts
-new Form<T extends Record<string, unknown>>(): Form<T>
-```
-
-| 方法 | 描述 |
-|---|---|
-| `field(definition)` | 根据 `name` 注册类型化字段。 |
-| `parse(input)` | 处理所有字段。返回 success 或 issues 的联合结果。顺序：required 检查、parse、transform、validate。 |
-| `reset()` | 清除内部保存的解析数据。 |
-
-Result parse:
-
-```ts
-type FormResult<T> =
-  | { success: true; data: T }
-  | { success: false; issues: ValidationIssue[] };
-```
-
-Issue 使用 code `required`、`parse` 或 `invalid`。
-
-#### `validators`
-
-| 验证器 | 输入 | 结果/错误 |
-|---|---|---|
-| `validators.string` | `unknown` | String；否则 `TypeError("Expected string")`. |
-| `validators.number` | `unknown` | 有限的 Number，包括数字字符串；否则 `TypeError("Expected number")`. |
-| `validators.integer` | `unknown` | Integer；否则 `TypeError("Expected integer")`. |
-| `validators.email` | `unknown` | 符合简易 email 模式的 String；否则 `TypeError("Expected email")`. |
-| `validators.url` | `unknown` | 可被 `URL` 构造函数接受的 String；否则 `TypeError("Expected URL")`. |
-
-### 分页与菜单
-
-#### `Page<T>`
-
-```ts
-interface Page<T> {
-  items: T[];
-  page: number;
-  pageCount: number;
-  hasPrevious: boolean;
-  hasNext: boolean;
-}
-```
-
-#### `paginate(items, page, pageSize)`
-
-```ts
-paginate<T>(
-  items: readonly T[],
-  page: number,
-  pageSize: number,
-): Page<T>
-```
-
-Page 使用 0 为基的索引。超出范围的 page 会被夹取到最后一页。空集合仍然具有 `pageCount: 1`。负数或非整数的 `page` 或 `pageSize < 1` 会抛出 `RangeError`。
-
-#### `paginationButtons(page, prefix)`
-
-```ts
-paginationButtons(
-  page: Page<unknown>,
-  prefix: string,
-): InlineKeyboardButton[]
-```
-
-生成 `Previous` 按钮、带回调 `${prefix}:noop` 的指示器 `${page + 1}/${pageCount}`，以及根据 page 标志显示 `Next`。
-
-#### `MenuItem`
-
-```ts
-interface MenuItem {
-  id: string;
-  label: string;
-  callbackData?: string;
-  url?: string;
-  visible?: boolean | ((context: MenuContext, item: MenuItem) => boolean | Promise<boolean>);
-  permission?: string | ((context: MenuContext, item: MenuItem) => boolean | Promise<boolean>);
-}
-```
-
-#### `Menu`
-
-```ts
-new Menu(id: string): Menu
-```
-
-| 方法/属性 | 描述 |
-|---|---|
-| `item(item)` | 添加 item 并支持链式调用。 |
-| `breadcrumb(label)` | 添加 breadcrumb 标签。 |
-| `build()` | 等待可见性谓词，跳过不可见项，然后生成 `InlineKeyboard`。URL 优先于 callback。 |
-| `breadcrumbs` | `breadcrumbs` 只读的 breadcrumb 数组。 |
-
-`permission` 仅作为 item 的元数据存储；`Menu.build()` 不会自动执行授权。
-
----
-
-## 12. Terminal Logging
-
-当 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. 文本工具
-
-### `escapeMarkdownV2(value)`
-
-```ts
-escapeMarkdownV2(value: string): string
-```
-
-对 Telegram MarkdownV2 字符进行转义：`\\_ * [ ] ( ) ~ ` > # + - = | { } . !`.
-
-### `escapeHtml(value)`
-
-```ts
-escapeHtml(value: string): string
-```
-
-将 `&`、`<`、`>` 和 `"` 转换为 HTML 实体。
-
-### `md`
-
-下面可用的 MarkdownV2 辅助对象：
-
-| Method | 输出（概念） |
-|---|---|
-| `md.bold(value)` | `*escaped value*` |
-| `md.italic(value)` | `_escaped value_` |
-| `md.link(label, url)` | `[escaped label](escaped url)` |
-| `md.code(value)` | 使用已转义反引号的行内代码。 |
-| `md.pre(value, language?)` | 带可选语言标签的代码块。 |
-| `md.escape(value)` | 别名 `escapeMarkdownV2`. |
-
-### `splitMessage(text, options?)`
-
-```ts
-splitMessage(
-  text: string,
-  options?: {
-    limit?: number;
-    parseMode?: "Markdown" | "MarkdownV2" | "HTML";
-  },
-): string[]
-```
-
-将文本拆分为片段，默认字符限制为 `4096`。在可能的情况下，拆分会优先选择段落边界、换行或空格；仅当边界位于窗口的一半以上时才使用该边界。`parseMode` 作为 API 的选项被接受，但目前并不会改变拆分算法。
-
-小于 1 的 limit 会抛出 `RangeError`。
-
-### `splitCaption(text)`
-
-```ts
-splitCaption(text: string): string[]
-```
-
-`splitMessage(text, { limit: 1024 })` 的快捷方式。
-
-### `template(templateText, values)`
-
-```ts
-template(
-  templateText: string,
-  values: Record<string, unknown>,
-): string
-```
-
-替换占位符 `{{ key }}` 以及类似 `{{ user.name }}` 的嵌套路径。`null` 或 `undefined` 的值会被替换为空字符串；其他值将使用 `String()` 转换。
-
-```ts
-template("你好 {{ user.name }}", { user: { name: "Ayu" } });
-// "你好 Ayu"
-```
-
----
-
-### `validateUpload(upload, rules)`
-
-```ts
-validateUpload(upload: UploadLike, rules: UploadRules): UploadValidationIssue[]
-```
-
-在发送前校验上传：`maxBytes`（大小上限）、`allowedMimeTypes`（精确或通配符如 `image/*`）、`allowedExtensions`（大小写不敏感，带不带前导点均可）。返回找到的全部违规 —— 空数组表示上传可接受。
-
-### `assertValidUpload(upload, rules)`
-
-规则相同，但不返回结果而是抛出 `UploadValidationError`（附带全部 `issues`）。
-
-```ts
-import { assertValidUpload } from "@xbibzlibrary/telebibz";
-
-assertValidUpload(
-  { sizeBytes: fileBytes.length, mimeType: "image/png", fileName: "logo.png" },
-  { maxBytes: 5_000_000, allowedMimeTypes: ["image/png", "image/jpeg"], allowedExtensions: [".png", ".jpg"] },
-);
-```
-
-## 14. Testing utilities
-
-Import dari `@xbibzlibrary/telebibz/testing` atau root package.
-
-### `MockTransport`
-
-```ts
-new MockTransport(): MockTransport
-```
-
-| API | Deskripsi |
-|---|---|
-| `calls` | Array semua `TransportRequest` yang diterima. |
-| `respond(method, response)` | Mengatur response statis atau callback berdasarkan payload dan mengembalikan transport. |
-| `request(request)` | Mencatat request dan mengembalikan response mock. Response default adalah `{ ok: true, result: true }`. |
-
-Status mock adalah `200` bila `ok: true`, atau `error_code`/`500` bila `ok: false`.
-
-```ts
-const transport = new MockTransport()
-  .respond("getMe", {
-    ok: true,
-    result: { id: 1, is_bot: true, first_name: "Test" },
-  });
-```
-
-`MockTransport` 同样实现了可选的下载成员：`download(filePath)` 把路径记录进 `downloads` 并返回 `downloadBytes`（默认为路径的 UTF-8 编码），`fileUrl(filePath)` 返回 `mock://files/<filePath>` —— 因此 `bot.downloadFile()` 无需网络即可完整测试。
-
-### `createMockUpdate(overrides?)`
-
-```ts
-createMockUpdate(overrides?: Partial<Update>): Update
-```
-
-Membuat update message default dengan `update_id: 1`, chat private id `1`, user id `2`, dan text `/start`. Object `overrides` digabung shallow dengan default.
-
-### `createTestBot()`
-
-```ts
-createTestBot(): { bot: Bot; transport: MockTransport }
-```
-
-Membuat bot dengan token test `123456:TEST_TOKEN`, mock `getMe()` yang menghasilkan bot id `99`, dan transport yang dapat diperiksa melalui `transport.calls`.
-
-### `createMockContext(bot, update?)`
-
-```ts
-createMockContext(
-  bot: Bot,
-  update?: Update,
-): Context
-```
-
-Membuat context menggunakan API bot, session kosong, dan services kosong.
-
----
-
-
-## 15. 生成的 Telegram 方法命名空间
-
-`generated/api.ts` 是生成器的内部源，定义了:
-
-```ts
-const TELEGRAM_API_VERSION = "10.2";
-const TELEGRAM_METHOD_NAMES: readonly string[];
-type TelegramMethodName = typeof TELEGRAM_METHOD_NAMES[number];
-type GeneratedMethodSpec = {
-  params: Record<string, unknown>;
-  result: unknown;
-};
-type GeneratedTelegramMethodMap = {
-  [K in TelegramMethodName]: GeneratedMethodSpec;
-};
-const GENERATED_METHODS: Record<TelegramMethodName, TelegramMethodName>;
-```
-
-`TELEGRAM_METHOD_NAMES` 包含生成器源中的 184 个方法名。该命名空间是 `api.methods`、`api.call` 和 `api.request` 的代理基础，但在此版本中生成的文件并未作为公共包子路径导出。尚未映射的特定参数/返回值可以通过 `api.raw()` 调用，或在 TypeScript 中通过类型转换传参。
-
-以下为未经分组的规范方法列表，生成时运行时命名空间中可用的方法名为：
-
-```text
-addStickerToSet,
-answerCallbackQuery,
-answerChatJoinRequestQuery,
-answerGuestQuery,
-answerInlineQuery,
-answerPreCheckoutQuery,
-answerShippingQuery,
-answerWebAppQuery,
-approveChatJoinRequest,
-approveSuggestedPost,
-banChatMember,
-banChatSenderChat,
-close,
-closeForumTopic,
-closeGeneralForumTopic,
-convertGiftToStars,
-copyMessage,
-copyMessages,
-createChatInviteLink,
-createChatSubscriptionInviteLink,
-createForumTopic,
-createInvoiceLink,
-createNewStickerSet,
-declineChatJoinRequest,
-declineSuggestedPost,
-deleteAllMessageReactions,
-deleteBusinessMessages,
-deleteChatPhoto,
-deleteChatStickerSet,
-deleteEphemeralMessage,
-deleteForumTopic,
-deleteMessage,
-deleteMessageReaction,
-deleteMessages,
-deleteMyCommands,
-deleteStickerFromSet,
-deleteStickerSet,
-deleteStory,
-deleteWebhook,
-editChatInviteLink,
-editChatSubscriptionInviteLink,
-editEphemeralMessageCaption,
-editEphemeralMessageMedia,
-editEphemeralMessageReplyMarkup,
-editEphemeralMessageText,
-editForumTopic,
-editGeneralForumTopic,
-editMessageCaption,
-editMessageChecklist,
-editMessageLiveLocation,
-editMessageMedia,
-editMessageReplyMarkup,
-editMessageText,
-editStory,
-editUserStarSubscription,
-exportChatInviteLink,
-forwardMessage,
-forwardMessages,
-getAvailableGifts,
-getBusinessAccountGifts,
-getBusinessAccountStarBalance,
-getBusinessConnection,
-getChat,
-getChatAdministrators,
-getChatGifts,
-getChatMember,
-getChatMemberCount,
-getChatMenuButton,
-getCustomEmojiStickers,
-getFile,
-getForumTopicIconStickers,
-getGameHighScores,
-getManagedBotAccessSettings,
-getManagedBotToken,
-getMe,
-getMyCommands,
-getMyDefaultAdministratorRights,
-getMyDescription,
-getMyName,
-getMyShortDescription,
-getMyStarBalance,
-getStarTransactions,
-getStickerSet,
-getUpdates,
-getUserChatBoosts,
-getUserGifts,
-getUserPersonalChatMessages,
-getUserProfileAudios,
-getUserProfilePhotos,
-getWebhookInfo,
-giftPremiumSubscription,
-hideGeneralForumTopic,
-leaveChat,
-logOut,
-pinChatMessage,
-postStory,
-promoteChatMember,
-readBusinessMessage,
-refundStarPayment,
-removeBusinessAccountProfilePhoto,
-removeChatVerification,
-removeMyProfilePhoto,
-removeUserVerification,
-reopenForumTopic,
-reopenGeneralForumTopic,
-replaceManagedBotToken,
-replaceStickerInSet,
-repostStory,
-restrictChatMember,
-revokeChatInviteLink,
-savePreparedInlineMessage,
-savePreparedKeyboardButton,
-sendAnimation,
-sendAudio,
-sendChatAction,
-sendChatJoinRequestWebApp,
-sendChecklist,
-sendContact,
-sendDice,
-sendDocument,
-sendGame,
-sendGift,
-sendInvoice,
-sendLivePhoto,
-sendLocation,
-sendMediaGroup,
-sendMessage,
-sendMessageDraft,
-sendPaidMedia,
-sendPhoto,
-sendPoll,
-sendRichMessage,
-sendRichMessageDraft,
-sendSticker,
-sendVenue,
-sendVideo,
-sendVideoNote,
-sendVoice,
-setBusinessAccountBio,
-setBusinessAccountGiftSettings,
-setBusinessAccountName,
-setBusinessAccountProfilePhoto,
-setBusinessAccountUsername,
-setChatAdministratorCustomTitle,
-setChatDescription,
-setChatMemberTag,
-setChatMenuButton,
-setChatPermissions,
-setChatPhoto,
-setChatStickerSet,
-setChatTitle,
-setCustomEmojiStickerSetThumbnail,
-setGameScore,
-setManagedBotAccessSettings,
-setMessageReaction,
-setMyCommands,
-setMyDefaultAdministratorRights,
-setMyDescription,
-setMyName,
-setMyProfilePhoto,
-setMyShortDescription,
-setPassportDataErrors,
-setStickerEmojiList,
-setStickerKeywords,
-setStickerMaskPosition,
-setStickerPositionInSet,
-setStickerSetThumbnail,
-setStickerSetTitle,
-setUserEmojiStatus,
-setWebhook,
-stopMessageLiveLocation,
-stopPoll,
-transferBusinessAccountStars,
-transferGift,
-unbanChatMember,
-unbanChatSenderChat,
-unhideGeneralForumTopic,
-unpinAllChatMessages,
-unpinAllForumTopicMessages,
-unpinAllGeneralForumTopicMessages,
-unpinChatMessage,
-upgradeGift,
-uploadStickerFile,
-verifyChat
-```
-
-> 上述列表遵循生成的源代码。如果 Telegram 添加了新方法，请在 schema 更新后运行 `npm run update:telegram` 或 `telebibz generate`。
-
----
-
-## 16. 命令行界面 (CLI)
-
-二进制包为 `telebibz`。
-
-```bash
-npx telebibz <command>
-```
-
-| 命令 | 行为 |
-|---|---|
-| `telebibz init [directory]` | 创建目录、最小的 `index.ts`，以及 `.env.example`。默认目录 `my-telebibz-bot`。 |
-| `telebibz doctor` | 显示 Node 版本、是否存在 `TELEGRAM_BOT_TOKEN`、cwd、包名，然后如果存在 token 则检查健康检查 API。如果 API 无法访问则退出码为 1。 |
-| `telebibz generate` | 运行 `scripts/generate-api.mjs` 中的生成器方法。 |
-| `telebibz build` | 运行 `npm run build`。 |
-| `telebibz test` | 运行 `npm test`。 |
-| `telebibz webhook` | 检查 `TELEGRAM_BOT_TOKEN`，如有则使用 `TELEGRAM_WEBHOOK_SECRET`，创建处理器并打印就绪状态。此命令不会创建 HTTP 服务器。 |
-| `telebibz inspect` | 显示 cwd 和 Node 版本。 |
-| 无命令 | 显示帮助命令列表。 |
-
-CLI 使用的环境变量是 `TELEGRAM_BOT_TOKEN` 和 `TELEGRAM_WEBHOOK_SECRET`。
-
----
-
-## 17. 主要 Telegram 类型
-
-该包直接导出最常用的数据类型。
-
-| Type | 重要内容 |
-|---|---|
-| `User` | ID、机器人标志、姓名、用户名、语言和能力标志。 |
-| `Chat` | ID、类型、标题/用户名/名称、论坛/私信 标志。 |
-| `Message` | ID、日期、聊天、发送者、文本/说明、实体、回复、标记，以及用于额外 Telegram 字段的索引签名。 |
-| `Update` | 包含源支持的所有更新字段，包括消息、回调、内联、投票、成员、加入请求、反应、提升、业务和扩展字段。 |
-| `CallbackQuery` | ID、来自用户、消息/内联消息 ID、聊天实例、数据。 |
-| `InlineQuery` | ID、来自用户、查询、偏移、聊天类型、位置。 |
-| `Poll`, `PollAnswer` | 投票数据和答案。 |
-| `ChatMemberUpdated`, `ChatJoinRequest` | 成员变更和加入请求。 |
-| `InlineKeyboardMarkup`, `ReplyKeyboardMarkup`, `ReplyKeyboardRemove`, `ForceReply` | Telegram 的回复标记（reply markup）格式。 |
-| `MessageEntity`, `ReplyParameters`, `LinkPreviewOptions` | 实体元数据、回复参数和链接预览选项。 |
-| `BotCommand`, `BotCommandScope`, `WebhookInfo`, `File`, `UserProfilePhotos`, `ChatMember`, `ChatAdministratorRights` | API 的结果/参数辅助类型。 |
-
----
-
-## 18. 持久化、完整 cron、菜单和完整 Telegram 声明
-
-### 持久化 storage 适配器
-
-所有适配器都实现相同的 `Storage<K, V>` contract。核心 package 不包含 vendor runtime dependency；Redis、SQL 和 Mongo 适配器接收由应用或所选 vendor client 提供的小型 driver interface。
-
-| Class | 构造函数 | 用途 |
-|---|---|---|
-| `MemoryStorage<K, V>` | `new MemoryStorage()` | 带 TTL 和按 key 原子 `update()` 的快速内存 storage。 |
-| `JsonFileStorage<V>` | `new JsonFileStorage(filePath)` | 适用于单进程部署的原子 JSON 文件持久化。 |
-| `RedisStorage<V>` | `new RedisStorage(client, prefix?)` | 通过 `RedisLikeClient` 使用 Redis storage，包含 TTL 和 namespace。 |
-| `SqlStorage<V>` | `new SqlStorage(driver)` | 通过应用提供的 `SqlStorageDriver` 使用 SQL storage。 |
-| `MongoStorage<V>` | `new MongoStorage(collection)` | 通过应用提供的 `MongoStorageCollection` 使用 Mongo storage。 |
-
-`BotOptions.session` 接受 `Storage<string, S>`，因此 session 可以使用任意适配器。`ConversationManager` 接受相同的 storage abstraction，并提供 `getAsync()`、`cancelAsync()` 和 `clearExpiredAsync()` 来持久化 conversation state。
-
-```ts
-const session = new JsonFileStorage<Record<string, unknown>>("./data/sessions.json");
-const bot = new Bot({ token: process.env.TELEGRAM_BOT_TOKEN!, session });
-```
-
-### 完整五字段 cron
-
-`parseCronExpression()` 支持标准五字段 `minute hour day-of-month month day-of-week`，包括 wildcard、list、range 和 step，例如 `*/15 9-17 1,15 * 1-5`。`nextCronOccurrence()` 计算下一个本地 occurrence。`Scheduler.cron()` 使用 one-shot timer，并在每次执行后重新调度；任务错误会交给 `Scheduler({ onError })`，不会成为未处理的 promise rejection。
-
-### Router matching mode
-
-`new Router()` 默认使用 **first-match**，防止意外的 double reply。只有在确实需要 fan-out 时才使用 `new Router({ matchMode: "all" })`。RegExp matcher 在测试前会重置 `lastIndex`，因此 global 或 sticky expression 可以安全复用。
-
-### MenuController 和 permission
-
-`Menu` 支持基于 permission 的 item、异步 visibility/permission predicate、breadcrumb 和多列布局。`MenuController` 增加 stateful page rendering，以及对 `select`、`page`、`noop` 和外部 callback data 的 dispatch。
-
-### 完整 Telegram declaration namespace
-
-Package 内置 MIT 许可的 Telegram declaration，并通过 type-only export 暴露 `TelegramTypes`，同时提供 `TelegramUser`、`TelegramMessage`、`TelegramUpdate` 和 `TelegramApiMethods` 等 alias。CLI 使用带颜色的 Unicode box，并包含 attribution `Library Bot Telegram By @xbibzofficial`。`Logger` 输出带 level、redaction、update summary 的 terminal 或 JSON 结构化日志，并支持 opt-in 记录 user message/callback content。这些 declaration 覆盖完整的 object、union、enum 和 method surface，不增加 runtime dependency。telebibz core method map 仍专门为具有直接参数/结果映射的 method 提供类型。
-
----
-
-## 19. 兼容性和需要注意的限制
-
-本库面向 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()` 或在应用端添加类型声明。
-
-Session 状态和其他内存 primitive 会在进程重启时丢失，除非应用提供持久化适配器。`BotOptions.session` 接受 generic `Storage<string, S>` contract。
-
----
-
-## 参考文献
-
-[1]: https://core.telegram.org/bots/api "Telegram Bot API — 官方文档"
-[2]: https://www.npmjs.com/package/@xbibzlibrary/telebibz "@xbibzlibrary/telebibz 在 npm 上"