@overpod/mcp-telegram 1.25.0 → 1.26.0

package/dist/__tests__/broadcast-stats.test.js

@@ -0,0 +1,172 @@
+import assert from "node:assert";
+import { describe, it } from "node:test";
+import bigInt from "big-integer";
+import { Api } from "telegram/tl/index.js";
+import { summarizeBroadcastStats, TelegramService } from "../telegram-client.js";
+function makeService(entity, invokeImpl, invocations) {
+    const fakeClient = {
+        invoke: async (req) => {
+            invocations.push(req);
+            return invokeImpl(req);
+        },
+    };
+    const service = new TelegramService(1, "hash");
+    const internals = service;
+    internals.client = fakeClient;
+    internals.connected = true;
+    internals.resolveChat = async () => entity;
+    return service;
+}
+function fakeStats() {
+    // Build a plain object that structurally matches BroadcastStats.
+    // We cast through unknown so tests don't depend on GramJS constructor quirks.
+    return {
+        period: { minDate: 1000, maxDate: 2000 },
+        followers: { current: 100, previous: 80 },
+        viewsPerPost: { current: 500, previous: 400 },
+        sharesPerPost: { current: 10, previous: 8 },
+        reactionsPerPost: { current: 25, previous: 20 },
+        viewsPerStory: { current: 50, previous: 45 },
+        sharesPerStory: { current: 3, previous: 2 },
+        reactionsPerStory: { current: 7, previous: 6 },
+        enabledNotifications: { part: 40, total: 100 },
+        growthGraph: new Api.StatsGraphAsync({ token: "growth-token" }),
+        followersGraph: new Api.StatsGraphAsync({ token: "followers-token" }),
+        muteGraph: new Api.StatsGraphError({ error: "unavailable" }),
+        topHoursGraph: new Api.StatsGraph({
+            json: new Api.DataJSON({ data: '{"x":[1,2,3]}' }),
+            zoomToken: "zoom",
+        }),
+        interactionsGraph: new Api.StatsGraphAsync({ token: "inter-token" }),
+        ivInteractionsGraph: new Api.StatsGraphAsync({ token: "iv-token" }),
+        viewsBySourceGraph: new Api.StatsGraphAsync({ token: "views-src-token" }),
+        newFollowersBySourceGraph: new Api.StatsGraphAsync({ token: "new-src-token" }),
+        languagesGraph: new Api.StatsGraphAsync({ token: "lang-token" }),
+        reactionsByEmotionGraph: new Api.StatsGraphAsync({ token: "react-token" }),
+        storyInteractionsGraph: new Api.StatsGraphAsync({ token: "story-inter-token" }),
+        storyReactionsByEmotionGraph: new Api.StatsGraphAsync({ token: "story-react-token" }),
+        recentPostsInteractions: [
+            new Api.PostInteractionCountersMessage({ msgId: 42, views: 500, forwards: 3, reactions: 12 }),
+            new Api.PostInteractionCountersStory({ storyId: 7, views: 50, forwards: 1, reactions: 4 }),
+        ],
+    };
+}
+describe("summarizeBroadcastStats", () => {
+    it("produces compact summary without graphs by default", () => {
+        const summary = summarizeBroadcastStats(fakeStats(), false);
+        assert.strictEqual(summary.graphs, undefined);
+        assert.deepStrictEqual(summary.period, { minDate: 1000, maxDate: 2000 });
+        assert.deepStrictEqual(summary.followers, { current: 100, previous: 80 });
+        assert.deepStrictEqual(summary.viewsPerPost, { current: 500, previous: 400 });
+        assert.strictEqual(summary.enabledNotifications.percent, 40);
+        assert.strictEqual(summary.recentPostsInteractions.length, 2);
+        assert.deepStrictEqual(summary.recentPostsInteractions[0], {
+            kind: "message",
+            msgId: 42,
+            views: 500,
+            forwards: 3,
+            reactions: 12,
+        });
+        assert.deepStrictEqual(summary.recentPostsInteractions[1], {
+            kind: "story",
+            storyId: 7,
+            views: 50,
+            forwards: 1,
+            reactions: 4,
+        });
+    });
+    it("handles zero-total enabled notifications without dividing by zero", () => {
+        const stats = fakeStats();
+        stats.enabledNotifications = {
+            part: 0,
+            total: 0,
+        };
+        const summary = summarizeBroadcastStats(stats, false);
+        assert.strictEqual(summary.enabledNotifications.percent, 0);
+    });
+    it("includes and decodes graphs when requested", () => {
+        const summary = summarizeBroadcastStats(fakeStats(), true);
+        assert.ok(summary.graphs);
+        const graphs = summary.graphs ?? {};
+        assert.deepStrictEqual(graphs.growth, { type: "async", token: "growth-token" });
+        assert.deepStrictEqual(graphs.mute, { type: "error", error: "unavailable" });
+        assert.deepStrictEqual(graphs.topHours, { type: "data", data: { x: [1, 2, 3] }, zoomToken: "zoom" });
+    });
+});
+describe("TelegramService.getBroadcastStats", () => {
+    function broadcastChannel() {
+        return new Api.Channel({
+            id: bigInt(12345),
+            title: "broadcast",
+            photo: new Api.ChatPhotoEmpty(),
+            date: 0,
+            accessHash: bigInt(1),
+            broadcast: true,
+        });
+    }
+    it("invokes stats.GetBroadcastStats and returns compact summary", async () => {
+        const invocations = [];
+        const service = makeService(broadcastChannel(), async () => fakeStats(), invocations);
+        const summary = await service.getBroadcastStats("12345");
+        const call = invocations.find((r) => r instanceof Api.stats.GetBroadcastStats);
+        assert.ok(call, "GetBroadcastStats was invoked");
+        assert.strictEqual(summary.followers.current, 100);
+        assert.strictEqual(summary.graphs, undefined);
+    });
+    it("passes dark=true when requested", async () => {
+        const invocations = [];
+        const service = makeService(broadcastChannel(), async () => fakeStats(), invocations);
+        await service.getBroadcastStats("12345", { dark: true });
+        const call = invocations.find((r) => r instanceof Api.stats.GetBroadcastStats);
+        assert.ok(call);
+        assert.strictEqual(call.dark, true);
+    });
+    it("includes graphs when includeGraphs=true", async () => {
+        const invocations = [];
+        const service = makeService(broadcastChannel(), async () => fakeStats(), invocations);
+        const summary = await service.getBroadcastStats("12345", { includeGraphs: true });
+        assert.ok(summary.graphs);
+        assert.strictEqual(summary.graphs?.growth.type, "async");
+    });
+    it("rejects supergroups with hint to use megagroup stats", async () => {
+        const megagroup = new Api.Channel({
+            id: bigInt(33333),
+            title: "supergroup",
+            photo: new Api.ChatPhotoEmpty(),
+            date: 0,
+            accessHash: bigInt(1),
+            megagroup: true,
+        });
+        const invocations = [];
+        const service = makeService(megagroup, async () => fakeStats(), invocations);
+        await assert.rejects(service.getBroadcastStats("33333"), /telegram-get-megagroup-stats/);
+        assert.strictEqual(invocations.find((r) => r instanceof Api.stats.GetBroadcastStats), undefined);
+    });
+    it("rejects non-channel entities", async () => {
+        const chat = new Api.Chat({
+            id: bigInt(44444),
+            title: "basic group",
+            photo: new Api.ChatPhotoEmpty(),
+            participantsCount: 5,
+            date: 0,
+            version: 0,
+        });
+        const invocations = [];
+        const service = makeService(chat, async () => fakeStats(), invocations);
+        await assert.rejects(service.getBroadcastStats("44444"), /channels/);
+    });
+    it("surfaces admin-required errors with a clearer message", async () => {
+        const invocations = [];
+        const service = makeService(broadcastChannel(), async () => {
+            throw new Error("CHAT_ADMIN_REQUIRED");
+        }, invocations);
+        await assert.rejects(service.getBroadcastStats("12345"), /admin rights/i);
+    });
+    it("surfaces stats-unavailable errors with premium hint", async () => {
+        const invocations = [];
+        const service = makeService(broadcastChannel(), async () => {
+            throw new Error("STATS_UNAVAILABLE");
+        }, invocations);
+        await assert.rejects(service.getBroadcastStats("12345"), /Premium/i);
+    });
+});

