@xbibzlibrary/telebibz 0.4.3 → 0.4.5

package/docs/MIGRATION_TELEGRAF.md

@@ -0,0 +1,154 @@
+# Migrating from Telegraf (English)
+
+telebibz implements the Telegraf context surface and launch options deliberately, so most handlers port with little or no change. This guide maps every part of a Telegraf bot to its telebibz equivalent.
+
+## Contents
+
+1. [Side-by-side: a whole bot](#1-side-by-side-a-whole-bot)
+2. [Concept map](#2-concept-map)
+3. [Context methods](#3-context-methods)
+4. [Launch options](#4-launch-options)
+5. [Scenes → Wizards](#5-scenes--wizards)
+6. [Session storage](#6-session-storage)
+7. [Webhooks](#7-webhooks)
+8. [What has no direct equivalent](#8-what-has-no-direct-equivalent)
+
+## 1. Side-by-side: a whole 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!"); });   // named command, not 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 });   // same option name
+```
+
+Only two mechanical differences: `bot.start(handler)` becomes `bot.command("start", handler)`, and `answerCbQuery()` becomes `answerCallbackQuery()`.
+
+## 2. Concept map
+
+| Telegraf | telebibz | Notes |
+|---|---|---|
+| `new Telegraf(token)` | `new Bot(token)` or `new Bot({ token, ... })` | |
+| `bot.launch()` | `bot.launch()` / `bot.start()` | `mode: "polling"` is explicit on `launch` |
+| `bot.stop()` | `bot.stop()` | telebibz drains in-flight handlers first |
+| `bot.use(mw)` | `bot.use(mw)` | same middleware signature `(ctx, next)` |
+| `bot.command(name, h)` | `bot.command(name, h)` | |
+| `bot.on(filter, h)` | `bot.on(filter, h)` | same filter grammar (`message:photo`, arrays) |
+| `bot.hears(trigger, h)` | `bot.hears(trigger, h)` | strings and RegExp |
+| `bot.action(pattern, h)` | `bot.action(pattern, h)` | drop-in alias of `bot.callback` |
+| `bot.catch(handler)` | `bot.catch(handler)` | receives `(error, ctx)` |
+| `ctx.reply(text, extra)` | `ctx.reply(text, extra)` | |
+| `ctx.telegram.callApi(m, p)` | `ctx.api.call(m, p)` / `ctx.api.raw(m, p)` | `raw` needs no type map entry |
+| `ctx.telegram.api.config` | `transportOptions` on the `Bot` options | timeout, retries, flood gate |
+| `Scenes.WizardScene` + `Stage` | `Wizard` + `bot.useWizard()` | see section 5 |
+| `session` middleware | built-in `session` storage option | see section 6 |
+| `webhookCallback(bot, app)` | `webhookCallback(bot, "express")` | framework is now an argument |
+| Telegraf plugins (`telegraf-i18n`, …) | `bot.usePlugin({ install, onStop, dispose })` | explicit lifecycle |
+
+## 3. Context methods
+
+Every Telegraf context shortcut exists — including the ones Telegraf leaves to plugins:
+
+- **Replies**: `reply`, `replyWithPhoto`, `replyWithDocument`, `replyWithVideo`, `replyWithAudio`, `replyWithVoice`, `replyWithAnimation`, `replyWithVideoNote`, `replyWithSticker`, `replyWithMediaGroup`, `replyWithLocation`, `replyWithVenue`, `replyWithContact`, `replyWithPoll`, `replyWithQuiz`, `replyWithDice`, `replyWithGame`, `replyWithInvoice`, `replyWithHTML`, `replyWithMarkdown` (+V2)
+- **Admin/moderation**: `banChatMember`, `unbanChatMember`, `restrictChatMember`, `promoteChatMember`, `banChatSenderChat`, `unbanChatSenderChat`
+- **Chat**: `setChatTitle`, `setChatDescription`, `setChatPhoto`, `deleteChatPhoto`, `setChatPermissions`, `leaveChat`, `unpinAllChatMessages`, `setChatStickerSet`, `deleteChatStickerSet`
+- **Info**: `getChat`, `getChatAdministrators`, `getChatMemberCount`, `getChatMember`
+- **Invite links/join requests**: `exportChatInviteLink`, `createChatInviteLink`, `editChatInviteLink`, `revokeChatInviteLink`, `approveChatJoinRequest`, `declineChatJoinRequest`
+- **Live location/polls/games**: `editMessageLiveLocation`, `stopMessageLiveLocation`, `stopPoll`, `setGameScore`, `getGameHighScores`
+- **Forum**: full topic set (`createForumTopic` … `unhideGeneralForumTopic`)
+- **New beyond Telegraf core**: `getFile` (typed), `downloadFile`, `edit` (rewrites the current message's text), plus standalone helpers exported from the package root — `validateUpload`/`assertValidUpload` — which are not context methods
+
+Naming differences to fix while porting: `answerCbQuery` → `answerCallbackQuery`; `ctx.telegram` → `ctx.api`; keyboard helpers come from the package root (`InlineKeyboard`, `ReplyKeyboard`, `removeKeyboard`, `forceReply`) instead of `Markup`.
+
+## 4. Launch options
+
+| Telegraf | telebibz |
+|---|---|
+| `launch({ dropPendingUpdates })` | `launch({ dropPendingUpdates })` — identical |
+| `handlerTimeout` (90 000 default) | `handlerTimeout` (90 000 default; `0` disables) |
+| `contextType` option | `contextType` option — your `Context` subclass is instantiated for every update |
+| `webhookReply` (per-update) | `webhookReply` on the handler / `handleUpdate` options |
+| `telegraf.use(session(...))` | `new Bot({ session: new MemoryStorage() })` (or JSON/Redis/SQL/Mongo) |
+
+## 5. Scenes → Wizards
+
+Telegraf's `WizardScene` + `Stage` becomes a single `Wizard` with explicit steps and no global session keys:
+
+```ts
+import { Bot, Wizard } from "@xbibzlibrary/telebibz";
+
+const wizard = new Wizard()
+  .step({ id: "ask-name", 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}!`); } });
+
+const bot = new Bot(process.env.TELEGRAM_BOT_TOKEN!);
+bot.useWizard(wizard);                                    // replaces Stage middleware
+bot.command("start", async (ctx) => { await wizard.run(ctx); }); // replaces scene.enter()
+```
+
+- The wizard key derives automatically from chat + sender — no manual key management.
+- `flow.set(key, value)` / `flow.get(key)` replace `ctx.scene.session`.
+- `/cancel` cancels; the conversation completes automatically after the last step.
+- For non-linear graphs, compose `ConversationManager` with the router (telebibz deliberately keeps scene orchestration application-owned; see FEATURE_MATRIX "Design decisions").
+
+## 6. Session storage
+
+Telegraf stores sessions in memory by default and needs a store plugin for persistence. telebibz takes storage on the constructor — swap the adapter, keep the code:
+
+```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"),   // or MemoryStorage / RedisStorage / SqlStorage / MongoStorage
+});
+```
+
+Full wiring recipes for every adapter: [STORAGE.md](STORAGE.md).
+
+## 7. Webhooks
+
+```ts
+// Telegraf: webhookCallback(bot, app)
+// telebibz: framework is explicit
+import { webhookCallback } from "@xbibzlibrary/telebibz";
+app.post("/telegram", webhookCallback(bot, "express", { secretToken: process.env.TELEGRAM_WEBHOOK_SECRET }));
+```
+
+`createWebhookHandler()` additionally provides a Web-standard `Request → Response` handler for Bun/Deno/edge. Full deployment guide: [WEBHOOK.md](WEBHOOK.md).
+
+## 8. What has no direct equivalent
+
+- **`bot.telegram` low-level client** — use `bot.api` (`call`, `raw`, `methods`, `downloadFile`); the flood gate and retries are built into the transport rather than configurable per call.
+- **Telegraf's plugin ecosystem** — port plugins as `Plugin` objects with an explicit lifecycle (`install`, `onStop`, `dispose`); the plugin manager restarts cleanly.
+- **`Composer.mount`/dynamic scenes** — build with `Router` nesting and `matchMode: "all"` instead.
+- **Markup helper chains** (`Markup.keyboard(...).resize()`) — use `new ReplyKeyboard().text("A").resized().build()`; same payloads, builder style.
+
+Bahasa Indonesia: [MIGRATION_TELEGRAF.id.md](MIGRATION_TELEGRAF.id.md) · 简体中文: [MIGRATION_TELEGRAF.zh-CN.md](MIGRATION_TELEGRAF.zh-CN.md)

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/STORAGE.id.md

@@ -0,0 +1,105 @@
+# Panduan cepat storage (Bahasa Indonesia)
+
+telebibz menyediakan interface `Storage<K, V>` generik dengan lima adapter. Core package **tanpa runtime dependency**: adapter Redis, SQL, dan Mongo menerima driver interface kecil yang sudah Anda punya, jadi Anda yang memilih driver dan versinya.
+
+Semua adapter memakai kontrak yang sama — `get` / `set` / `delete` / `has` / `clear` / `keys()` / `entries()` — ditambah **`update(key, updater, { ttlMs })`** yang menyalin penulisan per key sehingga update bersamaan ke key yang sama tidak pernah saling menimpa. TTL diatur per penulisan lewat `{ ttlMs }`.
+
+## MemoryStorage (default — tanpa konfigurasi)
+
+```ts
+import { Bot } from "@xbibzlibrary/telebibz";
+
+const bot = new Bot({ token: process.env.TELEGRAM_BOT_TOKEN! });
+// bot.session secara default adalah MemoryStorage<string, S>.
+```
+
+## JsonFileStorage (persistensi satu file, tetap tanpa dependency)
+
+```ts
+import { Bot, JsonFileStorage } from "@xbibzlibrary/telebibz";
+
+const bot = new Bot({
+  token: process.env.TELEGRAM_BOT_TOKEN!,
+  session: new JsonFileStorage("state/sessions.json"),
+});
+```
+
+## RedisStorage (bawa client Anda sendiri)
+
+Adapter ini hanya butuh lima method callback-style yang dimiliki setiap client Redis — `node-redis` langsung cocok:
+
+```ts
+import { Bot, RedisStorage } from "@xbibzlibrary/telebibz";
+import { createClient } from "redis"; // driver dan versi pilihan Anda
+
+const redis = createClient({ url: process.env.REDIS_URL });
+await redis.connect();
+
+const bot = new Bot({
+  token: process.env.TELEGRAM_BOT_TOKEN!,
+  session: new RedisStorage(redis, "mybot:"), // prefix untuk key Anda
+});
+// TTL per penulisan: await bot.session.set(key, value, { ttlMs: 24 * 60 * 60 * 1000 });
+// (kedaluwarsa PX Redis diterapkan otomatis.)
+```
+
+## SqlStorage (semua database SQL)
+
+Implementasikan driver lima method di atas library SQL Anda; contoh ini memakai `better-sqlite3`:
+
+```ts
+import { Bot, SqlStorage } from "@xbibzlibrary/telebibz";
+import Database from "better-sqlite3";
+
+const db = new Database("state/bot.db");
+db.exec("CREATE TABLE IF NOT EXISTS kv (key TEXT PRIMARY KEY, value TEXT NOT NULL, expires_at INTEGER)");
+
+const storage = new SqlStorage({
+  async get(key) {
+    const row = db.prepare("SELECT value, expires_at FROM kv WHERE key = ?").get(key) as { value: string; expires_at: number | null } | undefined;
+    return row === undefined ? undefined : JSON.parse(row.value);
+  },
+  async set(key, value, expiresAt) {
+    db.prepare("INSERT INTO kv (key, value, expires_at) VALUES (?, ?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value, expires_at = excluded.expires_at")
+      .run(key, JSON.stringify(value), expiresAt ?? null);
+  },
+  async delete(key) { return db.prepare("DELETE FROM kv WHERE key = ?").run(key).changes > 0; },
+  async has(key) { return db.prepare("SELECT 1 FROM kv WHERE key = ?").get(key) !== undefined; },
+  async clear() { db.prepare("DELETE FROM kv").run(); },
+  async entries() {
+    const rows = db.prepare("SELECT key, value, expires_at FROM kv").all() as Array<{ key: string; value: string; expires_at: number | null }>;
+    return rows.map((row) => [row.key, JSON.parse(row.value), row.expiresAt ?? undefined] as [string, unknown, number | undefined]);
+  },
+});
+
+const bot = new Bot({ token: process.env.TELEGRAM_BOT_TOKEN!, session: storage });
+```
+
+## MongoStorage (bawa collection Anda sendiri)
+
+Adapter ini berbicara langsung dengan bentuk collection MongoDB standar — cukup kirim collection Anda:
+
+```ts
+import { Bot, MongoStorage } from "@xbibzlibrary/telebibz";
+import { MongoClient } from "mongodb";
+
+const client = new MongoClient(process.env.MONGODB_URL!);
+await client.connect();
+
+const bot = new Bot({
+  token: process.env.TELEGRAM_BOT_TOKEN!,
+  session: new MongoStorage(client.db("mybot").collection("sessions")),
+});
+```
+
+## Memilih
+
+| Adapter | Pakai saat | Persistensi | Dependency tambahan |
+|---|---|---|---|
+| `MemoryStorage` | bot satu proses, test | selama proses hidup | tidak ada |
+| `JsonFileStorage` | bot kecil, deploy sederhana | file di disk | tidak ada |
+| `RedisStorage` | multi-instance, state bersama | Redis | client Redis Anda |
+| `SqlStorage` | aplikasi berbasis SQL | semua database SQL | driver SQL Anda |
+| `MongoStorage` | stack Mongo yang sudah ada | MongoDB | driver Mongo Anda |
+
+Signature API lengkap: [API.id.md](API.id.md). English: [STORAGE.md](STORAGE.md) · 简体中文: [STORAGE.zh-CN.md](STORAGE.zh-CN.md).

package/docs/STORAGE.md

@@ -0,0 +1,105 @@
+# Storage quick start (English)
+
+telebibz ships a generic `Storage<K, V>` interface with five adapters. The core package has **zero runtime dependencies**: the Redis, SQL, and Mongo adapters accept a small driver interface you already have, so you pick the driver and version.
+
+All adapters share one contract — `get` / `set` / `delete` / `has` / `clear` / `keys()` / `entries()` — plus **`update(key, updater, { ttlMs })`**, which serializes writes per key so concurrent updates to the same key never interleave. TTL is set per write through `{ ttlMs }`.
+
+## MemoryStorage (default — nothing to configure)
+
+```ts
+import { Bot } from "@xbibzlibrary/telebibz";
+
+const bot = new Bot({ token: process.env.TELEGRAM_BOT_TOKEN! });
+// bot.session is a MemoryStorage<string, S> by default.
+```
+
+## JsonFileStorage (single-file persistence, still zero dependencies)
+
+```ts
+import { Bot, JsonFileStorage } from "@xbibzlibrary/telebibz";
+
+const bot = new Bot({
+  token: process.env.TELEGRAM_BOT_TOKEN!,
+  session: new JsonFileStorage("state/sessions.json"),
+});
+```
+
+## RedisStorage (bring your own client)
+
+The adapter needs exactly the five callback-style methods every Redis client exposes — `node-redis` works as-is:
+
+```ts
+import { Bot, RedisStorage } from "@xbibzlibrary/telebibz";
+import { createClient } from "redis"; // your choice of driver and version
+
+const redis = createClient({ url: process.env.REDIS_URL });
+await redis.connect();
+
+const bot = new Bot({
+  token: process.env.TELEGRAM_BOT_TOKEN!,
+  session: new RedisStorage(redis, "mybot:"), // prefix for your keys
+});
+// Per-write TTL: await bot.session.set(key, value, { ttlMs: 24 * 60 * 60 * 1000 });
+// (Redis PX expiry is applied automatically.)
+```
+
+## SqlStorage (any SQL database)
+
+Implement the five-method driver over your SQL library; the example uses `better-sqlite3`:
+
+```ts
+import { Bot, SqlStorage } from "@xbibzlibrary/telebibz";
+import Database from "better-sqlite3";
+
+const db = new Database("state/bot.db");
+db.exec("CREATE TABLE IF NOT EXISTS kv (key TEXT PRIMARY KEY, value TEXT NOT NULL, expires_at INTEGER)");
+
+const storage = new SqlStorage({
+  async get(key) {
+    const row = db.prepare("SELECT value, expires_at FROM kv WHERE key = ?").get(key) as { value: string; expires_at: number | null } | undefined;
+    return row === undefined ? undefined : JSON.parse(row.value);
+  },
+  async set(key, value, expiresAt) {
+    db.prepare("INSERT INTO kv (key, value, expires_at) VALUES (?, ?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value, expires_at = excluded.expires_at")
+      .run(key, JSON.stringify(value), expiresAt ?? null);
+  },
+  async delete(key) { return db.prepare("DELETE FROM kv WHERE key = ?").run(key).changes > 0; },
+  async has(key) { return db.prepare("SELECT 1 FROM kv WHERE key = ?").get(key) !== undefined; },
+  async clear() { db.prepare("DELETE FROM kv").run(); },
+  async entries() {
+    const rows = db.prepare("SELECT key, value, expires_at FROM kv").all() as Array<{ key: string; value: string; expires_at: number | null }>;
+    return rows.map((row) => [row.key, JSON.parse(row.value), row.expiresAt ?? undefined] as [string, unknown, number | undefined]);
+  },
+});
+
+const bot = new Bot({ token: process.env.TELEGRAM_BOT_TOKEN!, session: storage });
+```
+
+## MongoStorage (bring your own collection)
+
+The adapter talks to a standard MongoDB collection shape — pass your collection directly:
+
+```ts
+import { Bot, MongoStorage } from "@xbibzlibrary/telebibz";
+import { MongoClient } from "mongodb";
+
+const client = new MongoClient(process.env.MONGODB_URL!);
+await client.connect();
+
+const bot = new Bot({
+  token: process.env.TELEGRAM_BOT_TOKEN!,
+  session: new MongoStorage(client.db("mybot").collection("sessions")),
+});
+```
+
+## Choosing
+
+| Adapter | Use when | Persistence | Extra dependency |
+|---|---|---|---|
+| `MemoryStorage` | single-process bots, tests | process lifetime | none |
+| `JsonFileStorage` | small bots, simple deploys | file on disk | none |
+| `RedisStorage` | multi-instance, shared state | Redis | your Redis client |
+| `SqlStorage` | SQL-backed apps | any SQL database | your SQL driver |
+| `MongoStorage` | existing Mongo stack | MongoDB | your Mongo driver |
+
+Full API signatures: [API.md](API.md). Bahasa Indonesia: [STORAGE.id.md](STORAGE.id.md) · 简体中文: [STORAGE.zh-CN.md](STORAGE.zh-CN.md).