@mtcute/core 0.16.7 → 0.16.9

package/highlevel/types/media/audio.d.ts

@@ -0,0 +1,31 @@
+import { tdFileId } from '@mtcute/file-id';
+import { tl } from '@mtcute/tl';
+import { RawDocument } from './document.js';
+/**
+ * An audio file
+ */
+export declare class Audio extends RawDocument {
+    /** TL object describing the audio */
+    readonly attr: tl.RawDocumentAttributeAudio;
+    /** Type of the media (for use in a tagged union) */
+    readonly type: "audio";
+    /** Type of the file for File ID generation */
+    protected _fileIdType(): tdFileId.FileType;
+    constructor(doc: tl.RawDocument, 
+    /** TL object describing the audio */
+    attr: tl.RawDocumentAttributeAudio);
+    /**
+     * Duration of the audio in seconds.
+     *
+     * May not be accurate since provided by the sender.
+     */
+    get duration(): number;
+    /**
+     * Performer of the audio track.
+     */
+    get performer(): string | null;
+    /**
+     * Title of the audio track.
+     */
+    get title(): string | null;
+}

package/highlevel/types/media/contact.d.ts

@@ -0,0 +1,31 @@
+import { tl } from '@mtcute/tl';
+/**
+ * A phone contact
+ */
+export declare class Contact {
+    readonly obj: tl.RawMessageMediaContact;
+    readonly type: "contact";
+    constructor(obj: tl.RawMessageMediaContact);
+    /**
+     * Contact's phone number
+     */
+    get phoneNumber(): string;
+    /**
+     * Contact's first name
+     */
+    get firstName(): string;
+    /**
+     * Contact's last name
+     */
+    get lastName(): string;
+    /**
+     * Contact's user ID in Telegram or `0` if not available
+     */
+    get userId(): number;
+    /**
+     * Input media TL object generated from this object,
+     * to be used inside {@link InputMediaLike} and
+     * {@link TelegramClient.sendMedia}
+     */
+    get inputMedia(): tl.TypeInputMedia;
+}

package/highlevel/types/media/dice.d.ts

