charness 3.6.1 → 3.7.0

package/dist/connectors/telegram/bindPicker.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.bindPickerCallbacks = exports.bindPageNoopCallback = exports.bindLeaveCurrentCallback = exports.bindCreateFolderCallback = exports.BIND_PAGE_SIZE = void 0;
+exports.checkIsBindPickerExtra = checkIsBindPickerExtra;
 exports.buildBindKeyboard = buildBindKeyboard;
 /**
  * The folder picker of `/bind` — and of `/topic`, which shows the same keyboard with its buttons pointing at a
@@ -30,6 +31,19 @@ exports.bindPickerCallbacks = {
     getPageCallback: (page) => `bind_page_${page}`,
     createFolderCallback: exports.bindCreateFolderCallback,
 };
+/**
+ * The keyboards {@link buildBindKeyboard} built with `/bind`'s own callbacks, by identity of their `reply_markup`: a copy of
+ * the extra that carries one (a larger object spread from it) still holds the same markup, so a send is recognised as a
+ * `/bind` picker wherever it was composed.
+ */
+const bindPickerMarkups = new WeakSet();
+/**
+ * @description Whether a send's `extra` carries a `/bind` picker — the keyboard of `/bind`, of the «not bound» replies and of
+ * the topic-created welcome — and not another keyboard, nor the `/topic` wizard's re-targeted copy of the same layout.
+ */
+function checkIsBindPickerExtra(extra) {
+    return 'reply_markup' in extra && typeof extra.reply_markup === 'object' && extra.reply_markup !== null && bindPickerMarkups.has(extra.reply_markup);
+}
 /**
  * @description Build a `subdir`-suggestion keyboard for `/bind` and friends.
  *
@@ -92,6 +106,9 @@ function buildBindKeyboard(subdirs, page = 0, pageSize = exports.BIND_PAGE_SIZE,
     if (callbacks.cancelButton) {
         rows.push([telegraf_1.Markup.button.callback(callbacks.cancelButton.label, callbacks.cancelButton.callback)]);
     }
-    return telegraf_1.Markup.inlineKeyboard(rows);
+    const keyboard = telegraf_1.Markup.inlineKeyboard(rows);
+    if (callbacks === exports.bindPickerCallbacks)
+        bindPickerMarkups.add(keyboard.reply_markup);
+    return keyboard;
 }
 //# sourceMappingURL=bindPicker.js.map

package/dist/connectors/telegram/bindPicker.js.map

@@ -1 +1 @@
-{"version":3,"file":"bindPicker.js","sourceRoot":"","sources":["../../../src/connectors/telegram/bindPicker.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"bindPicker.js","sourceRoot":"","sources":["../../../src/connectors/telegram/bindPicker.ts"],"names":[],"mappings":"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"}

package/dist/connectors/telegram/bindPickerClaims.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Which `/bind` picker messages a bind has already claimed. A leaf module (no `bot.ts`, no environment), so a test can
+ * reach it.
+ */
+import type { SessionKey } from '../../sessionKey';
+/** How many claims are kept: the oldest is dropped past it, as a keyboard that old has long been out of reach. */
+export declare const bindPickerClaimLimit = 200;
+/**
+ * The `/bind` picker is spent by the bind (or the leave) it leads to, and a bind takes seconds (the folder's facts are probed, the sends
+ * are paced): a second tap on the same keyboard inside that time must not bind again. A handler claims the picker message
+ * in the same synchronous step that decides to act, before its first await, so of two taps landing together exactly one wins;
+ * a bind that is refused gives the claim back, and the picker works on.
+ */
+export declare class BindPickerClaims {
+    private readonly limit;
+    private readonly claimed;
+    /** The messages {@link retire} holds until {@link unretire}; not subject to the limit. */
+    private readonly retired;
+    constructor(limit?: number);
+    /** @description Claim the picker message; `false` when a bind already holds it. */
+    claim(key: SessionKey, messageId: number): boolean;
+    /** @description Whether a bind (or a leave) holds the picker message: nothing else may act on it. */
+    has(key: SessionKey, messageId: number): boolean;
+    /**
+     * @description Hold the picker message outside the limit, until {@link unretire}: the sweep that closes a topic's open pickers
+     * takes dozens at once, which must neither push a tap's claim out of the limited list (a second tap would then bind again)
+     * nor be pushed out by newer claims (a picker that keeps its buttons — too old to delete, past the strip bound — has nothing
+     * else between a stale tap and a rebind). The hold lasts as long as the process: a restart forgets it, and a picker still
+     * carrying buttons then works again.
+     */
+    retire(key: SessionKey, messageId: number): void;
+    /** @description Let go of a {@link retire}d message that has nothing left to tap — deleted, or its buttons removed: the hold would only grow. */
+    unretire(key: SessionKey, messageId: number): void;
+    /** @description Give a claim back: the bind it was for was refused, so the picker stays usable. */
+    release(key: SessionKey, messageId: number): void;
+    /**
+     * @description Run `work` holding the picker message. `'busy'`: a bind already holds it, `work` did not run. `'done'`: `work`
+     * resolved `true` — it did what the tap asked, and the picker stays claimed (it is spent). `'undone'`: it resolved `false`
+     * (a refused bind), or threw — the claim goes back and the picker works on, so nothing between the claim and a finished
+     * bind can leave it held for a bind that never happened. The claim is taken before the first await: call this straight
+     * from the handler, with no await in front of it. `messageId` is `null` for a tap Telegram attached no message to: the
+     * work runs, with nothing to claim.
+     */
+    runClaimed(key: SessionKey, messageId: number | null, work: () => Promise<boolean>): Promise<'busy' | 'done' | 'undone'>;
+}
+//# sourceMappingURL=bindPickerClaims.d.ts.map

