xzcgram 0.0.1 → 0.0.3

package/src/context.js

@@ -33,12 +33,83 @@ class Context {
     this.event = event;
     /** Raw GramJS message object */
     this.message = event.message;
-    /** Chat/peer id where the message was sent */
+    /** Chat/peer id where the message was sent (numeric, informational) */
     this.chatId = this.message.chatId;
     /** Full text of the incoming message */
     this.text = this.message.message || "";
     /** Command arguments, e.g. "/start foo bar" -> ["foo", "bar"] */
     this.args = this.text.split(" ").slice(1);
+
+    // -- Extra metadata (read-only, straight from the raw message) --
+
+    /** Id of the user/chat that sent the message */
+    this.senderId = this.message.senderId || null;
+    /** Unix timestamp the message was sent at */
+    this.date = this.message.date || null;
+    /** Unix timestamp the message was last edited at, if any */
+    this.editDate = this.message.editDate || null;
+
+    /** true if this message came through an inline bot (@bot query) */
+    this.viaBotId = this.message.viaBotId || null;
+    /** true if this message came through a Telegram Business connected bot */
+    this.viaBusinessBotId = this.message.viaBusinessBotId || null;
+
+    /** true if the chat is a private 1-on-1 DM */
+    this.isPrivate = !!this.message.isPrivate;
+    /** true if the chat is a basic group */
+    this.isGroup = !!this.message.isGroup;
+    /** true if the chat is a channel or supergroup */
+    this.isChannel = !!this.message.isChannel;
+
+    /** Id of the message this one is replying to, if any */
+    this.replyToMsgId = this.message.replyTo ? this.message.replyTo.replyToMsgId : null;
+    /** true if this message is a reply to another message */
+    this.isReply = !!this.replyToMsgId;
+    
+    /** get entities from replied message */
+    this.replyMessage = this.message.replyTo ? this.client.getMessages(this.chatId, { ids: [this.replyToMsgId] }) : [];
+    /** Forward header info, if this message was forwarded */
+    this.fwdFrom = this.message.fwdFrom || null;
+    /** true if this message was forwarded from elsewhere */
+    this.isForwarded = !!this.fwdFrom;
+
+    /** Message entities (bold, links, mentions, etc.) */
+    this.entities = this.message.entities || [];
+
+    /** Raw media object attached to the message, if any (photo/video/doc/etc.) */
+    this.media = this.message.media || null;
+    /** true if the message has any attached media */
+    this.hasMedia = !!this.message.media;
+    /** Short class name of the attached media, e.g. "MessageMediaPhoto" */
+    this.mediaType = this.message.media ? this.message.media.className : null;
+
+    /** true if the message was sent silently (no notification) */
+    this.silent = !!this.message.silent;
+    /** true if this message was sent by the account this client is logged into */
+    this.out = !!this.message.out;
+    /** true if the message is pinned */
+    this.pinned = !!this.message.pinned;
+    /** Grouped media id, if this message is part of an album */
+    this.groupedId = this.message.groupedId || null;
+  }
+
+
+  /**
+   * Resolves the correct peer to send to/act on.
+   * Uses message.getInputChat() first, since it carries the access_hash
+   * from the incoming update — this avoids "Could not find the input
+   * entity" errors that happen when using a raw numeric chatId for a
+   * user/chat the client hasn't cached yet (e.g. first DM from someone new).
+   * Falls back to the raw chatId if getInputChat() can't resolve anything.
+   */
+  async peer() {
+    try {
+      const inputChat = await this.message.getInputChat();
+      if (inputChat) return inputChat;
+    } catch (err) {
+      // fall through to raw chatId below
+    }
+    return this.chatId;
   }
 
   // ---------------------------------------------------------------------
