@mtcute/core 0.20.4 → 0.21.0

package/client.cjs

@@ -58,6 +58,7 @@ const getChat = require("./highlevel/methods/chats/get-chat.cjs");
 const getFullChat = require("./highlevel/methods/chats/get-full-chat.cjs");
 const getFullUser = require("./highlevel/methods/chats/get-full-user.cjs");
 const getNearbyChats = require("./highlevel/methods/chats/get-nearby-chats.cjs");
+const getPeer = require("./highlevel/methods/chats/get-peer.cjs");
 const getSimilarChannels = require("./highlevel/methods/chats/get-similar-channels.cjs");
 const getUser = require("./highlevel/methods/chats/get-user.cjs");
 const iterChatEventLog = require("./highlevel/methods/chats/iter-chat-event-log.cjs");
@@ -589,6 +590,9 @@ TelegramClient.prototype.getFullUser = function(...args) {
 TelegramClient.prototype.getNearbyChats = function(...args) {
   return getNearbyChats.getNearbyChats(this._client, ...args);
 };
+TelegramClient.prototype.getPeer = function(...args) {
+  return getPeer.getPeer(this._client, ...args);
+};
 TelegramClient.prototype.getSimilarChannels = function(...args) {
   return getSimilarChannels.getSimilarChannels(this._client, ...args);
 };

package/client.js

@@ -51,6 +51,7 @@ import { getChat } from "./highlevel/methods/chats/get-chat.js";
 import { getFullChat } from "./highlevel/methods/chats/get-full-chat.js";
 import { getFullUser } from "./highlevel/methods/chats/get-full-user.js";
 import { getNearbyChats } from "./highlevel/methods/chats/get-nearby-chats.js";
+import { getPeer } from "./highlevel/methods/chats/get-peer.js";
 import { getSimilarChannels } from "./highlevel/methods/chats/get-similar-channels.js";
 import { getUser } from "./highlevel/methods/chats/get-user.js";
 import { iterChatEventLog } from "./highlevel/methods/chats/iter-chat-event-log.js";
@@ -582,6 +583,9 @@ TelegramClient.prototype.getFullUser = function(...args) {
 TelegramClient.prototype.getNearbyChats = function(...args) {
   return getNearbyChats(this._client, ...args);
 };
+TelegramClient.prototype.getPeer = function(...args) {
+  return getPeer(this._client, ...args);
+};
 TelegramClient.prototype.getSimilarChannels = function(...args) {
   return getSimilarChannels(this._client, ...args);
 };

package/highlevel/client.d.cts

@@ -23,7 +23,7 @@ import { QuoteParamsFrom } from './methods/messages/send-quote.js';
 import { CanApplyBoostResult } from './methods/premium/can-apply-boost.js';
 import { CanSendStoryResult } from './methods/stories/can-send-story.js';
 import { ITelegramStorageProvider } from './storage/provider.js';
-import { AllStories, ArrayPaginated, ArrayWithTotal, Boost, BoostSlot, BoostStats, BotChatJoinRequestUpdate, BotCommands, BotReactionCountUpdate, BotReactionUpdate, BotStoppedUpdate, BusinessCallbackQuery, BusinessChatLink, BusinessConnection, BusinessMessage, BusinessWorkHoursDay, CallbackQuery, Chat, ChatEvent, ChatInviteLink, ChatInviteLinkMember, ChatJoinRequestUpdate, ChatlistPreview, ChatMember, ChatMemberUpdate, ChatPreview, ChosenInlineResult, CollectibleInfo, DeleteBusinessMessageUpdate, DeleteMessageUpdate, DeleteStoryUpdate, Dialog, FactCheck, FileDownloadLocation, FileDownloadParameters, ForumTopic, FullChat, FullUser, GameHighScore, HistoryReadUpdate, InlineCallbackQuery, InlineQuery, InputChatEventFilters, InputDialogFolder, InputFileLike, InputInlineResult, InputMediaLike, InputMediaSticker, InputMessageId, InputPeerLike, InputPrivacyRule, InputReaction, InputStarGift, InputStickerSet, InputStickerSetItem, InputText, InputWebview, MaybeDynamic, Message, MessageEffect, MessageMedia, MessageReactions, ParametersSkip2, ParsedUpdate, PeerReaction, PeerStories, Photo, Poll, PollUpdate, PollVoteUpdate, PreCheckoutQuery, RawDocument, ReplyMarkup, SavedStarGift, SentCode, StarGift, StarGiftUnique, StarsStatus, StarsTransaction, Sticker, StickerSet, StickerType, StoriesStealthMode, Story, StoryInteractions, StoryUpdate, StoryViewer, StoryViewersList, TakeoutSession, TextWithEntities, TypingStatus, UploadedFile, UploadFileLike, User, UserStarGift, UserStatusUpdate, UserTypingUpdate, WebviewResult } from './types/index.js';
+import { AllStories, ArrayPaginated, ArrayWithTotal, Boost, BoostSlot, BoostStats, BotChatJoinRequestUpdate, BotCommands, BotReactionCountUpdate, BotReactionUpdate, BotStoppedUpdate, BusinessCallbackQuery, BusinessChatLink, BusinessConnection, BusinessMessage, BusinessWorkHoursDay, CallbackQuery, Chat, ChatEvent, ChatInviteLink, ChatInviteLinkMember, ChatJoinRequestUpdate, ChatlistPreview, ChatMember, ChatMemberUpdate, ChatPreview, ChosenInlineResult, CollectibleInfo, DeleteBusinessMessageUpdate, DeleteMessageUpdate, DeleteStoryUpdate, Dialog, FactCheck, FileDownloadLocation, FileDownloadParameters, ForumTopic, FullChat, FullUser, GameHighScore, HistoryReadUpdate, InlineCallbackQuery, InlineQuery, InputChatEventFilters, InputDialogFolder, InputFileLike, InputInlineResult, InputMediaLike, InputMediaSticker, InputMessageId, InputPeerLike, InputPrivacyRule, InputReaction, InputStarGift, InputStickerSet, InputStickerSetItem, InputText, InputWebview, MaybeDynamic, Message, MessageEffect, MessageMedia, MessageReactions, ParametersSkip2, ParsedUpdate, Peer, PeerReaction, PeerStories, Photo, Poll, PollUpdate, PollVoteUpdate, PreCheckoutQuery, RawDocument, ReplyMarkup, SavedStarGift, SentCode, StarGift, StarGiftUnique, StarsStatus, StarsTransaction, Sticker, StickerSet, StickerType, StoriesStealthMode, Story, StoryInteractions, StoryUpdate, StoryViewer, StoryViewersList, TakeoutSession, TextWithEntities, TypingStatus, UploadedFile, UploadFileLike, User, UserStarGift, UserStatusUpdate, UserTypingUpdate, WebviewResult } from './types/index.js';
 import { ParsedUpdateHandlerParams } from './updates/parsed.js';
 import { RawUpdateInfo } from './updates/types.js';
 import { InputStringSessionData } from './utils/string-session.js';
@@ -1298,6 +1298,8 @@ export interface TelegramClient extends ITelegramClient {
      * @param longitude  Longitude of the location
      */
     getNearbyChats(latitude: number, longitude: number): Promise<Chat[]>;
+    /** Shorthand for {@link getChat} and {@link getUser} depending on the type of the peer */
+    getPeer(peer: InputPeerLike): Promise<Peer>;
     /**
      * Get channels that are similar to a given channel
      *
@@ -3942,7 +3944,11 @@ export interface TelegramClient extends ITelegramClient {
     getMyBoostSlots(): Promise<BoostSlot[]>;
     /** Get one or more saved star gifts by their IDs */
     getSavedStarGiftsById(gifts: MaybeArray<InputStarGift>): Promise<SavedStarGift[]>;
-    /** Get a list of saved star gifts of a user */
+    /**
+     * Get a list of saved star gifts of a user/channel
+     *
+     * Note that filters currently only work for channels
+     */
     getSavedStarGifts(params: {
         /** Peer to get saved gifts from */
         owner: InputPeerLike;
@@ -3978,9 +3984,10 @@ export interface TelegramClient extends ITelegramClient {
     /**
      * Get a list of gifts sent to a user.
      *
-     * **Available**: 👤 users only
+     * **Available**: ✅ both users and bots
      *
      * @param userId  User whose gifts to fetch
+     * @deprecated  Use {@link getSavedStarGifts} instead
      * @returns  Gifts sent to the user
      */
     getStarGifts(userId: InputPeerLike, params?: {
@@ -3994,7 +4001,7 @@ export interface TelegramClient extends ITelegramClient {
          * @default  100
          */
         limit?: number;
-    }): Promise<ArrayPaginated<UserStarGift, string>>;
+    }): Promise<ArrayPaginated<SavedStarGift, string>>;
     /**
      * Get Telegram Stars transactions for a given peer.
      *
@@ -4141,7 +4148,7 @@ export interface TelegramClient extends ITelegramClient {
      *
      * **Available**: 👤 users only
      *
-     * @returns  Service message about the sent gift
+     * @returns  Service message about the sent gift, if one was generated.
      */
     sendStarGift(params: {
         /** ID of the peer to send the gift to */
@@ -4163,7 +4170,7 @@ export interface TelegramClient extends ITelegramClient {
          * to the client's update handler.
          */
         shouldDispatch?: true;
-    }): Promise<Message>;
+    }): Promise<Message | null>;
     /**
      * Set current user's business introduction.
      *
@@ -4212,7 +4219,7 @@ export interface TelegramClient extends ITelegramClient {
      *
      * **Available**: 👤 users only
      *
-     * @returns  Service message about the transferred gift
+     * @returns  Service message about the transferred gift, if one was generated.
      */
     transferStarGift(params: {
         /** Star gift to transfer */
@@ -4224,7 +4231,7 @@ export interface TelegramClient extends ITelegramClient {
          * to the client's update handler.
          */
         shouldDispatch?: true;
-    }): Promise<Message>;
+    }): Promise<Message | null>;
     /**
      * Upgrades a star gift to a unique gift.
      *
@@ -4235,7 +4242,7 @@ export interface TelegramClient extends ITelegramClient {
      *
      * **Available**: 👤 users only
      *
-     * @returns  Service message about the upgraded gift
+     * @returns  Service message about the upgraded gift, if one was generated.
      */
     upgradeStarGift(params: {
         gift: InputStarGift;
@@ -4249,7 +4256,7 @@ export interface TelegramClient extends ITelegramClient {
          * to the client's update handler.
          */
         shouldDispatch?: true;
-    }): Promise<Message>;
+    }): Promise<Message | null>;
     /**
      * Add a sticker to a sticker set.
      *

package/highlevel/client.d.ts

@@ -23,7 +23,7 @@ import { QuoteParamsFrom } from './methods/messages/send-quote.js';
 import { CanApplyBoostResult } from './methods/premium/can-apply-boost.js';
 import { CanSendStoryResult } from './methods/stories/can-send-story.js';
 import { ITelegramStorageProvider } from './storage/provider.js';
-import { AllStories, ArrayPaginated, ArrayWithTotal, Boost, BoostSlot, BoostStats, BotChatJoinRequestUpdate, BotCommands, BotReactionCountUpdate, BotReactionUpdate, BotStoppedUpdate, BusinessCallbackQuery, BusinessChatLink, BusinessConnection, BusinessMessage, BusinessWorkHoursDay, CallbackQuery, Chat, ChatEvent, ChatInviteLink, ChatInviteLinkMember, ChatJoinRequestUpdate, ChatlistPreview, ChatMember, ChatMemberUpdate, ChatPreview, ChosenInlineResult, CollectibleInfo, DeleteBusinessMessageUpdate, DeleteMessageUpdate, DeleteStoryUpdate, Dialog, FactCheck, FileDownloadLocation, FileDownloadParameters, ForumTopic, FullChat, FullUser, GameHighScore, HistoryReadUpdate, InlineCallbackQuery, InlineQuery, InputChatEventFilters, InputDialogFolder, InputFileLike, InputInlineResult, InputMediaLike, InputMediaSticker, InputMessageId, InputPeerLike, InputPrivacyRule, InputReaction, InputStarGift, InputStickerSet, InputStickerSetItem, InputText, InputWebview, MaybeDynamic, Message, MessageEffect, MessageMedia, MessageReactions, ParametersSkip2, ParsedUpdate, PeerReaction, PeerStories, Photo, Poll, PollUpdate, PollVoteUpdate, PreCheckoutQuery, RawDocument, ReplyMarkup, SavedStarGift, SentCode, StarGift, StarGiftUnique, StarsStatus, StarsTransaction, Sticker, StickerSet, StickerType, StoriesStealthMode, Story, StoryInteractions, StoryUpdate, StoryViewer, StoryViewersList, TakeoutSession, TextWithEntities, TypingStatus, UploadedFile, UploadFileLike, User, UserStarGift, UserStatusUpdate, UserTypingUpdate, WebviewResult } from './types/index.js';
+import { AllStories, ArrayPaginated, ArrayWithTotal, Boost, BoostSlot, BoostStats, BotChatJoinRequestUpdate, BotCommands, BotReactionCountUpdate, BotReactionUpdate, BotStoppedUpdate, BusinessCallbackQuery, BusinessChatLink, BusinessConnection, BusinessMessage, BusinessWorkHoursDay, CallbackQuery, Chat, ChatEvent, ChatInviteLink, ChatInviteLinkMember, ChatJoinRequestUpdate, ChatlistPreview, ChatMember, ChatMemberUpdate, ChatPreview, ChosenInlineResult, CollectibleInfo, DeleteBusinessMessageUpdate, DeleteMessageUpdate, DeleteStoryUpdate, Dialog, FactCheck, FileDownloadLocation, FileDownloadParameters, ForumTopic, FullChat, FullUser, GameHighScore, HistoryReadUpdate, InlineCallbackQuery, InlineQuery, InputChatEventFilters, InputDialogFolder, InputFileLike, InputInlineResult, InputMediaLike, InputMediaSticker, InputMessageId, InputPeerLike, InputPrivacyRule, InputReaction, InputStarGift, InputStickerSet, InputStickerSetItem, InputText, InputWebview, MaybeDynamic, Message, MessageEffect, MessageMedia, MessageReactions, ParametersSkip2, ParsedUpdate, Peer, PeerReaction, PeerStories, Photo, Poll, PollUpdate, PollVoteUpdate, PreCheckoutQuery, RawDocument, ReplyMarkup, SavedStarGift, SentCode, StarGift, StarGiftUnique, StarsStatus, StarsTransaction, Sticker, StickerSet, StickerType, StoriesStealthMode, Story, StoryInteractions, StoryUpdate, StoryViewer, StoryViewersList, TakeoutSession, TextWithEntities, TypingStatus, UploadedFile, UploadFileLike, User, UserStarGift, UserStatusUpdate, UserTypingUpdate, WebviewResult } from './types/index.js';
 import { ParsedUpdateHandlerParams } from './updates/parsed.js';
 import { RawUpdateInfo } from './updates/types.js';
 import { InputStringSessionData } from './utils/string-session.js';
@@ -1298,6 +1298,8 @@ export interface TelegramClient extends ITelegramClient {
      * @param longitude  Longitude of the location
      */
     getNearbyChats(latitude: number, longitude: number): Promise<Chat[]>;
+    /** Shorthand for {@link getChat} and {@link getUser} depending on the type of the peer */
+    getPeer(peer: InputPeerLike): Promise<Peer>;
     /**
      * Get channels that are similar to a given channel
      *
@@ -3942,7 +3944,11 @@ export interface TelegramClient extends ITelegramClient {
     getMyBoostSlots(): Promise<BoostSlot[]>;
     /** Get one or more saved star gifts by their IDs */
     getSavedStarGiftsById(gifts: MaybeArray<InputStarGift>): Promise<SavedStarGift[]>;
-    /** Get a list of saved star gifts of a user */
+    /**
+     * Get a list of saved star gifts of a user/channel
+     *
+     * Note that filters currently only work for channels
+     */
     getSavedStarGifts(params: {
         /** Peer to get saved gifts from */
         owner: InputPeerLike;
@@ -3978,9 +3984,10 @@ export interface TelegramClient extends ITelegramClient {
     /**
      * Get a list of gifts sent to a user.
      *
-     * **Available**: 👤 users only
+     * **Available**: ✅ both users and bots
      *
      * @param userId  User whose gifts to fetch
+     * @deprecated  Use {@link getSavedStarGifts} instead
      * @returns  Gifts sent to the user
      */
     getStarGifts(userId: InputPeerLike, params?: {
@@ -3994,7 +4001,7 @@ export interface TelegramClient extends ITelegramClient {
          * @default  100
          */
         limit?: number;
-    }): Promise<ArrayPaginated<UserStarGift, string>>;
+    }): Promise<ArrayPaginated<SavedStarGift, string>>;
     /**
      * Get Telegram Stars transactions for a given peer.
      *
@@ -4141,7 +4148,7 @@ export interface TelegramClient extends ITelegramClient {
      *
      * **Available**: 👤 users only
      *
-     * @returns  Service message about the sent gift
+     * @returns  Service message about the sent gift, if one was generated.
      */
     sendStarGift(params: {
         /** ID of the peer to send the gift to */
@@ -4163,7 +4170,7 @@ export interface TelegramClient extends ITelegramClient {
          * to the client's update handler.
          */
         shouldDispatch?: true;
-    }): Promise<Message>;
+    }): Promise<Message | null>;
     /**
      * Set current user's business introduction.
      *
@@ -4212,7 +4219,7 @@ export interface TelegramClient extends ITelegramClient {
      *
      * **Available**: 👤 users only
      *
-     * @returns  Service message about the transferred gift
+     * @returns  Service message about the transferred gift, if one was generated.
      */
     transferStarGift(params: {
         /** Star gift to transfer */
@@ -4224,7 +4231,7 @@ export interface TelegramClient extends ITelegramClient {
          * to the client's update handler.
          */
         shouldDispatch?: true;
-    }): Promise<Message>;
+    }): Promise<Message | null>;
     /**
      * Upgrades a star gift to a unique gift.
      *
@@ -4235,7 +4242,7 @@ export interface TelegramClient extends ITelegramClient {
      *
      * **Available**: 👤 users only
      *
-     * @returns  Service message about the upgraded gift
+     * @returns  Service message about the upgraded gift, if one was generated.
      */
     upgradeStarGift(params: {
         gift: InputStarGift;
@@ -4249,7 +4256,7 @@ export interface TelegramClient extends ITelegramClient {
          * to the client's update handler.
          */
         shouldDispatch?: true;
-    }): Promise<Message>;
+    }): Promise<Message | null>;
     /**
      * Add a sticker to a sticker set.
      *

package/highlevel/methods/chats/get-peer.cjs

@@ -0,0 +1,19 @@
+if (typeof globalThis !== "undefined" && !globalThis._MTCUTE_CJS_DEPRECATION_WARNED) {
+  globalThis._MTCUTE_CJS_DEPRECATION_WARNED = true;
+  console.warn("[@mtcute/core] CommonJS support is deprecated and will be removed in 0.25.0. Please consider switching to ESM, it's " + (/* @__PURE__ */ new Date()).getFullYear() + " already.");
+  console.warn("[@mtcute/core] Learn more about switching to ESM: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c");
+}
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const peerUtils = require("../../utils/peer-utils.cjs");
+const resolvePeer = require("../users/resolve-peer.cjs");
+const getChat = require("./get-chat.cjs");
+const getUser = require("./get-user.cjs");
+async function getPeer(client, peer) {
+  const resolved = await resolvePeer.resolvePeer(client, peer);
+  if (peerUtils.isInputPeerUser(resolved)) {
+    return getUser.getUser(client, resolved);
+  }
+  return getChat.getChat(client, resolved);
+}
+exports.getPeer = getPeer;

