@xbibzlibrary/telebibz 0.4.5 → 3.0.1

package/docs/GETTING_STARTED.zh-CN.md

@@ -1,89 +0,0 @@
-# Telebibz 入门
-
-本指南帮助新开发者在几分钟内完成安装并运行 Telegram bot。
-
-## 1. 创建 bot token
-
-通过 Telegram 官方 bot 管理账号创建 bot，并将 token 保存在部署环境中。不要把 token 提交到 source control。
-
-## 2. 安装 Telebibz
-
-```bash
-mkdir my-telebibz-bot && cd my-telebibz-bot
-npm init -y
-npm install @xbibzlibrary/telebibz
-npm install --save-dev tsx typescript
-```
-
-请使用 secret manager，或在 shell 中设置变量：
-
-```bash
-export TELEGRAM_BOT_TOKEN="<your-bot-token>"
-```
-
-## 3. 编写第一个 bot
-
-创建 `index.ts`：
-
-```ts
-import { Bot } from "@xbibzlibrary/telebibz";
-
-const token = process.env.TELEGRAM_BOT_TOKEN;
-if (!token) throw new Error("TELEGRAM_BOT_TOKEN is required.");
-
-const bot = new Bot(token);
-bot.command("start", async (ctx) => { await ctx.reply("Telebibz is working."); });
-bot.onText("ping", async (ctx) => { await ctx.reply("pong"); });
-
-await bot.start();
-```
-
-运行：
-
-```bash
-npx tsx index.ts
-```
-
-向 bot 发送 `/start` 或 `ping`。终端会显示 Telebibz branding 和 structured logs。如果日志会被 log collector 读取，请将 logger format 设置为 `json`。
-
-## 4. 添加多步骤 wizard
-
-当回复需要继续处理 active step 时，使用 `Wizard` 和 `bot.useWizard()`。使用 `wizard.run(ctx)` 显式开始 flow：
-
-```ts
-const wizard = new Wizard()
-  .step({ id: "name", run: async (flow) => {
-    flow.set("name", flow.ctx.message?.text?.trim()).next();
-    await flow.ctx.reply("How old are you?");
-  }})
-  .step({ id: "age", run: async (flow) => {
-    const age = Number(flow.ctx.message?.text?.trim());
-    if (!Number.isInteger(age)) { await flow.ctx.reply("Send a whole number."); return; }
-    flow.set("age", age).next();
-    await flow.ctx.reply("Registration complete.");
-  }});
-
-bot.useWizard(wizard);
-bot.command("register", async (ctx) => {
-  await wizard.run(ctx);
-  await ctx.reply("What is your name?");
-});
-```
-
-default conversation manager 会在 wizard instance 生命周期内持续使用，key 会根据 chat 和 sender identity 生成。默认情况下，`/cancel` 会取消 active flow。
-
-## 5. Production checklist
-
-Webhook 使用 HTTPS，验证 Telegram webhook secret，将 token 保存到 secret manager，配置 structured JSON logs，添加 health checks；如果 session 必须跨重启保留，请使用 persistent storage。部署前运行 `npm run typecheck`、`npm run test:types`、`npm run test:examples`、`npm test`、`npm run build` 和 `npm run security`。
-
-## 下一步
-
-- [Runnable examples](../examples/README.md)
-- [完整 API 参考](API.zh-CN.md)
-- [文件：上传与下载](FILES.zh-CN.md)
-- [错误处理与限流](ERRORS.zh-CN.md)
-- [Webhook 部署](WEBHOOK.zh-CN.md)
-- [离线测试你的 bot](TESTING.zh-CN.md)
-- [从 Telegraf 迁移](MIGRATION_TELEGRAF.zh-CN.md)
-- [生产实战手册](COOKBOOK.zh-CN.md)
-- [贡献指南](../CONTRIBUTING.md)

package/docs/GITHUB_PACKAGES.id.md

