@xbibzlibrary/telebibz 0.4.5 → 3.0.1

package/README.id.md

@@ -1,306 +0,0 @@
-# telebibz
-
-![telebibz logo](https://imgbs.com/uploads/telebibz-d7b30671.png)
-
-[![CI](https://github.com/XbibzOfficial777/telebibz/actions/workflows/ci.yml/badge.svg)](https://github.com/XbibzOfficial777/telebibz/actions/workflows/ci.yml)
-[![npm version](https://img.shields.io/npm/v/@xbibzlibrary/telebibz)](https://www.npmjs.com/package/@xbibzlibrary/telebibz)
-[![npm downloads](https://img.shields.io/npm/dm/@xbibzlibrary/telebibz)](https://www.npmjs.com/package/@xbibzlibrary/telebibz)
-[![Node.js](https://img.shields.io/node/v/@xbibzlibrary/telebibz)](https://www.npmjs.com/package/@xbibzlibrary/telebibz)
-
-**`@xbibzlibrary/telebibz`** adalah SDK dan framework Telegram Bot untuk Node.js dan TypeScript. Paket ini menyediakan API client, polling, router, middleware, context, keyboard builder, state/session, webhook handler, queue, scheduler, cache, plugin lifecycle, CLI, dan utilitas pengujian.
-
-[English](README.md) · **Bahasa Indonesia** · [简体中文](README.zh-CN.md)
-
-Referensi API lengkap: [English](docs/API.md) · **Indonesia** · [中文](docs/API.zh-CN.md)
-
-Panduan GitHub Packages: [English](docs/GITHUB_PACKAGES.md) · [Bahasa Indonesia](docs/GITHUB_PACKAGES.id.md) · [简体中文](docs/GITHUB_PACKAGES.zh-CN.md)
-
-Panduan cepat storage (Memory/JSON/Redis/SQL/Mongo): [English](docs/STORAGE.md) · [Bahasa Indonesia](docs/STORAGE.id.md) · [简体中文](docs/STORAGE.zh-CN.md)
-
-Panduan mulai: [English](docs/GETTING_STARTED.md) · [Bahasa Indonesia](docs/GETTING_STARTED.id.md) · [简体中文](docs/GETTING_STARTED.zh-CN.md)
-
-File (upload & download): [English](docs/FILES.md) · [Bahasa Indonesia](docs/FILES.id.md) · [简体中文](docs/FILES.zh-CN.md)
-
-Error & rate limit: [English](docs/ERRORS.md) · [Bahasa Indonesia](docs/ERRORS.id.md) · [简体中文](docs/ERRORS.zh-CN.md)
-
-Deployment webhook: [English](docs/WEBHOOK.md) · [Bahasa Indonesia](docs/WEBHOOK.id.md) · [简体中文](docs/WEBHOOK.zh-CN.md)
-
-Testing (offline dengan MockTransport): [English](docs/TESTING.md) · [Bahasa Indonesia](docs/TESTING.id.md) · [简体中文](docs/TESTING.zh-CN.md)
-
-Migrasi dari Telegraf: [English](docs/MIGRATION_TELEGRAF.md) · [Bahasa Indonesia](docs/MIGRATION_TELEGRAF.id.md) · [简体中文](docs/MIGRATION_TELEGRAF.zh-CN.md)
-
-Cookbook produksi (13 resep): [English](docs/COOKBOOK.md) · [Bahasa Indonesia](docs/COOKBOOK.id.md) · [简体中文](docs/COOKBOOK.zh-CN.md)
-
-Katalog dokumentasi lengkap: [docs/README.md](docs/README.md)
-
-Showcase komunitas: [SHOWCASE.md](SHOWCASE.md)
-
-![overview telebibz](https://cdn.jsdelivr.net/npm/@xbibzlibrary/telebibz@latest/assets/telebibz-readme-preview.png)
-
-## Instalasi
-
-```bash
-npm install @xbibzlibrary/telebibz
-```
-
-Node.js **22 atau lebih baru** diperlukan.
-
-## Bot sederhana
-
-```ts
-import { Bot } from "@xbibzlibrary/telebibz";
-
-const bot = new Bot(process.env.TELEGRAM_BOT_TOKEN!);
-
-bot.command("start", async (ctx) => { await ctx.reply("Bot aktif."); });
-bot.onText("ping", async (ctx) => { await ctx.reply("pong"); });
-
-await bot.start();
-```
-
-`Bot.start()` menjalankan long polling. Untuk siklus hidup manual, gunakan `init()`, `launch({ mode: "polling" })`, `health()`, `stop()`, atau `restart()`.
-
-## Starter resmi
-
-Repository menyediakan starter yang bisa langsung dijalankan untuk bot minimal, registration wizard multi-langkah, dan webhook Node.js. Lihat [`examples/README.md`](examples/README.md), atau jalankan starter minimal setelah mengatur `TELEGRAM_BOT_TOKEN`:
-
-```bash
-export TELEGRAM_BOT_TOKEN="<token-bot-kamu>"
-npx tsx examples/minimal.ts
-```
-
-Semua examples di-typecheck oleh CI melalui `npm run test:examples` dan tidak berisi credential asli.
-
-## Router dan middleware
-
-```ts
-bot.use(async (ctx, next) => {
-  const started = Date.now();
-  await next();
-  console.log(`processed in ${Date.now() - started}ms`);
-});
-
-bot.command("help", async (ctx) => { await ctx.reply("Bantuan tersedia."); });
-bot.onRegex(/^order:(\d+)$/, async (ctx) => { await ctx.reply("Order diterima."); });
-bot.callback("profile:*", async (ctx) => { await ctx.answerCallbackQuery("Dibuka."); });
-bot.action("menu:open", async (ctx) => { await ctx.answerCallbackQuery("Menu dibuka."); });
-bot.on("message:photo", async (ctx) => { await ctx.reply("Foto yang bagus."); });
-bot.on(["message:text", "callback_query:data"], async (ctx) => { await ctx.reply("Diterima."); });
-bot.hears("ping", async (ctx) => { await ctx.reply("pong"); });
-bot.catch(async (error, ctx) => { await ctx.reply("Terjadi kesalahan."); });
-```
-
-Router mendukung command, text, regex, pola callback, filter tipe update (`on`), predikat kustom, router bersarang, middleware per rute, dan prioritas rute. `bot.catch()` mendaftarkan error boundary: kegagalan handler diarahkan ke sana alih-alih menolak update.
-
-## Telegram API
-
-Generated method access dan raw access tersedia melalui API client:
-
-```ts
-await bot.api.methods.getMe();
-await bot.api.methods.sendMessage({ chat_id: 123456789, text: "Halo." });
-await bot.api.call("sendMessage", { chat_id: 123456789, text: "Halo." });
-await bot.api.raw("futureTelegramMethod", { value: true });
-```
-
-Transport bawaan menggunakan `fetch`, timeout, retry, exponential backoff, JSON payload, dan multipart upload.
-
-Referensi API lengkap untuk setiap class, function, method, type, error, lifecycle, CLI command, dan generated Telegram method tersedia di [`docs/API.id.md`](docs/API.id.md).
-
-## Keyboard
-
-```ts
-import { InlineKeyboard } from "@xbibzlibrary/telebibz";
-
-const keyboard = new InlineKeyboard()
-  .text("Profil", "profile")
-  .url("Dokumentasi", "https://core.telegram.org/bots/api")
-  .build();
-
-await ctx.reply("Pilih menu:", { reply_markup: keyboard });
-```
-
-Builder hanya menghasilkan payload keyboard native Telegram. UI HTML/CSS memerlukan Mini App atau Web App terpisah.
-
-## Startup dan log terminal
-
-Logger mengeluarkan baris terminal yang ringkas dan mudah dibaca dengan level berwarna serta konteks terstruktur. Level log: `silent`, `error`, `warn`, `info`, `debug`, dan `trace`; nilai sensitif di-redact; error dicetak merah lengkap dengan stack. Gunakan `format: "json"` untuk log terstruktur, dan `includeUpdateContent: true` hanya bila teks pesan atau data callback memang diperlukan.
-
-## Wizard dan conversation multi-langkah
-
-Gunakan `Wizard` bersama `bot.useWizard()` sehingga setiap balasan teks berikutnya dari chat/user yang sama otomatis diarahkan ke langkah yang sedang aktif. Key dihasilkan dari chat dan pengirim Telegram; tidak perlu key manual.
-
-```ts
-import { Bot, Wizard } from "@xbibzlibrary/telebibz";
-
-const wizard = new Wizard()
-  .step({ id: "prompt-name", run: async (flow) => { flow.next(); await flow.ctx.reply("Siapa nama kamu?"); } })
-  .step({ id: "name", run: async (flow) => { flow.set("name", flow.ctx.message?.text?.trim()); flow.next(); await flow.ctx.reply("Berapa umur kamu?"); } })
-  .step({ id: "age", run: (flow) => { const age = Number(flow.ctx.message?.text?.trim()); if (!Number.isInteger(age)) return; flow.set("age", age); flow.next(); } });
-
-const bot = new Bot(process.env.TELEGRAM_BOT_TOKEN!);
-bot.useWizard(wizard);
-bot.command("start", async (ctx) => { await wizard.run(ctx); });
-await bot.start();
-```
-
-`Wizard` mempertahankan `ConversationManager` defaultnya antar update dan menandai conversation selesai tepat setelah langkah terakhir. Gunakan `/cancel` untuk membatalkan wizard yang sedang berjalan.
-
-## Webhook
-
-```ts
-import { Bot, createWebhookHandler } from "@xbibzlibrary/telebibz";
-
-const bot = new Bot(process.env.TELEGRAM_BOT_TOKEN!);
-const handler = createWebhookHandler(bot, {
-  secretToken: process.env.TELEGRAM_WEBHOOK_SECRET,
-});
-```
-
-`createWebhookHandler` menerima Request Web standar dan menghasilkan Response. Secret token, ukuran body, parsing JSON, dan penanganan update duplikat diverifikasi oleh handler.
-
-## Update beban tinggi dan broadcast
-
-telebibz dibangun untuk burst 1000+ pesan tanpa cooldown buatan:
-
-- **Paralel antar chat, berurutan per chat.** Setiap batch `getUpdates` (dan setiap request webhook) diproses secara konkuren — update dari chat berbeda tidak pernah saling mengantre, sementara update dari chat yang sama menjaga urutan kedatangannya sehingga session, wizard, dan conversation tetap benar dan penulisan session tidak pernah hilang. Burst konkuren hanya memicu satu inisialisasi `getMe`. Jika Anda mengelola loop polling sendiri, umpankan batch yang sudah diambil lewat `bot.handleUpdates()`.
-- **Tidak ada throttling proaktif.** Permintaan keluar tidak pernah ditunda oleh library. Ketika Telegram menjawab 429, transport menunggu tepat jendela `retry_after` yang diperintahkan Telegram ("flood gate" global melindungi seluruh trafik) lalu otomatis retry — sehingga burst tetap terkirim lengkap, bukan gagal. Untuk batasan downstream Anda sendiri, `Limiter` dan `mapWithConcurrency()` mengatur laju beban kerja apa pun.
-- **Broadcast ke 1000+ user sekaligus.** `bot.broadcast()` langsung mencoba semua chat, me-retry 429 sesuai `retry_after` dari Telegram sendiri, dan mengembalikan laporan lengkap.
-- **Shutdown yang anggun.** `bot.stop()` lebih dulu menunggu handler yang sedang berjalan selesai (dibatasi `handlerTimeout`) dan baru kemudian menghentikan plugin manager — conversation yang aktif tidak pernah terpotong di tengah penulisan.
-
-```ts
-const report = await bot.broadcast(
-  subscriberIds,
-  (chatId) => bot.api.methods.sendMessage({ chat_id: chatId, text: "Newsletter #42" }),
-  { onProgress: (p) => console.log(`${p.delivered}/${p.total} terkirim`) },
-);
-console.log(`Terkirim ${report.delivered}/${report.total} dalam ${report.durationMs}ms`);
-```
-
-Batasi pekerjaan simultan dengan `new Bot({ ..., updates: { concurrency: 64 } })` atau `broadcast(..., { concurrency: 64 })` jika downstream Anda (database, API) membutuhkannya — secara default keduanya berjalan sepenuhnya paralel.
-
-## Paritas penuh Telegraf di permukaan context
-
-Semua shortcut context Telegraf tersedia, ditambah tambahan yang menutupi apa yang oleh inti Telegraf diserahkan ke ekosistem plugin-nya:
-
-- **Moderasi & admin** — `ctx.banChatMember`, `ctx.unbanChatMember`, `ctx.restrictChatMember`, `ctx.promoteChatMember`, `ctx.banChatSenderChat`, `ctx.unbanChatSenderChat`
-- **Manajemen chat** — `ctx.setChatTitle/Description/Photo`, `ctx.setChatPermissions`, `ctx.leaveChat`, `ctx.unpinAllChatMessages`, `ctx.setChatStickerSet`, `ctx.deleteChatStickerSet`
-- **Info** — `ctx.getChatAdministrators`, `ctx.getChatMemberCount`, `ctx.getChatMember`
-- **Invite link & join request** — `ctx.exportChatInviteLink`, `ctx.createChatInviteLink`, `ctx.editChatInviteLink`, `ctx.revokeChatInviteLink`, `ctx.approveChatJoinRequest`, `ctx.declineChatJoinRequest`
-- **Poll, game, pembayaran** — `ctx.replyWithQuiz`, `ctx.stopPoll`, `ctx.editMessageLiveLocation`, `ctx.stopMessageLiveLocation`, `ctx.replyWithGame`, `ctx.setGameScore`, `ctx.getGameHighScores`, `ctx.replyWithInvoice`
-- **Forum topic** — `ctx.createForumTopic`, `ctx.closeForumTopic`, `ctx.editGeneralForumTopic`, dan sembilan lainnya
-- **Opsi launch** — `handlerTimeout` (default 90 detik, seperti Telegraf) melempar `UpdateTimeoutError` untuk update yang menggantung sementara handler tetap berjalan; `0` menonaktifkan timeout; `contextType` memasang subclass `Context` Anda sendiri; `dropPendingUpdates` di `start()`/`launch()`
-- **Webhook reply** — opt-in `webhookReply: true` menjawab panggilan API pertama lewat respons HTTP webhook itu sendiri (ala Telegraf), dengan `getMe` malas yang tidak pernah mengklaim slot
-- **Alias handler drop-in** — `bot.action(...)` mendaftarkan handler callback query sama seperti `bot.callback(...)`, sehingga handler yang ditulis untuk Telegraf bisa dipindahkan tanpa perubahan
-
-## State, queue, scheduler, dan cache
-
-Paket menyediakan `MemoryStorage` dengan TTL dan pembaruan atomik, `JsonFileStorage`, `RedisStorage`, `SqlStorage`, `MongoStorage`, persistent application state storage, session bot, conversation dan form berbasis Storage, menu berbasis permission, pagination `MenuController`, `MemoryCache`, token-bucket limiter, task queue dengan retry/backoff/concurrency/delay/cancel, serta scheduler interval, one-shot, dan cron lima field lengkap. Adapter Redis, SQL, dan Mongo memakai driver kecil sehingga core package tetap tanpa runtime dependency vendor.
-
-## Pengalaman terminal
-
-Saat bot dinyalakan di terminal interaktif (`npm start`, `node index.js`, `telebibz start`), telebibz memainkan urutan startup: efek ketik `Installing Dependencies......`, glass progress bar dengan kilau menyapu, dan banner ASCII rainbow animasi **Tele Bibz** (font figlet `Speed`) yang terus mengalir sampai bot terhubung, lalu diam dengan `✓ Connected as @<username>`.
-
-Setelah itu, setiap update yang masuk ditampilkan dalam baris log yang mudah dibaca, dan error otomatis berwarna merah lengkap dengan stack-nya:
-
-```text
-[ => ] Message From 123456789 John Doe 29/08/2026 15:04:05
-        ↳ Text: /start
-[ => ] Callback From 123456789 John Doe 29/08/2026 15:04:07
-        ↳ Data: menu:open
-```
-
-Teks pesan/command biasa dibatasi 50 karakter; data tombol callback ditampilkan penuh. Matikan dengan `branding: false` pada `Bot`, atau pakai `logger.format: "json"` untuk log terstruktur. Output non-interaktif (pipe, Docker, CI) otomatis fallback ke teks polos tanpa animasi.
-
-## CLI
-
-Command CLI seperti `telebibz doctor`, `init`, dan `webhook` diawali banner rainbow `Tele Bibz`. Animasi startup otomatis fallback ke output statis bersih saat stdout bukan TTY.
-
-```bash
-npx telebibz init my-bot
-npx telebibz doctor
-npx telebibz build
-npx telebibz test
-```
-
-Branding terminal juga dapat dicetak dari aplikasi:
-
-```ts
-import { printTeleBibzBanner, printTerminalBranding } from "@xbibzlibrary/telebibz";
-
-printTeleBibzBanner({ subtitle: "Bot saya" });
-printTerminalBranding();
-```
-
-## Testing
-
-```bash
-npm run typecheck
-npm run test:types
-npm run lint
-npm test
-npm run build
-npm run security
-npm run release:check
-```
-
-E2E Telegram nyata memerlukan `TELEGRAM_BOT_TOKEN` dan `TELEGRAM_TEST_CHAT_ID`. Tanpa kredensial, E2E akan dilewati dan tidak dihitung sebagai lulus.
-
-## Web App dan pembayaran
-
-`validateWebAppInitData()` memverifikasi signature dan expiration Telegram Web App. `PaymentsClient` menyediakan wrapper invoice link, invoice, jawaban pre-checkout, jawaban Web App query, transaksi Stars, dan refund Stars. Gunakan `TelegramTypes` serta alias seperti `TelegramUser`, `TelegramMessage`, dan `TelegramUpdate` untuk full Telegram declaration surface yang divendor.
-
-## Permukaan API
-
-Semua yang tercantum di bawah diekspor dari entry point package kecuali disebutkan subpath-nya. Signature lengkap setiap export terdokumentasi di [docs/API.id.md](docs/API.id.md) (juga [docs/API.md](docs/API.md) dan [docs/API.zh-CN.md](docs/API.zh-CN.md)).
-
-| Area | Export |
-|---|---|
-| Bot & lifecycle | `Bot` dengan `on`, `onText`, `onRegex`, `command`, `hears`, `callback`, `action`, `catch`, `use`, `usePlugin`, `useWizard`, `handleUpdate`, `handleUpdates`, `start`/`launch`, `stop`, `restart`, `init`, `health`, `broadcast`, `getMe`, `setCommands`, `deleteCommands`, `downloadFile`; `UpdateTimeoutError` |
-| Context | `Context`, `ContextOptions`, opsi launch `contextType`; ~80 shortcut di `ctx` untuk balasan, aksi admin, manajemen chat, invite link, poll, game, pembayaran, dan forum topic |
-| Telegram API | `ApiClient` dengan `call()`, `request()`, `raw()`, `downloadFile()`, dan `methods` (seluruh generated Bot API method); `FetchTransport` dengan retry 429/5xx otomatis, flood gate global, upload multipart (Blob/byte/path/stream), dan unduhan file |
-| Error | `TelegramError` dengan taksonomi `kind` (`retryable`, `rate-limit`, `authentication`, `validation`, `network`, `server`, `unknown`) dan `retryAfter`, plus `TelegramRateLimitError`, `TelegramAuthError`, `TelegramValidationError`, `TelegramNetworkError` |
-| Router & middleware | `Router`, `compose`, 24 filter update (`message:photo`, `callback_query:data`, …), `matchMode` (`first`/`all`) |
-| Keyboard | `InlineKeyboard`, `ReplyKeyboard`, `removeKeyboard()`, `forceReply()` |
-| Storage | `MemoryStorage` (TTL, serialisasi per-key), `JsonFileStorage`, `RedisStorage`, `SqlStorage`, `MongoStorage`, beserta driver interface kecil yang menjadi dasarnya |
-| Cache & limiting | `MemoryCache`, `TokenBucketLimiter`, `Limiter`, `mapWithConcurrency()` |
-| Queue & scheduler | `TaskQueue` (prioritas, retry, backoff, delay, cancel), `Scheduler` (interval, one-shot, cron), `parseCronExpression()`, `nextCronOccurrence()` |
-| State & dialog | `Wizard`, `ConversationManager`, `ConversationFlow`, `Form` dengan `validators`, `Menu` berbasis permission, `MenuController`, `paginate()` |
-| Webhook | `createWebhookHandler()` (Request/Response Web), `webhookCallback()` untuk Express/Koa/Fastify/Node `http`, `runWithWebhookReply()`, `claimWebhookReply()` |
-| Web App & pembayaran | `parseWebAppInitData()`, `validateWebAppInitData()`, `PaymentsClient`, `TelegramTypes` (deklarasi Telegram yang dibundel) |
-| Observability | `Logger` (level, redaction, format JSON), `EventBus` dengan event map `update:*`, `bot:*`, `broadcast:*`, `redact()` |
-| Terminal | `printTeleBibzBanner()`, `printTerminalBranding()`, `buildTerminalBranding()`, `runStartupSequence()`, `startTeleBibzBanner()`, `paintRainbow()`, `printStatusLine()` |
-| Utilitas teks | `splitMessage()`, `splitCaption()`, `escapeMarkdownV2()`, `escapeHtml()`, `md`, `html`, `template()` |
-| Utilitas file | `validateUpload()`, `assertValidUpload()`, `UploadValidationError` (aturan ukuran, MIME, ekstensi) |
-| Testing (`@xbibzlibrary/telebibz/testing`) | `MockTransport` (dengan unduhan mock), `createTestBot()`, `createMockUpdate()`, `createMockCallbackUpdate()`, `createMockContext()` |
-| CLI (`telebibz …`) | `init`, `doctor`, `build`, `test`, `start`, `webhook`, `generate` |
-
-## API target dan batasan
-
-Daftar method dihasilkan dari dokumentasi Telegram Bot API saat skema diperbarui. Akses runtime tersedia untuk method resmi yang terdeteksi, sedangkan inferensi parameter/result khusus dipusatkan pada core method map. Full declaration Telegram untuk object, union, enum, dan method tersedia melalui `TelegramTypes`. Lihat [FEATURE_MATRIX.md](FEATURE_MATRIX.md) untuk status implementasi dan `docs/API.id.md` untuk referensi API lengkap.
-
-## Otomatisasi release
-
-Repository GitHub menyediakan CI dan workflow auto-publish. Setiap push ke `main` menjalankan quality gates lalu menurunkan versi berikutnya dari Conventional Commits yang didorong: commit `feat:` dan breaking change menaikkan minor selama package belum 1.0 (footer `BREAKING-CHANGE` atau subjek `type!:` menaikkan major mulai 1.0.0), sisanya menaikkan patch. Versi yang sudah dideklarasikan di `package.json` lebih tinggi dari npm diterbitkan persis apa adanya, dan workflow tidak pernah menerbitkan versi yang kurang dari atau sama dengan rilis npm terbaru. Workflow membuat commit versi, tag, menerbitkan ke npm (dengan provenance dinonaktifkan lewat `--provenance=false`), lalu membuat GitHub Release. Commit yang memuat `[skip release]` tidak memicu penerbitan. Konfigurasikan secret `NPM_TOKEN` pada GitHub Actions sebelum mengandalkan publish otomatis. Lihat [RELEASE_AUTOMATION.md](RELEASE_AUTOMATION.md) dan panduan [GitHub Packages](docs/GITHUB_PACKAGES.id.md).
-
-## Policy project dan kontribusi
-
-| Dokumen | Tujuan |
-|---|---|
-| [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) | Perilaku komunitas, penegakan, pelaporan, dan banding. |
-| [CONTRIBUTING.md](CONTRIBUTING.md) | Setup lokal, branch/commit, test, review, dan release workflow. |
-| [CONTRIBUTION_RULES.md](CONTRIBUTION_RULES.md) | Aturan API, compatibility, testing, dependency, security, dan release. |
-| [GOVERNANCE.md](GOVERNANCE.md) | Peran, pengambilan keputusan, triage, perlindungan repository, dan perubahan aturan. |
-| [SECURITY.md](SECURITY.md) | Pelaporan vulnerability privat, batas security, dan rotasi credential. |
-| [SUPPORT.md](SUPPORT.md) | Channel support, aturan laporan aman, dan ekspektasi response. |
-| [RELEASE_AUTOMATION.md](RELEASE_AUTOMATION.md) | Automation GitHub-to-npm dan setup `NPM_TOKEN`. |
-| [RELEASE_POLICY.md](RELEASE_POLICY.md) | Kontrol immutable release dan hardening. |
-| [NOTICE.md](NOTICE.md) | Atribusi declaration pihak ketiga. |
-
-## Keamanan
-
-Jangan commit token Telegram atau npm. Gunakan variabel lingkungan atau secret manager. Untuk kebijakan keamanan dan peningkatan keamanan rilis, lihat [SECURITY.md](SECURITY.md) dan [RELEASE_POLICY.md](RELEASE_POLICY.md).
-
-## Lisensi
-
-MIT. Lihat [LICENSE](LICENSE).

package/README.zh-CN.md

@@ -1,306 +0,0 @@
-# telebibz
-
-![telebibz 徽标](https://imgbs.com/uploads/telebibz-d7b30671.png)
-
-[![CI](https://github.com/XbibzOfficial777/telebibz/actions/workflows/ci.yml/badge.svg)](https://github.com/XbibzOfficial777/telebibz/actions/workflows/ci.yml)
-[![npm version](https://img.shields.io/npm/v/@xbibzlibrary/telebibz)](https://www.npmjs.com/package/@xbibzlibrary/telebibz)
-[![npm downloads](https://img.shields.io/npm/dm/@xbibzlibrary/telebibz)](https://www.npmjs.com/package/@xbibzlibrary/telebibz)
-[![Node.js](https://img.shields.io/node/v/@xbibzlibrary/telebibz)](https://www.npmjs.com/package/@xbibzlibrary/telebibz)
-
-**`@xbibzlibrary/telebibz`** 是一个面向 Node.js 和 TypeScript 的 Telegram Bot SDK 和框架。该包提供 API 客户端、轮询、路由器、中间件、上下文、键盘构造器、状态/会话、Webhook 处理、队列、调度器、缓存、插件生命周期、CLI 以及测试工具。
-
-[English](README.md) · [Bahasa Indonesia](README.id.md) · **简体中文**
-
-完整 API 参考：[English](docs/API.md) · [Indonesia](docs/API.id.md) · **中文**
-
-GitHub Packages 指南：[English](docs/GITHUB_PACKAGES.md) · [Bahasa Indonesia](docs/GITHUB_PACKAGES.id.md) · [简体中文](docs/GITHUB_PACKAGES.zh-CN.md)
-
-存储快速上手（Memory/JSON/Redis/SQL/Mongo）：[English](docs/STORAGE.md) · [Bahasa Indonesia](docs/STORAGE.id.md) · [简体中文](docs/STORAGE.zh-CN.md)
-
-入门指南：[English](docs/GETTING_STARTED.md) · [Bahasa Indonesia](docs/GETTING_STARTED.id.md) · [简体中文](docs/GETTING_STARTED.zh-CN.md)
-
-文件（上传与下载）：[English](docs/FILES.md) · [Bahasa Indonesia](docs/FILES.id.md) · [简体中文](docs/FILES.zh-CN.md)
-
-错误与限流：[English](docs/ERRORS.md) · [Bahasa Indonesia](docs/ERRORS.id.md) · [简体中文](docs/ERRORS.zh-CN.md)
-
-Webhook 部署：[English](docs/WEBHOOK.md) · [Bahasa Indonesia](docs/WEBHOOK.id.md) · [简体中文](docs/WEBHOOK.zh-CN.md)
-
-测试（用 MockTransport 离线进行）：[English](docs/TESTING.md) · [Bahasa Indonesia](docs/TESTING.id.md) · [简体中文](docs/TESTING.zh-CN.md)
-
-从 Telegraf 迁移：[English](docs/MIGRATION_TELEGRAF.md) · [Bahasa Indonesia](docs/MIGRATION_TELEGRAF.id.md) · [简体中文](docs/MIGRATION_TELEGRAF.zh-CN.md)
-
-生产实战手册（13 个配方）：[English](docs/COOKBOOK.md) · [Bahasa Indonesia](docs/COOKBOOK.id.md) · [简体中文](docs/COOKBOOK.zh-CN.md)
-
-完整文档目录：[docs/README.md](docs/README.md)
-
-社区 showcase：[SHOWCASE.md](SHOWCASE.md)
-
-![telebibz 概览](https://cdn.jsdelivr.net/npm/@xbibzlibrary/telebibz@latest/assets/telebibz-readme-preview.png)
-
-## 安装
-
-```bash
-npm install @xbibzlibrary/telebibz
-```
-
-需要 Node.js **22 或更高版本**。
-
-## 简单机器人
-
-```ts
-import { Bot } from "@xbibzlibrary/telebibz";
-
-const bot = new Bot(process.env.TELEGRAM_BOT_TOKEN!);
-
-bot.command("start", async (ctx) => { await ctx.reply("机器人已启动。"); });
-bot.onText("ping", async (ctx) => { await ctx.reply("pong"); });
-
-await bot.start();
-```
-
-`Bot.start()` 会运行长轮询。要手动管理生命周期，请使用 `init()`, `launch({ mode: "polling" })`, `health()`, `stop()`, 或 `restart()`。
-
-## 官方 starter examples
-
-repository 提供可直接运行的 minimal bot、多步骤 registration wizard 和 Node.js webhook starter。请查看 [`examples/README.md`](examples/README.md)，或设置 `TELEGRAM_BOT_TOKEN` 后运行 minimal starter：
-
-```bash
-export TELEGRAM_BOT_TOKEN="<your-bot-token>"
-npx tsx examples/minimal.ts
-```
-
-所有 examples 都会通过 `npm run test:examples` 在 CI 中进行类型检查，并且不包含真实 credential。
-
-## 路由器与中间件
-
-```ts
-bot.use(async (ctx, next) => {
-  const started = Date.now();
-  await next();
-  console.log(`processed in ${Date.now() - started}ms`);
-});
-
-bot.command("help", async (ctx) => { await ctx.reply("可以查看帮助。"); });
-bot.onRegex(/^order:(\d+)$/, async (ctx) => { await ctx.reply("订单已收到。"); });
-bot.callback("profile:*", async (ctx) => { await ctx.answerCallbackQuery("已打开。"); });
-bot.action("menu:open", async (ctx) => { await ctx.answerCallbackQuery("菜单已打开。"); });
-bot.on("message:photo", async (ctx) => { await ctx.reply("照片不错。"); });
-bot.on(["message:text", "callback_query:data"], async (ctx) => { await ctx.reply("收到。"); });
-bot.hears("ping", async (ctx) => { await ctx.reply("pong"); });
-bot.catch(async (error, ctx) => { await ctx.reply("出错了。"); });
-```
-
-路由器支持命令、文本、正则、回调模式、更新类型过滤器（`on`）、自定义谓词、嵌套路由器、每条路由的中间件，以及路由优先级。`bot.catch()` 注册错误边界：处理器失败会转发到那里，而不是拒绝整个 update。
-
-## Telegram API
-
-通过 API 客户端可以使用生成的方法调用和原始调用：
-
-```ts
-await bot.api.methods.getMe();
-await bot.api.methods.sendMessage({ chat_id: 123456789, text: "你好。" });
-await bot.api.call("sendMessage", { chat_id: 123456789, text: "你好。" });
-await bot.api.raw("futureTelegramMethod", { value: true });
-```
-
-内置传输使用 `fetch`，支持超时、重试、指数退避、JSON 载荷和多部分上传。
-
-关于每个 class、function、method、type、error、lifecycle、CLI 命令和生成的 Telegram 方法的完整 API 参考请参见 [`docs/API.zh-CN.md`](docs/API.zh-CN.md)。
-
-## 键盘
-
-```ts
-import { InlineKeyboard } from "@xbibzlibrary/telebibz";
-
-const keyboard = new InlineKeyboard()
-  .text("个人资料", "profile")
-  .url("文档", "https://core.telegram.org/bots/api")
-  .build();
-
-await ctx.reply("请选择菜单：", { reply_markup: keyboard });
-```
-
-构造器仅生成 Telegram 原生键盘的 payload。HTML/CSS 的 UI 需要单独的 Mini App 或 Web App。
-
-## 启动与终端日志
-
-Logger 输出紧凑易读的终端日志行，带彩色级别和结构化上下文。日志级别为 `silent`、`error`、`warn`、`info`、`debug` 和 `trace`；敏感值会被 redact；错误以红色打印并带完整堆栈。使用 `format: "json"` 做机器摄取，仅在明确需要消息文本或回调数据时才开启 `includeUpdateContent: true`。
-
-## Wizard 与多步会话
-
-将 `Wizard` 与 `bot.useWizard()` 配合使用，来自同一 chat/user 的后续每条文本回复都会自动路由到当前步骤。Key 由 Telegram chat 和发送者生成，无需手动指定。
-
-```ts
-import { Bot, Wizard } from "@xbibzlibrary/telebibz";
-
-const wizard = new Wizard()
-  .step({ id: "prompt-name", run: async (flow) => { flow.next(); await flow.ctx.reply("你叫什么名字？"); } })
-  .step({ id: "name", run: async (flow) => { flow.set("name", flow.ctx.message?.text?.trim()); flow.next(); await flow.ctx.reply("你多大了？"); } })
-  .step({ id: "age", run: (flow) => { const age = Number(flow.ctx.message?.text?.trim()); if (!Number.isInteger(age)) return; flow.set("age", age); flow.next(); } });
-
-const bot = new Bot(process.env.TELEGRAM_BOT_TOKEN!);
-bot.useWizard(wizard);
-bot.command("start", async (ctx) => { await wizard.run(ctx); });
-await bot.start();
-```
-
-`Wizard` 在 update 之间保持其默认的 `ConversationManager`，并在最后一步完成后立即标记会话完成。使用 `/cancel` 可取消正在进行的 wizard。
-
-## Webhook
-
-```ts
-import { Bot, createWebhookHandler } from "@xbibzlibrary/telebibz";
-
-const bot = new Bot(process.env.TELEGRAM_BOT_TOKEN!);
-const handler = createWebhookHandler(bot, {
-  secretToken: process.env.TELEGRAM_WEBHOOK_SECRET,
-});
-```
-
-`createWebhookHandler` 接受标准 Web `Request` 并返回 `Response`。处理程序会验证 secret token、body 大小、JSON 解析以及重复更新处理。
-
-## 高负载更新与广播
-
-telebibz 为 1000+ 条消息的突发场景而生，没有任何人为冷却：
-
-- **跨 chat 并行，同一 chat 内按序。** 每个 `getUpdates` 批次（以及每个 webhook 请求）都并发处理——不同 chat 的 update 不会互相排队，而同一 chat 的 update 保持到达顺序，因此会话、wizard 和 conversation 始终正确，会话写入永不丢失。并发突发只触发一次 `getMe` 初始化。如果你自己持有轮询循环，可用 `bot.handleUpdates()` 直接喂入已拉取的批次。
-- **没有主动限流。** 库永远不会延迟外发请求。当 Telegram 返回 429 时，transport 会严格按照 Telegram 指定的 `retry_after` 窗口等待（全局 "flood gate" 保护所有进行中的流量）并自动重试——因此突发流量会完整送达而不是失败。针对你自己的下游限制，`Limiter` 与 `mapWithConcurrency()` 可为任意工作负载整形速率。
-- **一次性向 1000+ 用户广播。** `bot.broadcast()` 立即尝试所有 chat，按照 Telegram 自己的 `retry_after` 重试 429，并返回完整报告。
-- **优雅停机。** `bot.stop()` 会先等待进行中的 handler 完成（受 `handlerTimeout` 约束），然后才停止 plugin manager——进行中的会话绝不会在写入途中被截断。
-
-```ts
-const report = await bot.broadcast(
-  subscriberIds,
-  (chatId) => bot.api.methods.sendMessage({ chat_id: chatId, text: "Newsletter #42" }),
-  { onProgress: (p) => console.log(`${p.delivered}/${p.total} delivered`) },
-);
-console.log(`Delivered ${report.delivered}/${report.total} in ${report.durationMs}ms`);
-```
-
-当你自己的下游（数据库、API）需要时，可以用 `new Bot({ ..., updates: { concurrency: 64 } })` 或 `broadcast(..., { concurrency: 64 })` 限制并发——默认情况下两者都完全并行。
-
-## Context 表面与 Telegraf 完全对齐
-
-Telegraf 的每一个 context 快捷方法都可用，还包含补齐 Telegraf 核心交给其插件生态的部分：
-
-- **管理与封禁** — `ctx.banChatMember`、`ctx.unbanChatMember`、`ctx.restrictChatMember`、`ctx.promoteChatMember`、`ctx.banChatSenderChat`、`ctx.unbanChatSenderChat`
-- **聊天管理** — `ctx.setChatTitle/Description/Photo`、`ctx.setChatPermissions`、`ctx.leaveChat`、`ctx.unpinAllChatMessages`、`ctx.setChatStickerSet`、`ctx.deleteChatStickerSet`
-- **信息** — `ctx.getChatAdministrators`、`ctx.getChatMemberCount`、`ctx.getChatMember`
-- **邀请链接与加群申请** — `ctx.exportChatInviteLink`、`ctx.createChatInviteLink`、`ctx.editChatInviteLink`、`ctx.revokeChatInviteLink`、`ctx.approveChatJoinRequest`、`ctx.declineChatJoinRequest`
-- **投票、游戏、支付** — `ctx.replyWithQuiz`、`ctx.stopPoll`、`ctx.editMessageLiveLocation`、`ctx.stopMessageLiveLocation`、`ctx.replyWithGame`、`ctx.setGameScore`、`ctx.getGameHighScores`、`ctx.replyWithInvoice`
-- **论坛主题** — `ctx.createForumTopic`、`ctx.closeForumTopic`、`ctx.editGeneralForumTopic` 等九个
-- **启动选项** — `handlerTimeout`（默认 90 秒，与 Telegraf 一致）以 `UpdateTimeoutError` 拒绝挂起的 update，同时 handler 继续运行；传 `0` 可禁用超时；`contextType` 接入你自己的 `Context` 子类；`start()`/`launch()` 的 `dropPendingUpdates`
-- **Webhook 应答** — 选择性开启的 `webhookReply: true` 让第一个 API 调用直接通过 webhook HTTP 响应本身应答（Telegraf 风格），懒加载的 `getMe` 永远不会占用槽位
-- **即插即用的 handler 别名** — `bot.action(...)` 与 `bot.callback(...)` 一样注册回调查询 handler，为 Telegraf 编写的 handler 可以原样迁移
-
-## 状态、队列、调度器和缓存
-
-该包提供带 TTL 和原子更新的 `MemoryStorage`、`JsonFileStorage`、`RedisStorage`、`SqlStorage`、`MongoStorage`、bot session、基于 Storage 的 conversation/form、基于 permission 的菜单、`MenuController` 分页、`MemoryCache`、令牌桶限流器、支持重试/退避/并发/延迟/取消的任务队列，以及间隔、一次性和完整五字段 cron 的调度器。Redis、SQL 和 Mongo 适配器使用小型 driver interface，因此 core package 不需要 vendor runtime dependency。
-
-## 终端体验
-
-当 bot 在交互式终端启动时（`npm start`、`node index.js`、`telebibz start`），telebibz 会播放启动序列：`Installing Dependencies......` 打字效果、带扫过高光的 glass 进度条，以及动画彩虹 ASCII 横幅 **Tele Bibz**（figlet `Speed` 字体）——彩虹持续流动直到 bot 连接成功，随后定格并显示 `✓ Connected as @<username>`。
-
-之后，每一条进入的 update 都会以易读的格式输出，错误自动以红色打印并附带完整堆栈：
-
-```text
-[ => ] Message From 123456789 John Doe 29/08/2026 15:04:05
-        ↳ Text: /start
-[ => ] Callback From 123456789 John Doe 29/08/2026 15:04:07
-        ↳ Data: menu:open
-```
-
-普通消息与命令文本截断为 50 个字符；回调按钮数据完整显示。向 `Bot` 传入 `branding: false` 可关闭启动序列，或设置 `logger.format: "json"` 获取结构化日志。非交互 stdout（管道、Docker、CI）会自动回退到无动画的纯文本输出。
-
-## CLI
-
-`telebibz doctor`、`init`、`webhook` 等 CLI command 以彩虹 `Tele Bibz` 横幅开始。当 stdout 不是 TTY 时，启动动画自动回退为干净的静态输出。
-
-```bash
-npx telebibz init my-bot
-npx telebibz doctor
-npx telebibz build
-npx telebibz test
-```
-
-也可以在应用中打印相同的 terminal branding：
-
-```ts
-import { printTeleBibzBanner, printTerminalBranding } from "@xbibzlibrary/telebibz";
-
-printTeleBibzBanner({ subtitle: "My bot" });
-printTerminalBranding();
-```
-
-## 测试
-
-```bash
-npm run typecheck
-npm run test:types
-npm run lint
-npm test
-npm run build
-npm run security
-npm run release:check
-```
-
-真实的 Telegram E2E 需要 `TELEGRAM_BOT_TOKEN` 和 `TELEGRAM_TEST_CHAT_ID`。没有凭证时，E2E 将被跳过且不计为通过。
-
-## Web App 和支付
-
-`validateWebAppInitData()` 会验证 Telegram Web App 的 signature 和 expiration。`PaymentsClient` 提供 invoice link、invoice、pre-checkout answer、Web App query answer、Stars transactions 和 Stars refunds 的 wrapper。使用 `TelegramTypes` 以及 `TelegramUser`、`TelegramMessage`、`TelegramUpdate` 等 alias 来访问完整的 vendored Telegram declaration surface。
-
-## API 表面
-
-除注明 subpath 外，以下所有内容都从 package 入口导出。每个导出的完整签名见 [docs/API.zh-CN.md](docs/API.zh-CN.md)（另有 [docs/API.md](docs/API.md) 与 [docs/API.id.md](docs/API.id.md)）。
-
-| 领域 | 导出 |
-|---|---|
-| Bot 与生命周期 | `Bot` 的 `on`、`onText`、`onRegex`、`command`、`hears`、`callback`、`action`、`catch`、`use`、`usePlugin`、`useWizard`、`handleUpdate`、`handleUpdates`、`start`/`launch`、`stop`、`restart`、`init`、`health`、`broadcast`、`getMe`、`setCommands`、`deleteCommands`、`downloadFile`；`UpdateTimeoutError` |
-| Context | `Context`、`ContextOptions`、launch 选项 `contextType`；`ctx` 上约 80 个快捷方法，覆盖回复、管理员操作、聊天管理、邀请链接、投票、游戏、支付与论坛主题 |
-| Telegram API | `ApiClient` 的 `call()`、`request()`、`raw()`、`downloadFile()` 与 `methods`（全部生成的 Bot API 方法）；`FetchTransport` 自带 429/5xx 自动重试、全局 flood gate、multipart 上传（Blob/字节/路径/流）以及文件下载 |
-| 错误 | `TelegramError` 带 `kind` 分类（`retryable`、`rate-limit`、`authentication`、`validation`、`network`、`server`、`unknown`）与 `retryAfter`，另有 `TelegramRateLimitError`、`TelegramAuthError`、`TelegramValidationError`、`TelegramNetworkError` |
-| 路由器与中间件 | `Router`、`compose`、24 个 update 过滤器（`message:photo`、`callback_query:data` 等）、`matchMode`（`first`/`all`） |
-| 键盘 | `InlineKeyboard`、`ReplyKeyboard`、`removeKeyboard()`、`forceReply()` |
-| 存储 | `MemoryStorage`（TTL、按 key 串行化）、`JsonFileStorage`、`RedisStorage`、`SqlStorage`、`MongoStorage`，以及它们所基于的小型 driver interface |
-| 缓存与限流 | `MemoryCache`、`TokenBucketLimiter`、`Limiter`、`mapWithConcurrency()` |
-| 队列与调度器 | `TaskQueue`（优先级、重试、退避、延迟、取消）、`Scheduler`（间隔、一次性、cron）、`parseCronExpression()`、`nextCronOccurrence()` |
-| 状态与对话 | `Wizard`、`ConversationManager`、`ConversationFlow`、带 `validators` 的 `Form`、基于 permission 的 `Menu`、`MenuController`、`paginate()` |
-| Webhook | `createWebhookHandler()`（Web `Request`/`Response`）、面向 Express/Koa/Fastify/Node `http` 的 `webhookCallback()`、`runWithWebhookReply()`、`claimWebhookReply()` |
-| Web App 与支付 | `parseWebAppInitData()`、`validateWebAppInitData()`、`PaymentsClient`、`TelegramTypes`（内置的 Telegram 声明） |
-| 可观测性 | `Logger`（级别、redaction、JSON 格式）、带 `update:*`、`bot:*`、`broadcast:*` 事件映射的 `EventBus`、`redact()` |
-| 终端 | `printTeleBibzBanner()`、`printTerminalBranding()`、`buildTerminalBranding()`、`runStartupSequence()`、`startTeleBibzBanner()`、`paintRainbow()`、`printStatusLine()` |
-| 文本工具 | `splitMessage()`、`splitCaption()`、`escapeMarkdownV2()`、`escapeHtml()`、`md`、`html`、`template()` |
-| 文件工具 | `validateUpload()`、`assertValidUpload()`、`UploadValidationError`（大小、MIME、扩展名规则） |
-| 测试（`@xbibzlibrary/telebibz/testing`） | `MockTransport`（含 mock 下载）、`createTestBot()`、`createMockUpdate()`、`createMockCallbackUpdate()`、`createMockContext()` |
-| CLI（`telebibz …`） | `init`、`doctor`、`build`、`test`、`start`、`webhook`、`generate` |
-
-## API 目标与限制
-
-方法列表会在 schema 更新时根据 Telegram Bot API 文档生成。检测到的官方方法都可以运行时访问，而专门的参数/结果推断主要集中在 core method map。完整的 Telegram object、union、enum 和 method declaration 可通过 `TelegramTypes` 使用。有关实现状态请参见 [FEATURE_MATRIX.md](FEATURE_MATRIX.md)，完整 API 请参见 `docs/API.zh-CN.md`。
-
-## 发布自动化
-
-GitHub repository 提供 CI 和自动发布 workflow。每次推送到 `main` 都会运行 quality gates，并从推送的 Conventional Commits 推导下一个版本：`feat:` 提交和破坏性变更在 package 处于 1.0 之前提升 minor（`BREAKING-CHANGE` footer 或 `type!:` 主题自 1.0.0 起提升 major），其余提升 patch。`package.json` 中已声明且高于 npm 的版本会按声明原样发布，workflow 绝不会发布低于或等于 npm 最新版的版本。workflow 会创建版本 commit 和 tag，发布到 npm（通过 `--provenance=false` 禁用 provenance），并创建 GitHub Release。包含 `[skip release]` 的提交不会触发发布。依赖自动发布前，请在 GitHub Actions 中配置 `NPM_TOKEN` secret。请参阅 [RELEASE_AUTOMATION.md](RELEASE_AUTOMATION.md) 和 [GitHub Packages 指南](docs/GITHUB_PACKAGES.zh-CN.md)。
-
-## 项目 policy 和贡献
-
-| 文档 | 用途 |
-|---|---|
-| [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) | 社区行为、执行、报告和申诉。 |
-| [CONTRIBUTING.md](CONTRIBUTING.md) | 本地 setup、branch/commit、测试、review 和 release workflow。 |
-| [CONTRIBUTION_RULES.md](CONTRIBUTION_RULES.md) | API、兼容性、测试、依赖、安全和 release 规则。 |
-| [GOVERNANCE.md](GOVERNANCE.md) | 角色、决策、triage、repository protection 和规则修改。 |
-| [SECURITY.md](SECURITY.md) | 私密漏洞报告、security boundary 和 credential rotation。 |
-| [SUPPORT.md](SUPPORT.md) | Support channel、安全报告规则和 response 预期。 |
-| [RELEASE_AUTOMATION.md](RELEASE_AUTOMATION.md) | GitHub-to-npm automation 和 `NPM_TOKEN` setup。 |
-| [RELEASE_POLICY.md](RELEASE_POLICY.md) | Immutable release 和 hardening 控制。 |
-| [NOTICE.md](NOTICE.md) | 第三方 declaration attribution。 |
-
-## 安全
-
-不要将 Telegram token 或 npm 凭证提交到版本控制。使用环境变量或机密管理器。有关安全策略和发布加固，请参见 [SECURITY.md](SECURITY.md) 和 [RELEASE_POLICY.md](RELEASE_POLICY.md)。
-
-## 许可证
-
-MIT。参见 [LICENSE](LICENSE)。