package/dist/connectors/telegram/bindPickerClaims.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bindPickerClaims.d.ts","sourceRoot":"","sources":["../../../src/connectors/telegram/bindPickerClaims.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAGnD,kHAAkH;AAClH,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAExC;;;;;GAKG;AACH,qBAAa,gBAAgB;IAKf,OAAO,CAAC,QAAQ,CAAC,KAAK;IAJlC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,0FAA0F;IAC1F,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;gBAEhB,KAAK,GAAE,MAA6B;IAEjE,mFAAmF;IACnF,KAAK,CAAC,GAAG,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO;IAYlD,qGAAqG;IACrG,GAAG,CAAC,GAAG,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO;IAKhD;;;;;;OAMG;IACH,MAAM,CAAC,GAAG,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAIhD,iJAAiJ;IACjJ,QAAQ,CAAC,GAAG,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAIlD,mGAAmG;IACnG,OAAO,CAAC,GAAG,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAIjD;;;;;;;OAOG;IACG,UAAU,CAAC,GAAG,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;CAW/H"}

package/dist/connectors/telegram/bindPickerClaims.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BindPickerClaims = exports.bindPickerClaimLimit = void 0;
+const callbackMessage_1 = require("./commands/callbackMessage");
+/** How many claims are kept: the oldest is dropped past it, as a keyboard that old has long been out of reach. */
+exports.bindPickerClaimLimit = 200;
+/**
+ * The `/bind` picker is spent by the bind (or the leave) it leads to, and a bind takes seconds (the folder's facts are probed, the sends
+ * are paced): a second tap on the same keyboard inside that time must not bind again. A handler claims the picker message
+ * in the same synchronous step that decides to act, before its first await, so of two taps landing together exactly one wins;
+ * a bind that is refused gives the claim back, and the picker works on.
+ */
+class BindPickerClaims {
+    limit;
+    claimed = new Set();
+    /** The messages {@link retire} holds until {@link unretire}; not subject to the limit. */
+    retired = new Set();
+    constructor(limit = exports.bindPickerClaimLimit) {
+        this.limit = limit;
+    }
+    /** @description Claim the picker message; `false` when a bind already holds it. */
+    claim(key, messageId) {
+        const claimKey = (0, callbackMessage_1.buildMessageSnapshotKey)(key, messageId);
+        if (this.claimed.has(claimKey) || this.retired.has(claimKey))
+            return false;
+        this.claimed.add(claimKey);
+        while (this.claimed.size > this.limit) {
+            const oldest = this.claimed.values().next().value;
+            if (oldest === undefined)
+                break;
+            this.claimed.delete(oldest);
+        }
+        return true;
+    }
+    /** @description Whether a bind (or a leave) holds the picker message: nothing else may act on it. */
+    has(key, messageId) {
+        const claimKey = (0, callbackMessage_1.buildMessageSnapshotKey)(key, messageId);
+        return this.claimed.has(claimKey) || this.retired.has(claimKey);
+    }
+    /**
+     * @description Hold the picker message outside the limit, until {@link unretire}: the sweep that closes a topic's open pickers
+     * takes dozens at once, which must neither push a tap's claim out of the limited list (a second tap would then bind again)
+     * nor be pushed out by newer claims (a picker that keeps its buttons — too old to delete, past the strip bound — has nothing
+     * else between a stale tap and a rebind). The hold lasts as long as the process: a restart forgets it, and a picker still
+     * carrying buttons then works again.
+     */
+    retire(key, messageId) {
+        this.retired.add((0, callbackMessage_1.buildMessageSnapshotKey)(key, messageId));
+    }
+    /** @description Let go of a {@link retire}d message that has nothing left to tap — deleted, or its buttons removed: the hold would only grow. */
+    unretire(key, messageId) {
+        this.retired.delete((0, callbackMessage_1.buildMessageSnapshotKey)(key, messageId));
+    }
+    /** @description Give a claim back: the bind it was for was refused, so the picker stays usable. */
+    release(key, messageId) {
+        this.claimed.delete((0, callbackMessage_1.buildMessageSnapshotKey)(key, messageId));
+    }
+    /**
+     * @description Run `work` holding the picker message. `'busy'`: a bind already holds it, `work` did not run. `'done'`: `work`
+     * resolved `true` — it did what the tap asked, and the picker stays claimed (it is spent). `'undone'`: it resolved `false`
+     * (a refused bind), or threw — the claim goes back and the picker works on, so nothing between the claim and a finished
+     * bind can leave it held for a bind that never happened. The claim is taken before the first await: call this straight
+     * from the handler, with no await in front of it. `messageId` is `null` for a tap Telegram attached no message to: the
+     * work runs, with nothing to claim.
+     */
+    async runClaimed(key, messageId, work) {
+        if (messageId === null)
+            return (await work()) ? 'done' : 'undone';
+        if (!this.claim(key, messageId))
+            return 'busy';
+        let isDone = false;
+        try {
+            isDone = await work();
+            return isDone ? 'done' : 'undone';
+        }
+        finally {
+            if (!isDone)
+                this.release(key, messageId);
+        }
+    }
+}
+exports.BindPickerClaims = BindPickerClaims;
+//# sourceMappingURL=bindPickerClaims.js.map

