@xbibzlibrary/telebibz 0.1.2 → 0.1.4

package/README.zh-CN.md

@@ -0,0 +1,172 @@
+# 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)。
+
+## 项目 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)。

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
 

package/SECURITY.md

@@ -2,14 +2,46 @@
 
 ## Supported versions
 
-Security fixes target the latest development branch and the latest published stable release.
+Security fixes target the latest development branch and the latest published stable release. Older versions may not receive backports. Upgrade to the latest release before requesting a fix unless the issue prevents upgrading.
+
+| Version | Supported |
+|---|---|
+| `main` | Yes, subject to current development changes |
+| Latest `0.x` release | Yes |
+| Older releases | Best effort only |
 
 ## Reporting a vulnerability
 
-Jangan publikasikan token bot, payload sensitif, atau detail eksploit pada issue terbuka. Kirim laporan privat kepada maintainer package dengan deskripsi reproduksi minimal, impact, versi Node.js, versi `telebibz`, dan apakah masalah terjadi pada transport, webhook, routing, storage, atau CLI.
+Do not publish tokens, sensitive payloads, exploit instructions, private chat content, or personal data in a public issue, pull request, discussion, or commit.
+
+Use GitHub's private vulnerability reporting or Security Advisory flow for this repository when available: [Report a private vulnerability](https://github.com/XbibzOfficial777/telebibz/security/advisories/new). If that flow is unavailable, contact the repository maintainers privately through an authenticated GitHub channel and request a secure reporting path. Do not create a public issue to ask where to report a vulnerability.
+
+A useful report includes the affected version or commit, Node.js version, impact, attack prerequisites, a minimal safe reproduction, affected subsystem, and a proposed mitigation if known. Redact credentials, personal information, private Telegram identifiers, and production payloads. Attachments should be sanitized before submission.
+
+## What to report privately
+
+Report authentication bypasses, secret exposure, webhook verification failures, unsafe file or URL handling, arbitrary code execution, injection, cross-user state leakage, approval-gate bypasses, dependency supply-chain issues, release-workflow compromise, and vulnerabilities that can cause unauthorized Telegram actions or data disclosure.
+
+Ordinary bugs without a security impact should use the public [Bug Report template](.github/ISSUE_TEMPLATE/bug_report.yml). Documentation and support requests should use their dedicated templates.
+
+## Response process
+
+Maintainers acknowledge a private report when practical, reproduce it in an isolated environment, assess severity and affected versions, coordinate a fix, and publish a security advisory or release note when disclosure is appropriate. Timelines depend on severity, reproducibility, maintainer availability, and coordination with affected users or upstream providers.
+
+Reporters should allow reasonable time for remediation and coordinated disclosure. Do not publicly disclose a vulnerability, proof of exploit, or affected production target before maintainers confirm that disclosure is safe.
 
 ## Security boundaries
 
-`telebibz` tidak mengirim telemetry ke third party secara otomatis. Token harus diberikan melalui environment atau secret manager dan tidak boleh dimasukkan ke source control. Aplikasi pengguna bertanggung jawab untuk membatasi akses server webhook, mengelola secret rotation, memvalidasi authorization domain Mini App, dan memilih adapter storage yang aman.
+telebibz does not send telemetry to third parties automatically. Tokens must be supplied through environment variables or a secret manager and must never be committed to source control, issue text, logs, screenshots, package archives, or workflow output.
+
+Telegram input is untrusted. Callback data, file paths, URLs, JSON payloads, and user-provided text must be validated before being used as filesystem, network, database, shell, or authorization input. Webhook deployments must restrict access, verify the Telegram secret token, enforce body-size limits, and apply infrastructure-level rate limiting where appropriate.
+
+Storage adapters are security boundaries owned by the application. Configure Redis, SQL, Mongo, and file permissions according to the deployment threat model. Do not store secrets or unnecessary personal data in sessions, conversations, caches, queues, or approval records.
+
+## Credential exposure and rotation
+
+If a Telegram or npm credential is exposed, revoke or rotate it immediately through the relevant provider, remove it from uncommitted files and logs, invalidate affected sessions, inspect release history, and report the exposure privately. Removing a secret from the latest commit does not remove it from history or external logs.
+
+## Security updates
 
