@xbibzlibrary/telebibz 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## Unreleased
+
+### Fixed
+
+- Callback-query contexts now resolve `message` and `chat` from `callback_query.message`, so `ctx.reply()`, `ctx.edit()`, and `ctx.delete()` work for button callbacks.
+- Router matching is first-match by default; explicit `matchMode: "all"` preserves deliberate fan-out without accidental double replies.
+- Polling isolates handler failures per update, continues the remainder of a batch, emits `update:error`, and uses abortable reconnect backoff.
+- Regex matchers reset `lastIndex` before reuse.
+
+### Added
+
+- JSON-file, Redis, SQL-driver, Mongo-driver, and persistent approval storage adapters.
+- Storage-backed conversations, full five-field cron parsing, scheduler error hooks, permission-aware menus, `MenuController`, Web App init-data validation, PaymentsClient, and vendored Telegram declarations.
+- Callback-update test fixtures and expanded failure-path/regression coverage.
+
 ## 0.1.2 — 2026-08-19
 
 ### Changed
@@ -32,4 +47,4 @@
 
 ### Known limitations
 
-The full object/type schema generator, conversations/scenes/wizard/forms, distributed adapters, Mini App UI SDK, high-level payments subsystem, and authenticated Telegram E2E verification are not complete in this release. See `FEATURE_MATRIX.md`.
+The generated method list has runtime coverage for official method names, while specialized request/result inference remains concentrated on the core method map; full Telegram declarations are available through `TelegramTypes`. Scene orchestration and a full Mini App UI layer remain application-owned. Redis, SQL, and Mongo adapters require the application to provide the corresponding vendor driver interface. See `FEATURE_MATRIX.md`.

package/README.id.md