package/dist/connectors/telegram/bindPickerClaims.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bindPickerClaims.js","sourceRoot":"","sources":["../../../src/connectors/telegram/bindPickerClaims.ts"],"names":[],"mappings":";;;AAKA,gEAAqE;AAErE,kHAAkH;AACrG,QAAA,oBAAoB,GAAG,GAAG,CAAC;AAExC;;;;;GAKG;AACH,MAAa,gBAAgB;IAKE;IAJZ,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAC7C,0FAA0F;IACzE,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAE7C,YAA6B,QAAgB,4BAAoB;QAApC,UAAK,GAAL,KAAK,CAA+B;IAAG,CAAC;IAErE,mFAAmF;IACnF,KAAK,CAAC,GAAe,EAAE,SAAiB;QACtC,MAAM,QAAQ,GAAG,IAAA,yCAAuB,EAAC,GAAG,EAAE,SAAS,CAAC,CAAC;QACzD,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC;YAAE,OAAO,KAAK,CAAC;QAC3E,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC3B,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;YACtC,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC;YAClD,IAAI,MAAM,KAAK,SAAS;gBAAE,MAAM;YAChC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAC9B,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,qGAAqG;IACrG,GAAG,CAAC,GAAe,EAAE,SAAiB;QACpC,MAAM,QAAQ,GAAG,IAAA,yCAAuB,EAAC,GAAG,EAAE,SAAS,CAAC,CAAC;QACzD,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAClE,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,GAAe,EAAE,SAAiB;QACvC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAA,yCAAuB,EAAC,GAAG,EAAE,SAAS,CAAC,CAAC,CAAC;IAC5D,CAAC;IAED,iJAAiJ;IACjJ,QAAQ,CAAC,GAAe,EAAE,SAAiB;QACzC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAA,yCAAuB,EAAC,GAAG,EAAE,SAAS,CAAC,CAAC,CAAC;IAC/D,CAAC;IAED,mGAAmG;IACnG,OAAO,CAAC,GAAe,EAAE,SAAiB;QACxC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAA,yCAAuB,EAAC,GAAG,EAAE,SAAS,CAAC,CAAC,CAAC;IAC/D,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,UAAU,CAAC,GAAe,EAAE,SAAwB,EAAE,IAA4B;QACtF,IAAI,SAAS,KAAK,IAAI;YAAE,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC;QAClE,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,SAAS,CAAC;YAAE,OAAO,MAAM,CAAC;QAC/C,IAAI,MAAM,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC;YACH,MAAM,GAAG,MAAM,IAAI,EAAE,CAAC;YACtB,OAAO,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC;QACpC,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,MAAM;gBAAE,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;QAC5C,CAAC;IACH,CAAC;CACF;AAlED,4CAkEC"}

package/dist/connectors/telegram/bindSweep.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The sweep that closes the open `/bind` messages of a topic once it is bound or has left its folder, written over ports so a
+ * test can reach it: the Telegram calls and the claim list are the caller's. A leaf module (no `bot.ts`, no environment).
+ */
+import { type OpenBindMessage } from './openBindMessages';
+/** What a sweep does to the messages of ONE topic. */
+export interface BindSweepPorts {
+    /** Hold a picker message: a tap on it is refused until {@link BindSweepPorts.unretire} (`BindPickerClaims.retire`). */
+    retire: (messageId: number) => void;
+    /** Let go of a message that has nothing left to tap (`BindPickerClaims.unretire`). */
+    unretire: (messageId: number) => void;
+    /** ONE bulk delete; `false` when Telegram refused the call. */
+    deleteMessages: (messageIds: readonly number[]) => Promise<boolean>;
+    /** Remove one message's keyboard; `false` when the edit failed. */
+    removeKeyboard: (messageId: number) => Promise<boolean>;
+}
+/**
+ * @description Remove the keyboards of messages that can no longer be deleted or must stay as history, the newest
+ * `keyboardStripsPerSweepLimit` of them (`messageIds` oldest first: the newest sit nearest the bottom of the topic): each strip
+ * is a paced send of the bot's one global gate. Resolves the ids whose keyboard is gone — the older rest and every failed edit
+ * still carry theirs.
+ */
+export declare function stripStaleKeyboards(messageIds: readonly number[], removeKeyboard: (messageId: number) => Promise<boolean>): Promise<number[]>;
+/**
+ * @description Close `entries`, the messages a topic had open. Every one is held FIRST, before the first await, so a tap on it is
+ * refused whatever becomes of its message; the hold is let go of for the ones with nothing left to tap — deleted by the bulk
+ * call, or stripped of their buttons. A message too old for Telegram to delete loses its buttons instead, and so does every one
+ * of a bulk call Telegram refused (no delete per picker: two paced sends each) — only the newest
+ * `keyboardStripsPerSweepLimit` of them; the older rest and any failed edit keep their buttons, and with them the hold.
+ */
+export declare function sweepOpenBindMessages(entries: readonly OpenBindMessage[], nowMs: number, ports: BindSweepPorts): Promise<void>;
+//# sourceMappingURL=bindSweep.d.ts.map

