@mtcute/core 0.18.0-rc.5 → 0.19.0

package/highlevel/types/peers/index.d.ts

@@ -1,4 +1,5 @@
 export * from './bot-info.js';
+export * from './chat-colors.js';
 export * from './chat-event/index.js';
 export * from './chat-invite-link-member.js';
 export * from './chat-invite-link.js';

package/highlevel/types/peers/peer.d.cts

@@ -0,0 +1,49 @@
+import { tl } from '@mtcute/tl';
+import { PeersIndex } from './peers-index.js';
+import { Chat } from './chat.js';
+import { User } from './user.js';
+/**
+ * More extensive peer types, that differentiate between
+ * users and bots, channels and supergroups.
+ */
+export type PeerType = 'user' | 'bot' | 'group' | 'channel' | 'supergroup';
+/**
+ * Type that can be used as an input peer to most of the high-level methods. Can be:
+ *  - `number`, representing peer's marked ID*
+ *  - `string`, representing peer's username (without preceding `@`)
+ *  - `string`, representing user's phone number
+ *  - `"me"` and `"self"` which will be replaced with the current user/bot
+ *  - Any object with `inputPeer: tl.TypeInputPeer` property
+ *  - Raw TL object
+ *
+ * > * Telegram has moved to int64 IDs. Though, Levin [has confirmed](https://t.me/tdlibchat/25071)
+ * > that new IDs *will* still fit into int53, meaning JS integers are fine.
+ */
+export type InputPeerLike = string | number | tl.TypePeer | tl.TypeInputPeer | tl.TypeInputUser | tl.TypeInputChannel | {
+    inputPeer: tl.TypeInputPeer;
+};
+/**
+ * Peer (a user or a chat)
+ *
+ * Type of the peer can be determined by the `.type` property
+ */
+export type Peer = User | Chat;
+/**
+ * An object representing an anonymous sender (e.g. for users that have forwards hidden)
+ */
+export interface AnonymousSender {
+    readonly type: 'anonymous';
+    /**
+     * Name of the anonymous sender that should be displayed
+     */
+    readonly displayName: string;
+}
+/**
+ * Object representing a sender of a forwarded message,
+ * which can be either a {@link Peer} or an {@link AnonymousSender}
+ */
+export type PeerSender = Peer | AnonymousSender;
+/**
+ * Given a `tl.TypePeer`, return a {@link Peer} object ({@link User} or {@link Chat})
+ */
+export declare function parsePeer(peer: tl.TypePeer, index: PeersIndex): Peer;

package/highlevel/types/peers/peers-index.d.cts

@@ -0,0 +1,15 @@
+import { tl } from '@mtcute/tl';
+export declare class PeersIndex {
+    readonly users: Map<number, tl.TypeUser>;
+    readonly chats: Map<number, tl.TypeChat>;
+    constructor(users?: Map<number, tl.TypeUser>, chats?: Map<number, tl.TypeChat>);
+    hasMin: boolean;
+    static from(obj: {
+        users?: tl.TypeUser[];
+        chats?: tl.TypeChat[];
+    }): PeersIndex;
+    get empty(): boolean;
+    user(id: number): tl.TypeUser;
+    chat(id: number): tl.TypeChat;
+    get(peer: tl.TypePeer): tl.TypeUser | tl.TypeChat;
+}

package/highlevel/types/peers/peers-index.test.d.cts

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

package/highlevel/types/peers/typing-status.d.cts

