@xbibzlibrary/telebibz 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # 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.
+- Code of Conduct, Contributing Guide, Contribution Rules, Governance, Support Policy, expanded Security Policy, third-party Notice, CODEOWNERS, Dependabot configuration, and complete GitHub issue/PR templates.
+
 ## 0.1.2 — 2026-08-19
 
 ### Changed
@@ -32,4 +48,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/CODE_OF_CONDUCT.md

@@ -0,0 +1,37 @@
+# Code of Conduct
+
+## Our pledge
+
+We are committed to making participation in the telebibz community welcoming, respectful, technically rigorous, and safe for everyone. Contributors, maintainers, reviewers, users, and other participants are expected to act in good faith and to prioritize constructive collaboration.
+
+## Expected behavior
+
+Participants should communicate clearly and respectfully, assume good intent while discussing technical disagreements, provide actionable feedback, document relevant context, respect privacy and confidentiality, and accept that maintainers may make decisions based on project scope, security, compatibility, and release risk.
+
+When reporting a defect or security issue, include reproducible technical information without publishing secrets, personal data, or exploit details that could put users at risk. When reviewing code, focus on the implementation and its consequences rather than the person who wrote it.
+
+## Unacceptable behavior
+
+Harassment, discrimination, threats, intimidation, personal attacks, doxxing, deliberate disruption, sexualized conduct in project spaces, impersonation, publishing private information without consent, spam, and knowingly submitting malicious or deceptive changes are not acceptable. Attempts to bypass project security controls, expose credentials, poison dependencies, or manipulate release automation are treated as serious violations.
+
+## Scope
+
+This Code of Conduct applies to repository issues, pull requests, discussions, reviews, commits, releases, documentation, official project channels, and any interaction where a participant is representing telebibz or its maintainers.
+
+## Enforcement
+
+Maintainers may remove or edit content, close discussions, restrict participation, reject contributions, revoke project permissions, or take other proportionate action. Serious or repeated violations may result in a permanent ban from project spaces. Enforcement decisions consider the severity, intent, impact, recurrence, and available evidence.
+
+## Reporting
+
+Report conduct concerns privately to the maintainers through the repository's private security/contact channel. Do not open a public issue for sensitive reports. Include links, dates, relevant usernames, and a concise description of what occurred. Do not include credentials or unnecessary personal information.
+
+Security vulnerabilities must be reported according to [SECURITY.md](SECURITY.md), not through a public issue.
+
+## Appeals
+
+A participant may request a review of an enforcement decision by providing relevant context privately. Appeals are reviewed by a maintainer who was not the sole decision-maker for the original action where practical. Retaliation against a good-faith report or appeal is prohibited.
+
+## Attribution
+
+This policy is informed by the [Contributor Covenant](https://www.contributor-covenant.org/version/2/1/code_of_conduct/), adapted for the technical and security needs of this project.

package/CONTRIBUTING.md

@@ -0,0 +1,54 @@
+# Contributing to telebibz
+
+Thank you for helping improve telebibz. Contributions are welcome when they are focused, reproducible, tested, documented, and compatible with the project's security and release policies.
+
+## Before you start
+
+Read [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md), [CONTRIBUTION_RULES.md](CONTRIBUTION_RULES.md), [SECURITY.md](SECURITY.md), and [RELEASE_POLICY.md](RELEASE_POLICY.md). Do not open a public issue for a security vulnerability or include tokens, private chat identifiers, production payloads, or other sensitive data in an issue, pull request, test, log, screenshot, or commit.
+
+Check existing issues and pull requests before opening a new one. For a defect, use the bug template and include a minimal reproduction. For a new capability, use the feature template and explain the public API, behavior, compatibility, and testing implications.
+
+## Local setup
+
+The project requires Node.js `>=20` and uses npm for release-compatible commands. Install dependencies and run the baseline checks:
+
+```bash
+npm ci
+npm run typecheck
+npm run test:types
+npm run lint
+npm test
+npm run build
+npm run security
+npm run release:check
+```
+
+The credential-gated Telegram E2E suite is skipped unless the required test environment variables are provided. Never use production credentials in tests. Use `MockTransport`, `createTestBot()`, `createMockUpdate()`, and the integration fixtures for deterministic tests.
+
+## Branches and commits
+
+Create a focused branch from `main`. Keep unrelated refactors out of a feature or bug-fix pull request. Use an imperative Conventional Commit-style message, for example `fix: isolate polling handler failures` or `docs: expand storage adapter reference`. Include `[skip release]` only when a change must not trigger the GitHub-to-npm release workflow; maintainers may remove that marker when a release is appropriate.
+
+## Implementation expectations
+
+Public behavior must be implemented in TypeScript with strict typing. Do not add fake responses, silent stubs, undocumented breaking behavior, or untested branches. Preserve ESM and CommonJS builds, zero runtime vendor dependencies in the core package, Node.js `>=20` compatibility, and the existing package export map.
+
+Changes to routing, context, lifecycle, transport, storage, queue, scheduler, approval, generated API declarations, or release automation require regression tests. Changes to a public function, class, method, option, error, event, or generated method require a corresponding API documentation update. Changes that affect package contents must pass `release:check` and `npm pack --dry-run`.
+
+## Pull request process
+
+Open a pull request against `main` and complete the pull request template. Explain the problem, solution, compatibility impact, test evidence, documentation changes, and security implications. Keep the diff reviewable. Maintainers may request changes, split a pull request, or ask for a follow-up issue when scope is too broad.
+
+Every pull request must pass the CI workflow. A maintainer reviews API compatibility, error handling, tests, documentation, package contents, and release impact before approval. Do not merge while required checks are failing or unresolved security concerns remain.
+
+## Documentation and translations
+
+English is the default README language. Keep `README.id.md`, `README.zh-CN.md`, `docs/API.id.md`, and `docs/API.zh-CN.md` synchronized when public behavior changes. Code signatures, method names, package names, environment variables, and command names must remain exact in every translation.
+
+## Release process
+
+Normal pushes to `main` can trigger the protected auto-publish workflow. The workflow runs quality gates, computes an unused patch version, publishes the package, commits the version, creates a tag, and creates a GitHub Release. See [RELEASE_AUTOMATION.md](RELEASE_AUTOMATION.md) for the required `NPM_TOKEN` secret and private-source provenance constraint. Contributors must not publish directly to npm unless explicitly authorized by the maintainers.
+
+## Questions
+
+Use the question/support template for usage questions and consult the [English API reference](docs/API.md) first. Keep support requests free of credentials and private user data.

package/CONTRIBUTION_RULES.md

@@ -0,0 +1,41 @@
+# Contribution Rules
+
+These rules are the operational requirements for contributions to telebibz. They complement [CONTRIBUTING.md](CONTRIBUTING.md) and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
+
+## Scope and ownership
+
+A contribution must have a clear owner, a stated problem, and a bounded outcome. Large changes should be split into reviewable pull requests. Maintainers may reject work that is technically correct but outside the package scope, duplicates an existing design, introduces unnecessary dependencies, or creates disproportionate maintenance cost.
+
+## API and compatibility rules
+
+Public exports, constructor options, method signatures, event names, error classes, generated method names, package entrypoints, and persisted data formats are compatibility-sensitive. A breaking change requires an explicit migration note, a versioning decision, updated type-level tests, and maintainer approval.
+
+New public APIs must have strict TypeScript types, runtime validation where input can be unsafe, deterministic error behavior, examples, and API reference documentation. Avoid `any` in public signatures. When a Telegram type is not specialized in the core method map, use the vendored `TelegramTypes` declarations or an honest generic boundary rather than inventing an inaccurate shape.
+
+## Runtime and error-handling rules
+
+Network operations must honor timeout and cancellation behavior. Retry logic must be bounded and must not retry authentication or validation failures blindly. Update handlers must not terminate polling because one update failed. Background tasks must surface errors through documented hooks or events and must not create unhandled promise rejections.
+
+Callback-query handling must work for both message-backed and inline callbacks. Router behavior must state whether first-match or all-match is used. Nested middleware must not execute terminal handlers twice. Persistent state must use the `Storage` abstraction and must document consistency, TTL, and driver assumptions.
+
+## Testing rules
+
+A pull request must add or update tests for every changed behavior. Use unit tests for pure logic, integration tests for module boundaries, type-level tests for public signatures, and credential-gated E2E tests only for real Telegram behavior that cannot be represented safely by mocks. Tests must be deterministic and must clean up timers, temporary files, listeners, and network resources.
+
+A bug fix is incomplete without a regression test that fails against the old behavior. A feature is incomplete without tests for success, invalid input, cancellation, retry/failure, and boundary behavior where applicable.
+
+## Documentation rules
+
+Documentation must describe the implementation that exists in source, not a planned feature. Every documented limitation must remain accurate. English is canonical; Indonesian and Simplified Chinese translations must preserve signatures, code blocks, URLs, environment variables, and command names exactly.
+
+## Dependency and security rules
+
+Do not add a runtime dependency without a written justification, license review, bundle/package impact analysis, and maintainer approval. Never commit credentials, private keys, Telegram tokens, npm tokens, test secrets, or real user data. Security-sensitive changes require review of [SECURITY.md](SECURITY.md) and must not be disclosed publicly before a fix or coordinated disclosure decision.
+
+## Release and repository rules
+
+Do not edit or overwrite an already published npm version. Do not manually create a release tag that conflicts with the protected workflow. Do not bypass required checks, disable security audit, weaken release checks, or modify workflow permissions without maintainer approval. Use `[skip release]` only for changes that must not publish a package.
+
+## Review standards
+
+Reviewers should verify correctness, compatibility, tests, documentation, security, package contents, and operational behavior. Approval is not a guarantee that no defect exists; it confirms that the change meets the current project acceptance criteria and is safe to merge based on the available evidence.

package/GOVERNANCE.md

@@ -0,0 +1,47 @@
+# Governance
+
+## Project purpose
+
+telebibz is a TypeScript Telegram Bot Framework. Governance exists to preserve a stable public API, honest feature scope, secure release automation, and a respectful contributor community.
+
+## Roles
+
+| Role | Responsibility |
+|---|---|
+| Users | Report reproducible defects, explain use cases, and provide feedback without publishing secrets. |
+| Contributors | Submit focused code, tests, documentation, and issue reports that follow the project rules. |
+| Reviewers | Examine correctness, compatibility, security, tests, documentation, and operational risk. |
+| Maintainers | Set project direction, review and merge changes, manage releases, triage issues, and protect the repository. |
+| Release maintainers | Control npm credentials, GitHub Actions environments, version tags, npm publication, and release verification. |
+
+One person may hold multiple roles, but security-sensitive actions should use separation of duties whenever practical.
+
+## Decision-making
+
+Routine decisions are made by maintainers through pull request review and documented issue discussion. Decisions should be based on user benefit, implementation quality, compatibility, security, maintenance cost, and evidence from tests or production reports.
+
+For controversial or breaking changes, maintainers should document alternatives, migration impact, and the reason for the selected approach. A maintainer may request a design note before implementation. Silence is not approval for a breaking change.
+
+## Triage
+
+New issues are initially classified as bug, feature, documentation, security, support, or duplicate. Maintainers may request a reproduction, reduce sensitive details, split scope, mark a report as blocked, or close it when the requested behavior conflicts with the documented project contract.
+
+Security reports are handled privately according to [SECURITY.md](SECURITY.md). Public issues must not contain exploit instructions, credentials, or personal data.
+
+## Pull requests
+
+A pull request requires a passing CI workflow and at least one maintainer review. Changes affecting authentication, transport, update dispatch, persistence, release automation, package exports, or security policy may require additional review. Maintainers can require a regression test, API documentation, migration note, or threat-model explanation before merge.
+
+## Releases
+
+The protected GitHub Actions workflow is the canonical release path. It runs quality gates, computes a new immutable npm version, publishes the package, creates a version commit and tag, and creates a GitHub Release. Direct npm publication is restricted to authorized release maintainers. Release credentials must remain in GitHub or npm secret storage and must be rotated after exposure.
+
+Because the source repository is private, the workflow uses npm publish without provenance. If the repository becomes public and provenance is enabled, the policy and workflow must be reviewed together before the next release.
+
+## Repository protection
+
+Required CI checks, branch protection, environment approvals, workflow permissions, package scope, and immutable release rules must not be weakened casually. Any change to these controls requires a pull request, a written rationale, and maintainer approval.
+
+## Amendments
+
+Governance changes are proposed through a pull request that explains the current problem, proposed rule, affected roles, and migration plan. The updated governance document becomes effective when the pull request merges.

package/NOTICE.md

@@ -0,0 +1,7 @@
+# Third-party notices
+
+## Vendored Telegram declarations
+
+The declaration files under `src/api/telegram-types/` and the corresponding published `dist` paths are derived from [`@grammyjs/types`](https://www.npmjs.com/package/@grammyjs/types), version `4.0.0`, released under the MIT License.
+
+The original license text is preserved at `src/api/telegram-types/LICENSE`. These files are type-only declarations used to expose Telegram Bot API object, union, enum, and method types. They do not add a runtime dependency to telebibz.

package/README.id.md

@@ -0,0 +1,172 @@
+# 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).
+
+## 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.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,38 @@ 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).
+
+## Release automation
 
-## API target dan batasan
+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).
 
-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.
+## Project policies and contribution
 
-## Keamanan
+| Document | Purpose |
+|---|---|
+| [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) | Community behavior, enforcement, reporting, and appeals. |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | Local setup, branch/commit rules, tests, review, and release workflow. |
+| [CONTRIBUTION_RULES.md](CONTRIBUTION_RULES.md) | API, compatibility, testing, dependency, security, and release requirements. |
+| [GOVERNANCE.md](GOVERNANCE.md) | Roles, decision-making, triage, repository protection, and amendments. |
+| [SECURITY.md](SECURITY.md) | Private vulnerability reporting, threat boundaries, and credential rotation. |
+| [SUPPORT.md](SUPPORT.md) | Support channels, safe-reporting rules, and request expectations. |
+| [RELEASE_AUTOMATION.md](RELEASE_AUTOMATION.md) | GitHub-to-npm automation and required `NPM_TOKEN` setup. |
+| [RELEASE_POLICY.md](RELEASE_POLICY.md) | Immutable release and hardening controls. |
+| [NOTICE.md](NOTICE.md) | Third-party declaration attribution. |
 
-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).