package/dist/connectors/telegram/bindSweep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bindSweep.d.ts","sourceRoot":"","sources":["../../../src/connectors/telegram/bindSweep.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAoD,KAAK,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE5G,sDAAsD;AACtD,MAAM,WAAW,cAAc;IAC7B,uHAAuH;IACvH,MAAM,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,sFAAsF;IACtF,QAAQ,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,+DAA+D;IAC/D,cAAc,EAAE,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACpE,mEAAmE;IACnE,cAAc,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACzD;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,UAAU,EAAE,SAAS,MAAM,EAAE,EAC7B,cAAc,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,GACtD,OAAO,CAAC,MAAM,EAAE,CAAC,CAMnB;AAED;;;;;;GAMG;AACH,wBAAsB,qBAAqB,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAWpI"}

package/dist/connectors/telegram/bindSweep.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stripStaleKeyboards = stripStaleKeyboards;
+exports.sweepOpenBindMessages = sweepOpenBindMessages;
+/**
+ * The sweep that closes the open `/bind` messages of a topic once it is bound or has left its folder, written over ports so a
+ * test can reach it: the Telegram calls and the claim list are the caller's. A leaf module (no `bot.ts`, no environment).
+ */
+const openBindMessages_1 = require("./openBindMessages");
+/**
+ * @description Remove the keyboards of messages that can no longer be deleted or must stay as history, the newest
+ * `keyboardStripsPerSweepLimit` of them (`messageIds` oldest first: the newest sit nearest the bottom of the topic): each strip
+ * is a paced send of the bot's one global gate. Resolves the ids whose keyboard is gone — the older rest and every failed edit
+ * still carry theirs.
+ */
+async function stripStaleKeyboards(messageIds, removeKeyboard) {
+    const strippedMessageIds = [];
+    for (const messageId of messageIds.slice(-openBindMessages_1.keyboardStripsPerSweepLimit)) {
+        if (await removeKeyboard(messageId))
+            strippedMessageIds.push(messageId);
+    }
+    return strippedMessageIds;
+}
+/**
+ * @description Close `entries`, the messages a topic had open. Every one is held FIRST, before the first await, so a tap on it is
+ * refused whatever becomes of its message; the hold is let go of for the ones with nothing left to tap — deleted by the bulk
+ * call, or stripped of their buttons. A message too old for Telegram to delete loses its buttons instead, and so does every one
+ * of a bulk call Telegram refused (no delete per picker: two paced sends each) — only the newest
+ * `keyboardStripsPerSweepLimit` of them; the older rest and any failed edit keep their buttons, and with them the hold.
+ */
+async function sweepOpenBindMessages(entries, nowMs, ports) {
+    for (const { messageId } of entries)
+        ports.retire(messageId);
+    const releaseAll = (messageIds) => {
+        for (const messageId of messageIds)
+            ports.unretire(messageId);
+    };
+    const { deletable, tooOld } = (0, openBindMessages_1.splitByDeleteWindow)(entries, nowMs);
+    if (deletable.length > 0) {
+        if (await ports.deleteMessages(deletable))
+            releaseAll(deletable);
+        else
+            releaseAll(await stripStaleKeyboards(deletable, ports.removeKeyboard));
+    }
+    releaseAll(await stripStaleKeyboards(tooOld, ports.removeKeyboard));
+}
+//# sourceMappingURL=bindSweep.js.map

package/dist/connectors/telegram/bindSweep.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bindSweep.js","sourceRoot":"","sources":["../../../src/connectors/telegram/bindSweep.ts"],"names":[],"mappings":";;AAwBA,kDASC;AASD,sDAWC;AArDD;;;GAGG;AACH,yDAA4G;AAc5G;;;;;GAKG;AACI,KAAK,UAAU,mBAAmB,CACvC,UAA6B,EAC7B,cAAuD;IAEvD,MAAM,kBAAkB,GAAa,EAAE,CAAC;IACxC,KAAK,MAAM,SAAS,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC,8CAA2B,CAAC,EAAE,CAAC;QACvE,IAAI,MAAM,cAAc,CAAC,SAAS,CAAC;YAAE,kBAAkB,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAC1E,CAAC;IACD,OAAO,kBAAkB,CAAC;AAC5B,CAAC;AAED;;;;;;GAMG;AACI,KAAK,UAAU,qBAAqB,CAAC,OAAmC,EAAE,KAAa,EAAE,KAAqB;IACnH,KAAK,MAAM,EAAE,SAAS,EAAE,IAAI,OAAO;QAAE,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IAC7D,MAAM,UAAU,GAAG,CAAC,UAA6B,EAAQ,EAAE;QACzD,KAAK,MAAM,SAAS,IAAI,UAAU;YAAE,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;IAChE,CAAC,CAAC;IACF,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,IAAA,sCAAmB,EAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAClE,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzB,IAAI,MAAM,KAAK,CAAC,cAAc,CAAC,SAAS,CAAC;YAAE,UAAU,CAAC,SAAS,CAAC,CAAC;;YAC5D,UAAU,CAAC,MAAM,mBAAmB,CAAC,SAAS,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC;IAC9E,CAAC;IACD,UAAU,CAAC,MAAM,mBAAmB,CAAC,MAAM,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC;AACtE,CAAC"}

