@xbibzlibrary/telebibz 0.4.3 → 0.4.5

package/docs/STORAGE.zh-CN.md

@@ -0,0 +1,105 @@
+# 存储快速上手（简体中文）
+
+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)。

package/docs/TESTING.id.md

@@ -0,0 +1,203 @@
+# Panduan testing (Bahasa Indonesia)
+
+Uji bot telebibz sepenuhnya offline: palsukan transport, rakit update, asersikan panggilan keluar, dan jalankan conversation utuh end-to-end.
+
+## Daftar isi
+
+1. [Subpath testing](#1-subpath-testing)
+2. [MockTransport](#2-mocktransport)
+3. [Men-drive update ke dalam bot](#3-men-drive-update-ke-dalam-bot)
+4. [Asersi panggilan keluar](#4-asersi-panggilan-keluar)
+5. [Menguji wizard end-to-end](#5-menguji-wizard-end-to-end)
+6. [Menguji unduhan file](#6-menguji-unduhan-file)
+7. [Menguji webhook](#7-menguji-webhook)
+8. [Menguji jalur error](#8-menguji-jalur-error)
+9. [Pola Vitest / Jest](#9-pola-vitest--jest)
+
+## 1. Subpath testing
+
+Semuanya tersedia dari `@xbibzlibrary/telebibz/testing`:
+
+```ts
+import { MockTransport, createTestBot, createMockUpdate, createMockCallbackUpdate, createMockContext } from "@xbibzlibrary/telebibz/testing";
+```
+
+- `createTestBot()` → `{ bot, transport }` — sebuah `Bot` yang terhubung ke `MockTransport`, branding dimatikan.
+- `createMockUpdate(overrides?)` → update pesan teks `/start` sederhana.
+- `createMockCallbackUpdate(overrides?)` → update callback-query.
+- `createMockContext(bot, update?)` → sebuah `Context` tanpa me-routing apa pun.
+
+## 2. MockTransport
+
+`MockTransport` merekam setiap request keluar dan menjawab dari response yang dikonfigurasi:
+
+```ts
+const { bot, transport } = createTestBot();
+
+transport.respond("getMe", { ok: true, result: { id: 99, is_bot: true, first_name: "TestBot", username: "test_bot" } });
+transport.respond("sendMessage", { ok: true, result: { message_id: 1, date: 0, chat: { id: 1, type: "private" } } });
+transport.respond("getFile", (payload) => ({                                   // jawaban dinamis
+  ok: true,
+  result: { file_id: (payload as { file_id: string }).file_id, file_unique_id: "u", file_path: "documents/a.pdf" },
+}));
+```
+
+Method yang tidak dikonfigurasi menjawab `{ ok: true, result: true }` — cukup untuk panggilan yang hasilnya Anda abaikan.
+
+Ia juga mengimplementasikan member download:
+
+```ts
+transport.downloadBytes = new TextEncoder().encode("file-content");
+transport.downloads;            // setiap file_path yang diberikan ke download(), berurutan
+transport.fileUrl("a.pdf");     // "mock://files/a.pdf"
+```
+
+## 3. Men-drive update ke dalam bot
+
+Daftarkan handler, lalu kirim update — tanpa jaringan, tanpa token:
+
+```ts
+bot.on("message", async (ctx) => { await ctx.reply("hi"); });
+await bot.init();                       // tepat satu getMe, seperti produksi
+
+await bot.handleUpdate(createMockUpdate({ message: { ...createMockUpdate().message!, text: "hello" } }));
+await bot.handleUpdates([updateA, updateB, updateC]);   // satu batch penuh, paralel antar chat
+```
+
+Untuk mensimulasikan beberapa chat, variasikan chat id:
+
+```ts
+function textUpdate(updateId: number, chatId: number, text: string) {
+  const base = createMockUpdate();
+  return { ...base, update_id: updateId, message: { ...base.message!, chat: { id: chatId, type: "private" as const }, text } };
+}
+```
+
+## 4. Asersi panggilan keluar
+
+Setiap request tercatat di `transport.calls` lengkap dengan method dan payload-nya:
+
+```ts
+const replies = transport.calls
+  .filter((call) => call.method === "sendMessage")
+  .map((call) => (call.payload as { text?: string }).text);
+
+expect(replies).toEqual(["Siapa nama Anda?", "Berapa usia Anda?"]);
+
+// Keyboard callback:
+const markup = (transport.calls.at(-1)?.payload as { reply_markup?: { inline_keyboard: unknown[][] } }).reply_markup;
+expect(markup?.inline_keyboard).toHaveLength(2);
+```
+
+## 5. Menguji wizard end-to-end
+
+Berikan conversation satu pesan demi satu pesan dan asersikan balasan yang akan dilihat user:
+
+```ts
+import { Bot, Wizard } from "@xbibzlibrary/telebibz";
+
+const wizard = new Wizard()
+  .step({ id: "ask", run: async (flow) => { flow.next(); await flow.ctx.reply("Siapa nama Anda?"); } })
+  .step({ id: "save", run: async (flow) => { await flow.ctx.reply(`Halo, ${flow.ctx.message?.text}!`); } });
+bot.useWizard(wizard);
+bot.command("start", async (ctx) => { await wizard.run(ctx); });
+
+await bot.handleUpdate(textUpdate(1, 7, "/start"));
+await bot.handleUpdate(textUpdate(2, 7, "Dewi"));
+
+expect(sentTexts()).toEqual(["Siapa nama Anda?", "Halo, Dewi!"]);
+```
+
+Dua chat, dua wizard independen — update yang berselang-seling tetap terisolasi karena update dari chat yang sama diserialisasi:
+
+```ts
+await bot.handleUpdate(textUpdate(1, 7, "/start"));
+await bot.handleUpdate(textUpdate(2, 8, "/start"));
+await bot.handleUpdate(textUpdate(3, 7, "Dewi"));
+await bot.handleUpdate(textUpdate(4, 8, "Budi"));
+expect(sentTexts()).toEqual(["Siapa nama Anda?", "Siapa nama Anda?", "Halo, Dewi!", "Halo, Budi!"]);
+```
+
+## 6. Menguji unduhan file
+
+```ts
+transport.respond("getFile", { ok: true, result: { file_id: "F1", file_unique_id: "U1", file_path: "photos/pic.jpg" } });
+transport.downloadBytes = new TextEncoder().encode("jpeg-bytes");
+
+const file = await bot.downloadFile("F1", { destination: tmpFile });
+expect(file.fileName).toBe("pic.jpg");
+expect(transport.downloads).toEqual(["photos/pic.jpg"]);
+expect(await readFile(tmpFile, "utf8")).toBe("jpeg-bytes");
+```
+
+## 7. Menguji webhook
+
+`createWebhookHandler` menerima `Request` Web sungguhan:
+
+```ts
+const handler = createWebhookHandler(bot, { secretToken: "s3cret" });
+
+const response = await handler(new Request("https://example.com/telegram", {
+  method: "POST",
+  headers: { "content-type": "application/json", "x-telegram-bot-api-secret-token": "s3cret" },
+  body: JSON.stringify(createMockUpdate()),
+}));
+expect(response.status).toBe(200);
+
+// Secret salah → ditolak sebelum handler mana pun berjalan
+const rejected = await handler(new Request("https://example.com/telegram", {
+  method: "POST",
+  headers: { "content-type": "application/json", "x-telegram-bot-api-secret-token": "salah" },
+  body: JSON.stringify(createMockUpdate()),
+}));
+expect(rejected.status).toBe(401);
+```
+
+## 8. Menguji jalur error
+
+```ts
+// Telegram menolak panggilan
+transport.respond("sendMessage", { ok: false, error_code: 400, description: "Bad Request: chat not found" });
+await expect(ctx.reply("hi")).rejects.toThrow(/chat not found/);
+
+// Handler melempar — asersikan error boundary melihatnya
+const errors: unknown[] = [];
+bot.events.on("update:error", ({ error }) => errors.push(error));
+bot.onText("boom", async () => { throw new Error("boom"); });
+await bot.handleUpdate(textUpdate(1, 7, "boom"));
+expect(errors).toHaveLength(1);
+
+// handlerTimeout: update yang menggantung melempar UpdateTimeoutError sementara handler tetap berjalan
+const slow = new Bot({ token: "123456:TEST", transport, handlerTimeout: 50, branding: false, logger: { level: "silent" } });
+let finished = false;
+slow.on("message", async () => { await sleep(200); finished = true; });
+await expect(slow.handleUpdate(createMockUpdate())).rejects.toBeInstanceOf(UpdateTimeoutError);
+// nanti:
+expect(finished).toBe(true);
+```
+
+## 9. Pola Vitest / Jest
+
+**Senyapkan logger di test** — `logger: { level: "silent" }` tidak memancarkan apa pun (diuji regresi):
+
+```ts
+const bot = new Bot({ token: "123456:TEST", transport, branding: false, logger: { level: "silent" } });
+```
+
+**Transport segar per test** — jangan pernah berbagi state antar kasus:
+
+```ts
+beforeEach(() => { ({ bot, transport } = createTestBot()); });
+```
+
+**Mempercepat waktu** — untuk test `Scheduler`/TTL pakai fake timer atau interval kecil (`1ms`); parser cron murni dan bisa diuji tanpa timer:
+
+```ts
+import { nextCronOccurrence, parseCronExpression } from "@xbibzlibrary/telebibz";
+expect(parseCronExpression("*/15 * * * *")).toBeDefined();
+expect(nextCronOccurrence("0 9 * * 1", new Date("2026-08-29T00:00:00Z")).toISOString()).toContain("T09:00");
+```
+
+**Jalankan suite**: `npm test` — test E2E yang membutuhkan token asli otomatis di-skip ketika `TELEGRAM_BOT_TOKEN` tidak ada.
+
+English: [TESTING.md](TESTING.md) · 简体中文: [TESTING.zh-CN.md](TESTING.zh-CN.md)

package/docs/TESTING.md

@@ -0,0 +1,203 @@
+# Testing guide (English)
+
+Test telebibz bots fully offline: fake the transport, craft updates, assert outgoing calls, and drive whole conversations end to end.
+
+## Contents
+
+1. [The testing subpath](#1-the-testing-subpath)
+2. [MockTransport](#2-mocktransport)
+3. [Driving updates through the bot](#3-driving-updates-through-the-bot)
+4. [Asserting outgoing calls](#4-asserting-outgoing-calls)
+5. [Testing wizards end to end](#5-testing-wizards-end-to-end)
+6. [Testing file downloads](#6-testing-file-downloads)
+7. [Testing webhooks](#7-testing-webhooks)
+8. [Testing error paths](#8-testing-error-paths)
+9. [Vitest / Jest patterns](#9-vitest--jest-patterns)
+
+## 1. The testing subpath
+
+Everything ships from `@xbibzlibrary/telebibz/testing`:
+
+```ts
+import { MockTransport, createTestBot, createMockUpdate, createMockCallbackUpdate, createMockContext } from "@xbibzlibrary/telebibz/testing";
+```
+
+- `createTestBot()` → `{ bot, transport }` — a `Bot` wired to a `MockTransport`, branding off.
+- `createMockUpdate(overrides?)` → a plain text `/start` message update.
+- `createMockCallbackUpdate(overrides?)` → a callback-query update.
+- `createMockContext(bot, update?)` → a `Context` without routing anything.
+
+## 2. MockTransport
+
+`MockTransport` records every outgoing request and answers from configured responses:
+
+```ts
+const { bot, transport } = createTestBot();
+
+transport.respond("getMe", { ok: true, result: { id: 99, is_bot: true, first_name: "TestBot", username: "test_bot" } });
+transport.respond("sendMessage", { ok: true, result: { message_id: 1, date: 0, chat: { id: 1, type: "private" } } });
+transport.respond("getFile", (payload) => ({                                   // dynamic answers
+  ok: true,
+  result: { file_id: (payload as { file_id: string }).file_id, file_unique_id: "u", file_path: "documents/a.pdf" },
+}));
+```
+
+Unconfigured methods answer `{ ok: true, result: true }` — enough for calls whose result you ignore.
+
+It also implements the download members:
+
+```ts
+transport.downloadBytes = new TextEncoder().encode("file-content");
+transport.downloads;            // every file_path passed to download(), in order
+transport.fileUrl("a.pdf");     // "mock://files/a.pdf"
+```
+
+## 3. Driving updates through the bot
+
+Register handlers, then feed updates — no network, no token:
+
+```ts
+bot.on("message", async (ctx) => { await ctx.reply("hi"); });
+await bot.init();                       // exactly one getMe, like production
+
+await bot.handleUpdate(createMockUpdate({ message: { ...createMockUpdate().message!, text: "hello" } }));
+await bot.handleUpdates([updateA, updateB, updateC]);   // whole batch, parallel across chats
+```
+
+To simulate several chats, vary the chat id:
+
+```ts
+function textUpdate(updateId: number, chatId: number, text: string) {
+  const base = createMockUpdate();
+  return { ...base, update_id: updateId, message: { ...base.message!, chat: { id: chatId, type: "private" as const }, text } };
+}
+```
+
+## 4. Asserting outgoing calls
+
+Every request is recorded in `transport.calls` with its method and payload:
+
+```ts
+const replies = transport.calls
+  .filter((call) => call.method === "sendMessage")
+  .map((call) => (call.payload as { text?: string }).text);
+
+expect(replies).toEqual(["What is your name?", "How old are you?"]);
+
+// Callback keyboards:
+const markup = (transport.calls.at(-1)?.payload as { reply_markup?: { inline_keyboard: unknown[][] } }).reply_markup;
+expect(markup?.inline_keyboard).toHaveLength(2);
+```
+
+## 5. Testing wizards end to end
+
+Feed the conversation one message at a time and assert the replies the user would see:
+
+```ts
+import { Bot, Wizard } from "@xbibzlibrary/telebibz";
+
+const wizard = new Wizard()
+  .step({ id: "ask", 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}!`); } });
+bot.useWizard(wizard);
+bot.command("start", async (ctx) => { await wizard.run(ctx); });
+
+await bot.handleUpdate(textUpdate(1, 7, "/start"));
+await bot.handleUpdate(textUpdate(2, 7, "Alice"));
+
+expect(sentTexts()).toEqual(["Name?", "Hi Alice!"]);
+```
+
+Two chats, two independent wizards — interleaved updates stay isolated because same-chat updates serialize:
+
+```ts
+await bot.handleUpdate(textUpdate(1, 7, "/start"));
+await bot.handleUpdate(textUpdate(2, 8, "/start"));
+await bot.handleUpdate(textUpdate(3, 7, "Alice"));
+await bot.handleUpdate(textUpdate(4, 8, "Bob"));
+expect(sentTexts()).toEqual(["Name?", "Name?", "Hi Alice!", "Hi Bob!"]);
+```
+
+## 6. Testing file downloads
+
+```ts
+transport.respond("getFile", { ok: true, result: { file_id: "F1", file_unique_id: "U1", file_path: "photos/pic.jpg" } });
+transport.downloadBytes = new TextEncoder().encode("jpeg-bytes");
+
+const file = await bot.downloadFile("F1", { destination: tmpFile });
+expect(file.fileName).toBe("pic.jpg");
+expect(transport.downloads).toEqual(["photos/pic.jpg"]);
+expect(await readFile(tmpFile, "utf8")).toBe("jpeg-bytes");
+```
+
+## 7. Testing webhooks
+
+`createWebhookHandler` accepts a real Web `Request`:
+
+```ts
+const handler = createWebhookHandler(bot, { secretToken: "s3cret" });
+
+const response = await handler(new Request("https://example.com/telegram", {
+  method: "POST",
+  headers: { "content-type": "application/json", "x-telegram-bot-api-secret-token": "s3cret" },
+  body: JSON.stringify(createMockUpdate()),
+}));
+expect(response.status).toBe(200);
+
+// Wrong secret → rejected before any handler runs
+const rejected = await handler(new Request("https://example.com/telegram", {
+  method: "POST",
+  headers: { "content-type": "application/json", "x-telegram-bot-api-secret-token": "wrong" },
+  body: JSON.stringify(createMockUpdate()),
+}));
+expect(rejected.status).toBe(401);
+```
+
+## 8. Testing error paths
+
+```ts
+// Telegram rejects the call
+transport.respond("sendMessage", { ok: false, error_code: 400, description: "Bad Request: chat not found" });
+await expect(ctx.reply("hi")).rejects.toThrow(/chat not found/);
+
+// A handler throws — assert the error boundary saw it
+const errors: unknown[] = [];
+bot.events.on("update:error", ({ error }) => errors.push(error));
+bot.onText("boom", async () => { throw new Error("boom"); });
+await bot.handleUpdate(textUpdate(1, 7, "boom"));
+expect(errors).toHaveLength(1);
+
+// handlerTimeout: hung updates reject with UpdateTimeoutError while the handler keeps running
+const slow = new Bot({ token: "123456:TEST", transport, handlerTimeout: 50, branding: false, logger: { level: "silent" } });
+let finished = false;
+slow.on("message", async () => { await sleep(200); finished = true; });
+await expect(slow.handleUpdate(createMockUpdate())).rejects.toBeInstanceOf(UpdateTimeoutError);
+// later:
+expect(finished).toBe(true);
+```
+
+## 9. Vitest / Jest patterns
+
+**Silence the logger in tests** — `logger: { level: "silent" }` emits nothing (regression-tested):
+
+```ts
+const bot = new Bot({ token: "123456:TEST", transport, branding: false, logger: { level: "silent" } });
+```
+
+**Fresh transport per test** — never share state between cases:
+
+```ts
+beforeEach(() => { ({ bot, transport } = createTestBot()); });
+```
+
+**Fast-forwarding time** — for `Scheduler`/TTL tests use fake timers or small intervals (`1ms`); the cron parser is pure and testable without timers:
+
+```ts
+import { nextCronOccurrence, parseCronExpression } from "@xbibzlibrary/telebibz";
+expect(parseCronExpression("*/15 * * * *")).toBeDefined();
+expect(nextCronOccurrence("0 9 * * 1", new Date("2026-08-29T00:00:00Z")).toISOString()).toContain("T09:00");
+```
+
+**Run the suite**: `npm test` — E2E tests requiring a real token are skipped automatically when `TELEGRAM_BOT_TOKEN` is absent.
+
+Bahasa Indonesia: [TESTING.id.md](TESTING.id.md) · 简体中文: [TESTING.zh-CN.md](TESTING.zh-CN.md)