@cogitator-ai/channels 0.7.6 → 0.8.0

package/dist/channels/telegram.js

@@ -1,36 +1,154 @@
 import { createServer } from 'node:http';
-const NOT_MODIFIED = 'message is not modified';
+import { adaptMarkdown } from '../formatters/markdown.js';
+/** Telegram's limit for a classic message and for a media caption. */
+const TEXT_LIMIT = 4096;
+const CAPTION_LIMIT = 1024;
+/** Telegram's limit for a rich message's text. */
+const RICH_LIMIT = 32768;
+const CALLBACK_DATA_BYTES = 64;
+const COMMAND_RE = /^[a-z0-9_]{1,32}$/;
 function errorMessage(err) {
     return err instanceof Error ? err.message : String(err);
 }
+function errorCode(err) {
+    const code = err?.error_code;
+    return typeof code === 'number' ? code : undefined;
+}
 function isEntityParseError(err) {
     const msg = errorMessage(err);
     return msg.includes("can't parse entities") || msg.includes("Bad Request: can't parse");
 }
 function isNotModifiedError(err) {
-    return errorMessage(err).includes(NOT_MODIFIED);
+    return errorMessage(err).includes('message is not modified');
+}
+/** A request Telegram refused as malformed or unknown, which a simpler form may get through. */
+function isRefused(err) {
+    const code = errorCode(err);
+    return code === 400 || code === 404 || isEntityParseError(err);
+}
+/** Telegram answers 404 to a method this Bot API server does not know. */
+function isUnknownMethod(err) {
+    return errorCode(err) === 404 || /method not found/i.test(errorMessage(err));
+}
+/** A chat id as Telegram takes it: a number, or a public `@username`. */
+export function telegramChatId(id) {
+    return /^-?\d+$/.test(id) ? Number(id) : id;
+}
+function isPrivateChat(id) {
+    return /^\d+$/.test(id);
+}
+/** The inline keyboard for rows of buttons. */
+export function telegramKeyboard(rows) {
+    return {
+        inline_keyboard: rows.map((row) => row.map((button) => {
+            const base = { text: button.text, ...(button.style && { style: button.style }) };
+            if (button.disabled)
+                return { ...base, disabled: {} };
+            if (button.url !== undefined)
+                return { ...base, url: button.url };
+            if (button.copyText !== undefined)
+                return { ...base, copy_text: { text: button.copyText } };
+            if (button.data !== undefined) {
+                if (new TextEncoder().encode(button.data).length > CALLBACK_DATA_BYTES) {
+                    throw new Error(`Button "${button.text}" carries more than ${CALLBACK_DATA_BYTES} bytes of data`);
+                }
+                return { ...base, callback_data: button.data };
+            }
+            throw new Error(`Button "${button.text}" needs data, url, copyText or disabled`);
+        })),
+    };
+}
+function linkPreviewOptions(preview) {
+    if (preview === undefined)
+        return undefined;
+    if (preview === false)
+        return { is_disabled: true };
+    return {
+        ...(preview.url && { url: preview.url }),
+        ...(preview.aboveText && { show_above_text: true }),
+        ...(preview.size === 'small' && { prefer_small_media: true }),
+        ...(preview.size === 'large' && { prefer_large_media: true }),
+    };
 }