-Input dari Telegram dianggap tidak tepercaya. Callback data, file path, URL, JSON payload, dan user-provided text harus divalidasi sebelum digunakan sebagai perintah filesystem, network, atau database.
+Security fixes may change behavior or require a new immutable npm version. Follow [RELEASE_POLICY.md](RELEASE_POLICY.md) and [RELEASE_AUTOMATION.md](RELEASE_AUTOMATION.md) for the protected release path.

package/SUPPORT.md

@@ -0,0 +1,30 @@
+# Support Policy
+
+## Before requesting support
+
+Read the [English API reference](docs/API.md), the localized API references, [CONTRIBUTING.md](CONTRIBUTING.md), and the relevant release or security policy. Search existing issues and discussions before opening a new request.
+
+## Where to ask
+
+| Need | Channel |
+|---|---|
+| Usage question or configuration help | GitHub issue using the Question/Support template |
+| Reproducible defect | GitHub issue using the Bug Report template |
+| New capability | GitHub issue using the Feature Request template |
+| Documentation error | GitHub issue using the Documentation template |
+| Security vulnerability | Private process described in [SECURITY.md](SECURITY.md); never a public issue |
+| Contribution or patch | Pull request following [CONTRIBUTING.md](CONTRIBUTING.md) |
+
+## Information to include
+
+Provide the telebibz version, Node.js version, operating system where relevant, module system, minimal reproduction, expected behavior, actual behavior, stack trace with secrets removed, and the result of relevant quality gates. Include whether the behavior occurs with ESM, CommonJS, mocks, or a real Telegram environment.
+
+Never include Telegram bot tokens, npm tokens, private keys, cookies, authorization headers, real user identifiers, private chat content, or unredacted production payloads. Replace sensitive values with placeholders before posting.
+
+## Response expectations
+
+This is a community-maintained project. Maintainers prioritize security reports, release blockers, data-loss risks, regressions, and reproducible runtime failures. Response and fix times are not guaranteed. A support request may be closed when it lacks a reproduction after reasonable follow-up, duplicates an existing issue, or asks for behavior outside the documented scope.
+
+## Support boundaries
+
+Support does not include operating a user's production infrastructure, recovering deleted credentials, guaranteeing Telegram availability, or bypassing npm/GitHub permission controls. For Telegram platform behavior, verify the official Telegram Bot API documentation as well as the telebibz API reference.

package/assets/readme-preview.html