package/highlevel/methods/chats/get-peer.d.cts

@@ -0,0 +1,4 @@
+import { ITelegramClient } from '../../client.types.js';
+import { InputPeerLike, Peer } from '../../types/index.js';
+/** Shorthand for {@link getChat} and {@link getUser} depending on the type of the peer */
+export declare function getPeer(client: ITelegramClient, peer: InputPeerLike): Promise<Peer>;

package/highlevel/methods/chats/get-peer.d.ts

@@ -0,0 +1,4 @@
+import { ITelegramClient } from '../../client.types.js';
+import { InputPeerLike, Peer } from '../../types/index.js';
+/** Shorthand for {@link getChat} and {@link getUser} depending on the type of the peer */
+export declare function getPeer(client: ITelegramClient, peer: InputPeerLike): Promise<Peer>;

package/highlevel/methods/chats/get-peer.js

@@ -0,0 +1,14 @@
+import { isInputPeerUser } from "../../utils/peer-utils.js";
+import { resolvePeer } from "../users/resolve-peer.js";
+import { getChat } from "./get-chat.js";
+import { getUser } from "./get-user.js";
+async function getPeer(client, peer) {
+  const resolved = await resolvePeer(client, peer);
+  if (isInputPeerUser(resolved)) {
+    return getUser(client, resolved);
+  }
+  return getChat(client, resolved);
+}
+export {
+  getPeer
+};