@@ -0,0 +1,155 @@
+import { tl } from '@mtcute/tl';
+/**
+ * A dice or another interactive random emoji.
+ */
+export declare class Dice {
+    readonly obj: tl.RawMessageMediaDice;
+    readonly type: "dice";
+    /**
+     * A simple 6-sided dice.
+     *
+     * {@link value} represents its value (1-6)
+     */
+    static readonly TYPE_DICE = "\uD83C\uDFB2";
+    /**
+     * A dart. Telegram dart has 4 rings and middle.
+     *
+     * {@link value} represents the position of the dart:
+     * ![Dart position graph](https://i.imgur.com/iPBm7HG.png)
+     */
+    static readonly TYPE_DART = "\uD83C\uDFAF";
+    /**
+     * A basketball thrown into a hoop.
+     *
+     * {@link value} represents the motion of the ball:
+     *  - 1: simple miss (ball hits right part, bounces to the left)
+     *  - 2: first hit the ring, then miss
+     *  - 3: ball gets stuck between the ring and the base
+     *  - 4: first hit the ring, then score
+     *  - 5: direct score
+     */
+    static readonly TYPE_BASKETBALL = "\uD83C\uDFC0";
+    /**
+     * A football thrown to the gate.
+     *
+     * {@link value} represents the motion of the ball:
+     *  - 1: flies above the top barbell
+     *  - 2: hits right barbell, then miss
+     *  - 3: direct score in the middle
+     *  - 4: hits left barbell, then score, then hits right barbell
+     *  - 5: score in the top-right corner
+     */
+    static readonly TYPE_FOOTBALL = "\u26BD\uFE0F";
+    /**
+     * A bowling ball thrown to pins.
+     *
+     * Assuming the following identifiers for the pins:
+     * ```
+     * 4 5 6
+     *  2 3
+     *   1
+     * ```
+     *
+     * {@link value} represents the motion of the ball and pins:
+     *  - 1: the ball touched 6th pin, none are down
+     *  - 2: the ball hit 4th pin, only 4th pin is down.
+     *  - 3: the ball hit 1st pin, pins 1, 2, 5 are down, leaving pins 3, 4, 6
+     *  - 4: the ball hit 1st pin on the right side, all the pins except 2nd and 6th are down
+     *  - 5: the ball hit 3rd pin and all the pins except 2nd are down.
+     *  - 6: the ball hit 1st pin and all pins are down
+     */
+    static readonly TYPE_BOWLING = "\uD83C\uDFB3";
+    /**
+     * A slot machine.
+     *
+     * {@link value} represents the result of the machine.
+     * Value itself is an integer in range `[1, 64]`,
+     * and is composed out of several parts.
+     *
+     * > **Note**: The following information is based on the TDesktop
+     * > implementation. These are the relevant files:
+     * >  - [`chat_helpers/stickers_dice_pack.cpp`](https://github.com/telegramdesktop/tdesktop/blob/dev/Telegram/SourceFiles/chat_helpers/stickers_dice_pack.cpp)
+     * >  - [`history/view/media/history_view_slot_machine.cpp`](https://github.com/telegramdesktop/tdesktop/blob/dev/Telegram/SourceFiles/history/view/media/history_view_slot_machine.cpp)
+     *
+     * Unlike other animated dices, this does not have
+     * all the possible combinations in the sticker set.
+     * Instead, `value` is a specially encoded integer that contains
+     * the information about the indexes.
+     *
+     * There are some base parts of the animations:
+     *  - 0th sticker is the base background of the machine
+     *  - 1st sticker is the background of the machine for the "winning" state (i.e. `777`)
+     *  - 2nd sticker is the frame of the machine, including the handle
+     *  - 8th sticker is the "idle" state for the left slot
+     *  - 14th sticker is the "idle" state for the middle slot
+     *  - 20th sticker is the "idle" state for the right slot
+     *
+     * The machine result is encoded as 3 concatenated two-bit integers,
+     * and the resulting integer is incremented by one.
+     *
+     * So, to decode the value to its parts, you can use this code:
+     * ```typescript
+     * const computePartValue = (val: number, idx: number) => ((val - 1) >> (idx * 2)) & 0x03; // 0..3
+     * const parts = [
+     *   computePartValue(msg.media.value, 0),
+     *   computePartValue(msg.media.value, 1),
+     *   computePartValue(msg.media.value, 2),
+     * ]
+     * ```
+     *
+     * Each part of the value corresponds to a particular slot (i.e. part 0 is left slot,
+     * part 1 is middle, part 2 is right). The slot values are as follows:
+     *  - 0: BAR (displayed as a *BAR* sign on a black background)
+     *  - 1: BERRIES (displayed as berries, similar to emoji 🍇)
+     *  - 2: LEMON (displayed as a lemon, similar to emoji 🍋)
+     *  - 3: SEVEN (displayed as a red digit 7)
+     *
+     * Therefore, the winning value (i.e. `777`) is represented as `(3 << 4 | 3 << 2 | 3 << 0) + 1 = 64`
+     *
+     * To determine the needed animation parts, you'll need to apply some shifts.
+     * These are the offsets for the individual symbols:
+     *  - WIN_SEVEN: 0
+     *  - SEVEN: 1
+     *  - BAR: 2
+     *  - BERRIES: 3
+     *  - LEMON: 4
+     *
+     * And these are the shifts for each slot:
+     *  - LEFT: 3
+     *  - MIDDLE: 9
+     *  - RIGHT: 15
+     *
+     * > WIN_SEVEN is the same as SEVEN, but only used if the machine result is `777` (i.e. `value = 64`),
+     * > as it contains additional "blinking" animation.
+     *
+     * The sticker index is computed as follows: `SHIFTS[SLOT] + OFFSETS[SYM]`.
+     * For example, berries for the middle slot would be: `SHIFTS[MIDDLE] + OFFSETS[BERRIES] = 9 + 3 = 12`
+     *
+     * Currently, this sticker set is used for the machine: [SlotMachineAnimated](https://t.me/addstickers/SlotMachineAnimated)
+     */
+    static readonly TYPE_SLOTS = "\uD83C\uDFB0";
+    constructor(obj: tl.RawMessageMediaDice);
+    /**
+     * An emoji which was originally sent.
+     *
+     * See static members of {@link Dice} for a list
+     * of possible values
+     */
+    get emoji(): string;
+    /**
+     * Emoji's interactive value.
+     *
+     * See what this value represents in the corresponding
+     * type's documentation (in {@link Dice} static fields)
+     */
+    get value(): number;
+    /**
+     * Input media TL object generated from this object,
+     * to be used inside {@link InputMediaLike} and
+     * {@link TelegramClient.sendMedia}
+     *
+     * Note that when you use this media, a new `value`
+     * will be generated!
+     */
+    get inputMedia(): tl.TypeInputMedia;
+}