package/dist/__tests__/business-chat-links.test.d.ts

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

package/dist/__tests__/business-chat-links.test.js

@@ -0,0 +1,102 @@
+import assert from "node:assert";
+import { describe, it } from "node:test";
+import { Api } from "telegram/tl/index.js";
+import { summarizeBusinessChatLink, summarizeBusinessChatLinks, TelegramService } from "../telegram-client.js";
+function makeService(invocations, responder) {
+    const fakeClient = {
+        invoke: async (req) => {
+            invocations.push(req);
+            return responder(req);
+        },
+    };
+    const service = new TelegramService(1, "hash");
+    const internals = service;
+    internals.client = fakeClient;
+    internals.connected = true;
+    return service;
+}
+describe("summarizeBusinessChatLink", () => {
+    it("maps link, message, title, views and entity count", () => {
+        const link = new Api.BusinessChatLink({
+            link: "https://t.me/message/abc",
+            message: "Hello there",
+            title: "Welcome",
+            views: 42,
+            entities: [
+                new Api.MessageEntityBold({ offset: 0, length: 5 }),
+                new Api.MessageEntityItalic({ offset: 6, length: 5 }),
+            ],
+        });
+        const out = summarizeBusinessChatLink(link);
+        assert.strictEqual(out.link, "https://t.me/message/abc");
+        assert.strictEqual(out.message, "Hello there");
+        assert.strictEqual(out.title, "Welcome");
+        assert.strictEqual(out.views, 42);
+        assert.strictEqual(out.entityCount, 2);
+    });
+    it("leaves title undefined and entityCount 0 when entities missing", () => {
+        const link = new Api.BusinessChatLink({
+            link: "https://t.me/message/xyz",
+            message: "Plain",
+            views: 0,
+        });
+        const out = summarizeBusinessChatLink(link);
+        assert.strictEqual(out.title, undefined);
+        assert.strictEqual(out.entityCount, 0);
+        assert.strictEqual(out.views, 0);
+    });
+});
+describe("summarizeBusinessChatLinks", () => {
+    it("computes count from links length and maps each entry", () => {
+        const resp = new Api.account.BusinessChatLinks({
+            links: [
+                new Api.BusinessChatLink({
+                    link: "https://t.me/message/a",
+                    message: "Hi",
+                    views: 1,
+                }),
+                new Api.BusinessChatLink({
+                    link: "https://t.me/message/b",
+                    message: "Hello",
+                    title: "Label",
+                    views: 5,
+                }),
+            ],
+            chats: [],
+            users: [],
+        });
+        const out = summarizeBusinessChatLinks(resp);
+        assert.strictEqual(out.count, 2);
+        assert.strictEqual(out.links.length, 2);
+        assert.strictEqual(out.links[0].link, "https://t.me/message/a");
+        assert.strictEqual(out.links[1].title, "Label");
+    });
+    it("handles empty link list", () => {
+        const resp = new Api.account.BusinessChatLinks({ links: [], chats: [], users: [] });
+        const out = summarizeBusinessChatLinks(resp);
+        assert.strictEqual(out.count, 0);
+        assert.deepStrictEqual(out.links, []);
+    });
+});
+describe("TelegramService.getBusinessChatLinks", () => {
+    it("invokes account.GetBusinessChatLinks and returns summary", async () => {
+        const invocations = [];
+        const service = makeService(invocations, () => new Api.account.BusinessChatLinks({
+            links: [
+                new Api.BusinessChatLink({
+                    link: "https://t.me/message/foo",
+                    message: "hey",
+                    views: 9,
+                }),
+            ],
+            chats: [],
+            users: [],
+        }));
+        const out = await service.getBusinessChatLinks();
+        const call = invocations.find((r) => r instanceof Api.account.GetBusinessChatLinks);
+        assert.ok(call);
+        assert.strictEqual(out.count, 1);
+        assert.strictEqual(out.links[0].link, "https://t.me/message/foo");
+        assert.strictEqual(out.links[0].views, 9);
+    });
+});