package/dist/connectors/telegram/bindingWelcome.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The pure parts of a binding's welcome that name OTHER topics: how a topic that shares the folder is written in the
+ * welcome's «also used by» row. A leaf module (no `bot.ts`, no environment), so a test can reach it.
+ */
+/**
+ * A topic bound to the same folder. `name`: what the bot saw the topic made with (or renamed to by an admin), when it
+ * saw it. `link`: the link that opens the topic, which a person can always follow.
+ */
+export interface SharedTopic {
+    name: string | undefined;
+    link: string;
+}
+/**
+ * @description The row's list, comma-separated: a topic with a name is that name as inline code, one without is its bare
+ * link (Telegram makes it tappable; it is digits and slashes only, so Markdown has nothing to mangle). `moreLabel` —
+ * the count of the topics that are only counted, already worded (`+2 more`) — is the last item: those of OTHER chats, and any
+ * of this chat that has neither a name nor a link to show; a
+ * member of one chat is not told the names, the links or the ids of another's. The welcome is sent as Markdown, where
+ * nothing inside a code span can be escaped, so a backtick in a name (a name is free text) would end the span early — it
+ * becomes an apostrophe instead.
+ */
+export declare function formatSharedTopicList(topics: readonly SharedTopic[], moreLabel?: string | null): string;
+//# sourceMappingURL=bindingWelcome.d.ts.map

package/dist/connectors/telegram/bindingWelcome.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bindingWelcome.d.ts","sourceRoot":"","sources":["../../../src/connectors/telegram/bindingWelcome.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,EAAE,SAAS,GAAE,MAAM,GAAG,IAAW,GAAG,MAAM,CAO7G"}

package/dist/connectors/telegram/bindingWelcome.js

@@ -0,0 +1,26 @@
+"use strict";
+/**
+ * The pure parts of a binding's welcome that name OTHER topics: how a topic that shares the folder is written in the
+ * welcome's «also used by» row. A leaf module (no `bot.ts`, no environment), so a test can reach it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatSharedTopicList = formatSharedTopicList;
+/**
+ * @description The row's list, comma-separated: a topic with a name is that name as inline code, one without is its bare
+ * link (Telegram makes it tappable; it is digits and slashes only, so Markdown has nothing to mangle). `moreLabel` —
+ * the count of the topics that are only counted, already worded (`+2 more`) — is the last item: those of OTHER chats, and any
+ * of this chat that has neither a name nor a link to show; a
+ * member of one chat is not told the names, the links or the ids of another's. The welcome is sent as Markdown, where
+ * nothing inside a code span can be escaped, so a backtick in a name (a name is free text) would end the span early — it
+ * becomes an apostrophe instead.
+ */
+function formatSharedTopicList(topics, moreLabel = null) {
+    const items = topics.map(({ name, link }) => {
+        const label = name?.trim();
+        return label ? `\`${label.replaceAll('`', "'")}\`` : link;
+    });
+    if (moreLabel !== null)
+        items.push(moreLabel);
+    return items.join(', ');
+}
+//# sourceMappingURL=bindingWelcome.js.map

package/dist/connectors/telegram/bindingWelcome.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bindingWelcome.js","sourceRoot":"","sources":["../../../src/connectors/telegram/bindingWelcome.ts"],"names":[],"mappings":";AAAA;;;GAGG;;AAoBH,sDAOC;AAhBD;;;;;;;;GAQG;AACH,SAAgB,qBAAqB,CAAC,MAA8B,EAAE,YAA2B,IAAI;IACnG,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE;QAC1C,MAAM,KAAK,GAAG,IAAI,EAAE,IAAI,EAAE,CAAC;QAC3B,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;IAC5D,CAAC,CAAC,CAAC;IACH,IAAI,SAAS,KAAK,IAAI;QAAE,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAC9C,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/dist/connectors/telegram/botApiConnection.d.ts