@@ -0,0 +1,26 @@
+/**
+ * User typing status. Used to provide detailed
+ * information about chat partners' actions:
+ * typing messages, recording/uploading attachments, etc.
+ *
+ * Can be:
+ *  - `typing`: User is typing
+ *  - `cancel`: User is not doing anything (used to cancel previously sent status)
+ *  - `record_video`: User is recording a video
+ *  - `upload_video`: User is uploading a video
+ *  - `record_voice`: User is recording a voice message
+ *  - `upload_voice`: User is uploading a voice message
+ *  - `upload_photo`: User is uploading a photo
+ *  - `upload_document`: User is uploading a document
+ *  - `geo`: User is choosing a geolocation to share
+ *  - `contact`: User is choosing a contact to share
+ *  - `game`: User is playing a game
+ *  - `record_round`: User is recording a round video message
+ *  - `upload_round`: User is uploading a round video message
+ *  - `speak_call`: User is speaking in a group call
+ *  - `history_import`: User is importing history
+ *  - `sticker`: User is choosing a sticker
+ *  - `interaction`: User has sent an emoji interaction
+ *  - `interaction_seen`: User is watching a previously sent emoji interaction
+ */
+export type TypingStatus = 'typing' | 'cancel' | 'record_video' | 'upload_video' | 'record_voice' | 'upload_voice' | 'upload_photo' | 'upload_document' | 'geo' | 'contact' | 'game' | 'record_round' | 'upload_round' | 'speak_call' | 'history_import' | 'sticker' | 'interaction' | 'interaction_seen';

package/highlevel/types/peers/user.d.cts

