2.0.1

MIGRATION.md

@@ -56,8 +56,14 @@ The example scripts now use `tsx` and Node.js built-in watch mode instead of `ts
 
 Components can subscribe to arbitrary Telegram update types through `events`. Existing `message` and `callback_query` routing remains compatible.
 
+TBF now automatically acknowledges callback queries before running their actions. This clears Telegram's inline-button loading indicator before a page edits the message or replaces its keyboard. Expired callback acknowledgements are ignored and do not prevent routing.
+
 Action handlers now expose `reply`, media helpers, `sendPoll`, `sendLocation`, `sendChatAction`, `react`, and the generic `api(method, payload)` escape hatch. The generic API method is intentionally loosely typed so applications can use a newly released Telegram method before Telegraf and TBF publish updated types.
 
+Long-running operations can use `withChatAction("typing", callback)` to keep Telegram's activity status alive until the callback settles. An action or message handler can instead declare `chatAction: "typing"`; no status is sent unless one of these opt-in forms is used.
+
+Set `chatActions.stopOnNavigation: true` to stop refreshing active chat actions before `goToAction`, `goToPage`, `goToPlugin`, or `openPage` starts the next action. It defaults to `false` for compatibility.
+
 ## Page navigation and runtime lifecycle
 
 `await openPage()` now waits for the selected page action to finish. This fixes the previous promise contract, which resolved immediately after starting the action.

README.md

@@ -378,6 +378,7 @@ Messaging
 * `this.sendPhoto()`, `sendVideo()`, `sendAnimation()`, `sendAudio()`, `sendDocument()`, `sendVoice()`, `sendSticker()` send media and register resulting messages for cleanup.
 * `this.sendLocation()` and `this.sendPoll()` send location and poll messages.
 * `this.sendChatAction("typing")` sends a chat action.
+* `this.withChatAction("typing", callback)` keeps a chat action active while an asynchronous operation runs.
 * `this.react("👍")` reacts to the current message.
 * `this.clearChat()` clears chat with user.  
 
@@ -510,13 +511,50 @@ await this.reply({
 
 await this.react(["👍", "🔥"], { is_big: true });
 
+const answer = await this.withChatAction("typing", async () => {
+    return generateAnswer();
+});
+
+await this.send({ text: answer });
+
 await this.api("sendMessageDraft", {
     chat_id: this.ctx.chatId,
     draft_id: 1,
     text: "Generating…"
 });
 ```
 
+For an entire action or message handler, the same behavior can be declared without a wrapper:
+
+```ts
+actions: {
+    generate: {
+        chatAction: "typing",
+        async handler() {
+            const answer = await generateAnswer();
+            await this.send({ text: answer });
+        }
+    }
+}
+```
+
+`chatAction` is opt-in and defaults to `undefined`, preserving the previous behavior. TBF refreshes the status every four seconds and always stops the timer when the operation completes or throws.
+
+To also stop the current status immediately when navigating to another action, page, or plugin, enable navigation tracking:
+
+```ts
+TBF({
+    telegram: { token },
+    config: {
+        chatActions: {
+            stopOnNavigation: true
+        }
+    }
+});
+```
+
+The option defaults to `false`. Telegram Bot API has no explicit cancel operation: TBF stops refreshing the status, and Telegram removes it within five seconds or as soon as the bot sends a new message.
+
 ### Combine callback and message handlers.
 
 We can imagine a little action that asks for user's name.  

lib/config.d.ts

@@ -13,6 +13,9 @@ type ResolvedTBFConfig = {
     gracefulShutdown: {
         handleSignals: boolean;
     };
+    chatActions: {
+        stopOnNavigation: boolean;
+    };
     webServer: {
         port: number;
         address: string;