@mtcute/core 0.18.0-rc.5 → 0.18.0

package/highlevel/types/bots/inline-result/types.d.cts

@@ -0,0 +1,417 @@
+import { tl } from '@mtcute/tl';
+import { InputInlineMessage } from '../inline-message/types.js';
+export interface BaseInputInlineResult {
+    /**
+     * Unique ID of the result
+     */
+    id: string;
+    /**
+     * Message to send when the result is selected.
+     *
+     * By default, is automatically generated,
+     * and details about how it is generated can be found
+     * in subclasses' description
+     */
+    message?: InputInlineMessage;
+}
+/**
+ * Inline result containing an article.
+ *
+ * If `message` is not provided, a {@link InputInlineMessageText} is created
+ * with web preview enabled and text generated as follows:
+ * ```
+ * {{#if url}}
+ * <a href="{{url}}"><b>{{title}}</b></a>
+ * {{else}}
+ * <b>{{title}}</b>
+ * {{/if}}
+ * {{#if description}}
+ * {{description}}
+ * {{/if}}
+ * ```
+ * > Handlebars syntax is used. HTML tags are used to signify entities,
+ * > but in fact raw TL entity objects are created
+ */
+export interface InputInlineResultArticle extends BaseInputInlineResult {
+    type: 'article';
+    /**
+     * Title of the result (must not be empty)
+     */
+    title: string;
+    /**
+     * Description of the result
+     */
+    description?: string;
+    /**
+     * URL of the article
+     */
+    url?: string;
+    /**
+     * Whether to prevent article URL from
+     * displaying by the client
+     *
+     * @default  `false`
+     */
+    hideUrl?: boolean;
+    /**
+     * Article thumbnail URL (must be jpeg).
+     */
+    thumb?: string | tl.RawInputWebDocument;
+}
+/**
+ * Inline result containing an animation (silent mp4 or gif).
+ *
+ * If `message` is not provided, {@link InputInlineMessageMedia} is used
+ * with empty caption
+ */
+export interface InputInlineResultGif extends BaseInputInlineResult {
+    type: 'gif';
+    /**
+     * The animation itself.
+     *
+     * Can be a URL, a TDLib and Bot API compatible File ID,
+     * or a TL object representing either of them.
+     */
+    media: string | tl.RawInputWebDocument | tl.RawInputDocument;
+    /**
+     * Media MIME type, only applicable to URLs.
+     *
+     * Usually unnecessary, since Telegram automatically infers it.
+     *
+     * @default `video/mp4`
+     */
+    mime?: string;
+    /**
+     * Title of the result
+     */
+    title?: string;
+    /**
+     * Title of the result
+     */
+    description?: string;
+    /**
+     * Animation thumbnail URL, only applicable in case `media` is a URL
+     *
+     * @default  `media`
+     */
+    thumb?: string | tl.RawInputWebDocument;
+    /**
+     * Thumbnail MIME type
+     *
+     * @default  `image/jpeg`
+     */
+    thumbMime?: string;
+    /**
+     * Width of the animation in pixels
+     */
+    width?: number;
+    /**
+     * Height of the animation in pixels
+     */
+    height?: number;
+    /**
+     * Duration of the animation in seconds
+     */
+    duration?: number;
+}
+/**
+ * Inline result containing a video (only MP4)
+ *
+ * If `message` is not provided, {@link InputInlineMessageMedia} is used
+ * with empty caption for non-embed videos, {@link InputInlineMessageText}
+ * is used with text containing the URL for embed videos.
+ */
+export interface InputInlineResultVideo extends BaseInputInlineResult {
+    type: 'video';
+    /**
+     * The video itself, or a page containing an embedded video
+     *
+     * Can be a URL, a TDLib and Bot API compatible File ID,
+     * or a TL object representing either of them.
+     */
+    media: string | tl.RawInputWebDocument | tl.RawInputDocument;
+    /**
+     * In case `media` is a URL, whether that URL is a link
+     * to an embedded video player.
+     */
+    isEmbed?: boolean;
+    /**
+     * Title of the result
+     */
+    title: string;
+    /**
+     * Description of the result
+     */
+    description?: string;
+    /**
+     * Video thumbnail URL (must be jpeg), only applicable in case `media` is a URL.
+     *
+     * Must be provided explicitly if this is a video loaded by URL.
+     *
+     * @default  `media`
+     */
+    thumb?: string | tl.RawInputWebDocument;
+    /**
+     * Width of the video in pixels
+     */
+    width?: number;
+    /**
+     * Height of the video in pixels
+     */
+    height?: number;
+    /**
+     * Duration of the video in seconds
+     */
+    duration?: number;
+}
+/**
+ * Inline result containing an audio file
+ *
+ * If `message` is not provided, {@link InputInlineMessageMedia} is used
+ * with empty caption.
+ */
+export interface InputInlineResultAudio extends BaseInputInlineResult {
+    type: 'audio';
+    /**
+     * The audio itself
+     *
+     * Can be a URL, a TDLib and Bot API compatible File ID,
+     * or a TL object representing either of them.
+     */
+    media: string | tl.RawInputWebDocument | tl.RawInputDocument;
+    /**
+     * MIME type of the audio file
+     *
+     * Usually unnecessary, since Telegram infers it automatically.
+     *
+     * @default  `audio/mpeg`
+     */
+    mime?: string;
+    /**
+     * Title of the audio track
+     */
+    title: string;
+    /**
+     * Performer of the audio track
+     */
+    performer?: string;
+    /**
+     * Duration of the audio in seconds
+     */
+    duration?: number;
+}
+/**
+ * Inline result containing a voice note
+ *
+ * If `message` is not provided, {@link InputInlineMessageMedia} is used
+ * with empty caption.
+ */
+export interface InputInlineResultVoice extends BaseInputInlineResult {
+    type: 'voice';
+    /**
+     * The voice itself (.ogg, preferably encoded with OPUS)
+     *
+     * Can be a URL, a TDLib and Bot API compatible File ID,
+     * or a TL object representing either of them.
+     */
+    media: string | tl.RawInputWebDocument | tl.RawInputDocument;
+    /**
+     * Title of the result
+     */
+    title: string;
+    /**
+     * Duration of the voice note in seconds
+     */
+    duration?: number;
+}
+/**
+ * Inline result containing a photo
+ *
+ * If `message` is not provided, {@link InputInlineMessageMedia} is used
+ * with empty caption.
+ */
+export interface InputInlineResultPhoto extends BaseInputInlineResult {
+    type: 'photo';
+    /**
+     * The photo itself
+     *
+     * Can be a URL, a TDLib and Bot API compatible File ID,
+     * or a TL object representing either of them.
+     */
+    media: string | tl.RawInputWebDocument | tl.RawInputPhoto;
+    /**
+     * Title of the result
+     */
+    title?: string;
+    /**
+     * Description of the result
+     */
+    description?: string;
+    /**
+     * Width of the photo in pixels
+     */
+    width?: number;
+    /**
+     * Height of the photo in pixels
+     */
+    height?: number;
+    /**
+     * Photo thumbnail URL (must be jpeg), only applicable in case `media` is a URL
+     *
+     * @default  `media`
+     */
+    thumb?: string | tl.RawInputWebDocument;
+}
+/**
+ * Inline result containing a sticker
+ *
+ * If `message` is not provided, {@link InputInlineMessageMedia} is used.
+ */
+export interface InputInlineResultSticker extends BaseInputInlineResult {
+    type: 'sticker';
+    /**
+     * The sticker itself. Can't be a URL.
+     */
+    media: string | tl.RawInputDocument;
+}
+/**
+ * Inline result containing a document
+ *
+ * If `message` is not provided, {@link InputInlineMessageMedia} is used
+ * with empty caption.
+ */
+export interface InputInlineResultFile extends BaseInputInlineResult {
+    type: 'file';
+    /**
+     * The file itself. When using URL, only PDF and ZIP are supported.
+     *
+     * Can be a URL, a TDLib and Bot API compatible File ID,
+     * or a TL object representing either of them.
+     */
+    media: string | tl.RawInputWebDocument | tl.RawInputDocument;
+    /**
+     * MIME type of the file.
+     *
+     * Due to some Telegram limitation, you can only send
+     * PDF and ZIP files from URL
+     * (`application/pdf` and `application/zip` MIMEs respectively).
+     *
+     * Must be provided if `media` is a URL
+     */
+    mime?: string;
+    /**
+     * Title of the result
+     */
+    title: string;
+    /**
+     * Description of the result
+     */
+    description?: string;
+    /**
+     * Photo thumbnail URL (must be jpeg), only applicable in case `media` is a URL
+     *
+     * @default  `media`
+     */
+    thumb?: string | tl.RawInputWebDocument;
+}
+/**
+ * Inline result containing a geolocation.
+ *
+ * If `message` is not passed, a {@link InputInlineMessageGeo} is
+ * used, with the `latitude` and `longitude` parameters set
+ * accordingly
+ */
+export interface InputInlineResultGeo extends BaseInputInlineResult {
+    type: 'geo';
+    /**
+     * Title of the result
+     */
+    title: string;
+    /**
+     * Latitude of the geolocation
+     */
+    latitude: number;
+    /**
+     * Longitude of the geolocation
+     */
+    longitude: number;
+    /**
+     * Location thumbnail URL (must be jpeg).
+     *
+     * By default, Telegram generates one based on
+     * the location set by `latitude` and `longitude`
+     */
+    thumb?: string | tl.RawInputWebDocument;
+}
+/**
+ * Inline result containing a venue.
+ *
+ * If `message` is not passed, {@link BotInlineMessage.venue} is used with
+ * given `latitude` and `longitude` were passed.
+ * If they weren't passed either, an error is thrown.
+ */
+export interface InputInlineResultVenue extends BaseInputInlineResult {
+    type: 'venue';
+    /**
+     * Title of the venue
+     */
+    title: string;
+    /**
+     * Address of the venue
+     */
+    address: string;
+    /**
+     * Latitude of the geolocation
+     */
+    latitude?: number;
+    /**
+     * Longitude of the geolocation
+     */
+    longitude?: number;
+    /**
+     * Venue thumbnail URL (must be jpeg).
+     *
+     * By default, Telegram generates one based on
+     * the location in the `message`
+     */
+    thumb?: string | tl.RawInputWebDocument;
+}
+/**
+ * Inline result containing a game.
+ *
+ * If `message` is not passed, {@link InputInlineMessageGame} is used.
+ *
+ * Note that `message` can only be {@link InputInlineMessageGame}
+ */
+export interface InputInlineResultGame extends BaseInputInlineResult {
+    type: 'game';
+    /**
+     * Short name of the game
+     */
+    shortName: string;
+}
+/**
+ * Inline result containing a contact.
+ *
+ * If `message` is not passed, {@link InputInlineMessageContact} is used.
+ */
+export interface InputInlineResultContact extends BaseInputInlineResult {
+    type: 'contact';
+    /**
+     * First name of the contact
+     */
+    firstName: string;
+    /**
+     * Last name of the contact
+     */
+    lastName?: string;
+    /**
+     * Phone number of the contact
+     */
+    phone: string;
+    /**
+     * Contact thumbnail URL (i.e. their avatar) (must be jpeg)
+     */
+    thumb?: string | tl.RawInputWebDocument;
+}
+export type InputInlineResult = InputInlineResultArticle | InputInlineResultGif | InputInlineResultVideo | InputInlineResultAudio | InputInlineResultVoice | InputInlineResultPhoto | InputInlineResultSticker | InputInlineResultFile | InputInlineResultGeo | InputInlineResultVenue | InputInlineResultGame | InputInlineResultContact;