@@ -0,0 +1,268 @@
+import { tl } from '@mtcute/tl';
+import { MessageEntity } from '../messages/message-entity.js';
+import { EmojiStatus } from '../reactions/emoji-status.js';
+import { ChatColors } from './chat-colors.js';
+import { ChatPhoto } from './chat-photo.js';
+/**
+ * User's Last Seen & Online status.
+ * Can be one of the following:
+ *  - `online`, user is online right now.
+ *  - `offline`, user is currently offline.
+ *  - `recently`, user with hidden last seen time who was online between 1 second and 72 hours ago.
+ *  - `within_week`, user with hidden last seen time who was online between 72 hours and 7 days ago.
+ *  - `within_month`, user with hidden last seen time who was online between 7 days and a month ago.
+ *  - `long_time_ago`, blocked user or user with hidden last seen time who was online more than a month ago.
+ *  - `bot`, for bots.
+ */
+export type UserStatus = 'online' | 'offline' | 'recently' | 'within_week' | 'within_month' | 'long_time_ago' | 'bot';
+export interface UserParsedStatus {
+    status: UserStatus;
+    lastOnline: Date | null;
+    nextOffline: Date | null;
+    byMe: boolean;
+}
+export declare class User {
+    readonly type: "user";
+    /**
+     * Underlying raw TL object
+     */
+    readonly raw: tl.RawUser;
+    constructor(user: tl.TypeUser);
+    /** Unique identifier for this user or bot */
+    get id(): number;
+    /**
+     * Whether this user's information is incomplete.
+     *
+     * This usually only happens in large chats, where
+     * the server sometimes sends only a part of the user's
+     * information. Basic info like name and profile photo
+     * are always available, but other fields may be omitted
+     * despite being available.
+     *
+     * For a rough list of fields that may be missing, see the
+     * [official docs](https://core.telegram.org/constructor/user).
+     *
+     * This currently only ever happens for non-bot users, so if you are building
+     * a normal bot, you can safely ignore this field.
+     *
+     * To fetch the "complete" user information, use one of these methods:
+     *  - {@link TelegramClient.getUsers}
+     *  - {@link TelegramClient.getChat}
+     *  - {@link TelegramClient.getFullChat}.
+     *
+     * Learn more: [Incomplete peers](https://mtcute.dev/guide/topics/peers.html#incomplete-peers)
+     */
+    get isMin(): boolean;
+    /** Whether this user is you yourself */
+    get isSelf(): boolean;
+    /** Whether this user is in your contacts */
+    get isContact(): boolean;
+    /** Whether you both have each other's contact */
+    get isMutualContact(): boolean;
+    /** Whether this user is in yout "close friends" list */
+    get isCloseFriend(): boolean;
+    /** Whether this user is deleted */
+    get isDeleted(): boolean;
+    /** Whether this user is a bot */
+    get isBot(): boolean;
+    /**
+     * Whether this user is a bot that can be connected to a
+     * Telegram Business account to receive its messages
+     */
+    get isBusinessBot(): boolean;
+    /** Whether this user is a bot that has access to all messages */
+    get isBotWithHistory(): boolean;
+    /** Whether this user is a bot that can't be added to chats */
+    get isBotWithoutChats(): boolean;
+    /** Whether this bot offers an attachment menu web app */
+    get isBotWithAttachmentMenu(): boolean;
+    /** Whether this bot offers an attachment menu web app, and we have it enabled */
+    get isBotAttachmentMenuEnabled(): boolean;
+    /** Whether this bot can request geolocation when used in inline mode */
+    get isBotWithInlineGeo(): boolean;
+    /** Whether this bot can be edited by the current user */
+    get isBotEditable(): boolean;
+    /** Whether this user has been verified by Telegram */
+    get isVerified(): boolean;
+    /**
+     * Whether this user has been restricted. Bots only.
+     * See {@link restrictionReason} for details
+     */
+    get isRestricted(): boolean;
+    /**
+     * Reason why this bot was restricted
+     */
+    get restrictionReason(): tl.TypeRestrictionReason[];
+    /** Whether this user has been flagged for scam */
+    get isScam(): boolean;
+    /** Whether this user has been flagged for impersonation */
+    get isFake(): boolean;
+    /** Whether this user is part of the Telegram support team */
+    get isSupport(): boolean;
+    /** Whether this user has Premium subscription */
+    get isPremium(): boolean;
+    /** Whether Premium is required to contact this user */
+    get isPremiumRequired(): boolean;
+    /** Number of bot's active users, if available */
+    get botActiveUsers(): number | null;
+    /** Whether this bot has a main app */
+    get hasMainApp(): boolean;
+    /** User's or bot's first name */
+    get firstName(): string;
+    /** User's or bot's last name */
+    get lastName(): string | null;
+    static parseStatus(status?: tl.TypeUserStatus, bot?: boolean): UserParsedStatus;
+    private get _parsedStatus();
+    /** User's Last Seen & Online status */
+    get status(): UserStatus;
+    /**
+     * Whether user's online status is hidden because
+     * we have hidden our own online status from them,
+     * and we don't have Premium subscription.
+     */
+    get statusHiddenByMe(): boolean;
+    /**
+     * Last time this user was seen online.
+     * Only available if {@link status} is `offline`
+     */
+    get lastOnline(): Date | null;
+    /**
+     * Time when this user will automatically go offline.
+     * Only available if {@link status} is `online`
+     */
+    get nextOffline(): Date | null;
+    /** User's or bot's username */
+    get username(): string | null;
+    /** User's or bot's usernames (including collectibles) */
+    get usernames(): ReadonlyArray<tl.RawUsername> | null;
+    /**
+     * IETF language tag of the user's language
+     *
+     * Only available in some contexts
+     */
+    get language(): string | null;
+    /**
+     * User's or bot's assigned DC (data center).
+     * Available only in case the user has set a public profile photo.
+     *
+     * **Note**: this information is approximate; it is based on where
+     * Telegram stores a user profile pictures and does not by any means tell
+     * you the user location (i.e. a user might travel far away, but will still connect
+     * to its assigned DC).
+     * More info at [Pyrogram FAQ](https://docs.pyrogram.org/faq#what-are-the-ip-addresses-of-telegram-data-centers).
+     */
+    get dcId(): number | null;
+    /** User's phone number */
+    get phoneNumber(): string | null;
+    /**
+     * Get this user's input peer for advanced use-cases.
+     *
+     * > **Note**: for {@link min} users, this method will return
+     * > `mtcute.dummyInputPeerMinUser`, which is actually not a valid input peer.
+     * > These are used to indicate that the user is incomplete, and a message
+     * > reference is needed to resolve the peer.
+     * >
+     * > Such objects are handled by {@link TelegramClient.resolvePeer} method,
+     * > so prefer using it whenever you need an input peer.
+     */
+    get inputPeer(): tl.TypeInputPeer;
+    /**
+     * User's or bot's current profile photo, if any.
+     * Suitable for downloads only
+     */
+    get photo(): ChatPhoto | null;
+    /**
+     * The list of reasons why this bot might be unavailable to some users.
+     * This field is available only in case *isRestricted* is `true`
+     */
+    get restrictions(): ReadonlyArray<tl.RawRestrictionReason> | null;
+    /**
+     * User's display name.
+     *
+     * First name and last name if available,
+     * only first name otherwise.
+     */
+    get displayName(): string;
+    /**
+     * User's emoji status, if any.
+     */
+    get emojiStatus(): EmojiStatus | null;
+    /** Whether you have hidden (arhived) this user's stories */
+    get storiesHidden(): boolean;
+    get storiesUnavailable(): boolean;
+    /**
+     * Maximum ID of stories this user has (or 0 if none)
+     */
+    get storiesMaxId(): number;
+    /**
+     * Color that should be used when rendering replies to
+     * their messages and web previews sent by them,
+     * as well as to render the chat title
+     */
+    get color(): ChatColors;
+    /**
+     * Color that should be used when rendering the header of
+     * the user's profile
+     *
+     * If `null`, a generic header should be used instead
+     */
+    get profileColors(): ChatColors | null;
+    /**
+     * Create a mention for the user.
+     *
+     * When available and `text` is omitted, this method will return `@username`.
+     * Otherwise, text mention is created.
+     *
+     * Use `null` as `text` (first parameter) to force create a text
+     * mention with display name, even if there is a username.
+     *
+     * > **Note**: This method doesn't format anything on its own.
+     * > Instead, it returns a {@link MessageEntity} that can later
+     * > be used with `html` or `md` template tags
+     *
+     * @param text  Text of the mention.
+     * @example
+     * ```typescript
+     * msg.replyText(html`Hello, ${msg.sender.mention()`)
+     * ```
+     */
+    mention(text?: string | null): string | MessageEntity;
+    /**
+     * Create a permanent mention for this user.
+     *
+     * Permanent* means that this mention will also
+     * contain user's access hash, so even if the user
+     * changes their username or the client forgets
+     * about that user, it can still be mentioned.
+     *
+     * Telegram might change access hash in some cases,
+     * so it may not exactly be *permanent*. The only way
+     * to actually make it permanent is to send it as a message
+     * somewhere and load it from there if needed.
+     *
+     * Note that some users (particularly, users with hidden forwards)
+     * may not be mentioned like this outside the chats you have in common.
+     *
+     * This method is only needed when the result will be
+     * stored somewhere outside current mtcute instance (e.g. saved for later use),
+     * otherwise {@link mention} will be enough.
+     *
+     * > **Note**: This method doesn't format anything on its own.
+     * > Instead, it returns a {@link MessageEntity} that can later
+     * > be used with `html` or `md` template tags
+     *
+     * > **Note**: the resulting text can only be used by clients
+     * > that support mtcute notation of permanent
+     * > mention links (`tg://user?id=123&hash=abc`).
+     * >
+     * > Also note that these permanent mentions are only
+     * > valid for current account, since peer access hashes are
+     * > account-specific and can't be used on another account.
+     * >
+     * > Also note that for some users such mentions might not work at all
+     * > due to privacy settings.
+     *
+     * @param text  Mention text
+     */
+    permanentMention(text?: string | null): MessageEntity;
+}

