@overpod/mcp-telegram 1.26.0 → 1.26.1

package/dist/index.js

@@ -6,10 +6,13 @@ console.log = (...args) => {
     console.error(...args);
 };
 import "dotenv/config";
+import { createRequire } from "node:module";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { TelegramService } from "./telegram-client.js";
 import { registerTools } from "./tools/index.js";
+const require = createRequire(import.meta.url);
+const { version } = require("../package.json");
 // Telegram API credentials from env
 const API_ID = Number(process.env.TELEGRAM_API_ID);
 const API_HASH = process.env.TELEGRAM_API_HASH;
@@ -22,7 +25,7 @@ if (!API_ID || !API_HASH) {
 const telegram = new TelegramService(API_ID, API_HASH);
 const server = new McpServer({
     name: "mcp-telegram",
-    version: "1.0.0",
+    version,
 });
 registerTools(server, telegram);
 async function main() {

package/dist/rate-limiter.d.ts

@@ -13,11 +13,11 @@ export interface RateLimiterOptions {
     maxRetryDelay?: number;
 }
 export declare class RateLimiter {
-    private lastRequestTime;
     private minInterval;
     private maxRetries;
     private initialRetryDelay;
     private maxRetryDelay;
+    private slotQueue;
     constructor(options?: RateLimiterOptions);
     /**
      * Execute a function with rate limiting and automatic retry.

package/dist/rate-limiter.js

@@ -3,11 +3,12 @@
  * Handles FLOOD_WAIT errors and implements exponential backoff.
  */
 export class RateLimiter {
-    lastRequestTime = 0;
     minInterval;
     maxRetries;
     initialRetryDelay;
     maxRetryDelay;
+    // Serializes concurrent calls so each waits for the previous slot to clear
+    slotQueue = Promise.resolve();
     constructor(options = {}) {
         const maxRequestsPerSecond = options.maxRequestsPerSecond ?? 20;
         this.minInterval = 1000 / maxRequestsPerSecond;
@@ -67,13 +68,12 @@ export class RateLimiter {
             throw error;
         }
     }
-    async waitForSlot() {
-        const now = Date.now();
-        const elapsed = now - this.lastRequestTime;
-        if (elapsed < this.minInterval) {
-            await sleep(this.minInterval - elapsed);
-        }
-        this.lastRequestTime = Date.now();
+    waitForSlot() {
+        // Chain onto the previous slot so concurrent callers queue up sequentially.
+        // Each turn: wait minInterval from when the previous turn started, then resolve.
+        const nextSlot = this.slotQueue.then(() => sleep(this.minInterval));
+        this.slotQueue = nextSlot;
+        return nextSlot;
     }
 }
 function isNetworkError(msg) {

package/dist/telegram-client.d.ts

@@ -1,474 +1,9 @@
-import bigInt from "big-integer";
 import { TelegramClient } from "telegram";
 import { Api } from "telegram/tl/index.js";
-export declare function describeAdminLogAction(action: Api.TypeChannelAdminLogEventAction): string;
-export declare function describeAdminLogDetails(action: Api.TypeChannelAdminLogEventAction, describeUser: (userId: bigInt.BigInteger) => string): string;
-export declare function reactionToEmoji(reaction: Api.TypeReaction): string | null;
-export type CompactStatsGraph = {
-    type: "async";
-    token: string;
-} | {
-    type: "error";
-    error: string;
-} | {
-    type: "data";
-    data: unknown;
-    zoomToken?: string;
-};
-export type StatsValue = {
-    current: number;
-    previous: number;
-};
-export type BroadcastStatsSummary = {
-    period: {
-        minDate: number;
-        maxDate: number;
-    };
-    followers: StatsValue;
-    viewsPerPost: StatsValue;
-    sharesPerPost: StatsValue;
-    reactionsPerPost: StatsValue;
-    viewsPerStory: StatsValue;
-    sharesPerStory: StatsValue;
-    reactionsPerStory: StatsValue;
-    enabledNotifications: {
-        part: number;
-        total: number;
-        percent: number;
-    };
-    recentPostsInteractions: Array<{
-        kind: "message";
-        msgId: number;
-        views: number;
-        forwards: number;
-        reactions: number;
-    } | {
-        kind: "story";
-        storyId: number;
-        views: number;
-        forwards: number;
-        reactions: number;
-    }>;
-    graphs?: Record<string, CompactStatsGraph>;
-};
-export type MegagroupStatsSummary = {
-    period: {
-        minDate: number;
-        maxDate: number;
-    };
-    members: StatsValue;
-    messages: StatsValue;
-    viewers: StatsValue;
-    posters: StatsValue;
-    topPosters: Array<{
-        userId: string;
-        messages: number;
-        avgChars: number;
-    }>;
-    topAdmins: Array<{
-        userId: string;
-        deleted: number;
-        kicked: number;
-        banned: number;
-    }>;
-    topInviters: Array<{
-        userId: string;
-        invitations: number;
-    }>;
-    graphs?: Record<string, CompactStatsGraph>;
-};
-export declare function summarizeMegagroupStats(stats: Api.stats.MegagroupStats, includeGraphs: boolean): MegagroupStatsSummary;
-export declare function summarizeBroadcastStats(stats: Api.stats.BroadcastStats, includeGraphs: boolean): BroadcastStatsSummary;
-export type ChatPermissions = {
-    sendMessages?: boolean;
-    sendMedia?: boolean;
-    sendStickers?: boolean;
-    sendGifs?: boolean;
-    sendPolls?: boolean;
-    sendInline?: boolean;
-    embedLinks?: boolean;
-    changeInfo?: boolean;
-    inviteUsers?: boolean;
-    pinMessages?: boolean;
-};
-export declare function mergeBannedRights(current: Record<string, unknown> | undefined | null, permissions: ChatPermissions): Record<string, boolean>;
-export type MessageButtonDescriptor = {
-    row: number;
-    col: number;
-    type: string;
-    label: string;
-    data?: string;
-    url?: string;
-    switchQuery?: string;
-    samePeer?: boolean;
-    userId?: string;
-    buttonId?: number;
-    copyText?: string;
-    requiresPassword?: boolean;
-    quiz?: boolean;
-};
-export declare function describeKeyboardButton(button: Api.TypeKeyboardButton, row: number, col: number): MessageButtonDescriptor;
-export type CompactPeer = {
-    kind: "user";
-    id: string;
-} | {
-    kind: "chat";
-    id: string;
-} | {
-    kind: "channel";
-    id: string;
-};
-export type UpdatesMessageSummary = {
-    id: number;
-    peer: CompactPeer;
-    fromId?: CompactPeer;
-    date: number;
-    text: string;
-    isService: boolean;
-};
-export type UpdatesDifferenceSummary = {
-    state: {
-        pts: number;
-        qts: number;
-        date: number;
-        seq: number;
-        unreadCount?: number;
-    };
-    isFinal: boolean;
-    newMessages: UpdatesMessageSummary[];
-    deletedMessageIds: Array<{
-        peer?: CompactPeer;
-        messageIds: number[];
-    }>;
-    otherUpdates: Array<{
-        type: string;
-    }>;
-    fallback?: {
-        kind: "tooLong";
-        suggestedAction: string;
-    };
-};
-export type ChannelDifferenceSummary = {
-    channelId: string;
-    pts: number;
-    isFinal: boolean;
-    timeout?: number;
-    newMessages: UpdatesMessageSummary[];
-    otherUpdates: Array<{
-        type: string;
-    }>;
-    fallback?: {
-        kind: "tooLong";
-        suggestedAction: string;
-    };
-};
-export declare function peerToCompact(peer: Api.TypePeer | undefined): CompactPeer | undefined;
-export declare function summarizeUpdatesDifference(diff: Api.updates.TypeDifference, cursor: {
-    pts: number;
-    qts: number;
-    date: number;
-}): UpdatesDifferenceSummary;
-export declare function summarizeChannelDifference(diff: Api.updates.TypeChannelDifference, channelId: string, fallbackPts: number): ChannelDifferenceSummary;
-export type StoryItemSummary = {
-    id: number;
-    kind: "active" | "deleted" | "skipped";
-    date?: number;
-    expireDate?: number;
-    caption?: string;
-    mediaType?: string;
-    pinned?: boolean;
-    public?: boolean;
-    closeFriends?: boolean;
-    edited?: boolean;
-    noforwards?: boolean;
-    fromId?: CompactPeer;
-    viewsCount?: number;
-    reactionsCount?: number;
-};
-export type PeerStoriesSummary = {
-    peer: CompactPeer;
-    maxReadId?: number;
-    stories: StoryItemSummary[];
-};
-export type AllStoriesSummary = {
-    modified: boolean;
-    state: string;
-    hasMore?: boolean;
-    count?: number;
-    peerStories: PeerStoriesSummary[];
-    stealthMode?: {
-        activeUntilDate?: number;
-        cooldownUntilDate?: number;
-    };
-};
-export type StoriesByIdSummary = {
-    count: number;
-    stories: StoryItemSummary[];
-    pinnedToTop?: number[];
-};
-export type StoryViewSummary = {
-    kind: "user";
-    userId: string;
-    date: number;
-    reaction?: string | null;
-    blocked?: boolean;
-    blockedMyStoriesFrom?: boolean;
-} | {
-    kind: "publicForward";
-    messageId?: number;
-    peer?: CompactPeer;
-    blocked?: boolean;
-    blockedMyStoriesFrom?: boolean;
-} | {
-    kind: "publicRepost";
-    peer?: CompactPeer;
-    storyId?: number;
-    blocked?: boolean;
-    blockedMyStoriesFrom?: boolean;
-};
-export type StoryViewsListSummary = {
-    count: number;
-    viewsCount: number;
-    forwardsCount: number;
-    reactionsCount: number;
-    views: StoryViewSummary[];
-    nextOffset?: string;
-};
-export type MyBoostSummary = {
-    slot: number;
-    peer?: CompactPeer;
-    date: number;
-    expires: number;
-    cooldownUntilDate?: number;
-};
-export type MyBoostsSummary = {
-    count: number;
-    myBoosts: MyBoostSummary[];
-};
-export declare function summarizeMyBoost(boost: Api.TypeMyBoost): MyBoostSummary;
-export declare function summarizeMyBoosts(result: Api.premium.TypeMyBoosts): MyBoostsSummary;
-export type PrepaidGiveawaySummary = {
-    kind: "premium" | "stars";
-    id: string;
-    quantity: number;
-    date: number;
-    months?: number;
-    stars?: string;
-    boosts?: number;
-};
-export type BoostsStatusSummary = {
-    level: number;
-    boosts: number;
-    currentLevelBoosts: number;
-    nextLevelBoosts?: number;
-    giftBoosts?: number;
-    premiumAudience?: {
-        part: number;
-        total: number;
-    };
-    boostUrl: string;
-    myBoost?: boolean;
-    myBoostSlots?: number[];
-    prepaidGiveaways?: PrepaidGiveawaySummary[];
-};
-export declare function summarizePrepaidGiveaway(g: Api.TypePrepaidGiveaway): PrepaidGiveawaySummary;
-export declare function summarizeBoostsStatus(result: Api.premium.TypeBoostsStatus): BoostsStatusSummary;
-export type BoostSummary = {
-    id: string;
-    userId?: string;
-    date: number;
-    expires: number;
-    gift?: boolean;
-    giveaway?: boolean;
-    unclaimed?: boolean;
-    giveawayMsgId?: number;
-    usedGiftSlug?: string;
-    multiplier?: number;
-    stars?: string;
-};
-export type BoostsListSummary = {
-    count: number;
-    boosts: BoostSummary[];
-    nextOffset?: string;
-};
-export declare function summarizeBoost(boost: Api.TypeBoost): BoostSummary;
-export declare function summarizeBoostsList(result: Api.premium.TypeBoostsList): BoostsListSummary;
-export type BusinessChatLinkSummary = {
-    link: string;
-    message: string;
-    title?: string;
-    views: number;
-    entityCount: number;
-};
-export type BusinessChatLinksSummary = {
-    count: number;
-    links: BusinessChatLinkSummary[];
-};
-export declare function summarizeBusinessChatLink(link: Api.TypeBusinessChatLink): BusinessChatLinkSummary;
-export declare function summarizeBusinessChatLinks(result: Api.account.TypeBusinessChatLinks): BusinessChatLinksSummary;
-export type GroupCallInfoSummary = {
-    kind: "active";
-    id: string;
-    accessHash: string;
-    participantsCount: number;
-    title?: string;
-    scheduleDate?: number;
-    recordStartDate?: number;
-    streamDcId?: number;
-    unmutedVideoCount?: number;
-    unmutedVideoLimit: number;
-    version: number;
-    joinMuted?: boolean;
-    canChangeJoinMuted?: boolean;
-    joinDateAsc?: boolean;
-    scheduleStartSubscribed?: boolean;
-    canStartVideo?: boolean;
-    recordVideoActive?: boolean;
-    rtmpStream?: boolean;
-    listenersHidden?: boolean;
-} | {
-    kind: "discarded";
-    id: string;
-    accessHash: string;
-    duration: number;
-};
-export type GroupCallParticipantSummary = {
-    peer: CompactPeer | undefined;
-    date: number;
-    activeDate?: number;
-    source: number;
-    volume?: number;
-    muted?: boolean;
-    left?: boolean;
-    canSelfUnmute?: boolean;
-    justJoined?: boolean;
-    self?: boolean;
-    mutedByYou?: boolean;
-    volumeByAdmin?: boolean;
-    videoJoined?: boolean;
-    about?: string;
-    raiseHandRating?: string;
-    hasVideo?: boolean;
-    hasPresentation?: boolean;
-};
-export type GroupCallSummary = {
-    call: GroupCallInfoSummary;
-    participants: GroupCallParticipantSummary[];
-    participantsNextOffset?: string;
-};
-export type GroupCallParticipantsSummary = {
-    count: number;
-    participants: GroupCallParticipantSummary[];
-    nextOffset?: string;
-    version: number;
-};
-export declare function summarizeGroupCallInfo(call: Api.TypeGroupCall): GroupCallInfoSummary;
-export declare function summarizeGroupCallParticipant(p: Api.TypeGroupCallParticipant): GroupCallParticipantSummary;
-export declare function summarizeGroupCall(result: Api.phone.TypeGroupCall): GroupCallSummary;
-export declare function summarizeGroupCallParticipants(result: Api.phone.TypeGroupParticipants): GroupCallParticipantsSummary;
-export type StarsAmountSummary = {
-    amount: string;
-    nanos: number;
-};
-export type StarsTransactionPeerSummary = {
-    kind: "appStore";
-} | {
-    kind: "playMarket";
-} | {
-    kind: "premiumBot";
-} | {
-    kind: "fragment";
-} | {
-    kind: "ads";
-} | {
-    kind: "api";
-} | {
-    kind: "unsupported";
-} | {
-    kind: "peer";
-    peer: CompactPeer | undefined;
-};
-export type StarsTransactionSummary = {
-    id: string;
-    stars: StarsAmountSummary;
-    date: number;
-    peer: StarsTransactionPeerSummary;
-    refund?: boolean;
-    pending?: boolean;
-    failed?: boolean;
-    gift?: boolean;
-    reaction?: boolean;
-    title?: string;
-    description?: string;
-    msgId?: number;
-    subscriptionPeriod?: number;
-    giveawayPostId?: number;
-    transactionDate?: number;
-    transactionUrl?: string;
-};
-export type StarsSubscriptionPricingSummary = {
-    period: number;
-    amount: string;
-};
-export type StarsSubscriptionSummary = {
-    id: string;
-    peer: CompactPeer | undefined;
-    untilDate: number;
-    pricing: StarsSubscriptionPricingSummary;
-    canceled?: boolean;
-    canRefulfill?: boolean;
-    missingBalance?: boolean;
-    botCanceled?: boolean;
-    chatInviteHash?: string;
-    title?: string;
-    invoiceSlug?: string;
-};
-export type StarsStatusSummary = {
-    balance: StarsAmountSummary;
-    subscriptions?: StarsSubscriptionSummary[];
-    subscriptionsNextOffset?: string;
-    subscriptionsMissingBalance?: string;
-    history?: StarsTransactionSummary[];
-    nextOffset?: string;
-};
-export declare function summarizeStarsAmount(amount: Api.TypeStarsAmount): StarsAmountSummary;
-export declare function summarizeStarsTransactionPeer(peer: Api.TypeStarsTransactionPeer): StarsTransactionPeerSummary;
-export declare function summarizeStarsTransaction(tx: Api.TypeStarsTransaction): StarsTransactionSummary;
-export declare function summarizeStarsSubscription(sub: Api.TypeStarsSubscription): StarsSubscriptionSummary;
-export type QuickReplySummary = {
-    shortcutId: number;
-    shortcut: string;
-    topMessage: number;
-    count: number;
-};
-export type QuickRepliesSummary = {
-    notModified?: boolean;
-    quickReplies?: QuickReplySummary[];
-};
-export declare function summarizeQuickReply(reply: Api.TypeQuickReply): QuickReplySummary;
-export declare function summarizeQuickReplies(result: Api.messages.TypeQuickReplies): QuickRepliesSummary;
-export type QuickReplyMessageSummary = {
-    id: number;
-    date: number;
-    text: string;
-    isService: boolean;
-    fromId?: CompactPeer;
-    replyToMsgId?: number;
-};
-export type QuickReplyMessagesSummary = {
-    notModified?: boolean;
-    count?: number;
-    messages?: QuickReplyMessageSummary[];
-};
-export declare function summarizeQuickReplyMessage(msg: Api.TypeMessage): QuickReplyMessageSummary | null;
-export declare function summarizeQuickReplyMessages(result: Api.messages.TypeMessages): QuickReplyMessagesSummary;
-export declare function summarizeStarsStatus(result: Api.payments.TypeStarsStatus): StarsStatusSummary;
-export declare function summarizeStoryItem(item: Api.TypeStoryItem): StoryItemSummary;
-export declare function summarizePeerStories(ps: Api.TypePeerStories): PeerStoriesSummary | null;
-export declare function summarizeStoriesById(result: Api.stories.TypeStories): StoriesByIdSummary;
-export declare function summarizeStoryView(view: Api.TypeStoryView): StoryViewSummary;
-export declare function summarizeStoryViewsList(result: Api.stories.TypeStoryViewsList): StoryViewsListSummary;
-export declare function summarizeAllStories(result: Api.stories.TypeAllStories): AllStoriesSummary;
+import type { AllStoriesSummary, BoostsListSummary, BoostsStatusSummary, BroadcastStatsSummary, BusinessChatLinksSummary, ChannelDifferenceSummary, ChatPermissions, GroupCallParticipantsSummary, GroupCallSummary, MegagroupStatsSummary, MessageButtonDescriptor, MyBoostsSummary, PeerStoriesSummary, QuickRepliesSummary, QuickReplyMessagesSummary, StarsStatusSummary, StoriesByIdSummary, StoryViewsListSummary, UpdatesDifferenceSummary } from "./telegram-helpers.js";
+export type { AllStoriesSummary, BoostSummary, BoostsListSummary, BoostsStatusSummary, BroadcastStatsSummary, BusinessChatLinkSummary, BusinessChatLinksSummary, ChannelDifferenceSummary, ChatPermissions, CompactPeer, CompactStatsGraph, GroupCallInfoSummary, GroupCallParticipantSummary, GroupCallParticipantsSummary, GroupCallSummary, MegagroupStatsSummary, MessageButtonDescriptor, MyBoostSummary, MyBoostsSummary, PeerStoriesSummary, PrepaidGiveawaySummary, QuickRepliesSummary, QuickReplyMessageSummary, QuickReplyMessagesSummary, QuickReplySummary, StarsAmountSummary, StarsStatusSummary, StarsSubscriptionPricingSummary, StarsSubscriptionSummary, StarsTransactionPeerSummary, StarsTransactionSummary, StatsValue, StoriesByIdSummary, StoryItemSummary, StoryViewSummary, StoryViewsListSummary, UpdatesDifferenceSummary, UpdatesMessageSummary, } from "./telegram-helpers.js";
+export { describeAdminLogAction, describeAdminLogDetails, describeKeyboardButton, mergeBannedRights, peerToCompact, reactionToEmoji, summarizeAllStories, summarizeBoost, summarizeBoostsList, summarizeBoostsStatus, summarizeBroadcastStats, summarizeBusinessChatLink, summarizeBusinessChatLinks, summarizeChannelDifference, summarizeGroupCall, summarizeGroupCallInfo, summarizeGroupCallParticipant, summarizeGroupCallParticipants, summarizeMegagroupStats, summarizeMyBoost, summarizeMyBoosts, summarizePeerStories, summarizePrepaidGiveaway, summarizeQuickReplies, summarizeQuickReply, summarizeQuickReplyMessage, summarizeQuickReplyMessages, summarizeStarsAmount, summarizeStarsStatus, summarizeStarsSubscription, summarizeStarsTransaction, summarizeStarsTransactionPeer, summarizeStoriesById, summarizeStoryItem, summarizeStoryView, summarizeStoryViewsList, summarizeUpdatesDifference, } from "./telegram-helpers.js";
+export type ChatEntity = Api.User | Api.Chat | Api.Channel | Api.TypeUser | Api.TypeChat;
 export declare class TelegramService {
     private client;
     private apiId;
@@ -478,6 +13,7 @@ export declare class TelegramService {
     private sessionPath;
     private rateLimiter;
     private lastTypingAt;
+    private entityCache;
     lastError: string;
     get sessionDir(): string;
     getClient(): TelegramClient | null;
@@ -642,7 +178,7 @@ export declare class TelegramService {
      * Resolve a chat by ID, username, or display name.
      * Falls back to searching user's dialogs if getEntity() fails.
      */
-    resolveChat(chatId: string): Promise<any>;
+    resolveChat(chatId: string): Promise<ChatEntity>;
     /**
      * Resolve chatId to a peer string that GramJS methods accept.
      * Handles display names by searching dialogs.