@@ -0,0 +1,74 @@
+/**
+ * @description The connections the bot keeps pooled to the Bot API, and what happens when the server closed one the bot
+ * still held.
+ *
+ * The bot keeps its connections alive and reuses them. A server closes an idle one after a while; a client that learns
+ * of it only when it writes its next request (a process starved of CPU, whose event loop has not yet read the close)
+ * gets «socket hang up» / `ECONNRESET` / `EPIPE` for a request the closed connection never delivered. Two layers:
+ *
+ *  1. The agent closes a connection that sat idle in the pool for {@link botApiFreeSocketTimeoutMs} itself, long before
+ *     the server's own idle limit (api.telegram.org kept an idle HTTP/1.1 connection for more than 130 s when measured),
+ *     so an ordinary pause between two sends never meets a connection the server closed. A client stalled past the
+ *     server's limit cannot be helped that way: its timers do not run either, and the stale connection is still in the
+ *     pool when the next request starts. What it meets then depends on the Node: since 22.23.4 the http agent looks for
+ *     what the server already sent on an idle socket before it reuses it («http: ensure agent data guard works without I/O»,
+ *     CVE-2026-105481) and opens a fresh connection; an older Node (`engines` allows 22.12) writes onto the closed one.
+ *  2. {@link wireBotApiClient} makes a client send such a request again ONCE, on a fresh connection — the case of those older
+ *     agents, and on every Node the one of a server that closes the connection as the request is on its way, which no
+ *     client sees coming. It does so only when
+ *     the request rode a REUSED connection (`ClientRequest.reusedSocket`, the signal Node documents for exactly this) and
+ *     the connection failed at once ({@link staleConnectionFailureWindowMs}) with the socket having read not a single byte
+ *     since the reuse: no answer began, not even a partial one, and the server did not sit on the request. A timeout, an
+ *     abort, an answer that began, a failure that came late and a first-time connection are never retried.
+ *
+ * This is a heuristic, not a guarantee. A server that took the request and dropped the connection at once, before a byte of
+ * its answer, looks the same to the client, and there the retry posts the message twice. That case is rare; the alternative
+ * is losing the message every time a pooled connection had been closed.
+ */
+import * as http from 'http';
+import * as https from 'https';
+import type { CallApiHost } from '../../outputTrace';
+/**
+ * @description How long a connection may idle in the pool before the agent closes it. Well under the server's own limit
+ * (the real Bot API held an idle HTTP/1.1 connection for more than 130 s when measured, and sends no `Keep-Alive` hint),
+ * long enough to span the pauses between a topic's sends and the typing indicator, so a streaming reply keeps its warm
+ * connection.
+ *
+ * It is a socket idle timeout, applied by Node only to FREE sockets (`http.Agent` destroys a socket on `timeout` only if
+ * it sits in the free list): a long poll that waits 50 s for an update is not cut.
+ */
+export declare const botApiFreeSocketTimeoutMs = 30000;
+/**
+ * @description How soon after a pooled connection was handed to a request its failure still counts as "the server had
+ * closed it". A closed connection fails within one turn of the event loop of the write — milliseconds, a second on a host
+ * that is starved of CPU —, while a server that took the request, worked on it for long and then dropped the connection
+ * (a slow send under load, a media group, a middlebox) fails later: that request is not retried.
+ */
+export declare const staleConnectionFailureWindowMs = 1000;
+/** The log line of a retry: `<prefix> (<method>): …`. Never carries the bot token. */
+export declare const reusedConnectionRetryLogPrefix = "[telegram] pooled connection was closed by the server, retrying once on a fresh one";
+/**
+ * @description The keep-alive, IPv4-pinned `https.Agent` the Bot API client and the file downloads ride: a warm
+ * connection avoids the cold-handshake stall.
+ */
+export declare function createBotApiHttpsAgent(freeSocketTimeoutMs?: number): https.Agent;
+/**
+ * @description The same pooling for an `http://` API root (the process-level tests' fake on loopback): Telegraf drops its
+ * agent for such a root and node-fetch then falls back to the global agent, which has other limits.
+ */
+export declare function createBotApiHttpAgent(freeSocketTimeoutMs?: number): http.Agent;
+/** A Telegraf `Telegram` client, as far as the wiring needs it. */
+export interface BotApiClient extends CallApiHost {
+    readonly options: {
+        agent?: http.Agent;
+    };
+}
+/**
+ * @description Put the bot's pooling on a Telegraf client: its agent (Telegraf drops the agent of an `http://` root, and
+ * builds every client from options that already lack it) and the retry of a request that met a closed pooled connection.
+ * Telegraf builds a NEW client for every update (`ctx.telegram`, behind `ctx.reply` / `ctx.answerCbQuery` /
+ * `ctx.editMessageText`), so this runs once for `bot.telegram` and once per update for `ctx.telegram`. For `bot.telegram`
+ * call it AFTER the output trace wrap, so the trace records both attempts of a retried request.
+ */
+export declare function wireBotApiClient(telegram: BotApiClient, agent: http.Agent): void;
+//# sourceMappingURL=botApiConnection.d.ts.map

package/dist/connectors/telegram/botApiConnection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"botApiConnection.d.ts","sourceRoot":"","sources":["../../../src/connectors/telegram/botApiConnection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAK/B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGrD;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,QAAS,CAAC;AAKhD;;;;;GAKG;AACH,eAAO,MAAM,8BAA8B,OAAO,CAAC;AAEnD,sFAAsF;AACtF,eAAO,MAAM,8BAA8B,wFAAwF,CAAC;AAkDpI;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,mBAAmB,GAAE,MAAkC,GAAG,KAAK,CAAC,KAAK,CAE3G;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,mBAAmB,GAAE,MAAkC,GAAG,IAAI,CAAC,KAAK,CAEzG;AA0CD,mEAAmE;AACnE,MAAM,WAAW,YAAa,SAAQ,WAAW;IAC/C,QAAQ,CAAC,OAAO,EAAE;QAAE,KAAK,CAAC,EAAE,IAAI,CAAC,KAAK,CAAA;KAAE,CAAC;CAC1C;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,YAAY,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,GAAG,IAAI,CAGhF"}