package/highlevel/types/peers/user.test.d.cts

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

package/highlevel/types/premium/boost-slot.d.cts

@@ -0,0 +1,37 @@
+import { tl } from '@mtcute/tl';
+import { PeersIndex, Chat } from '../peers/index.js';
+/**
+ * Information about a boost slot
+ */
+export declare class BoostSlot {
+    readonly raw: tl.RawMyBoost;
+    readonly _peers: PeersIndex;
+    constructor(raw: tl.RawMyBoost, _peers: PeersIndex);
+    /** ID of this slot */
+    get id(): number;
+    /**
+     * Whether this slot is occupied
+     */
+    get occupied(): boolean;
+    /**
+     * Channel that is occupying this slot, if any
+     */
+    get chat(): Chat | null;
+    /**
+     * Date when we started boosting this channel
+     *
+     * If this slot is not occupied, will be `0`
+     */
+    get date(): Date;
+    /**
+     * Date when this boost will automatically expire.
+     */
+    get expireDate(): Date;
+    /**
+     * If this slot is occupied, returns the date when
+     * we can reassing this slot to another channel.
+     *
+     * If `null`, we can reassign it immediately.
+     */
+    get cooldownUntil(): Date | null;
+}

package/highlevel/types/premium/boost-stats.d.cts