package/highlevel/types/media/document-utils.d.ts

@@ -0,0 +1,11 @@
+import { tl } from '@mtcute/tl';
+import { Audio } from './audio.js';
+import { Document } from './document.js';
+import { Sticker } from './sticker.js';
+import { Video } from './video.js';
+import { Voice } from './voice.js';
+export type ParsedDocument = Sticker | Voice | Audio | Video | Document;
+/** @internal */
+export declare function parseSticker(doc: tl.RawDocument): Sticker | undefined;
+/** @internal */
+export declare function parseDocument(doc: tl.RawDocument, media?: tl.RawMessageMediaDocument): ParsedDocument;

package/highlevel/types/media/document.d.ts

@@ -0,0 +1,75 @@
+import { tdFileId as td } from '@mtcute/file-id';
+import { tl } from '@mtcute/tl';
+import { FileLocation } from '../files/index.js';
+import { Thumbnail } from './thumbnail.js';
+/**
+ * A file that is represented as a document in MTProto.
+ *
+ * This also includes audios, videos, voices etc.
+ */
+export declare abstract class RawDocument extends FileLocation {
+    readonly raw: tl.RawDocument;
+    /** Type of the media (for use in a tagged union) */
+    abstract type: string;
+    constructor(raw: tl.RawDocument);
+    /**
+     * Original file name, extracted from the document
+     * attributes.
+     */
+    get fileName(): string | null;
+    /**
+     * File MIME type, as defined by the sender.
+     */
+    get mimeType(): string;
+    /**
+     * Date the document was sent
+     */
+    get date(): Date;
+    /**
+     * Available thumbnails, if any.
+     *
+     * If there are no thumbnails, the array will be empty.
+     */
+    get thumbnails(): ReadonlyArray<Thumbnail>;
+    /**
+     * Get a thumbnail by its type.
+     *
+     * Thumbnail types are described in the
+     * [Telegram docs](https://core.telegram.org/api/files#image-thumbnail-types),
+     * and are also available as static members of {@link Thumbnail} for convenience.
+     *
+     * @param type  Thumbnail type
+     */
+    getThumbnail(type: string): Thumbnail | null;
+    /**
+     * Input document TL object generated from this object,
+     * to be used with methods that use it
+     */
+    get inputDocument(): tl.TypeInputDocument;
+    /**
+     * Input media TL object generated from this object,
+     * to be used inside {@link InputMediaLike} and
+     * {@link TelegramClient.sendMedia}
+     */
+    get inputMedia(): tl.TypeInputMedia;
+    protected _fileIdType(): td.FileType;
+    /**
+     * Get TDLib and Bot API compatible File ID
+     * representing this document.
+     */
+    get fileId(): string;
+    /**
+     * Get a unique File ID representing this document.
+     */
+    get uniqueFileId(): string;
+}
+/**
+ * A generic file.
+ *
+ * This does not include audios, videos, voices etc.
+ * and only used for documents without any special
+ * attributes.
+ */
+export declare class Document extends RawDocument {
+    readonly type: "document";
+}