package/highlevel/methods/premium/send-star-gift.cjs

@@ -37,6 +37,6 @@ async function sendStarGift(client, params) {
     formId: form.formId
   });
   typeAssertions.assertTypeIs("payments.sendStarsForm", res, "payments.paymentResult");
-  return findInUpdate._findMessageInUpdate(client, res.updates, false, !shouldDispatch);
+  return findInUpdate._findMessageInUpdate(client, res.updates, false, !shouldDispatch, true);
 }
 exports.sendStarGift = sendStarGift;

package/highlevel/methods/premium/send-star-gift.d.cts

@@ -12,7 +12,7 @@ import { InputText } from '../../types/misc/entities.js';
  * > For GUI clients, you should refer to the method's source code and
  * > present the payment form to the user.
  *
- * @returns  Service message about the sent gift
+ * @returns  Service message about the sent gift, if one was generated.
  */
 export declare function sendStarGift(client: ITelegramClient, params: {
     /** ID of the peer to send the gift to */
@@ -34,4 +34,4 @@ export declare function sendStarGift(client: ITelegramClient, params: {
      * to the client's update handler.
      */
     shouldDispatch?: true;
-}): Promise<Message>;
+}): Promise<Message | null>;

package/highlevel/methods/premium/send-star-gift.d.ts