package/dist/__tests__/get-message-buttons.test.d.ts

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

package/dist/__tests__/get-message-buttons.test.js

@@ -0,0 +1,122 @@
+import assert from "node:assert";
+import { describe, it } from "node:test";
+import bigInt from "big-integer";
+import { Api } from "telegram/tl/index.js";
+import { TelegramService } from "../telegram-client.js";
+function makeService(chatEntity, messages) {
+    const fakeClient = {
+        getMessages: async (_entity, _opts) => messages,
+    };
+    const service = new TelegramService(1, "hash");
+    const internals = service;
+    internals.client = fakeClient;
+    internals.connected = true;
+    internals.resolveChat = async () => chatEntity;
+    return service;
+}
+function makeChannel(id) {
+    return new Api.Channel({
+        id: bigInt(id),
+        title: "t",
+        photo: new Api.ChatPhotoEmpty(),
+        date: 0,
+        accessHash: bigInt(1),
+        megagroup: true,
+    });
+}
+function makeMessage(id, markup) {
+    return new Api.Message({
+        id,
+        peerId: new Api.PeerChannel({ channelId: bigInt(100) }),
+        date: 0,
+        message: "hi",
+        replyMarkup: markup,
+    });
+}
+function inlineMarkup(buttons) {
+    return new Api.ReplyInlineMarkup({
+        rows: buttons.map((row) => new Api.KeyboardButtonRow({ buttons: row })),
+    });
+}
+describe("TelegramService.getMessageButtons", () => {
+    it("returns empty buttons and markupType='none' when message has no markup", async () => {
+        const msg = makeMessage(1, undefined);
+        const service = makeService(makeChannel(100), [msg]);
+        const res = await service.getMessageButtons("100", 1);
+        assert.deepStrictEqual(res, { markupType: "none", buttons: [] });
+    });
+    it("describes a callback button with base64 data", async () => {
+        const data = Buffer.from("vote_yes");
+        const msg = makeMessage(42, inlineMarkup([[new Api.KeyboardButtonCallback({ text: "Yes", data, requiresPassword: false })]]));
+        const service = makeService(makeChannel(100), [msg]);
+        const res = await service.getMessageButtons("100", 42);
+        assert.strictEqual(res.markupType, "ReplyInlineMarkup");
+        assert.strictEqual(res.buttons.length, 1);
+        const b = res.buttons[0];
+        assert.strictEqual(b.row, 0);
+        assert.strictEqual(b.col, 0);
+        assert.strictEqual(b.type, "KeyboardButtonCallback");
+        assert.strictEqual(b.label, "Yes");
+        assert.ok(b.data, "data is set");
+        assert.strictEqual(Buffer.from(b.data, "base64").toString(), "vote_yes");
+        assert.strictEqual(b.requiresPassword, undefined);
+    });
+    it("flags requiresPassword callback buttons", async () => {
+        const msg = makeMessage(1, inlineMarkup([
+            [new Api.KeyboardButtonCallback({ text: "Admin", data: Buffer.from("x"), requiresPassword: true })],
+        ]));
+        const service = makeService(makeChannel(100), [msg]);
+        const res = await service.getMessageButtons("100", 1);
+        assert.strictEqual(res.buttons[0].requiresPassword, true);
+    });
+    it("describes URL, switch-inline and copy buttons with type-specific fields", async () => {
+        const msg = makeMessage(2, inlineMarkup([
+            [
+                new Api.KeyboardButtonUrl({ text: "Open", url: "https://x.test" }),
+                new Api.KeyboardButtonSwitchInline({ text: "Inline", query: "q", samePeer: true }),
+            ],
+            [new Api.KeyboardButtonCopy({ text: "Copy", copyText: "abc" })],
+        ]));
+        const service = makeService(makeChannel(100), [msg]);
+        const res = await service.getMessageButtons("100", 2);
+        assert.strictEqual(res.buttons.length, 3);
+        const [urlB, inlineB, copyB] = res.buttons;
+        assert.strictEqual(urlB.type, "KeyboardButtonUrl");
+        assert.strictEqual(urlB.url, "https://x.test");
+        assert.strictEqual(urlB.row, 0);
+        assert.strictEqual(urlB.col, 0);
+        assert.strictEqual(inlineB.type, "KeyboardButtonSwitchInline");
+        assert.strictEqual(inlineB.switchQuery, "q");
+        assert.strictEqual(inlineB.samePeer, true);
+        assert.strictEqual(inlineB.row, 0);
+        assert.strictEqual(inlineB.col, 1);
+        assert.strictEqual(copyB.type, "KeyboardButtonCopy");
+        assert.strictEqual(copyB.copyText, "abc");
+        assert.strictEqual(copyB.row, 1);
+        assert.strictEqual(copyB.col, 0);
+    });
+    it("preserves markupType for non-inline reply keyboards with buttons", async () => {
+        const markup = new Api.ReplyKeyboardMarkup({
+            rows: [new Api.KeyboardButtonRow({ buttons: [new Api.KeyboardButton({ text: "x" })] })],
+        });
+        const msg = makeMessage(3, markup);
+        const service = makeService(makeChannel(100), [msg]);
+        const res = await service.getMessageButtons("100", 3);
+        assert.strictEqual(res.markupType, "ReplyKeyboardMarkup");
+        assert.strictEqual(res.buttons.length, 1);
+        assert.strictEqual(res.buttons[0].type, "KeyboardButton");
+        assert.strictEqual(res.buttons[0].label, "x");
+    });
+    it("returns empty buttons for ReplyKeyboardHide-like markup without rows", async () => {
+        const markup = new Api.ReplyKeyboardHide({ selective: false });
+        const msg = makeMessage(4, markup);
+        const service = makeService(makeChannel(100), [msg]);
+        const res = await service.getMessageButtons("100", 4);
+        assert.strictEqual(res.markupType, "ReplyKeyboardHide");
+        assert.deepStrictEqual(res.buttons, []);
+    });
+    it("rejects when message is not found", async () => {
+        const service = makeService(makeChannel(100), []);
+        await assert.rejects(service.getMessageButtons("100", 999), /not found/i);
+    });
+});

package/dist/__tests__/group-calls.test.d.ts

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