@@ -1,82 +0,0 @@
-# GitHub Packages
-
-`@xbibzlibrary/telebibz` dirilis ke [npmjs](https://www.npmjs.com/package/@xbibzlibrary/telebibz) dan registry npm GitHub Packages. Repository GitHub resminya adalah [XbibzOfficial777/telebibz](https://github.com/XbibzOfficial777/telebibz).
-
-## Registry
-
-URL registry GitHub Packages:
-
-```text
-https://npm.pkg.github.com
-```
-
-Mapping scope npm:
-
-```ini
-@xbibzlibrary:registry=https://npm.pkg.github.com
-```
-
-Workflow release mempublikasikan tarball yang sama ke npmjs dan GitHub Packages setelah typecheck, test, build, security audit, dan release check berhasil. Workflow menggunakan `GITHUB_TOKEN` dengan permission `packages: write`; personal access token GitHub tidak disimpan di repository atau workflow.
-
-## Instalasi package
-
-Untuk package public, tambahkan mapping berikut pada `.npmrc` project yang memakai package:
-
-```ini
-@xbibzlibrary:registry=https://npm.pkg.github.com
-```
-
-Jika package atau repository bersifat private, gunakan **personal access token (classic)** dengan minimal akses `read:packages`. Simpan token di luar repository, sebaiknya melalui environment variable reference pada konfigurasi npm user:
-
-```ini
-@xbibzlibrary:registry=https://npm.pkg.github.com
-//npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}
-```
-
-Kemudian jalankan:
-
-```bash
-export GITHUB_PACKAGES_TOKEN="<token-read-packages-kamu>"
-npm install @xbibzlibrary/telebibz
-```
-
-Jangan mengganti placeholder dengan token asli di file yang di-commit. Jangan commit `.npmrc` yang berisi kredensial literal, dan jangan memasukkan token ke issue, pull request, log, atau chat.
-
-## Publikasi lokal
-
-Cara yang direkomendasikan adalah workflow GitHub Actions yang telah dilindungi. Workflow memeriksa versi dan hanya publish setelah seluruh release gate berhasil. Publikasi lokal hanya untuk maintainer yang memiliki personal access token (classic) dengan `write:packages` serta permission repository:
-
-```bash
-export GITHUB_PACKAGES_TOKEN="<token-write-packages-kamu>"
-printf '@xbibzlibrary:registry=https://npm.pkg.github.com\n//npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}\n' > "$HOME/.npmrc"
-npm run build
-npm pack
-npm publish ./xbibzlibrary-telebibz-<version>.tgz --registry=https://npm.pkg.github.com --access public
-```
-
-Gunakan semantic version baru untuk setiap publikasi. Versi registry bersifat immutable dan tidak boleh ditimpa.
-
-## Permission GitHub Actions
-
-Workflow release menggunakan permission minimum berikut:
-
-```yaml
-permissions:
-  contents: write
-  packages: write
-```
-
-`NPM_TOKEN` tetap menjadi environment secret untuk publikasi ke npmjs. GitHub Packages menggunakan `GITHUB_TOKEN` otomatis, sehingga tidak memerlukan secret GitHub tambahan untuk package milik repository ini. Jika kebijakan organisasi menonaktifkan pewarisan akses package, hubungkan package ke repository dan berikan akses workflow melalui pengaturan package.
-
-## Troubleshooting
-
-Respons `401 Unauthorized` biasanya berarti token tidak ada, sudah kedaluwarsa, atau tidak mempunyai scope package yang benar. Respons `403 Forbidden` biasanya berarti akun atau workflow tidak memiliki permission package, atau kebijakan organisasi memblokir publikasi. Respons `404 Not Found` dapat muncul ketika package private diakses tanpa autentikasi atau scope belum diarahkan ke `https://npm.pkg.github.com`.
-
-Untuk instalasi dari npmjs, hapus mapping GitHub scope atau gunakan registry npm default. Kedua registry berisi nama package dan versi yang sama, tetapi autentikasi dan access control dikelola secara terpisah.
-
-## Referensi
-
-1. [Working with the npm registry — GitHub Docs](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry)
-2. [About permissions for GitHub Packages — GitHub Docs](https://docs.github.com/en/packages/learn-github-packages/about-permissions-for-github-packages)
-3. [Publishing and installing a package with GitHub Actions — GitHub Docs](https://docs.github.com/en/packages/quickstart)
-4. [npm package.json publishConfig — npm Docs](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#publishconfig)

package/docs/GITHUB_PACKAGES.md

@@ -1,82 +0,0 @@
-# GitHub Packages
-
-`@xbibzlibrary/telebibz` is released to both [npmjs](https://www.npmjs.com/package/@xbibzlibrary/telebibz) and the GitHub Packages npm registry. The canonical GitHub repository is [XbibzOfficial777/telebibz](https://github.com/XbibzOfficial777/telebibz).
-
-## Registry
-
-GitHub Packages uses the following npm registry URL:
-
-```text
-https://npm.pkg.github.com
-```
-
-The package scope is mapped to GitHub Packages with:
-
-```ini
-@xbibzlibrary:registry=https://npm.pkg.github.com
-```
-
-The release workflow publishes the same verified tarball to npmjs and GitHub Packages after the type checks, tests, build, security audit, and release checks pass. The workflow uses `GITHUB_TOKEN` with `packages: write`; no GitHub personal access token is stored in the repository or workflow file.
-
-## Installing the package
-
-For a public package, use a GitHub Packages-aware `.npmrc` in the consuming project:
-
-```ini
-@xbibzlibrary:registry=https://npm.pkg.github.com
-```
-
-If the package or repository is private, authenticate with a **personal access token (classic)** that has at least `read:packages` access. Store the token outside the repository, preferably in the user-level npm configuration or an environment-variable reference:
-
-```ini
-@xbibzlibrary:registry=https://npm.pkg.github.com
-//npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}
-```
-
-Then install the package:
-
-```bash
-export GITHUB_PACKAGES_TOKEN="<your-read-packages-token>"
-npm install @xbibzlibrary/telebibz
-```
-
-Do not replace the placeholder with a real token in a committed file. Do not commit `.npmrc` files containing literal credentials, and do not paste tokens into issues, pull requests, logs, or chat.
-
-## Publishing locally
-
-The recommended publishing path is the protected GitHub Actions workflow. It verifies the version and publishes only after all release gates succeed. Local publishing is intended for maintainers who have a classic personal access token with `write:packages` and repository permission to publish packages:
-
-```bash
-export GITHUB_PACKAGES_TOKEN="<your-write-packages-token>"
-printf '@xbibzlibrary:registry=https://npm.pkg.github.com\n//npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}\n' > "$HOME/.npmrc"
-npm run build
-npm pack
-npm publish ./xbibzlibrary-telebibz-<version>.tgz --registry=https://npm.pkg.github.com --access public
-```
-
-Use a new semantic version for every publication. Registry versions are immutable; an existing version must never be overwritten.
-
-## GitHub Actions permissions
-
-The release workflow declares the minimum package permission required for publication:
-
-```yaml
-permissions:
-  contents: write
-  packages: write
-```
-
-`NPM_TOKEN` remains an environment secret for npmjs publication. GitHub Packages uses the automatically provided `GITHUB_TOKEN`, so no additional GitHub token secret is required for the repository's own package. If organization policy disables automatic package access inheritance, connect the package to the repository and grant the workflow access under the package's settings.
-
-## Troubleshooting
-
-A `401 Unauthorized` response normally means the token is missing, expired, or lacks the required package scope. A `403 Forbidden` response usually means the account or workflow does not have permission to the package, or that organization policy blocks publication. A `404 Not Found` response can occur when a private package is queried without authentication or when the scope is not mapped to `https://npm.pkg.github.com`.
-
-For npmjs installation, omit the GitHub scope mapping or use the default npm registry. Both registries contain the same package name and release version, but authentication and access control are handled independently.
-
-## References
-
-1. [Working with the npm registry — GitHub Docs](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry)
-2. [About permissions for GitHub Packages — GitHub Docs](https://docs.github.com/en/packages/learn-github-packages/about-permissions-for-github-packages)
-3. [Publishing and installing a package with GitHub Actions — GitHub Docs](https://docs.github.com/en/packages/quickstart)
-4. [npm package.json publishConfig — npm Docs](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#publishconfig)

package/docs/GITHUB_PACKAGES.zh-CN.md

@@ -1,82 +0,0 @@
-# GitHub Packages
-
-`@xbibzlibrary/telebibz` 同时发布到 [npmjs](https://www.npmjs.com/package/@xbibzlibrary/telebibz) 和 GitHub Packages npm registry。官方 GitHub 仓库是 [XbibzOfficial777/telebibz](https://github.com/XbibzOfficial777/telebibz)。
-
-## Registry
-
-GitHub Packages 使用以下 npm registry 地址：
-
-```text
-https://npm.pkg.github.com
-```
-
-npm scope 映射如下：
-
-```ini
-@xbibzlibrary:registry=https://npm.pkg.github.com
-```
-
-release workflow 会在 typecheck、测试、构建、安全审计和 release check 全部通过后，将同一个经过验证的 tarball 发布到 npmjs 和 GitHub Packages。workflow 使用具有 `packages: write` 权限的 `GITHUB_TOKEN`，不会把 GitHub personal access token 存储在仓库或 workflow 文件中。
-
-## 安装 package
-
-对于 public package，可以在使用方项目的 `.npmrc` 中加入：
-
-```ini
-@xbibzlibrary:registry=https://npm.pkg.github.com
-```
-
-如果 package 或 repository 是 private，请使用具有至少 `read:packages` 权限的 **personal access token (classic)**。请将 token 保存在仓库之外，建议使用 npm 用户配置中的环境变量引用：
-
-```ini
-@xbibzlibrary:registry=https://npm.pkg.github.com
-//npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}
-```
-
-然后执行：
-
-```bash
-export GITHUB_PACKAGES_TOKEN="<your-read-packages-token>"
-npm install @xbibzlibrary/telebibz
-```
-
-不要把真实 token 写入已经提交的文件。不要提交包含明文凭据的 `.npmrc`，也不要在 issue、pull request、日志或聊天中粘贴 token。
-
-## 本地发布
-
-推荐使用受保护的 GitHub Actions workflow 发布。workflow 会检查版本，并且只有所有 release gate 成功后才会发布。本地发布仅适用于拥有 `write:packages` classic token 以及 repository 发布权限的 maintainer：
-
-```bash
-export GITHUB_PACKAGES_TOKEN="<your-write-packages-token>"
-printf '@xbibzlibrary:registry=https://npm.pkg.github.com\n//npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}\n' > "$HOME/.npmrc"
-npm run build
-npm pack
-npm publish ./xbibzlibrary-telebibz-<version>.tgz --registry=https://npm.pkg.github.com --access public
-```
-
-每次发布必须使用新的 semantic version。registry 中的版本是 immutable，不能覆盖已有版本。
-
-## GitHub Actions 权限
-
-release workflow 声明了发布所需的最小权限：
-
-```yaml
-permissions:
-  contents: write
-  packages: write
-```
-
-`NPM_TOKEN` 仍然作为 npmjs 发布所需的 environment secret。GitHub Packages 使用自动提供的 `GITHUB_TOKEN`，因此本仓库的 package 不需要额外的 GitHub token secret。如果组织策略关闭了 package 权限自动继承，请在 package 设置中连接 repository，并授予 workflow 访问权限。
-
-## 故障排查
-
-`401 Unauthorized` 通常表示 token 缺失、过期或没有正确的 package scope。`403 Forbidden` 通常表示账号或 workflow 没有 package 权限，或者组织策略禁止发布。访问 private package 时没有认证，或 scope 没有映射到 `https://npm.pkg.github.com`，也可能得到 `404 Not Found`。
-
-从 npmjs 安装时，请删除 GitHub scope mapping 或使用默认 npm registry。两个 registry 包含相同的 package 名称和版本，但认证和 access control 独立管理。
-
-## 参考资料
-
-1. [Working with the npm registry — GitHub Docs](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry)
-2. [About permissions for GitHub Packages — GitHub Docs](https://docs.github.com/en/packages/learn-github-packages/about-permissions-for-github-packages)
-3. [Publishing and installing a package with GitHub Actions — GitHub Docs](https://docs.github.com/en/packages/quickstart)
-4. [npm package.json publishConfig — npm Docs](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#publishconfig)

package/docs/MIGRATION_TELEGRAF.id.md

@@ -1,147 +0,0 @@
-# Migrasi dari Telegraf (Bahasa Indonesia)
-
-telebibz mengimplementasikan surface context dan opsi launch Telegraf secara sengaja, sehingga sebagian besar handler bisa dipindah dengan sedikit atau tanpa perubahan. Panduan ini memetakan setiap bagian bot Telegraf ke padanannya di telebibz.
-
-## Daftar isi
-
-1. [Side-by-side: satu bot utuh](#1-side-by-side-satu-bot-utuh)
-2. [Peta konsep](#2-peta-konsep)
-3. [Method Context](#3-method-context)
-4. [Opsi launch](#4-opsi-launch)
-5. [Scenes → Wizards](#5-scenes--wizards)
-6. [Penyimpanan session](#6-penyimpanan-session)
-7. [Webhook](#7-webhook)
-8. [Yang tidak punya ekuivalen langsung](#8-yang-tidak-punya-ekuivalen-langsung)
-
-## 1. Side-by-side: satu bot utuh
-
-**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!"); });   // command bernama, bukan 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 });   // nama opsi sama
-```
-
-Hanya dua perbedaan mekanis: `bot.start(handler)` menjadi `bot.command("start", handler)`, dan `answerCbQuery()` menjadi `answerCallbackQuery()`.
-
-## 2. Peta konsep
-
-| Telegraf | telebibz | Catatan |
-|---|---|---|
-| `new Telegraf(token)` | `new Bot(token)` atau `new Bot({ token, ... })` | |
-| `bot.launch()` | `bot.launch()` / `bot.start()` | `mode: "polling"` eksplisit di `launch` |
-| `bot.stop()` | `bot.stop()` | telebibz men-drain handler yang sedang berjalan lebih dulu |
-| `bot.use(mw)` | `bot.use(mw)` | signature middleware sama `(ctx, next)` |
-| `bot.command(name, h)` | `bot.command(name, h)` | |
-| `bot.on(filter, h)` | `bot.on(filter, h)` | grammar filter sama (`message:photo`, array) |
-| `bot.hears(trigger, h)` | `bot.hears(trigger, h)` | string dan RegExp |
-| `bot.action(pattern, h)` | `bot.action(pattern, h)` | alias drop-in dari `bot.callback` |
-| `bot.catch(handler)` | `bot.catch(handler)` | menerima `(error, ctx)` |
-
-## 3. Method Context
-
-Setiap shortcut context Telegraf ada — termasuk yang di Telegraf diserahkan ke plugin:
-
-- **Balasan**: `reply`, `replyWithPhoto`, `replyWithDocument`, `replyWithVideo`, `replyWithAudio`, `replyWithVoice`, `replyWithAnimation`, `replyWithVideoNote`, `replyWithSticker`, `replyWithMediaGroup`, `replyWithLocation`, `replyWithVenue`, `replyWithContact`, `replyWithPoll`, `replyWithQuiz`, `replyWithDice`, `replyWithGame`, `replyWithInvoice`, `replyWithHTML`, `replyWithMarkdown` (+V2)
-- **Admin/moderasi**: `banChatMember`, `unbanChatMember`, `restrictChatMember`, `promoteChatMember`, `banChatSenderChat`, `unbanChatSenderChat`
-- **Chat**: `setChatTitle`, `setChatDescription`, `setChatPhoto`, `deleteChatPhoto`, `setChatPermissions`, `leaveChat`, `unpinAllChatMessages`, `setChatStickerSet`, `deleteChatStickerSet`
-- **Info**: `getChat`, `getChatAdministrators`, `getChatMemberCount`, `getChatMember`
-- **Invite link/join request**: `exportChatInviteLink`, `createChatInviteLink`, `editChatInviteLink`, `revokeChatInviteLink`, `approveChatJoinRequest`, `declineChatJoinRequest`
-- **Live location/poll/game**: `editMessageLiveLocation`, `stopMessageLiveLocation`, `stopPoll`, `setGameScore`, `getGameHighScores`
-- **Forum**: set topik lengkap (`createForumTopic` … `unhideGeneralForumTopic`)
-- **Baru, melampaui core Telegraf**: `getFile` (typed), `downloadFile`, `edit` (menulis ulang teks pesan saat ini), plus helper mandiri yang diekspor dari root paket — `validateUpload`/`assertValidUpload` — yang bukan method context
-
-Perbedaan penamaan yang harus diperbaiki saat porting: `answerCbQuery` → `answerCallbackQuery`; `ctx.telegram` → `ctx.api`; helper keyboard berasal dari root paket (`InlineKeyboard`, `ReplyKeyboard`, `removeKeyboard`, `forceReply`) alih-alih `Markup`.
-
-## 4. Opsi launch
-
-| Telegraf | telebibz |
-|---|---|
-| `launch({ dropPendingUpdates })` | `launch({ dropPendingUpdates })` — identik |
-| `handlerTimeout` (default 90 000) | `handlerTimeout` (default 90 000; `0` menonaktifkan) |
-| Opsi `contextType` | Opsi `contextType` — subclass `Context` Anda diinstansiasi untuk setiap update |
-| `webhookReply` (per-update) | `webhookReply` pada opsi handler / `handleUpdate` |
-| `telegraf.use(session(...))` | `new Bot({ session: new MemoryStorage() })` (atau JSON/Redis/SQL/Mongo) |
-
-## 5. Scenes → Wizards
-
-`WizardScene` + `Stage` milik Telegraf menjadi satu `Wizard` dengan step eksplisit dan tanpa kunci session global:
-
-```ts
-import { Bot, Wizard } from "@xbibzlibrary/telebibz";
-
-const wizard = new Wizard()
-  .step({ id: "ask-name", run: async (flow) => { flow.next(); await flow.ctx.reply("Nama?"); } })
-  .step({ id: "save", run: async (flow) => { await flow.ctx.reply(`Hai ${flow.ctx.message?.text}!`); } });
-
-const bot = new Bot(process.env.TELEGRAM_BOT_TOKEN!);
-bot.useWizard(wizard);                                    // menggantikan middleware Stage
-bot.command("start", async (ctx) => { await wizard.run(ctx); }); // menggantikan scene.enter()
-```
-
-- Kunci wizard diturunkan otomatis dari chat + pengirim — tanpa pengelolaan kunci manual.
-- `flow.set(key, value)` / `flow.get(key)` menggantikan `ctx.scene.session`.
-- `/cancel` membatalkan; conversation selesai otomatis setelah step terakhir.
-- Untuk graf non-linear, susun `ConversationManager` dengan router (telebibz sengaja menjadikan orkestrasi scene milik aplikasi; lihat "Design decisions" di FEATURE_MATRIX).
-
-## 6. Penyimpanan session
-
-Telegraf menyimpan session di memori secara default dan butuh plugin store untuk persistensi. telebibz menerima storage di constructor — ganti adapter, pertahankan kode:
-
-```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"),   // atau MemoryStorage / RedisStorage / SqlStorage / MongoStorage
-});
-```
-
-Resep wiring lengkap untuk setiap adapter: [STORAGE.id.md](STORAGE.id.md).
-
-## 7. Webhook
-
-```ts
-// Telegraf: webhookCallback(bot, app)
-// telebibz: framework eksplisit
-import { webhookCallback } from "@xbibzlibrary/telebibz";
-app.post("/telegram", webhookCallback(bot, "express", { secretToken: process.env.TELEGRAM_WEBHOOK_SECRET }));
-```
-
-`createWebhookHandler()` tambahan menyediakan handler Web-standard `Request → Response` untuk Bun/Deno/edge. Panduan deployment lengkap: [WEBHOOK.id.md](WEBHOOK.id.md).
-
-## 8. Yang tidak punya ekuivalen langsung
-
-- **Client low-level `bot.telegram`** — pakai `bot.api` (`call`, `raw`, `methods`, `downloadFile`); flood gate dan retry terpasang di transport, bukan dikonfigurasi per panggilan.
-- **Ekosistem plugin Telegraf** — port plugin sebagai objek `Plugin` dengan lifecycle eksplisit (`install`, `onStop`, `dispose`); plugin manager di-restart dengan bersih.
-- **`Composer.mount`/scene dinamis** — bangun dengan nesting `Router` dan `matchMode: "all"`.
-- **Rantai helper Markup** (`Markup.keyboard(...).resize()`) — pakai `new ReplyKeyboard().text("A").resized().build()`; payload sama, gaya builder.
-
-English: [MIGRATION_TELEGRAF.md](MIGRATION_TELEGRAF.md) · 简体中文: [MIGRATION_TELEGRAF.zh-CN.md](MIGRATION_TELEGRAF.zh-CN.md)

package/docs/MIGRATION_TELEGRAF.md

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