+/** Splits text at line breaks or spaces so every piece fits Telegram's limit. */
+function chunk(text, limit) {
+    const pieces = [];
+    let rest = text;
+    while (rest.length > limit) {
+        const window = rest.slice(0, limit);
+        const newline = window.lastIndexOf('\n');
+        const space = window.lastIndexOf(' ');
+        const at = newline >= limit / 2 ? newline + 1 : space > 0 ? space + 1 : limit;
+        pieces.push(rest.slice(0, at).trimEnd());
+        rest = rest.slice(at);
+    }
+    if (rest.trim() || pieces.length === 0)
+        pieces.push(rest);
+    return pieces;
+}
+function sentId(result) {
+    const id = result?.message_id;
+    return id === undefined ? '' : String(id);
+}
+/**
+ * Telegram through grammY, on the current Bot API: rich messages that render standard Markdown,
+ * streamed drafts with a stop button, inline buttons with colors and their presses, topics,
+ * captions and albums, message effects, link previews, ephemeral messages and command menus.
+ * Every call goes through grammY's raw API, so a Bot API feature newer than the installed grammY
+ * still works, and `call` reaches any method this class does not wrap.
+ */
 export class TelegramChannel {
     config;
     type = 'telegram';
     handler = null;
+    actionHandler = null;
+    stopHandler = null;
     bot = null;
     grammy = null;
     server = null;
+    /** Set when the Bot API server does not know rich messages, so they are not tried again. */
+    richUnavailable = false;
     constructor(config) {
         this.config = config;
     }
+    /**
+     * With rich messages on, Markdown arrives as written (GitHub Flavored) and is adapted to
+     * Telegram's classic Markdown here when a rich message cannot be sent.
+     */
+    get nativeMarkdown() {
+        return this.config.richMessages !== false;
+    }
+    get maxMessageChars() {
+        return this.nativeMarkdown ? RICH_LIMIT : TEXT_LIMIT;
+    }
+    /** Text for a classic message: Markdown written for rich messages is adapted first. */
+    classic(text, format) {
+        return format === 'markdown' && this.nativeMarkdown ? adaptMarkdown(text, 'telegram') : text;
+    }
     onMessage(handler) {
         this.handler = handler;
     }
+    onAction(handler) {
+        this.actionHandler = handler;
+    }
+    onStop(handler) {
+        this.stopHandler = handler;
+    }
+    /** Calls any Bot API method by name, for features this class does not wrap. */
+    async call(method, args = {}) {
+        const bot = this.requireBot();
+        const fn = bot.api.raw[method];
+        if (!fn)
+            throw new Error(`Telegram method ${method} is not available`);
+        return (await fn(args));
+    }
     requireBot() {
         if (!this.bot)
             throw new Error('Telegram channel is not started');
         return this.bot;
     }
     async downloadFile(fileId) {
-        const bot = this.requireBot();
-        const file = await bot.api.getFile(fileId);
+        const file = await this.call('getFile', { file_id: fileId });
         if (!file.file_path)
             throw new Error('Telegram returned no file_path');
         const url = `https://api.telegram.org/file/bot${this.config.token}/${file.file_path}`;
@@ -41,6 +159,7 @@ export class TelegramChannel {
     }
     buildBaseMessage(ctx) {
         const replyTo = ctx.message.reply_to_message?.message_id;
+        const topic = ctx.message.message_thread_id;
         return {
             id: String(ctx.message.message_id),
             channelType: 'telegram',
@@ -49,6 +168,9 @@ export class TelegramChannel {
             userName: ctx.from.first_name + (ctx.from.last_name ? ` ${ctx.from.last_name}` : ''),
             groupId: ctx.chat.type !== 'private' ? String(ctx.chat.id) : undefined,
             ...(replyTo !== undefined ? { replyTo: String(replyTo) } : {}),
+            ...(topic !== undefined && (ctx.message.is_topic_message || ctx.chat.type === 'private')
+                ? { topicId: String(topic) }
+                : {}),
         };
     }
     async emitWithFile(ctx, file, attachment) {
@@ -83,6 +205,43 @@ export class TelegramChannel {
         bot.catch((err) => {
             console.error('[telegram] Bot error:', err);
         });
+        bot.use(async (ctx, next) => {
+            const stopped = ctx.update.stopped_message_generation;
+            if (!stopped) {
+                await next();
+                return;
+            }
+            this.stopHandler?.({
+                channelType: 'telegram',
+                channelId: String(stopped.chat.id),
+                draftId: stopped.draft_id,
+                ...(stopped.message_thread_id !== undefined
+                    ? { topicId: String(stopped.message_thread_id) }
+                    : {}),
+            });
+        });
+        bot.on('callback_query:data', async (ctx) => {
+            const query = ctx.callbackQuery;
+            if (!query?.data)
+                return;
+            if (!this.actionHandler) {
+                await this.answerAction(query.id).catch(() => { });
+                return;
+            }
+            const message = query.message;
+            const topic = message?.message_thread_id;
+            await this.actionHandler({
+                id: query.id,
+                channelType: 'telegram',
+                channelId: String(message?.chat?.id ?? query.from.id),
+                userId: String(query.from.id),
+                userName: query.from.first_name + (query.from.last_name ? ` ${query.from.last_name}` : ''),
+                ...(message ? { messageId: String(message.message_id) } : {}),
+                ...(topic !== undefined ? { topicId: String(topic) } : {}),
+                data: query.data,
+                raw: ctx,
+            });
+        });
         bot.on('message:text', async (ctx) => {
             if (!this.handler)
                 return;
@@ -131,9 +290,29 @@ export class TelegramChannel {
                 filename: video.file_name,
             });
         });
+        bot.on('message:video_note', async (ctx) => {
+            const note = ctx.message.video_note;
+            if (!note)
+                return;
+            await this.emitWithFile(ctx, note, {
+                type: 'video',
+                mimeType: 'video/mp4',
+                filename: 'video_note.mp4',
+            });
+        });
+        bot.on('message:animation', async (ctx) => {
+            const animation = ctx.message.animation;
+            if (!animation)
+                return;
+            await this.emitWithFile(ctx, animation, {
+                type: 'video',
+                mimeType: animation.mime_type ?? 'video/mp4',
+                filename: animation.file_name,
+            });
+        });
         bot.on('message:document', async (ctx) => {
             const doc = ctx.message.document;
-            if (!doc)
+            if (!doc || ctx.message.animation)
                 return;
             const isImage = doc.mime_type?.startsWith('image/') ?? false;
             await this.emitWithFile(ctx, doc, {
@@ -194,7 +373,8 @@ export class TelegramChannel {
             });
         });
         this.server = server;
-        await bot.api.setWebhook(webhook.url, {
+        await bot.api.raw.setWebhook({
+            url: webhook.url,
             drop_pending_updates: true,
             ...(this.config.allowedUpdates ? { allowed_updates: this.config.allowedUpdates } : {}),
             ...(webhook.secretToken ? { secret_token: webhook.secretToken } : {}),
@@ -219,12 +399,11 @@ export class TelegramChannel {
             await bot.stop();
         }
     }
-    async sendText(channelId, text, options) {
-        const bot = this.requireBot();
-        const chatId = Number(channelId);
-        const useMarkdown = options?.format === 'markdown';
-        const baseOpts = {
-            ...(options?.replyTo
+    /** The parameters every send shares: topic, reply, notification, protection, effect, buttons. */
+    envelope(options) {
+        return {
+            ...(options.topicId ? { message_thread_id: Number(options.topicId) } : {}),
+            ...(options.replyTo
                 ? {
                     reply_parameters: {
                         message_id: Number(options.replyTo),
@@ -232,97 +411,405 @@ export class TelegramChannel {
                     },
                 }
                 : {}),
-            ...(options?.silent ? { disable_notification: true } : {}),
+            ...(options.silent ? { disable_notification: true } : {}),
+            ...(options.protect ? { protect_content: true } : {}),
+            ...(options.effect ? { message_effect_id: options.effect } : {}),
+            ...(options.visibleTo
+                ? { ephemeral_message_parameters: { receiver_user_id: Number(options.visibleTo) } }
+                : {}),
+            ...(options.buttons?.length ? { reply_markup: telegramKeyboard(options.buttons) } : {}),
         };
-        if (useMarkdown) {
+    }
+    get useRich() {
+        return this.config.richMessages !== false && !this.richUnavailable;
+    }
+    /** Notes a refusal of a rich call, so an unknown method is not tried again. */
+    richRefused(err) {
+        if (isUnknownMethod(err))
+            this.richUnavailable = true;
+    }
+    async sendText(channelId, text, options = {}) {
+        const chatId = telegramChatId(channelId);
+        if (options.format === 'markdown' && this.useRich) {
             try {
-                const sent = await bot.api.sendMessage(chatId, text, {
-                    ...baseOpts,
-                    parse_mode: 'Markdown',
+                const sent = await this.call('sendRichMessage', {
+                    chat_id: chatId,
+                    rich_message: { markdown: text },
+                    ...this.envelope(options),
                 });
-                return String(sent.message_id);
+                return sentId(sent);
             }
             catch (err) {
-                if (!isEntityParseError(err))
+                if (!isRefused(err))
                     throw err;
+                this.richRefused(err);
             }
         }
-        const sent = await bot.api.sendMessage(chatId, text, baseOpts);
-        return String(sent.message_id);
+        return this.sendClassic(chatId, this.classic(text, options.format), options);
     }
-    async editText(channelId, messageId, text) {
-        const bot = this.requireBot();
-        const chatId = Number(channelId);
-        const msgId = Number(messageId);
+    /**
+     * A text message in Telegram's classic formatting, in as many messages as the limit needs:
+     * the reply goes on the first, the buttons on the last, and a parse failure is sent as plain
+     * text.
+     */
+    async sendClassic(chatId, text, options) {
+        const parseMode = options.format === 'html' ? 'HTML' : options.format === 'markdown' ? 'Markdown' : undefined;
+        const pieces = chunk(text, TEXT_LIMIT);
+        const preview = linkPreviewOptions(options.linkPreview);
+        let first = '';
+        for (let i = 0; i < pieces.length; i++) {
+            const piece = pieces[i] ?? '';
+            const envelope = this.envelope({
+                ...options,
+                ...(i > 0 ? { replyTo: undefined } : {}),
+                ...(i < pieces.length - 1 ? { buttons: undefined } : {}),
+            });
+            const args = {
+                chat_id: chatId,
+                text: piece,
+                ...envelope,
+                ...(preview ? { link_preview_options: preview } : {}),
+            };
+            let sent;
+            if (parseMode) {
+                try {
+                    sent = await this.call('sendMessage', { ...args, parse_mode: parseMode });
+                }
+                catch (err) {
+                    if (!isEntityParseError(err))
+                        throw err;
+                    sent = await this.call('sendMessage', args);
+                }
+            }
+            else {
+                sent = await this.call('sendMessage', args);
+            }
+            if (i === 0)
+                first = sentId(sent);
+        }
+        return first;
+    }
+    async editText(channelId, messageId, text, options = {}) {
+        const chatId = telegramChatId(channelId);
+        const format = options.format ?? 'markdown';
+        const target = {
+            chat_id: chatId,
+            message_id: Number(messageId),
+            ...(options.buttons ? { reply_markup: telegramKeyboard(options.buttons) } : {}),
+        };
+        if (format === 'markdown' && this.useRich) {
+            try {
+                await this.call('editMessageText', { ...target, rich_message: { markdown: text } });
+                return;
+            }
+            catch (err) {
+                if (isNotModifiedError(err))
+                    return;
+                if (!isRefused(err))
+                    throw err;
+                this.richRefused(err);
+            }
+        }
+        const classicText = this.classic(text, format);
+        const clipped = classicText.length > TEXT_LIMIT ? classicText.slice(0, TEXT_LIMIT) : classicText;
+        const parseMode = format === 'html' ? 'HTML' : format === 'markdown' ? 'Markdown' : undefined;
         try {
-            await bot.api.editMessageText(chatId, msgId, text, { parse_mode: 'Markdown' });
+            await this.call('editMessageText', {
+                ...target,
+                text: clipped,
+                ...(parseMode ? { parse_mode: parseMode } : {}),
+            });
             return;
         }
         catch (err) {
             if (isNotModifiedError(err))
                 return;
-            if (!isEntityParseError(err))
+            if (!parseMode || !isEntityParseError(err))
                 throw err;
         }
         try {
-            await bot.api.editMessageText(chatId, msgId, text);
+            await this.call('editMessageText', { ...target, text: clipped });
         }
         catch (err) {
             if (!isNotModifiedError(err))
                 throw err;
         }
     }
-    async sendFile(channelId, file) {
-        const bot = this.requireBot();
-        const chatId = Number(channelId);
-        let source;
+    source(file) {
         if (file.buffer) {
             if (!this.grammy)
                 throw new Error('Telegram channel is not started');
-            source = new this.grammy.InputFile(file.buffer, file.filename);
-        }
-        else if (file.url) {
-            source = file.url;
-        }
-        else {
-            throw new Error('Attachment must have either a buffer or a url');
+            return new this.grammy.InputFile(file.buffer, file.filename);
         }
+        if (file.url)
+            return file.url;
+        throw new Error('Attachment must have either a buffer or a url');
+    }
+    /** The Bot API method and field a file is sent with. */
+    static mediaKind(file) {
+        const mime = file.mimeType.toLowerCase();
         switch (file.type) {
             case 'image':
-                await bot.api.sendPhoto(chatId, source);
-                return;
-            case 'audio':
-                await bot.api.sendAudio(chatId, source);
-                return;
+                return mime === 'image/gif'
+                    ? { method: 'sendAnimation', field: 'animation' }
+                    : { method: 'sendPhoto', field: 'photo' };
             case 'video':
-                await bot.api.sendVideo(chatId, source);
-                return;
+                return { method: 'sendVideo', field: 'video' };
+            case 'audio':
+                return mime.includes('ogg') || mime.includes('opus')
+                    ? { method: 'sendVoice', field: 'voice' }
+                    : { method: 'sendAudio', field: 'audio' };
             default:
-                await bot.api.sendDocument(chatId, source);
+                return { method: 'sendDocument', field: 'document' };
+        }
+    }
+    /** A caption in classic formatting, or none when it is too long to be one. */
+    caption(text, format) {
+        if (!text || text.length > CAPTION_LIMIT)
+            return {};
+        if (format === 'html')
+            return { caption: text, parse_mode: 'HTML' };
+        if (format === 'markdown') {
+            return { caption: this.classic(text, format), parse_mode: 'Markdown' };
+        }
+        return { caption: text };
+    }
+    /** Sends one file and returns the id of its message. */
+    async sendFile(channelId, file, options = {}) {
+        const chatId = telegramChatId(channelId);
+        const { method, field } = TelegramChannel.mediaKind(file);
+        const longCaption = (file.caption?.length ?? 0) > CAPTION_LIMIT;
+        const args = {
+            chat_id: chatId,
+            [field]: this.source(file),
+            ...this.caption(file.caption, options.format),
+            ...this.envelope(longCaption ? { ...options, buttons: undefined } : options),
+        };
+        let sent;
+        try {
+            sent = await this.call(method, args);
         }
+        catch (err) {
+            if (!('parse_mode' in args) || !isEntityParseError(err))
+                throw err;
+            const { parse_mode: _mode, ...plain } = args;
+            sent = await this.call(method, { ...plain, caption: file.caption });
+        }
+        if (longCaption && file.caption) {
+            await this.sendText(channelId, file.caption, { ...options, replyTo: undefined });
+        }
+        return sentId(sent);
     }
-    async sendTyping(channelId) {
+    /**
+     * Sends files as albums of up to ten. Photos and videos share an album, while audio and
+     * documents each go in albums of their own kind, as Telegram requires; GIFs, which albums do
+     * not take, go on their own as animations. Each file keeps its own caption, and a caption too
+     * long for an album follows it as a message. Albums carry no buttons. Returns the ids of every
+     * message sent.
+     */
+    async sendFiles(channelId, files, options = {}) {
+        if (files.length === 1 && files[0]) {
+            return [await this.sendFile(channelId, files[0], options)];
+        }
+        const kindOf = (file) => {
+            if (TelegramChannel.mediaKind(file).method === 'sendAnimation')
+                return 'animation';
+            return file.type === 'image' || file.type === 'video' ? 'visual' : file.type;
+        };
+        const groups = [];
+        for (const file of files) {
+            const last = groups[groups.length - 1];
+            const joins = last &&
+                last.length < 10 &&
+                last[0] &&
+                kindOf(file) !== 'animation' &&
+                kindOf(last[0]) === kindOf(file);
+            if (joins)
+                last.push(file);
+            else
+                groups.push([file]);
+        }
+        const chatId = telegramChatId(channelId);
+        let replyTo = options.replyTo;
+        const ids = [];
+        for (const group of groups) {
+            if (group.length === 1 && group[0]) {
+                ids.push(await this.sendFile(channelId, group[0], { ...options, replyTo }));
+            }
+            else {
+                const album = await this.call('sendMediaGroup', {
+                    chat_id: chatId,
+                    media: group.map((file) => ({
+                        type: file.type === 'image'
+                            ? 'photo'
+                            : file.type === 'video'
+                                ? 'video'
+                                : file.type === 'audio'
+                                    ? 'audio'
+                                    : 'document',
+                        media: this.source(file),
+                        ...this.caption(file.caption, options.format),
+                    })),
+                    ...this.envelope({ ...options, replyTo, buttons: undefined, visibleTo: undefined }),
+                });
+                if (Array.isArray(album))
+                    ids.push(...album.map(sentId));
+                for (const file of group) {
+                    if (file.caption && file.caption.length > CAPTION_LIMIT) {
+                        ids.push(await this.sendText(channelId, file.caption, {
+                            ...options,
+                            replyTo: undefined,
+                            buttons: undefined,
+                        }));
+                    }
+                }
+            }
+            replyTo = undefined;
+        }
+        return ids;
+    }
+    async sendTyping(channelId, options = {}) {
         if (!this.bot)
             return;
-        await this.bot.api.sendChatAction(Number(channelId), 'typing');
-    }
-    async sendDraft(channelId, draftId, text, options) {
-        const bot = this.requireBot();
-        const useMarkdown = options?.format === 'markdown';
-        await bot.api.sendMessageDraft(Number(channelId), draftId, text, {
-            ...(useMarkdown ? { parse_mode: 'Markdown' } : {}),
+        await this.call('sendChatAction', {
+            chat_id: telegramChatId(channelId),
+            action: 'typing',
+            ...(options.topicId ? { message_thread_id: Number(options.topicId) } : {}),
         });
     }
+    /**
+     * Streams a partial answer as a draft, a preview Telegram shows for 30 seconds; the final
+     * answer is sent as a message. Drafts exist in private chats only, so a group throws and the
+     * caller falls back to sending and editing messages. With `canStop`, the user gets a stop
+     * button and the draft stays on screen after a press until the final message replaces it.
+     */
+    async sendDraft(channelId, draftId, text, options = {}) {
+        if (!isPrivateChat(channelId)) {
+            throw new Error('Telegram drafts can only be sent to private chats');
+        }
+        const base = {
+            chat_id: Number(channelId),
+            draft_id: draftId,
+            ...(options.topicId ? { message_thread_id: Number(options.topicId) } : {}),
+            ...(options.canStop ? { can_stop: true, keep_on_stop: true } : {}),
+        };
+        if (options.format === 'markdown' && this.useRich && text.trim()) {
+            try {
+                await this.call('sendRichMessageDraft', { ...base, rich_message: { markdown: text } });
+                return;
+            }
+            catch (err) {
+                if (!isRefused(err))
+                    throw err;
+                this.richRefused(err);
+            }
+        }
+        const classic = this.classic(text, options.format);
+        const clipped = classic.length > TEXT_LIMIT ? classic.slice(0, TEXT_LIMIT) : classic;
+        try {
+            await this.call('sendMessageDraft', {
+                ...base,
+                text: clipped,
+                ...(options.format === 'markdown' ? { parse_mode: 'Markdown' } : {}),
+            });
+        }
+        catch (err) {
+            if (options.format !== 'markdown' || !isEntityParseError(err))
+                throw err;
+            await this.call('sendMessageDraft', { ...base, text: clipped });
+        }
+    }
     async deleteMessage(channelId, messageId) {
-        const bot = this.requireBot();
-        await bot.api.deleteMessage(Number(channelId), Number(messageId));
+        await this.call('deleteMessage', {
+            chat_id: telegramChatId(channelId),
+            message_id: Number(messageId),
+        });
     }
     async setReaction(channelId, messageId, emoji) {
         if (!this.bot)
             return;
-        await this.bot.api.setMessageReaction(Number(channelId), Number(messageId), [
-            { type: 'emoji', emoji },
-        ]);
+        await this.call('setMessageReaction', {
+            chat_id: telegramChatId(channelId),
+            message_id: Number(messageId),
+            reaction: [{ type: 'emoji', emoji }],
+        });
+    }
+    async answerAction(actionId, options = {}) {
+        await this.call('answerCallbackQuery', {
+            callback_query_id: actionId,
+            ...(options.text ? { text: options.text } : {}),
+            ...(options.alert ? { show_alert: true } : {}),
+        });
+    }
+    async editButtons(channelId, messageId, buttons) {
+        try {
+            await this.call('editMessageReplyMarkup', {
+                chat_id: telegramChatId(channelId),
+                message_id: Number(messageId),
+                reply_markup: buttons ? telegramKeyboard(buttons) : { inline_keyboard: [] },
+            });
+        }
+        catch (err) {
+            if (!isNotModifiedError(err))
+                throw err;
+        }
+    }
+    async setCommands(commands, scope = {}) {
+        await this.setCommandMenu(commands, {
+            scope: scope.chatId ? { type: 'chat', chatId: scope.chatId } : { type: 'default' },
+        });
+    }
+    /** Sets the command menu for a scope and, optionally, a language. */
+    async setCommandMenu(commands, options = {}) {
+        for (const { command, description } of commands) {
+            if (!COMMAND_RE.test(command)) {
+                throw new Error(`Telegram command "${command}" must be 1-32 lowercase letters, digits or underscores`);
+            }
+            if (description.length < 1 || description.length > 256) {
+                throw new Error(`The description of /${command} must be 1-256 characters`);
+            }
+        }
+        await this.call('setMyCommands', {
+            commands,
+            ...this.scopeArgs(options),
+        });
+    }
+    /** Removes the command menu of a scope. */
+    async deleteCommandMenu(options = {}) {
+        await this.call('deleteMyCommands', this.scopeArgs(options));
+    }
+    scopeArgs(options) {
+        const scope = options.scope;
+        const wire = !scope
+            ? undefined
+            : scope.type === 'chat' || scope.type === 'chat_administrators'
+                ? { type: scope.type, chat_id: telegramChatId(scope.chatId) }
+                : scope.type === 'chat_member'
+                    ? {
+                        type: scope.type,
+                        chat_id: telegramChatId(scope.chatId),
+                        user_id: Number(scope.userId),
+                    }
+                    : { type: scope.type };
+        return {
+            ...(wire ? { scope: wire } : {}),
+            ...(options.languageCode ? { language_code: options.languageCode } : {}),
+        };
+    }
+    /** Sets the bot's name, description and short description; fields left out are not changed. */
+    async setProfile(profile) {
+        const language = profile.languageCode ? { language_code: profile.languageCode } : {};
+        if (profile.name !== undefined)
+            await this.call('setMyName', { name: profile.name, ...language });
+        if (profile.description !== undefined) {
+            await this.call('setMyDescription', { description: profile.description, ...language });
+        }
+        if (profile.shortDescription !== undefined) {
+            await this.call('setMyShortDescription', {
+                short_description: profile.shortDescription,
+                ...language,
+            });
+        }
     }
 }
 export function telegramChannel(config) {