package/highlevel/types/media/extended-media.d.ts

@@ -0,0 +1,20 @@
+import { tl } from '@mtcute/tl';
+import { Thumbnail } from './thumbnail.js';
+export declare class ExtendedMediaPreview {
+    readonly raw: tl.RawMessageExtendedMediaPreview;
+    constructor(raw: tl.RawMessageExtendedMediaPreview);
+    /**
+     * Width of the preview, in pixels (if available, else 0)
+     */
+    get width(): number;
+    /**
+     * Height of the preview, in pixels (if available, else 0)
+     */
+    get height(): number;
+    get thumbnail(): Thumbnail | null;
+    /**
+     * If this is a video, the duration of the video,
+     * in seconds (if available, else 0)
+     */
+    get videoDuration(): number;
+}

package/highlevel/types/media/game.d.ts

@@ -0,0 +1,38 @@
+import { tl } from '@mtcute/tl';
+import { Photo } from './photo.js';
+import { Video } from './video.js';
+export declare class Game {
+    readonly game: tl.RawGame;
+    readonly type: "game";
+    constructor(game: tl.RawGame);
+    /**
+     * Unique identifier of the game.
+     */
+    get id(): tl.Long;
+    /**
+     * Title of the game
+     */
+    get title(): string;
+    /**
+     * Description of the game
+     */
+    get description(): string;
+    /**
+     * Unique short name of the game
+     */
+    get shortName(): string;
+    /**
+     * Photo that will be displayed in the game message in chats
+     */
+    get photo(): Photo | null;
+    /**
+     * Animation that will be displayed in the game message in chats
+     */
+    get animation(): Video | null;
+    /**
+     * Input media TL object generated from this object,
+     * to be used inside {@link InputMediaLike} and
+     * {@link TelegramClient.sendMedia}
+     */
+    get inputMedia(): tl.TypeInputMedia;
+}

package/highlevel/types/media/input-media/factories.d.ts

