tgplus 1.0.0

package/README.md

@@ -0,0 +1,1512 @@
+<div align="center">
+
+# TG plus ✨
+
+**A friendlier, fully-typed Telegram Bot API library for Node.js**
+
+Works equally well from plain JavaScript or TypeScript. Covers **Bot API 7.0 through 10.3** — 187 methods across 21 categories.
+
+<p>
+  <a href="https://www.npmjs.com/package/tgplus"><img src="https://img.shields.io/npm/v/tgplus?style=flat-square&color=blue" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/tgplus"><img src="https://img.shields.io/npm/dm/tgplus?style=flat-square&color=green" alt="npm downloads"></a>
+  <a href="https://github.com/crysnovax/TGplus/actions"><img src="https://img.shields.io/github/actions/workflow/status/crysnovax/TGplus/test.yml?style=flat-square" alt="CI"></a>
+  <img src="https://img.shields.io/badge/zero%20runtime%20deps-✓-brightgreen?style=flat-square" alt="Zero runtime dependencies">
+  <img src="https://img.shields.io/badge/Node.js-%3E%3D18-blue?style=flat-square&logo=node.js" alt="Node.js">
+</p>
+
+<img src="https://cdn.crysnova.qzz.io/files/1789261660580-631a0aeb-b041-466d-ac89-400b968b1920.jpeg" alt="tgplus" width="720" />
+
+[Quick Start](#quick-start) · [Features With Examples](#features-with-examples) · [Every Class](#every-class-with-an-example) · [Full API Surface](#the-complete-api-surface) · [Testing](#testing) · [Status](#status)
+
+</div>
+
+---
+
+## Table of contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Features With Examples](#features-with-examples)
+  1. [Router handlers](#1-router-handlers)
+  2. [Keyboard builders](#2-keyboard-builders)
+  3. [Editing messages from button taps](#3-editing-messages-from-button-taps)
+  4. [Rich Messages](#4-rich-messages-bot-api-101103)
+  5. [Inline streaming & AI drafts](#5-inline-streaming--ai-drafts)
+  6. [Decorator classes](#6-decorator-classes)
+  7. [Scenes (multi-step conversations)](#7-scenes-multi-step-conversations)
+  8. [Sessions](#8-sessions)
+  9. [Rate limiting](#9-rate-limiting)
+  10. [Flood control & throttling](#10-flood-control--throttling)
+  11. [i18n](#11-i18n)
+  12. [Entity & reaction filters](#12-entity--reaction-filters)
+  13. [File uploads & downloads](#13-file-uploads--downloads)
+  14. [Composer gates, combinators & Router](#14-composer-gates-combinators--router)
+  15. [Polling, webhooks & serverless](#15-polling-webhooks--serverless)
+  16. [Context helpers](#16-context-helpers)
+  17. [Typed API & escape hatch](#17-typed-api--escape-hatch)
+  18. [Error handling](#18-error-handling)
+- [Every Class, With An Example](#every-class-with-an-example)
+- [The Complete API Surface](#the-complete-api-surface)
+- [Coverage Confidence](#coverage-confidence)
+- [Project Layout](#project-layout)
+- [Testing](#testing)
+- [Status](#status)
+- [Contributing](#contributing)
+- [Credits](#credits)
+- [License](#license)
+
+---
+
+## Installation
+
+```bash
+npm install tgplus
+```
+
+Requires Node.js 18+ (uses the native `fetch`/`FormData`/`Blob` globals — no runtime dependencies to install).
+
+Optional peer dependencies, only if you use them:
+
+```bash
+npm install ioredis          # for RedisSessionStore
+npm install better-sqlite3   # for SqliteSessionStore
+```
+
+---
+
+## Quick Start
+
+```typescript
+import { Bot } from "tgplus";
+
+const bot = new Bot(process.env.BOT_TOKEN!);
+
+bot.command("start", (ctx) => ctx.reply(`Hey ${ctx.from?.first_name}!`));
+bot.hears(/^ping$/i, (ctx) => ctx.reply("pong"));
+bot.on("photo", (ctx) => ctx.reply("Nice photo!"));
+
+bot.launch(); // long polling
+```
+
+Everything below is a worked example of one part of the package.
+
+---
+
+## Features With Examples
+
+### 1. Router handlers
+
+`command` / `hears` / `on` / `action`. Regex captures land in `ctx.match`; `command()` accepts aliases and `/cmd@BotName`.
+
+```typescript
+// Multiple aliases for one handler — "/help" and "/h" both match
+bot.command(["help", "h"], (ctx) => ctx.reply("Here's what I can do."));
+
+// Arguments after the command: "/ban 42 spam" -> ctx.match[1] === "42 spam"
+bot.command("ban", (ctx) => {
+  const args = ctx.match![1] ?? "";
+  ctx.reply(`Banning ${args || "…"} (not really).`);
+});
+
+// /start@MyBotName also matches (deep links, group usage)
+bot.command("start", (ctx) => ctx.reply("Started."));
+
+// Exact string or RegExp on message text
+bot.hears("hello", (ctx) => ctx.reply("Hi!"));
+bot.hears(/^good (morning|evening)$/i, (ctx) => ctx.reply(`Good ${ctx.match![1].toLowerCase()}!`));
+
+// Update types
+bot.on("message", (ctx) => ctx.reply("A message arrived."));
+
+// Message sub-types
+bot.on("text", (ctx) => ctx.reply(`You said: ${ctx.text}`));
+bot.on("photo", (ctx) => ctx.reply("Nice photo!"));
+bot.on("sticker", (ctx) => ctx.reply("Nice sticker."));
+bot.on("location", (ctx) => ctx.reply("Got a location."));
+bot.on("contact", (ctx) => ctx.reply("Got a contact."));
+bot.on("poll", (ctx) => ctx.reply("A poll."));
+bot.on("dice", (ctx) => ctx.reply("A dice."));
+bot.on("video_note", (ctx) => ctx.reply("Round video."));
+bot.on("rich_message", (ctx) => ctx.reply("A rich message."));
+
+// Non-message update types
+bot.on("callback_query", (ctx) => ctx.answerCbQuery());
+bot.on("inline_query", (ctx) => ctx.answerInlineQuery([]));
+bot.on("chat_join_request", (ctx) => ctx.api.approveChatJoinRequest({ chat_id: ctx.chatId!, user_id: ctx.from!.id }));
+bot.on("poll_answer", (ctx) => console.log("Poll answered by", ctx.from?.id));
+
+// Callback button data — exact or RegExp with captures
+bot.action("dice", (ctx) => ctx.api.sendDice({ chat_id: ctx.chatId! }));
+bot.action(/^server:(.+)$/, (ctx) => ctx.reply(`Opening server ${ctx.match![1]}…`));
+
+// A custom predicate instead of a name
+bot.on((ctx) => ctx.text?.includes("urgent") === true, (ctx) => ctx.reply("Marked urgent."));
+
+// Catch-all — put it last
+bot.otherwise((ctx) => ctx.reply("I didn't understand that."));
+```
+
+### 2. Keyboard builders
+
+`Keyboard.inline()`, `Keyboard.reply()`, `Keyboard.remove()`, `Keyboard.forceReply()`.
+
+```typescript
+import { Keyboard } from "tgplus";
+
+// ---- Inline keyboard (buttons attached to a message) ----
+bot.command("menu", (ctx) =>
+  ctx.reply("Pick one:", {
+    reply_markup: Keyboard.inline()
+      .button("Confirm", "confirm:yes", { style: "success" })      // callback button + color
+      .button("Cancel", "confirm:no", { style: "danger" })
+      .button("Danger!", "d", { icon_custom_emoji_id: "5368324170671202286" })
+      .row()                                                        // start a new row
+      .url("Docs", "https://example.com")                           // URL button
+      .urlButton("Join channel", "https://t.me/example")            // alias of .url()
+      .row()
+      .webApp("Open Mini App", "https://your.app")                  // Web App button
+      .row()
+      .switchInline("Share this bot", "query")                      // switch to inline mode
+      .row()
+      .pay("Buy now")                                               // payment button
+      .row()
+      .copyText("Copy code", "AB12-CD34")                           // Bot API 7.11+ clipboard copy
+      .build(),
+  })
+);
+
+// ---- Reply keyboard (the persistent bottom keyboard) ----
+bot.command("settings", (ctx) =>
+  ctx.reply("Settings:", {
+    reply_markup: Keyboard.reply()
+      .text("Notifications")
+      .text("Language", { style: "primary" })
+      .row()
+      .requestContact("Share my contact")     // request_contact: true
+      .requestLocation("Share my location")   // request_location: true
+      .build({ resize: true, oneTime: true, placeholder: "Choose one" }),
+  })
+);
+
+// ---- Remove a reply keyboard ----
+bot.command("done", (ctx) =>
+  ctx.reply("Keyboard hidden.", { reply_markup: Keyboard.remove() })      // or Keyboard.remove(true) for selective
+);
+
+// ---- Force the user to type a reply ----
+bot.command("age", (ctx) =>
+  ctx.reply("How old are you?", { reply_markup: Keyboard.forceReply("Type a number") })
+);
+```
+
+> `ReplyKeyboardBuilder` supports `.text()`, `.requestContact()`, `.requestLocation()`, and `.row()`. Inline supports `.button()`, `.url()`, `.urlButton()`, `.webApp()`, `.switchInline()`, `.pay()`, `.copyText()`, `.row()`.
+
+### 3. Editing messages from button taps
+
+`editText` / `editCaption` / `editMedia` / `editReplyMarkup` / `deleteMessage` all resolve the message id from `callback_query.message` automatically — the single most common Telegram UI pattern.
+
+```typescript
+bot.command("confirm", (ctx) =>
+  ctx.reply("Proceed?", {
+    reply_markup: Keyboard.inline().button("Yes", "confirm:yes").button("No", "confirm:no").build(),
+  })
+);
+
+bot.action(/^confirm:(yes|no)$/, async (ctx) => {
+  await ctx.answerCbQuery();                       // stop the button spinner
+  await ctx.editText(ctx.match![1] === "yes" ? "Confirmed ✅" : "Cancelled ❌");
+  // ctx.editCaption(), ctx.editMedia(), ctx.editReplyMarkup() work the same way
+});
+
+// Toggle just the keyboard in place, without resending the message
+bot.action("toggle:notifs", async (ctx) => {
+  await ctx.answerCbQuery("Toggled");
+  await ctx.editReplyMarkup(
+    Keyboard.inline().button("Toggle again", "toggle:notifs").build()
+  );
+});
+
+// Replace the media under a caption
+bot.action("swap:image", async (ctx) => {
+  await ctx.answerCbQuery();
+  await ctx.editMedia({ type: "photo", media: { url: "https://picsum.photos/600" } });
+});
+
+// Delete the message the button was attached to
+bot.action("done", async (ctx) => {
+  await ctx.answerCbQuery();
+  await ctx.deleteMessage();
+});
+```
+
+### 4. Rich Messages (Bot API 10.1–10.3)
+
+Three builders. `markdown()` / `html()` write formatted text; `blocks()` builds the structured block tree — media blocks reference separately-declared media by id, and the `.photo()`/`.video()`/`.document()` helpers handle that bookkeeping (and throw locally if you reference an undeclared id).
+
+```typescript
+import { RichMessage } from "tgplus";
+
+// ---------- Rich Markdown ----------
+bot.command("report", (ctx) =>
+  ctx.replyRich(
+    RichMessage.markdown()
+      .heading("Build report", 2)
+      .text("Here's today's run:")
+      .table(["Step", "Status"], [["Install", "✅"], ["Test", "✅"], ["Deploy", "⏳"]]) // GFM table
+      .checklist(["Install deps", "Run tests", { label: "Deploy", done: false }])       // - [ ] / - [x]
+      .list(["First", "Second"], false)                                                 // bullet list
+      .list(["One", "Two"], true)                                                       // ordered list
+      .codeBlock("npm install tgplus", "bash")                                          // fenced code
+      .blockquote("Generated automatically.")                                           // > quote
+      .photo("https://example.com/screenshot.png", "Build screenshot")                  // inline image
+      .divider()                                                                        // ---
+      .build()
+  )
+);
+
+// ---------- Rich HTML ----------
+bot.command("html", (ctx) =>
+  ctx.replyRich(
+    RichMessage.html()
+      .heading("Hello", 2)
+      .paragraph("This is <b>Rich HTML</b>.")
+      .raw("<tg-spoiler>hidden</tg-spoiler>")
+      .build()
+  )
+);
+
+// ---------- Rich blocks (10.2+) — real structure, media, buttons, details ----------
+bot.command("card", (ctx) =>
+  ctx.replyRich(
+    RichMessage.blocks()
+      .heading("Server status", 2)
+      .paragraph("All systems operational.")
+      .divider()
+      .table(
+        [
+          [{ text: "Region", is_header: true }, { text: "Uptime", is_header: true }],
+          [{ text: "EU" }, { text: "99.99%" }],
+        ],
+        { bordered: true, striped: true, caption: "Last 24h" }
+      )
+      .list([
+        { label: "EU-west", blocks: [{ type: "paragraph", text: "99.99% uptime" }], is_checked: true },
+      ])
+      .photo({ url: "https://example.com/chart.png" }, { hasSpoiler: true, caption: { text: "Traffic" } })
+      .video({ url: "https://example.com/clip.mp4" }, { caption: { text: "Demo" } })
+      .audio({ url: "https://example.com/audio.mp3" })
+      .animation({ url: "https://example.com/loop.gif" })
+      .voiceNote({ url: "https://example.com/voice.ogg" })
+      .document({ url: "https://example.com/report.pdf" }, { caption: { text: "Full report" } }) // 10.3
+      .buttons([{ text: "Open dashboard", url: "https://example.com" }])                       // 10.3
+      .details("More details", [{ type: "paragraph", text: "Hidden until expanded." }], true)  // collapsible
+      .expandableBlockquote([{ type: "paragraph", text: "Long quote collapsed by default." }], { credit: "— Team" })
+      .raw({ type: "divider" })                                                               // escape hatch for any block
+      .build()
+  )
+);
+
+// The same InputRichMessage works with the raw API and in edits
+await bot.api.sendRichMessage({ chat_id: 42, rich_message: RichMessage.markdown().text("Hi").build() });
+await bot.api.editMessageText({ chat_id: 42, message_id: 10, rich_message: RichMessage.markdown().text("Updated").build() });
+```
+
+### 5. Inline streaming & AI drafts
+
+For AI/LLM output, Telegram supports **draft messages**: partial content is previewed in a private chat while it is being generated, then replaced by a real message when the stream finishes. `tgplus` wraps both the plain-text and rich-message drafts.
+
+- Drafts are **private-chat only** (`chat_id` must be the numeric user id).
+- A draft is **ephemeral** — a short preview, not saved in the chat.
+- `draft_id` must be **non-zero**; repeated calls with the same `draft_id` animate between states.
+- Bot API 10.3 adds `can_stop` (the user may stop generation) and `keep_on_stop` (keep the draft visible after stopping).
+
+```typescript
+// ---------- Stream plain text while an LLM generates it ----------
+bot.command("ask", async (ctx) => {
+  const draftId = Date.now(); // any non-zero number, stable for this generation
+  let accumulated = "";
+
+  for await (const chunk of fakeLLMStream("Write me a haiku about bots")) {
+    accumulated += chunk;
+    await bot.api.sendMessageDraft({
+      chat_id: ctx.from!.id,      // drafts are private-chat only
+      draft_id: draftId,
+      text: accumulated,
+      can_stop: true,             // Bot API 10.3+
+      keep_on_stop: false,        // Bot API 10.3+
+    });
+  }
+
+  // Finalize with a real, saved message
+  await ctx.reply(accumulated);
+});
+
+// ---------- Stream a rich message (markdown/HTML/blocks) ----------
+bot.command("ask-rich", async (ctx) => {
+  const draftId = Date.now();
+  let accumulated = "";
+
+  for await (const chunk of fakeLLMStream("Summarize the release notes")) {
+    accumulated += chunk;
+    await bot.api.sendRichMessageDraft({
+      chat_id: ctx.from!.id,
+      draft_id: draftId,
+      rich_message: RichMessage.markdown().text(accumulated).build(),
+      can_stop: true,
+    });
+  }
+
+  // Commit the finished content as a real message
+  await ctx.replyRich(RichMessage.markdown().text(accumulated).build());
+});
+
+// Helper standing in for a real streaming model call
+async function* fakeLLMStream(_prompt: string): AsyncGenerator<string> {
+  for (const word of ["Streaming ", "a ", "reply ", "token ", "by ", "token."]) yield word;
+}
+```
+
+> Sending a draft is `sendMessageDraft` / `sendRichMessageDraft`; both return `Promise<true>`. See the source comments in `src/client.ts` for the confidence notes on each (the rich variant's shape is field-verified; the plain-text variant is modeled on it).
+
+### 6. Decorator classes
+
+Pure sugar over the same router — mix freely with the other styles.
+
+```typescript
+import { Bot, Context, BotController, Command, Hears, Action, On } from "tgplus";
+
+@BotController() // optional marker decorator
+class MainController {
+  @Command("start")
+  start(ctx: Context) { return ctx.reply("Welcome!"); }
+
+  @Command(["help", "h"])
+  help(ctx: Context) { return ctx.reply("Send /start, or say thanks."); }
+
+  @Hears(/^thanks?$/i)
+  thanks(ctx: Context) { return ctx.reply("You're welcome!"); }
+
+  @Action(/^confirm:(yes|no)$/)
+  confirm(ctx: Context) {
+    const choice = ctx.match?.[1];
+    return ctx.reply(choice === "yes" ? "Confirmed ✅" : "Cancelled ❌");
+  }
+
+  @On("photo")
+  photo(ctx: Context) { return ctx.reply("Nice photo!"); }
+}
+
+const bot = new Bot(process.env.BOT_TOKEN!);
+bot.useController(new MainController());
+bot.launch();
+```
+
+### 7. Scenes (multi-step conversations)
+
+Mount `session()` **before** `Stage.middleware()`. Each step runs once per incoming update; `next()` advances the pointer (the next step runs on the *next* update), `selectStep(index)` jumps and runs immediately, `scene.leave()` exits.
+
+```typescript
+import { Context, session, Stage, WizardScene } from "tgplus";
+
+bot.use(session());
+
+const signup = new WizardScene<Context>("signup", [
+  async (ctx) => { await ctx.reply("What's your name?"); await ctx.wizard.next(); },
+  async (ctx) => { ctx.wizard.state.name = ctx.text; await ctx.reply("How old are you?"); await ctx.wizard.next(); },
+  async (ctx) => {
+    ctx.wizard.state.age = ctx.text;
+    await ctx.reply(`Thanks, ${ctx.wizard.state.name} (age ${ctx.wizard.state.age})!`);
+    await ctx.scene.leave();
+  },
+]);
+
+const stage = new Stage<Context>([signup]);
+stage.register(/* more WizardScenes… */);
+bot.use(stage.middleware());
+
+bot.command("signup", (ctx) => ctx.scene!.enter("signup"));                 // enter, optionally with initial state
+bot.command("edit", (ctx) => ctx.scene!.selectStep?.(0) as any);            // (wizard.selectStep from inside a step)
+bot.command("cancel", (ctx) => ctx.scene!.leave());
+bot.command("where", (ctx) => ctx.reply(`Current scene: ${ctx.scene!.current ?? "none"}`));
+
+// Inside a step you also have:
+// ctx.wizard.cursor        -> current step index
+// ctx.wizard.state         -> your collected data
+// ctx.wizard.next()        -> advance one step
+// ctx.wizard.selectStep(n) -> jump to step n and run it now
+```
+
+### 8. Sessions
+
+One `SessionStore` interface, three implementations. Swap without touching handlers. Sessions are keyed per chat by default — pass `getSessionKey` for per-user sessions.
+
+```typescript
+import { session, MemorySessionStore, RedisSessionStore, SqliteSessionStore } from "tgplus";
+
+// ---------- In-memory (default) ----------
+bot.use(session({ defaultSession: () => ({ count: 0 }) }));
+bot.on("text", (ctx) => {
+  const s = ctx.session as { count: number };
+  s.count += 1;
+  return ctx.reply(`Message #${s.count}`);
+});
+
+// ---------- Redis (ioredis or node-redis v4+; duck-typed) ----------
+import Redis from "ioredis";
+bot.use(session({
+  store: new RedisSessionStore(new Redis(), { prefix: "mybot:session:", ttlSeconds: 86400 }),
+  defaultSession: () => ({ lang: "en" }),
+}));
+
+// ---------- SQLite (better-sqlite3; duck-typed, synchronous) ----------
+import Database from "better-sqlite3";
+bot.use(session({
+  store: new SqliteSessionStore(new Database("bot.db"), { tableName: "my_sessions" }),
+}));
+
+// ---------- Per-user sessions instead of per-chat ----------
+bot.use(session({ getSessionKey: (ctx) => (ctx.from ? String(ctx.from.id) : undefined) }));
+
+// ---------- Deleting a session ----------
+bot.command("reset", async (ctx) => {
+  (ctx as any).session = undefined; // session() removes the stored entry when ctx.session is undefined after your handler
+  await ctx.reply("Session cleared.");
+});
+```
+
+### 9. Rate limiting
+
+Sliding-window limiter for **incoming** updates. Mount it early so spam never reaches your handlers.
+
+```typescript
+import { rateLimit } from "tgplus";
+
+bot.use(rateLimit({
+  windowMs: 2000,                                                 // window length, default 3000
+  limit: 3,                                                       // max updates per window per key, default 1
+  keyFn: (ctx) => (ctx.from ? String(ctx.from.id) : undefined),   // default: per chat
+  onLimitExceeded: (ctx) => ctx.reply("Slow down!"),              // default: silently drop
+}));
+```
+
+### 10. Flood control & throttling
+
+429 responses are retried automatically on **every** API call (not just polling), honoring Telegram's `retry_after`. `minIntervalMs` queues outgoing calls at a fixed pace.
+
+```typescript
+const bot = new Bot(process.env.BOT_TOKEN!, {
+  floodControl: { maxRetries: 5 }, // default 3
+  minIntervalMs: 35,               // ~28 msgs/sec, safely under Telegram's ~30/sec
+  apiRoot: "https://api.telegram.org", // point at a local Bot API server if you run one
+});
+```
+
+### 11. i18n
+
+`createI18n` attaches `ctx.t(key, ...args)` using the user's Telegram `language_code`, falling back to `defaultLocale`. Dictionary values may be strings or functions (for interpolation/pluralization).
+
+```typescript
+import { createI18n } from "tgplus";
+
+const i18n = createI18n({
+  defaultLocale: "en",
+  locales: {
+    en: {
+      hi: (n: string) => `Hi ${n}!`,
+      apples: (n: number) => (n === 1 ? "1 apple" : `${n} apples`),
+      missing: "This one is a plain string",
+    },
+    fr: {
+      hi: (n: string) => `Salut ${n} !`,
+      apples: (n: number) => (n === 1 ? "1 pomme" : `${n} pommes`),
+    },
+  },
+  // Optional: resolve the locale yourself instead of using language_code
+  // getLocale: (ctx) => (ctx as any).session?.lang,
+});
+
+bot.use(i18n.middleware());
+
+bot.command("start", (ctx) => ctx.reply(ctx.t("hi", ctx.from?.first_name ?? "there")));
+bot.command("apples", (ctx) => ctx.reply(ctx.t("apples", 3)));
+bot.command("lang", (ctx) => ctx.reply(`Your locale: ${ctx.locale ?? "unknown"}`));
+// Unknown keys return the key itself instead of throwing
+```
+
+### 12. Entity & reaction filters
+
+Composable predicates used with `bot.on(filter())` or `bot.filter(...)`. Each maps to exactly one real Bot API entity type — they are deliberately not merged.
+
+```typescript
+import {
+  mention, hashtag, cashtag, url, textLink, textMention, phone, email,
+  botCommand, spoiler, customEmoji, reaction,
+} from "tgplus";
+
+bot.on(mention(), (ctx) => ctx.reply("A @username was mentioned."));         // entity: mention
+bot.on(textMention(), (ctx) => ctx.reply("Mentioned a user with no username.")); // entity: text_mention
+bot.on(hashtag(), (ctx) => ctx.reply("Nice hashtag."));                      // entity: hashtag
+bot.on(cashtag(), (ctx) => ctx.reply("Cashtag spotted."));                   // entity: cashtag
+bot.on(url(), (ctx) => ctx.reply("Plain URL in the text."));                 // entity: url
+bot.on(textLink(), (ctx) => ctx.reply("Labeled [link](url)."));              // entity: text_link
+bot.on(phone(), (ctx) => ctx.reply("That looks like a phone number."));      // entity: phone_number
+bot.on(email(), (ctx) => ctx.reply("That looks like an email."));            // entity: email
+bot.on(botCommand(), (ctx) => ctx.reply("A /command appeared."));            // entity: bot_command
+bot.on(spoiler(), (ctx) => ctx.reply("Spoiler content."));                   // entity: spoiler
+bot.on(customEmoji(), (ctx) => ctx.reply("Premium custom emoji."));          // entity: custom_emoji
+bot.on(reaction("🔥"), (ctx) => ctx.reply("Things are heating up."));        // message_reaction with 🔥
+bot.on(reaction(), (ctx) => ctx.reply("A reaction changed."));               // any reaction change
+
+// Filters are plain predicates — usable with bot.filter() too
+bot.filter(hashtag(), (ctx) => ctx.reply("Also a hashtag."));
+```
+
+### 13. File uploads & downloads
+
+Paths and Node streams are genuinely streamed through a hand-built multipart encoder (never fully buffered). Buffers use the proven `FormData` path.
+
+```typescript
+import fs from "node:fs";
+
+// ---------- Uploads ----------
+await ctx.replyWithPhoto({ source: "./photo.jpg" });                                   // local path
+await ctx.replyWithDocument({ source: fs.createReadStream("./big.zip"), filename: "big.zip" }); // stream
+await ctx.replyWithPhoto({ source: buffer, filename: "generated.png" });               // Buffer
+await ctx.replyWithVideo({ source: "./clip.mp4", filename: "clip.mp4" }, { caption: "Demo" });
+await ctx.replyWithAudio({ source: "./song.mp3" });
+await ctx.replyWithSticker({ source: "./cat.webp" });
+
+// Any send method accepts the same InputFile shape
+await bot.api.sendDocument({ chat_id: ctx.chatId!, document: { source: "./report.pdf" } });
+await bot.api.setChatPhoto({ chat_id: ctx.chatId!, photo: { source: "./icon.png" } });
+
+// ---------- Receiving files ----------
+bot.on("document", async (ctx) => {
+  const file = await bot.api.getFile({ file_id: ctx.message!.document!.file_id });
+  const url = await bot.api.getFileLink(file);   // resolves getFile() for you if you pass an id
+  console.log("Download:", url);
+});
+
+// Build a download URL directly from a known file_path
+const direct = bot.api.fileUrl("documents/file_12.pdf");
+```
+
+### 14. Composer gates, combinators & Router
+
+Gates restrict handlers by chat type or sender role. Note: a nested handler must come from the **static** `Composer` methods (the instance methods return the composer, not a middleware).
+
+```typescript
+import { Composer, Router } from "tgplus";
+
+// ---------- Gates ----------
+bot.privateChat(Composer.command("start", (ctx) => ctx.reply("Welcome!")));
+bot.groupChat(Composer.command("rules", (ctx) => ctx.reply("Be nice.")));
+bot.chatType("private", Composer.hears("hi", (ctx) => ctx.reply("Hi!")));
+bot.chatType(["group", "supergroup"], Composer.command("stats", (ctx) => ctx.reply("Stats…")));
+bot.admin(Composer.command("ban", (ctx) => ctx.reply("Banning…")));       // one getChatMember per matching update
+bot.creator(Composer.command("shutdown", (ctx) => ctx.reply("Shutting down…")));
+
+// ---------- Combinators ----------
+bot.filter((ctx) => ctx.chat?.type === "private", (ctx) => ctx.reply("private!"));
+bot.optional((ctx) => ctx.from?.id === 42, (ctx) => ctx.reply("Hello, 42."));   // alias for filter()
+bot.branch(
+  (ctx) => ctx.text === "vip",
+  (ctx) => ctx.reply("VIP path"),
+  [(ctx) => ctx.reply("Normal path")]
+);
+bot.lazy((ctx) => async (c) => c.reply(`Resolved at dispatch time: ${c.text}`));
+bot.otherwise((ctx) => ctx.reply("Fallback."));
+
+// ---------- Mount a whole sub-composer as a module ----------
+const adminModule = new Composer();
+adminModule.command("reload", (ctx) => ctx.reply("Reloading…"));
+bot.admin(adminModule.handle.bind(adminModule));
+bot.mount(adminModule);
+
+// ---------- Compose middlewares without a Composer instance ----------
+const composed = Composer.compose([
+  async (ctx, next) => { console.log("before"); await next(); },
+  async (ctx) => { await ctx.reply("after"); },
+]);
+bot.use(composed);
+
+// ---------- Router: key-based dispatch ----------
+const router = new Router((ctx) => (ctx as any).session?.lang);
+router.on("en", (ctx) => ctx.reply("Hi!"));
+router.on("fr", (ctx) => ctx.reply("Salut !"));
+router.otherwise((ctx) => ctx.reply("Hi! (set a language with /lang)"));
+bot.use(router.middleware());
+```
+
+### 15. Polling, webhooks & serverless
+
+```typescript
+// ---------- Long polling (default) ----------
+await bot.launch({ dropPendingUpdates: false, allowedUpdates: ["message", "callback_query"] });
+bot.stop(); // also wired to SIGINT/SIGTERM automatically
+
+// ---------- Standalone webhook server (sets the webhook and listens) ----------
+await bot.launchWebhook({
+  url: "https://your-domain.com",
+  port: 8080,
+  path: "/webhook",                       // default "/webhook"
+  secretToken: process.env.WEBHOOK_SECRET,
+});
+
+// ---------- Raw http — mount anywhere (Express/Fastify/Next custom server) ----------
+import http from "node:http";
+const server = http.createServer(bot.webhookCallback("/webhook", { secretToken: process.env.WEBHOOK_SECRET }));
+
+// ---------- Serverless adapters ----------
+import { vercelWebhookHandler, lambdaWebhookHandler, cloudflareWebhookHandler } from "tgplus";
+
+// Vercel (pages/api or app route handler)
+export default vercelWebhookHandler(bot, { secretToken: process.env.WEBHOOK_SECRET });
+
+// AWS Lambda behind API Gateway
+export const handler = lambdaWebhookHandler(bot, { secretToken: process.env.WEBHOOK_SECRET });
+
+// Cloudflare Workers
+export default { fetch: cloudflareWebhookHandler(bot, { secretToken: process.env.WEBHOOK_SECRET }) };
+
+// Or drive a parsed update yourself (bring your own framework)
+await bot.handleUpdate(update);
+```
+
+### 16. Context helpers
+
+Every helper auto-fills `chat_id` and resolves ids from the current update type.
+
+```typescript
+bot.on("text", async (ctx) => {
+  // Accessors
+  ctx.update; ctx.updateType; ctx.botInfo;
+  ctx.message; ctx.callbackQuery; ctx.inlineQuery;
+  ctx.chat; ctx.chatId; ctx.from; ctx.text; ctx.match; ctx.state;
+
+  // Sending
+  await ctx.reply("text");
+  await ctx.replyRich(RichMessage.markdown().text("rich").build());
+  await ctx.replyWithPhoto({ source: "./p.jpg" });
+  await ctx.replyWithVideo({ source: "./v.mp4" });
+  await ctx.replyWithDocument({ source: "./d.pdf" });
+  await ctx.replyWithAudio({ source: "./a.mp3" });
+  await ctx.replyWithSticker({ source: "./s.webp" });
+  await ctx.replyWithPoll("Pineapple on pizza?", ["Yes", "Obviously"], { is_anonymous: false });
+  await ctx.replyWithChatAction("typing");          // sendChatAction shortcut
+
+  // Editing / deleting the current message (or the message a button was attached to)
+  await ctx.editText("edited");
+  await ctx.editCaption("edited caption");
+  await ctx.editMedia({ type: "photo", media: { url: "https://picsum.photos/600" } });
+  await ctx.editReplyMarkup(Keyboard.inline().button("Again", "again").build());
+  await ctx.deleteMessage();                          // or ctx.deleteMessage(messageId)
+
+  // Callback/inline responses
+  if (ctx.callbackQuery) await ctx.answerCbQuery("Done");
+  if (ctx.inlineQuery) await ctx.answerInlineQuery([]);
+});
+```
+
+### 17. Typed API & escape hatch
+
+Every Bot API method has a typed, autocompleted wrapper. Anything Telegram ships next works immediately through `api.call()`.
+
+```typescript
+// Fully typed — parameters and return value
+const me = await bot.api.getMe();
+const sent = await bot.api.sendMessage({ chat_id: 42, text: "typed and autocompleted" });
+await bot.api.setChatPermissions({ chat_id: -100123, permissions: { can_send_messages: false } });
+await bot.api.setMyCommands({ commands: [{ command: "start", description: "Start the bot" }] });
+
+// Escape hatch — brand-new/undocumented methods, the same day Telegram ships them
+await bot.api.call("someBrandNewMethod", { chat_id: 42, whatever: true });
+const meToo = await bot.api.call<{ id: number }>("getMe");
+```
+
+### 18. Error handling
+
+Central handler for anything thrown in your handlers. API failures throw a typed `TelegramApiError`.
+
+```typescript
+import { TelegramApiError } from "tgplus";
+
+bot.catch((err, ctx) => {
+  console.error("Update failed:", ctx.updateType, err);
+  if (ctx.chat) ctx.reply("Something went wrong.").catch(() => {});
+});
+
+try {
+  await bot.api.sendMessage({ chat_id: 42, text: "hi" });
+} catch (err) {
+  if (err instanceof TelegramApiError) {
+    console.log(err.method, err.errorCode, err.message);  // "sendMessage", 403, "sendMessage failed (403): …"
+    if (err.errorCode === 403) { /* blocked */ }
+    if (err.parameters?.retry_after) { /* flood wait */ }
+    if (err.parameters?.migrate_to_chat_id) { /* group → supergroup migration */ }
+  }
+}
+```
+
+---
+
+## Every Class, With An Example
+
+Every class exported from `tgplus`, in one place.
+
+### `Bot` — `src/bot.ts`
+
+The entry point. `Bot` **extends `Composer`**, so every router/helper method is available directly on it. Holds `bot.api`.
+
+```typescript
+import { Bot } from "tgplus";
+
+const bot = new Bot(process.env.BOT_TOKEN!, {
+  contextType: MyContext,                 // optional: a Context subclass for extra helpers
+  apiRoot: "https://api.telegram.org",    // optional: local Bot API server
+  floodControl: { maxRetries: 5 },        // optional
+  minIntervalMs: 35,                      // optional
+});
+
+bot.command("start", (ctx) => ctx.reply("hi"));   // Composer methods
+bot.useController(new MainController());           // decorator controllers
+bot.catch((err, ctx) => console.error(err));       // central error handler
+await bot.launch();                                // long polling (SIGINT/SIGTERM safe)
+bot.stop();
+await bot.launchWebhook({ url, port, secretToken });
+const handler = bot.webhookCallback("/webhook", { secretToken });
+await bot.handleUpdate(update);                    // for your own serverless glue
+bot.api;                                           // the Api instance
+```
+
+### `Context` — `src/context.ts`
+
+One incoming update, with the accessors and reply/edit helpers people reach for constantly. See [Context helpers](#16-context-helpers) for the full method list.
+
+```typescript
+bot.on("text", (ctx) => {
+  ctx.message; ctx.chat; ctx.from; ctx.chatId; ctx.text; ctx.match;
+  ctx.update; ctx.updateType; ctx.api; ctx.botInfo; ctx.state;
+  ctx.session; ctx.scene; ctx.wizard; ctx.locale; ctx.t("key");
+  return ctx.reply("hello");
+});
+```
+
+### `Composer` — `src/composer.ts`
+
+The middleware engine. `use`, `mount`, `filter`, `on`, `command`, `hears`, `action`, `otherwise`, `chatType`, `privateChat`, `groupChat`, `admin`, `creator`, `optional`, `branch`, `lazy`, plus static `filter`/`on`/`command`/`hears`/`action`/`compose`. See [section 14](#14-composer-gates-combinators--router).
+
+```typescript
+import { Composer } from "tgplus";
+const module = new Composer<Context>();
+module.command("ping", (ctx) => ctx.reply("pong"));
+bot.mount(module);
+```
+
+### `Router` — `src/composer.ts`
+
+Key-based dispatch. Construct with a key function, register `on(key, …)`, optional `otherwise(…)`, then `bot.use(router.middleware())` (also `new Router<Context>((ctx) => ctx.session?.lang)`).
+
+```typescript
+const router = new Router<Context>((ctx) => (ctx.session as any)?.lang);
+router.on("en", (ctx) => ctx.reply("Hi!"));
+router.on("fr", (ctx) => ctx.reply("Salut !"));
+router.otherwise((ctx) => ctx.reply("Hi!"));
+bot.use(router.middleware());
+```
+
+### `Api` — `src/client.ts`
+
+All 187 typed Bot API methods, plus `call()` and `fileUrl()`. Reachable as `bot.api`, or constructed directly over a `Transport`.
+
+```typescript
+await bot.api.sendMessage({ chat_id: 42, text: "hi" });
+await bot.api.getMe();
+await bot.api.call("anyMethod", { … });
+bot.api.fileUrl("documents/file_12.pdf");
+await bot.api.getFileLink(fileIdOrFile);
+```
+
+### `Transport` — `src/client.ts`
+
+HTTP transport: JSON + streaming multipart, flood-control retries, optional pacing `minIntervalMs`, custom `apiRoot`. Exported for advanced use (custom clients/tests).
+
+```typescript
+import { Api, Transport } from "tgplus";
+
+const transport = new Transport(process.env.BOT_TOKEN!, {
+  apiRoot: "http://localhost:8081",   // e.g. a local Bot API server
+  floodControl: { maxRetries: 4 },
+  minIntervalMs: 50,
+});
+const api = new Api(transport);
+await api.sendMessage({ chat_id: 42, text: "via a custom transport" });
+transport.getFileDownloadUrl("documents/file_12.pdf");
+
+// Note: ClientOptions also declares `timeoutMs`, but it is currently accepted
+// and not applied to requests — don't rely on it for timeouts yet.
+```
+
+### `TelegramApiError` — `src/client.ts`
+
+Thrown by every API call on a non-`ok` response. Carries `method`, `errorCode`, and `parameters`.
+
+```typescript
+import { TelegramApiError } from "tgplus";
+
+try {
+  await bot.api.sendMessage({ chat_id: 42, text: "hi" });
+} catch (err) {
+  if (err instanceof TelegramApiError) {
+    err.method;                      // "sendMessage"
+    err.errorCode;                   // 400 | 403 | 429 | …
+    err.message;                     // "sendMessage failed (403): …"
+    err.parameters?.retry_after;     // 429 flood wait, seconds
+    err.parameters?.migrate_to_chat_id;
+  }
+}
+```
+
+### `Keyboard`, `InlineKeyboardBuilder`, `ReplyKeyboardBuilder` — `src/keyboard.ts`
+
+Fluent keyboard builders. See [section 2](#2-keyboard-builders).
+
+```typescript
+import { Keyboard, InlineKeyboardBuilder, ReplyKeyboardBuilder } from "tgplus";
+
+Keyboard.inline().button("Yes", "y").row().url("Docs", "https://x.dev").build();
+Keyboard.reply().text("Yes").row().requestLocation("Where?").build({ oneTime: true });
+Keyboard.remove();
+Keyboard.forceReply("Type here");
+
+const inline = new InlineKeyboardBuilder().button("A", "a").build();
+const reply = new ReplyKeyboardBuilder().text("A").build();
+```
+
+### `RichMessage`, `RichMarkdownBuilder`, `RichHtmlBuilder`, `RichBlocksBuilder` — `src/richMessage.ts`
+
+Rich Message builders. See [section 4](#4-rich-messages-bot-api-101103).
+
+```typescript
+import { RichMessage, RichMarkdownBuilder, RichHtmlBuilder, RichBlocksBuilder } from "tgplus";
+
+RichMessage.markdown(); RichMessage.html(); RichMessage.blocks();
+
+const md: RichMarkdownBuilder = new RichMarkdownBuilder();
+const html: RichHtmlBuilder = new RichHtmlBuilder();
+const blocks: RichBlocksBuilder = new RichBlocksBuilder();
+ctx.replyRich(md.text("Hello").build());
+```
+
+### `BotController`, `Command`, `Hears`, `Action`, `On` — `src/decorators.ts`
+
+Class-based controllers. See [section 6](#6-decorator-classes).
+
+```typescript
+import { BotController, Command, Hears, Action, On } from "tgplus";
+
+@BotController()
+class Controller {
+  @Command("start") start(ctx: Context) { return ctx.reply("hi"); }
+  @Hears(/^thanks$/i) thanks(ctx: Context) { return ctx.reply("yw"); }
+  @Action("like") like(ctx: Context) { return ctx.answerCbQuery("❤️"); }
+  @On("photo") photo(ctx: Context) { return ctx.reply("nice"); }
+}
+bot.useController(new Controller());
+```
+
+### `session`, `MemorySessionStore`, `RedisSessionStore`, `SqliteSessionStore` — `src/session*.ts`
+
+Session middleware and the three stores. See [section 8](#8-sessions).
+
+```typescript
+import { session, MemorySessionStore, RedisSessionStore, SqliteSessionStore } from "tgplus";
+
+session({ store, getSessionKey, defaultSession });
+new MemorySessionStore<{ count: number }>();
+new RedisSessionStore(new Redis(), { prefix: "mybot:session:", ttlSeconds: 86400 });
+new SqliteSessionStore(new Database("bot.db"), { tableName: "my_sessions" });
+
+// Custom store: implement SessionStore's get/set/delete
+import type { SessionStore } from "tgplus";
+const myStore: SessionStore<{ count: number }> = {
+  get: async (k) => undefined,
+  set: async (k, v) => {},
+  delete: async (k) => {},
+};
+```
+
+### `WizardScene`, `Stage` — `src/scenes.ts`
+
+Multi-step conversations. See [section 7](#7-scenes-multi-step-conversations).
+
+```typescript
+import { WizardScene, Stage } from "tgplus";
+
+const scene = new WizardScene<Context>("signup", [step1, step2, step3]);
+const stage = new Stage<Context>([scene]).register(anotherScene);
+bot.use(session());
+bot.use(stage.middleware());
+bot.command("signup", (ctx) => ctx.scene!.enter("signup", { from: "menu" }));
+```
+
+### `rateLimit` — `src/rateLimit.ts`
+
+Incoming-update limiter. See [section 9](#9-rate-limiting).
+
+```typescript
+import { rateLimit, RateLimitOptions } from "tgplus";
+
+const opts: RateLimitOptions = { windowMs: 3000, limit: 2, onLimitExceeded: (ctx) => ctx.reply("Slow down!") };
+bot.use(rateLimit(opts));
+```
+
+### `createI18n` — `src/i18n.ts`
+
+Locale middleware and `ctx.t()`. See [section 11](#11-i18n).
+
+```typescript
+import { createI18n } from "tgplus";
+
+const i18n = createI18n({ defaultLocale: "en", locales: { en: { hi: "Hi" }, fr: { hi: "Salut" } } });
+bot.use(i18n.middleware());
+i18n.translate("fr", "hi");
+ctx.t("hi");
+```
+
+### Serverless adapters — `src/adapters.ts`
+
+Vercel / Lambda / Cloudflare Workers request adapters. See [section 15](#15-polling-webhooks--serverless).
+
+```typescript
+import { vercelWebhookHandler, lambdaWebhookHandler, cloudflareWebhookHandler } from "tgplus";
+
+export default vercelWebhookHandler(bot, { secretToken });
+export const handler = lambdaWebhookHandler(bot, { secretToken });
+export default { fetch: cloudflareWebhookHandler(bot, { secretToken }) };
+```
+
+### Filters — `src/filters.ts`
+
+`mention`, `hashtag`, `cashtag`, `url`, `textLink`, `textMention`, `phone`, `email`, `botCommand`, `spoiler`, `customEmoji`, `reaction`. See [section 12](#12-entity--reaction-filters).
+
+```typescript
+import { mention, hashtag, reaction } from "tgplus";
+bot.on(mention(), (ctx) => ctx.reply("mentioned!"));
+bot.on(hashtag(), (ctx) => ctx.reply("hashtag!"));
+bot.on(reaction("👍"), (ctx) => ctx.reply("thanks!"));
+```
+
+### Types namespace — `src/types.ts`
+
+Every Bot API type is exported as `Types` (and used throughout the typed API).
+
+```typescript
+import { Types } from "tgplus";
+
+const update: Types.Update = { update_id: 1 };
+const file: Types.InputFile = { source: "./a.pdf", filename: "a.pdf" };
+const params: Types.SendMessageParams = { chat_id: 42, text: "hi" }; // where available
+```
+
+---
+
+## The Complete API Surface
+
+`bot.api` exposes **187 typed methods across 21 categories**, plus the `call()` escape hatch. Below: every category with an example, and the full method inventory.
+
+### Core
+
+```typescript
+await bot.api.call("anyMethod", { … });        // escape hatch, always current
+bot.api.fileUrl("documents/file_12.pdf");       // build a file download URL
+```
+
+`call`, `fileUrl`
+
+### Getting updates (7)
+
+```typescript
+const me = await bot.api.getMe();
+await bot.api.setWebhook({ url: "https://x.dev/hook", secret_token: "s", max_connections: 40, allowed_updates: ["message"], drop_pending_updates: true });
+const info = await bot.api.getWebhookInfo();
+await bot.api.deleteWebhook({ drop_pending_updates: true });
+const updates = await bot.api.getUpdates({ offset: 0, timeout: 30, limit: 100 });
+await bot.api.logOut();
+await bot.api.close();
+```
+
+`getMe`, `logOut`, `close`, `getUpdates`, `setWebhook`, `deleteWebhook`, `getWebhookInfo`
+
+### Sending messages (28)
+
+```typescript
+await bot.api.sendMessage({ chat_id, text: "hi", parse_mode: "Markdown", link_preview_options: { is_disabled: true } });
+await bot.api.sendMessageDraft({ chat_id: 42, draft_id: 1, text: "partial…" });         // streaming draft
+await bot.api.sendRichMessage({ chat_id, rich_message: RichMessage.markdown().text("hi").build() });
+await bot.api.sendRichMessageDraft({ chat_id: 42, draft_id: 1, rich_message: RichMessage.markdown().text("…").build() });
+
+await bot.api.forwardMessage({ chat_id, from_chat_id: -100, message_id: 5 });
+await bot.api.forwardMessages({ chat_id, from_chat_id: -100, message_ids: [5, 6] });
+await bot.api.copyMessage({ chat_id, from_chat_id: -100, message_id: 5 });
+await bot.api.copyMessages({ chat_id, from_chat_id: -100, message_ids: [5, 6] });
+
+await bot.api.sendPhoto({ chat_id, photo: { source: "./p.jpg" }, caption: "hi", has_spoiler: true });
+await bot.api.sendLivePhoto({ chat_id, live_photo: { source: "./lp.jpg" } });
+await bot.api.sendAudio({ chat_id, audio: { source: "./a.mp3" }, performer: "X", title: "Y" });
+await bot.api.sendDocument({ chat_id, document: { source: "./d.pdf" } });
+await bot.api.sendVideo({ chat_id, video: { source: "./v.mp4" }, supports_streaming: true });
+await bot.api.sendAnimation({ chat_id, animation: { source: "./l.gif" } });
+await bot.api.sendSticker({ chat_id, sticker: { source: "./s.webp" }, emoji: "🙂" });
+await bot.api.sendVoice({ chat_id, voice: { source: "./v.ogg" } });
+await bot.api.sendVideoNote({ chat_id, video_note: { source: "./note.mp4" } });
+await bot.api.sendMediaGroup({ chat_id, media: [{ type: "photo", media: "https://x.dev/1.jpg" }] });
+await bot.api.sendPaidMedia({ chat_id, star_count: 10, media: [{ type: "photo", media: "https://x.dev/p.jpg" }] });
+
+await bot.api.sendLocation({ chat_id, latitude: 51.5, longitude: -0.12 });
+await bot.api.editMessageLiveLocation({ chat_id, message_id: 5, latitude: 51.6, longitude: -0.13 });
+await bot.api.stopMessageLiveLocation({ chat_id, message_id: 5 });
+await bot.api.sendVenue({ chat_id, latitude: 51.5, longitude: -0.12, title: "Office", address: "1 Main St" });
+await bot.api.sendContact({ chat_id, phone_number: "+15551234", first_name: "Ada" });
+
+await bot.api.sendPoll({ chat_id, question: "Pizza?", options: ["Yes", "No"], is_anonymous: false });
+await bot.api.sendQuiz({ chat_id, question: "2+2?", options: ["3", "4"], correct_option_ids: [1] });
+await bot.api.sendDice({ chat_id, emoji: "🎲" });
+await bot.api.sendChatAction({ chat_id, action: "typing" });
+```
+
+`sendMessage`, `sendMessageDraft`, `sendRichMessage`, `sendRichMessageDraft`, `forwardMessage`, `forwardMessages`, `copyMessage`, `copyMessages`, `sendPhoto`, `sendLivePhoto`, `sendAudio`, `sendDocument`, `sendVideo`, `sendAnimation`, `sendSticker`, `sendVoice`, `sendVideoNote`, `sendMediaGroup`, `sendPaidMedia`, `sendLocation`, `editMessageLiveLocation`, `stopMessageLiveLocation`, `sendVenue`, `sendContact`, `sendPoll`, `sendQuiz`, `sendDice`, `sendChatAction`
+
+### Editing / deleting (7)
+
+```typescript
+await bot.api.editMessageText({ chat_id, message_id: 5, text: "edited", reply_markup: Keyboard.inline().button("x", "x").build() });
+await bot.api.editMessageCaption({ chat_id, message_id: 5, caption: "new caption" });
+await bot.api.editMessageMedia({ chat_id, message_id: 5, media: { type: "photo", media: "https://x.dev/new.jpg" } });
+await bot.api.editMessageReplyMarkup({ chat_id, message_id: 5, reply_markup: undefined });
+await bot.api.stopPoll({ chat_id, message_id: 5 });
+await bot.api.deleteMessage({ chat_id, message_id: 5 });
+await bot.api.deleteMessages({ chat_id, message_ids: [5, 6, 7] });
+```
+
+`editMessageText`, `editMessageCaption`, `editMessageMedia`, `editMessageReplyMarkup`, `stopPoll`, `deleteMessage`, `deleteMessages`
+
+### Ephemeral Messages (Bot API 10.2) (5)
+
+```typescript
+// Send an ephemeral message (visible only to one user) via any send method
+await bot.api.sendMessage({ chat_id, text: "only you see this", ephemeral_message_parameters: { receiver_user_id: 42 } as any });
+
+await bot.api.editEphemeralMessageText({ receiver_user_id: 42, chat_id, ephemeral_message_id: 5, text: "edited" });
+await bot.api.editEphemeralMessageMedia({ receiver_user_id: 42, chat_id, ephemeral_message_id: 5, media: { type: "photo", media: "https://x.dev/p.jpg" } });
+await bot.api.editEphemeralMessageCaption({ receiver_user_id: 42, chat_id, ephemeral_message_id: 5, caption: "cap" });
+await bot.api.editEphemeralMessageReplyMarkup({ receiver_user_id: 42, chat_id, ephemeral_message_id: 5, reply_markup: undefined });
+await bot.api.deleteEphemeralMessage({ receiver_user_id: 42, chat_id, ephemeral_message_id: 5 });
+```
+
+`editEphemeralMessageText`, `editEphemeralMessageMedia`, `editEphemeralMessageCaption`, `editEphemeralMessageReplyMarkup`, `deleteEphemeralMessage`
+
+### Files (3)
+
+```typescript
+const file = await bot.api.getFile({ file_id: "AgAC…" });
+const url = await bot.api.getFileLink(file);                 // or pass the file_id directly
+await bot.api.getUserProfilePhotos({ user_id: 42, limit: 10 });
+await bot.api.getUserProfileAudios({ user_id: 42, limit: 10 });
+```
+
+`getFile`, `getFileLink`, `getUserProfilePhotos`, `getUserProfileAudios`
+
+### Chat administration (35)
+
+```typescript
+await bot.api.banChatMember({ chat_id, user_id: 42, revoke_messages: true });
+await bot.api.unbanChatMember({ chat_id, user_id: 42 });
+await bot.api.restrictChatMember({ chat_id, user_id: 42, permissions: { can_send_messages: false } });
+await bot.api.promoteChatMember({ chat_id, user_id: 42, can_delete_messages: true, can_send_welcome_messages: true });
+await bot.api.setChatAdministratorCustomTitle({ chat_id, user_id: 42, custom_title: "Moderator" });
+await bot.api.setChatMemberTag({ chat_id, user_id: 42, tag: "vip" });
+await bot.api.banChatSenderChat({ chat_id, sender_chat_id: -1009 });
+await bot.api.unbanChatSenderChat({ chat_id, sender_chat_id: -1009 });
+await bot.api.setChatPermissions({ chat_id, permissions: { can_send_messages: false } });
+
+const link = await bot.api.exportChatInviteLink({ chat_id });
+await bot.api.createChatInviteLink({ chat_id, name: "campaign", member_limit: 100 });
+await bot.api.editChatInviteLink({ chat_id, invite_link: link, name: "renamed" });
+await bot.api.revokeChatInviteLink({ chat_id, invite_link: link });
+await bot.api.approveChatJoinRequest({ chat_id, user_id: 42 });
+await bot.api.declineChatJoinRequest({ chat_id, user_id: 42 });
+await bot.api.answerChatJoinRequestQuery({ query_id: "q", approve: true });
+await bot.api.sendChatJoinRequestWebApp({ query_id: "q", web_app: { url: "https://x.dev/app" } });
+
+await bot.api.setChatPhoto({ chat_id, photo: { source: "./icon.png" } });
+await bot.api.deleteChatPhoto({ chat_id });
+await bot.api.setChatTitle({ chat_id, title: "New title" });
+await bot.api.setChatDescription({ chat_id, description: "New description" });
+await bot.api.pinChatMessage({ chat_id, message_id: 5 });
+await bot.api.unpinChatMessage({ chat_id, message_id: 5 });
+await bot.api.unpinAllChatMessages({ chat_id });
+await bot.api.leaveChat({ chat_id });
+
+const chat = await bot.api.getChat({ chat_id });
+const admins = await bot.api.getChatAdministrators({ chat_id, return_bots: true });
+const count = await bot.api.getChatMemberCount({ chat_id });
+const member = await bot.api.getChatMember({ chat_id, user_id: 42 });
+await bot.api.setChatStickerSet({ chat_id, sticker_set_name: "my_set" });
+await bot.api.deleteChatStickerSet({ chat_id });
+await bot.api.setMessageReaction({ chat_id, message_id: 5, reaction: [{ type: "emoji", emoji: "👍" }] });
+await bot.api.deleteAllMessageReactions({ chat_id, message_id: 5 });
+await bot.api.deleteMessageReaction({ chat_id, message_id: 5, user_id: 42 });
+await bot.api.getUserChatBoosts({ chat_id, user_id: 42 });
+```
+
+`banChatMember`, `unbanChatMember`, `restrictChatMember`, `promoteChatMember`, `setChatAdministratorCustomTitle`, `setChatMemberTag`, `banChatSenderChat`, `unbanChatSenderChat`, `setChatPermissions`, `exportChatInviteLink`, `createChatInviteLink`, `editChatInviteLink`, `revokeChatInviteLink`, `approveChatJoinRequest`, `declineChatJoinRequest`, `answerChatJoinRequestQuery`, `sendChatJoinRequestWebApp`, `setChatPhoto`, `deleteChatPhoto`, `setChatTitle`, `setChatDescription`, `pinChatMessage`, `unpinChatMessage`, `unpinAllChatMessages`, `leaveChat`, `getChat`, `getChatAdministrators`, `getChatMemberCount`, `getChatMember`, `setChatStickerSet`, `deleteChatStickerSet`, `setMessageReaction`, `deleteAllMessageReactions`, `deleteMessageReaction`, `getUserChatBoosts`
+
+### Forum topics (13)
+
+```typescript
+const icons = await bot.api.getForumTopicIconStickers();
+const topic = await bot.api.createForumTopic({ chat_id, name: "Support", icon_color: 0x6FB9F0 });
+await bot.api.editForumTopic({ chat_id, message_thread_id: topic.message_thread_id, name: "Renamed" });
+await bot.api.closeForumTopic({ chat_id, message_thread_id: topic.message_thread_id });
+await bot.api.reopenForumTopic({ chat_id, message_thread_id: topic.message_thread_id });
+await bot.api.deleteForumTopic({ chat_id, message_thread_id: topic.message_thread_id });
+await bot.api.unpinAllForumTopicMessages({ chat_id, message_thread_id: topic.message_thread_id });
+
+await bot.api.editGeneralForumTopic({ chat_id, name: "General renamed" });
+await bot.api.closeGeneralForumTopic({ chat_id });
+await bot.api.reopenGeneralForumTopic({ chat_id });
+await bot.api.hideGeneralForumTopic({ chat_id });
+await bot.api.unhideGeneralForumTopic({ chat_id });
+await bot.api.unpinAllGeneralForumTopicMessages({ chat_id });
+```
+
+`getForumTopicIconStickers`, `createForumTopic`, `editForumTopic`, `closeForumTopic`, `reopenForumTopic`, `deleteForumTopic`, `unpinAllForumTopicMessages`, `editGeneralForumTopic`, `closeGeneralForumTopic`, `reopenGeneralForumTopic`, `hideGeneralForumTopic`, `unhideGeneralForumTopic`, `unpinAllGeneralForumTopicMessages`
+
+### Bot profile / commands / menu (17)
+
+```typescript
+await bot.api.setMyCommands({ commands: [{ command: "start", description: "Start" }], scope: { type: "default" }, language_code: "en" });
+const commands = await bot.api.getMyCommands();
+await bot.api.deleteMyCommands();
+
+await bot.api.setChatMenuButton({ menu_button: { type: "commands" } });
+await bot.api.getChatMenuButton();
+await bot.api.setMyDefaultAdministratorRights({ rights: { can_delete_messages: true }, for_channels: false });
+await bot.api.getMyDefaultAdministratorRights();
+
+await bot.api.setMyName({ name: "My Bot" });
+await bot.api.getMyName();
+await bot.api.setMyDescription({ description: "A helpful bot." });
+await bot.api.getMyDescription();
+await bot.api.setMyShortDescription({ short_description: "Helpful." });
+await bot.api.getMyShortDescription();
+await bot.api.setMyProfilePhoto({ photo: { source: "./avatar.png" } });
+await bot.api.removeMyProfilePhoto();
+await bot.api.setUserEmojiStatus({ user_id: 42, emoji_status_custom_emoji_id: "5368…" });
+await bot.api.setPassportDataErrors({ user_id: 42, errors: [] });
+```
+
+`setMyCommands`, `deleteMyCommands`, `getMyCommands`, `setChatMenuButton`, `getChatMenuButton`, `setMyDefaultAdministratorRights`, `getMyDefaultAdministratorRights`, `setMyName`, `getMyName`, `setMyDescription`, `getMyDescription`, `setMyShortDescription`, `getMyShortDescription`, `setMyProfilePhoto`, `removeMyProfilePhoto`, `setUserEmojiStatus`, `setPassportDataErrors`
+
+### Callback / inline queries (6)
+
+```typescript
+await bot.api.answerCallbackQuery({ callback_query_id: "cb1", text: "Done", show_alert: false });
+await bot.api.answerGameQuery({ callback_query_id: "cb1", url: "https://game.example" });
+await bot.api.answerInlineQuery({ inline_query_id: "iq1", results: [], cache_time: 5, is_personal: true });
+await bot.api.answerWebAppQuery({ web_app_query_id: "wa1", result: { type: "article", id: "1", title: "T", input_message_content: { message_text: "hi" } } });
+await bot.api.savePreparedInlineMessage({ user_id: 42, result: { type: "article", id: "1", title: "T", input_message_content: { message_text: "hi" } } });
+await bot.api.savePreparedKeyboardButton({ user_id: 42, button: { text: "Create bot" } as any });
+```
+
+`answerCallbackQuery`, `answerGameQuery`, `answerInlineQuery`, `answerWebAppQuery`, `savePreparedInlineMessage`, `savePreparedKeyboardButton`
+
+### Payments (4)
+
+```typescript
+await bot.api.sendInvoice({
+  chat_id, title: "Pro", description: "Monthly", payload: "order-1", currency: "USD",
+  prices: [{ label: "Pro", amount: 500 }],
+});
+const invoiceLink = await bot.api.createInvoiceLink({ title: "Pro", description: "Monthly", payload: "order-1", currency: "USD", prices: [{ label: "Pro", amount: 500 }] });
+await bot.api.answerShippingQuery({ shipping_query_id: "sq1", ok: true });
+await bot.api.answerPreCheckoutQuery({ pre_checkout_query_id: "pc1", ok: true });
+```
+
+`sendInvoice`, `createInvoiceLink`, `answerShippingQuery`, `answerPreCheckoutQuery`
+
+### Stickers (14)
+
+```typescript
+const set = await bot.api.getStickerSet({ name: "my_set" });
+await bot.api.getCustomEmojiStickers({ custom_emoji_ids: ["5368…"] });
+const uploaded = await bot.api.uploadStickerFile({ user_id: 42, sticker: { source: "./s.png" }, sticker_format: "static" });
+await bot.api.createNewStickerSet({ user_id: 42, name: "my_set_by_bot", title: "My Set", stickers: [{ sticker: uploaded.file_id, format: "static", emoji_list: ["🙂"] }] });
+await bot.api.addStickerToSet({ user_id: 42, name: "my_set_by_bot", sticker: { sticker: "file_id", format: "static", emoji_list: ["🙂"] } });
+await bot.api.setStickerPositionInSet({ sticker: "file_id", position: 0 });
+await bot.api.deleteStickerFromSet({ sticker: "file_id" });
+await bot.api.setStickerEmojiList({ sticker: "file_id", emoji_list: ["🙂"] });
+await bot.api.setStickerKeywords({ sticker: "file_id", keywords: ["happy"] });
+await bot.api.setStickerMaskPosition({ sticker: "file_id" });
+await bot.api.setStickerSetTitle({ name: "my_set_by_bot", title: "Renamed" });
+await bot.api.setStickerSetThumbnail({ name: "my_set_by_bot", user_id: 42, format: "static" });
+await bot.api.setCustomEmojiStickerSetThumbnail({ name: "my_set_by_bot", custom_emoji_id: "5368…" });
+await bot.api.deleteStickerSet({ name: "my_set_by_bot" });
+```
+
+`getStickerSet`, `getCustomEmojiStickers`, `uploadStickerFile`, `createNewStickerSet`, `addStickerToSet`, `setStickerPositionInSet`, `deleteStickerFromSet`, `setStickerEmojiList`, `setStickerKeywords`, `setStickerMaskPosition`, `setStickerSetTitle`, `setStickerSetThumbnail`, `setCustomEmojiStickerSetThumbnail`, `deleteStickerSet`
+
+### Games (3)
+
+```typescript
+await bot.api.sendGame({ chat_id, game_short_name: "my_game" });
+await bot.api.setGameScore({ user_id: 42, score: 9001, chat_id, message_id: 5 });
+const scores = await bot.api.getGameHighScores({ user_id: 42, chat_id, message_id: 5 });
+```
+
+`sendGame`, `setGameScore`, `getGameHighScores`
+
+### Checklists (Bot API 9.1) (2)
+
+```typescript
+// Checklists are sent/edited on behalf of a business account only
+await bot.api.sendChecklist({ business_connection_id: "bc1", chat_id, checklist: { title: "Todo", tasks: [] } as any });
+await bot.api.editMessageChecklist({ business_connection_id: "bc1", chat_id, message_id: 5, checklist: { title: "Todo", tasks: [] } as any });
+```
+
+`sendChecklist`, `editMessageChecklist`
+
+### Business accounts (21)
+
+```typescript
+const conn = await bot.api.getBusinessConnection({ business_connection_id: "bc1" });
+await bot.api.readBusinessMessage({ business_connection_id: "bc1", chat_id, message_id: 5 });
+await bot.api.deleteBusinessMessages({ business_connection_id: "bc1", message_ids: [5] });
+await bot.api.setBusinessAccountName({ business_connection_id: "bc1", first_name: "Shop" });
+await bot.api.setBusinessAccountUsername({ business_connection_id: "bc1", username: "myshop" });
+await bot.api.setBusinessAccountBio({ business_connection_id: "bc1", bio: "We sell things." });
+await bot.api.setBusinessAccountProfilePhoto({ business_connection_id: "bc1", photo: { source: "./logo.png" } });
+await bot.api.removeBusinessAccountProfilePhoto({ business_connection_id: "bc1" });
+await bot.api.setBusinessAccountGiftSettings({ business_connection_id: "bc1", show_gift_button: true, accepted_gift_types: {} as any });
+const balance = await bot.api.getBusinessAccountStarBalance({ business_connection_id: "bc1" });
+await bot.api.transferBusinessAccountStars({ business_connection_id: "bc1", star_count: 100 });
+const gifts = await bot.api.getBusinessAccountGifts({ business_connection_id: "bc1", limit: 20 });
+await bot.api.getUserGifts({ user_id: 42 });
+await bot.api.getChatGifts({ chat_id });
+await bot.api.convertGiftToStars({ business_connection_id: "bc1", owned_gift_id: "g1" });
+await bot.api.upgradeGift({ business_connection_id: "bc1", owned_gift_id: "g1", star_count: 50 });
+await bot.api.transferGift({ business_connection_id: "bc1", owned_gift_id: "g1", new_owner_chat_id: 43 });
+const story = await bot.api.postStory({ business_connection_id: "bc1", content: { type: "photo", photo: "https://x.dev/s.jpg" } as any, active_period: 86400 });
+await bot.api.editStory({ business_connection_id: "bc1", story_id: story.id, content: { type: "photo", photo: "https://x.dev/s2.jpg" } as any });
+await bot.api.deleteStory({ business_connection_id: "bc1", story_id: story.id });
+await bot.api.repostStory({ business_connection_id: "bc1", story_id: story.id });
+```
+
+`getBusinessConnection`, `readBusinessMessage`, `deleteBusinessMessages`, `setBusinessAccountName`, `setBusinessAccountUsername`, `setBusinessAccountBio`, `setBusinessAccountProfilePhoto`, `removeBusinessAccountProfilePhoto`, `setBusinessAccountGiftSettings`, `getBusinessAccountStarBalance`, `transferBusinessAccountStars`, `getBusinessAccountGifts`, `getUserGifts`, `getChatGifts`, `convertGiftToStars`, `upgradeGift`, `transferGift`, `postStory`, `editStory`, `deleteStory`, `repostStory`
+
+### Verification (Bot API 8.2+) (4)
+
+```typescript
+await bot.api.verifyUser({ user_id: 42, custom_description: "Verified member" });
+await bot.api.verifyChat({ chat_id, custom_description: "Official" });
+await bot.api.removeUserVerification({ user_id: 42 });
+await bot.api.removeChatVerification({ chat_id });
+```
+
+`verifyUser`, `verifyChat`, `removeUserVerification`, `removeChatVerification`
+
+### Gifts (Bot API 8.0+) (3)
+
+```typescript
+const available = await bot.api.getAvailableGifts();
+await bot.api.sendGift({ gift_id: "gift-1", user_id: 42, text: "Enjoy!" });
+await bot.api.giftPremiumSubscription({ user_id: 42, month_count: 3, star_count: 100 });
+```
+
+`getAvailableGifts`, `sendGift`, `giftPremiumSubscription`
+
+### Stars & Payments transactions (Bot API 7.4+) (4)
+
+```typescript
+const txns = await bot.api.getStarTransactions({ limit: 50 });
+const mine = await bot.api.getMyStarBalance();
+await bot.api.refundStarPayment({ user_id: 42, telegram_payment_charge_id: "charge-1" });
+await bot.api.editUserStarSubscription({ user_id: 42, telegram_payment_charge_id: "charge-1", is_canceled: true });
+```
+
+`getStarTransactions`, `getMyStarBalance`, `refundStarPayment`, `editUserStarSubscription`
+
+### Suggested Posts / Direct Messages in Channels (Bot API 9.2+) (2)
+
+```typescript
+// Turn a send into a suggested post via sendMessage's suggested_post_parameters, then approve/decline
+await bot.api.sendMessage({ chat_id, text: "Draft post", suggested_post_parameters: { send_date: 0 } as any });
+await bot.api.approveSuggestedPost({ chat_id, message_id: 5 });
+await bot.api.declineSuggestedPost({ chat_id, message_id: 5, comment: "Not now" });
+```
+
+`approveSuggestedPost`, `declineSuggestedPost`
+
+### Guest mode (Bot API 10.0+) (1)
+
+```typescript
+// Respond to a guest_message update (bots mentioned/queried with no direct relationship)
+await bot.api.answerGuestQuery({ guest_query_id: "gq1", result: { type: "article", id: "1", title: "T", input_message_content: { message_text: "hi" } } });
+```
+
+`answerGuestQuery`
+
+### Managed Bots (Bot API 9.5/9.6) (5)
+
+```typescript
+const { token } = await bot.api.getManagedBotToken({ bot_id: 123 });
+const replaced = await bot.api.replaceManagedBotToken({ bot_id: 123 });
+const settings = await bot.api.getManagedBotAccessSettings({ bot_id: 123 });
+await bot.api.setManagedBotAccessSettings({ bot_id: 123, access_settings: settings });
+const personal = await bot.api.getUserPersonalChatMessages({ user_id: 42, limit: 20 });
+```
+
+`getManagedBotToken`, `replaceManagedBotToken`, `getManagedBotAccessSettings`, `setManagedBotAccessSettings`, `getUserPersonalChatMessages`
+
+---
+
+## Coverage Confidence
+
+Honest, area-by-area — so you know where to double-check before relying on something:
+
+| Area | Confidence | How it was verified |
+|---|---|---|
+| Core messaging, chat admin, forum topics, stickers, games, payments | High | Diffed against telegraf's published method list |
+| Inline mode (`InlineQueryResult` — all 20 variants), Telegram Passport | High | Field-by-field against python-telegram-bot's generated docs |
+| `ReplyParameters`, polls, reactions, chat boosts | High | Cross-checked directly against the official Bot API changelog |
+| Rich Messages (`RichBlock`/`RichText` — 21 + 25 variants) | High | Field-by-field against a community reference + the official changelog |
+| Ephemeral Messages, Communities (Bot API 10.2/10.3) | High | Verified against the official changelog the same day it shipped |
+| Gifts, Stars transactions, Business accounts | High | Field-by-field against python-telegram-bot's generated docs |
+| `ChatBackground`/`BackgroundType`/`BackgroundFill` | High | Stable schema, cross-checked against generated docs |
+| Checklists, Guest mode, Suggested Posts | Medium | Top-level shapes confirmed via changelog; some nested fields inferred |
+| `StoryArea`/`InputStoryContent` (Business Stories) | Medium-low | General structure confirmed via changelog mentions only |
+| `sendMessageDraft` (plain-text streaming) | Medium | Implemented from its changelog entry; parameter shape modeled on the field-verified `sendRichMessageDraft` |
+| `UniqueGiftColors`, `GiftBackground`, `UserRating` | Low, explicitly | Confirmed to exist; field names inferred from a sibling type's pattern, not verified. Flagged in `types.ts`'s JSDoc. |
+| `getManagedBotToken`/`replaceManagedBotToken`, `answerGuestQuery` | Lower | Implemented from the changelog alone, not cross-checked against a second source |
+
+Every method's parameters and return values are backed by a named, field-checked type — the remaining `Record<string, unknown>` occurrences in `client.ts` are internal transport plumbing (multipart encoding), not API surface. The auto-generated reference at `docs/api-reference.html` is parsed straight out of `src/client.ts` (`npm run docs:api`), so it cannot silently drift.
+
+---
+
+## Project Layout
+
+```
+src/
+  types.ts           Telegram Bot API type definitions (Bot API 7.0-10.3)
+  client.ts          Transport (HTTP + multipart + flood control) + typed API surface (187 methods)
+  context.ts         Context — fluent ctx.reply()/ctx.editText()/etc.
+  composer.ts        Middleware engine: use/on/command/hears/action/branch/lazy/Router
+  keyboard.ts        Fluent inline/reply keyboard builders
+  richMessage.ts     Rich Message builders — markdown/html text or structured blocks (10.3)
+  decorators.ts      @Command/@Hears/@Action/@On class decorators
+  session.ts         session() middleware + MemorySessionStore
+  session-redis.ts   RedisSessionStore (duck-typed against any Redis client)
+  session-sqlite.ts  SqliteSessionStore (duck-typed against better-sqlite3)
+  scenes.ts          WizardScene + Stage — multi-step conversations
+  rateLimit.ts       Per-chat/user rate limiting middleware
+  i18n.ts            Minimal i18n (translate by Telegram language_code)
+  filters.ts         Entity & reaction filters (mention(), hashtag(), reaction(), …)
+  adapters.ts        Vercel / Lambda / Cloudflare Workers webhook handlers
+  bot.ts             Bot — polling, webhook, ties it all together
+examples/
+  basic.ts             router style
+  fluent.ts            keyboard/rich-message + webhook example
+  decorators.ts        class-based style
+  scenes.ts            multi-step signup flow
+  pterodactyl-bot.ts   real-world example: a Pterodactyl panel control bot
+test/
+  *.test.ts            106 tests — Composer, Context, Scenes, Keyboard, RichMessage,
+                        i18n, rateLimit, adapters, decorators, Transport flood control
+  decorator-smoke/      real @Command syntax, compiled by real tsc, run with plain node
+  smoke.plain-js.test.js  plain-require() proof the compiled output works with zero TS
+docs/
+  index.html           full documentation site
+  api-reference.html   auto-generated API reference (npm run docs:api)
+```
+
+---
+
+## Testing
+
+```bash
+npm test
+```
+
+Runs, in order: a real `tsc` build to `dist/`, 106 unit/integration tests via Node's
+built-in test runner, a plain-JavaScript smoke test proving the compiled output
+works with zero TypeScript involved, and a real-decorator-syntax smoke test
+(isolated `tsc` compile + plain `node`, proving legacy decorators work end-to-end
+for real consumers — `tsx`, used for the fast test suite, doesn't honor
+`experimentalDecorators`, which is a test-runner quirk, not a library bug; see
+`test/decorators.test.ts`'s comment for the full explanation).
+
+```bash
+npm run docs:api   # regenerate docs/api-reference.html from src/client.ts
+```
+
+**Not covered by `npm test`:** an actual live run against Telegram's real servers.
+See [Status](#status).
+
+---
+
+## Status
+
+### Verified
+- Full build pipeline (`tsc` → 106 tests → JS smoke test → real-decorator smoke test)
+- Core method coverage diffed against telegraf v4's actual published method list
+- Newer areas verified against the official changelog directly
+- **Live-tested against real Telegram servers**: `getMe()`, `getWebhookInfo()`, and the
+  core happy path (commands, inline keyboards, callback queries, `hears()` matching,
+  text echo, photo receipt) confirmed working end-to-end via real long polling
+- Three real bugs found and fixed by porting an actual working bot into tgplus
+  (see `CHANGELOG.md`'s 0.2.0 entry) — `ctx.editText()`/`ctx.deleteMessage()` from
+  callback_query handlers, and `ctx.chat`/`ctx.from` missing several update types
+
+### Not yet verified
+- Webhook mode (code is there, not live-tested)
+- Scenes/sessions in a live multi-turn conversation
+- File uploads (sending a Buffer via `sendPhoto`/`sendDocument`)
+- Streaming drafts (`sendMessageDraft`/`sendRichMessageDraft`) against a real server
+- Newer/lower-confidence feature areas (Rich Messages, Ephemeral Messages, Gifts,
+  Stars, Business accounts) — sent to mocked `fetch` in tests, never a real server
+- Production mileage or community — telegraf and aiogram have years of real-world
+  edge cases already found and fixed; that only comes from real usage over time,
+  and can't be written in ahead of time
+
+CI runs the full suite on every push (Node 18/20/22) — see `.github/workflows/test.yml`.
+
+---
+
+## Contributing
+
+Issues and PRs welcome. Given how new this project is, the most valuable
+contribution right now is simply **using it and reporting what breaks** —
+see "Not yet verified" above for where the real risk currently is.
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/thing`)
+3. `npm test` before committing
+4. Open a PR
+
+---
+
+## Credits
+
+tgplus is developed and maintained by **[@crysnovax](https://github.com/crysnovax)**.
+
+tgplus builds on the original work of **[@ayo](https://github.com/AyoFemi10)** —
+all credit for the original design and implementation belongs to @ayo.
+
+## License
+
+**Proprietary — All Rights Reserved.** See [LICENSE](LICENSE).
+
+This package is not open source. No permission is granted to use, reproduce,
+distribute, modify, or commercially exploit this software, in whole or in part,
+without prior written permission from the author.