@poolzin/pool-bot 2026.2.21 → 2026.2.23

package/dist/telegram/send.js

@@ -1,29 +1,32 @@
 import { Bot, HttpError, InputFile } from "grammy";
 import { loadConfig } from "../config/config.js";
+import { resolveMarkdownTableMode } from "../config/markdown-tables.js";
 import { logVerbose } from "../globals.js";
 import { recordChannelActivity } from "../infra/channel-activity.js";
-import { withTelegramApiErrorLogging } from "./api-logging.js";
-import { formatErrorMessage, formatUncaughtError } from "../infra/errors.js";
 import { isDiagnosticFlagEnabled } from "../infra/diagnostic-flags.js";
+import { formatErrorMessage, formatUncaughtError } from "../infra/errors.js";
 import { createTelegramRetryRunner } from "../infra/retry-policy.js";
 import { redactSensitiveText } from "../logging/redact.js";
 import { createSubsystemLogger } from "../logging/subsystem.js";
 import { mediaKindFromMime } from "../media/constants.js";
 import { isGifMedia } from "../media/mime.js";
+import { normalizePollInput } from "../polls.js";
 import { loadWebMedia } from "../web/media.js";
 import { resolveTelegramAccount } from "./accounts.js";
+import { withTelegramApiErrorLogging } from "./api-logging.js";
+import { buildTelegramThreadParams } from "./bot/helpers.js";
+import { splitTelegramCaption } from "./caption.js";
 import { resolveTelegramFetch } from "./fetch.js";
-import { makeProxyFetch } from "./proxy.js";
 import { renderTelegramHtmlText } from "./format.js";
-import { resolveMarkdownTableMode } from "../config/markdown-tables.js";
 import { isRecoverableTelegramNetworkError } from "./network-errors.js";
-import { splitTelegramCaption } from "./caption.js";
+import { makeProxyFetch } from "./proxy.js";
 import { recordSentMessage } from "./sent-message-cache.js";
 import { parseTelegramTarget, stripTelegramInternalPrefixes } from "./targets.js";
 import { resolveTelegramVoiceSend } from "./voice.js";
-import { buildTelegramThreadParams } from "./bot/helpers.js";
 const PARSE_ERR_RE = /can't parse entities|parse entities|find end of the entity/i;
 const THREAD_NOT_FOUND_RE = /400:\s*Bad Request:\s*message thread not found/i;
