@overpod/mcp-telegram 1.39.1 → 1.40.0

package/CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.40.0](https://github.com/mcp-telegram/mcp-telegram/compare/v1.39.1...v1.40.0) (2026-06-23)
+
+
+### Added
+
+* **media:** add thumbnail option to downloadMediaAsBuffer ([#64](https://github.com/mcp-telegram/mcp-telegram/issues/64)) ([d9f302c](https://github.com/mcp-telegram/mcp-telegram/commit/d9f302c8efde73a8d86467b23d05b8a12650662f))
+
 ## [1.39.1](https://github.com/mcp-telegram/mcp-telegram/compare/v1.39.0...v1.39.1) (2026-06-21)
 
 

package/dist/telegram-client.d.ts

@@ -142,9 +142,30 @@ export declare class TelegramService {
         ids: number[];
     }>;
     downloadMedia(chatId: string, messageId: number, downloadPath: string): Promise<string>;
-    downloadMediaAsBuffer(chatId: string, messageId: number): Promise<{
+    /**
+     * Download a message's media into memory.
+     *
+     * When `options.thumb` is given, GramJS fetches that thumbnail size instead of
+     * the full file (`0` = smallest, larger indexes = bigger previews). This keeps
+     * payloads tiny — useful for callers that inline the bytes and pay per byte
+     * (e.g. base64 in an LLM context). If the message has no thumbnail at that
+     * index, GramJS returns an empty/`undefined` buffer; we transparently fall
+     * back to the full file so the caller always gets bytes. `isThumb` reports
+     * which one was served.
+     *
+     * Note: GramJS signals "no bytes" inconsistently — `undefined` for a missing
+     * thumbnail, but `Buffer.alloc(0)` for undownloadable media (geo/poll/dice,
+     * documents without a file, and several failure paths). An empty Buffer is
+     * truthy, so we guard on `.length`, not truthiness, in both the fallback and
+     * the final failure check — otherwise a 0-byte buffer would be returned as a
+     * "successful" (but garbage) download.
+     */
+    downloadMediaAsBuffer(chatId: string, messageId: number, options?: {
+        thumb?: number;
+    }): Promise<{
         buffer: Buffer;
         mimeType: string;
+        isThumb: boolean;
     }>;
     /** Detect MIME type from buffer magic bytes, falling back to media metadata */
     private detectMimeType;

package/dist/telegram-client.js

@@ -708,7 +708,25 @@ export class TelegramService {
         await writeFile(downloadPath, buffer);
         return downloadPath;
     }
-    async downloadMediaAsBuffer(chatId, messageId) {
+    /**
+     * Download a message's media into memory.
+     *
+     * When `options.thumb` is given, GramJS fetches that thumbnail size instead of
+     * the full file (`0` = smallest, larger indexes = bigger previews). This keeps
+     * payloads tiny — useful for callers that inline the bytes and pay per byte
+     * (e.g. base64 in an LLM context). If the message has no thumbnail at that
+     * index, GramJS returns an empty/`undefined` buffer; we transparently fall
+     * back to the full file so the caller always gets bytes. `isThumb` reports
+     * which one was served.
+     *
+     * Note: GramJS signals "no bytes" inconsistently — `undefined` for a missing
+     * thumbnail, but `Buffer.alloc(0)` for undownloadable media (geo/poll/dice,
+     * documents without a file, and several failure paths). An empty Buffer is
+     * truthy, so we guard on `.length`, not truthiness, in both the fallback and
+     * the final failure check — otherwise a 0-byte buffer would be returned as a
+     * "successful" (but garbage) download.
+     */
+    async downloadMediaAsBuffer(chatId, messageId, options) {
         if (!this.client || !this.connected)
             throw new Error(NOT_CONNECTED_ERROR);
         const resolved = await this.resolvePeer(chatId);
@@ -718,11 +736,19 @@ export class TelegramService {
             throw new Error(`Message ${messageId} not found`);
         if (!message.media)
             throw new Error(`Message ${messageId} has no media`);
-        const buffer = (await this.client.downloadMedia(message));
-        if (!buffer)
+        let isThumb = false;
+        let buffer;
+        if (options?.thumb !== undefined) {
+            buffer = (await this.client.downloadMedia(message, { thumb: options.thumb }));
+            isThumb = !!buffer?.length;
+        }
+        // No thumb requested, or this media has no thumbnail at that size → full file.
+        if (!buffer?.length)
+            buffer = (await this.client.downloadMedia(message));
+        if (!buffer?.length)
             throw new Error("Failed to download media");
         const mimeType = this.detectMimeType(buffer, message.media);
-        return { buffer, mimeType };
+        return { buffer, mimeType, isThumb };
     }
     /** Detect MIME type from buffer magic bytes, falling back to media metadata */
     detectMimeType(buffer, media) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@overpod/mcp-telegram",
-  "version": "1.39.1",
+  "version": "1.40.0",
   "description": "MCP server for Telegram userbot — messages, media, reactions, polls & more. Built on GramJS/MTProto.",
   "type": "module",
   "main": "dist/index.js",