@grammyjs/types 3.0.3 → 3.1.0

package/README.md

@@ -90,6 +90,7 @@ The actual type definitions themselves are never different.
 4. No `More info on Sending Files »`.
    File handling is abstracted away by the underlying library.
    Also, without the links, it's useless anyway.
+   The same is true for the links to more info about requesting chats and users.
 5. No images.
    Documentation strings containing an image are adjusted to make sense without the images, too.
 

package/inline.d.ts

@@ -1,5 +1,5 @@
 import type { Chat, User } from "./manage.js";
-import type { InlineKeyboardMarkup } from "./markup.js";
+import type { InlineKeyboardMarkup, WebAppInfo } from "./markup.js";
 import type { Location, MessageEntity, ParseMode } from "./message.js";
 import type { LabeledPrice } from "./payment.js";
 /** This object represents an incoming inline query. When the user sends an empty query, your bot could return some default or trending results. */
@@ -668,3 +668,14 @@ export interface ChosenInlineResult {
     /** The query that was used to obtain the result */
     query: string;
 }
+/** This object represents a button to be shown above inline query results. You must use exactly one of the optional fields.
+
+Example: An inline bot that sends YouTube videos can ask the user to connect the bot to their YouTube account to adapt search results accordingly. To do this, it displays a 'Connect your YouTube account' button above the results, or even before showing any. The user presses the button, switches to a private chat with the bot and, in doing so, passes a start parameter that instructs the bot to return an OAuth link. Once done, the bot can offer a switch_inline button so that the user can easily return to the chat where they wanted to use the bot's inline capabilities. */
+export interface InlineQueryResultsButton {
+    /** Label text on the button */
+    text: string;
+    /** Description of the Web App that will be launched when the user presses the button. The Web App will be able to switch back to the inline mode using the method web_app_switch_inline_query inside the Web App. */
+    web_app?: WebAppInfo;
+    /** Deep-linking parameter for the /start message sent to the bot when a user presses the button. 1-64 characters, only `A-Z`, `a-z`, `0-9`, `_` and `-` are allowed. */
+    start_parameter?: string;
+}

package/manage.d.ts