package/highlevel/types/bots/keyboards/builder.d.cts

@@ -0,0 +1,38 @@
+import { tl } from '@mtcute/tl';
+import { InlineKeyboardMarkup, ReplyKeyboardMarkup } from './types.js';
+export type ButtonLike = tl.TypeKeyboardButton | false | null | undefined | void;
+/**
+ * Builder for bot keyboards
+ */
+export declare class BotKeyboardBuilder {
+    readonly maxRowWidth: number | null;
+    private _buttons;
+    constructor(maxRowWidth?: number | null);
+    /**
+     * Add buttons, wrapping them once {@link maxRowWidth} is reached
+     *
+     * @param buttons  Buttons to add
+     */
+    push(...buttons: (ButtonLike | (() => ButtonLike))[]): this;
+    /**
+     * Add a row of buttons. Will not be wrapped.
+     *
+     * @param row  Row or a function that will populate it
+     */
+    row(row: ButtonLike[] | ((arr: ButtonLike[]) => void)): this;
+    /**
+     * Append a button to the last row, wrapping if needed.
+     *
+     * @param btn  Button to add
+     * @param force  Whether to forcefully add the button (i.e. do not wrap)
+     */
+    append(btn: ButtonLike | (() => ButtonLike), force?: boolean): this;
+    /**
+     * Return contents of this builder as an inline keyboard
+     */
+    asInline(): InlineKeyboardMarkup;
+    /**
+     * Return contents of this builder as a reply keyboard
+     */
+    asReply(params?: Omit<ReplyKeyboardMarkup, 'type' | 'buttons'>): ReplyKeyboardMarkup;
+}