@@ -12,7 +12,7 @@ import { InputText } from '../../types/misc/entities.js';
  * > For GUI clients, you should refer to the method's source code and
  * > present the payment form to the user.
  *
- * @returns  Service message about the sent gift
+ * @returns  Service message about the sent gift, if one was generated.
  */
 export declare function sendStarGift(client: ITelegramClient, params: {
     /** ID of the peer to send the gift to */
@@ -34,4 +34,4 @@ export declare function sendStarGift(client: ITelegramClient, params: {
      * to the client's update handler.
      */
     shouldDispatch?: true;
-}): Promise<Message>;
+}): Promise<Message | null>;

package/highlevel/methods/premium/send-star-gift.js

@@ -30,7 +30,7 @@ async function sendStarGift(client, params) {
     formId: form.formId
   });
   assertTypeIs("payments.sendStarsForm", res, "payments.paymentResult");
-  return _findMessageInUpdate(client, res.updates, false, !shouldDispatch);
+  return _findMessageInUpdate(client, res.updates, false, !shouldDispatch, true);
 }
 export {
   sendStarGift

package/highlevel/methods/premium/transfer-star-gift.cjs

@@ -26,6 +26,6 @@ async function transferStarGift(client, params) {
     formId: form.formId
   });
   typeAssertions.assertTypeIs("payments.sendStarsForm", res, "payments.paymentResult");
-  return findInUpdate._findMessageInUpdate(client, res.updates, false, !shouldDispatch);
+  return findInUpdate._findMessageInUpdate(client, res.updates, false, !shouldDispatch, true);
 }
 exports.transferStarGift = transferStarGift;

package/highlevel/methods/premium/transfer-star-gift.d.cts

@@ -9,7 +9,7 @@ import { Message } from '../../types/messages/message.js';
  * > For GUI clients, you should refer to the method's source code and
  * > present the payment form to the user.
  *
- * @returns  Service message about the transferred gift
+ * @returns  Service message about the transferred gift, if one was generated.
  */
 export declare function transferStarGift(client: ITelegramClient, params: {
     /** Star gift to transfer */
@@ -21,4 +21,4 @@ export declare function transferStarGift(client: ITelegramClient, params: {
      * to the client's update handler.
      */
     shouldDispatch?: true;
-}): Promise<Message>;
+}): Promise<Message | null>;

