@xbibzlibrary/telebibz 0.3.2 → 0.4.2

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,18 @@ 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");
+const node_async_hooks_1 = require("node:async_hooks");
+/** 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,8 +43,18 @@ 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();
+    /**
+     * Identifies the update chain executing in the current async context so
+     * `stop()` called from inside a handler never deadlocks waiting on itself
+     * (Telegraf allows `bot.stop()` from within a handler).
+     */
+    currentUpdateChain = new node_async_hooks_1.AsyncLocalStorage();
     /** Memoized init so a burst of updates triggers exactly one getMe call. */
     initOnce;
     brandingEnabled;
@@ -62,6 +84,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,
@@ -84,6 +108,8 @@ class Bot {
     use(...middleware) { this.middlewares.push(...middleware); return this; }
     command(name, handler) { this.router.command(name, handler); return this; }
     callback(pattern, handler) { this.router.callback(pattern, handler); return this; }
+    /** Telegraf-style alias for `callback()`: registers a handler for callback-query button data. */
+    action(pattern, handler) { this.router.callback(pattern, handler); return this; }
     onText(text, handler) { this.router.text(text, handler); return this; }
     onRegex(expression, handler) { this.router.regex(expression, handler); return this; }
     /** Registers a handler for update types: `bot.on("message:photo", handler)` or `bot.on(["message:text", "callback_query:data"], handler)`. */
@@ -155,7 +181,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 +206,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 });
@@ -197,6 +228,9 @@ class Bot {
         await this.events.emit("bot:stopping", { bot: this });
         this.pollingAbort?.abort();
         this.pollingAbort = undefined;
+        // Graceful shutdown: wait for updates still being processed (bounded by
+        // handlerTimeout) so sessions finish writing before plugins are disposed.
+        await this.drainInFlightUpdates();
         await this.plugins.stop();
         await this.plugins.dispose();
         this.statusValue = "stopped";
@@ -206,6 +240,17 @@ class Bot {
             this.logger.info("bot.stopped");
         await this.events.emit("bot:stopped", { bot: this });
     }
+    /** Waits (bounded by `handlerTimeout`) for updates that are still processing. */
+    async drainInFlightUpdates() {
+        // A handler calling stop() must not wait on its own chain (deadlock); it
+        // keeps running in the background, exactly like Telegraf.
+        const current = this.currentUpdateChain.getStore();
+        const inFlight = [...this.chatChains.values()].filter((chain) => chain !== current);
+        if (inFlight.length === 0)
+            return;
+        this.logger.info("bot.draining_updates", { inFlight: inFlight.length });
+        await this.withTimeout(Promise.allSettled(inFlight), this.handlerTimeoutMs, -1);
+    }
     async restart() { await this.stop(); await this.start(); }
     async health() {
         try {
@@ -224,18 +269,62 @@ 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. The
+        // chain is installed as the current AsyncLocalStorage value so a handler
+        // calling bot.stop() is excluded from the drain set.
+        const run = (previous ?? Promise.resolve()).catch(() => undefined).then(() => this.currentUpdateChain.run(tail, 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; `timeoutMs <= 0` or a non-finite value disables the guard. */
+    async withTimeout(promise, timeoutMs, updateId) {
+        if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+            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 +354,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 +385,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

@@ -14,8 +14,9 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.printTerminalBranding = exports.buildTerminalBranding = void 0;
+exports.startTeleBibzBanner = exports.runStartupSequence = exports.printStatusLine = exports.paintRainbow = exports.printTeleBibzBanner = 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);
@@ -37,4 +38,9 @@ __exportStar(require("./telegram-features.js"), exports);
 var terminal_js_1 = require("./branding/terminal.js");
 Object.defineProperty(exports, "buildTerminalBranding", { enumerable: true, get: function () { return terminal_js_1.buildTerminalBranding; } });
 Object.defineProperty(exports, "printTerminalBranding", { enumerable: true, get: function () { return terminal_js_1.printTerminalBranding; } });
+Object.defineProperty(exports, "printTeleBibzBanner", { enumerable: true, get: function () { return terminal_js_1.printTeleBibzBanner; } });
+Object.defineProperty(exports, "paintRainbow", { enumerable: true, get: function () { return terminal_js_1.paintRainbow; } });
+Object.defineProperty(exports, "printStatusLine", { enumerable: true, get: function () { return terminal_js_1.printStatusLine; } });
+Object.defineProperty(exports, "runStartupSequence", { enumerable: true, get: function () { return terminal_js_1.runStartupSequence; } });
+Object.defineProperty(exports, "startTeleBibzBanner", { enumerable: true, get: function () { return terminal_js_1.startTeleBibzBanner; } });
 __exportStar(require("./observability/logger.js"), exports);

package/dist-cjs/src/observability/logger.js

@@ -6,7 +6,10 @@ exports.formatLocalStamp = formatLocalStamp;
 exports.describeIncomingUpdate = describeIncomingUpdate;
 exports.summarizeUpdate = summarizeUpdate;
 exports.createLogger = createLogger;
-const priorities = { silent: 99, error: 0, warn: 1, info: 2, debug: 3, trace: 4 };
+// Higher number = more verbose. `silent` must sort BELOW `error` so that every
+// message level is filtered out (a value above all others would let every
+// message through, including errors).
+const priorities = { silent: -1, error: 0, warn: 1, info: 2, debug: 3, trace: 4 };
 const defaultRedactKeys = ["token", "secret", "password", "authorization", "cookie", "private_key", "api_key", "npm_token", "bot_token"];
 const ANSI = {
     reset: "\u001b[0m",

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