+const MESSAGE_NOT_MODIFIED_RE = /400:\s*Bad Request:\s*message is not modified|MESSAGE_NOT_MODIFIED/i;
+const CHAT_NOT_FOUND_RE = /400: Bad Request: chat not found/i;
 const diagLogger = createSubsystemLogger("telegram/diagnostic");
 function createTelegramHttpLogger(cfg) {
     const enabled = isDiagnosticFlagEnabled("telegram.http", cfg);
@@ -31,8 +34,9 @@ function createTelegramHttpLogger(cfg) {
         return () => { };
     }
     return (label, err) => {
-        if (!(err instanceof HttpError))
+        if (!(err instanceof HttpError)) {
             return;
+        }
         const detail = redactSensitiveText(formatUncaughtError(err.error ?? err));
         diagLogger.warn(`telegram http error (${label}): ${detail}`);
     };
@@ -55,8 +59,9 @@ function resolveTelegramClientOptions(account) {
         : undefined;
 }
 function resolveToken(explicit, params) {
-    if (explicit?.trim())
+    if (explicit?.trim()) {
         return explicit.trim();
+    }
     if (!params.token) {
         throw new Error(`Telegram bot token missing for account "${params.accountId}" (set channels.telegram.accounts.${params.accountId}.botToken/tokenFile or TELEGRAM_BOT_TOKEN for default).`);
     }
@@ -64,8 +69,9 @@ function resolveToken(explicit, params) {
 }
 function normalizeChatId(to) {
     const trimmed = to.trim();
-    if (!trimmed)
+    if (!trimmed) {
         throw new Error("Recipient is required for Telegram sends");
+    }
     // Common internal prefixes that sometimes leak into outbound sends.
     // - ctx.To uses `telegram:<id>`
     // - group sessions often use `telegram:group:<id>`
@@ -74,17 +80,22 @@ function normalizeChatId(to) {
     // (Invite links like `t.me/+...` are not resolvable via Bot API.)
     const m = /^https?:\/\/t\.me\/([A-Za-z0-9_]+)$/i.exec(normalized) ??
         /^t\.me\/([A-Za-z0-9_]+)$/i.exec(normalized);
-    if (m?.[1])
+    if (m?.[1]) {
         normalized = `@${m[1]}`;
-    if (!normalized)
+    }
+    if (!normalized) {
         throw new Error("Recipient is required for Telegram sends");
-    if (normalized.startsWith("@"))
+    }
+    if (normalized.startsWith("@")) {
         return normalized;
-    if (/^-?\d+$/.test(normalized))
+    }
+    if (/^-?\d+$/.test(normalized)) {
         return normalized;
+    }
     // If the user passed a username without `@`, assume they meant a public chat/channel.
-    if (/^[A-Za-z0-9_]{5,}$/i.test(normalized))
+    if (/^[A-Za-z0-9_]{5,}$/i.test(normalized)) {
         return `@${normalized}`;
+    }
     return normalized;
 }
 function normalizeMessageId(raw) {
@@ -97,117 +108,192 @@ function normalizeMessageId(raw) {
             throw new Error("Message id is required for Telegram actions");
         }
         const parsed = Number.parseInt(value, 10);
-        if (Number.isFinite(parsed))
+        if (Number.isFinite(parsed)) {
             return parsed;
+        }
     }
     throw new Error("Message id is required for Telegram actions");
 }
 function isTelegramThreadNotFoundError(err) {
     return THREAD_NOT_FOUND_RE.test(formatErrorMessage(err));
 }
+function isTelegramMessageNotModifiedError(err) {
+    return MESSAGE_NOT_MODIFIED_RE.test(formatErrorMessage(err));
+}
 function hasMessageThreadIdParam(params) {
-    if (!params)
+    if (!params) {
         return false;
+    }
     const value = params.message_thread_id;
-    if (typeof value === "number")
+    if (typeof value === "number") {
         return Number.isFinite(value);
-    if (typeof value === "string")
+    }
+    if (typeof value === "string") {
         return value.trim().length > 0;
+    }
     return false;
 }
 function removeMessageThreadIdParam(params) {
-    if (!params || !hasMessageThreadIdParam(params))
+    if (!params || !hasMessageThreadIdParam(params)) {
         return params;
+    }
     const next = { ...params };
     delete next.message_thread_id;
     return Object.keys(next).length > 0 ? next : undefined;
 }
+function isTelegramHtmlParseError(err) {
+    return PARSE_ERR_RE.test(formatErrorMessage(err));
+}
+function buildTelegramThreadReplyParams(params) {
+    const messageThreadId = params.messageThreadId != null ? params.messageThreadId : params.targetMessageThreadId;
+    const threadScope = params.chatType === "direct" ? "dm" : "forum";
+    // Never blanket-strip DM message_thread_id by chat-id sign.
+    // Telegram supports DM topics; stripping silently misroutes topic replies.
+    // Keep thread id and rely on thread-not-found retry fallback for plain DMs.
+    const threadSpec = messageThreadId != null ? { id: messageThreadId, scope: threadScope } : undefined;
+    const threadIdParams = buildTelegramThreadParams(threadSpec);
+    const threadParams = threadIdParams ? { ...threadIdParams } : {};
+    if (params.replyToMessageId != null) {
+        const replyToMessageId = Math.trunc(params.replyToMessageId);
+        if (params.quoteText?.trim()) {
+            threadParams.reply_parameters = {
+                message_id: replyToMessageId,
+                quote: params.quoteText.trim(),
+            };
+        }
+        else {
+            threadParams.reply_to_message_id = replyToMessageId;
+        }
+    }
+    return threadParams;
+}
+async function withTelegramHtmlParseFallback(params) {
+    try {
+        return await params.requestHtml(params.label);
+    }
+    catch (err) {
+        if (!isTelegramHtmlParseError(err)) {
+            throw err;
+        }
+        if (params.verbose) {
+            console.warn(`telegram ${params.label} failed with HTML parse error, retrying as plain text: ${formatErrorMessage(err)}`);
+        }
+        return await params.requestPlain(`${params.label}-plain`);
+    }
+}
+function resolveTelegramApiContext(opts) {
+    const cfg = opts.cfg ?? loadConfig();
+    const account = resolveTelegramAccount({
+        cfg,
+        accountId: opts.accountId,
+    });
+    const token = resolveToken(opts.token, account);
+    const client = resolveTelegramClientOptions(account);
+    const api = (opts.api ?? new Bot(token, client ? { client } : undefined).api);
+    return { cfg, account, api };
+}
+function createTelegramRequestWithDiag(params) {
+    const request = createTelegramRetryRunner({
+        retry: params.retry,
+        configRetry: params.account.config.retry,
+        verbose: params.verbose,
+        ...(params.shouldRetry ? { shouldRetry: params.shouldRetry } : {}),
+    });
+    const logHttpError = createTelegramHttpLogger(params.cfg);
+    return (fn, label, options) => {
+        const runRequest = () => request(fn, label);
+        const call = params.useApiErrorLogging === false
+            ? runRequest()
+            : withTelegramApiErrorLogging({
+                operation: label ?? "request",
+                fn: runRequest,
+                ...(options?.shouldLog ? { shouldLog: options.shouldLog } : {}),
+            });
+        return call.catch((err) => {
+            logHttpError(label ?? "request", err);
+            throw err;
+        });
+    };
+}
+function wrapTelegramChatNotFoundError(err, params) {
+    if (!CHAT_NOT_FOUND_RE.test(formatErrorMessage(err))) {
+        return err;
+    }
+    return new Error([
+        `Telegram send failed: chat not found (chat_id=${params.chatId}).`,
+        "Likely: bot not started in DM, bot removed from group/channel, group migrated (new -100… id), or wrong bot token.",
+        `Input was: ${JSON.stringify(params.input)}.`,
+    ].join(" "));
+}
+async function withTelegramThreadFallback(params, label, verbose, attempt) {
+    try {
+        return await attempt(params, label);
+    }
+    catch (err) {
+        // Do not widen this fallback to cover "chat not found".
+        // chat-not-found is routing/auth/membership/token; stripping thread IDs hides root cause.
+        if (!hasMessageThreadIdParam(params) || !isTelegramThreadNotFoundError(err)) {
+            throw err;
+        }
+        if (verbose) {
+            console.warn(`telegram ${label} failed with message_thread_id, retrying without thread: ${formatErrorMessage(err)}`);
+        }
+        const retriedParams = removeMessageThreadIdParam(params);
+        return await attempt(retriedParams, `${label}-threadless`);
+    }
+}
+function createRequestWithChatNotFound(params) {
+    return async (fn, label) => params.requestWithDiag(fn, label).catch((err) => {
+        throw wrapTelegramChatNotFoundError(err, {
+            chatId: params.chatId,
+            input: params.input,
+        });
+    });
+}
 export function buildInlineKeyboard(buttons) {
-    if (!buttons?.length)
+    if (!buttons?.length) {
         return undefined;
+    }
     const rows = buttons
         .map((row) => row
         .filter((button) => button?.text && button?.callback_data)
         .map((button) => ({
         text: button.text,
         callback_data: button.callback_data,
+        ...(button.style ? { style: button.style } : {}),
     })))
         .filter((row) => row.length > 0);
-    if (rows.length === 0)
+    if (rows.length === 0) {
         return undefined;
+    }
     return { inline_keyboard: rows };
 }
 export async function sendMessageTelegram(to, text, opts = {}) {
-    const cfg = loadConfig();
-    const account = resolveTelegramAccount({
-        cfg,
-        accountId: opts.accountId,
-    });
-    const token = resolveToken(opts.token, account);
+    const { cfg, account, api } = resolveTelegramApiContext(opts);
     const target = parseTelegramTarget(to);
     const chatId = normalizeChatId(target.chatId);
-    // Use provided api or create a new Bot instance. The nullish coalescing
-    // operator ensures api is always defined (Bot.api is always non-null).
-    const client = resolveTelegramClientOptions(account);
-    const api = opts.api ?? new Bot(token, client ? { client } : undefined).api;
     const mediaUrl = opts.mediaUrl?.trim();
     const replyMarkup = buildInlineKeyboard(opts.buttons);
-    // Build optional params for forum topics and reply threading.
-    // Only include these if actually provided to keep API calls clean.
-    const messageThreadId = opts.messageThreadId != null ? opts.messageThreadId : target.messageThreadId;
-    const threadIdParams = buildTelegramThreadParams(messageThreadId);
-    const threadParams = threadIdParams ? { ...threadIdParams } : {};
-    const quoteText = opts.quoteText?.trim();
-    if (opts.replyToMessageId != null) {
-        if (quoteText) {
-            threadParams.reply_parameters = {
-                message_id: Math.trunc(opts.replyToMessageId),
-                quote: quoteText,
-            };
-        }
-        else {
-            threadParams.reply_to_message_id = Math.trunc(opts.replyToMessageId);
-        }
-    }
+    const threadParams = buildTelegramThreadReplyParams({
+        targetMessageThreadId: target.messageThreadId,
+        messageThreadId: opts.messageThreadId,
+        chatType: target.chatType,
+        replyToMessageId: opts.replyToMessageId,
+        quoteText: opts.quoteText,
+    });
     const hasThreadParams = Object.keys(threadParams).length > 0;
-    const request = createTelegramRetryRunner({
+    const requestWithDiag = createTelegramRequestWithDiag({
+        cfg,
+        account,
         retry: opts.retry,
-        configRetry: account.config.retry,
         verbose: opts.verbose,
         shouldRetry: (err) => isRecoverableTelegramNetworkError(err, { context: "send" }),
     });
-    const logHttpError = createTelegramHttpLogger(cfg);
-    const requestWithDiag = (fn, label) => withTelegramApiErrorLogging({
-        operation: label ?? "request",
-        fn: () => request(fn, label),
-    }).catch((err) => {
-        logHttpError(label ?? "request", err);
-        throw err;
+    const requestWithChatNotFound = createRequestWithChatNotFound({
+        requestWithDiag,
+        chatId,
+        input: to,
     });
-    const wrapChatNotFound = (err) => {
-        if (!/400: Bad Request: chat not found/i.test(formatErrorMessage(err)))
-            return err;
-        return new Error([
-            `Telegram send failed: chat not found (chat_id=${chatId}).`,
-            "Likely: bot not started in DM, bot removed from group/channel, group migrated (new -100… id), or wrong bot token.",
-            `Input was: ${JSON.stringify(to)}.`,
-        ].join(" "));
-    };
-    const sendWithThreadFallback = async (params, label, attempt) => {
-        try {
-            return await attempt(params, label);
-        }
-        catch (err) {
-            if (!hasMessageThreadIdParam(params) || !isTelegramThreadNotFoundError(err)) {
-                throw err;
-            }
-            if (opts.verbose) {
-                console.warn(`telegram ${label} failed with message_thread_id, retrying without thread: ${formatErrorMessage(err)}`);
-            }
-            const retriedParams = removeMessageThreadIdParam(params);
-            return await attempt(retriedParams, `${label}-threadless`);
-        }
-    };
     const textMode = opts.textMode ?? "markdown";
     const tableMode = resolveMarkdownTableMode({
         cfg,
@@ -219,7 +305,7 @@ export async function sendMessageTelegram(to, text, opts = {}) {
     const linkPreviewEnabled = account.config.linkPreview ?? true;
     const linkPreviewOptions = linkPreviewEnabled ? undefined : { is_disabled: true };
     const sendTelegramText = async (rawText, params, fallbackText) => {
-        return await sendWithThreadFallback(params, "message", async (effectiveParams, label) => {
+        return await withTelegramThreadFallback(params, "message", opts.verbose, async (effectiveParams, label) => {
             const htmlText = renderHtmlText(rawText);
             const baseParams = effectiveParams ? { ...effectiveParams } : {};
             if (linkPreviewOptions) {
@@ -231,31 +317,26 @@ export async function sendMessageTelegram(to, text, opts = {}) {
                 ...baseParams,
                 ...(opts.silent === true ? { disable_notification: true } : {}),
             };
-            const res = await requestWithDiag(() => api.sendMessage(chatId, htmlText, sendParams), label).catch(async (err) => {
-                // Telegram rejects malformed HTML (e.g., unsupported tags or entities).
-                // When that happens, fall back to plain text so the message still delivers.
-                const errText = formatErrorMessage(err);
-                if (PARSE_ERR_RE.test(errText)) {
-                    if (opts.verbose) {
-                        console.warn(`telegram HTML parse failed, retrying as plain text: ${errText}`);
-                    }
-                    const fallback = fallbackText ?? rawText;
+            return await withTelegramHtmlParseFallback({
+                label,
+                verbose: opts.verbose,
+                requestHtml: (retryLabel) => requestWithChatNotFound(() => api.sendMessage(chatId, htmlText, sendParams), retryLabel),
+                requestPlain: (retryLabel) => {
                     const plainParams = hasBaseParams
                         ? baseParams
                         : undefined;
-                    return await requestWithDiag(() => plainParams
-                        ? api.sendMessage(chatId, fallback, plainParams)
-                        : api.sendMessage(chatId, fallback), `${label}-plain`).catch((err2) => {
-                        throw wrapChatNotFound(err2);
-                    });
-                }
-                throw wrapChatNotFound(err);
+                    return requestWithChatNotFound(() => plainParams
+                        ? api.sendMessage(chatId, fallbackText ?? rawText, plainParams)
+                        : api.sendMessage(chatId, fallbackText ?? rawText), retryLabel);
+                },
             });
-            return res;
         });
     };
     if (mediaUrl) {
-        const media = await loadWebMedia(mediaUrl, opts.maxBytes);
+        const media = await loadWebMedia(mediaUrl, {
+            maxBytes: opts.maxBytes,
+            localRoots: opts.mediaLocalRoots,
+        });
         const kind = mediaKindFromMime(media.contentType ?? undefined);
         const isGif = isGifMedia({
             contentType: media.contentType,
@@ -267,7 +348,6 @@ export async function sendMessageTelegram(to, text, opts = {}) {
         let caption;
         let followUpText;
         if (isVideoNote) {
-            // Video notes don't support captions; send any text as follow-up.
             caption = undefined;
             followUpText = text.trim() ? text : undefined;
         }
@@ -291,52 +371,56 @@ export async function sendMessageTelegram(to, text, opts = {}) {
             ...baseMediaParams,
             ...(opts.silent === true ? { disable_notification: true } : {}),
         };
-        let result;
-        if (isGif) {
-            result = await sendWithThreadFallback(mediaParams, "animation", async (effectiveParams, label) => requestWithDiag(() => api.sendAnimation(chatId, file, effectiveParams), label).catch((err) => {
-                throw wrapChatNotFound(err);
-            }));
-        }
-        else if (kind === "image") {
-            result = await sendWithThreadFallback(mediaParams, "photo", async (effectiveParams, label) => requestWithDiag(() => api.sendPhoto(chatId, file, effectiveParams), label).catch((err) => {
-                throw wrapChatNotFound(err);
-            }));
-        }
-        else if (kind === "video") {
-            if (isVideoNote) {
-                result = await sendWithThreadFallback(mediaParams, "video_note", async (effectiveParams, label) => requestWithDiag(() => api.sendVideoNote(chatId, file, effectiveParams), label).catch((err) => {
-                    throw wrapChatNotFound(err);
-                }));
+        const sendMedia = async (label, sender) => await withTelegramThreadFallback(mediaParams, label, opts.verbose, async (effectiveParams, retryLabel) => requestWithChatNotFound(() => sender(effectiveParams), retryLabel));
+        const mediaSender = (() => {
+            if (isGif) {
+                return {
+                    label: "animation",
+                    sender: (effectiveParams) => api.sendAnimation(chatId, file, effectiveParams),
+                };
             }
-            else {
-                result = await sendWithThreadFallback(mediaParams, "video", async (effectiveParams, label) => requestWithDiag(() => api.sendVideo(chatId, file, effectiveParams), label).catch((err) => {
-                    throw wrapChatNotFound(err);
-                }));
+            if (kind === "image") {
+                return {
+                    label: "photo",
+                    sender: (effectiveParams) => api.sendPhoto(chatId, file, effectiveParams),
+                };
             }
-        }
-        else if (kind === "audio") {
-            const { useVoice } = resolveTelegramVoiceSend({
-                wantsVoice: opts.asVoice === true, // default false (backward compatible)
-                contentType: media.contentType,
-                fileName,
-                logFallback: logVerbose,
-            });
-            if (useVoice) {
-                result = await sendWithThreadFallback(mediaParams, "voice", async (effectiveParams, label) => requestWithDiag(() => api.sendVoice(chatId, file, effectiveParams), label).catch((err) => {
-                    throw wrapChatNotFound(err);
-                }));
+            if (kind === "video") {
+                if (isVideoNote) {
+                    return {
+                        label: "video_note",
+                        sender: (effectiveParams) => api.sendVideoNote(chatId, file, effectiveParams),
+                    };
+                }
+                return {
+                    label: "video",
+                    sender: (effectiveParams) => api.sendVideo(chatId, file, effectiveParams),
+                };
             }
-            else {
-                result = await sendWithThreadFallback(mediaParams, "audio", async (effectiveParams, label) => requestWithDiag(() => api.sendAudio(chatId, file, effectiveParams), label).catch((err) => {
-                    throw wrapChatNotFound(err);
-                }));
+            if (kind === "audio") {
+                const { useVoice } = resolveTelegramVoiceSend({
+                    wantsVoice: opts.asVoice === true, // default false (backward compatible)
+                    contentType: media.contentType,
+                    fileName,
+                    logFallback: logVerbose,
+                });
+                if (useVoice) {
+                    return {
+                        label: "voice",
+                        sender: (effectiveParams) => api.sendVoice(chatId, file, effectiveParams),
+                    };
+                }
+                return {
+                    label: "audio",
+                    sender: (effectiveParams) => api.sendAudio(chatId, file, effectiveParams),
+                };
             }
-        }
-        else {
-            result = await sendWithThreadFallback(mediaParams, "document", async (effectiveParams, label) => requestWithDiag(() => api.sendDocument(chatId, file, effectiveParams), label).catch((err) => {
-                throw wrapChatNotFound(err);
-            }));
-        }
+            return {
+                label: "document",
+                sender: (effectiveParams) => api.sendDocument(chatId, file, effectiveParams),
+            };
+        })();
+        const result = await sendMedia(mediaSender.label, mediaSender.sender);
         const mediaMessageId = String(result?.message_id ?? "unknown");
         const resolvedChatId = String(result?.chat?.id ?? chatId);
         if (result?.message_id) {
@@ -387,30 +471,16 @@ export async function sendMessageTelegram(to, text, opts = {}) {
     return { messageId, chatId: String(res?.chat?.id ?? chatId) };
 }
 export async function reactMessageTelegram(chatIdInput, messageIdInput, emoji, opts = {}) {
-    const cfg = loadConfig();
-    const account = resolveTelegramAccount({
-        cfg,
-        accountId: opts.accountId,
-    });
-    const token = resolveToken(opts.token, account);
+    const { cfg, account, api } = resolveTelegramApiContext(opts);
     const chatId = normalizeChatId(String(chatIdInput));
     const messageId = normalizeMessageId(messageIdInput);
-    const client = resolveTelegramClientOptions(account);
-    const api = opts.api ?? new Bot(token, client ? { client } : undefined).api;
-    const request = createTelegramRetryRunner({
+    const requestWithDiag = createTelegramRequestWithDiag({
+        cfg,
+        account,
         retry: opts.retry,
-        configRetry: account.config.retry,
         verbose: opts.verbose,
         shouldRetry: (err) => isRecoverableTelegramNetworkError(err, { context: "send" }),
     });
-    const logHttpError = createTelegramHttpLogger(cfg);
-    const requestWithDiag = (fn, label) => withTelegramApiErrorLogging({
-        operation: label ?? "request",
-        fn: () => request(fn, label),
-    }).catch((err) => {
-        logHttpError(label ?? "request", err);
-        throw err;
-    });
     const remove = opts.remove === true;
     const trimmedEmoji = emoji.trim();
     // Build the reaction array. We cast emoji to the grammY union type since
@@ -421,62 +491,47 @@ export async function reactMessageTelegram(chatIdInput, messageIdInput, emoji, o
     if (typeof api.setMessageReaction !== "function") {
         throw new Error("Telegram reactions are unavailable in this bot API.");
     }
-    await requestWithDiag(() => api.setMessageReaction(chatId, messageId, reactions), "reaction");
+    try {
+        await requestWithDiag(() => api.setMessageReaction(chatId, messageId, reactions), "reaction");
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (/REACTION_INVALID/i.test(msg)) {
+            return { ok: false, warning: `Reaction unavailable: ${trimmedEmoji}` };
+        }
+        throw err;
+    }
     return { ok: true };
 }
 export async function deleteMessageTelegram(chatIdInput, messageIdInput, opts = {}) {
-    const cfg = loadConfig();
-    const account = resolveTelegramAccount({
-        cfg,
-        accountId: opts.accountId,
-    });
-    const token = resolveToken(opts.token, account);
+    const { cfg, account, api } = resolveTelegramApiContext(opts);
     const chatId = normalizeChatId(String(chatIdInput));
     const messageId = normalizeMessageId(messageIdInput);
-    const client = resolveTelegramClientOptions(account);
-    const api = opts.api ?? new Bot(token, client ? { client } : undefined).api;
-    const request = createTelegramRetryRunner({
+    const requestWithDiag = createTelegramRequestWithDiag({
+        cfg,
+        account,
         retry: opts.retry,
-        configRetry: account.config.retry,
         verbose: opts.verbose,
         shouldRetry: (err) => isRecoverableTelegramNetworkError(err, { context: "send" }),
     });
-    const logHttpError = createTelegramHttpLogger(cfg);
-    const requestWithDiag = (fn, label) => withTelegramApiErrorLogging({
-        operation: label ?? "request",
-        fn: () => request(fn, label),
-    }).catch((err) => {
-        logHttpError(label ?? "request", err);
-        throw err;
-    });
     await requestWithDiag(() => api.deleteMessage(chatId, messageId), "deleteMessage");
     logVerbose(`[telegram] Deleted message ${messageId} from chat ${chatId}`);
     return { ok: true };
 }
 export async function editMessageTelegram(chatIdInput, messageIdInput, text, opts = {}) {
-    const cfg = opts.cfg ?? loadConfig();
-    const account = resolveTelegramAccount({
-        cfg,
-        accountId: opts.accountId,
+    const { cfg, account, api } = resolveTelegramApiContext({
+        ...opts,
+        cfg: opts.cfg,
     });
-    const token = resolveToken(opts.token, account);
     const chatId = normalizeChatId(String(chatIdInput));
     const messageId = normalizeMessageId(messageIdInput);
-    const client = resolveTelegramClientOptions(account);
-    const api = opts.api ?? new Bot(token, client ? { client } : undefined).api;
-    const request = createTelegramRetryRunner({
+    const requestWithDiag = createTelegramRequestWithDiag({
+        cfg,
+        account,
         retry: opts.retry,
-        configRetry: account.config.retry,
         verbose: opts.verbose,
     });
-    const logHttpError = createTelegramHttpLogger(cfg);
-    const requestWithDiag = (fn, label) => withTelegramApiErrorLogging({
-        operation: label ?? "request",
-        fn: () => request(fn, label),
-    }).catch((err) => {
-        logHttpError(label ?? "request", err);
-        throw err;
-    });
+    const requestWithEditShouldLog = (fn, label, shouldLog) => requestWithDiag(fn, label, shouldLog ? { shouldLog } : undefined);
     const textMode = opts.textMode ?? "markdown";
     const tableMode = resolveMarkdownTableMode({
         cfg,
@@ -494,26 +549,37 @@ export async function editMessageTelegram(chatIdInput, messageIdInput, text, opt
     const editParams = {
         parse_mode: "HTML",
     };
+    if (opts.linkPreview === false) {
+        editParams.link_preview_options = { is_disabled: true };
+    }
     if (replyMarkup !== undefined) {
         editParams.reply_markup = replyMarkup;
     }
-    await requestWithDiag(() => api.editMessageText(chatId, messageId, htmlText, editParams), "editMessage").catch(async (err) => {
-        // Telegram rejects malformed HTML. Fall back to plain text.
-        const errText = formatErrorMessage(err);
-        if (PARSE_ERR_RE.test(errText)) {
-            if (opts.verbose) {
-                console.warn(`telegram HTML parse failed, retrying as plain text: ${errText}`);
-            }
-            const plainParams = {};
-            if (replyMarkup !== undefined) {
-                plainParams.reply_markup = replyMarkup;
-            }
-            return await requestWithDiag(() => Object.keys(plainParams).length > 0
+    const plainParams = {};
+    if (opts.linkPreview === false) {
+        plainParams.link_preview_options = { is_disabled: true };
+    }
+    if (replyMarkup !== undefined) {
+        plainParams.reply_markup = replyMarkup;
+    }
+    try {
+        await withTelegramHtmlParseFallback({
+            label: "editMessage",
+            verbose: opts.verbose,
+            requestHtml: (retryLabel) => requestWithEditShouldLog(() => api.editMessageText(chatId, messageId, htmlText, editParams), retryLabel, (err) => !isTelegramMessageNotModifiedError(err)),
+            requestPlain: (retryLabel) => requestWithEditShouldLog(() => Object.keys(plainParams).length > 0
                 ? api.editMessageText(chatId, messageId, text, plainParams)
-                : api.editMessageText(chatId, messageId, text), "editMessage-plain");
+                : api.editMessageText(chatId, messageId, text), retryLabel, (plainErr) => !isTelegramMessageNotModifiedError(plainErr)),
+        });
+    }
+    catch (err) {
+        if (isTelegramMessageNotModifiedError(err)) {
+            // no-op: Telegram reports message content unchanged, treat as success
         }
-        throw err;
-    });
+        else {
+            throw err;
+        }
+    }
     logVerbose(`[telegram] Edited message ${messageId} in chat ${chatId}`);
     return { ok: true, messageId: String(messageId), chatId };
 }
@@ -539,70 +605,164 @@ export async function sendStickerTelegram(to, fileId, opts = {}) {
     if (!fileId?.trim()) {
         throw new Error("Telegram sticker file_id is required");
     }
+    const { cfg, account, api } = resolveTelegramApiContext(opts);
+    const target = parseTelegramTarget(to);
+    const chatId = normalizeChatId(target.chatId);
+    const threadParams = buildTelegramThreadReplyParams({
+        targetMessageThreadId: target.messageThreadId,
+        messageThreadId: opts.messageThreadId,
+        chatType: target.chatType,
+        replyToMessageId: opts.replyToMessageId,
+    });
+    const hasThreadParams = Object.keys(threadParams).length > 0;
+    const requestWithDiag = createTelegramRequestWithDiag({
+        cfg,
+        account,
+        retry: opts.retry,
+        verbose: opts.verbose,
+        useApiErrorLogging: false,
+    });
+    const requestWithChatNotFound = createRequestWithChatNotFound({
+        requestWithDiag,
+        chatId,
+        input: to,
+    });
+    const stickerParams = hasThreadParams ? threadParams : undefined;
+    const result = await withTelegramThreadFallback(stickerParams, "sticker", opts.verbose, async (effectiveParams, label) => requestWithChatNotFound(() => api.sendSticker(chatId, fileId.trim(), effectiveParams), label));
+    const messageId = String(result?.message_id ?? "unknown");
+    const resolvedChatId = String(result?.chat?.id ?? chatId);
+    if (result?.message_id) {
+        recordSentMessage(chatId, result.message_id);
+    }
+    recordChannelActivity({
+        channel: "telegram",
+        accountId: account.accountId,
+        direction: "outbound",
+    });
+    return { messageId, chatId: resolvedChatId };
+}
+/**
+ * Send a poll to a Telegram chat.
+ * @param to - Chat ID or username (e.g., "123456789" or "@username")
+ * @param poll - Poll input with question, options, maxSelections, and optional durationHours
+ * @param opts - Optional configuration
+ */
+export async function sendPollTelegram(to, poll, opts = {}) {
+    const { cfg, account, api } = resolveTelegramApiContext(opts);
+    const target = parseTelegramTarget(to);
+    const chatId = normalizeChatId(target.chatId);
+    // Normalize the poll input (validates question, options, maxSelections)
+    const normalizedPoll = normalizePollInput(poll, { maxOptions: 10 });
+    const threadParams = buildTelegramThreadReplyParams({
+        targetMessageThreadId: target.messageThreadId,
+        messageThreadId: opts.messageThreadId,
+        chatType: target.chatType,
+        replyToMessageId: opts.replyToMessageId,
+    });
+    // Build poll options as simple strings (Grammy accepts string[] or InputPollOption[])
+    const pollOptions = normalizedPoll.options;
+    const requestWithDiag = createTelegramRequestWithDiag({
+        cfg,
+        account,
+        retry: opts.retry,
+        verbose: opts.verbose,
+        shouldRetry: (err) => isRecoverableTelegramNetworkError(err, { context: "send" }),
+    });
+    const requestWithChatNotFound = createRequestWithChatNotFound({
+        requestWithDiag,
+        chatId,
+        input: to,
+    });
+    const durationSeconds = normalizedPoll.durationSeconds;
+    if (durationSeconds === undefined && normalizedPoll.durationHours !== undefined) {
+        throw new Error("Telegram poll durationHours is not supported. Use durationSeconds (5-600) instead.");
+    }
+    if (durationSeconds !== undefined && (durationSeconds < 5 || durationSeconds > 600)) {
+        throw new Error("Telegram poll durationSeconds must be between 5 and 600");
+    }
+    // Build poll parameters following Grammy's api.sendPoll signature
+    // sendPoll(chat_id, question, options, other?, signal?)
+    const pollParams = {
+        allows_multiple_answers: normalizedPoll.maxSelections > 1,
+        is_anonymous: opts.isAnonymous ?? true,
+        ...(durationSeconds !== undefined ? { open_period: durationSeconds } : {}),
+        ...(Object.keys(threadParams).length > 0 ? threadParams : {}),
+        ...(opts.silent === true ? { disable_notification: true } : {}),
+    };
+    const result = await withTelegramThreadFallback(pollParams, "poll", opts.verbose, async (effectiveParams, label) => requestWithChatNotFound(() => api.sendPoll(chatId, normalizedPoll.question, pollOptions, effectiveParams), label));
+    const messageId = String(result?.message_id ?? "unknown");
+    const resolvedChatId = String(result?.chat?.id ?? chatId);
+    const pollId = result?.poll?.id;
+    if (result?.message_id) {
+        recordSentMessage(chatId, result.message_id);
+    }
+    recordChannelActivity({
+        channel: "telegram",
+        accountId: account.accountId,
+        direction: "outbound",
+    });
+    return { messageId, chatId: resolvedChatId, pollId };
+}
+/**
+ * Create a forum topic in a Telegram supergroup.
+ * Requires the bot to have `can_manage_topics` permission.
+ *
+ * @param chatId - Supergroup chat ID
+ * @param name - Topic name (1-128 characters)
+ * @param opts - Optional configuration
+ */
+export async function createForumTopicTelegram(chatId, name, opts = {}) {
+    if (!name?.trim()) {
+        throw new Error("Forum topic name is required");
+    }
+    const trimmedName = name.trim();
+    if (trimmedName.length > 128) {
+        throw new Error("Forum topic name must be 128 characters or fewer");
+    }
     const cfg = loadConfig();
     const account = resolveTelegramAccount({
         cfg,
         accountId: opts.accountId,
     });
     const token = resolveToken(opts.token, account);
-    const target = parseTelegramTarget(to);
-    const chatId = normalizeChatId(target.chatId);
+    // Accept topic-qualified targets (e.g. telegram:group:<id>:topic:<thread>)
+    // but createForumTopic must always target the base supergroup chat id.
+    const target = parseTelegramTarget(chatId);
+    const normalizedChatId = normalizeChatId(target.chatId);
     const client = resolveTelegramClientOptions(account);
     const api = opts.api ?? new Bot(token, client ? { client } : undefined).api;
-    const messageThreadId = opts.messageThreadId != null ? opts.messageThreadId : target.messageThreadId;
-    const threadIdParams = buildTelegramThreadParams(messageThreadId);
-    const threadParams = threadIdParams ? { ...threadIdParams } : {};
-    if (opts.replyToMessageId != null) {
-        threadParams.reply_to_message_id = Math.trunc(opts.replyToMessageId);
-    }
-    const hasThreadParams = Object.keys(threadParams).length > 0;
     const request = createTelegramRetryRunner({
         retry: opts.retry,
         configRetry: account.config.retry,
         verbose: opts.verbose,
+        shouldRetry: (err) => isRecoverableTelegramNetworkError(err, { context: "send" }),
     });
     const logHttpError = createTelegramHttpLogger(cfg);
-    const requestWithDiag = (fn, label) => request(fn, label).catch((err) => {
+    const requestWithDiag = (fn, label) => withTelegramApiErrorLogging({
+        operation: label ?? "request",
+        fn: () => request(fn, label),
+    }).catch((err) => {
         logHttpError(label ?? "request", err);
         throw err;
     });
-    const wrapChatNotFound = (err) => {
-        if (!/400: Bad Request: chat not found/i.test(formatErrorMessage(err)))
-            return err;
-        return new Error([
-            `Telegram send failed: chat not found (chat_id=${chatId}).`,
-            "Likely: bot not started in DM, bot removed from group/channel, group migrated (new -100… id), or wrong bot token.",
-            `Input was: ${JSON.stringify(to)}.`,
-        ].join(" "));
-    };
-    const sendWithStickerThreadFallback = async (params, label, attempt) => {
-        try {
-            return await attempt(params, label);
-        }
-        catch (err) {
-            if (!hasMessageThreadIdParam(params) || !isTelegramThreadNotFoundError(err)) {
-                throw err;
-            }
-            if (opts.verbose) {
-                console.warn(`telegram ${label} failed with message_thread_id, retrying without thread: ${formatErrorMessage(err)}`);
-            }
-            const retriedParams = removeMessageThreadIdParam(params);
-            return await attempt(retriedParams, `${label}-threadless`);
-        }
-    };
-    const stickerParams = hasThreadParams ? threadParams : undefined;
-    const result = await sendWithStickerThreadFallback(stickerParams, "sticker", async (effectiveParams, label) => requestWithDiag(() => api.sendSticker(chatId, fileId.trim(), effectiveParams), label).catch((err) => {
-        throw wrapChatNotFound(err);
-    }));
-    const messageId = String(result?.message_id ?? "unknown");
-    const resolvedChatId = String(result?.chat?.id ?? chatId);
-    if (result?.message_id) {
-        recordSentMessage(chatId, result.message_id);
+    const extra = {};
+    if (opts.iconColor != null) {
+        extra.icon_color = opts.iconColor;
+    }
+    if (opts.iconCustomEmojiId?.trim()) {
+        extra.icon_custom_emoji_id = opts.iconCustomEmojiId.trim();
     }
+    const hasExtra = Object.keys(extra).length > 0;
+    const result = await requestWithDiag(() => api.createForumTopic(normalizedChatId, trimmedName, hasExtra ? extra : undefined), "createForumTopic");
+    const topicId = result.message_thread_id;
     recordChannelActivity({
         channel: "telegram",
         accountId: account.accountId,
         direction: "outbound",
     });
-    return { messageId, chatId: resolvedChatId };
+    return {
+        topicId,
+        name: result.name ?? trimmedName,
+        chatId: normalizedChatId,
+    };
 }