@@ -0,0 +1,75 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>telebibz README preview</title>
+<style>
+  :root { color-scheme: dark; --bg:#07111f; --panel:#0d1b2d; --panel2:#11243a; --line:#24415f; --text:#f1f7ff; --muted:#9db1c8; --cyan:#42d9ff; --blue:#668cff; --green:#72e1ad; --orange:#ffbd6b; }
+  * { box-sizing: border-box; }
+  body { margin:0; width:1600px; min-height:1000px; font-family: Inter, ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif; background: radial-gradient(circle at 10% 0%, #12345b 0, transparent 37%), linear-gradient(135deg,#06101d,#0a1728 55%,#071221); color:var(--text); }
+  .wrap { padding:58px 74px 64px; }
+  .top { display:flex; align-items:center; justify-content:space-between; margin-bottom:44px; }
+  .brand { display:flex; align-items:center; gap:20px; }
+  .mark { width:78px; height:78px; border-radius:22px; background:linear-gradient(145deg,#39d9ff,#637cff); display:grid; place-items:center; box-shadow:0 18px 45px #1e8bdc55; font-weight:900; font-size:31px; letter-spacing:-3px; color:#fff; }
+  h1 { font-size:48px; line-height:1; margin:0 0 10px; letter-spacing:-2px; }
+  .tag { color:var(--muted); font-size:20px; }
+  .lang { border:1px solid var(--line); background:#0b1b2d; color:#dcecff; padding:12px 18px; border-radius:12px; font-weight:700; }
+  .hero { display:grid; grid-template-columns: 1fr 1.15fr; gap:34px; align-items:stretch; }
+  .hero-copy { padding:30px 0 10px; }
+  .eyebrow { color:var(--cyan); text-transform:uppercase; letter-spacing:2px; font-size:13px; font-weight:800; }
+  h2 { font-size:42px; line-height:1.08; letter-spacing:-1.5px; margin:14px 0 18px; max-width:630px; }
+  .lead { color:#bfd0e4; font-size:20px; line-height:1.5; max-width:640px; }
+  .pill-row { display:flex; flex-wrap:wrap; gap:10px; margin-top:26px; }
+  .pill { border:1px solid #2d5277; background:#0c2035; color:#dcefff; padding:9px 13px; border-radius:999px; font-size:14px; }
+  .code { border:1px solid var(--line); background:#071525; border-radius:20px; overflow:hidden; box-shadow:0 22px 70px #0006; }
+  .code-head { display:flex; align-items:center; gap:8px; padding:15px 18px; background:#0d2137; border-bottom:1px solid var(--line); color:#91abc8; font-size:14px; }
+  .dot { width:10px; height:10px; border-radius:50%; background:#fb7185; } .dot:nth-child(2){background:#fbbf24}.dot:nth-child(3){background:#34d399}
+  pre { margin:0; padding:24px 28px 30px; font-family:"SFMono-Regular",Consolas,monospace; font-size:18px; line-height:1.62; color:#d9e8fa; white-space:pre-wrap; }
+  .kw { color:#9b9dff; }.fn { color:#74e7ff; }.str { color:#8de8ae; }.cm { color:#6f8ba8; }
+  .section-title { margin:56px 0 20px; display:flex; align-items:end; justify-content:space-between; }
+  .section-title h3 { margin:0; font-size:26px; letter-spacing:-.5px; }.section-title span { color:var(--muted); font-size:14px; }
+  .cards { display:grid; grid-template-columns:repeat(4,1fr); gap:16px; }
+  .card { min-height:150px; padding:21px; border:1px solid var(--line); background:linear-gradient(145deg,#0d2034,#0b1828); border-radius:16px; }
+  .icon { color:var(--cyan); font-size:22px; font-weight:900; }.card strong { display:block; margin:12px 0 8px; font-size:17px; }.card p { margin:0; color:var(--muted); line-height:1.45; font-size:14px; }
+  .footer { display:flex; justify-content:space-between; gap:20px; margin-top:40px; padding-top:20px; border-top:1px solid var(--line); color:var(--muted); font-size:14px; }
+  .status { color:var(--green); font-weight:800; }
+</style>
+</head>
+<body>
+  <main class="wrap">
+    <header class="top">
+      <div class="brand"><div class="mark">tb</div><div><h1>telebibz</h1><div class="tag">Telegram Bot Framework for Node.js &amp; TypeScript</div></div></div>
+      <div class="lang">English &nbsp;·&nbsp; Bahasa Indonesia &nbsp;·&nbsp; 简体中文</div>
+    </header>
+    <section class="hero">
+      <div class="hero-copy">
+        <div class="eyebrow">Typed. Composable. Production-minded.</div>
+        <h2>Build serious Telegram bots without fighting the API.</h2>
+        <p class="lead">A full-scale framework with typed API access, routing, middleware, context helpers, keyboards, sessions, webhooks, queues, scheduling, plugins, approval gates, and test utilities.</p>
+        <div class="pill-row"><span class="pill">Node.js ≥ 20</span><span class="pill">ESM + CommonJS</span><span class="pill">Telegram Bot API 10.2</span><span class="pill">TypeScript strict</span></div>
+      </div>
+      <div class="code"><div class="code-head"><span class="dot"></span><span class="dot"></span><span class="dot"></span><span style="margin-left:8px">examples/minimal.ts</span></div><pre><span class="kw">import</span> { <span class="fn">Bot</span>, <span class="fn">InlineKeyboard</span> } <span class="kw">from</span> <span class="str">"@xbibzlibrary/telebibz"</span>;
+
+<span class="kw">const</span> bot = <span class="kw">new</span> <span class="fn">Bot</span>(process.env.TELEGRAM_BOT_TOKEN!);
+
+bot.<span class="fn">command</span>(<span class="str">"start"</span>, (ctx) =&gt;
+  ctx.<span class="fn">reply</span>(<span class="str">"Welcome to telebibz"</span>, {
+    reply_markup: <span class="kw">new</span> <span class="fn">InlineKeyboard</span>()
+      .<span class="fn">text</span>(<span class="str">"Explore API"</span>, <span class="str">"api"</span>)
+      .<span class="fn">build</span>(),
+  }),
+);
+
+<span class="kw">await</span> bot.<span class="fn">start</span>();</pre></div>
+    </section>
+    <div class="section-title"><h3>One framework, the whole bot lifecycle</h3><span>Designed around real Telegram primitives</span></div>
+    <section class="cards">
+      <article class="card"><div class="icon">01</div><strong>Typed API client</strong><p>Dynamic Telegram method access with typed core methods, errors, retry, timeout, JSON, multipart, and AbortSignal.</p></article>
+      <article class="card"><div class="icon">02</div><strong>Router + context</strong><p>Commands, exact text, regex, callbacks, predicates, nested routes, middleware composition, and ergonomic replies.</p></article>
+      <article class="card"><div class="icon">03</div><strong>Stateful workflows</strong><p>Sessions, forms, conversations, wizards, menus, pagination, queues, schedulers, caches, and plugins.</p></article>
+      <article class="card"><div class="icon">04</div><strong>Release hardening</strong><p>Approval gate, webhook secret verification, ESM/CommonJS builds, tests, security checks, and npm provenance.</p></article>
+    </section>
+    <footer class="footer"><span>xbibzlibrary/telebibz · documented in three languages</span><span class="status">● API surface documented</span></footer>
+  </main>
+</body>
+</html>

package/dist/src/api/index.d.ts

@@ -2,4 +2,5 @@ export * from "./client.js";
 export * from "./errors.js";
 export * from "./transport.js";
 export * from "./types.js";
+export * from "./telegram.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/src/api/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC"}

package/dist/src/api/index.js

@@ -2,4 +2,5 @@ export * from "./client.js";
 export * from "./errors.js";
 export * from "./transport.js";
 export * from "./types.js";
+export * from "./telegram.js";
 //# sourceMappingURL=index.js.map

package/dist/src/api/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/api/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/api/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC"}

package/dist/src/api/telegram-types/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021-2024 KnorpelSenf
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/src/api/telegram-types/api.d.ts

@@ -0,0 +1,22 @@
+export interface ApiError {
+    ok: false;
+    error_code: number;
+    description: string;
+    parameters?: ResponseParameters;
+}
+export interface ApiSuccess<T> {
+    ok: true;
+    result: T;
+}
+/** The response contains an object, which always has a Boolean field 'ok' and may have an optional String field 'description' with a human-readable description of the result. If 'ok' equals True, the request was successful and the result of the query can be found in the 'result' field. In case of an unsuccessful request, 'ok' equals False and the error is explained in the 'description'. An Integer 'error_code' field is also returned, but its contents are subject to change in the future. Some errors may also have an optional field 'parameters' of the type ResponseParameters, which can help to automatically handle the error.
+
+- All methods in the Bot API are case-insensitive.
+- All queries must be made using UTF-8. */
+export type ApiResponse<T> = ApiError | ApiSuccess<T>;
+/** Describes why a request was unsuccessful. */
+export interface ResponseParameters {
+    /** The group has been migrated to a supergroup with the specified identifier. */
+    migrate_to_chat_id?: number;
+    /** In case of exceeding flood control, the number of seconds left to wait before the request can be repeated */
+    retry_after?: number;
+}

package/dist/src/api/telegram-types/checklist.d.ts

@@ -0,0 +1,72 @@
+import type { Chat, User } from "./manage.js";
+import type { Message, MessageEntity, ParseMode } from "./message.js";
+/** Describes a task in a checklist. */
+export interface ChecklistTask {
+    /** Unique identifier of the task */
+    id: number;
+    /** Text of the task */
+    text: string;
+    /** Special entities that appear in the task text */
+    text_entities?: MessageEntity[];
+    /** User that completed the task; omitted if the task wasn't completed by a user */
+    completed_by_user?: User;
+    /** Chat that completed the task; omitted if the task wasn't completed by a chat */
+    completed_by_chat?: Chat;
+    /** Point in time (Unix timestamp) when the task was completed; 0 if the task wasn't completed */
+    completion_date?: number;
+}
+/** Describes a checklist. */
+export interface Checklist {
+    /** Title of the checklist */
+    title: string;
+    /** Special entities that appear in the checklist title */
+    title_entities?: MessageEntity[];
+    /** List of tasks in the checklist */
+    tasks: ChecklistTask[];
+    /** True, if users other than the creator of the list can add tasks to the list */
+    others_can_add_tasks?: true;
+    /** True, if users other than the creator of the list can mark tasks as done or not done */
+    others_can_mark_tasks_as_done?: true;
+}
+/** Describes a task to add to a checklist. */
+export interface InputChecklistTask {
+    /** Unique identifier of the task; must be positive and unique among all task identifiers currently present in the checklist */
+    id: number;
+    /** Text of the task; 1-100 characters after entities parsing */
+    text: string;
+    /** Mode for parsing entities in the text. See formatting options for more details. */
+    parse_mode?: ParseMode;
+    /** List of special entities that appear in the text, which can be specified instead of parse_mode. Currently, only bold, italic, underline, strikethrough, spoiler, custom_emoji, and date_time entities are allowed. */
+    text_entities?: MessageEntity[];
+}
+/** Describes a checklist to create. */
+export interface InputChecklist {
+    /** Title of the checklist; 1-255 characters after entities parsing */
+    title: string;
+    /** Mode for parsing entities in the title. See formatting options for more details. */
+    parse_mode?: ParseMode;
+    /** List of special entities that appear in the title, which can be specified instead of parse_mode. Currently, only bold, italic, underline, strikethrough, spoiler, custom_emoji, and date_time entities are allowed. */
+    title_entities?: MessageEntity[];
+    /** List of 1-30 tasks in the checklist */
+    tasks: InputChecklistTask[];
+    /** Pass True if other users can add tasks to the checklist */
+    others_can_add_tasks?: boolean;
+    /** Pass True if other users can mark tasks as done or not done in the checklist */
+    others_can_mark_tasks_as_done?: true;
+}
+/** Describes a service message about checklist tasks marked as done or not done. */
+export interface ChecklistTasksDone {
+    /** Message containing the checklist whose tasks were marked as done or not done. Note that the Message object in this field will not contain the reply_to_message field even if it itself is a reply. */
+    checklist_message?: Message;
+    /** Identifiers of the tasks that were marked as done */
+    marked_as_done_task_ids?: number[];
+    /** Identifiers of the tasks that were marked as not done */
+    marked_as_not_done_task_ids?: number[];
+}
+/** Describes a service message about tasks added to a checklist. */
+export interface ChecklistTasksAdded {
+    /** Message containing the checklist to which the tasks were added. Note that the Message object in this field will not contain the reply_to_message field even if it itself is a reply. */
+    checklist_message?: Message;
+    /** List of tasks added to the checklist */
+    tasks: ChecklistTask[];
+}