@@ -46,13 +117,15 @@ class Context {
   // ---------------------------------------------------------------------
 
   /** Reply in the same chat the message came from. */
-  reply(text, opts = {}) {
-    return this.client.sendMessage(this.chatId, { message: text, ...opts });
+  async reply(text, opts = {}) {
+    const peer = await this.peer();
+    return this.client.sendMessage(peer, { message: text, ...opts });
   }
 
   /** Reply directly to the triggering message (quote-style reply). */
-  replyQuote(text, opts = {}) {
-    return this.client.sendMessage(this.chatId, {
+  async replyQuote(text, opts = {}) {
+    const peer = await this.peer();
+    return this.client.sendMessage(peer, {
       message: text,
       replyTo: this.message.id,
       ...opts,
@@ -60,8 +133,9 @@ class Context {
   }
 
   /** Edit a message previously sent in this chat (must be your own message). */
-  editMessage(messageId, text, opts = {}) {
-    return this.client.editMessage(this.chatId, {
+  async editMessage(messageId, text, opts = {}) {
+    const peer = await this.peer();
+    return this.client.editMessage(peer, {
       message: messageId,
       text,
       ...opts,
@@ -73,13 +147,15 @@ class Context {
   // ---------------------------------------------------------------------
 
   /** Send a photo. `file` can be a path, Buffer, URL, or existing file id. */
-  replyWithPhoto(file, opts = {}) {
-    return this.client.sendFile(this.chatId, { file, ...opts });
+  async replyWithPhoto(file, opts = {}) {
+    const peer = await this.peer();
+    return this.client.sendFile(peer, { file, ...opts });
   }
 
   /** Send a video. Pass `opts.supportsStreaming = true` for streamable playback. */
-  replyWithVideo(file, opts = {}) {
-    return this.client.sendFile(this.chatId, {
+  async replyWithVideo(file, opts = {}) {
+    const peer = await this.peer();
+    return this.client.sendFile(peer, {
       file,
       supportsStreaming: true,
       ...opts,
@@ -87,23 +163,27 @@ class Context {
   }
 
   /** Send a round "video note" (the circular video bubble). */
-  replyWithVideoNote(file, opts = {}) {
-    return this.client.sendFile(this.chatId, { file, videoNote: true, ...opts });
+  async replyWithVideoNote(file, opts = {}) {
+    const peer = await this.peer();
+    return this.client.sendFile(peer, { file, videoNote: true, ...opts });
   }
 
   /** Send an audio file (music, shown with player + duration/title). */
-  replyWithAudio(file, opts = {}) {
-    return this.client.sendFile(this.chatId, { file, ...opts });
+  async replyWithAudio(file, opts = {}) {
+    const peer = await this.peer();
+    return this.client.sendFile(peer, { file, ...opts });
   }
 
   /** Send a voice note (the waveform bubble). */
-  replyWithVoice(file, opts = {}) {
-    return this.client.sendFile(this.chatId, { file, voiceNote: true, ...opts });
+  async replyWithVoice(file, opts = {}) {
+    const peer = await this.peer();
+    return this.client.sendFile(peer, { file, voiceNote: true, ...opts });
   }
 
   /** Send any file as a generic document. */
-  replyWithDocument(file, opts = {}) {
-    return this.client.sendFile(this.chatId, {
+  async replyWithDocument(file, opts = {}) {
+    const peer = await this.peer();
+    return this.client.sendFile(peer, {
       file,
       forceDocument: true,
       ...opts,
@@ -111,13 +191,15 @@ class Context {
   }
 
   /** Send a sticker (.webp/.tgs file or existing file reference). */
-  replyWithSticker(file, opts = {}) {
-    return this.client.sendFile(this.chatId, { file, ...opts });
+  async replyWithSticker(file, opts = {}) {
+    const peer = await this.peer();
+    return this.client.sendFile(peer, { file, ...opts });
   }
 
   /** Send an animated GIF. */
-  replyWithAnimation(file, opts = {}) {
-    return this.client.sendFile(this.chatId, {
+  async replyWithAnimation(file, opts = {}) {
+    const peer = await this.peer();
+    return this.client.sendFile(peer, {
       file,
       attributes: [new Api.DocumentAttributeAnimated()],
       ...opts,
@@ -125,8 +207,9 @@ class Context {
   }
 
   /** Send multiple files as an album/media group. `files` is an array. */
-  replyWithMediaGroup(files, opts = {}) {
-    return this.client.sendFile(this.chatId, { file: files, ...opts });
+  async replyWithMediaGroup(files, opts = {}) {
+    const peer = await this.peer();
+    return this.client.sendFile(peer, { file: files, ...opts });
   }
 
   // ---------------------------------------------------------------------
@@ -139,8 +222,9 @@ class Context {
    * @param {Array<Array<{text: string, data?: string, url?: string}>>} rows
    * @param {object} [opts]
    */
-  replyWithButtons(text, rows, opts = {}) {
-    return this.client.sendMessage(this.chatId, {
+  async replyWithButtons(text, rows, opts = {}) {
+    const peer = await this.peer();
+    return this.client.sendMessage(peer, {
       message: text,
       buttons: buildButtons(rows, true),
       ...opts,
@@ -153,8 +237,9 @@ class Context {
    * @param {Array<Array<{text: string}>>} rows
    * @param {object} [opts]
    */
-  replyWithKeyboard(text, rows, opts = {}) {
-    return this.client.sendMessage(this.chatId, {
+  async replyWithKeyboard(text, rows, opts = {}) {
+    const peer = await this.peer();
+    return this.client.sendMessage(peer, {
       message: text,
       buttons: buildButtons(rows, false),
       ...opts,
@@ -167,19 +252,33 @@ class Context {
    * @param {string[]} answers
    * @param {object} [opts] e.g. { multipleChoice: true, quiz: false }
    */
-  replyWithPoll(question, answers, opts = {}) {
+  async replyWithPoll(question, answers, opts = {}) {
+    const {
+      publicVoters = true,
+      multipleChoice = true,
+      quiz = false
+    } = opts;
+    const peer = await this.peer();
     return this.client.invoke(
       new Api.messages.SendMedia({
-        peer: this.chatId,
+        peer,
         media: new Api.InputMediaPoll({
           poll: new Api.Poll({
             id: BigInt(Date.now()),
-            question,
+            question: new Api.TextWithEntities({
+              text: question,
+              entities: [],
+            }),
             answers: answers.map(
               (text, i) =>
-                new Api.PollAnswer({ text, option: Buffer.from([i]) })
+                new Api.PollAnswer({
+                  text: new Api.TextWithEntities({ text, entities: [] }),
+                  option: Buffer.from([i]),
+                })
             ),
-            multipleChoice: !!opts.multipleChoice,
+            multipleChoice: !!multipleChoice,
+            publicVoters,
+            ...opts
           }),
         }),
         message: "",
@@ -189,25 +288,27 @@ class Context {
   }
 
   /** Send a geographic location. */
-  replyWithLocation(latitude, longitude, opts = {}) {
+  async replyWithLocation(latitude, longitude, opts = {}) {
+    const peer = await this.peer();
     return this.client.invoke(
       new Api.messages.SendMedia({
-        peer: this.chatId,
+        peer,
         media: new Api.InputMediaGeoPoint({
           geoPoint: new Api.InputGeoPoint({ lat: latitude, long: longitude }),
         }),
         message: "",
-        randomId: BigInt(Date.now()),
+        randomId: BigInt(Math.floor(Math.random() * Number.MAX_SAFE_INTEGER)),
         ...opts,
       })
     );
   }
-
+  
   /** Send a contact card. */
-  replyWithContact(phoneNumber, firstName, lastName = "", opts = {}) {
+  async replyWithContact(phoneNumber, firstName, lastName = "", opts = {}) {
+    const peer = await this.peer();
     return this.client.invoke(
       new Api.messages.SendMedia({
-        peer: this.chatId,
+        peer,
         media: new Api.InputMediaContact({
           phoneNumber,
           firstName,
@@ -215,56 +316,58 @@ class Context {
           vcard: "",
         }),
         message: "",
-        randomId: BigInt(Date.now()),
+        randomId: BigInt(Math.floor(Math.random() * Number.MAX_SAFE_INTEGER)),
         ...opts,
       })
     );
   }
 
   /** Send an animated dice/emoji reaction (🎲 🎯 🏀 ⚽ 🎰 🎳). */
-  replyWithDice(emoji = "🎰", opts = {}) {
+  async replyWithDice(emoji = "🎰", opts = {}) {
+    const peer = await this.peer();
     return this.client.invoke(
       new Api.messages.SendMedia({
-        peer: this.chatId,
+        peer,
         media: new Api.InputMediaDice({ emoticon: emoji }),
         message: "",
-        randomId: BigInt(Date.now()),
+        randomId: BigInt(Math.floor(Math.random() * Number.MAX_SAFE_INTEGER)),
         ...opts,
       })
     );
   }
 
-  // ---------------------------------------------------------------------
-  // Chat / message management
-  // ---------------------------------------------------------------------
-
-  /** Delete the triggering message (revokes for everyone by default). */
-  deleteMessage() {
-    return this.client.deleteMessages(this.chatId, [this.message.id], {
+  /** Delete a message (defaults to the triggering message; revokes for everyone). */
+  async deleteMessage(id = this.message.id) {
+    const peer = await this.peer();
+    return this.client.deleteMessages(peer, [id], {
       revoke: true,
     });
   }
 
-  /** Forward the triggering message to another chat. */
-  forwardMessage(toChatId) {
+  /** Forward a message (defaults to the triggering message) to another chat. */
+  async forwardMessage(toChatId, id = this.message.id) {
+    const peer = await this.peer();
     return this.client.forwardMessages(toChatId, {
-      messages: [this.message.id],
-      fromPeer: this.chatId,
+      messages: [id],
+      fromPeer: peer,
     });
   }
 
-  /** Pin the triggering message in the current chat. */
-  pinMessage(opts = {}) {
-    return this.client.pinMessage(this.chatId, this.message.id, opts);
+  /** Pin a message (defaults to the triggering message) in the current chat. */
+  async pinMessage(id = this.message.id, opts = {}) {
+    const peer = await this.peer();
+    return this.client.pinMessage(peer, id, opts);
   }
 
-  /** Unpin the triggering message in the current chat. */
-  unpinMessage() {
-    return this.client.unpinMessage(this.chatId, this.message.id);
+  /** Unpin a message (defaults to the triggering message) in the current chat. */
+  async unpinMessage(id = this.message.id) {
+    const peer = await this.peer();
+    return this.client.unpinMessage(peer, id);
   }
 
   /** Show the "typing..." / "sending photo..." indicator. */
-  sendChatAction(action = "typing") {
+  async sendChatAction(action = "typing") {
+    const peer = await this.peer();
     const actions = {
       typing: new Api.SendMessageTypingAction(),
       photo: new Api.SendMessageUploadPhotoAction({ progress: 0 }),
@@ -275,7 +378,7 @@ class Context {
     };
     return this.client.invoke(
       new Api.messages.SetTyping({
-        peer: this.chatId,
+        peer,
         action: actions[action] || actions.typing,
       })
     );
@@ -290,6 +393,663 @@ class Context {
   getChat() {
     return this.message.getChat();
   }
+
+  /**
+   * Send a message "via @bot" — i.e. runs an inline query against a bot
+   * that supports inline mode, then sends one of its results. This is
+   * the only way to get the "via @bot" label on a message; you can't set
+   * `viaBotId` manually on a normal sendMessage/sendFile call.
+   *
+   * @param {string} bot - the bot's @username (with or without the @)
+   * @param {string} [query=""] - the inline query text to send to the bot
+   * @param {object} [opts]
+   * @param {number} [opts.resultIndex=0] - which result to pick from the list
+   * @param {boolean} [opts.hideVia=false] - hide the "via @bot" label
+   * @param {number} [opts.retries=2] - retry count if the bot times out
+   *   (BOT_RESPONSE_TIMEOUT) or is briefly unreachable — this is a
+   *   bot-side issue, not something the query itself can prevent
+   *
+   * @example
+   * // equivalent of typing "@pic cats" and sending the first result
+   * await ctx.replyViaBot("pic", "cats");
+   */
+  async replyViaBot(bot, query = "", opts = {}) {
+    const peer = await this.peer();
+    const retries = opts.retries ?? 2;
+
+    let results;
+    let lastErr;
+    for (let attempt = 0; attempt <= retries; attempt++) {
+      try {
+        results = await this.client.inlineQuery(bot, query, peer);
+        lastErr = null;
+        break;
+      } catch (err) {
+        lastErr = err;
+        const retriable =
+          err?.errorMessage === "BOT_RESPONSE_TIMEOUT" ||
+          err?.message?.includes("BOT_RESPONSE_TIMEOUT");
+        if (!retriable || attempt === retries) break;
+        // Small backoff before asking the bot again.
+        await new Promise((r) => setTimeout(r, 500 * (attempt + 1)));
+      }
+    }
+
+    if (lastErr) {
+      throw new Error(
+        `replyViaBot: @${bot} didn't respond in time after ${retries + 1} ` +
+          `attempt(s) (${lastErr.errorMessage || lastErr.message}). ` +
+          `This means the bot itself is slow/offline, not a bug in the query.`
+      );
+    }
+
+    if (!results || results.length === 0) {
+      throw new Error(
+        `replyViaBot: @${bot} returned no inline results for "${query}"`
+      );
+    }
+
+    const index = opts.resultIndex || 0;
+    const chosen = results[index];
+    if (!chosen) {
+      throw new Error(
+        `replyViaBot: no result at index ${index} (got ${results.length} results)`
+      );
+    }
+
+    return chosen.click({
+      entity: peer,
+      hideVia: !!opts.hideVia,
+    });
+  }
+
+  // ---------------------------------------------------------------------
+  // More media / interaction helpers
+  // ---------------------------------------------------------------------
+
+  /**
+   * Send a venue — a location pinned with a name and address (e.g. a
+   * restaurant or landmark), like the "Location > Venue" picker in-app.
+   */
+  async replyWithVenue(latitude, longitude, title, address, opts = {}) {
+    const peer = await this.peer();
+    return this.client.invoke(
+      new Api.messages.SendMedia({
+        peer,
+        media: new Api.InputMediaVenue({
+          geoPoint: new Api.InputGeoPoint({ lat: latitude, long: longitude }),
+          title,
+          address,
+          provider: opts.provider || "",
+          venueId: opts.venueId || "",
+          venueType: opts.venueType || "",
+        }),
+        message: "",
+        randomId: BigInt(Math.floor(Math.random() * Number.MAX_SAFE_INTEGER)),
+      })
+    );
+  }
+
+  /**
+   * Send a live location that updates in real time for `period` seconds
+   * (Telegram allows 60–86400). Use client.editMessage(...) with a new
+   * InputMediaGeoLive afterwards to push position updates.
+   */
+  async replyWithLiveLocation(latitude, longitude, period = 900, opts = {}) {
+    const peer = await this.peer();
+    return this.client.invoke(
+      new Api.messages.SendMedia({
+        peer,
+        media: new Api.InputMediaGeoLive({
+          geoPoint: new Api.InputGeoPoint({ lat: latitude, long: longitude }),
+          period,
+          heading: opts.heading,
+          proximityNotificationRadius: opts.proximityNotificationRadius,
+        }),
+        message: "",
+        randomId: BigInt(Math.floor(Math.random() * Number.MAX_SAFE_INTEGER)),
+      })
+    );
+  }
+
+  /**
+   * React to the triggering message with an emoji (❤️ 👍 🔥 🎉 etc).
+   * Pass an empty string or `null` to remove your reaction instead.
+   */
+  async react(id = this.message.id, emoji = "👍", opts = {}) {
+    const peer = await this.peer();
+    return this.client.invoke(
+      new Api.messages.SendReaction({
+        peer,
+        msgId: id,
+        reaction: emoji ? [new Api.ReactionEmoji({ emoticon: emoji })] : [],
+        big: !!opts.big,
+        addToRecent: opts.addToRecent !== false,
+      })
+    );
+  }
+
+  /**
+   * Re-send the triggering message's content (text or media) to another
+   * chat, WITHOUT the "Forwarded from" header — unlike forwardMessage().
+   * Closest equivalent to Bot API's "copy message".
+   */
+  async copyMessage(toChatId, opts = {}) {
+    if (this.message.media) {
+      return this.client.sendFile(toChatId, {
+        file: this.message.media,
+        caption: this.text,
+        ...opts,
+      });
+    }
+    return this.client.sendMessage(toChatId, { message: this.text, ...opts });
+  }
+
+  /** Mark the current chat as read, up to (and including) this message. */
+  async markAsRead(userId) {
+    const peer = userId || await this.peer();
+    return this.client.markAsRead(peer, this.message);
+  }
+
+  /**
+   * Download the media attached to the triggering message (photo, video,
+   * document, voice note, etc). Resolves to a Buffer by default, or writes
+   * straight to disk if you pass `opts.outputFile: "path/to/save"`.
+   */
+  async downloadMedia(opts = {}) {
+    if (!this.message.media) {
+      throw new Error("downloadMedia: the triggering message has no media");
+    }
+    return this.client.downloadMedia(this.message, opts);
+  }
+
+  /** Edit the media of a message you previously sent (e.g. swap out a photo). */
+  async editMessageMedia(messageId, file, opts = {}) {
+    const peer = await this.peer();
+    return this.client.editMessage(peer, {
+      message: messageId,
+      file,
+      ...opts,
+    });
+  }
+
+  // ---------------------------------------------------------------------
+  // Voice / text / poll utilities
+  // ---------------------------------------------------------------------
+
+  /**
+   * Transcribe the voice note attached to the triggering message using
+   * Telegram's built-in transcription. Resolves to
+   * `{ text, transcriptionId, pending, trialRemainsNum, trialRemainsUntilDate }`.
+   * If `pending` is true, the final text arrives later via an
+   * `UpdateTranscribedAudio` update rather than this call.
+   */
+  async transcribeVoice(id = this.message.id) {
+    const peer = await this.peer();
+    return this.client.invoke(
+      new Api.messages.TranscribeAudio({ peer, msgId: id })
+    );
+  }
+
+  /** Translate the triggering message's text into another language (e.g. "en", "id"). */
+  async translateText(text, toLang) {
+    return this.client.invoke(
+      new Api.messages.TranslateText({
+        text: [new Api.TextWithEntities({ text, entities: [] })],
+        toLang,
+      })
+    );
+  }
+
+  /**
+   * Vote on the poll attached to the triggering message.
+   * @param {number|number[]} options - option index (or indexes, for
+   *   multiple-choice polls), 0-based in the order the poll was created.
+   */
+  async votePoll(id = this.message.id, options) {
+    const peer = await this.peer();
+    const optionBytes = (Array.isArray(options) ? options : [options]).map(
+      (i) => Buffer.from([i])
+    );
+    return this.client.invoke(
+      new Api.messages.SendVote({
+        peer,
+        msgId: id,
+        options: optionBytes,
+      })
+    );
+  }
+
+  /** Retract your vote on the triggering message's poll. */
+  async retractVote(id = this.message.id) {
+    const peer = await this.peer();
+    return this.client.invoke(
+      new Api.messages.SendVote({ peer, msgId: id, options: [] })
+    );
+  }
+
+  // ---------------------------------------------------------------------
+  // Contacts / history
+  // ---------------------------------------------------------------------
+
+  /** Block the sender of the triggering message. */
+  async blockUser(userId) {
+    const senderPeer = userId || await this.message.getInputSender();
+    return this.client.invoke(new Api.contacts.Block({ id: senderPeer }));
+  }
+
+  /** Unblock the sender of the triggering message. */
+  async unblockUser(userId) {
+    const senderPeer = userId || await this.message.getInputSender();
+    return this.client.invoke(new Api.contacts.Unblock({ id: senderPeer }));
+  }
+
+  /** Fetch the most recent messages in the current chat. */
+  async getHistory(userId, limit = 20, opts = {}) {
+    const peer = userId || await this.peer();
+    return this.client.getMessages(peer, { limit, ...opts });
+  }
+
+  /** Search for messages containing `query` in the current chat. */
+  async searchMessages(query, opts = {}) {
+    const peer = await this.peer();
+    return this.client.getMessages(peer, { search: query, ...opts });
+  }
+
+  /** Unpin every pinned message in the current chat. */
+  async unpinAllMessages(userId) {
+    const peer = userId || await this.peer();
+    return this.client.unpinMessage(peer);
+  }
+
+  /** List participants/members of the current chat (groups/channels only). */
+  async getParticipants(opts = {}) {
+    const peer = await this.peer();
+    return this.client.getParticipants(peer, opts);
+  }
+
+  /**
+   * Get metadata for a user/chat/channel by @username.
+   * Resolves both the basic entity (id, name, username, etc.) and the
+   * "full" info (bio for users; description/member count for chats/channels).
+   *
+   * @param {string} username - with or without the leading @
+   * @returns {Promise<{ entity: object, full: object|null }>}
+   *
+   * @example
+   * const { entity, full } = await ctx.getEntityByUsername("durov");
+   * console.log(entity.firstName, full.fullUser.about);
+   */
+  async getEntityByUsername(username) {
+    const clean = username.replace(/^@/, "");
+    const entity = await this.client.getEntity(clean);
+
+    let full = null;
+    try {
+      if (entity.className === "User") {
+        full = await this.client.invoke(new Api.users.GetFullUser({ id: entity }));
+      } else if (entity.className === "Channel") {
+        full = await this.client.invoke(
+          new Api.channels.GetFullChannel({ channel: entity })
+        );
+      } else if (entity.className === "Chat") {
+        full = await this.client.invoke(
+          new Api.messages.GetFullChat({ chatId: entity.id })
+        );
+      }
+    } catch (err) {
+      // full info isn't always available (e.g. restricted/deleted accounts);
+      // the basic `entity` above is still returned either way
+    }
+
+    return { entity, full };
+  }
+
+  // ---------------------------------------------------------------------
+  // Channel / group management (supergroups & channels — see notes below)
+  // ---------------------------------------------------------------------
+
+  /**
+   * Ban a user from the current supergroup/channel (they can't rejoin
+   * unless unbanned). For basic (non-super) groups, Telegram doesn't
+   * support per-user restrictions — use kickUser() instead.
+   * @param {string|number} userId
+   * @param {object} [opts] e.g. { untilDate: unixTimestamp } for a timed ban
+   */
+  async banUser(userId, opts = {}) {
+    const peer = await this.peer();
+    const participant = await this.client.getInputEntity(userId);
+    return this.client.invoke(
+      new Api.channels.EditBanned({
+        channel: peer,
+        participant,
+        bannedRights: new Api.ChatBannedRights({
+          untilDate: opts.untilDate || 0,
+          viewMessages: true,
+          sendMessages: true,
+          sendMedia: true,
+          sendStickers: true,
+          sendGifs: true,
+          sendGames: true,
+          sendInline: true,
+          embedLinks: true,
+          sendPolls: true,
+          changeInfo: true,
+          inviteUsers: true,
+          pinMessages: true,
+        }),
+      })
+    );
+  }
+
+  /** Clear all restrictions on a user in the current supergroup/channel. */
+  async unbanUser(userId) {
+    const peer = await this.peer();
+    const participant = await this.client.getInputEntity(userId);
+    return this.client.invoke(
+      new Api.channels.EditBanned({
+        channel: peer,
+        participant,
+        bannedRights: new Api.ChatBannedRights({ untilDate: 0 }),
+      })
+    );
+  }
+
+  /**
+   * Kick a user (remove them, but they CAN rejoin) from a supergroup/channel.
+   * For basic groups, this uses messages.DeleteChatUser instead.
+   */
+  async kickUser(userId) {
+    if (this.isChannel) {
+      await this.banUser(userId);
+      return this.unbanUser(userId);
+    }
+    const participant = await this.client.getInputEntity(userId);
+    return this.client.invoke(
+      new Api.messages.DeleteChatUser({ chatId: this.chatId, userId: participant })
+    );
+  }
+
+  /**
+   * Promote a user to admin in the current supergroup/channel.
+   * `rights` overrides the (fairly permissive) defaults below.
+   */
+  async promoteUser(userId, rights = {}, rank = "") {
+    const peer = await this.peer();
+    const participant = await this.client.getInputEntity(userId);
+    return this.client.invoke(
+      new Api.channels.EditAdmin({
+        channel: peer,
+        userId: participant,
+        adminRights: new Api.ChatAdminRights({
+          changeInfo: true,
+          postMessages: true,
+          editMessages: true,
+          deleteMessages: true,
+          banUsers: true,
+          inviteUsers: true,
+          pinMessages: true,
+          addAdmins: false,
+          anonymous: false,
+          manageCall: true,
+          other: true,
+          ...rights,
+        }),
+        rank,
+      })
+    );
+  }
+
+  /** Strip a user of all admin rights in the current supergroup/channel. */
+  async demoteUser(userId) {
+    return this.promoteUser(
+      userId,
+      {
+        changeInfo: false,
+        postMessages: false,
+        editMessages: false,
+        deleteMessages: false,
+        banUsers: false,
+        inviteUsers: false,
+        pinMessages: false,
+        addAdmins: false,
+        anonymous: false,
+        manageCall: false,
+        other: false,
+      },
+      ""
+    );
+  }
+
+  /** Invite one or more users to the current supergroup/channel. */
+  async inviteToChannel(channelId, userIds) {
+    const peer = channelId || await this.peer();
+    const users = await Promise.all(
+      (Array.isArray(userIds) ? userIds : [userIds]).map((u) =>
+        this.client.getInputEntity(u)
+      )
+    );
+    return this.client.invoke(
+      new Api.channels.InviteToChannel({ channel: peer, users })
+    );
+  }
+
+  /** Rename the current chat/supergroup/channel. */
+  async setChatTitle(id, title) {
+    const peer = id || await this.peer();
+    if (this.isChannel) {
+      return this.client.invoke(new Api.channels.EditTitle({ channel: peer, title }));
+    }
+    return this.client.invoke(
+      new Api.messages.EditChatTitle({ chatId: this.chatId, title })
+    );
+  }
+
+  /** Change the current chat/supergroup/channel's profile photo. */
+  async setChatPhoto(id, file) {
+    const peer = id || await this.peer();
+    const uploaded = await this.client.uploadFile({ file, workers: 1 });
+    const photo = new Api.InputChatUploadedPhoto({ file: uploaded });
+    if (this.isChannel) {
+      return this.client.invoke(new Api.channels.EditPhoto({ channel: peer, photo }));
+    }
+    return this.client.invoke(
+      new Api.messages.EditChatPhoto({ chatId: this.chatId, photo })
+    );
+  }
+
+  // ---------------------------------------------------------------------
+  // Stickers & GIFs
+  // ---------------------------------------------------------------------
+
+  /** Look up stickers matching an emoji (e.g. "😂"). */
+  async searchStickers(emoji) {
+    return this.client.invoke(
+      new Api.messages.GetStickers({ emoticon: emoji, hash: BigInt(0) })
+    );
+  }
+
+  /** Get full info + document list for a sticker set by its short name. */
+  async getStickerSet(shortName) {
+    return this.client.invoke(
+      new Api.messages.GetStickerSet({
+        stickerset: new Api.InputStickerSetShortName({ shortName }),
+        hash: 0,
+      })
+    );
+  }
+
+  /** Search Telegram's global GIF results for a query. */
+  async searchGifs(query, offset = "") {
+    return this.client.invoke(new Api.messages.SearchGifs({ q: query, offset }));
+  }
+
+  /**
+   * Save (or unsave) a GIF document to the user's "Saved GIFs".
+   * @param {object} document - an Api.Document, e.g. from searchGifs() results
+   * @param {boolean} [unsave=false]
+   */
+  async saveGif(document, unsave = false) {
+    return this.client.invoke(new Api.messages.SaveGif({ id: document, unsave }));
+  }
+
+  // ---------------------------------------------------------------------
+  // Privacy & account settings
+  // ---------------------------------------------------------------------
+
+  /**
+   * Get your current privacy rules for a given key.
+   * @param {"phoneNumber"|"lastSeen"|"chatInvite"|"phoneCall"|"profilePhoto"|"forwards"} [key]
+   */
+  async getPrivacySettings(key = "phoneNumber") {
+    const keyMap = {
+      phoneNumber: () => new Api.InputPrivacyKeyPhoneNumber(),
+      lastSeen: () => new Api.InputPrivacyKeyStatusTimestamp(),
+      chatInvite: () => new Api.InputPrivacyKeyChatInvite(),
+      phoneCall: () => new Api.InputPrivacyKeyPhoneCall(),
+      profilePhoto: () => new Api.InputPrivacyKeyProfilePhoto(),
+      forwards: () => new Api.InputPrivacyKeyForwards(),
+    };
+    const build = keyMap[key] || keyMap.phoneNumber;
+    return this.client.invoke(new Api.account.GetPrivacy({ key: build() }));
+  }
+
+  /** Update your account's first/last name and bio ("about"). */
+  async updateProfile(opts = {}) {
+    return this.client.invoke(
+      new Api.account.UpdateProfile({
+        firstName: opts.firstName,
+        lastName: opts.lastName,
+        about: opts.about,
+      })
+    );
+  }
+
+  /** Change your account's @username. */
+  async updateUsername(username) {
+    return this.client.invoke(new Api.account.UpdateUsername({ username }));
+  }
+
+  /** Manually set your account's online/offline status. */
+  async setOnlineStatus(online = true) {
+    return this.client.invoke(new Api.account.UpdateStatus({ offline: !online }));
+  }
+
+  // ---------------------------------------------------------------------
+  // Advanced file uploads
+  // ---------------------------------------------------------------------
+
+  /** Send a photo/video with the "spoiler" blur overlay. */
+  async replyWithSpoiler(file, opts = {}) {
+    const peer = await this.peer();
+    return this.client.sendFile(peer, { file, spoiler: true, ...opts });
+  }
+
+  /** Send a file with a custom thumbnail image. */
+  async replyWithThumb(file, thumb, opts = {}) {
+    const peer = await this.peer();
+    return this.client.sendFile(peer, { file, thumb, ...opts });
+  }
+
+  /**
+   * Upload a file with progress tracking, without sending it yet. Returns
+   * an uploaded-file handle you can pass as `file` to any replyWith*
+   * method — useful for showing upload progress on large files.
+   * @param {*} file
+   * @param {(uploaded: number, total: number) => void} onProgress
+   */
+  async uploadWithProgress(file, onProgress) {
+    return this.client.uploadFile({
+      file,
+      workers: 1,
+      progressCallback: onProgress,
+    });
+  }
+  // ---------------------------------------------------------------------
+// Channel / Group Actions
+// ---------------------------------------------------------------------
+
+  /**
+   * Join channel/group by username, id, or invite link
+   * @param {string | number} channel - "@username", id, or entity
+   * @example ctx.joinChannel("XazepysK")
+   */
+  async joinChannel(id) {
+    const entity = await this.client.getInputEntity(id);
+    return this.client.invoke(new Api.channels.JoinChannel({ channel: entity }));
+  }
+
+  /**
+   * Join private group/channel via invite hash
+   * @param {string} hash - hash from t.me/+HASH
+   * @example ctx.joinByInvite("AAAAAE2x...")
+   */
+  async joinByInvite(hash) {
+    return this.client.invoke(new Api.messages.ImportChatInvite({ hash }));
+  }
+
+  /**
+   * Leave channel/group
+   * @param {string | number} channel - "@username", id, or entity. Default: chatId
+   */
+  async leaveChannel(id = null) {
+    const peer = id? await this.client.getInputEntity(id) : await this.peer();
+    return this.client.invoke(new Api.channels.LeaveChannel({ channel: peer }));
+  }
+  
+    /**
+   * Get buffer + metadata from media with messageId
+   * @param {number} [messageId] - messageId
+   * @param {object} [opts={}] - opts downloadMedia
+   * @returns {Promise<{buffer: Buffer, metadata: object, filename: string}>}
+   */
+  async saveMediaMessage(messageId = null, opts = {}) {
+    const peer = await this.peer();
+    const targetMsg = messageId ? (await this.client.getMessages(peer, { ids: [messageId] }))[0] : this.message;
+
+    if (!targetMsg) throw new Error(`${messageId} not found`);
+    if (!targetMsg.media) throw new Error("message doesnt have media");
+    const buffer = await this.client.downloadMedia(targetMsg, opts);
+    const media = targetMsg.media;
+    let metadata = {
+      type: targetMsg.media.className,
+      size: null,
+      mimeType: null,
+      fileName: null,
+      width: null,
+      height: null,
+      duration: null,
+      date: targetMsg.date,
+      chatId: targetMsg.chatId,
+      messageId: targetMsg.id,
+      senderId: targetMsg.senderId,
+    };
+    if (media.className === "MessageMediaPhoto") {
+      const biggest = media.photo.sizes[media.photo.sizes.length - 1];
+      metadata.size = biggest?.size || null;
+      metadata.width = biggest?.w || null;
+      metadata.height = biggest?.h || null;
+      metadata.fileName = `photo_${targetMsg.id}.jpg`;
+    }
+
+    if (media.className === "MessageMediaDocument") {
+      const doc = media.document;
+      metadata.size = doc.size;
+      metadata.mimeType = doc.mimeType;
+      metadata.date = doc.date;
+      const attr = doc.attributes.find(a => a.className === "DocumentAttributeFilename");
+      metadata.fileName = attr?.fileName || `file_${targetMsg.id}`;
+      const videoAttr = doc.attributes.find(a => a.className === "DocumentAttributeVideo");
+      if (videoAttr) {
+        metadata.width = videoAttr.w;
+        metadata.height = videoAttr.h;
+        metadata.duration = videoAttr.duration;
+      }
+      const audioAttr = doc.attributes.find(a => a.className === "DocumentAttributeAudio");
+      if (audioAttr) metadata.duration = audioAttr.duration;
+    }
+    return { buffer, metadata, filename: metadata.fileName };
+  }
 }
 
 module.exports = { Context, buildButtons };