@xbibzlibrary/telebibz 0.4.5 → 3.0.1

package/docs/MIGRATION_TELEGRAF.zh-CN.md

@@ -1,147 +0,0 @@
-# 从 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,67 +0,0 @@
-# telebibz Documentation
-
-The default documentation language is **English**. Every guide below is available in English, Bahasa Indonesia, and 简体中文.
-
-| 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, files, errors, webhook deployment, testing, migration, and production recipes.
-
-## 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 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 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 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` |
-| 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, 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

@@ -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).

package/docs/STORAGE.md

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

package/docs/STORAGE.zh-CN.md

@@ -1,105 +0,0 @@
-# 存储快速上手（简体中文）
-
-telebibz 提供一个通用的 `Storage<K, V>` 接口和五个适配器。核心包**零运行时依赖**：Redis、SQL 和 Mongo 适配器只要求一个你已经拥有的小型 driver interface，由你自己选择驱动和版本。
-
-所有适配器共享同一契约 —— `get` / `set` / `delete` / `has` / `clear` / `keys()` / `entries()` —— 以及 **`update(key, updater, { ttlMs })`**，它按 key 串行化写入，因此对同一 key 的并发更新永远不会交错。TTL 通过 `{ ttlMs }` 按每次写入设置。
-
-## MemoryStorage（默认 —— 无需配置）
-
-```ts
-import { Bot } from "@xbibzlibrary/telebibz";
-
-const bot = new Bot({ token: process.env.TELEGRAM_BOT_TOKEN! });
-// bot.session 默认就是 MemoryStorage<string, S>。
-```
-
-## JsonFileStorage（单文件持久化，依然零依赖）
-
-```ts
-import { Bot, JsonFileStorage } from "@xbibzlibrary/telebibz";
-
-const bot = new Bot({
-  token: process.env.TELEGRAM_BOT_TOKEN!,
-  session: new JsonFileStorage("state/sessions.json"),
-});
-```
-
-## RedisStorage（自带客户端）
-
-适配器只需要每个 Redis 客户端都有的五个回调式方法 —— `node-redis` 可以直接使用：
-
-```ts
-import { Bot, RedisStorage } from "@xbibzlibrary/telebibz";
-import { createClient } from "redis"; // 由你选择驱动和版本
-
-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:"), // 你的 key 前缀
-});
-// 按次写入的 TTL：await bot.session.set(key, value, { ttlMs: 24 * 60 * 60 * 1000 });
-// （Redis PX 过期会自动应用。）
-```
-
-## SqlStorage（任意 SQL 数据库）
-
-在你的 SQL 库之上实现这五个方法的 driver；示例使用 `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（自带 collection）
-
-适配器直接对接标准 MongoDB collection 形状 —— 直接传入你的 collection：
-
-```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")),
-});
-```
-
-## 如何选择
-
-| 适配器 | 适用场景 | 持久化 | 额外依赖 |
-|---|---|---|---|
-| `MemoryStorage` | 单进程 bot、测试 | 进程生命周期 | 无 |
-| `JsonFileStorage` | 小型 bot、简单部署 | 磁盘文件 | 无 |
-| `RedisStorage` | 多实例、共享状态 | Redis | 你的 Redis 客户端 |
-| `SqlStorage` | 基于 SQL 的应用 | 任意 SQL 数据库 | 你的 SQL 驱动 |
-| `MongoStorage` | 已有 Mongo 技术栈 | MongoDB | 你的 Mongo 驱动 |
-
-完整 API 签名：[API.zh-CN.md](API.zh-CN.md)。English: [STORAGE.md](STORAGE.md) · Bahasa Indonesia: [STORAGE.id.md](STORAGE.id.md)。