@@ -0,0 +1,54 @@
+import { tl } from '@mtcute/tl';
+/**
+ * Information about boosts in a channel
+ */
+export declare class BoostStats {
+    readonly raw: tl.premium.RawBoostsStatus;
+    constructor(raw: tl.premium.RawBoostsStatus);
+    /** Whether this channel is being boosted by the current user */
+    get isBoosting(): boolean;
+    /**
+     * Current level of boosts in this channel.
+     *
+     * Currently this maps 1-to-1 to the number of stories
+     * the channel can post daily
+     */
+    get level(): number;
+    /** Whether this channel is already at the maximum level */
+    get isMaxLevel(): boolean;
+    /**
+     * The number of boosts acquired from created Telegram Premium
+     * gift codes and giveaways, only available to channel admins
+     */
+    get gifts(): number;
+    /**
+     * Number of boosts that were needed for the current level
+     */
+    get currentLevelBoosts(): number;
+    /** Total number of boosts this channel has */
+    get currentBoosts(): number;
+    /**
+     * Number of boosts the channel must have to reach the next level
+     *
+     * `null` if the channel is already at the maximum level
+     */
+    get nextLevelBoosts(): number | null;
+    /**
+     * Number of boosts the channel needs in addition to the current value
+     * to reach the next level
+     */
+    get remainingBoosts(): number;
+    /** If available, total number of subscribers this channel has */
+    get totalSubscribers(): number | null;
+    /** If available, total number of Premium subscribers this channel has */
+    get totalPremiumSubscribers(): number | null;
+    /** If available, percentage of this channel's subscribers that are Premium */
+    get premiumSubscribersPercentage(): number | null;
+    /** URL that would bring up the boost interface */
+    get url(): string;
+    /**
+     * If {@link isBoosting}, IDs of the boost slots that are
+     * currently occupied by this channel
+     */
+    get boostSlots(): number[];
+}

package/highlevel/types/premium/boost.d.cts

@@ -0,0 +1,56 @@
+import { tl } from '@mtcute/tl';
+import { PeersIndex, User } from '../peers/index.js';
+/**
+ * Origin of a boost
+ *
+ * - `gift` - boost applied because the channel gifted a subscription to some user
+ * - `unclaimed_gift` - boost applied because the channel gifted a subscription to some user,
+ *   but the user hasn't yet claimed it
+ * - `giveaway` - boost applied because the user was chosen in a giveaway
+ * - `user` - boost applied because the user directly boosted the channel
+ */
+export type BoostOrigin = 'gift' | 'unclaimed_gift' | 'giveaway' | 'user';
+/**
+ * Information about a boost (one or more)
+ */
+export declare class Boost {
+    readonly raw: tl.RawBoost;
+    readonly _peers: PeersIndex;
+    constructor(raw: tl.RawBoost, _peers: PeersIndex);
+    /** Unique ID of this boost */
+    get id(): string;
+    /** Number of boosts this boost is actually representing */
+    get count(): number;
+    /** Date when this boost was applied */
+    get date(): Date;
+    /** Amount of Telegram Stars that were awarded along with this boost */
+    get stars(): tl.Long | null;
+    /**
+     * Date when this boost will automatically expire.
+     *
+     * > **Note**: User can still manually cancel the boost before that date
+     */
+    get expireDate(): Date;
+    /**
+     * Whether this boost was applied because the channel
+     * directly gifted a subscription to the user
+     */
+    get origin(): BoostOrigin;
+    /**
+     * User who is boosting the channel.
+     *
+     * Only available for some origins
+     */
+    get user(): User | null;
+    /**
+     * ID of the message containing the giveaway where this
+     * user has won
+     */
+    get giveawayMessageId(): number | null;
+    /**
+     * The created Telegram Premium gift code, only set if `origin` is not `user`,
+     * AND it is either a gift code for the currently logged in user,
+     * or if it was already claimed
+     */
+    get usedGiftSlug(): string | null;
+}

package/highlevel/types/premium/boost.d.ts

@@ -9,7 +9,7 @@ import { PeersIndex, User } from '../peers/index.js';
  * - `giveaway` - boost applied because the user was chosen in a giveaway
  * - `user` - boost applied because the user directly boosted the channel
  */