package/highlevel/methods/premium/transfer-star-gift.d.ts

@@ -9,7 +9,7 @@ import { Message } from '../../types/messages/message.js';
  * > For GUI clients, you should refer to the method's source code and
  * > present the payment form to the user.
  *
- * @returns  Service message about the transferred gift
+ * @returns  Service message about the transferred gift, if one was generated.
  */
 export declare function transferStarGift(client: ITelegramClient, params: {
     /** Star gift to transfer */
@@ -21,4 +21,4 @@ export declare function transferStarGift(client: ITelegramClient, params: {
      * to the client's update handler.
      */
     shouldDispatch?: true;
-}): Promise<Message>;
+}): Promise<Message | null>;

package/highlevel/methods/premium/transfer-star-gift.js

@@ -19,7 +19,7 @@ async function transferStarGift(client, params) {
     formId: form.formId
   });
   assertTypeIs("payments.sendStarsForm", res, "payments.paymentResult");
-  return _findMessageInUpdate(client, res.updates, false, !shouldDispatch);
+  return _findMessageInUpdate(client, res.updates, false, !shouldDispatch, true);
 }
 export {
   transferStarGift

package/highlevel/methods/premium/upgrade-star-gift.cjs

@@ -25,6 +25,6 @@ async function upgradeStarGift(client, params) {
     formId: form.formId
   });
   typeAssertions.assertTypeIs("payments.sendStarsForm", res, "payments.paymentResult");
-  return findInUpdate._findMessageInUpdate(client, res.updates, false, !shouldDispatch);
+  return findInUpdate._findMessageInUpdate(client, res.updates, false, !shouldDispatch, true);
 }
 exports.upgradeStarGift = upgradeStarGift;

package/highlevel/methods/premium/upgrade-star-gift.d.cts

@@ -9,7 +9,7 @@ import { Message } from '../../types/messages/message.js';
  * > For GUI clients, you should refer to the method's source code and
  * > present the payment form to the user.
  *
- * @returns  Service message about the upgraded gift
+ * @returns  Service message about the upgraded gift, if one was generated.
  */
 export declare function upgradeStarGift(client: ITelegramClient, params: {
     gift: InputStarGift;
@@ -23,4 +23,4 @@ export declare function upgradeStarGift(client: ITelegramClient, params: {
      * to the client's update handler.
      */
     shouldDispatch?: true;
-}): Promise<Message>;
+}): Promise<Message | null>;

package/highlevel/methods/premium/upgrade-star-gift.d.ts

@@ -9,7 +9,7 @@ import { Message } from '../../types/messages/message.js';
  * > For GUI clients, you should refer to the method's source code and
  * > present the payment form to the user.
  *
- * @returns  Service message about the upgraded gift
+ * @returns  Service message about the upgraded gift, if one was generated.
  */
 export declare function upgradeStarGift(client: ITelegramClient, params: {
     gift: InputStarGift;
@@ -23,4 +23,4 @@ export declare function upgradeStarGift(client: ITelegramClient, params: {
      * to the client's update handler.
      */
     shouldDispatch?: true;
-}): Promise<Message>;
+}): Promise<Message | null>;

package/highlevel/methods/premium/upgrade-star-gift.js

@@ -18,7 +18,7 @@ async function upgradeStarGift(client, params) {
     formId: form.formId
   });
   assertTypeIs("payments.sendStarsForm", res, "payments.paymentResult");