package/dist/connectors/telegram/botApiConnection.js

@@ -0,0 +1,201 @@
+"use strict";
+/**
+ * @description The connections the bot keeps pooled to the Bot API, and what happens when the server closed one the bot
+ * still held.
+ *
+ * The bot keeps its connections alive and reuses them. A server closes an idle one after a while; a client that learns
+ * of it only when it writes its next request (a process starved of CPU, whose event loop has not yet read the close)
+ * gets «socket hang up» / `ECONNRESET` / `EPIPE` for a request the closed connection never delivered. Two layers:
+ *
+ *  1. The agent closes a connection that sat idle in the pool for {@link botApiFreeSocketTimeoutMs} itself, long before
+ *     the server's own idle limit (api.telegram.org kept an idle HTTP/1.1 connection for more than 130 s when measured),
+ *     so an ordinary pause between two sends never meets a connection the server closed. A client stalled past the
+ *     server's limit cannot be helped that way: its timers do not run either, and the stale connection is still in the
+ *     pool when the next request starts. What it meets then depends on the Node: since 22.23.4 the http agent looks for
+ *     what the server already sent on an idle socket before it reuses it («http: ensure agent data guard works without I/O»,
+ *     CVE-2026-105481) and opens a fresh connection; an older Node (`engines` allows 22.12) writes onto the closed one.
+ *  2. {@link wireBotApiClient} makes a client send such a request again ONCE, on a fresh connection — the case of those older
+ *     agents, and on every Node the one of a server that closes the connection as the request is on its way, which no
+ *     client sees coming. It does so only when
+ *     the request rode a REUSED connection (`ClientRequest.reusedSocket`, the signal Node documents for exactly this) and
+ *     the connection failed at once ({@link staleConnectionFailureWindowMs}) with the socket having read not a single byte
+ *     since the reuse: no answer began, not even a partial one, and the server did not sit on the request. A timeout, an
+ *     abort, an answer that began, a failure that came late and a first-time connection are never retried.
+ *
+ * This is a heuristic, not a guarantee. A server that took the request and dropped the connection at once, before a byte of
+ * its answer, looks the same to the client, and there the retry posts the message twice. That case is rare; the alternative
+ * is losing the message every time a pooled connection had been closed.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reusedConnectionRetryLogPrefix = exports.staleConnectionFailureWindowMs = exports.botApiFreeSocketTimeoutMs = void 0;
+exports.createBotApiHttpsAgent = createBotApiHttpsAgent;
+exports.createBotApiHttpAgent = createBotApiHttpAgent;
+exports.wireBotApiClient = wireBotApiClient;
+const http = __importStar(require("http"));
+const https = __importStar(require("https"));
+const async_hooks_1 = require("async_hooks");
+const net_1 = require("net");
+const perf_hooks_1 = require("perf_hooks");
+const stream_1 = require("stream");
+const sendErrorClassifier_1 = require("../../sendErrorClassifier");
+/**
+ * @description How long a connection may idle in the pool before the agent closes it. Well under the server's own limit
+ * (the real Bot API held an idle HTTP/1.1 connection for more than 130 s when measured, and sends no `Keep-Alive` hint),
+ * long enough to span the pauses between a topic's sends and the typing indicator, so a streaming reply keeps its warm
+ * connection.
+ *
+ * It is a socket idle timeout, applied by Node only to FREE sockets (`http.Agent` destroys a socket on `timeout` only if
+ * it sits in the free list): a long poll that waits 50 s for an update is not cut.
+ */
+exports.botApiFreeSocketTimeoutMs = 30_000;
+/** The initial delay of the TCP keep-alive probes on a pooled connection. */
+const tcpKeepAliveInitialDelayMs = 10_000;
+/**
+ * @description How soon after a pooled connection was handed to a request its failure still counts as "the server had
+ * closed it". A closed connection fails within one turn of the event loop of the write — milliseconds, a second on a host
+ * that is starved of CPU —, while a server that took the request, worked on it for long and then dropped the connection
+ * (a slow send under load, a media group, a middlebox) fails later: that request is not retried.
+ */
+exports.staleConnectionFailureWindowMs = 1000;
+/** The log line of a retry: `<prefix> (<method>): …`. Never carries the bot token. */
+exports.reusedConnectionRetryLogPrefix = '[telegram] pooled connection was closed by the server, retrying once on a fresh one';
+/** How deep a payload is searched for a one-shot stream (`{ media: [{ media: { source: stream } }] }` is the deepest shape). */
+const maxPayloadDepth = 5;
+/**
+ * The probe of the `callApi` that is running, handed to the agent through the async context: node-fetch sits between the
+ * two and keeps nothing of the request on the error it throws.
+ */
+const reuseProbeStorage = new async_hooks_1.AsyncLocalStorage();
+/**
+ * Mark the running `callApi`'s probe when this reused request fails at once ({@link staleConnectionFailureWindowMs}) with the
+ * socket having read nothing since the reuse. The socket's byte count, not the request's `response` event, is the test for
+ * "nothing": that event fires only once a whole response head is parsed, so a connection that delivered half a head — an
+ * answer that began — would pass for a closed one. `bytesRead` is the bytes of the application stream on a TLS socket too (a
+ * `close_notify` alert is not counted).
+ */
+function watchReusedRequest(socket, request) {
+    const probe = reuseProbeStorage.getStore();
+    if (!probe || !(socket instanceof net_1.Socket))
+        return;
+    const bytesReadAtReuse = socket.bytesRead;
+    const reusedAtMs = perf_hooks_1.performance.now();
+    request.once('error', () => {
+        const isAtOnce = perf_hooks_1.performance.now() - reusedAtMs <= exports.staleConnectionFailureWindowMs;
+        if (isAtOnce && socket.bytesRead === bytesReadAtReuse)
+            probe.isPooledConnectionLost = true;
+    });
+}
+/** `agent.reuseSocket` is called by Node, synchronously inside `http.request`, when a pooled socket is handed to a request. */
+function trackReusedConnections(agent) {
+    const reuseSocket = agent.reuseSocket.bind(agent);
+    agent.reuseSocket = (socket, request) => {
+        reuseSocket(socket, request);
+        watchReusedRequest(socket, request);
+    };
+    return agent;
+}
+/** The pooling both agents share. `freeSocketTimeoutMs` is a test seam; production keeps {@link botApiFreeSocketTimeoutMs}. */
+function getBotApiAgentOptions(freeSocketTimeoutMs) {
+    return { keepAlive: true, keepAliveMsecs: tcpKeepAliveInitialDelayMs, family: 4, timeout: freeSocketTimeoutMs };
+}
+/**
+ * @description The keep-alive, IPv4-pinned `https.Agent` the Bot API client and the file downloads ride: a warm
+ * connection avoids the cold-handshake stall.
+ */
+function createBotApiHttpsAgent(freeSocketTimeoutMs = exports.botApiFreeSocketTimeoutMs) {
+    return trackReusedConnections(new https.Agent(getBotApiAgentOptions(freeSocketTimeoutMs)));
+}
+/**
+ * @description The same pooling for an `http://` API root (the process-level tests' fake on loopback): Telegraf drops its
+ * agent for such a root and node-fetch then falls back to the global agent, which has other limits.
+ */
+function createBotApiHttpAgent(freeSocketTimeoutMs = exports.botApiFreeSocketTimeoutMs) {
+    return trackReusedConnections(new http.Agent(getBotApiAgentOptions(freeSocketTimeoutMs)));
+}
+/**
+ * A file handed to Telegraf as a stream can be read once: sending the payload again would upload what is left of it. Also
+ * skips a Buffer (its bytes are not walked) and bounds the walk.
+ */
+function checkIsPayloadReplayable(payload, depth = 0) {
+    if (payload instanceof stream_1.Readable)
+        return false;
+    if (ArrayBuffer.isView(payload) || depth >= maxPayloadDepth)
+        return true;
+    return Object.values(payload).every((value) => typeof value !== 'object' || value === null || checkIsPayloadReplayable(value, depth + 1));
+}
+/** Close every idle pooled connection: one that went stale was idle just as long as its siblings, so a retry must not meet another. */
+function destroyFreeSockets(agent) {
+    for (const sockets of Object.values(agent.freeSockets)) {
+        for (const socket of [...(sockets ?? [])])
+            socket.destroy();
+    }
+}
+/**
+ * Wrap `host.callApi` so a request that rode a reused connection and was dropped before any byte of an answer is sent again
+ * ONCE on a fresh connection (see the module description for what that does and does not guarantee). A second failure is the
+ * caller's, as before. `agent` is the one `host` sends through. Sits BELOW the send queue, the global pacer and the 429
+ * retry — the retry takes no permit, the thread's order is kept — and above the output trace, which therefore shows both
+ * attempts.
+ */
+function installReusedConnectionRetry(host, agent) {
+    const originalCallApi = host.callApi.bind(host);
+    host.callApi = async (method, payload, options) => {
+        const probe = { isPooledConnectionLost: false };
+        try {
+            return await reuseProbeStorage.run(probe, () => originalCallApi(method, payload, options));
+        }
+        catch (error) {
+            const isRetryable = probe.isPooledConnectionLost && (0, sendErrorClassifier_1.checkIsConnectionResetError)(error) && checkIsPayloadReplayable(payload);
+            if (!isRetryable)
+                throw error;
+            console.warn(`${exports.reusedConnectionRetryLogPrefix} (${method})`);
+            destroyFreeSockets(agent);
+            return originalCallApi(method, payload, options);
+        }
+    };
+}
+/**
+ * @description Put the bot's pooling on a Telegraf client: its agent (Telegraf drops the agent of an `http://` root, and
+ * builds every client from options that already lack it) and the retry of a request that met a closed pooled connection.
+ * Telegraf builds a NEW client for every update (`ctx.telegram`, behind `ctx.reply` / `ctx.answerCbQuery` /
+ * `ctx.editMessageText`), so this runs once for `bot.telegram` and once per update for `ctx.telegram`. For `bot.telegram`
+ * call it AFTER the output trace wrap, so the trace records both attempts of a retried request.
+ */
+function wireBotApiClient(telegram, agent) {
+    telegram.options.agent = agent;
+    installReusedConnectionRetry(telegram, agent);
+}
+//# sourceMappingURL=botApiConnection.js.map