package/highlevel/types/bots/keyboards/builder.test.d.cts

@@ -0,0 +1 @@
+export {};

package/highlevel/types/bots/keyboards/factories.d.cts

@@ -0,0 +1,208 @@
+import { InlineKeyboardMarkup, ReplyKeyboardForceReply, ReplyKeyboardHide, ReplyKeyboardMarkup, ReplyMarkup } from './types.js';
+import { tl } from '@mtcute/tl';
+import { BotKeyboardBuilder } from './builder.js';
+/** Create a keyboard builder */
+export declare function builder(maxRowWidth?: number | null): BotKeyboardBuilder;
+/**
+ * Create an inline keyboard markup
+ *
+ * @param buttons  Two-dimensional array of buttons
+ */
+export declare function inline(buttons: tl.TypeKeyboardButton[][]): InlineKeyboardMarkup;
+/**
+ * Create a reply keyboard markup
+ *
+ * @param buttons  Two-dimensional array of buttons
+ * @param params  Additional parameters for the keyboard
+ */
+export declare function reply(buttons: tl.TypeKeyboardButton[][], params?: Omit<ReplyKeyboardMarkup, 'type' | 'buttons'>): ReplyKeyboardMarkup;
+/**
+ * Hide the previously sent reply keyboard
+ *
+ * @param selective
+ *     Whether to remove the keyboard for specific users only. Targets:
+ *      - users that are @mentioned in the text of the Message
+ *      - in case this is a reply, sender of the original message
+ */
+export declare function hideReply(selective?: boolean): ReplyKeyboardHide;
+/**
+ * Force the user to send a reply
+ */
+export declare function forceReply(params?: Omit<ReplyKeyboardForceReply, 'type'>): ReplyKeyboardForceReply;
+/**
+ * Create a text-only keyboard button.
+ *
+ * Used for reply keyboards, not inline!
+ *
+ * @param text  Button text
+ */
+export declare function text(text: string): tl.RawKeyboardButton;
+/**
+ * Create a keyboard button requesting for user's contact.
+ * Available only for private chats.
+ *
+ * Used for reply keyboards, not inline!
+ *
+ * @param text  Button text
+ */
+export declare function requestContact(text: string): tl.RawKeyboardButtonRequestPhone;
+/**
+ * Create a keyboard button requesting for user's geo location.
+ * Available only for private chats.
+ *
+ * Used for reply keyboards, not inline!
+ *
+ * @param text  Button text
+ */
+export declare function requestGeo(text: string): tl.RawKeyboardButtonRequestGeoLocation;
+/**
+ * Create a keyboard button requesting the user to create and send a poll.
+ * Available only for private chats.
+ *
+ * Used for reply keyboards, not inline!
+ *
+ * @param text  Button text
+ * @param quiz  If set, only quiz polls can be sent
+ */
+export declare function requestPoll(text: string, quiz?: boolean): tl.RawKeyboardButtonRequestPoll;
+/**
+ * Create a keyboard button with a link.
+ *
+ * Used for inline keyboards, not reply!
+ *
+ * @param text  Button text
+ * @param url  URL
+ */
+export declare function url(text: string, url: string): tl.RawKeyboardButtonUrl;
+/**
+ * Create a keyboard button with a link.
+ *
+ * Used for inline keyboards, not reply!
+ *
+ * @param text  Button text
+ * @param data  Callback data (1-64 bytes). String will be converted to `Buffer`
+ * @param requiresPassword
+ *   Whether the user should verify their identity by entering 2FA password.
+ *   See more: {@link tl.RawKeyboardButtonCallback#requiresPassword}
+ */
+export declare function callback(text: string, data: string | Uint8Array, requiresPassword?: boolean): tl.RawKeyboardButtonCallback;
+/**
+ * Button to force a user to switch to inline mode.
+ *
+ * Pressing the button will prompt the user to select
+ * one of their chats, open that chat and insert the bot‘s
+ * username and the specified inline query (if any) in the input field.
+ *
+ * Used for inline keyboards, not reply!
+ *
+ * @param text  Button text
+ * @param query  Inline query (can be empty or omitted)
+ * @param currentChat
+ *     If set, pressing the button will insert the bot's username
+ *     and the specified inline query in the current chat's input field
+ */
+export declare function switchInline(text: string, query?: string, currentChat?: boolean): tl.RawKeyboardButtonSwitchInline;
+/**
+ * Button to start a game
+ *
+ * Used for inline keyboards, not reply!
+ *
+ * **Note**: This type of button must always be
+ * the first button in the first row. ID of the
+ * game is inferred from {@link InputMedia.game},
+ * thus this button should only be used with it.
+ */
+export declare function game(text: string): tl.RawKeyboardButtonGame;
+/**
+ * Button to pay for a product.
+ *
+ * Used for inline keyboards, not reply!
+ *
+ * **Note**: This type of button must always be
+ * the first button in the first row. Related
+ * invoice is inferred from {@link InputMedia.invoice},
+ * thus this button should only be used with it.
+ */
+export declare function pay(text: string): tl.RawKeyboardButtonBuy;
+/**
+ * Button to authorize a user
+ *
+ * Used for inline keyboards, not reply!
+ *
+ * @param text  Button label
+ * @param url  Authorization URL (see {@link tl.RawInputKeyboardButtonUrlAuth})
+ * @param params
+ */
+export declare function urlAuth(text: string, url: string, params?: {
+    /**
+     * Button label when forwarded
+     */
+    fwdText?: string;
+    /**
+     * Whether to request the permission for
+     * your bot to send messages to the user
+     */
+    requestWriteAccess?: boolean;
+    /**
+     * Bot, which will be used for user authorization.
+     * `url` domain must be the same as the domain linked
+     * with the bot.
+     *
+     * @default  current bot
+     */
+    bot?: tl.TypeInputUser;
+}): tl.RawInputKeyboardButtonUrlAuth;
+/**
+ * Button to open webview
+ *
+ * Used for both inline keyboards and reply ones
+ *
+ * @param text  Button label
+ * @param url  WebView URL
+ */
+export declare function webView(text: string, url: string): tl.RawKeyboardButtonWebView;
+/**
+ * Button to open user profile
+ *
+ * @param text  Text of the button
+ * @param user  User to be opened (use {@link TelegramClient.resolvePeer})
+ */
+export declare function userProfile(text: string, user: tl.TypeInputPeer): tl.RawInputKeyboardButtonUserProfile;
+/**
+ * Button to request a peer from the user
+ *
+ * @param text  Text of the button
+ * @param buttonId  ID of the button that will later be passed to the service message
+ */
+export declare function requestPeer(text: string, buttonId: number, params: {
+    /**
+     * Peer type, along with filters
+     */
+    peerType: tl.TypeRequestPeerType;
+    /**
+     * Maximum number of peers to be selected
+     *
+     * @default  1
+     */
+    count?: number;
+}): tl.RawKeyboardButtonRequestPeer;
+/**
+ * Button to copy text to the user's clipboard
+ */
+export declare function copy(params: {
+    text: string;
+    copyText?: string;
+}): tl.RawKeyboardButtonCopy;
+/**
+ * Find a button in the keyboard by its text or by predicate
+ *
+ * @param buttons  Two-dimensional array of buttons
+ * @param predicate  Button text or predicate function
+ */
+export declare function findButton(buttons: tl.TypeKeyboardButton[][], predicate: string | ((btn: tl.TypeKeyboardButton) => boolean)): tl.TypeKeyboardButton | null;
+/** @internal */
+export declare function _rowsTo2d(rows: tl.RawKeyboardButtonRow[]): tl.TypeKeyboardButton[][];
+/** @internal */
+export declare function _2dToRows(arr: tl.TypeKeyboardButton[][], inline: boolean): tl.RawKeyboardButtonRow[];
+/** @internal */
+export declare function _convertToTl(obj?: ReplyMarkup): tl.TypeReplyMarkup | undefined;

package/highlevel/types/bots/keyboards/index.d.cts

@@ -0,0 +1,15 @@
+import * as BotKeyboard from './factories.js';
+export * from './builder.js';
+export * from './types.js';
+export { 
+/**
+ * Convenience methods wrapping TL
+ * objects creation for bot keyboard buttons.
+ *
+ * You can also use the type-discriminated objects directly.
+ *
+ * > **Note**: Button creation functions are intended to be used
+ * > with inline reply markup, unless stated otherwise
+ * > in the description.
+ */
+BotKeyboard, };

package/highlevel/types/bots/keyboards/keyboards.test.d.cts

@@ -0,0 +1 @@
+export {};