@xbibzlibrary/telebibz 0.4.4 → 3.0.1

package/docs/GETTING_STARTED.id.md

@@ -1,85 +0,0 @@
-# Memulai dengan Telebibz
-
-Panduan ini membawa developer baru dari instalasi hingga bot Telegram yang berjalan dalam beberapa menit.
-
-## 1. Buat token bot
-
-Buat bot melalui akun resmi pengelola bot Telegram dan simpan token di environment deployment. Jangan pernah commit token ke source control.
-
-## 2. Instal Telebibz
-
-```bash
-mkdir my-telebibz-bot && cd my-telebibz-bot
-npm init -y
-npm install @xbibzlibrary/telebibz
-npm install --save-dev tsx typescript
-```
-
-Atur secret melalui secret manager atau export variable pada shell:
-
-```bash
-export TELEGRAM_BOT_TOKEN="<token-bot-kamu>"
-```
-
-## 3. Tulis bot pertama
-
-Buat `index.ts`:
-
-```ts
-import { Bot } from "@xbibzlibrary/telebibz";
-
-const token = process.env.TELEGRAM_BOT_TOKEN;
-if (!token) throw new Error("TELEGRAM_BOT_TOKEN wajib diisi.");
-
-const bot = new Bot(token);
-bot.command("start", async (ctx) => { await ctx.reply("Telebibz berhasil berjalan."); });
-bot.onText("ping", async (ctx) => { await ctx.reply("pong"); });
-
-await bot.start();
-```
-
-Jalankan:
-
-```bash
-npx tsx index.ts
-```
-
-Kirim `/start` atau `ping` ke bot. Terminal akan menampilkan branding Telebibz dan log terstruktur. Gunakan format logger `json` jika output akan dikonsumsi log collector.
-
-## 4. Tambahkan wizard multi-langkah
-
-Gunakan `Wizard` dan `bot.useWizard()` ketika jawaban harus melanjutkan step aktif. Mulai flow secara eksplisit dengan `wizard.run(ctx)`:
-
-```ts
-const wizard = new Wizard()
-  .step({ id: "name", run: async (flow) => {
-    flow.set("name", flow.ctx.message?.text?.trim()).next();
-    await flow.ctx.reply("Berapa umur kamu?");
-  }})
-  .step({ id: "age", run: async (flow) => {
-    const age = Number(flow.ctx.message?.text?.trim());
-    if (!Number.isInteger(age)) { await flow.ctx.reply("Kirim angka bulat."); return; }
-    flow.set("age", age).next();
-    await flow.ctx.reply("Registrasi selesai.");
-  }});
-
-bot.useWizard(wizard);
-bot.command("register", async (ctx) => {
-  await wizard.run(ctx);
-  await ctx.reply("Siapa nama kamu?");
-});
-```
-
-Conversation manager default tetap digunakan selama instance wizard hidup, sedangkan key dibuat dari identitas chat dan pengirim. `/cancel` membatalkan flow aktif secara default.
-
-## 5. Checklist production
-
-Gunakan HTTPS untuk webhook, validasi secret webhook Telegram, simpan token di secret manager, gunakan structured JSON logs, tambahkan health check, gunakan persistent storage untuk session yang harus bertahan setelah restart, dan jalankan `npm run typecheck`, `npm run test:types`, `npm run test:examples`, `npm test`, `npm run build`, serta `npm run security` sebelum deploy.
-
-## Langkah berikutnya
-
-- [Runnable examples](../examples/README.md)
-- [Referensi API lengkap](API.id.md)
-- [Webhook API](API.id.md#10-webhook)
-- [Conversation dan wizard](API.id.md#8-state-session-and-conversations)
-- [Panduan kontribusi](../CONTRIBUTING.md)

package/docs/GETTING_STARTED.md

@@ -1,85 +0,0 @@
-# Getting started with Telebibz
-
-This guide takes a new developer from installation to a working Telegram bot in a few minutes.
-
-## 1. Create a bot token
-
-Create a bot with Telegram's official bot management account and keep the token in your deployment environment. Never commit it to source control.
-
-## 2. Install Telebibz
-
-```bash
-mkdir my-telebibz-bot && cd my-telebibz-bot
-npm init -y
-npm install @xbibzlibrary/telebibz
-npm install --save-dev tsx typescript
-```
-
-Create `.env` through your secret manager or export the variable in the shell:
-
-```bash
-export TELEGRAM_BOT_TOKEN="<your-bot-token>"
-```
-
-## 3. Write the first bot
-
-Create `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();
-```
-
-Run it with:
-
-```bash
-npx tsx index.ts
-```
-
-Send `/start` or `ping` to the bot. The terminal displays the Telebibz branding and structured logs. Set the logger format to `json` when a log collector consumes the output.
-
-## 4. Add a multi-step wizard
-
-Use `Wizard` and `bot.useWizard()` when replies should continue through active steps. Start the flow explicitly with `wizard.run(ctx)`:
-
-```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?");
-});
-```
-
-The default conversation manager persists for the lifetime of the wizard instance, and the key is derived from chat and sender identity. `/cancel` cancels the active flow by default.
-
-## 5. Production checklist
-
-Use HTTPS for webhooks, verify the Telegram webhook secret, keep tokens in a secret manager, configure structured JSON logs, add health checks, use persistent storage for sessions that must survive restarts, and run `npm run typecheck`, `npm run test:types`, `npm run test:examples`, `npm test`, `npm run build`, and `npm run security` before deployment.
-
-## Next steps
-
-- [Runnable examples](../examples/README.md)
-- [Complete API reference](API.md)
-- [Webhook API](API.md#10-webhook)
-- [Conversations and wizards](API.md#8-state-session-and-conversations)
-- [Contribution guide](../CONTRIBUTING.md)

package/docs/GETTING_STARTED.zh-CN.md

@@ -1,85 +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)
-- [Webhook API](API.zh-CN.md#10-webhook)
-- [Conversation 和 wizard](API.zh-CN.md#8-state-session-and-conversations)
-- [贡献指南](../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/README.md

@@ -1,48 +0,0 @@
-# telebibz Documentation
-
-The default documentation language is **English**. Translated README and API references are available below.
-
-| 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) |
-
-![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.
-
-| 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. |
-
-| 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 |
-| 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` |
-| 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 |
-| 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` |
-| 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` |
-| GitHub contribution templates | Bug, feature, documentation, question/support, security notice, and pull request templates under `.github/` |
-
-## GitHub templates
-
-Issue forms are available for bug reports, feature requests, documentation problems, and support questions. A security notice template redirects reporters to the private process in `SECURITY.md`; vulnerabilities must not be disclosed in public issues. Pull requests use `.github/PULL_REQUEST_TEMPLATE/pull_request_template.md` to require tests, documentation, compatibility, and security checks.
-
-## 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.

package/docs/STORAGE.id.md

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