@@ -360,6 +360,8 @@ export interface ChatMemberUpdated {
     new_chat_member: ChatMember;
     /** Chat invite link, which was used by the user to join the chat; for joining by invite link events only. */
     invite_link?: ChatInviteLink;
+    /** True, if the user joined the chat via a chat folder invite link */
+    via_chat_folder_invite_link?: boolean;
 }
 /** Represents a join request sent to a chat. */
 export interface ChatJoinRequest {

package/markup.d.ts

@@ -38,6 +38,10 @@ export declare namespace InlineKeyboardButton {
         This offers a quick way for the user to open your bot in inline mode in the same chat – good for selecting something from multiple options. */
         switch_inline_query_current_chat: string;
     }
+    export interface SwitchInlineChosenChatButton extends AbstractInlineKeyboardButton {
+        /** If set, pressing the button will prompt the user to select one of their chats of the specified type, open that chat and insert the bot's username and the specified inline query in the input field */
+        switch_inline_query_chosen_chat: SwitchInlineQueryChosenChat;
+    }
     export interface GameButton extends AbstractInlineKeyboardButton {
         /** Description of the game that will be launched when the user presses the button.
     
@@ -53,7 +57,7 @@ export declare namespace InlineKeyboardButton {
     export {};
 }
 /** This object represents one button of an inline keyboard. You must use exactly one of the optional fields. */
-export type InlineKeyboardButton = InlineKeyboardButton.CallbackButton | InlineKeyboardButton.GameButton | InlineKeyboardButton.LoginButton | InlineKeyboardButton.PayButton | InlineKeyboardButton.SwitchInlineButton | InlineKeyboardButton.SwitchInlineCurrentChatButton | InlineKeyboardButton.UrlButton | InlineKeyboardButton.WebAppButton;
+export type InlineKeyboardButton = InlineKeyboardButton.CallbackButton | InlineKeyboardButton.GameButton | InlineKeyboardButton.LoginButton | InlineKeyboardButton.PayButton | InlineKeyboardButton.SwitchInlineButton | InlineKeyboardButton.SwitchInlineCurrentChatButton | InlineKeyboardButton.SwitchInlineChosenChatButton | InlineKeyboardButton.UrlButton | InlineKeyboardButton.WebAppButton;
 /** This object represents a parameter of the inline keyboard button used to automatically authorize a user. Serves as a great replacement for the Telegram Login Widget when the user is coming from Telegram. All the user needs to do is tap/click a button and confirm that they want to log in.
 Telegram apps support these buttons as of version 5.7. */
 export interface LoginUrl {
@@ -68,6 +72,19 @@ export interface LoginUrl {
     /** Pass True to request the permission for your bot to send messages to the user. */
     request_write_access?: boolean;
 }
+/** This object represents an inline button that switches the current user to inline mode in a chosen chat, with an optional default inline query. */
+export interface SwitchInlineQueryChosenChat {
+    /** The default inline query to be inserted in the input field. If left empty, only the bot's username will be inserted */
+    query?: string;
+    /** True, if private chats with users can be chosen */
+    allow_user_chats?: boolean;
+    /** True, if private chats with bots can be chosen */
+    allow_bot_chats?: boolean;
+    /** True, if group and supergroup chats can be chosen */
+    allow_group_chats?: boolean;
+    /** True, if channel chats can be chosen */
+    allow_channel_chats?: boolean;
+}
 /** A placeholder, currently holds no information. Use BotFather to set up your game. */
 export interface CallbackGame {
 }

package/message.d.ts

@@ -1,5 +1,5 @@
-import type { InlineKeyboardMarkup } from "./markup.js";
 import type { Chat, File, User } from "./manage.js";
+import type { InlineKeyboardMarkup } from "./markup.js";
 import type { PassportData } from "./passport.js";
 import type { Invoice, SuccessfulPayment } from "./payment.js";
 type MsgWith<P extends keyof Message> = Record<P, NonNullable<Message[P]>>;
@@ -243,6 +243,7 @@ __underline__
 *bold _italic bold ~italic bold strikethrough ||italic bold strikethrough spoiler||~ __underline italic bold___ bold*
 [inline URL](http://www.example.com/)
 [inline mention of a user](tg://user?id=123456789)
+![👍](tg://emoji?id=5368324170671202286)
 `inline fixed-width code`
 `​`​`
 pre-formatted fixed-width code block
@@ -256,6 +257,8 @@ Please note:
 - Any character with code between 1 and 126 inclusively can be escaped anywhere with a preceding '\' character, in which case it is treated as an ordinary character and not a part of the markup. This implies that '\' character usually must be escaped with a preceding '\' character.
 - Inside `pre` and `code` entities, all '`' and '\' characters must be escaped with a preceding '\' character.
 - Inside `(...)` part of inline link definition, all ')' and '\' must be escaped with a preceding '\' character.
+- A valid emoji must be provided as an alternative value for the custom emoji. The emoji will be shown instead of the custom emoji in places where a custom emoji cannot be displayed (e.g., system notifications) or if the message is forwarded by a non-premium user. It is recommended to use the emoji from the emoji field of the custom emoji sticker.
+- Custom emoji entities can only be used by bots that purchased additional usernames on Fragment.
 - In all other places characters '_', '*', '[', ']', '(', ')', '~', '`', '>', '#', '+', '-', '=', '|', '{', '}', '.', '!' must be escaped with the preceding character '\'.
 - In case of ambiguity between `italic` and `underline` entities `__` is always greadily treated from left to right as beginning or end of `underline` entity, so instead of `___italic underline___` use `___italic underline_\r__`, where `\r` is a character with code 13, which will be ignored.
 
@@ -271,6 +274,7 @@ To use this mode, pass *HTML* in the *parse_mode* field. The following tags are
 <b>bold <i>italic bold <s>italic bold strikethrough <span class="tg-spoiler">italic bold strikethrough spoiler</span></s> <u>underline italic bold</u></i> bold</b>
 <a href="http://www.example.com/">inline URL</a>
 <a href="tg://user?id=123456789">inline mention of a user</a>
+<tg-emoji emoji-id="5368324170671202286">👍</tg-emoji>
 <code>inline fixed-width code</code>
 <pre>pre-formatted fixed-width code block</pre>
 <pre><code class="language-python">pre-formatted fixed-width code block written in the Python programming language</code></pre>
@@ -283,6 +287,8 @@ Please note:
 - The API currently supports only the following named HTML entities: `&lt;`, `&gt;`, `&amp;` and `&quot;`.
 - Use nested `pre` and `code` tags, to define programming language for pre entity.
 - Programming language can't be specified for standalone `code` tags.
+- A valid emoji must be used as the content of the tg-emoji tag. The emoji will be shown instead of the custom emoji in places where a custom emoji cannot be displayed (e.g., system notifications) or if the message is forwarded by a non-premium user. It is recommended to use the emoji from the emoji field of the custom emoji sticker.
+- Custom emoji entities can only be used by bots that purchased additional usernames on Fragment.
 
 #### Markdown style
 This is a legacy mode, retained for backward compatibility. To use this mode, pass *Markdown* in the *parse_mode* field. Use the following syntax in your message:
@@ -615,8 +621,10 @@ export interface ChatShared {
     /** Identifier of the shared chat. This number may have more than 32 significant bits and some programming languages may have difficulty/silent defects in interpreting it. But it has at most 52 significant bits, so a 64-bit integer or double-precision float type are safe for storing this identifier. The bot may not have access to the chat and could be unable to use this identifier, unless the chat is already known to the bot by some other means. */
     chat_id: number;
 }
-/** This object represents a service message about a user allowing a bot added to the attachment menu to write messages. Currently holds no information. */
+/** This object represents a service message about a user allowing a bot to write messages after adding the bot to the attachment menu or launching a Web App from a link. */
 export interface WriteAccessAllowed {
+    /** Name of the Web App which was launched from a link */
+    web_app_name?: string;
 }
 /** This object represents a service message about a video chat scheduled in the chat. */
 export interface VideoChatScheduled {

package/methods.d.ts

@@ -1,10 +1,10 @@
-import type { InlineQueryResult } from "./inline.js";
+import type { InlineQueryResult, InlineQueryResultsButton } from "./inline.js";
 import type { BotCommand, ChatAdministratorRights, ChatFromGetChat, ChatInviteLink, ChatMember, ChatMemberAdministrator, ChatMemberOwner, ChatPermissions, File, ForumTopic, UserFromGetMe, UserProfilePhotos, WebhookInfo } from "./manage.js";
 import type { ForceReply, InlineKeyboardMarkup, ReplyKeyboardMarkup, ReplyKeyboardRemove } from "./markup.js";
 import type { GameHighScore, MaskPosition, Message, MessageEntity, MessageId, ParseMode, Poll, SentWebAppMessage, Sticker, StickerSet } from "./message.js";
 import type { PassportElementError } from "./passport.js";
 import type { LabeledPrice, ShippingOption } from "./payment.js";
-import type { BotCommandScope, BotDescription, BotShortDescription, MenuButton } from "./settings.js";
+import type { BotCommandScope, BotDescription, BotName, BotShortDescription, MenuButton } from "./settings.js";
 import type { Update } from "./update.js";
 /** Extracts the parameters of a given method name */
 type Params<F, M extends keyof ApiMethods<F>> = Parameters<ApiMethods<F>[M]>;
@@ -20,7 +20,7 @@ export type ApiMethods<F> = {
     1. This method will not work if an outgoing webhook is set up.
     2. In order to avoid getting duplicate updates, recalculate offset after each server response. */
     getUpdates(args?: {
-        /** Identifier of the first update to be returned. Must be greater by one than the highest among the identifiers of previously received updates. By default, updates starting with the earliest unconfirmed update are returned. An update is considered confirmed as soon as getUpdates is called with an offset higher than its update_id. The negative offset can be specified to retrieve updates starting from -offset update from the end of the updates queue. All previous updates will forgotten. */
+        /** Identifier of the first update to be returned. Must be greater by one than the highest among the identifiers of previously received updates. By default, updates starting with the earliest unconfirmed update are returned. An update is considered confirmed as soon as getUpdates is called with an offset higher than its update_id. The negative offset can be specified to retrieve updates starting from -offset update from the end of the updates queue. All previous updates will be forgotten. */
         offset?: number;
         /** Limits the number of updates to be retrieved. Values between 1-100 are accepted. Defaults to 100. */
         limit?: number;
@@ -920,6 +920,18 @@ export type ApiMethods<F> = {
         /** The maximum amount of time in seconds that the result of the callback query may be cached client-side. Telegram apps will support caching starting in version 3.14. Defaults to 0. */
         cache_time?: number;
     }): true;
+    /** Use this method to change the bot's name. Returns True on success. */
+    setMyName(args: {
+        /** New bot name; 0-64 characters. Pass an empty string to remove the dedicated name for the given language. */
+        name?: string;
+        /** A two-letter ISO 639-1 language code. If empty, the name will be shown to all users for whose language there is no dedicated name. */
+        language_code?: string;
+    }): true;
+    /** Use this method to get the current bot name for the given user language. Returns BotName on success. */
+    getMyName(args: {
+        /** A two-letter ISO 639-1 language code or an empty string */
+        language_code?: string;
+    }): BotName;
     /** Use this method to change the list of the bot's commands. See https://core.telegram.org/bots#commands for more details about bot commands. Returns True on success. */
     setMyCommands(args: {
         /** A list of bot commands to be set as the list of the bot's commands. At most 100 commands can be specified. */
@@ -943,18 +955,6 @@ export type ApiMethods<F> = {
         /** A two-letter ISO 639-1 language code or an empty string */
         language_code?: string;
     }): BotCommand[];
-    /** Use this method to change the bot's menu button in a private chat, or the default menu button. Returns True on success. */
-    setChatMenuButton(args: {
-        /** Unique identifier for the target private chat. If not specified, default bot's menu button will be changed */
-        chat_id?: number;
-        /** An object for the bot's new menu button. Defaults to MenuButtonDefault */
-        menu_button?: MenuButton;
-    }): true;
-    /** Use this method to get the current value of the bot's menu button in a private chat, or the default menu button. Returns MenuButton on success. */
-    getChatMenuButton(args: {
-        /** Unique identifier for the target private chat. If not specified, default bot's menu button will be returned */
-        chat_id?: number;
-    }): MenuButton;
     /** Use this method to change the bot's description, which is shown in the chat with the bot if the chat is empty. Returns True on success. */
     setMyDescription(args: {
         /** New bot description; 0-512 characters. Pass an empty string to remove the dedicated description for the given language. */
@@ -979,6 +979,18 @@ export type ApiMethods<F> = {
         /** A two-letter ISO 639-1 language code or an empty string */
         language_code?: string;
     }): BotShortDescription;
+    /** Use this method to change the bot's menu button in a private chat, or the default menu button. Returns True on success. */
+    setChatMenuButton(args: {
+        /** Unique identifier for the target private chat. If not specified, default bot's menu button will be changed */
+        chat_id?: number;
+        /** An object for the bot's new menu button. Defaults to MenuButtonDefault */
+        menu_button?: MenuButton;
+    }): true;
+    /** Use this method to get the current value of the bot's menu button in a private chat, or the default menu button. Returns MenuButton on success. */
+    getChatMenuButton(args: {
+        /** Unique identifier for the target private chat. If not specified, default bot's menu button will be returned */
+        chat_id?: number;
+    }): MenuButton;
     /** Use this method to change the default administrator rights requested by the bot when it's added as an administrator to groups or channels. These rights will be suggested to users, but they are free to modify the list before adding the bot. Returns True on success. */
     setMyDefaultAdministratorRights(args: {
         /** An object describing new default administrator rights. If not specified, the default administrator rights will be cleared. */
@@ -1218,10 +1230,8 @@ export type ApiMethods<F> = {
         is_personal?: boolean;
         /** Pass the offset that a client should send in the next query with the same text to receive more results. Pass an empty string if there are no more results or if you don't support pagination. Offset length can't exceed 64 bytes. */
         next_offset?: string;
-        /** If passed, clients will display a button with specified text that switches the user to a private chat with the bot and sends the bot a start message with the parameter switch_pm_parameter */
-        switch_pm_text?: string;
-        /** Deep-linking parameter for the /start message sent to the bot when user presses the switch button. 1-64 characters, only A-Z, a-z, 0-9, _ and - are allowed. */
-        switch_pm_parameter?: string;
+        /** An object describing a button to be shown above inline query results */
+        button?: InlineQueryResultsButton;
     }): true;
     /** Use this method to set the result of an interaction with a Web App and send a corresponding message on behalf of the user to the chat from which the query originated. On success, a SentWebAppMessage object is returned. */
     answerWebAppQuery(args: {

package/mod.d.ts

@@ -2,9 +2,9 @@ export * from "./api.js";
 export * from "./inline.js";
 export * from "./manage.js";
 export * from "./markup.js";
-export * from "./settings.js";
 export * from "./message.js";
+export * from "./methods.js";
 export * from "./passport.js";
 export * from "./payment.js";
-export * from "./methods.js";
+export * from "./settings.js";
 export * from "./update.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grammyjs/types",
-  "version": "3.0.3",
+  "version": "3.1.0",
   "description": "Telegram Bot API type declarations for grammY",
   "main": "mod.js",
   "repository": {

package/settings.d.ts

@@ -1,4 +1,9 @@
 import type { WebAppInfo } from "./markup.js";
+/** This object represents the bot's name. */
+export interface BotName {
+    /** The bot's name */
+    name: string;
+}
 /** This object represents the bot's description. */
 export interface BotDescription {
     /** The bot's description */

package/update.d.ts

@@ -1,6 +1,6 @@
-import type { CallbackQuery } from "./markup.js";
 import type { ChosenInlineResult, InlineQuery } from "./inline.js";
 import type { Chat, ChatJoinRequest, ChatMemberUpdated, User } from "./manage.js";
+import type { CallbackQuery } from "./markup.js";
 import type { Message, Poll, PollAnswer } from "./message.js";
 import type { PreCheckoutQuery, ShippingQuery } from "./payment.js";
 /** Internal namespace used to make some message types more accurate */