-  return _findMessageInUpdate(client, res.updates, false, !shouldDispatch);
+  return _findMessageInUpdate(client, res.updates, false, !shouldDispatch, true);
 }
 export {
   upgradeStarGift

package/highlevel/methods.d.cts

@@ -54,6 +54,7 @@ export { getChat } from './methods/chats/get-chat.js';
 export { getFullChat } from './methods/chats/get-full-chat.js';
 export { getFullUser } from './methods/chats/get-full-user.js';
 export { getNearbyChats } from './methods/chats/get-nearby-chats.js';
+export { getPeer } from './methods/chats/get-peer.js';
 export { getSimilarChannels } from './methods/chats/get-similar-channels.js';
 export { getUser } from './methods/chats/get-user.js';
 export { iterChatEventLog } from './methods/chats/iter-chat-event-log.js';

package/highlevel/methods.d.ts

@@ -54,6 +54,7 @@ export { getChat } from './methods/chats/get-chat.js';
 export { getFullChat } from './methods/chats/get-full-chat.js';
 export { getFullUser } from './methods/chats/get-full-user.js';
 export { getNearbyChats } from './methods/chats/get-nearby-chats.js';
+export { getPeer } from './methods/chats/get-peer.js';
 export { getSimilarChannels } from './methods/chats/get-similar-channels.js';
 export { getUser } from './methods/chats/get-user.js';
 export { iterChatEventLog } from './methods/chats/iter-chat-event-log.js';

package/highlevel/types/misc/takeout-session.cjs

@@ -26,14 +26,19 @@ class TakeoutSession {
    * @param params  Additional call parameters
    */
   async call(message, params) {
-    return this.client.call(
-      {
-        _: "invokeWithTakeout",
-        takeoutId: this.id,
-        query: message
-      },
-      params
-    );
+    let query = {
+      _: "invokeWithTakeout",
+      takeoutId: this.id,
+      query: message
+    };
+    if (params?.withMessageRange) {
+      query = {
+        _: "invokeWithMessagesRange",
+        range: params.withMessageRange,
+        query
+      };
+    }
+    return this.client.call(query, params);
   }
   /**
    * Create a proxy over {@link TelegramClient}
@@ -42,20 +47,12 @@ class TakeoutSession {
    * You can optionally provide a function to check if some
    * RPC method should be called via a takeout session or directly,
    * otherwise all methods are called through the takeout session.
-   *
-   * > **Note**: This will return a `Proxy` object that
-   * > overrides `call` method. Using this method requires
-   * > that your target environment supports `Proxy` and `Reflect` APIs
-   *
-   * @param predicate
-   *     Function that given the RPC call should determine whether
-   *     that call should be called via takeout session or not.
-   *     Returning `true` will use takeout session, `false` will not.
    */
-  createProxy(predicate) {
-    const boundCall = predicate ? (obj, params) => {
-      if (predicate(obj)) {
-        return this.call(obj, params);
+  createProxy(params) {
+    const boundCall = params ? (obj, theirParams) => {
+      const mergedParams = theirParams ? { ...params, ...theirParams } : params;
+      if (!params.predicate || params.predicate?.(obj)) {
+        return this.call(obj, mergedParams);
       }
       return this.client.call(obj, params);
     } : this.call.bind(this);

package/highlevel/types/misc/takeout-session.d.cts

@@ -21,7 +21,10 @@ export declare class TakeoutSession {
      * @param message  RPC method to call
      * @param params  Additional call parameters
      */
-    call<T extends tl.RpcMethod>(message: MustEqual<T, tl.RpcMethod>, params?: RpcCallOptions): Promise<tl.RpcCallReturn[T['_']]>;
+    call<T extends tl.RpcMethod>(message: MustEqual<T, tl.RpcMethod>, params?: RpcCallOptions & {
+        /** If passed, the request will be wrapped in an `invokeWithMessagesRange` */
+        withMessageRange?: tl.TypeMessageRange;
+    }): Promise<tl.RpcCallReturn[T['_']]>;
     /**
      * Create a proxy over {@link TelegramClient}
      * that will use this takeout session to call methods.
@@ -29,17 +32,19 @@ export declare class TakeoutSession {
      * You can optionally provide a function to check if some
      * RPC method should be called via a takeout session or directly,
      * otherwise all methods are called through the takeout session.
-     *
-     * > **Note**: This will return a `Proxy` object that
-     * > overrides `call` method. Using this method requires
-     * > that your target environment supports `Proxy` and `Reflect` APIs
-     *
-     * @param predicate
-     *     Function that given the RPC call should determine whether
-     *     that call should be called via takeout session or not.
-     *     Returning `true` will use takeout session, `false` will not.
      */
-    createProxy(predicate?: (obj: tl.TlObject) => boolean): ITelegramClient;
+    createProxy(params?: RpcCallOptions & {
+        /**
+         * Function that given the RPC call should determine whether
+         * that call should be called via takeout session (and use the rest of the params passed here) or not.
+         * Returning `true` will use takeout session, `false` will call the method directly.
+         *
+         * @default  `undefined`, i.e. all calls are sent via takeout session
+         */
+        predicate?: (obj: tl.TlObject) => boolean;
+        /** If passed, the request will be wrapped in an `invokeWithMessagesRange` */
+        withMessageRange?: tl.TypeMessageRange;
+    }): ITelegramClient;
     /**
      * Finish account takeout session
      *

package/highlevel/types/misc/takeout-session.d.ts

@@ -21,7 +21,10 @@ export declare class TakeoutSession {
      * @param message  RPC method to call
      * @param params  Additional call parameters
      */
-    call<T extends tl.RpcMethod>(message: MustEqual<T, tl.RpcMethod>, params?: RpcCallOptions): Promise<tl.RpcCallReturn[T['_']]>;
+    call<T extends tl.RpcMethod>(message: MustEqual<T, tl.RpcMethod>, params?: RpcCallOptions & {
+        /** If passed, the request will be wrapped in an `invokeWithMessagesRange` */
+        withMessageRange?: tl.TypeMessageRange;
+    }): Promise<tl.RpcCallReturn[T['_']]>;
     /**
      * Create a proxy over {@link TelegramClient}
      * that will use this takeout session to call methods.
@@ -29,17 +32,19 @@ export declare class TakeoutSession {
      * You can optionally provide a function to check if some
      * RPC method should be called via a takeout session or directly,
      * otherwise all methods are called through the takeout session.
-     *
-     * > **Note**: This will return a `Proxy` object that
-     * > overrides `call` method. Using this method requires
-     * > that your target environment supports `Proxy` and `Reflect` APIs
-     *
-     * @param predicate
-     *     Function that given the RPC call should determine whether
-     *     that call should be called via takeout session or not.
-     *     Returning `true` will use takeout session, `false` will not.
      */
-    createProxy(predicate?: (obj: tl.TlObject) => boolean): ITelegramClient;
+    createProxy(params?: RpcCallOptions & {
+        /**
+         * Function that given the RPC call should determine whether
+         * that call should be called via takeout session (and use the rest of the params passed here) or not.
+         * Returning `true` will use takeout session, `false` will call the method directly.
+         *
+         * @default  `undefined`, i.e. all calls are sent via takeout session
+         */
+        predicate?: (obj: tl.TlObject) => boolean;
+        /** If passed, the request will be wrapped in an `invokeWithMessagesRange` */
+        withMessageRange?: tl.TypeMessageRange;
+    }): ITelegramClient;
     /**
      * Finish account takeout session
      *

package/highlevel/types/misc/takeout-session.js

@@ -19,14 +19,19 @@ class TakeoutSession {
    * @param params  Additional call parameters
    */
   async call(message, params) {
-    return this.client.call(
-      {
-        _: "invokeWithTakeout",
-        takeoutId: this.id,
-        query: message
-      },
-      params
-    );
+    let query = {
+      _: "invokeWithTakeout",
+      takeoutId: this.id,
+      query: message
+    };
+    if (params?.withMessageRange) {
+      query = {
+        _: "invokeWithMessagesRange",
+        range: params.withMessageRange,
+        query
+      };
+    }
+    return this.client.call(query, params);
   }
   /**
    * Create a proxy over {@link TelegramClient}
@@ -35,20 +40,12 @@ class TakeoutSession {
    * You can optionally provide a function to check if some
    * RPC method should be called via a takeout session or directly,
    * otherwise all methods are called through the takeout session.
-   *
-   * > **Note**: This will return a `Proxy` object that
-   * > overrides `call` method. Using this method requires
-   * > that your target environment supports `Proxy` and `Reflect` APIs
-   *
-   * @param predicate
-   *     Function that given the RPC call should determine whether
-   *     that call should be called via takeout session or not.
-   *     Returning `true` will use takeout session, `false` will not.
    */
-  createProxy(predicate) {
-    const boundCall = predicate ? (obj, params) => {
-      if (predicate(obj)) {
-        return this.call(obj, params);
+  createProxy(params) {
+    const boundCall = params ? (obj, theirParams) => {
+      const mergedParams = theirParams ? { ...params, ...theirParams } : params;
+      if (!params.predicate || params.predicate?.(obj)) {
+        return this.call(obj, mergedParams);
       }
       return this.client.call(obj, params);
     } : this.call.bind(this);

package/index.cjs

@@ -152,6 +152,7 @@ const utils = require("./types/utils.cjs");
 exports.Long = Long;
 exports.getAllPeersFrom = peerUtils.getAllPeersFrom;
 exports.getBarePeerId = peerUtils.getBarePeerId;
+exports.getBasicPeerType = peerUtils.getBasicPeerType;
 exports.getMarkedPeerId = peerUtils.getMarkedPeerId;
 exports.parseMarkedPeerId = peerUtils.parseMarkedPeerId;
 exports.toggleChannelIdMark = peerUtils.toggleChannelIdMark;

package/index.js

@@ -1,5 +1,5 @@
 import { default as default2 } from "long";
-import { getAllPeersFrom, getBarePeerId, getMarkedPeerId, parseMarkedPeerId, toggleChannelIdMark } from "./utils/peer-utils.js";
+import { getAllPeersFrom, getBarePeerId, getBasicPeerType, getMarkedPeerId, parseMarkedPeerId, toggleChannelIdMark } from "./utils/peer-utils.js";
 import { mtp, tl } from "@mtcute/tl";
 import { TelegramStorageManager } from "./highlevel/storage/storage.js";
 import { SentCode } from "./highlevel/types/auth/sent-code.js";
@@ -308,6 +308,7 @@ export {
   businessWorkHoursDaysToRaw,
   getAllPeersFrom,
   getBarePeerId,
+  getBasicPeerType,
   getMarkedPeerId,
   inputTextToTl,
   isUploadedFile,

package/methods.cjs

@@ -56,6 +56,7 @@ const getChat = require("./highlevel/methods/chats/get-chat.cjs");
 const getFullChat = require("./highlevel/methods/chats/get-full-chat.cjs");
 const getFullUser = require("./highlevel/methods/chats/get-full-user.cjs");
 const getNearbyChats = require("./highlevel/methods/chats/get-nearby-chats.cjs");
+const getPeer = require("./highlevel/methods/chats/get-peer.cjs");
 const getSimilarChannels = require("./highlevel/methods/chats/get-similar-channels.cjs");
 const getUser = require("./highlevel/methods/chats/get-user.cjs");
 const iterChatEventLog = require("./highlevel/methods/chats/iter-chat-event-log.cjs");
@@ -317,6 +318,7 @@ exports.getChat = getChat.getChat;
 exports.getFullChat = getFullChat.getFullChat;
 exports.getFullUser = getFullUser.getFullUser;
 exports.getNearbyChats = getNearbyChats.getNearbyChats;
+exports.getPeer = getPeer.getPeer;
 exports.getSimilarChannels = getSimilarChannels.getSimilarChannels;
 exports.getUser = getUser.getUser;
 exports.iterChatEventLog = iterChatEventLog.iterChatEventLog;

package/methods.js

@@ -49,6 +49,7 @@ import { getChat } from "./highlevel/methods/chats/get-chat.js";
 import { getFullChat } from "./highlevel/methods/chats/get-full-chat.js";
 import { getFullUser } from "./highlevel/methods/chats/get-full-user.js";
 import { getNearbyChats } from "./highlevel/methods/chats/get-nearby-chats.js";
+import { getPeer } from "./highlevel/methods/chats/get-peer.js";
 import { getSimilarChannels } from "./highlevel/methods/chats/get-similar-channels.js";
 import { getUser } from "./highlevel/methods/chats/get-user.js";
 import { iterChatEventLog } from "./highlevel/methods/chats/iter-chat-event-log.js";
@@ -379,6 +380,7 @@ export {
   getMyUsername,
   getNearbyChats,
   getPasswordHint,
+  getPeer,
   getPeerDialogs,
   getPeerStories,
   getPrimaryInviteLink,

package/network/network-manager.cjs

@@ -220,7 +220,7 @@ class NetworkManager {
       _: "initConnection",
       deviceModel,
       systemVersion: "1.0",
-      appVersion: "0.20.4",
+      appVersion: "0.21.0",
       systemLangCode: "en",
       langPack: "",
       // "langPacks are for official apps only"

package/network/network-manager.js

@@ -213,7 +213,7 @@ class NetworkManager {
       _: "initConnection",
       deviceModel,
       systemVersion: "1.0",
-      appVersion: "0.20.4",
+      appVersion: "0.21.0",
       systemLangCode: "en",
       langPack: "",
       // "langPacks are for official apps only"

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@mtcute/core",
     "type": "module",
-    "version": "0.20.4",
+    "version": "0.21.0",
     "description": "Type-safe library for MTProto (Telegram API)",
     "license": "MIT",
     "scripts": {},

package/utils/peer-utils.cjs

@@ -6,6 +6,7 @@ if (typeof globalThis !== "undefined" && !globalThis._MTCUTE_CJS_DEPRECATION_WAR
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const errors = require("../types/errors.cjs");
+const utils = require("../types/utils.cjs");
 const ZERO_CHANNEL_ID = -1e12;
 const ZERO_SECRET_CHAT_ID = -2e12;
 const MAX_SECRET_CHAT_ID = -1997852516353;
@@ -136,8 +137,51 @@ function* getAllPeersFrom(obj) {
     }
   }
 }
+function getBasicPeerType(id) {
+  if (typeof id === "number") {
+    if (id < 0) {
+      if (MIN_MARKED_CHAT_ID <= id) {
+        return "chat";
+      }
+      if (MIN_MARKED_CHANNEL_ID <= id && id !== ZERO_CHANNEL_ID) {
+        return "channel";
+      }
+    } else if (id > 0 && id <= MAX_USER_ID) {
+      return "user";
+    }
+    throw new Error(`Invalid marked peer id: ${id}`);
+  }
+  switch (id._) {
+    case "peerUser":
+    case "inputUser":
+    case "inputUserSelf":
+    case "inputPeerSelf":
+    case "inputUserFromMessage":
+    case "inputPeerUser":
+    case "inputPeerUserFromMessage":
+    case "inputUserEmpty":
+    case "mtcute.dummyInputPeerMinUser":
+      return "user";
+    case "peerChat":
+    case "inputPeerChat":
+      return "chat";
+    case "peerChannel":
+    case "inputChannel":
+    case "inputChannelEmpty":
+    case "mtcute.dummyInputPeerMinChannel":
+    case "inputChannelFromMessage":
+    case "inputPeerChannel":
+    case "inputPeerChannelFromMessage":
+      return "channel";
+    case "inputPeerEmpty":
+      throw new Error("Empty peer");
+    default:
+      utils.assertNever();
+  }
+}
 exports.getAllPeersFrom = getAllPeersFrom;
 exports.getBarePeerId = getBarePeerId;
+exports.getBasicPeerType = getBasicPeerType;
 exports.getMarkedPeerId = getMarkedPeerId;
 exports.parseMarkedPeerId = parseMarkedPeerId;
 exports.toggleChannelIdMark = toggleChannelIdMark;

package/utils/peer-utils.d.cts

@@ -27,3 +27,5 @@ export declare function parseMarkedPeerId(id: number): [BasicPeerType, number];
  * Only checks `.user`, `.chat`, `.channel`, `.users` and `.chats` properties
  */
 export declare function getAllPeersFrom(obj: tl.TlObject | tl.TlObject[]): Iterable<tl.TypeUser | tl.TypeChat>;
+/** Get the {@link BasicPeerType} of a peer, either by its marked ID or by its TL object */
+export declare function getBasicPeerType(id: number | tl.TypePeer | tl.TypeInputPeer | tl.TypeInputUser | tl.TypeInputChannel): BasicPeerType;

package/utils/peer-utils.d.ts

@@ -27,3 +27,5 @@ export declare function parseMarkedPeerId(id: number): [BasicPeerType, number];
  * Only checks `.user`, `.chat`, `.channel`, `.users` and `.chats` properties
  */
 export declare function getAllPeersFrom(obj: tl.TlObject | tl.TlObject[]): Iterable<tl.TypeUser | tl.TypeChat>;
+/** Get the {@link BasicPeerType} of a peer, either by its marked ID or by its TL object */
+export declare function getBasicPeerType(id: number | tl.TypePeer | tl.TypeInputPeer | tl.TypeInputUser | tl.TypeInputChannel): BasicPeerType;

package/utils/peer-utils.js

@@ -1,4 +1,5 @@
 import { MtUnsupportedError, MtArgumentError } from "../types/errors.js";
+import { assertNever } from "../types/utils.js";
 const ZERO_CHANNEL_ID = -1e12;
 const ZERO_SECRET_CHAT_ID = -2e12;
 const MAX_SECRET_CHAT_ID = -1997852516353;
@@ -129,9 +130,52 @@ function* getAllPeersFrom(obj) {
     }
   }
 }
+function getBasicPeerType(id) {
+  if (typeof id === "number") {
+    if (id < 0) {
+      if (MIN_MARKED_CHAT_ID <= id) {
+        return "chat";
+      }
+      if (MIN_MARKED_CHANNEL_ID <= id && id !== ZERO_CHANNEL_ID) {
+        return "channel";
+      }
+    } else if (id > 0 && id <= MAX_USER_ID) {
+      return "user";
+    }
+    throw new Error(`Invalid marked peer id: ${id}`);
+  }
+  switch (id._) {
+    case "peerUser":
+    case "inputUser":
+    case "inputUserSelf":
+    case "inputPeerSelf":
+    case "inputUserFromMessage":
+    case "inputPeerUser":
+    case "inputPeerUserFromMessage":
+    case "inputUserEmpty":
+    case "mtcute.dummyInputPeerMinUser":
+      return "user";
+    case "peerChat":
+    case "inputPeerChat":
+      return "chat";
+    case "peerChannel":
+    case "inputChannel":
+    case "inputChannelEmpty":
+    case "mtcute.dummyInputPeerMinChannel":
+    case "inputChannelFromMessage":
+    case "inputPeerChannel":
+    case "inputPeerChannelFromMessage":
+      return "channel";
+    case "inputPeerEmpty":
+      throw new Error("Empty peer");
+    default:
+      assertNever();
+  }
+}
 export {
   getAllPeersFrom,
   getBarePeerId,
+  getBasicPeerType,
   getMarkedPeerId,
   parseMarkedPeerId,
   toggleChannelIdMark

package/utils.cjs

@@ -71,6 +71,7 @@ exports.getRandomInt = miscUtils$1.getRandomInt;
 exports.sleepWithAbort = miscUtils$1.sleepWithAbort;
 exports.getAllPeersFrom = peerUtils$1.getAllPeersFrom;
 exports.getBarePeerId = peerUtils$1.getBarePeerId;
+exports.getBasicPeerType = peerUtils$1.getBasicPeerType;
 exports.getMarkedPeerId = peerUtils$1.getMarkedPeerId;
 exports.parseMarkedPeerId = peerUtils$1.parseMarkedPeerId;
 exports.toggleChannelIdMark = peerUtils$1.toggleChannelIdMark;

package/utils.js

@@ -10,7 +10,7 @@ import { SortedLinkedList } from "./utils/linked-list.js";
 import { LogManager, Logger } from "./utils/logger.js";
 import { LongMap, LongSet, compareLongs, longFromBuffer, longFromFastString, longToFastString, randomLong, removeFromLongArray } from "./utils/long-utils.js";
 import { getRandomInt, sleepWithAbort } from "./utils/misc-utils.js";
-import { getAllPeersFrom, getBarePeerId, getMarkedPeerId, parseMarkedPeerId, toggleChannelIdMark } from "./utils/peer-utils.js";
+import { getAllPeersFrom, getBarePeerId, getBasicPeerType, getMarkedPeerId, parseMarkedPeerId, toggleChannelIdMark } from "./utils/peer-utils.js";
 import { SortedArray } from "./utils/sorted-array.js";
 import { jsonToTlJson, tlJsonToJson } from "./utils/tl-json.js";
 import { assertTrue, assertTypeIs, assertTypeIsNot, hasValueAtKey, isPresent, isTlRpcError, mtpAssertTypeIs } from "./utils/type-assertions.js";
@@ -80,6 +80,7 @@ export {
   generateKeyAndIvFromNonce,
   getAllPeersFrom,
   getBarePeerId,
+  getBasicPeerType,
   getMarkedPeerId,
   getRandomInt,
   hasValueAtKey,