@xbibzlibrary/telebibz 0.3.2 → 0.4.1

package/dist-cjs/src/core/bot.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Bot = void 0;
+exports.Bot = exports.UpdateTimeoutError = void 0;
 const client_js_1 = require("../api/client.js");
 const transport_js_1 = require("../api/transport.js");
 const context_js_1 = require("../context/context.js");
@@ -14,6 +14,17 @@ const terminal_js_1 = require("../branding/terminal.js");
 const conversation_js_1 = require("../state/conversation.js");
 const broadcast_js_1 = require("../broadcast/broadcast.js");
 const concurrency_js_1 = require("../utils/concurrency.js");
+const webhook_reply_js_1 = require("./webhook-reply.js");
+/** Thrown when a single update exceeds `handlerTimeout`; the handler keeps running in the background. */
+class UpdateTimeoutError extends Error {
+    name = "UpdateTimeoutError";
+    updateId;
+    constructor(updateId, timeoutMs) {
+        super(`Update ${updateId} handler timed out after ${timeoutMs}ms`);
+        this.updateId = updateId;
+    }
+}
+exports.UpdateTimeoutError = UpdateTimeoutError;
 class Bot {
     api;
     router;
@@ -31,6 +42,10 @@ class Bot {
     me;
     /** Caps how many updates run at once (default: unlimited). */
     updateLimiter;
+    /** Per-update timeout in ms; `Infinity` disables. */
+    handlerTimeoutMs;
+    /** Context class instantiated per update (default `Context`). */
+    contextType;
     /** Per-chat processing chains: parallel across chats, ordered within a chat. */
     chatChains = new Map();
     /** Memoized init so a burst of updates triggers exactly one getMe call. */
@@ -62,6 +77,8 @@ class Bot {
         });
         this.plugins = new plugin_js_1.PluginManager(this);
         this.updateLimiter = new concurrency_js_1.Limiter(config.updates?.concurrency ?? Infinity);
+        this.handlerTimeoutMs = config.handlerTimeout ?? 90_000;
+        this.contextType = config.contextType ?? context_js_1.Context;
         this.pollingOptions = {
             allowedUpdates: config.polling?.allowedUpdates ?? [],
             limit: config.polling?.limit ?? 100,
@@ -155,7 +172,7 @@ class Bot {
             throw error;
         }
     }
-    async start() { await this.launch({ mode: "polling" }); }
+    async start(options = {}) { await this.launch({ mode: "polling", ...options }); }
     async launch(options = { mode: "polling" }) {
         if (options.mode !== "polling")
             throw new Error("Use createWebhookHandler() for webhook mode.");
@@ -180,6 +197,11 @@ class Bot {
         }
         if (this.statusValue === "running")
             return;
+        if (options.dropPendingUpdates) {
+            // Same mechanism Telegraf uses: drop everything Telegram is holding for
+            // this bot before the first getUpdates call.
+            await this.api.call("deleteWebhook", { drop_pending_updates: true });
+        }
         this.statusValue = "starting";
         this.startupLog("bot.starting", { mode: options.mode });
         await this.events.emit("bot:starting", { bot: this });
@@ -224,18 +246,60 @@ class Bot {
      * updates for the same chat are processed strictly in arrival order so
      * sessions, wizards, and conversations never interleave. Rejects for this
      * update's failure (as before) without affecting other updates.
+     *
+     * `options.webhookReply` installs a Telegraf-style responder: the first
+     * outgoing API call during this update is answered through the webhook HTTP
+     * response instead of a separate request, and resolves with `true` because
+     * Telegram never sends the method result back to a webhook response.
      */
-    async handleUpdate(update) {
+    async handleUpdate(update, options = {}) {
         const key = this.conversationKey(update);
         const previous = this.chatChains.get(key);
-        const run = (previous ?? Promise.resolve()).catch(() => undefined).then(() => this.processUpdate(update));
+        const execute = options.webhookReply === undefined
+            ? () => this.processUpdate(update)
+            : () => (0, webhook_reply_js_1.runWithWebhookReply)(options.webhookReply, () => this.processUpdate(update));
+        // The chain waits for the real completion so same-chat ordering holds
+        // even when the caller-facing await below is released by a timeout.
+        const run = (previous ?? Promise.resolve()).catch(() => undefined).then(execute);
         const tail = run.then(() => undefined, () => undefined);
         this.chatChains.set(key, tail);
         void tail.then(() => {
             if (this.chatChains.get(key) === tail)
                 this.chatChains.delete(key);
         });
-        await run;
+        try {
+            await this.withTimeout(run, this.handlerTimeoutMs, update.update_id);
+        }
+        catch (error) {
+            if (!(error instanceof UpdateTimeoutError))
+                throw error;
+            // A timed-out update follows the same error flow as a failed handler;
+            // the handler itself keeps running to completion in the background.
+            this.logger.error("update.handler_timeout", { updateId: update.update_id, timeoutMs: this.handlerTimeoutMs });
+            await this.events.emit("update:error", { update, error });
+            await this.events.emit("bot:error", { bot: this, error });
+            if (this.errorHandler) {
+                await this.errorHandler(error, new context_js_1.Context({ update, api: this.api, session: {}, services: this.services, me: this.me }));
+                return;
+            }
+            throw error;
+        }
+    }
+    /** Rejects with `UpdateTimeoutError` after `timeoutMs` unless `promise` settles first. */
+    async withTimeout(promise, timeoutMs, updateId) {
+        if (!Number.isFinite(timeoutMs))
+            return promise;
+        let timer;
+        const timeout = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new UpdateTimeoutError(updateId, timeoutMs)), timeoutMs);
+        });
+        try {
+            return await Promise.race([promise, timeout]);
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
     }
     /**
      * Handles a whole batch of updates at once: every chat in the batch is
@@ -265,12 +329,12 @@ class Bot {
     async broadcast(chatIds, send, options) {
         return (0, broadcast_js_1.runBroadcast)(chatIds, send, options);
     }
-    /** Runs init() once even when many updates arrive concurrently. */
+    /** Runs init() once even when many updates arrive concurrently; never claims a webhook reply slot. */
     ensureInitialized() {
         if (this.me)
             return Promise.resolve();
         if (!this.initOnce) {
-            this.initOnce = this.init().then(() => { this.initOnce = undefined; }, (error) => {
+            this.initOnce = (0, webhook_reply_js_1.runWithoutWebhookReply)(() => this.init()).then(() => { this.initOnce = undefined; }, (error) => {
                 this.initOnce = undefined;
                 throw error;
             });
@@ -296,7 +360,7 @@ class Bot {
             await this.ensureInitialized();
         if (!this.me)
             return;
-        const ctx = new context_js_1.Context({ update, api: this.api, session, services: this.services, me: this.me });
+        const ctx = new this.contextType({ update, api: this.api, session, services: this.services, me: this.me });
         await this.events.emit("update", { update });
         if (message) {
             await this.events.emit("message", { message });

package/dist-cjs/src/core/webhook-reply.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runWithWebhookReply = runWithWebhookReply;
+exports.runWithoutWebhookReply = runWithoutWebhookReply;
+exports.claimWebhookReply = claimWebhookReply;
+exports.hasWebhookReply = hasWebhookReply;
+const node_async_hooks_1 = require("node:async_hooks");
+const storage = new node_async_hooks_1.AsyncLocalStorage();
+/** Runs `fn` with a webhook reply sink active for every API call inside it. */
+function runWithWebhookReply(sink, fn) {
+    return storage.run({ sink, claimed: false, suppressed: false }, fn);
+}
+/**
+ * Runs `fn` with webhook replies suppressed (library-internal calls such as
+ * the lazy `getMe` initialization must never claim the response slot).
+ */
+function runWithoutWebhookReply(fn) {
+    const state = storage.getStore();
+    if (!state)
+        return fn();
+    return storage.run({ ...state, suppressed: true }, fn);
+}
+/**
+ * Claims the webhook reply for `method`/`payload` if a sink is active and not
+ * yet used. Returns the synthesized transport response the caller should
+ * resolve with, or `undefined` when the call must go through the transport.
+ */
+function claimWebhookReply(method, payload) {
+    const state = storage.getStore();
+    if (!state || state.claimed || state.suppressed)
+        return undefined;
+    state.claimed = true;
+    state.sink({ method, ...(payload ?? {}) });
+    // Telegram never sends the method result back to the webhook response, so
+    // the caller resolves with a synthetic success (same as Telegraf).
+    return { status: 200, data: { ok: true, result: true } };
+}
+/** True while an unclaimed webhook reply is available (diagnostics/testing). */
+function hasWebhookReply() {
+    const state = storage.getStore();
+    return state !== undefined && !state.claimed;
+}

package/dist-cjs/src/index.js

@@ -16,6 +16,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.printTerminalBranding = exports.buildTerminalBranding = void 0;
 __exportStar(require("./core/bot.js"), exports);
+__exportStar(require("./core/webhook-reply.js"), exports);
 __exportStar(require("./core/events.js"), exports);
 __exportStar(require("./api/index.js"), exports);
 __exportStar(require("./context/context.js"), exports);

package/dist-cjs/src/webhook/handler.js

@@ -3,6 +3,19 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createWebhookHandler = createWebhookHandler;
 exports.webhookCallback = webhookCallback;
 const node_crypto_1 = require("node:crypto");
+/** Runs the update, optionally claiming the webhook response for the first API call. */
+async function processWithOptionalReply(bot, update, sink) {
+    if (sink === undefined) {
+        await bot.handleUpdate(update);
+        return;
+    }
+    await bot.handleUpdate(update, { webhookReply: sink });
+}
+function replyResponse(payload) {
+    if (payload !== undefined)
+        return new Response(JSON.stringify(payload), { status: 200, headers: { "content-type": "application/json" } });
+    return new Response("OK", { status: 200 });
+}
 function createWebhookHandler(bot, options = {}) {
     const maxBodyBytes = options.maxBodyBytes ?? 1_048_576;
     return async (request) => {
@@ -23,8 +36,10 @@ function createWebhookHandler(bot, options = {}) {
             const update = JSON.parse(new TextDecoder().decode(raw));
             if (!Number.isInteger(update.update_id))
                 return new Response("Bad Request", { status: 400 });
-            await bot.handleUpdate(update);
-            return new Response("OK", { status: 200 });
+            let replyPayload;
+            const sink = options.webhookReply === true ? (payload) => { replyPayload = payload; } : undefined;
+            await processWithOptionalReply(bot, update, sink);
+            return replyResponse(replyPayload);
         }
         catch (error) {
             await options.onError?.(error);
@@ -37,9 +52,9 @@ function webhookCallback(bot, _framework = "express", options = {}) {
     return async (req, res) => {
         const rawReq = req;
         const rawRes = res;
-        const sendResponse = (status, message) => {
+        const sendResponse = (status, message, contentType = "text/plain") => {
             if (rawRes && typeof rawRes.writeHead === "function" && typeof rawRes.end === "function") {
-                rawRes.writeHead(status, { "Content-Type": "text/plain" });
+                rawRes.writeHead(status, { "Content-Type": contentType });
                 rawRes.end(message);
                 return;
             }
@@ -99,8 +114,13 @@ function webhookCallback(bot, _framework = "express", options = {}) {
                 sendResponse(400, "Bad Request");
                 return;
             }
-            await bot.handleUpdate(update);
-            sendResponse(200, "OK");
+            let replyPayload;
+            const sink = options.webhookReply === true ? (payload) => { replyPayload = payload; } : undefined;
+            await processWithOptionalReply(bot, update, sink);
+            if (replyPayload !== undefined)
+                sendResponse(200, JSON.stringify(replyPayload), "application/json");
+            else
+                sendResponse(200, "OK");
         }
         catch (error) {
             await options.onError?.(error);

package/docs/API.id.md

@@ -75,6 +75,8 @@ type BotStatus =
 | `polling.retryDelayMs` | `number` | `500` | Delay awal ketika polling gagal. |
 | `polling.maxRetryDelayMs` | `number` | `30000` | Batas maksimum delay reconnect. |
 | `updates.concurrency` | `number` | `Infinity` | Batas jumlah update yang diproses bersamaan. Update selalu berjalan paralel antar chat dan tetap berurutan di dalam satu chat, sehingga burst 1000+ pesan tertangani sekaligus. |
+| `handlerTimeout` | `number` | `90000` | Timeout pemrosesan per update dalam ms (`Infinity` untuk menonaktifkan). Saat timeout, alur error update berjalan (`update:error`, `bot:error`, boundary `catch()`) dan `handleUpdate()` melempar `UpdateTimeoutError`, sementara handler tetap berjalan sampai selesai di background. |
+| `contextType` | `new (options: ContextOptions<S>) => Context<S>` | `Context` | Subclass `Context` kustom yang diinstansiasi untuk setiap update (`contextType` milik Telegraf). |
 
 ### Konstruktor `Bot`
 
@@ -199,10 +201,11 @@ launch(options?: {
   mode: "polling";
   timeout?: number;
   allowedUpdates?: string[];
+  dropPendingUpdates?: boolean;
 }): Promise<void>
 ```
 
-Menjalankan bot dalam mode polling. Saat mulai, lifecycle berpindah melalui `starting` lalu `running`, kemudian loop `getUpdates()` memproses setiap batch update secara konkuren: update dari chat berbeda berjalan paralel, sedangkan update dari chat yang sama menjaga urutan kedatangannya. Kegagalan polling memancarkan `polling:reconnect` dan menggunakan backoff eksponensial.
+Menjalankan bot dalam mode polling. Saat mulai, lifecycle berpindah melalui `starting` lalu `running`, kemudian loop `getUpdates()` memproses setiap batch update secara konkuren: update dari chat berbeda berjalan paralel, sedangkan update dari chat yang sama menjaga urutan kedatangannya. Kegagalan polling memancarkan `polling:reconnect` dan menggunakan backoff eksponensial. `dropPendingUpdates: true` (juga tersedia di `bot.start()`) membuang semua update yang ditahan Telegram sebelum panggilan `getUpdates` pertama, memakai mekanisme `deleteWebhook({ drop_pending_updates: true })` yang sama dengan Telegraf.
 
 Mode selain `"polling"` melempar error dan menyarankan penggunaan `createWebhookHandler()` untuk webhook.
 
@@ -274,12 +277,14 @@ Jalan pintas ke `deleteMyCommands`.
 ### `bot.handleUpdate(update)`
 
 ```ts
-handleUpdate(update: Update): Promise<void>
+handleUpdate(update: Update, options?: { webhookReply?: WebhookReplySink }): Promise<void>
 ```
 
-Memproses satu update secara manual. Method menentukan kunci session dari `chat.id` dan `from.id`, membuat `Context`, memancarkan event `update` dan `message`, menjalankan middleware lalu router, dan menyimpan session setelah pipeline selesai.
+Memproses satu update secara manual. Method menentukan kunci session dari `chat.id` dan `from.id`, membuat `Context` (dari `contextType` yang dikonfigurasi), memancarkan event `update` dan `message`, menjalankan middleware lalu router, dan menyimpan session setelah pipeline selesai.
 
-Update dari chat berbeda diproses paralel; update dari chat yang sama diserialisasi sesuai urutan kedatangan, sehingga session, wizard, dan conversation tidak pernah saling tumpang tindih dan penulisan session tidak pernah hilang. Burst update konkuren hanya memicu satu inisialisasi `getMe`.
+Update dari chat berbeda diproses paralel; update dari chat yang sama diserialisasi sesuai urutan kedatangan, sehingga session, wizard, dan conversation tidak pernah saling tumpang tindih dan penulisan session tidak pernah hilang. Burst update konkuren hanya memicu satu inisialisasi `getMe`. Seluruh proses per update dijaga `handlerTimeout` (default 90 detik, sama dengan Telegraf): saat timeout, error mengalir lewat `update:error`/`bot:error` dan boundary `catch()`, dan `handleUpdate()` melempar `UpdateTimeoutError` sementara handler tetap berjalan di background.
+
+`options.webhookReply` memasang responder ala Telegraf: panggilan API keluar pertama selama update ini dijawab lewat respons HTTP webhook, bukan request terpisah, dan resolve dengan `true` (Telegram tidak pernah mengirim hasil method kembali ke respons webhook).
 
 Error pipeline mengubah status bot menjadi `error`, memancarkan `bot:error`, lalu dilempar kembali.
 
@@ -327,6 +332,25 @@ for (const failure of report.failures) console.warn(`Gagal: ${failure.chatId}
 | `BroadcastReport.durationMs` | `number` | — | Durasi total sesi broadcast. |
 | `BroadcastReport.failures` | `BroadcastFailure[]` | — | Catatan per chat `{ chatId, attempts, error, errorKind }`. |
 
+### `UpdateTimeoutError` dan helper webhook-reply
+
+```ts
+class UpdateTimeoutError extends Error {
+  readonly name = "UpdateTimeoutError";
+  readonly updateId: number;
+}
+```
+
+Dilempar oleh `handleUpdate()` ketika satu update melebihi `handlerTimeout`. Handler itu sendiri tetap berjalan; error juga mengalir lewat `update:error`, `bot:error`, dan boundary `catch()`.
+
+```ts
+type WebhookReplySink = (payload: Record<string, unknown>) => void;
+runWithWebhookReply(sink, fn): Promise<T>   // memasang responder untuk semua panggilan API di dalam fn
+runWithoutWebhookReply(fn): Promise<T>      // panggilan internal library yang tidak pernah mengklaim slot
+```
+
+Diekspor agar webhook server kustom bisa memasang webhook reply dengan cara yang sama seperti `createWebhookHandler`.
+
 ### Contoh bot minimal
 
 ```ts
@@ -736,6 +760,23 @@ new Context<S>(options: ContextOptions<S>): Context<S>
 
 Semua pengirim `replyWith*` menerima parameter native Telegram sebagai `extra` dan otomatis me-quote message yang masuk. `reply_parameters` pada `extra` digabung dengan `message_id` otomatis, bukan menggantikannya. `reply`, `send`, `getChat`, dan beberapa helper lain melempar error ketika update tidak memiliki chat yang diperlukan. `edit` dan `delete` membutuhkan chat serta message.
 
+### Method admin, chat, dan forum pada Context (paritas penuh Telegraf)
+
+Semua method di bawah beraksi pada chat update (`ctx.chat`) dan menerima parameter native Telegram lewat `extra`; semuanya melempar error jelas bila update tidak memiliki chat. Gunakan `ctx.api.methods.*` untuk menargetkan chat lain.
+
+| Grup | Method |
+|---|---|
+| Moderasi | `banChatMember(userId, untilDate?, extra?)`, `unbanChatMember(userId, onlyIfBanned?, extra?)`, `restrictChatMember(userId, permissions, untilDate?, extra?)`, `promoteChatMember(userId, extra?)`, `banChatSenderChat(senderChatId, extra?)`, `unbanChatSenderChat(senderChatId, extra?)` |
+| Manajemen chat | `setChatTitle(title)`, `setChatDescription(description?)`, `setChatPhoto(photo)`, `deleteChatPhoto()`, `setChatPermissions(permissions, extra?)`, `leaveChat()`, `unpinAllChatMessages(extra?)`, `setChatStickerSet(name)`, `deleteChatStickerSet()` |
+| Info chat & member | `getChatAdministrators(): Promise<ChatMember[]>`, `getChatMemberCount(): Promise<number>`, `getChatMember(userId): Promise<ChatMember>` |
+| Invite link | `exportChatInviteLink(): Promise<string>`, `createChatInviteLink(extra?)`, `editChatInviteLink(inviteLink, extra?)`, `revokeChatInviteLink(inviteLink)` |
+| Join request | `approveChatJoinRequest(userId)`, `declineChatJoinRequest(userId)` |
+| Poll & live location | `replyWithQuiz(question, options, extra?)` (sendPoll dengan `type: "quiz"`), `stopPoll(messageId?, extra?)`, `editMessageLiveLocation(latitude?, longitude?, extra?)`, `stopMessageLiveLocation(extra?)` |
+| Game & pembayaran | `replyWithGame(gameShortName, extra?)`, `setGameScore(userId, score, extra?)`, `getGameHighScores(userId?, extra?)`, `replyWithInvoice(title, description, payload, providerToken, currency, prices, extra?)` |
+| Forum topic | `createForumTopic(name, extra?)`, `editForumTopic(extra?)`, `closeForumTopic(threadId?)`, `reopenForumTopic(threadId?)`, `deleteForumTopic(threadId?)`, `unpinAllForumTopicMessages(threadId?)`, `getForumTopicIconStickers()`, `editGeneralForumTopic(name)`, `closeGeneralForumTopic()`, `reopenGeneralForumTopic()`, `hideGeneralForumTopic()`, `unhideGeneralForumTopic()` |
+
+`threadId` default ke `message_thread_id` message context. `replyWithQuiz`, `replyWithGame`, dan `replyWithInvoice` me-quote message masuk seperti semua pengirim `replyWith*`.
+
 ---
 
 ## 5. Middleware dan router
@@ -1131,9 +1172,12 @@ interface WebhookOptions {
   secretToken?: string;
   maxBodyBytes?: number;
   onError?: (error: unknown) => void | Promise<void>;
+  webhookReply?: boolean;
 }
 ```
 
+`webhookReply` (default `false`) mengaktifkan webhook reply ala Telegraf: saat memproses update, panggilan API keluar pertama dijawab lewat respons HTTP webhook itu sendiri (`{"method":"sendMessage", ...}`), sehingga Telegram mengeksekusi method tanpa request kedua. Panggilan itu resolve dengan `true` karena Telegram tidak pernah mengirim hasil method kembali ke respons webhook; setiap panggilan berikutnya tetap lewat transport seperti biasa. Inisialisasi `getMe` malas tidak pernah mengklaim slot tersebut. Berbeda dengan Telegraf, fitur ini opt-in agar deployment webhook yang sudah ada mempertahankan perilakunya persis.
+
 ### `createWebhookHandler(bot, options?)`
 
 ```ts

package/docs/API.md

@@ -74,6 +74,8 @@ type BotStatus =
 | `polling.retryDelayMs` | `number` | `500` | Initial delay when polling fails. |
 | `polling.maxRetryDelayMs` | `number` | `30000` | Maximum reconnect delay. |
 | `updates.concurrency` | `number` | `Infinity` | Cap on how many updates are processed at the same time. Updates always run in parallel across chats and stay ordered within a single chat, so bursts of 1000+ messages are handled at once. |
+| `handlerTimeout` | `number` | `90000` | Per-update processing timeout in ms (`Infinity` disables). On timeout the update error flow runs (`update:error`, `bot:error`, `catch()` boundary) and `handleUpdate()` rejects with `UpdateTimeoutError`, while the handler keeps running to completion in the background. |
+| `contextType` | `new (options: ContextOptions<S>) => Context<S>` | `Context` | Custom `Context` subclass instantiated for every update (Telegraf's `contextType`). |
 
 ### Constructor `Bot`
 
@@ -216,10 +218,11 @@ launch(options?: {
   mode: "polling";
   timeout?: number;
   allowedUpdates?: string[];
+  dropPendingUpdates?: boolean;
 }): Promise<void>
 ```
 
-Runs the bot in polling mode. On start, the lifecycle moves through `starting` to `running`, then the `getUpdates()` loop processes each batch of updates concurrently: updates for different chats run in parallel while updates for the same chat keep their arrival order. Polling failures emit `polling:reconnect` and use exponential backoff.
+Runs the bot in polling mode. On start, the lifecycle moves through `starting` to `running`, then the `getUpdates()` loop processes each batch of updates concurrently: updates for different chats run in parallel while updates for the same chat keep their arrival order. Polling failures emit `polling:reconnect` and use exponential backoff. `dropPendingUpdates: true` (also on `bot.start()`) drops everything Telegram is holding for the bot before the first `getUpdates` call, using the same `deleteWebhook({ drop_pending_updates: true })` mechanism Telegraf uses.
 
 Modes other than `"polling"` throw an error and suggest using `createWebhookHandler()` for webhooks.
 
@@ -291,12 +294,14 @@ Shortcut to `deleteMyCommands`.
 ### `bot.handleUpdate(update)`
 
 ```ts
-handleUpdate(update: Update): Promise<void>
+handleUpdate(update: Update, options?: { webhookReply?: WebhookReplySink }): Promise<void>
 ```
 
-Processes a single update manually. The method determines the session key from `chat.id` and `from.id`, creates a `Context`, emits `update` and `message` events, runs middleware then the router, and saves the session after the pipeline completes.
+Processes a single update manually. The method determines the session key from `chat.id` and `from.id`, creates a `Context` (of the configured `contextType`), emits `update` and `message` events, runs middleware then the router, and saves the session after the pipeline completes.
 
-Updates for different chats are processed in parallel; updates for the same chat are serialized in arrival order, so sessions, wizards, and conversations never interleave and session writes are never lost. A burst of concurrent updates triggers exactly one `getMe` initialization.
+Updates for different chats are processed in parallel; updates for the same chat are serialized in arrival order, so sessions, wizards, and conversations never interleave and session writes are never lost. A burst of concurrent updates triggers exactly one `getMe` initialization. The whole per-update run is guarded by `handlerTimeout` (default 90s, matching Telegraf): on timeout the error flows through `update:error`/`bot:error` and the `catch()` boundary, and `handleUpdate()` rejects with `UpdateTimeoutError` while the handler keeps running in the background.
+
+`options.webhookReply` installs a Telegraf-style responder: the first outgoing API call during this update is answered through the webhook HTTP response instead of a separate request, and resolves with `true` (Telegram never sends the method result back to a webhook response).
 
 Pipeline errors set the bot status to `error`, emit `bot:error`, and then rethrow the error.
 
@@ -344,6 +349,25 @@ for (const failure of report.failures) console.warn(`Failed: ${failure.chatId}
 | `BroadcastReport.durationMs` | `number` | — | Wall-clock duration of the run. |
 | `BroadcastReport.failures` | `BroadcastFailure[]` | — | Per-chat `{ chatId, attempts, error, errorKind }` records. |
 
+### `UpdateTimeoutError` and webhook-reply helpers
+
+```ts
+class UpdateTimeoutError extends Error {
+  readonly name = "UpdateTimeoutError";
+  readonly updateId: number;
+}
+```
+
+Rejected by `handleUpdate()` when a single update exceeds `handlerTimeout`. The handler itself keeps running; the error also flows through `update:error`, `bot:error`, and the `catch()` boundary.
+
+```ts
+type WebhookReplySink = (payload: Record<string, unknown>) => void;
+runWithWebhookReply(sink, fn): Promise<T>   // sets the responder for every API call inside fn
+runWithoutWebhookReply(fn): Promise<T>      // library-internal calls that never claim the slot
+```
+
+Exported so custom webhook servers can wire webhook replies the same way `createWebhookHandler` does.
+
 ### Minimal bot example
 
 ```ts
@@ -754,6 +778,23 @@ new Context<S>(options: ContextOptions<S>): Context<S>
 
 All `replyWith*` senders accept the native Telegram parameters as `extra` and automatically quote the incoming message. Passing `reply_parameters` in `extra` merges with the automatic `message_id` instead of replacing it. `reply`, `send`, `getChat`, and some other helpers throw an error when the update does not have the required chat. `edit` and `delete` require both chat and message.
 
+### Context admin, chat, and forum methods (full Telegraf parity)
+
+Every method below acts on the update's chat (`ctx.chat`) and accepts native Telegram parameters through `extra`; they throw a clear error when the update has no chat. Use `ctx.api.methods.*` to target a different chat.
+
+| Group | Methods |
+|---|---|
+| Moderation | `banChatMember(userId, untilDate?, extra?)`, `unbanChatMember(userId, onlyIfBanned?, extra?)`, `restrictChatMember(userId, permissions, untilDate?, extra?)`, `promoteChatMember(userId, extra?)`, `banChatSenderChat(senderChatId, extra?)`, `unbanChatSenderChat(senderChatId, extra?)` |
+| Chat management | `setChatTitle(title)`, `setChatDescription(description?)`, `setChatPhoto(photo)`, `deleteChatPhoto()`, `setChatPermissions(permissions, extra?)`, `leaveChat()`, `unpinAllChatMessages(extra?)`, `setChatStickerSet(name)`, `deleteChatStickerSet()` |
+| Chat & member info | `getChatAdministrators(): Promise<ChatMember[]>`, `getChatMemberCount(): Promise<number>`, `getChatMember(userId): Promise<ChatMember>` |
+| Invite links | `exportChatInviteLink(): Promise<string>`, `createChatInviteLink(extra?)`, `editChatInviteLink(inviteLink, extra?)`, `revokeChatInviteLink(inviteLink)` |
+| Join requests | `approveChatJoinRequest(userId)`, `declineChatJoinRequest(userId)` |
+| Polls & live location | `replyWithQuiz(question, options, extra?)` (sendPoll with `type: "quiz"`), `stopPoll(messageId?, extra?)`, `editMessageLiveLocation(latitude?, longitude?, extra?)`, `stopMessageLiveLocation(extra?)` |
+| Games & payments | `replyWithGame(gameShortName, extra?)`, `setGameScore(userId, score, extra?)`, `getGameHighScores(userId?, extra?)`, `replyWithInvoice(title, description, payload, providerToken, currency, prices, extra?)` |
+| Forum topics | `createForumTopic(name, extra?)`, `editForumTopic(extra?)`, `closeForumTopic(threadId?)`, `reopenForumTopic(threadId?)`, `deleteForumTopic(threadId?)`, `unpinAllForumTopicMessages(threadId?)`, `getForumTopicIconStickers()`, `editGeneralForumTopic(name)`, `closeGeneralForumTopic()`, `reopenGeneralForumTopic()`, `hideGeneralForumTopic()`, `unhideGeneralForumTopic()` |
+
+`threadId` defaults to the context message's `message_thread_id`. `replyWithQuiz`, `replyWithGame`, and `replyWithInvoice` quote the incoming message like every `replyWith*` sender.
+
 ---
 
 ## 5. Middleware and router
@@ -1149,9 +1190,12 @@ interface WebhookOptions {
   secretToken?: string;
   maxBodyBytes?: number;
   onError?: (error: unknown) => void | Promise<void>;
+  webhookReply?: boolean;
 }
 ```
 
+`webhookReply` (default `false`) enables Telegraf-style webhook replies: while handling an update, the first outgoing API call is answered through the webhook HTTP response itself (`{"method":"sendMessage", ...}`), so Telegram executes the method without a second request. That call resolves with `true` because Telegram never sends the method result back to a webhook response; every later call goes through the transport as usual. The lazy `getMe` initialization never claims the slot. Unlike Telegraf, this is opt-in so existing webhook deployments keep their exact behavior.
+
 ### `createWebhookHandler(bot, options?)`
 
 ```ts

package/docs/API.zh-CN.md

@@ -75,6 +75,8 @@ type BotStatus =
 | `polling.retryDelayMs` | `number` | `500` | 轮询失败时的初始延迟（毫秒）。 |
 | `polling.maxRetryDelayMs` | `number` | `30000` | 重连延迟的最大值（毫秒）。 |
 | `updates.concurrency` | `number` | `Infinity` | 同时处理的 update 数量上限。不同 chat 的 update 始终并行，同一 chat 内保持顺序，因此 1000+ 条消息的突发可一次性处理。 |
+| `handlerTimeout` | `number` | `90000` | 单个 update 的处理超时（毫秒，`Infinity` 表示禁用）。超时后走 update 错误流程（`update:error`、`bot:error`、`catch()` 边界），`handleUpdate()` 以 `UpdateTimeoutError` 拒绝，而 handler 仍在后台继续运行直至完成。 |
+| `contextType` | `new (options: ContextOptions<S>) => Context<S>` | `Context` | 为每个 update 实例化的自定义 `Context` 子类（Telegraf 的 `contextType`）。 |
 
 ### `Bot` constructor
 
@@ -199,10 +201,11 @@ launch(options?: {
   mode: "polling";
   timeout?: number;
   allowedUpdates?: string[];
+  dropPendingUpdates?: boolean;
 }): Promise<void>
 ```
 
-以 polling 模式运行 bot。启动时生命周期依次变为 `starting` 然后 `running`，之后 `getUpdates()` 循环并发处理每一批 update：不同 chat 的 update 并行执行，同一 chat 的 update 保持到达顺序。轮询失败会触发 `polling:reconnect` 并使用指数退避。
+以 polling 模式运行 bot。启动时生命周期依次变为 `starting` 然后 `running`，之后 `getUpdates()` 循环并发处理每一批 update：不同 chat 的 update 并行执行，同一 chat 的 update 保持到达顺序。轮询失败会触发 `polling:reconnect` 并使用指数退避。`dropPendingUpdates: true`（`bot.start()` 同样支持）会在第一次 `getUpdates` 之前丢弃 Telegram 为该 bot 持有的全部更新，使用与 Telegraf 相同的 `deleteWebhook({ drop_pending_updates: true })` 机制。
 
 除 `"polling"` 外的模式会抛出错误，并建议对 webhook 使用 `createWebhookHandler()`。
 
@@ -274,12 +277,14 @@ deleteCommands(
 ### `bot.handleUpdate(update)`
 
 ```ts
-handleUpdate(update: Update): Promise<void>
+handleUpdate(update: Update, options?: { webhookReply?: WebhookReplySink }): Promise<void>
 ```
 
-手动处理单个 update。该方法根据 `chat.id` 和 `from.id` 确定会话 key，创建 `Context`，触发 `update` 和 `message` 事件，执行 middleware 然后路由器，并在流水线完成后保存会话。
+手动处理单个 update。该方法根据 `chat.id` 和 `from.id` 确定会话 key，创建 `Context`（由配置的 `contextType` 实例化），触发 `update` 和 `message` 事件，执行 middleware 然后路由器，并在流水线完成后保存会话。
 
-不同 chat 的 update 并行处理；同一 chat 的 update 按到达顺序串行处理，因此会话、wizard 和 conversation 永远不会交错，会话写入也不会丢失。并发的 update 突发只会触发一次 `getMe` 初始化。
+不同 chat 的 update 并行处理；同一 chat 的 update 按到达顺序串行处理，因此会话、wizard 和 conversation 永远不会交错，会话写入也不会丢失。并发的 update 突发只会触发一次 `getMe` 初始化。整个单 update 流程受 `handlerTimeout` 保护（默认 90 秒，与 Telegraf 一致）：超时后错误会流经 `update:error`/`bot:error` 和 `catch()` 边界，`handleUpdate()` 以 `UpdateTimeoutError` 拒绝，而 handler 仍在后台继续运行。
+
+`options.webhookReply` 安装一个 Telegraf 风格的响应器：该 update 期间第一个外发 API 调用通过 webhook HTTP 响应本身来应答（而不是单独发请求），并且以 `true` resolve（Telegram 从不把方法结果发回 webhook 响应）。
 
 流水线错误会将 bot 状态置为 `error`，触发 `bot:error`，然后重新抛出错误。
 
@@ -327,6 +332,25 @@ for (const failure of report.failures) console.warn(`Failed: ${failure.chatId}
 | `BroadcastReport.durationMs` | `number` | — | 本次广播的实际耗时（毫秒）。 |
 | `BroadcastReport.failures` | `BroadcastFailure[]` | — | 按 chat 记录的 `{ chatId, attempts, error, errorKind }`。 |
 
+### `UpdateTimeoutError` 与 webhook-reply 辅助函数
+
+```ts
+class UpdateTimeoutError extends Error {
+  readonly name = "UpdateTimeoutError";
+  readonly updateId: number;
+}
+```
+
+当单个 update 超过 `handlerTimeout` 时由 `handleUpdate()` 拒绝抛出。handler 本身继续运行；错误同样会流经 `update:error`、`bot:error` 和 `catch()` 边界。
+
+```ts
+type WebhookReplySink = (payload: Record<string, unknown>) => void;
+runWithWebhookReply(sink, fn): Promise<T>   // 为 fn 内的所有 API 调用设置响应器
+runWithoutWebhookReply(fn): Promise<T>      // 永不占用槽位的库内部调用
+```
+
+导出这些函数，让自定义 webhook 服务器能够以与 `createWebhookHandler` 相同的方式接入 webhook 应答。
+
 ### 最小 bot 示例
 
 ```ts
@@ -736,6 +760,23 @@ new Context<S>(options: ContextOptions<S>): Context<S>
 
 `reply`、`send`、`getChat` 以及其他一些辅助方法在更新缺少所需聊天时会抛出错误。`edit` 和 `delete` 需要同时有聊天和消息。
 
+### Context 管理员、聊天与论坛方法（与 Telegraf 完全对齐）
+
+以下方法均作用于本次更新的聊天（`ctx.chat`），并通过 `extra` 接受原生 Telegram 参数；当更新没有聊天时都会抛出清晰的错误。要操作其他聊天请使用 `ctx.api.methods.*`。
+
+| 分组 | 方法 |
+|---|---|
+| 管理/封禁 | `banChatMember(userId, untilDate?, extra?)`、`unbanChatMember(userId, onlyIfBanned?, extra?)`、`restrictChatMember(userId, permissions, untilDate?, extra?)`、`promoteChatMember(userId, extra?)`、`banChatSenderChat(senderChatId, extra?)`、`unbanChatSenderChat(senderChatId, extra?)` |
+| 聊天管理 | `setChatTitle(title)`、`setChatDescription(description?)`、`setChatPhoto(photo)`、`deleteChatPhoto()`、`setChatPermissions(permissions, extra?)`、`leaveChat()`、`unpinAllChatMessages(extra?)`、`setChatStickerSet(name)`、`deleteChatStickerSet()` |
+| 聊天与成员信息 | `getChatAdministrators(): Promise<ChatMember[]>`、`getChatMemberCount(): Promise<number>`、`getChatMember(userId): Promise<ChatMember>` |
+| 邀请链接 | `exportChatInviteLink(): Promise<string>`、`createChatInviteLink(extra?)`、`editChatInviteLink(inviteLink, extra?)`、`revokeChatInviteLink(inviteLink)` |
+| 加群申请 | `approveChatJoinRequest(userId)`、`declineChatJoinRequest(userId)` |
+| 投票与实时位置 | `replyWithQuiz(question, options, extra?)`（`type: "quiz"` 的 sendPoll）、`stopPoll(messageId?, extra?)`、`editMessageLiveLocation(latitude?, longitude?, extra?)`、`stopMessageLiveLocation(extra?)` |
+| 游戏与支付 | `replyWithGame(gameShortName, extra?)`、`setGameScore(userId, score, extra?)`、`getGameHighScores(userId?, extra?)`、`replyWithInvoice(title, description, payload, providerToken, currency, prices, extra?)` |
+| 论坛主题 | `createForumTopic(name, extra?)`、`editForumTopic(extra?)`、`closeForumTopic(threadId?)`、`reopenForumTopic(threadId?)`、`deleteForumTopic(threadId?)`、`unpinAllForumTopicMessages(threadId?)`、`getForumTopicIconStickers()`、`editGeneralForumTopic(name)`、`closeGeneralForumTopic()`、`reopenGeneralForumTopic()`、`hideGeneralForumTopic()`、`unhideGeneralForumTopic()` |
+
+`threadId` 默认取上下文消息的 `message_thread_id`。`replyWithQuiz`、`replyWithGame` 和 `replyWithInvoice` 与所有 `replyWith*` 发送者一样自动引用回复。
+
 ---
 
 ## 5. 中间件与路由器
@@ -1125,9 +1166,12 @@ interface WebhookOptions {
   secretToken?: string;
   maxBodyBytes?: number;
   onError?: (error: unknown) => void | Promise<void>;
+  webhookReply?: boolean;
 }
 ```
 
+`webhookReply`（默认 `false`）启用 Telegraf 风格的 webhook 应答：处理 update 期间，第一个外发 API 调用直接通过 webhook HTTP 响应本身应答（`{"method":"sendMessage", ...}`），Telegram 因此无需第二次请求即可执行该方法。该调用以 `true` resolve，因为 Telegram 从不把方法结果发回 webhook 响应；之后的每个调用都照常走 transport。懒加载的 `getMe` 初始化永远不会占用该槽位。与 Telegraf 不同，此功能为 opt-in，已有的 webhook 部署行为保持完全不变。
+
 ### `createWebhookHandler(bot, options?)`
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xbibzlibrary/telebibz",
-  "version": "0.3.2",
+  "version": "0.4.1",
   "description": "Telegram Bot framework for Node.js and TypeScript with a typed API client, routing, middleware, webhooks, keyboards, conversations, plugins, queues, and a polished terminal experience.",
   "keywords": [
     "telegram",