@xbibzlibrary/telebibz 0.4.5 → 3.0.1

package/docs/WEBHOOK.id.md

@@ -1,212 +0,0 @@
-# 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

@@ -1,215 +0,0 @@
-# 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)

package/docs/WEBHOOK.zh-CN.md

@@ -1,212 +0,0 @@
-# Webhook 指南（简体中文）
-
-通过 webhook 提供更新服务 —— 适用于无长轮询的平台（serverless、容器），或需要公网 HTTPS 端点的场景。
-
-## 目录
-
-1. [轮询 vs webhook](#1-轮询-vs-webhook)
-2. [处理器：`createWebhookHandler()`](#2-处理器createwebhookhandler)
-3. [常见框架](#3-常见框架)
-4. [向 Telegram 注册 URL](#4-向-telegram-注册-url)
-5. [Secret token](#5-secret-token)
-6. [`webhookReply` 模式](#6-webhookreply-模式)
-7. [本地开发：隧道](#7-本地开发隧道)
-8. [生产检查清单](#8-生产检查清单)
-9. [故障排查](#9-故障排查)
-
-## 1. 轮询 vs webhook
-
-| | 轮询（`bot.start()`） | Webhook |
-|---|---|---|
-| 主动连接 Telegram | 是（长轮询） | 否 —— Telegram 主动连接你 |
-| 需要公网域名 + HTTPS | 否 | 是 |
-| 适合 | 本地脚本、开发、VPS | Serverless（Lambda/Workers/Cloud Functions）、容器、k8s |
-| 并发 | 相同的逐更新流水线 | 相同的逐更新流水线 |
-| 自定义 `POST /<path>` 路由 | — | 是 —— 处理器返回 `Response`，路由仍归你 |
-
-同一时间只有一种生效：webhook 注册后 Telegram 把更新推到该 URL，并忽略 `getUpdates`。
-
-## 2. 处理器：`createWebhookHandler()`
-
-处理器接受 **Web 标准 `Request`** 并返回 **`Response`** —— 可运行于 Node、Bun、Deno 与 edge runtime：
-
-```ts
-import { createWebhookHandler } from "@xbibzlibrary/telebibz";
-
-const handleUpdate = createWebhookHandler(bot, {
-  secretToken: process.env.TELEGRAM_WEBHOOK_SECRET,  // 校验 X-Telegram-Bot-Api-Secret-Token
-  webhookReply: true,                                 // 通过响应体应答 API（可选）
-});
-
-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`（可用 `maxBodyBytes` 调整）。
-- Secret 不匹配 → `401 Unauthorized`。
-- 非 POST 方法 → `405 Method Not Allowed`。
-- 更新经正常流水线处理 —— 错误处理器、session、conversation 全部照常工作。
-
-对 Express 风格的 Node 服务器（req/res 对象而非 `Request`），使用 `webhookCallback()` —— 见[常见框架](#3-常见框架)。
-
-## 3. 常见框架
-
-### 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（配合 `koa-bodyparser` 使 `ctx.request.body` 被解析）
-
-```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. 向 Telegram 注册 URL
-
-webhook 只会推送到你注册的 URL。服务器在公网地址就绪后，调用一次 `setWebhook`：
-
-```ts
-const secret = process.env.TELEGRAM_WEBHOOK_SECRET;
-
-await bot.api.methods.setWebhook({
-  url: "https://bot.example.com/telegram",
-  secret_token: secret,                 // 与处理器的 secretToken 完全一致
-  max_connections: 40,                  // 默认 40；按容量调整
-  allowed_updates: ["message", "callback_query"],  // 可选：减少流量
-  drop_pending_updates: false,
-});
-```
-
-**撤销 webhook** —— 两种选择：
-
-```ts
-await bot.api.methods.deleteWebhook({ drop_pending_updates: true }); // 回到轮询
-```
-
-当 bot 运行在本地 Bot API 服务器上时，`setWebhook` 还接受 `ip_address`，避免公网 DNS 解析。
-
-## 5. Secret token
-
-没有 secret，任何知道 URL 的人都能伪造更新。secret 用于确认请求确实来自 Telegram：
-
-```bash
-openssl rand -hex 32
-```
-
-保存为环境变量，并把**完全相同的值**传给 `setWebhook`（`secret_token` 参数）和处理器（`secretToken` 选项）。比较采用常数时间 —— 无法计时攻击。规则：1–256 个字符，仅限 `A-Z a-z 0-9 _ -`。
-
-注意 `webhookReply` 与 secret 无关 —— 该模式决定 API 响应*如何*发送，而非请求来自谁。
-
-## 6. `webhookReply` 模式
-
-Telegram 允许 bot 直接在 webhook 响应体里应答一次 API 调用。开启后每次回复省去一次往返 —— 在 serverless 上尤其有价值：
-
-```ts
-const handleUpdate = createWebhookHandler(bot, { webhookReply: true });
-```
-
-每个 update 只有**一次** API 调用能享受此机制 —— 最先完成的那次获胜；其余照常走 HTTP 请求。响应体被占用后，处理器返回 `{}`（Telegram 仍视为成功）。
-
-Telegraf 中称为 `telegram.webhookReply`；概念与默认值在 telebibz 中完全一致。
-
-## 7. 本地开发：隧道
-
-Telegram 只向**公网 HTTPS** URL 推送。开发时把公网 URL 隧道到 localhost：
-
-```bash
-# cloudflared（无需账号）
-cloudflared tunnel --url http://localhost:3000
-
-# 或 ngrok
-ngrok http 3000
-```
-
-然后注册得到的 URL：
-
-```bash
-TOKEN="…"
-URL="https://random-words.loca.lt"   # 来自隧道输出
-SECRET="…"
-curl "https://api.telegram.org/bot$TOKEN/setWebhook" \
-  -d "url=$URL/telegram" -d "secret_token=$SECRET"
-```
-
-开发完成后记得 `deleteWebhook`，让 `bot.start()` 重新可用。
-
-## 8. 生产检查清单
-
-- [ ] 公网 HTTPS + 有效证书（Telegram 拒绝自签名）
-- [ ] `secret_token` 已设置且两端一致
-- [ ] `max_connections` 已调整（默认 40）
-- [ ] Body parser 上限 ≥ 1 MB（`express.json({ limit: "1mb" })` 等）
-- [ ] 上游超时 > `handlerTimeout`（让 `UpdateTimeoutError` 先接管，而不是负载均衡器返回 504）
-- [ ] 重新部署时考虑 `drop_pending_updates`
-- [ ] 错误可观测：`bot.catch()` + `update:error`
-- [ ] 优雅关机：退出前 `bot.stop()`
-
-## 9. 故障排查
-
-| 症状 | 原因 | 修复 |
-|---|---|---|
-| Telegram 一直超时（`getUpdates` 空转） | webhook 处于激活状态 —— Telegram 忽略轮询 | `deleteWebhook` 或改用处理器 |
-| 每个请求都 401 | 处理器 secret ≠ 已注册的 `secret_token` | 两端改为一致 |
-| 413 Payload Too Large | Body 超过 `maxBodyBytes`（默认 1 MB） | 调大 `maxBodyBytes` 与 body parser 上限 |
-| 代理返回 502 | webhook 发送 `content-type: application/json` —— 代理拒绝 | 移除 content-type 改写；处理器接受 JSON |
-| `getUpdates` 报 `409 Conflict` | webhook 仍注册着 | 先 `deleteWebhook` |
-| 更新收到后挂起 | handler 在等待缓慢的网络调用 | 降低 `handlerTimeout`；通过 `update:error` 保证可观测 |
-| Serverless：回复从未送达 | 单个 handler 里 await 过多 | 开启 `webhookReply`，让第一次调用搭响应的便车 |
-
-English: [WEBHOOK.md](WEBHOOK.md) · Bahasa Indonesia: [WEBHOOK.id.md](WEBHOOK.id.md)

package/examples/README.md

@@ -1,37 +0,0 @@
-# Telebibz examples
-
-These examples are intentionally small, runnable starting points for developers evaluating Telebibz. They use environment variables for secrets and do not contain real Telegram credentials.
-
-## Run the examples
-
-From the repository root:
-
-```bash
-npm install
-export TELEGRAM_BOT_TOKEN="<your-bot-token>"
-npx tsx examples/minimal.ts
-```
-
-The official npm package can be used from a separate project by replacing the local import path with `@xbibzlibrary/telebibz` and installing the package from npm.
-
-## Available starters
-
-| Example | Demonstrates | Start command |
-|---|---|---|
-| `minimal.ts` | Commands, text routing, and a minimal long-polling bot. | `npx tsx examples/minimal.ts` |
-| `wizard-registration.ts` | A two-step name/age conversation with automatic continuation across messages. | `npx tsx examples/wizard-registration.ts` |
-| `webhook.ts` | A Node.js HTTP server, webhook secret validation, and Telegram update handling. | `TELEGRAM_WEBHOOK_SECRET=<secret> npx tsx examples/webhook.ts` |
-
-The wizard example starts the flow with `/register`, asks for a name, then asks for an age. Send `/cancel` to cancel an active flow. The webhook example requires both `TELEGRAM_BOT_TOKEN` and `TELEGRAM_WEBHOOK_SECRET`; expose the server through HTTPS in a deployment environment and configure the matching Telegram webhook secret.
-
-## Production checklist
-
-Use a secret manager or deployment environment for `TELEGRAM_BOT_TOKEN` and `TELEGRAM_WEBHOOK_SECRET`. Do not commit `.env` files or literal credentials. Run `npm run test:examples` before submitting changes. For production deployments, prefer a managed HTTPS endpoint, structured JSON logs, health checks, graceful shutdown, and a persistent storage adapter when conversations or sessions must survive restarts.
-
-## More documentation
-
-- [English API reference](../docs/API.md)
-- [Bahasa Indonesia API reference](../docs/API.id.md)
-- [简体中文 API reference](../docs/API.zh-CN.md)
-- [GitHub Packages guide](../docs/GITHUB_PACKAGES.md)
-- [Contributing guide](../CONTRIBUTING.md)