@xbibzlibrary/telebibz 0.4.4 → 0.4.5

package/docs/TESTING.zh-CN.md

@@ -0,0 +1,203 @@
+# 测试指南（简体中文）
+
+完全离线地测试 telebibz bot：伪造传输层、构造更新、断言外发调用，并端到端驱动整段对话。
+
+## 目录
+
+1. [testing 子路径](#1-testing-子路径)
+2. [MockTransport](#2-mocktransport)
+3. [把更新送进 bot](#3-把更新送进-bot)
+4. [断言外发调用](#4-断言外发调用)
+5. [端到端测试向导](#5-端到端测试向导)
+6. [测试文件下载](#6-测试文件下载)
+7. [测试 webhook](#7-测试-webhook)
+8. [测试错误路径](#8-测试错误路径)
+9. [Vitest / Jest 模式](#9-vitest--jest-模式)
+
+## 1. testing 子路径
+
+所有工具都从 `@xbibzlibrary/telebibz/testing` 导出：
+
+```ts
+import { MockTransport, createTestBot, createMockUpdate, createMockCallbackUpdate, createMockContext } from "@xbibzlibrary/telebibz/testing";
+```
+
+- `createTestBot()` → `{ bot, transport }` —— 连接到 `MockTransport` 的 `Bot`，branding 已关闭。
+- `createMockUpdate(overrides?)` → 一条普通 `/start` 文本消息更新。
+- `createMockCallbackUpdate(overrides?)` → 一条回调查询更新。
+- `createMockContext(bot, update?)` → 不经过路由的 `Context`。
+
+## 2. MockTransport
+
+`MockTransport` 记录每个外发请求，并按配置应答：
+
+```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) => ({                                   // 动态应答
+  ok: true,
+  result: { file_id: (payload as { file_id: string }).file_id, file_unique_id: "u", file_path: "documents/a.pdf" },
+}));
+```
+
+未配置的方法应答 `{ ok: true, result: true }` —— 对结果无所谓的调用足够了。
+
+它还实现了下载成员：
+
+```ts
+transport.downloadBytes = new TextEncoder().encode("file-content");
+transport.downloads;            // 每个传给 download() 的 file_path，按顺序
+transport.fileUrl("a.pdf");     // "mock://files/a.pdf"
+```
+
+## 3. 把更新送进 bot
+
+注册 handler，然后投喂更新 —— 无网络、无 token：
+
+```ts
+bot.on("message", async (ctx) => { await ctx.reply("hi"); });
+await bot.init();                       // 恰好一次 getMe，与生产一致
+
+await bot.handleUpdate(createMockUpdate({ message: { ...createMockUpdate().message!, text: "hello" } }));
+await bot.handleUpdates([updateA, updateB, updateC]);   // 整批投喂，跨 chat 并行
+```
+
+模拟多个 chat 时，变换 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. 断言外发调用
+
+每个请求连同 method 与 payload 记录在 `transport.calls`：
+
+```ts
+const replies = transport.calls
+  .filter((call) => call.method === "sendMessage")
+  .map((call) => (call.payload as { text?: string }).text);
+
+expect(replies).toEqual(["你叫什么名字？", "你多大了？"]);
+
+// 回调键盘：
+const markup = (transport.calls.at(-1)?.payload as { reply_markup?: { inline_keyboard: unknown[][] } }).reply_markup;
+expect(markup?.inline_keyboard).toHaveLength(2);
+```
+
+## 5. 端到端测试向导
+
+逐条消息推进对话，并断言用户将看到的回复：
+
+```ts
+import { Bot, Wizard } from "@xbibzlibrary/telebibz";
+
+const wizard = new Wizard()
+  .step({ id: "ask", run: async (flow) => { flow.next(); await flow.ctx.reply("你叫什么名字？"); } })
+  .step({ id: "save", run: async (flow) => { await flow.ctx.reply(`你好，${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, "小明"));
+
+expect(sentTexts()).toEqual(["你叫什么名字？", "你好，小明！"]);
+```
+
+两个 chat、两个独立向导 —— 交错投喂依然隔离，因为同一 chat 的更新按序串行：
+
+```ts
+await bot.handleUpdate(textUpdate(1, 7, "/start"));
+await bot.handleUpdate(textUpdate(2, 8, "/start"));
+await bot.handleUpdate(textUpdate(3, 7, "小明"));
+await bot.handleUpdate(textUpdate(4, 8, "小红"));
+expect(sentTexts()).toEqual(["你叫什么名字？", "你叫什么名字？", "你好，小明！", "你好，小红！"]);
+```
+
+## 6. 测试文件下载
+
+```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. 测试 webhook
+
+`createWebhookHandler` 接受真实的 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);
+
+// 错误 secret → 在任何 handler 运行前被拒绝
+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. 测试错误路径
+
+```ts
+// Telegram 拒绝调用
+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 抛异常 —— 断言错误边界看到了它
+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：挂起的更新以 UpdateTimeoutError 拒绝，而 handler 继续运行
+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);
+// 稍后：
+expect(finished).toBe(true);
+```
+
+## 9. Vitest / Jest 模式
+
+**测试中静音 logger** —— `logger: { level: "silent" }` 不输出任何内容（有回归测试）：
+
+```ts
+const bot = new Bot({ token: "123456:TEST", transport, branding: false, logger: { level: "silent" } });
+```
+
+**每个测试全新 transport** —— 不要在用例间共享状态：
+
+```ts
+beforeEach(() => { ({ bot, transport } = createTestBot()); });
+```
+
+**快进时间** —— `Scheduler`/TTL 测试用假定时器或小间隔（`1ms`）；cron 解析器是纯函数，无需定时器：
+
+```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");
+```
+
+**运行套件**：`npm test` —— 缺少 `TELEGRAM_BOT_TOKEN` 时，需要真实 token 的 E2E 测试自动跳过。
+
+English: [TESTING.md](TESTING.md) · Bahasa Indonesia: [TESTING.id.md](TESTING.id.md)

package/docs/WEBHOOK.id.md

@@ -0,0 +1,212 @@
+# Webhook (Bahasa Indonesia)
+
+Cara melayani update lewat webhook — untuk platform tanpa long-polling (serverless, container), atau saat butuh endpoint terbuka HTTPS.
+
+## Daftar isi
+
+1. [Polling vs webhook](#1-polling-vs-webhook)
+2. [Handler: `createWebhookHandler()`](#2-handler-createwebhookhandler)
+3. [Framework populer](#3-framework-populer)
+4. [Mendaftarkan URL ke Telegram](#4-mendaftarkan-url-ke-telegram)
+5. [Secret token](#5-secret-token)
+6. [Mode `webhookReply`](#6-mode-webhookreply)
+7. [Local development dengan tunnel](#7-local-development-dengan-tunnel)
+8. [Checklist produksi](#8-checklist-produksi)
+9. [Troubleshooting](#9-troubleshooting)
+
+## 1. Polling vs webhook
+
+| | Polling (`bot.start()`) | Webhook |
+|---|---|---|
+| Menghubungi Telegram | Ya (long-polling) | Tidak — Telegram yang menghubungi Anda |
+| Butuh domain + HTTPS publik | Tidak | Ya |
+| Cocok untuk | Skrip lokal, development, VPS | Serverless (Lambda/Workers/Cloud Functions), container, k8s |
+| Konkurensi | Pipeline per-update yang sama | Pipeline per-update yang sama |
+| Menerima `POST /<path>` Anda sendiri | — | Ya — handler mengembalikan `Response`, routing tetap milik Anda |
+
+Hanya satu yang aktif: Telegram mengirim update ke webhook terdaftar dan mengabaikan `getUpdates` selama webhook aktif.
+
+## 2. Handler: `createWebhookHandler()`
+
+Handler menerima **Web-standard `Request`** dan mengembalikan **`Response`** — berjalan di Node, Bun, Deno, dan edge runtime:
+
+```ts
+import { createWebhookHandler } from "@xbibzlibrary/telebibz";
+
+const handleUpdate = createWebhookHandler(bot, {
+  secretToken: process.env.TELEGRAM_WEBHOOK_SECRET,  // verifikasi X-Telegram-Bot-Api-Secret-Token
+  webhookReply: true,                                 // jawab API via body respons (opsional)
+});
+
+export default {
+  async fetch(request: Request): Promise<Response> {
+    if (request.method === "POST" && new URL(request.url).pathname === "/telegram") {
+      return handleUpdate(request);
+    }
+    return new Response("Not Found", { status: 404 });
+  },
+};
+```
+
+- Body > 1 MB → `413 Payload Too Large` (atur `maxBodyBytes`).
+- Secret salah → `401 Unauthorized`.
+- Method non-POST → `405 Method Not Allowed`.
+- Update diproses via pipeline normal — error handler, session, conversation, semuanya bekerja.
+
+Untuk server Node ala Express (objek req/res, bukan `Request`), gunakan `webhookCallback()` — lihat [Framework populer](#3-framework-populer).
+
+## 3. Framework populer
+
+### Express
+
+```ts
+import express from "express";
+import { webhookCallback } from "@xbibzlibrary/telebibz";
+
+const app = express();
+app.use(express.json({ limit: "1mb" }));
+app.post("/telegram", webhookCallback(bot, "express", { secretToken: process.env.TELEGRAM_WEBHOOK_SECRET }));
+app.listen(3000);
+```
+
+### Node `http`
+
+```ts
+import http from "node:http";
+import { webhookCallback } from "@xbibzlibrary/telebibz";
+
+const callback = webhookCallback(bot, "http", { secretToken: process.env.TELEGRAM_WEBHOOK_SECRET });
+http
+  .createServer(async (req, res) => {
+    if (req.method === "POST" && req.url === "/telegram") return callback(req, res);
+    res.writeHead(404).end();
+  })
+  .listen(3000);
+```
+
+### Fastify
+
+```ts
+import Fastify from "fastify";
+import { webhookCallback } from "@xbibzlibrary/telebibz";
+
+const fastify = Fastify({ bodyLimit: 1_048_576 });
+fastify.post("/telegram", (req, reply) => webhookCallback(bot, "fastify", { secretToken: process.env.TELEGRAM_WEBHOOK_SECRET })(req, reply));
+await fastify.listen({ port: 3000 });
+```
+
+### Koa (dengan `koa-bodyparser` agar `ctx.request.body` terisi)
+
+```ts
+import Koa from "koa";
+import bodyParser from "koa-bodyparser";
+import { webhookCallback } from "@xbibzlibrary/telebibz";
+
+const app = new Koa();
+app.use(bodyParser());
+app.use(async (ctx) => {
+  if (ctx.method === "POST" && ctx.path === "/telegram") {
+    await webhookCallback(bot, "koa", { secretToken: process.env.TELEGRAM_WEBHOOK_SECRET })(ctx.request, ctx);
+    return;
+  }
+  ctx.status = 404;
+});
+app.listen(3000);
+```
+
+## 4. Mendaftarkan URL ke Telegram
+
+Webhook hanya mengirim ke URL yang Anda daftarkan. Setelah server jalan di URL publik, panggil `setWebhook` sekali:
+
+```ts
+const secret = process.env.TELEGRAM_WEBHOOK_SECRET;
+
+await bot.api.methods.setWebhook({
+  url: "https://bot.example.com/telegram",
+  secret_token: secret,                 // sama persis dengan secretToken handler
+  max_connections: 40,                  // default 40; sesuaikan dengan kapasitas
+  allowed_updates: ["message", "callback_query"],  // opsional: kurangi trafik
+  drop_pending_updates: false,
+});
+```
+
+**Menghentikan webhook** — dua opsi:
+
+```ts
+await bot.api.methods.deleteWebhook({ drop_pending_updates: true }); // kembali ke polling
+```
+
+Saat bot Anda berjalan di local Bot API server, `setWebhook` juga menerima `ip_address` untuk menghindari resolusi DNS publik.
+
+## 5. Secret token
+
+Tanpa secret, siapa pun yang tahu URL bisa mengirim update palsu. Secret memverifikasi bahwa request berasal dari Telegram:
+
+```bash
+openssl rand -hex 32
+```
+
+Simpan sebagai environment variable dan berikan **nilai yang sama persis** ke `setWebhook` (parameter `secret_token`) dan ke handler (opsi `secretToken`). Perbandingan dilakukan constant-time — tidak bisa diTiming-attack. Aturan: 1–256 karakter dari `A-Z a-z 0-9 _ -`.
+
+Perhatikan `webhookReply` **tidak** terkait secret — mode itu memilih *bagaimana* respons API dikirim, bukan siapa pengirimnya.
+
+## 6. Mode `webhookReply`
+
+Telegram mengizinkan bot menjawab satu panggilan API langsung di body respons webhook. Mengaktifkan mode ini menghilangkan satu round-trip per balasan — sangat berguna di serverless:
+
+```ts
+const handleUpdate = createWebhookHandler(bot, { webhookReply: true });
+```
+
+Hanya **satu** panggilan API per update yang mendapat manfaat ini — panggilan pertama yang selesai menang; sisanya dikirim sebagai request HTTP normal. Ketika body respons sudah dipakai, handler mengembalikan `{}` (Telegram tetap menganggapnya sukses).
+
+Telegraf menyebutnya `telegram.webhookReply`; konsep dan default-nya sama persi di telebibz.
+
+## 7. Local development dengan tunnel
+
+Telegram hanya mengirim ke URL **publik HTTPS**. Saat development, arahkan URL publik ke localhost:
+
+```bash
+# cloudflared (tanpa akun)
+cloudflared tunnel --url http://localhost:3000
+
+# atau ngrok
+ngrok http 3000
+```
+
+Lalu daftarkan URL yang dihasilkan:
+
+```bash
+TOKEN="…"
+URL="https://random-words.loca.lt"   # dari output tunnel
+SECRET="…"
+curl "https://api.telegram.org/bot$TOKEN/setWebhook" \
+  -d "url=$URL/telegram" -d "secret_token=$SECRET"
+```
+
+Lepas webhook setelah selesai (`deleteWebhook`) agar `bot.start()` berfungsi kembali.
+
+## 8. Checklist produksi
+
+- [ ] HTTPS publik + sertifikat valid (Telegram menolak self-signed)
+- [ ] `secret_token` ter-set dan cocok di kedua sisi
+- [ ] `max_connections` disetel (default 40)
+- [ ] Body parser limit ≥ 1 MB (`express.json({ limit: "1mb" })` dkk.)
+- [ ] Timeout upstream > `handlerTimeout` (agar `UpdateTimeoutError` sempat mengambil alih, bukan 504 load balancer)
+- [ ] `drop_pending_updates` dipertimbangkan saat redeploy
+- [ ] Error ter-observasi: `bot.catch()` + `update:error`
+- [ ] Graceful shutdown: `bot.stop()` sebelum exit
+
+## 9. Troubleshooting
+
+| Gejala | Penyebab | Perbaikan |
+|---|---|---|
+| Telegram selalu timeout (baris `getUpdates` kosong) | Webhook aktif — Telegram mengabaikan polling | `deleteWebhook` atau gunakan handler |
+| 401 di setiap request | Secret handler ≠ `secret_token` yang terdaftar | Samakan nilainya di `setWebhook` dan handler |
+| 413 Payload Too Large | Body melebihi `maxBodyBytes` (default 1 MB) | Naikkan `maxBodyBytes` + limit body parser |
+| 502 dari proxy | Webhook mengirim `content-type: application/json` — proxy menolak | Hapus rewrite content-type; handler menerima JSON |
+| `409 Conflict` saat `getUpdates` | Webhook masih terdaftar | `deleteWebhook` dulu |
+| Update diterima lalu menggantung | Handler menunggu network call yang lambat | Turunkan `handlerTimeout`; pastikan observabilitas via `update:error` |
+| Serverless: jawaban tidak pernah sampai | Terlalu banyak await di satu handler | Aktifkan `webhookReply` agar panggilan pertama menumpang respons |
+
+English: [WEBHOOK.md](WEBHOOK.md) · 简体中文: [WEBHOOK.zh-CN.md](WEBHOOK.zh-CN.md)

package/docs/WEBHOOK.md

@@ -0,0 +1,215 @@
+# Webhook deployment guide (English)
+
+Everything needed to run telebibz behind a webhook: choosing polling vs webhook, the four framework integrations, secret tokens, registering the webhook, webhook replies, and local development tunnels.
+
+## Contents
+
+1. [Polling or webhook?](#1-polling-or-webhook)
+2. [The Web-standard handler](#2-the-web-standard-handler)
+3. [Express, Koa, Fastify, and Node http](#3-express-koa-fastify-and-node-http)
+4. [Registering the webhook](#4-registering-the-webhook)
+5. [Secret tokens](#5-secret-tokens)
+6. [Webhook replies (Telegraf-style)](#6-webhook-replies-telegraf-style)
+7. [Local development with a tunnel](#7-local-development-with-a-tunnel)
+8. [Production checklist](#8-production-checklist)
+9. [Troubleshooting](#9-troubleshooting)
+
+## 1. Polling or webhook?
+
+| | Long polling (`bot.start()`) | Webhook |
+|---|---|---|
+| Setup | zero | needs HTTPS endpoint |
+| Works behind NAT/laptop | ✅ | needs tunnel |
+| Best for | development, small bots | production, serverless, high volume |
+| Update delivery | bot pulls | Telegram pushes |
+
+Both share the exact same update pipeline (parallel across chats, ordered per chat). Switch freely — handlers do not change.
+
+## 2. The Web-standard handler
+
+`createWebhookHandler()` takes a Web `Request` and returns a `Response` — it works on Node 22 (via `node:http` bridging below), Bun, Deno, and edge runtimes:
+
+```ts
+import { Bot, createWebhookHandler } from "@xbibzlibrary/telebibz";
+
+const bot = new Bot(process.env.TELEGRAM_BOT_TOKEN!);
+bot.on("message", async (ctx) => { await ctx.reply("hello"); });
+
+export const handler = createWebhookHandler(bot, {
+  secretToken: process.env.TELEGRAM_WEBHOOK_SECRET,   // verifies X-Telegram-Bot-Api-Secret-Token
+  maxBodyBytes: 1_048_576,                            // reject bodies over 1 MB (default)
+  webhookReply: false,                                // see section 6
+});
+```
+
+The handler verifies, in order: HTTP method and path, secret token header, body size, JSON parsing, and update shape — answering each failure with the right status code before your handlers ever run.
+
+## 3. Express, Koa, Fastify, and Node http
+
+`webhookCallback()` adapts the handler to each framework's request/response style:
+
+**Express**
+
+```ts
+import express from "express";
+import { Bot, webhookCallback } from "@xbibzlibrary/telebibz";
+
+const bot = new Bot(process.env.TELEGRAM_BOT_TOKEN!);
+bot.on("message", async (ctx) => { await ctx.reply("hello"); });
+
+const app = express();
+app.use(express.json({ limit: "1mb" }));
+app.post("/telegram", webhookCallback(bot, "express", { secretToken: process.env.TELEGRAM_WEBHOOK_SECRET }));
+app.get("/healthz", (_req, res) => res.json({ ok: true }));
+
+app.listen(3000);
+```
+
+**Node http (no framework)**
+
+```ts
+import { createServer } from "node:http";
+import { webhookCallback } from "@xbibzlibrary/telebibz";
+
+const callback = webhookCallback(bot, "http", { secretToken: process.env.TELEGRAM_WEBHOOK_SECRET });
+createServer((req, res) => {
+  if (req.method === "POST" && req.url === "/telegram") return void callback(req, res);
+  res.writeHead(404).end();
+}).listen(3000);
+```
+
+**Fastify**
+
+```ts
+import Fastify from "fastify";
+import { webhookCallback } from "@xbibzlibrary/telebibz";
+
+const fastify = Fastify({ logger: true });
+fastify.post("/telegram", (req, reply) => webhookCallback(bot, "fastify", { secretToken: process.env.TELEGRAM_WEBHOOK_SECRET })(req, reply));
+await fastify.listen({ port: 3000, host: "0.0.0.0" });
+```
+
+**Koa** (with `koa-bodyparser` so `ctx.request.body` is parsed)
+
+```ts
+import Koa from "koa";
+import bodyParser from "koa-bodyparser";
+import { webhookCallback } from "@xbibzlibrary/telebibz";
+
+const app = new Koa();
+app.use(bodyParser());
+app.use(async (ctx) => {
+  if (ctx.method === "POST" && ctx.path === "/telegram") {
+    await webhookCallback(bot, "koa", { secretToken: process.env.TELEGRAM_WEBHOOK_SECRET })(ctx.request, ctx);
+    return;
+  }
+  ctx.status = 404;
+});
+app.listen(3000);
+```
+
+Framework ids: `"express" | "http" | "fastify" | "koa"`.
+
+## 4. Registering the webhook
+
+Point Telegram at your endpoint once (not on every boot):
+
+```ts
+await bot.api.methods.setWebhook({
+  url: "https://bot.example.com/telegram",
+  secret_token: process.env.TELEGRAM_WEBHOOK_SECRET,
+  max_connections: 40,                // 1–100, default 40
+  drop_pending_updates: true,         // optional: discard updates queued while down
+  allowed_updates: ["message", "callback_query"],
+});
+```
+
+Check registration and tear it down:
+
+```ts
+const info = await bot.api.methods.getWebhookInfo();
+await bot.api.methods.deleteWebhook({ drop_pending_updates: false });
+```
+
+A small CLI-style script makes this repeatable:
+
+```ts
+// scripts/register-webhook.ts — run with: npx tsx scripts/register-webhook.ts
+import { Bot } from "@xbibzlibrary/telebibz";
+const bot = new Bot(process.env.TELEGRAM_BOT_TOKEN!);
+await bot.api.methods.setWebhook({
+  url: process.env.WEBHOOK_URL!,
+  secret_token: process.env.TELEGRAM_WEBHOOK_SECRET,
+  max_connections: 40,
+});
+console.log("webhook registered:", process.env.WEBHOOK_URL);
+```
+
+## 5. Secret tokens
+
+Always set a secret token. Telegram then sends it in the `X-Telegram-Bot-Api-Secret-Token` header on every update; the handler rejects anything that does not match with `401 Unauthorized`. Generate one with `openssl rand -hex 32`. Two rules:
+
+- Between 1 and 256 characters of `A-Z, a-z, 0-9, _` and `-`.
+- Pass the **same value** to `setWebhook` (`secret_token`) and to `createWebhookHandler`/`webhookCallback` (`secretToken`).
+
+## 6. Webhook replies (Telegraf-style)
+
+With `webhookReply: true`, the **first** API call while handling an update is answered through the webhook HTTP response itself — Telegram executes the method for you and you save one round trip:
+
+```ts
+const handler = createWebhookHandler(bot, { webhookReply: true });
+```
+
+- Only the first call is claimed; later calls go through the transport as usual.
+- The claimed call resolves with `true` (Telegram never sends the method result back through the webhook response).
+- The lazy `getMe` initialization never claims the slot.
+- Per-update override: `bot.handleUpdate(update, { webhookReply: sink })` for fully custom servers.
+
+Most bots should keep it off — the default reply-then-200 flow is simpler to reason about, and the transport's connection reuse already keeps latency low.
+
+## 7. Local development with a tunnel
+
+Telegram must reach your endpoint over HTTPS. For local development, expose your port through a tunnel and register the tunnel URL:
+
+```bash
+# Option A: cloudflared (no account, no install to project)
+cloudflared tunnel --url http://localhost:3000
+# → https://random-name.trycloudflare.com
+
+# Option B: ngrok
+ngrok http 3000
+# → https://random-name.ngrok-free.app
+```
+
+Then:
+
+```bash
+WEBHOOK_URL=https://random-name.trycloudflare.com npx tsx scripts/register-webhook.ts
+```
+
+Tunnel URLs change on restart — re-register after each restart, or keep using polling during development and switch to webhooks only in staging/production (the handler code is identical).
+
+## 8. Production checklist
+
+- [ ] HTTPS endpoint with a valid certificate (Telegram rejects self-signed certs unless you upload `certificate`)
+- [ ] Secret token set on both `setWebhook` and the handler
+- [ ] `max_connections` tuned (default 40; range 1–100)
+- [ ] Health endpoint (`/healthz`) for your load balancer
+- [ ] Graceful shutdown: `process.on("SIGTERM", () => bot.stop())` — drains in-flight handlers before plugins are disposed
+- [ ] Body limit enforced (the handler rejects oversized bodies, but the framework's own limit should match)
+- [ ] Logging: `logger: { format: "json" }` for structured ingestion
+- [ ] Monitoring: subscribe to `update:error` and `bot:error` events
+- [ ] `getWebhookInfo()` polled by your ops dashboard (watch `pending_update_count`)
+
+## 9. Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Telegram never calls the endpoint | Webhook not registered / wrong URL | `getWebhookInfo()` shows the registered URL and the last error |
+| Every update answers 401 | Secret token mismatch | Same value in `setWebhook` and the handler |
+| 404 from Telegram | Wrong path | Register the exact path you serve (`/telegram`) |
+| Updates arrive twice | Both polling and webhook active | `deleteWebhook()` or stop calling `bot.start()` |
+| `ai_response`/ssl errors in `getWebhookInfo` | Invalid certificate | Use a CA-signed cert or upload the self-signed one as `certificate` |
+| Handler never sees large bodies | Framework body limit below Telegram's payload | Raise the framework's JSON limit (e.g. `express.json({ limit: "1mb" })`) |
+
+Bahasa Indonesia: [WEBHOOK.id.md](WEBHOOK.id.md) · 简体中文: [WEBHOOK.zh-CN.md](WEBHOOK.zh-CN.md)