-type BoostOrigin = 'gift' | 'unclaimed_gift' | 'giveaway' | 'user';
+export type BoostOrigin = 'gift' | 'unclaimed_gift' | 'giveaway' | 'user';
 /**
  * Information about a boost (one or more)
  */
@@ -54,4 +54,3 @@ export declare class Boost {
      */
     get usedGiftSlug(): string | null;
 }
-export {};

package/highlevel/types/premium/business-account.d.cts

@@ -0,0 +1,19 @@
+import { tl } from '@mtcute/tl';
+import { BusinessIntro } from './business-intro.js';
+import { BusinessLocation } from './business-location.js';
+import { BusinessWorkHours } from './business-work-hours.js';
+/** Information about a business account */
+export declare class BusinessAccount {
+    readonly info: tl.RawUserFull;
+    constructor(info: tl.RawUserFull);
+    /** Introduction of the business account */
+    get intro(): BusinessIntro | null;
+    /** Work hours of the business */
+    get workHours(): BusinessWorkHours | null;
+    /** Location of the business */
+    get location(): BusinessLocation | null;
+    /** Information about a greeting message */
+    get greetingMessage(): tl.TypeBusinessGreetingMessage | null;
+    /** Information about an "away" message */
+    get awayMessage(): tl.TypeBusinessAwayMessage | null;
+}

package/highlevel/types/premium/business-chat-link.d.cts

@@ -0,0 +1,19 @@
+import { tl } from '@mtcute/tl';
+import { MessageEntity } from '../messages/message-entity.js';
+/**
+ * A business chat link, i.e. a link to start a chat with a pre-filled message.
+ */
+export declare class BusinessChatLink {
+    readonly raw: tl.RawBusinessChatLink;
+    constructor(raw: tl.RawBusinessChatLink);
+    /** The link itself */
+    get link(): string;
+    /** Text to be inserted into the message input */
+    get text(): string;
+    /** Entities for the text */
+    get entities(): MessageEntity[];
+    /** Custom title for the link */
+    get title(): string | null;
+    /** Number of clicks on the link */
+    get clicks(): number;
+}

package/highlevel/types/premium/business-connection.d.cts

@@ -0,0 +1,23 @@
+import { tl } from '@mtcute/tl';
+import { PeersIndex } from '../peers/peers-index.js';
+import { User } from '../peers/user.js';
+/**
+ * Describes the connection of the bot with a business account.
+ */
+export declare class BusinessConnection {
+    readonly raw: tl.TypeBotBusinessConnection;
+    readonly _peers: PeersIndex;
+    constructor(raw: tl.TypeBotBusinessConnection, _peers: PeersIndex);
+    /** Whether the connection was removed by the user */
+    get isRemoved(): boolean;
+    /** ID of the connection */
+    get id(): string;
+    /** Datacenter ID of the connected user */
+    get dcId(): number;
+    /** Date when the connection was created */
+    get date(): Date;
+    /** Whether the bot can reply on behalf of the user */
+    get canReply(): boolean;
+    /** Business account user that created the business connection */
+    get user(): User;
+}

package/highlevel/types/premium/business-intro.d.cts

@@ -0,0 +1,22 @@
+import { tl } from '@mtcute/tl';
+import { Sticker } from '../media/sticker.js';
+/**
+ * Information about a "business intro" – text that is displayed
+ * when a user opens a chat with a business account for the first time.
+ */
+export declare class BusinessIntro {
+    readonly raw: tl.RawBusinessIntro;
+    constructor(raw: tl.RawBusinessIntro);
+    /**
+     * Title of the intro.
+     */
+    get title(): string;
+    /**
+     * Description of the intro.
+     */
+    get description(): string;
+    /**
+     * Sticker of the intro.
+     */
+    get sticker(): Sticker | null;
+}

package/highlevel/types/premium/business-location.d.cts

@@ -0,0 +1,10 @@
+import { tl } from '@mtcute/tl';
+import { Location } from '../media/location.js';
+/** Location of a business */
+export declare class BusinessLocation {
+    readonly raw: tl.RawBusinessLocation;
+    constructor(raw: tl.RawBusinessLocation);
+    /** Address of the business */
+    get address(): string;
+    get location(): Location | null;
+}