@@ -0,0 +1,142 @@
+import { tl } from '@mtcute/tl';
+import { InputFileLike } from '../../files/utils.js';
+import { CaptionMixin, InputMediaAudio, InputMediaAuto, InputMediaContact, InputMediaDice, InputMediaDocument, InputMediaGame, InputMediaGeo, InputMediaGeoLive, InputMediaInvoice, InputMediaLike, InputMediaPaidMedia, InputMediaPhoto, InputMediaPoll, InputMediaQuiz, InputMediaSticker, InputMediaStory, InputMediaVenue, InputMediaVideo, InputMediaVoice, InputMediaWebpage } from './types.js';
+/** Omit `type` and `file` from the given type */
+export type OmitTypeAndFile<T extends InputMediaLike, K extends keyof T = never> = Omit<T, 'type' | 'file' | K>;
+/**
+ * Create an animation to be sent
+ *
+ * @param file  Animation
+ * @param params  Additional parameters
+ */
+export declare function animation(file: InputFileLike, params?: OmitTypeAndFile<InputMediaVideo>): InputMediaVideo;
+/**
+ * Create an audio to be sent
+ *
+ * @param file  Audio file
+ * @param params  Additional parameters
+ */
+export declare function audio(file: InputFileLike, params?: OmitTypeAndFile<InputMediaAudio>): InputMediaAudio;
+/**
+ * Create an document to be sent
+ *
+ * @param file  Document
+ * @param params  Additional parameters
+ */
+export declare function document(file: InputFileLike, params?: OmitTypeAndFile<InputMediaDocument>): InputMediaDocument;
+/**
+ * Create an photo to be sent
+ *
+ * @param file  Photo
+ * @param params  Additional parameters
+ */
+export declare function photo(file: InputFileLike, params?: OmitTypeAndFile<InputMediaPhoto>): InputMediaPhoto;
+/**
+ * Create an video to be sent
+ *
+ * @param file  Video
+ * @param params  Additional parameters
+ */
+export declare function video(file: InputFileLike, params?: OmitTypeAndFile<InputMediaVideo>): InputMediaVideo;
+/**
+ * Create a voice note to be sent
+ *
+ * @param file  Voice note
+ * @param params  Additional parameters
+ */
+export declare function voice(file: InputFileLike, params?: OmitTypeAndFile<InputMediaVoice>): InputMediaVoice;
+/**
+ * Create a sticker to be sent
+ *
+ * @param file  Sticker
+ * @param params  Additional parameters
+ */
+export declare function sticker(file: InputFileLike, params?: OmitTypeAndFile<InputMediaSticker>): InputMediaSticker;
+/**
+ * Create a venue to be sent
+ *
+ * @param params  Venue parameters
+ */
+export declare function venue(params: OmitTypeAndFile<InputMediaVenue>): InputMediaVenue;
+/**
+ * Create a geolocation to be sent
+ *
+ * @param latitude  Latitude of the location
+ * @param longitude  Longitude of the location
+ * @param params  Additional parameters
+ */
+export declare function geo(latitude: number, longitude: number, params?: OmitTypeAndFile<InputMediaGeo, 'latitude' | 'longitude'>): InputMediaGeo;
+/**
+ * Create a live geolocation to be sent
+ *
+ * @param latitude  Latitude of the current location
+ * @param longitude  Longitude of the current location
+ * @param params  Additional parameters
+ */
+export declare function geoLive(latitude: number, longitude: number, params?: OmitTypeAndFile<InputMediaGeoLive, 'latitude' | 'longitude'>): InputMediaGeoLive;
+/**
+ * Create a dice to be sent
+ *
+ * For convenience, known dice emojis are available
+ * as static members of {@link Dice}.
+ *
+ * @param emoji  Emoji representing the dice
+ * @param params  Additional parameters
+ */
+export declare function dice(emoji: string, params: CaptionMixin): InputMediaDice;
+/**
+ * Create a contact to be sent
+ *
+ * @param params  Contact parameters
+ */
+export declare function contact(params: OmitTypeAndFile<InputMediaContact>): InputMediaContact;
+/**
+ * Create a game to be sent
+ *
+ * @param game  Game short name or TL object representing one
+ */
+export declare function game(game: string | tl.TypeInputGame): InputMediaGame;
+/**
+ * Create an invoice to be sent
+ *
+ * @param params  Invoice parameters
+ */
+export declare function invoice(params: OmitTypeAndFile<InputMediaInvoice>): InputMediaInvoice;
+/**
+ * Create a poll to be sent
+ *
+ * @param params  Poll parameters
+ */
+export declare function poll(params: OmitTypeAndFile<InputMediaPoll>): InputMediaPoll;
+/**
+ * Create a quiz to be sent
+ *
+ * @param params  Quiz parameters
+ */
+export declare function quiz(params: OmitTypeAndFile<InputMediaQuiz>): InputMediaQuiz;
+/**
+ * Create a story to be sent
+ *
+ * @param params  Story parameters
+ */
+export declare function story(params: OmitTypeAndFile<InputMediaStory>): InputMediaStory;
+/**
+ * Create a webpage to be sent
+ *
+ * @param url  Webpage URL
+ * @param params  Additional parameters
+ */
+export declare function webpage(url: string, params?: OmitTypeAndFile<InputMediaWebpage, 'url'>): InputMediaWebpage;
+export declare function paid(params: OmitTypeAndFile<InputMediaPaidMedia>): InputMediaPaidMedia;
+/**
+ * Create a document to be sent, which subtype
+ * is inferred automatically by file contents.
+ *
+ * Photo type is only inferred for reused files,
+ * newly uploaded photos with `auto` will be
+ * uploaded as a document
+ *
+ * @param file  The media file
+ * @param params  Additional parameters
+ */
+export declare function auto(file: InputFileLike, params?: OmitTypeAndFile<InputMediaAuto>): InputMediaAuto;