@@ -0,0 +1,158 @@
+# telebibz
+
+![telebibz logo](https://cdn.jsdelivr.net/npm/@xbibzlibrary/telebibz@0.1.2/assets/telebibz-logo.png)
+
+**`@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)
+
+![overview telebibz](assets/telebibz-readme-preview.png)
+
+## Instalasi
+
+```bash
+npm install @xbibzlibrary/telebibz
+```
+
+Node.js **20 atau lebih baru** diperlukan.
+
+## Bot sederhana
+
+```ts
+import { Bot } from "@xbibzlibrary/telebibz";
+
+const bot = new Bot(process.env.TELEGRAM_BOT_TOKEN!);
+
+bot.command("start", (ctx) => ctx.reply("Bot aktif."));
+bot.onText("ping", (ctx) => ctx.reply("pong"));
+
+await bot.start();
+```
+
+`Bot.start()` menjalankan long polling. Untuk siklus hidup manual, gunakan `init()`, `launch({ mode: "polling" })`, `health()`, `stop()`, atau `restart()`.
+
+## 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", (ctx) => ctx.reply("Bantuan tersedia."));
+bot.onRegex(/^order:(\\d+)$/, (ctx) => ctx.reply("Order diterima."));
+bot.callback("profile:", (ctx) => ctx.answerCallbackQuery("Dibuka."));
+```
+
+Router mendukung command, text, regex, pola callback, predikat kustom, router bersarang, middleware per rute, dan prioritas rute.
+
+## 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.
+
+## Persetujuan pemilik
+
+Gerbang persetujuan menahan pembaruan biasa sampai pemilik menyetujui bot melalui tombol **Izinkan** atau **Tidak Diizinkan**.
+
+```ts
+const bot = new Bot({
+  token: process.env.TELEGRAM_BOT_TOKEN!,
+  approval: {
+    ownerChatId: Number(process.env.TELEBIBZ_OWNER_CHAT_ID),
+    ownerUserId: Number(process.env.TELEBIBZ_OWNER_USER_ID),
+    ownerLabel: "Dev Gantenggg",
+    requireApproval: true,
+  },
+});
+```
+
+Library mengirim notifikasi ke `ownerChatId`, sedangkan hanya `ownerUserId` yang dapat mengambil keputusan. Callback menggunakan nonce acak. Untuk deployment multi-instance, gunakan `ApprovalStore` persisten melalui database atau Redis; default-nya adalah memory store.
+
+## 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.
+
+## State, queue, scheduler, dan cache
+
+Paket menyediakan `MemoryStorage` dengan TTL dan pembaruan atomik, `JsonFileStorage`, `RedisStorage`, `SqlStorage`, `MongoStorage`, persistent approval 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.
+
+## CLI
+
+```bash
+npx telebibz init my-bot
+npx telebibz doctor
+npx telebibz build
+npx telebibz test
+```
+
+## 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.
+
+## 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 [APPROVAL_FEATURE.md](APPROVAL_FEATURE.md) untuk detail persetujuan.
+
+## Otomatisasi release
+
+Repository GitHub menyediakan CI dan workflow auto-publish. Setiap push ke `main` menjalankan quality gates, memilih patch version yang belum dipakai, membuat commit dan tag, menerbitkan package ke npm, lalu membuat GitHub Release. Karena source repository bersifat private, workflow menggunakan `--provenance=false`, sesuai batasan npm untuk source private. Konfigurasikan secret `NPM_TOKEN` pada GitHub Actions sebelum mengandalkan publish otomatis. Lihat [RELEASE_AUTOMATION.md](RELEASE_AUTOMATION.md).
+
+## 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.md

@@ -2,32 +2,42 @@
 
 ![telebibz logo](https://cdn.jsdelivr.net/npm/@xbibzlibrary/telebibz@0.1.2/assets/telebibz-logo.png)
 
-**`@xbibzlibrary/telebibz`** adalah SDK dan framework Telegram Bot untuk Node.js dan TypeScript. Package ini menyediakan API client, polling, router, middleware, context, keyboard builder, state/session, webhook handler, queue, scheduler, cache, plugin lifecycle, CLI, dan testing utilities.
+[![CI](https://github.com/XbibzOfficial777/telebibz/actions/workflows/ci.yml/badge.svg)](https://github.com/XbibzOfficial777/telebibz/actions/workflows/ci.yml)
 
-## Instalasi
+**`@xbibzlibrary/telebibz`** is a full-scale Telegram Bot SDK and framework for Node.js and TypeScript. It provides a typed API client, polling, routing, middleware, context helpers, keyboard builders, state/session primitives, webhooks, queues, scheduling, caching, plugin lifecycle, approval gates, CLI tooling, and testing utilities.
+
+## Documentation languages
+
+**English (default)** · [Bahasa Indonesia](README.id.md) · [简体中文](README.zh-CN.md)
+
+Complete API references: [English](docs/API.md) · [Indonesia](docs/API.id.md) · [中文](docs/API.zh-CN.md)
+
+![telebibz overview](assets/telebibz-readme-preview.png)
+
+## Installation
 
 ```bash
 npm install @xbibzlibrary/telebibz
 ```
 
-Node.js **20 atau lebih baru** diperlukan.
+Node.js **20 or newer** is required.
 
-## Bot sederhana
+## Minimal bot
 
 ```ts
 import { Bot } from "@xbibzlibrary/telebibz";
 
 const bot = new Bot(process.env.TELEGRAM_BOT_TOKEN!);
 
-bot.command("start", (ctx) => ctx.reply("Bot aktif."));
+bot.command("start", (ctx) => ctx.reply("Bot is active."));
 bot.onText("ping", (ctx) => ctx.reply("pong"));
 
 await bot.start();
 ```
 
-`Bot.start()` menjalankan long polling. Untuk lifecycle manual, gunakan `init()`, `launch({ mode: "polling" })`, `health()`, `stop()`, atau `restart()`.
+`Bot.start()` runs long polling. For manual lifecycle control, use `init()`, `launch({ mode: "polling" })`, `health()`, `stop()`, or `restart()`.
 
-## Router dan middleware
+## Router and middleware
 
 ```ts
 bot.use(async (ctx, next) => {
@@ -36,44 +46,44 @@ bot.use(async (ctx, next) => {
   console.log(`processed in ${Date.now() - started}ms`);
 });
 
-bot.command("help", (ctx) => ctx.reply("Bantuan tersedia."));
-bot.onRegex(/^order:(\\d+)$/, (ctx) => ctx.reply("Order diterima."));
-bot.callback("profile:", (ctx) => ctx.answerCallbackQuery("Dibuka."));
+bot.command("help", (ctx) => ctx.reply("Help is available."));
+bot.onRegex(/^order:(\\d+)$/, (ctx) => ctx.reply("Order received."));
+bot.callback("profile:", (ctx) => ctx.answerCallbackQuery("Opened."));
 ```
 
-Router mendukung command, text, regex, callback pattern, custom predicate, nested router, middleware per route, dan prioritas route.
+The router supports commands, exact text, regular expressions, callback patterns, custom predicates, nested routers, per-route middleware, and route priority.
 
 ## Telegram API
 
-Generated method access dan raw access tersedia melalui API client:
+Generated method access and raw access are available through the 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.methods.sendMessage({ chat_id: 123456789, text: "Hello." });
+await bot.api.call("sendMessage", { chat_id: 123456789, text: "Hello." });
 await bot.api.raw("futureTelegramMethod", { value: true });
 ```
 
-Transport bawaan menggunakan `fetch`, timeout, retry, exponential backoff, JSON payload, dan multipart upload.
+The built-in transport uses `fetch`, timeouts, retries, exponential backoff, JSON payloads, and multipart upload.
 
-## Keyboard
+## Keyboard builders
 
 ```ts
 import { InlineKeyboard } from "@xbibzlibrary/telebibz";
 
 const keyboard = new InlineKeyboard()
-  .text("Profil", "profile")
-  .url("Dokumentasi", "https://core.telegram.org/bots/api")
+  .text("Profile", "profile")
+  .url("Documentation", "https://core.telegram.org/bots/api")
   .build();
 
-await ctx.reply("Pilih menu:", { reply_markup: keyboard });
+await ctx.reply("Choose an option:", { reply_markup: keyboard });
 ```
 
-Builder hanya menghasilkan payload keyboard native Telegram. UI HTML/CSS memerlukan Mini App atau Web App terpisah.
+Builders produce native Telegram keyboard payloads. HTML/CSS interfaces require a separate Mini App or Web App.
 
-## Owner approval
+## Owner approval gate
 
-Approval gate menahan update biasa sampai owner menyetujui bot melalui tombol **Izinkan** atau **Tidak Diizinkan**.
+The approval gate pauses regular updates until the owner approves or denies a new bot through inline buttons.
 
 ```ts
 const bot = new Bot({
@@ -87,7 +97,7 @@ const bot = new Bot({
 });
 ```
 
-Library mengirim notifikasi ke `ownerChatId`, sedangkan hanya `ownerUserId` yang dapat mengambil keputusan. Callback menggunakan nonce acak. Untuk deployment multi-instance, gunakan `ApprovalStore` persisten melalui database atau Redis; default-nya adalah memory store.
+The library sends the notification to `ownerChatId`, while only `ownerUserId` can decide. Callback data uses a random nonce. For multi-instance deployments, provide a persistent `ApprovalStore`; the default store is in memory.
 
 ## Webhook
 
@@ -100,11 +110,11 @@ const handler = createWebhookHandler(bot, {
 });
 ```
 
-`createWebhookHandler` menerima Web standard `Request` dan menghasilkan `Response`. Secret token, ukuran body, parsing JSON, dan duplicate update handling diverifikasi oleh handler.
+`createWebhookHandler` accepts a standard Web `Request` and returns a `Response`. It verifies the optional secret token, body size, JSON payload, and update shape before calling `bot.handleUpdate()`.
 
-## State, queue, scheduler, dan cache
+## State, queue, scheduler, and cache
 
-Package menyediakan `MemoryStorage` dengan TTL dan atomic update, session pada context, conversation/form primitives, menu/pagination, `MemoryCache`, token-bucket limiter, task queue dengan retry/backoff/concurrency/delay/cancel, serta scheduler interval, one-shot, dan simple cron. Adapter Redis, SQL, MongoDB, dan queue vendor harus disediakan oleh aplikasi atau package optional.
+The package provides `MemoryStorage` with TTL and serialized per-key updates, `JsonFileStorage`, `RedisStorage`, `SqlStorage`, `MongoStorage`, persistent approval storage, bot sessions, storage-backed conversations and forms, permission-aware menus, `MenuController` pagination, `MemoryCache`, a token-bucket limiter, a task queue with retry/backoff/concurrency/delay/cancel, and schedulers for intervals, one-shot tasks, and full five-field cron expressions. Redis, SQL, and Mongo adapters use small driver interfaces so the core package remains free of vendor runtime dependencies.
 
 ## CLI
 
@@ -127,16 +137,26 @@ npm run security
 npm run release:check
 ```
 
-Real Telegram E2E memerlukan `TELEGRAM_BOT_TOKEN` dan `TELEGRAM_TEST_CHAT_ID`. Tanpa credentials, E2E akan dilewati dan tidak dihitung sebagai lulus.
+Real Telegram E2E tests require `TELEGRAM_BOT_TOKEN` and `TELEGRAM_TEST_CHAT_ID`. Without credentials, E2E tests are skipped and are not counted as passing.
+
+## Web Apps and payments
+
+`validateWebAppInitData()` verifies Telegram Web App signatures and expiration. `PaymentsClient` provides wrappers for invoice links, invoices, pre-checkout answers, Web App query answers, Stars transactions, and Stars refunds. Use `TelegramTypes` and aliases such as `TelegramUser`, `TelegramMessage`, and `TelegramUpdate` for the vendored full Telegram declaration surface.
+
+## API targets and limitations
+
+The generated method list is derived from the Telegram Bot API schema when it is updated. Runtime access is available for detected official methods, while specialized request/result inference remains concentrated on the core method map. The complete vendored Telegram object, union, enum, and method declarations are available through `TelegramTypes`. See [FEATURE_MATRIX.md](FEATURE_MATRIX.md) for implementation status and [APPROVAL_FEATURE.md](APPROVAL_FEATURE.md) for approval details.
+
+For every exported class, function, method, type, error, lifecycle hook, CLI command, and generated Telegram method, see the [complete English API reference](docs/API.md).
 
-## API target dan batasan
+## Release automation
 
-Method list dihasilkan dari dokumentasi Telegram Bot API saat schema diperbarui. Method access tersedia untuk method resmi yang terdeteksi, tetapi tidak semua object, union, enum, dan optional adapter memiliki typing tingkat lanjut penuh. Lihat [FEATURE_MATRIX.md](FEATURE_MATRIX.md) untuk status implementasi dan [APPROVAL_FEATURE.md](APPROVAL_FEATURE.md) untuk detail approval.
+The GitHub repository includes CI and an auto-publish workflow. A push to `main` runs the quality gates, chooses the next unused patch version, commits the version, creates a tag, publishes to npm, and creates a GitHub Release. Because the source repository is private, the workflow uses `--provenance=false`, which npm requires for private source repositories. Configure the `NPM_TOKEN` GitHub Actions secret before relying on automatic publication. See [RELEASE_AUTOMATION.md](RELEASE_AUTOMATION.md).
 
-## Keamanan
+## Security
 
-Jangan commit token Telegram atau npm. Gunakan environment variable atau secret manager. Untuk kebijakan keamanan dan release hardening, lihat [SECURITY.md](SECURITY.md) dan [RELEASE_POLICY.md](RELEASE_POLICY.md).
+Never commit Telegram tokens or npm credentials. Use environment variables or a secret manager. See [SECURITY.md](SECURITY.md) and [RELEASE_POLICY.md](RELEASE_POLICY.md) for security and release hardening policies.
 
-## Lisensi
+## License
 
-MIT. Lihat [LICENSE](LICENSE).
+MIT. See [LICENSE](LICENSE).

package/README.zh-CN.md

@@ -0,0 +1,158 @@
+# telebibz
+
+![telebibz 徽标](https://cdn.jsdelivr.net/npm/@xbibzlibrary/telebibz@0.1.2/assets/telebibz-logo.png)
+
+**`@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) · **中文**
+
+![telebibz 概览](assets/telebibz-readme-preview.png)
+
+## 安装
+
+```bash
+npm install @xbibzlibrary/telebibz
+```
+
+需要 Node.js **20 或更高版本**。
+
+## 简单机器人
+
+```ts
+import { Bot } from "@xbibzlibrary/telebibz";
+
+const bot = new Bot(process.env.TELEGRAM_BOT_TOKEN!);
+
+bot.command("start", (ctx) => ctx.reply("Bot aktif."));
+bot.onText("ping", (ctx) => ctx.reply("pong"));
+
+await bot.start();
+```
+
+`Bot.start()` 会运行长轮询。要手动管理生命周期，请使用 `init()`, `launch({ mode: "polling" })`, `health()`, `stop()`, 或 `restart()`。
+
+## 路由器与中间件
+
+```ts
+bot.use(async (ctx, next) => {
+  const started = Date.now();
+  await next();
+  console.log(`processed in ${Date.now() - started}ms`);
+});
+
+bot.command("help", (ctx) => ctx.reply("Bantuan tersedia."));
+bot.onRegex(/^order:(\\d+)$/, (ctx) => ctx.reply("Order diterima."));
+bot.callback("profile:", (ctx) => ctx.answerCallbackQuery("Dibuka."));
+```
+
+路由器支持命令、文本、正则、回调模式、自定义谓词、嵌套路由器、每条路由的中间件，以及路由优先级。
+
+## Telegram API
+
+通过 API 客户端可以使用生成的方法调用和原始调用：
+
+```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 });
+```
+
+内置传输使用 `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("Profil", "profile")
+  .url("Dokumentasi", "https://core.telegram.org/bots/api")
+  .build();
+
+await ctx.reply("Pilih menu:", { reply_markup: keyboard });
+```
+
+构造器仅生成 Telegram 原生键盘的 payload。HTML/CSS 的 UI 需要单独的 Mini App 或 Web App。
+
+## 所有者审批
+
+审批门将在所有者通过 **允许** 或 **不允许** 按钮批准机器人之前拦截普通更新。
+
+```ts
+const bot = new Bot({
+  token: process.env.TELEGRAM_BOT_TOKEN!,
+  approval: {
+    ownerChatId: Number(process.env.TELEBIBZ_OWNER_CHAT_ID),
+    ownerUserId: Number(process.env.TELEBIBZ_OWNER_USER_ID),
+    ownerLabel: "Dev Gantenggg",
+    requireApproval: true,
+  },
+});
+```
+
+库会向 `ownerChatId` 发送通知，但只有 `ownerUserId` 可以做出决策。回调使用随机 nonce。对于多实例部署，请通过数据库或 Redis 使用持久化的 `ApprovalStore`；默认是内存存储。
+
+## 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 解析以及重复更新处理。
+
+## 状态、队列、调度器和缓存
+
+该包提供带 TTL 和原子更新的 `MemoryStorage`、`JsonFileStorage`、`RedisStorage`、`SqlStorage`、`MongoStorage`、持久化 approval storage、bot session、基于 Storage 的 conversation/form、基于 permission 的菜单、`MenuController` 分页、`MemoryCache`、令牌桶限流器、支持重试/退避/并发/延迟/取消的任务队列，以及间隔、一次性和完整五字段 cron 的调度器。Redis、SQL 和 Mongo 适配器使用小型 driver interface，因此 core package 不需要 vendor runtime dependency。
+
+## CLI
+
+```bash
+npx telebibz init my-bot
+npx telebibz doctor
+npx telebibz build
+npx telebibz test
+```
+
+## 测试
+
+```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 目标与限制
+
+方法列表会在 schema 更新时根据 Telegram Bot API 文档生成。检测到的官方方法都可以运行时访问，而专门的参数/结果推断主要集中在 core method map。完整的 Telegram object、union、enum 和 method declaration 可通过 `TelegramTypes` 使用。有关实现状态请参见 [FEATURE_MATRIX.md](FEATURE_MATRIX.md)，有关审批的详细信息请参见 [APPROVAL_FEATURE.md](APPROVAL_FEATURE.md)。
+
+## 发布自动化
+
+GitHub repository 提供 CI 和自动发布 workflow。每次推送到 `main` 都会运行 quality gates，选择尚未使用的 patch version，创建 commit 和 tag，发布 npm package，然后创建 GitHub Release。由于 source repository 是 private，workflow 使用 `--provenance=false`，符合 npm 对 private source 的限制。依赖自动发布前，请在 GitHub Actions 中配置 `NPM_TOKEN` secret。请参阅 [RELEASE_AUTOMATION.md](RELEASE_AUTOMATION.md)。
+
+## 安全
+
+不要将 Telegram token 或 npm 凭证提交到版本控制。使用环境变量或机密管理器。有关安全策略和发布加固，请参见 [SECURITY.md](SECURITY.md) 和 [RELEASE_POLICY.md](RELEASE_POLICY.md)。
+
+## 许可证
+
+MIT。参见 [LICENSE](LICENSE)。

package/RELEASE_AUTOMATION.md

@@ -0,0 +1,66 @@
+# GitHub-to-npm Release Automation
+
+Repository ini menggunakan GitHub Actions untuk menjaga source GitHub dan package npm tetap sinkron melalui satu jalur release yang tervalidasi. Repository source tetap private; karena itu workflow menggunakan npm publish tanpa provenance, sesuai batasan registry npm untuk source private.
+
+## Alur otomatis
+
+Setiap push ke branch `main` menjalankan workflow `.github/workflows/auto-publish.yml`, kecuali commit tersebut memuat marker `[skip release]`.
+
+| Tahap | Perilaku |
+|---|---|
+| Checkout | Mengambil seluruh history agar tag dapat dibuat dengan benar. |
+| Install | Menjalankan `npm ci --ignore-scripts`. |
+| Version | Membaca versi dari `package.json`, membaca versi latest npm, lalu memilih patch version berikutnya yang lebih tinggi dari keduanya. |
+| Verification | Menjalankan typecheck, type-level tests, lint, runtime tests, build ESM/CommonJS, security audit, dan release check. |
+| Immutable guard | Menolak publish jika versi target sudah ada di npm. |
+| Git sync | Commit otomatis `chore(release): vX.Y.Z [skip release]`, membuat annotated tag `vX.Y.Z`, lalu push commit dan tag ke GitHub. |
+| npm publish | Menerbitkan package public menggunakan `NPM_TOKEN`; provenance dinonaktifkan karena npm menolak provenance dari source repository private. |
+| GitHub Release | Membuat GitHub Release dengan generated notes. |
+
+Push commit version otomatis tidak memicu release kedua karena mengandung `[skip release]`. Workflow menggunakan concurrency sehingga release berjalan satu per satu.
+
+## Secret yang wajib tersedia
+
+Buka repository GitHub, kemudian masuk ke **Settings → Secrets and variables → Actions** dan tambahkan repository secret:
+
+```text
+NPM_TOKEN=${NPM_TOKEN}
+```
+
+Jika memakai GitHub Environment bernama `npm-release`, secret dapat disimpan sebagai environment secret dan environment tersebut dapat diberi required reviewers untuk approval manual sebelum publish.
+
+Jangan menyimpan token di repository, `.npmrc`, source code, issue, commit, atau workflow. Token npm yang pernah ditempelkan di chat harus dicabut dan diganti dengan granular token baru.
+
+## Aturan penggunaan
+
+Perubahan source biasa dapat dipush ke `main`; workflow akan menghasilkan patch release baru setelah seluruh quality gates lulus. Karena versi npm immutable, workflow tidak pernah menimpa versi yang telah ada.
+
+Untuk perubahan besar, ubah `package.json` ke major/minor version yang diinginkan sebelum push. Workflow tetap memastikan hasil akhir lebih tinggi daripada versi npm yang sudah terbit, lalu menaikkan patch dari versi tertinggi tersebut.
+
+Untuk perubahan dokumentasi atau perubahan internal yang tidak boleh menerbitkan npm, gunakan commit message yang memuat marker berikut:
+
+```text
+docs: update API reference [skip release]
+```
+
+Untuk memicu workflow secara manual, gunakan **Actions → Auto publish to npm → Run workflow**. Manual trigger tetap menjalankan versioning dan semua gate yang sama.
+
+## Verifikasi lokal
+
+Sebelum push, jalankan:
+
+```bash
+npm run typecheck
+npm run test:types
+npm run lint
+npm test
+npm run build
+npm run security
+npm run release:check
+```
+
+Setelah workflow selesai, verifikasi:
+
+```bash
+npm view @xbibzlibrary/telebibz version dist.integrity dist.tarball
+```

package/RELEASE_POLICY.md

@@ -6,9 +6,9 @@ The published artifact is scoped as `@xbibzlibrary/telebibz`. npm package versio
 
 ## Hardening controls
 
-Every release must pass strict TypeScript typechecking, type-level tests, lint, runtime tests, build for ESM and CommonJS, dependency audit, and `release:check`. The release checker rejects an incorrect scope, private package status, missing public publish configuration, missing provenance, install lifecycle scripts, credential patterns in tracked release content, and incomplete tarball contents.
+Every release must pass strict TypeScript typechecking, type-level tests, lint, runtime tests, build for ESM and CommonJS, dependency audit, and `release:check`. The release checker rejects an incorrect scope, private package status, missing public publish configuration, install lifecycle scripts, credential patterns in tracked release content, and incomplete tarball contents. npm provenance is required when the source repository is public; npm rejects provenance for private source repositories, so the current private-repository workflow explicitly uses `--provenance=false`.
 
-The package uses npm provenance configuration and a protected GitHub Actions release workflow. The publish token must be stored only as a repository secret or temporary `NPM_TOKEN` environment variable with the smallest possible scope. Tokens must never be committed, placed in `.npmrc` inside the repository, or included in archives.
+The package uses a protected GitHub Actions release workflow. The publish token must be stored only as a repository secret or temporary `NPM_TOKEN` environment variable with the smallest possible scope. Tokens must never be committed, placed in `.npmrc` inside the repository, or included in archives.
 
 ## Release verification