@xbibzlibrary/telebibz 0.4.4 → 0.4.5

package/docs/MIGRATION_TELEGRAF.zh-CN.md

@@ -0,0 +1,147 @@
+# 从 Telegraf 迁移（简体中文）
+
+telebibz 有意实现了 Telegraf 的 context 表面与启动选项，因此大多数 handler 只需极少改动即可移植。本指南把 Telegraf bot 的每个部分映射到 telebibz 对应物。
+
+## 目录
+
+1. [并排对照：完整 bot](#1-并排对照完整-bot)
+2. [概念映射](#2-概念映射)
+3. [Context 方法](#3-context-方法)
+4. [启动选项](#4-启动选项)
+5. [Scenes → Wizards](#5-scenes--wizards)
+6. [会话存储](#6-会话存储)
+7. [Webhook](#7-webhook)
+8. [没有直接对应物的部分](#8-没有直接对应物的部分)
+
+## 1. 并排对照：完整 bot
+
+**Telegraf**
+
+```ts
+import { Telegraf } from "telegraf";
+
+const bot = new Telegraf(process.env.TELEGRAM_BOT_TOKEN!);
+
+bot.use(async (ctx, next) => { console.time("update"); await next(); console.timeEnd("update"); });
+bot.start((ctx) => ctx.reply("Welcome!"));
+bot.command("help", (ctx) => ctx.reply("Help"));
+bot.action("menu:open", async (ctx) => { await ctx.answerCbQuery(); await ctx.reply("Menu"); });
+bot.on("message", (ctx) => ctx.reply("got it"));
+bot.catch((error) => console.error(error));
+
+bot.launch({ dropPendingUpdates: true });
+```
+
+**telebibz**
+
+```ts
+import { Bot } from "@xbibzlibrary/telebibz";
+
+const bot = new Bot(process.env.TELEGRAM_BOT_TOKEN!);
+
+bot.use(async (ctx, next) => { console.time("update"); await next(); console.timeEnd("update"); });
+bot.command("start", async (ctx) => { await ctx.reply("Welcome!"); });   // 具名命令，而非 bot.start()
+bot.command("help", async (ctx) => { await ctx.reply("Help"); });
+bot.action("menu:open", async (ctx) => { await ctx.answerCallbackQuery(); await ctx.reply("Menu"); });
+bot.on("message", async (ctx) => { await ctx.reply("got it"); });
+bot.catch(async (error) => { console.error(error); });
+
+await bot.launch({ dropPendingUpdates: true });   // 选项名相同
+```
+
+只有两处机械差异：`bot.start(handler)` 变为 `bot.command("start", handler)`；`answerCbQuery()` 变为 `answerCallbackQuery()`。
+
+## 2. 概念映射
+
+| Telegraf | telebibz | 说明 |
+|---|---|---|
+| `new Telegraf(token)` | `new Bot(token)` 或 `new Bot({ token, ... })` | |
+| `bot.launch()` | `bot.launch()` / `bot.start()` | `launch` 上显式声明 `mode: "polling"` |
+| `bot.stop()` | `bot.stop()` | telebibz 先排空在途 handler |
+| `bot.use(mw)` | `bot.use(mw)` | 中间件签名相同 `(ctx, next)` |
+| `bot.command(name, h)` | `bot.command(name, h)` | |
+| `bot.on(filter, h)` | `bot.on(filter, h)` | 过滤语法相同（`message:photo`、数组） |
+| `bot.hears(trigger, h)` | `bot.hears(trigger, h)` | 字符串与 RegExp |
+| `bot.action(pattern, h)` | `bot.action(pattern, h)` | `bot.callback` 的直接别名 |
+| `bot.catch(handler)` | `bot.catch(handler)` | 接收 `(error, ctx)` |
+
+## 3. Context 方法
+
+Telegraf context 的每个快捷方法都在 —— 包括 Telegraf 留给插件的那部分：
+
+- **回复**：`reply`、`replyWithPhoto`、`replyWithDocument`、`replyWithVideo`、`replyWithAudio`、`replyWithVoice`、`replyWithAnimation`、`replyWithVideoNote`、`replyWithSticker`、`replyWithMediaGroup`、`replyWithLocation`、`replyWithVenue`、`replyWithContact`、`replyWithPoll`、`replyWithQuiz`、`replyWithDice`、`replyWithGame`、`replyWithInvoice`、`replyWithHTML`、`replyWithMarkdown`（+V2）
+- **管理/群管**：`banChatMember`、`unbanChatMember`、`restrictChatMember`、`promoteChatMember`、`banChatSenderChat`、`unbanChatSenderChat`
+- **聊天**：`setChatTitle`、`setChatDescription`、`setChatPhoto`、`deleteChatPhoto`、`setChatPermissions`、`leaveChat`、`unpinAllChatMessages`、`setChatStickerSet`、`deleteChatStickerSet`
+- **信息**：`getChat`、`getChatAdministrators`、`getChatMemberCount`、`getChatMember`
+- **邀请链接/加群申请**：`exportChatInviteLink`、`createChatInviteLink`、`editChatInviteLink`、`revokeChatInviteLink`、`approveChatJoinRequest`、`declineChatJoinRequest`
+- **实时位置/投票/游戏**：`editMessageLiveLocation`、`stopMessageLiveLocation`、`stopPoll`、`setGameScore`、`getGameHighScores`
+- **论坛**：完整话题方法集（`createForumTopic` … `unhideGeneralForumTopic`）
+- **超越 Telegraf 核心的新增**：`getFile`（带类型）、`downloadFile`、`edit`（改写当前消息文本），以及从包根导出的独立助手 —— `validateUpload`/`assertValidUpload` —— 它们不是 context 方法
+
+移植时需修正的命名差异：`answerCbQuery` → `answerCallbackQuery`；`ctx.telegram` → `ctx.api`；键盘助手来自包根（`InlineKeyboard`、`ReplyKeyboard`、`removeKeyboard`、`forceReply`）而非 `Markup`。
+
+## 4. 启动选项
+
+| Telegraf | telebibz |
+|---|---|
+| `launch({ dropPendingUpdates })` | `launch({ dropPendingUpdates })` —— 完全相同 |
+| `handlerTimeout`（默认 90 000） | `handlerTimeout`（默认 90 000；`0` 禁用） |
+| `contextType` 选项 | `contextType` 选项 —— 你的 `Context` 子类会为每个更新实例化 |
+| `webhookReply`（按更新） | 处理器 / `handleUpdate` 选项上的 `webhookReply` |
+| `telegraf.use(session(...))` | `new Bot({ session: new MemoryStorage() })`（或 JSON/Redis/SQL/Mongo） |
+
+## 5. Scenes → Wizards
+
+Telegraf 的 `WizardScene` + `Stage` 变成单个 `Wizard`：显式步骤、无全局 session 键：
+
+```ts
+import { Bot, Wizard } from "@xbibzlibrary/telebibz";
+
+const wizard = new Wizard()
+  .step({ id: "ask-name", run: async (flow) => { flow.next(); await flow.ctx.reply("名字？"); } })
+  .step({ id: "save", run: async (flow) => { await flow.ctx.reply(`你好 ${flow.ctx.message?.text}！`); } });
+
+const bot = new Bot(process.env.TELEGRAM_BOT_TOKEN!);
+bot.useWizard(wizard);                                    // 取代 Stage 中间件
+bot.command("start", async (ctx) => { await wizard.run(ctx); }); // 取代 scene.enter()
+```
+
+- 向导键自动由 chat + 发送者派生 —— 无需手工管理键。
+- `flow.set(key, value)` / `flow.get(key)` 取代 `ctx.scene.session`。
+- `/cancel` 取消；最后一步完成后对话自动收尾。
+- 非线性流程图请用 `ConversationManager` 配合 router 组合（telebibz 刻意把场景编排留给应用；见 FEATURE_MATRIX 的 "Design decisions"）。
+
+## 6. 会话存储
+
+Telegraf 默认把会话放在内存，持久化需要 store 插件。telebibz 在构造函数上接收 storage —— 换适配器，不换代码：
+
+```ts
+import { Bot, MemoryStorage, JsonFileStorage, RedisStorage } from "@xbibzlibrary/telebibz";
+
+const bot = new Bot({
+  token: process.env.TELEGRAM_BOT_TOKEN!,
+  session: new JsonFileStorage("state/sessions.json"),   // 或 MemoryStorage / RedisStorage / SqlStorage / MongoStorage
+});
+```
+
+每个适配器的完整接线配方：[STORAGE.zh-CN.md](STORAGE.zh-CN.md)。
+
+## 7. Webhook
+
+```ts
+// Telegraf: webhookCallback(bot, app)
+// telebibz: 框架需显式指定
+import { webhookCallback } from "@xbibzlibrary/telebibz";
+app.post("/telegram", webhookCallback(bot, "express", { secretToken: process.env.TELEGRAM_WEBHOOK_SECRET }));
+```
+
+`createWebhookHandler()` 另外提供 Web 标准 `Request → Response` 处理器，适配 Bun/Deno/edge。完整部署指南：[WEBHOOK.zh-CN.md](WEBHOOK.zh-CN.md)。
+
+## 8. 没有直接对应物的部分
+
+- **`bot.telegram` 底层客户端** —— 使用 `bot.api`（`call`、`raw`、`methods`、`downloadFile`）；flood gate 与重试内置于传输层，不能按调用配置。
+- **Telegraf 插件生态** —— 把插件移植为带显式生命周期（`install`、`onStop`、`dispose`）的 `Plugin` 对象；插件管理器可干净重启。
+- **`Composer.mount`/动态 scene** —— 改用 `Router` 嵌套与 `matchMode: "all"` 组合。
+- **Markup 链式助手**（`Markup.keyboard(...).resize()`） —— 使用 `new ReplyKeyboard().text("A").resized().build()`；负载相同，builder 风格。
+
+English: [MIGRATION_TELEGRAF.md](MIGRATION_TELEGRAF.md) · Bahasa Indonesia: [MIGRATION_TELEGRAF.id.md](MIGRATION_TELEGRAF.id.md)

package/docs/README.md

@@ -1,39 +1,58 @@
 # telebibz Documentation
 
-The default documentation language is **English**. Translated README and API references are available below.
+The default documentation language is **English**. Every guide below is available in English, Bahasa Indonesia, and 简体中文.
 
-| Language | README | Complete API reference |
-|---|---|---|
-| English (default) | [`README.md`](../README.md) | [`API.md`](API.md) |
-| Bahasa Indonesia | [`README.id.md`](../README.id.md) | [`API.id.md`](API.id.md) |
-| 简体中文 | [`README.zh-CN.md`](../README.zh-CN.md) | [`API.zh-CN.md`](API.zh-CN.md) |
+| Language | README | Getting started | Complete API reference |
+|---|---|---|---|
+| English (default) | [`README.md`](../README.md) | [`GETTING_STARTED.md`](GETTING_STARTED.md) | [`API.md`](API.md) |
+| Bahasa Indonesia | [`README.id.md`](../README.id.md) | [`GETTING_STARTED.id.md`](GETTING_STARTED.id.md) | [`API.id.md`](API.id.md) |
+| 简体中文 | [`README.zh-CN.md`](../README.zh-CN.md) | [`GETTING_STARTED.zh-CN.md`](GETTING_STARTED.zh-CN.md) | [`API.zh-CN.md`](API.zh-CN.md) |
 
 ![telebibz overview](https://cdn.jsdelivr.net/npm/@xbibzlibrary/telebibz@latest/assets/telebibz-readme-preview.png)
 
-The documentation covers the complete lifecycle: onboarding, bot startup and shutdown, API client and transport, update routing, middleware and context, state/session, interaction UI, background work, deployment, testing, and migration boundaries.
+The documentation covers the complete lifecycle: onboarding, bot startup and shutdown, API client and transport, update routing, middleware and context, state/session, interaction UI, background work, files, errors, webhook deployment, testing, migration, and production recipes.
 
-| Resource | Purpose |
-|---|---|
-| [`GETTING_STARTED.md`](GETTING_STARTED.md) | Five-minute English onboarding from installation to a working bot. |
-| [`GETTING_STARTED.id.md`](GETTING_STARTED.id.md) | Indonesian onboarding guide. |
-| [`GETTING_STARTED.zh-CN.md`](GETTING_STARTED.zh-CN.md) | Simplified Chinese onboarding guide. |
-| [`../examples/README.md`](../examples/README.md) | Runnable minimal, wizard, and webhook starters. |
-| [`../SHOWCASE.md`](../SHOWCASE.md) | Community project showcase and submission format. |
+## Complete guide catalog
+
+Every topic guide ships in three languages (EN · ID · ZH). Pick a topic, pick a language:
+
+| Guide | English | Bahasa Indonesia | 简体中文 | Purpose |
+|---|---|---|---|---|
+| Getting started | [`GETTING_STARTED.md`](GETTING_STARTED.md) | [`GETTING_STARTED.id.md`](GETTING_STARTED.id.md) | [`GETTING_STARTED.zh-CN.md`](GETTING_STARTED.zh-CN.md) | Five-minute onboarding from installation to a working bot. |
+| Complete API reference | [`API.md`](API.md) | [`API.id.md`](API.id.md) | [`API.zh-CN.md`](API.zh-CN.md) | Every exported class, method, type, error, and generated Telegram method. |
+| Files: upload & download | [`FILES.md`](FILES.md) | [`FILES.id.md`](FILES.id.md) | [`FILES.zh-CN.md`](FILES.zh-CN.md) | `downloadFile()`, manual `getFile()`, `file_path` vs `filePath`, upload sources, validation, limits, troubleshooting. |
+| Errors | [`ERRORS.md`](ERRORS.md) | [`ERRORS.id.md`](ERRORS.id.md) | [`ERRORS.zh-CN.md`](ERRORS.zh-CN.md) | Error taxonomy, 429 and the flood gate, `bot.catch()`, `handlerTimeout`, retries, graceful shutdown. |
+| Webhook | [`WEBHOOK.md`](WEBHOOK.md) | [`WEBHOOK.id.md`](WEBHOOK.id.md) | [`WEBHOOK.zh-CN.md`](WEBHOOK.zh-CN.md) | Polling vs webhook, `createWebhookHandler()`, Express/http/Fastify/Koa, `setWebhook`, secret tokens, tunnels, production checklist. |
+| Testing | [`TESTING.md`](TESTING.md) | [`TESTING.id.md`](TESTING.id.md) | [`TESTING.zh-CN.md`](TESTING.zh-CN.md) | Fully offline testing with `MockTransport`, driving updates, wizards end to end, webhooks, error paths, Vitest patterns. |
+| Migration from Telegraf | [`MIGRATION_TELEGRAF.md`](MIGRATION_TELEGRAF.md) | [`MIGRATION_TELEGRAF.id.md`](MIGRATION_TELEGRAF.id.md) | [`MIGRATION_TELEGRAF.zh-CN.md`](MIGRATION_TELEGRAF.zh-CN.md) | Side-by-side port, concept map, context methods, scenes → wizards, webhooks. |
+| Storage | [`STORAGE.md`](STORAGE.md) | [`STORAGE.id.md`](STORAGE.id.md) | [`STORAGE.zh-CN.md`](STORAGE.zh-CN.md) | Memory/JSON/Redis/SQL/Mongo adapters, TTL, atomic `update()`. |
+| Production cookbook | [`COOKBOOK.md`](COOKBOOK.md) | [`COOKBOOK.id.md`](COOKBOOK.id.md) | [`COOKBOOK.zh-CN.md`](COOKBOOK.zh-CN.md) | Thirteen verified recipes: rate limiting, auth, broadcast, scheduling, queues, menus, forms, caching, Mini Apps, payments, metrics. |
+| GitHub Packages install | [`GITHUB_PACKAGES.md`](GITHUB_PACKAGES.md) | [`GITHUB_PACKAGES.id.md`](GITHUB_PACKAGES.id.md) | [`GITHUB_PACKAGES.zh-CN.md`](GITHUB_PACKAGES.zh-CN.md) | Installing via GitHub Packages with a personal access token. |
+
+Also available: [`../examples/README.md`](../examples/README.md) — runnable minimal, wizard, file, and webhook starters, and [`../SHOWCASE.md`](../SHOWCASE.md) — community project showcase.
+
+## Coverage status
 
 | Area | Status |
 |---|---|
-| Getting started | Dedicated guides are available in English, Indonesian, and Simplified Chinese, with runnable examples. |
-| Complete API reference | Available in English, Indonesian, and Simplified Chinese |
+| Getting started | Dedicated guides in EN/ID/ZH with runnable examples |
+| Complete API reference | Available in EN/ID/ZH |
 | Bot lifecycle, polling, webhook | Core implementation, per-update error isolation, reconnect backoff, and tests available |
-| API client and generated method list | Available; full vendored Telegram declarations are exposed through `TelegramTypes` |
+| API client and generated method list | Available; full vendored Telegram declarations exposed through `TelegramTypes` |
 | Router, middleware, context | Available and tested; first-match is default, all-match is explicit |
 | Keyboard, callback, menus, pagination | Keyboard/callback core, permission menus, MenuController, and pagination available |
 | Sessions, conversations, wizards, forms | Storage-backed session/conversation primitives and forms available; scene orchestration remains application-owned |
 | Storage, cache, queue, scheduler | Memory, JSON file, Redis, SQL, Mongo driver adapters, cache, queue, and full five-field cron available |
+| Files | Dedicated guide: one-call `downloadFile()`, upload sources, validation, limits, troubleshooting (EN/ID/ZH) |
+| Errors | Dedicated guide: taxonomy, 429/flood gate, boundaries, timeouts, retries (EN/ID/ZH) |
+| Webhook deployment | Dedicated guide: handler, four frameworks, registration, secrets, tunnels, checklist (EN/ID/ZH) |
+| Testing | Dedicated guide: MockTransport, update drivers, wizards, webhooks, error paths (EN/ID/ZH) |
+| Migration | Dedicated Telegraf migration guide (EN/ID/ZH) |
+| Production recipes | Cookbook with thirteen verified recipes (EN/ID/ZH) |
 | Plugins, services, observability | Lifecycle/plugin/service hooks available |
 | Mini Apps, payments, business features | Web App signature validation and PaymentsClient wrappers available; UI is application-owned |
 | Testing and security | Unit, integration, type-level, gated E2E, CI, and security policy available |
-| Deployment and migration | Release automation is documented in `RELEASE_AUTOMATION.md`; webhook and deployment onboarding is in `GETTING_STARTED.md` |
+| Deployment and migration | Release automation is documented in `RELEASE_AUTOMATION.md`; webhook deployment is in `WEBHOOK.md` |
 | Governance and community | `CODE_OF_CONDUCT.md`, `GOVERNANCE.md`, `CONTRIBUTING.md`, `CONTRIBUTION_RULES.md`, and `SHOWCASE.md` |
 | Security and support | `SECURITY.md` and `SUPPORT.md` |
 | Third-party notices | `NOTICE.md` and `LICENSE` |
@@ -45,4 +64,4 @@ Issue forms are available for bug reports, feature requests, documentation probl
 
 ## Documentation principle
 
-The documentation describes only capabilities that are implemented and tested in the current package. Telegram-native API access, Mini App/Web App behavior, external persistence, and distributed adapters are described separately so the documentation does not promise features that are not included.
+The documentation describes only capabilities that are implemented and tested in the current package, and every code snippet in the guides is verified against the actual implementation. Telegram-native API access, Mini App/Web App behavior, external persistence, and distributed adapters are described separately so the documentation does not promise features that are not included.

package/docs/TESTING.id.md

@@ -0,0 +1,203 @@
+# Panduan testing (Bahasa Indonesia)
+
+Uji bot telebibz sepenuhnya offline: palsukan transport, rakit update, asersikan panggilan keluar, dan jalankan conversation utuh end-to-end.
+
+## Daftar isi
+
+1. [Subpath testing](#1-subpath-testing)
+2. [MockTransport](#2-mocktransport)
+3. [Men-drive update ke dalam bot](#3-men-drive-update-ke-dalam-bot)
+4. [Asersi panggilan keluar](#4-asersi-panggilan-keluar)
+5. [Menguji wizard end-to-end](#5-menguji-wizard-end-to-end)
+6. [Menguji unduhan file](#6-menguji-unduhan-file)
+7. [Menguji webhook](#7-menguji-webhook)
+8. [Menguji jalur error](#8-menguji-jalur-error)
+9. [Pola Vitest / Jest](#9-pola-vitest--jest)
+
+## 1. Subpath testing
+
+Semuanya tersedia dari `@xbibzlibrary/telebibz/testing`:
+
+```ts
+import { MockTransport, createTestBot, createMockUpdate, createMockCallbackUpdate, createMockContext } from "@xbibzlibrary/telebibz/testing";
+```
+
+- `createTestBot()` → `{ bot, transport }` — sebuah `Bot` yang terhubung ke `MockTransport`, branding dimatikan.
+- `createMockUpdate(overrides?)` → update pesan teks `/start` sederhana.
+- `createMockCallbackUpdate(overrides?)` → update callback-query.
+- `createMockContext(bot, update?)` → sebuah `Context` tanpa me-routing apa pun.
+
+## 2. MockTransport
+
+`MockTransport` merekam setiap request keluar dan menjawab dari response yang dikonfigurasi:
+
+```ts
+const { bot, transport } = createTestBot();
+
+transport.respond("getMe", { ok: true, result: { id: 99, is_bot: true, first_name: "TestBot", username: "test_bot" } });
+transport.respond("sendMessage", { ok: true, result: { message_id: 1, date: 0, chat: { id: 1, type: "private" } } });
+transport.respond("getFile", (payload) => ({                                   // jawaban dinamis
+  ok: true,
+  result: { file_id: (payload as { file_id: string }).file_id, file_unique_id: "u", file_path: "documents/a.pdf" },
+}));
+```
+
+Method yang tidak dikonfigurasi menjawab `{ ok: true, result: true }` — cukup untuk panggilan yang hasilnya Anda abaikan.
+
+Ia juga mengimplementasikan member download:
+
+```ts
+transport.downloadBytes = new TextEncoder().encode("file-content");
+transport.downloads;            // setiap file_path yang diberikan ke download(), berurutan
+transport.fileUrl("a.pdf");     // "mock://files/a.pdf"
+```
+
+## 3. Men-drive update ke dalam bot
+
+Daftarkan handler, lalu kirim update — tanpa jaringan, tanpa token:
+
+```ts
+bot.on("message", async (ctx) => { await ctx.reply("hi"); });
+await bot.init();                       // tepat satu getMe, seperti produksi
+
+await bot.handleUpdate(createMockUpdate({ message: { ...createMockUpdate().message!, text: "hello" } }));
+await bot.handleUpdates([updateA, updateB, updateC]);   // satu batch penuh, paralel antar chat
+```
+
+Untuk mensimulasikan beberapa chat, variasikan chat id:
+
+```ts
+function textUpdate(updateId: number, chatId: number, text: string) {
+  const base = createMockUpdate();
+  return { ...base, update_id: updateId, message: { ...base.message!, chat: { id: chatId, type: "private" as const }, text } };
+}
+```
+
+## 4. Asersi panggilan keluar
+
+Setiap request tercatat di `transport.calls` lengkap dengan method dan payload-nya:
+
+```ts
+const replies = transport.calls
+  .filter((call) => call.method === "sendMessage")
+  .map((call) => (call.payload as { text?: string }).text);
+
+expect(replies).toEqual(["Siapa nama Anda?", "Berapa usia Anda?"]);
+
+// Keyboard callback:
+const markup = (transport.calls.at(-1)?.payload as { reply_markup?: { inline_keyboard: unknown[][] } }).reply_markup;
+expect(markup?.inline_keyboard).toHaveLength(2);
+```
+
+## 5. Menguji wizard end-to-end
+
+Berikan conversation satu pesan demi satu pesan dan asersikan balasan yang akan dilihat user:
+
+```ts
+import { Bot, Wizard } from "@xbibzlibrary/telebibz";
+
+const wizard = new Wizard()
+  .step({ id: "ask", run: async (flow) => { flow.next(); await flow.ctx.reply("Siapa nama Anda?"); } })
+  .step({ id: "save", run: async (flow) => { await flow.ctx.reply(`Halo, ${flow.ctx.message?.text}!`); } });
+bot.useWizard(wizard);
+bot.command("start", async (ctx) => { await wizard.run(ctx); });
+
+await bot.handleUpdate(textUpdate(1, 7, "/start"));
+await bot.handleUpdate(textUpdate(2, 7, "Dewi"));
+
+expect(sentTexts()).toEqual(["Siapa nama Anda?", "Halo, Dewi!"]);
+```
+
+Dua chat, dua wizard independen — update yang berselang-seling tetap terisolasi karena update dari chat yang sama diserialisasi:
+
+```ts
+await bot.handleUpdate(textUpdate(1, 7, "/start"));
+await bot.handleUpdate(textUpdate(2, 8, "/start"));
+await bot.handleUpdate(textUpdate(3, 7, "Dewi"));
+await bot.handleUpdate(textUpdate(4, 8, "Budi"));
+expect(sentTexts()).toEqual(["Siapa nama Anda?", "Siapa nama Anda?", "Halo, Dewi!", "Halo, Budi!"]);
+```
+
+## 6. Menguji unduhan file
+
+```ts
+transport.respond("getFile", { ok: true, result: { file_id: "F1", file_unique_id: "U1", file_path: "photos/pic.jpg" } });
+transport.downloadBytes = new TextEncoder().encode("jpeg-bytes");
+
+const file = await bot.downloadFile("F1", { destination: tmpFile });
+expect(file.fileName).toBe("pic.jpg");
+expect(transport.downloads).toEqual(["photos/pic.jpg"]);
+expect(await readFile(tmpFile, "utf8")).toBe("jpeg-bytes");
+```
+
+## 7. Menguji webhook
+
+`createWebhookHandler` menerima `Request` Web sungguhan:
+
+```ts
+const handler = createWebhookHandler(bot, { secretToken: "s3cret" });
+
+const response = await handler(new Request("https://example.com/telegram", {
+  method: "POST",
+  headers: { "content-type": "application/json", "x-telegram-bot-api-secret-token": "s3cret" },
+  body: JSON.stringify(createMockUpdate()),
+}));
+expect(response.status).toBe(200);
+
+// Secret salah → ditolak sebelum handler mana pun berjalan
+const rejected = await handler(new Request("https://example.com/telegram", {
+  method: "POST",
+  headers: { "content-type": "application/json", "x-telegram-bot-api-secret-token": "salah" },
+  body: JSON.stringify(createMockUpdate()),
+}));
+expect(rejected.status).toBe(401);
+```
+
+## 8. Menguji jalur error
+
+```ts
+// Telegram menolak panggilan
+transport.respond("sendMessage", { ok: false, error_code: 400, description: "Bad Request: chat not found" });
+await expect(ctx.reply("hi")).rejects.toThrow(/chat not found/);
+
+// Handler melempar — asersikan error boundary melihatnya
+const errors: unknown[] = [];
+bot.events.on("update:error", ({ error }) => errors.push(error));
+bot.onText("boom", async () => { throw new Error("boom"); });
+await bot.handleUpdate(textUpdate(1, 7, "boom"));
+expect(errors).toHaveLength(1);
+
+// handlerTimeout: update yang menggantung melempar UpdateTimeoutError sementara handler tetap berjalan
+const slow = new Bot({ token: "123456:TEST", transport, handlerTimeout: 50, branding: false, logger: { level: "silent" } });
+let finished = false;
+slow.on("message", async () => { await sleep(200); finished = true; });
+await expect(slow.handleUpdate(createMockUpdate())).rejects.toBeInstanceOf(UpdateTimeoutError);
+// nanti:
+expect(finished).toBe(true);
+```
+
+## 9. Pola Vitest / Jest
+
+**Senyapkan logger di test** — `logger: { level: "silent" }` tidak memancarkan apa pun (diuji regresi):
+
+```ts
+const bot = new Bot({ token: "123456:TEST", transport, branding: false, logger: { level: "silent" } });
+```
+
+**Transport segar per test** — jangan pernah berbagi state antar kasus:
+
+```ts
+beforeEach(() => { ({ bot, transport } = createTestBot()); });
+```
+
+**Mempercepat waktu** — untuk test `Scheduler`/TTL pakai fake timer atau interval kecil (`1ms`); parser cron murni dan bisa diuji tanpa timer:
+
+```ts
+import { nextCronOccurrence, parseCronExpression } from "@xbibzlibrary/telebibz";
+expect(parseCronExpression("*/15 * * * *")).toBeDefined();
+expect(nextCronOccurrence("0 9 * * 1", new Date("2026-08-29T00:00:00Z")).toISOString()).toContain("T09:00");
+```
+
+**Jalankan suite**: `npm test` — test E2E yang membutuhkan token asli otomatis di-skip ketika `TELEGRAM_BOT_TOKEN` tidak ada.
+
+English: [TESTING.md](TESTING.md) · 简体中文: [TESTING.zh-CN.md](TESTING.zh-CN.md)

package/docs/TESTING.md

@@ -0,0 +1,203 @@
+# Testing guide (English)
+
+Test telebibz bots fully offline: fake the transport, craft updates, assert outgoing calls, and drive whole conversations end to end.
+
+## Contents
+
+1. [The testing subpath](#1-the-testing-subpath)
+2. [MockTransport](#2-mocktransport)
+3. [Driving updates through the bot](#3-driving-updates-through-the-bot)
+4. [Asserting outgoing calls](#4-asserting-outgoing-calls)
+5. [Testing wizards end to end](#5-testing-wizards-end-to-end)
+6. [Testing file downloads](#6-testing-file-downloads)
+7. [Testing webhooks](#7-testing-webhooks)
+8. [Testing error paths](#8-testing-error-paths)
+9. [Vitest / Jest patterns](#9-vitest--jest-patterns)
+
+## 1. The testing subpath
+
+Everything ships from `@xbibzlibrary/telebibz/testing`:
+
+```ts
+import { MockTransport, createTestBot, createMockUpdate, createMockCallbackUpdate, createMockContext } from "@xbibzlibrary/telebibz/testing";
+```
+
+- `createTestBot()` → `{ bot, transport }` — a `Bot` wired to a `MockTransport`, branding off.
+- `createMockUpdate(overrides?)` → a plain text `/start` message update.
+- `createMockCallbackUpdate(overrides?)` → a callback-query update.
+- `createMockContext(bot, update?)` → a `Context` without routing anything.
+
+## 2. MockTransport
+
+`MockTransport` records every outgoing request and answers from configured responses:
+
+```ts
+const { bot, transport } = createTestBot();
+
+transport.respond("getMe", { ok: true, result: { id: 99, is_bot: true, first_name: "TestBot", username: "test_bot" } });
+transport.respond("sendMessage", { ok: true, result: { message_id: 1, date: 0, chat: { id: 1, type: "private" } } });
+transport.respond("getFile", (payload) => ({                                   // dynamic answers
+  ok: true,
+  result: { file_id: (payload as { file_id: string }).file_id, file_unique_id: "u", file_path: "documents/a.pdf" },
+}));
+```
+
+Unconfigured methods answer `{ ok: true, result: true }` — enough for calls whose result you ignore.
+
+It also implements the download members:
+
+```ts
+transport.downloadBytes = new TextEncoder().encode("file-content");
+transport.downloads;            // every file_path passed to download(), in order
+transport.fileUrl("a.pdf");     // "mock://files/a.pdf"
+```
+
+## 3. Driving updates through the bot
+
+Register handlers, then feed updates — no network, no token:
+
+```ts
+bot.on("message", async (ctx) => { await ctx.reply("hi"); });
+await bot.init();                       // exactly one getMe, like production
+
+await bot.handleUpdate(createMockUpdate({ message: { ...createMockUpdate().message!, text: "hello" } }));
+await bot.handleUpdates([updateA, updateB, updateC]);   // whole batch, parallel across chats
+```
+
+To simulate several chats, vary the chat id:
+
+```ts
+function textUpdate(updateId: number, chatId: number, text: string) {
+  const base = createMockUpdate();
+  return { ...base, update_id: updateId, message: { ...base.message!, chat: { id: chatId, type: "private" as const }, text } };
+}
+```
+
+## 4. Asserting outgoing calls
+
+Every request is recorded in `transport.calls` with its method and payload:
+
+```ts
+const replies = transport.calls
+  .filter((call) => call.method === "sendMessage")
+  .map((call) => (call.payload as { text?: string }).text);
+
+expect(replies).toEqual(["What is your name?", "How old are you?"]);
+
+// Callback keyboards:
+const markup = (transport.calls.at(-1)?.payload as { reply_markup?: { inline_keyboard: unknown[][] } }).reply_markup;
+expect(markup?.inline_keyboard).toHaveLength(2);
+```
+
+## 5. Testing wizards end to end
+
+Feed the conversation one message at a time and assert the replies the user would see:
+
+```ts
+import { Bot, Wizard } from "@xbibzlibrary/telebibz";
+
+const wizard = new Wizard()
+  .step({ id: "ask", run: async (flow) => { flow.next(); await flow.ctx.reply("Name?"); } })
+  .step({ id: "save", run: async (flow) => { await flow.ctx.reply(`Hi ${flow.ctx.message?.text}!`); } });
+bot.useWizard(wizard);
+bot.command("start", async (ctx) => { await wizard.run(ctx); });
+
+await bot.handleUpdate(textUpdate(1, 7, "/start"));
+await bot.handleUpdate(textUpdate(2, 7, "Alice"));
+
+expect(sentTexts()).toEqual(["Name?", "Hi Alice!"]);
+```
+
+Two chats, two independent wizards — interleaved updates stay isolated because same-chat updates serialize:
+
+```ts
+await bot.handleUpdate(textUpdate(1, 7, "/start"));
+await bot.handleUpdate(textUpdate(2, 8, "/start"));
+await bot.handleUpdate(textUpdate(3, 7, "Alice"));
+await bot.handleUpdate(textUpdate(4, 8, "Bob"));
+expect(sentTexts()).toEqual(["Name?", "Name?", "Hi Alice!", "Hi Bob!"]);
+```
+
+## 6. Testing file downloads
+
+```ts
+transport.respond("getFile", { ok: true, result: { file_id: "F1", file_unique_id: "U1", file_path: "photos/pic.jpg" } });
+transport.downloadBytes = new TextEncoder().encode("jpeg-bytes");
+
+const file = await bot.downloadFile("F1", { destination: tmpFile });
+expect(file.fileName).toBe("pic.jpg");
+expect(transport.downloads).toEqual(["photos/pic.jpg"]);
+expect(await readFile(tmpFile, "utf8")).toBe("jpeg-bytes");
+```
+
+## 7. Testing webhooks
+
+`createWebhookHandler` accepts a real Web `Request`:
+
+```ts
+const handler = createWebhookHandler(bot, { secretToken: "s3cret" });
+
+const response = await handler(new Request("https://example.com/telegram", {
+  method: "POST",
+  headers: { "content-type": "application/json", "x-telegram-bot-api-secret-token": "s3cret" },
+  body: JSON.stringify(createMockUpdate()),
+}));
+expect(response.status).toBe(200);
+
+// Wrong secret → rejected before any handler runs
+const rejected = await handler(new Request("https://example.com/telegram", {
+  method: "POST",
+  headers: { "content-type": "application/json", "x-telegram-bot-api-secret-token": "wrong" },
+  body: JSON.stringify(createMockUpdate()),
+}));
+expect(rejected.status).toBe(401);
+```
+
+## 8. Testing error paths
+
+```ts
+// Telegram rejects the call
+transport.respond("sendMessage", { ok: false, error_code: 400, description: "Bad Request: chat not found" });
+await expect(ctx.reply("hi")).rejects.toThrow(/chat not found/);
+
+// A handler throws — assert the error boundary saw it
+const errors: unknown[] = [];
+bot.events.on("update:error", ({ error }) => errors.push(error));
+bot.onText("boom", async () => { throw new Error("boom"); });
+await bot.handleUpdate(textUpdate(1, 7, "boom"));
+expect(errors).toHaveLength(1);
+
+// handlerTimeout: hung updates reject with UpdateTimeoutError while the handler keeps running
+const slow = new Bot({ token: "123456:TEST", transport, handlerTimeout: 50, branding: false, logger: { level: "silent" } });
+let finished = false;
+slow.on("message", async () => { await sleep(200); finished = true; });
+await expect(slow.handleUpdate(createMockUpdate())).rejects.toBeInstanceOf(UpdateTimeoutError);
+// later:
+expect(finished).toBe(true);
+```
+
+## 9. Vitest / Jest patterns
+
+**Silence the logger in tests** — `logger: { level: "silent" }` emits nothing (regression-tested):
+
+```ts
+const bot = new Bot({ token: "123456:TEST", transport, branding: false, logger: { level: "silent" } });
+```
+
+**Fresh transport per test** — never share state between cases:
+
+```ts
+beforeEach(() => { ({ bot, transport } = createTestBot()); });
+```
+
+**Fast-forwarding time** — for `Scheduler`/TTL tests use fake timers or small intervals (`1ms`); the cron parser is pure and testable without timers:
+
+```ts
+import { nextCronOccurrence, parseCronExpression } from "@xbibzlibrary/telebibz";
+expect(parseCronExpression("*/15 * * * *")).toBeDefined();
+expect(nextCronOccurrence("0 9 * * 1", new Date("2026-08-29T00:00:00Z")).toISOString()).toContain("T09:00");
+```
+
+**Run the suite**: `npm test` — E2E tests requiring a real token are skipped automatically when `TELEGRAM_BOT_TOKEN` is absent.
+
+Bahasa Indonesia: [TESTING.id.md](TESTING.id.md) · 简体中文: [TESTING.zh-CN.md](TESTING.zh-CN.md)