@overpod/mcp-telegram 1.25.0 → 1.26.1

package/dist/tools/stories.js

@@ -0,0 +1,107 @@
+import { z } from "zod";
+import { fail, ok, READ_ONLY, requireConnection } from "./shared.js";
+export function registerStoryTools(server, telegram) {
+    server.registerTool("telegram-get-all-stories", {
+        description: "Fetch active stories from contacts/channels the user follows. Pagination via 'next' + 'state' — pass the returned state back on the next call with next:true to load more. Use hidden:true to read stories from muted/archived peers. Returns compact story metadata (id, date, expireDate, caption, mediaType, counters) without raw media blobs.",
+        inputSchema: {
+            next: z.boolean().optional().describe("Load the next page (use with state from a prior response)"),
+            hidden: z.boolean().optional().describe("Fetch stories from hidden/archived peers instead of the main feed"),
+            state: z.string().optional().describe("Pagination state token returned by a previous call"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ next, hidden, state }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        if (next === true && !state) {
+            return fail(new Error("'state' is required when 'next' is true — use the state token from a prior telegram-get-all-stories response"));
+        }
+        try {
+            const result = await telegram.getAllStories({ next, hidden, state });
+            return ok(JSON.stringify(result));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-peer-stories", {
+        description: "Fetch currently active stories posted by a specific peer (user/channel). Returns compact story metadata (id, date, expireDate, caption, mediaType, counters) with media type className only — no raw media blobs. Use telegram-download-media with the story id if you need media bytes.",
+        inputSchema: {
+            chat: z
+                .string()
+                .describe("Peer to fetch stories from — user/channel id, @username, phone, or display name fragment"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ chat }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.getPeerStories(chat);
+            if (result === null)
+                return ok("No active stories found for the specified peer");
+            return ok(JSON.stringify(result));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-stories-by-id", {
+        description: "Fetch specific stories from a peer by their numeric IDs. Useful for retrieving archived/pinned stories outside the active feed. Returns compact story metadata and optional pinnedToTop list. Pass up to ~100 ids per request.",
+        inputSchema: {
+            chat: z
+                .string()
+                .describe("Peer to fetch stories from — user/channel id, @username, phone, or display name fragment"),
+            ids: z.array(z.number().int().positive()).min(1).max(100).describe("Story IDs to fetch (1–100 per request)"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ chat, ids }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.getStoriesById(chat, ids);
+            return ok(JSON.stringify(result));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-story-views", {
+        description: "List viewers of one of YOUR stories (stories.GetStoryViewsList). Returns per-viewer entries (user id, view date, their reaction emoji if any), plus totals (viewsCount, forwardsCount, reactionsCount) and nextOffset for pagination. Pass your own user id (numeric) or @username as the peer — this only works for stories you posted. Some accounts (non-Premium, old stories) may not get a full viewer list — a Premium hint is surfaced on typical errors.",
+        inputSchema: {
+            chat: z.string().describe("Peer owning the story — usually 'me' or your own user id/@username"),
+            storyId: z.number().int().positive().describe("Story ID to fetch viewers for"),
+            q: z.string().optional().describe("Filter viewers by name substring"),
+            justContacts: z.boolean().optional().describe("Return only contacts"),
+            reactionsFirst: z.boolean().optional().describe("Sort viewers who reacted first"),
+            forwardsFirst: z.boolean().optional().describe("Sort forwards/reposts first"),
+            offset: z.string().optional().describe("Pagination offset from a previous response's nextOffset"),
+            limit: z.number().int().min(1).max(100).optional().describe("Max viewers to return (default 50, max 100)"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ chat, storyId, q, justContacts, reactionsFirst, forwardsFirst, offset, limit }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.getStoryViewsList(chat, {
+                id: storyId,
+                q,
+                justContacts,
+                reactionsFirst,
+                forwardsFirst,
+                offset,
+                limit,
+            });
+            return ok(JSON.stringify(result));
+        }
+        catch (e) {
+            const msg = e.message ?? "";
+            if (/PREMIUM|PAYMENT_REQUIRED/i.test(msg)) {
+                return fail(new Error("story view stats may require Telegram Premium"));
+            }
+            return fail(e);
+        }
+    });
+}

package/package.json

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

package/dist/__tests__/admin-log.test.d.ts

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

package/dist/__tests__/admin-log.test.js

@@ -1,41 +0,0 @@
-import assert from "node:assert";
-import { describe, it } from "node:test";
-import { Api } from "telegram/tl/index.js";
-import { describeAdminLogAction, describeAdminLogDetails } from "../telegram-client.js";
-describe("describeAdminLogAction", () => {
-    it("converts ChangeTitle to snake_case", () => {
-        const action = new Api.ChannelAdminLogEventActionChangeTitle({ prevValue: "a", newValue: "b" });
-        assert.strictEqual(describeAdminLogAction(action), "change_title");
-    });
-    it("converts ParticipantJoin to snake_case", () => {
-        const action = new Api.ChannelAdminLogEventActionParticipantJoin();
-        assert.strictEqual(describeAdminLogAction(action), "participant_join");
-    });
-    it("handles ToggleSlowMode", () => {
-        const action = new Api.ChannelAdminLogEventActionToggleSlowMode({ prevValue: 0, newValue: 30 });
-        assert.strictEqual(describeAdminLogAction(action), "toggle_slow_mode");
-    });
-    it("handles ChangeHistoryTTL without splitting acronym", () => {
-        const action = new Api.ChannelAdminLogEventActionChangeHistoryTTL({ prevValue: 0, newValue: 86400 });
-        assert.strictEqual(describeAdminLogAction(action), "change_history_ttl");
-    });
-});
-describe("describeAdminLogDetails", () => {
-    const describeUser = (id) => `user_${id.toString()}`;
-    it("formats title change", () => {
-        const action = new Api.ChannelAdminLogEventActionChangeTitle({ prevValue: "old", newValue: "new" });
-        assert.strictEqual(describeAdminLogDetails(action, describeUser), '"old" → "new"');
-    });
-    it("formats username change", () => {
-        const action = new Api.ChannelAdminLogEventActionChangeUsername({ prevValue: "old", newValue: "new" });
-        assert.strictEqual(describeAdminLogDetails(action, describeUser), "@old → @new");
-    });
-    it("formats slow mode change", () => {
-        const action = new Api.ChannelAdminLogEventActionToggleSlowMode({ prevValue: 0, newValue: 30 });
-        assert.strictEqual(describeAdminLogDetails(action, describeUser), "0s → 30s");
-    });
-    it("returns empty string for unknown actions", () => {
-        const action = new Api.ChannelAdminLogEventActionParticipantJoin();
-        assert.strictEqual(describeAdminLogDetails(action, describeUser), "");
-    });
-});

package/dist/__tests__/rate-limiter.test.d.ts

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

package/dist/__tests__/rate-limiter.test.js

@@ -1,81 +0,0 @@
-import assert from "node:assert";
-import { describe, it } from "node:test";
-import { RateLimiter } from "../rate-limiter.js";
-describe("RateLimiter", () => {
-    it("should execute a function successfully", async () => {
-        const limiter = new RateLimiter({ maxRequestsPerSecond: 100 });
-        const result = await limiter.execute(async () => "success");
-        assert.strictEqual(result, "success");
-    });
-    it("should enforce rate limiting between requests", async () => {
-        const limiter = new RateLimiter({ maxRequestsPerSecond: 10 }); // 10 req/s = 100ms between requests
-        const start = Date.now();
-        await limiter.execute(async () => "first");
-        await limiter.execute(async () => "second");
-        const elapsed = Date.now() - start;
-        assert.ok(elapsed >= 90, `Expected at least 90ms, got ${elapsed}ms`);
-    });
-    it("should retry on FLOOD_WAIT error", async () => {
-        const limiter = new RateLimiter({ maxRetries: 2, maxRequestsPerSecond: 100 });
-        let attempts = 0;
-        const result = await limiter.execute(async () => {
-            attempts++;
-            if (attempts < 2) {
-                throw new Error("FLOOD_WAIT_1");
-            }
-            return "success after retry";
-        });
-        assert.strictEqual(result, "success after retry");
-        assert.strictEqual(attempts, 2);
-    });
-    it("should throw after max retries on FLOOD_WAIT", async () => {
-        const limiter = new RateLimiter({ maxRetries: 1, maxRequestsPerSecond: 100 });
-        await assert.rejects(async () => {
-            await limiter.execute(async () => {
-                throw new Error("FLOOD_WAIT_2");
-            });
-        }, {
-            message: /Rate limit exceeded after 1 retries/,
-        });
-    });
-    it("should retry on network errors with exponential backoff", async () => {
-        const limiter = new RateLimiter({
-            maxRetries: 2,
-            initialRetryDelay: 100,
-            maxRequestsPerSecond: 100,
-        });
-        let attempts = 0;
-        const result = await limiter.execute(async () => {
-            attempts++;
-            if (attempts < 2) {
-                throw new Error("TIMEOUT");
-            }
-            return "recovered";
-        });
-        assert.strictEqual(result, "recovered");
-        assert.strictEqual(attempts, 2);
-    });
-    it("should not retry on non-retryable errors", async () => {
-        const limiter = new RateLimiter({ maxRetries: 3, maxRequestsPerSecond: 100 });
-        let attempts = 0;
-        await assert.rejects(async () => {
-            await limiter.execute(async () => {
-                attempts++;
-                throw new Error("AUTH_KEY_UNREGISTERED");
-            });
-        }, {
-            message: "AUTH_KEY_UNREGISTERED",
-        });
-        assert.strictEqual(attempts, 1, "Should not retry non-retryable errors");
-    });
-    it("should handle FLOOD_WAIT with seconds parsing", async () => {
-        const limiter = new RateLimiter({ maxRetries: 1, maxRequestsPerSecond: 100 });
-        await assert.rejects(async () => {
-            await limiter.execute(async () => {
-                throw new Error("FLOOD_WAIT_1");
-            });
-        }, {
-            message: /Telegram requires 1s wait/,
-        });
-    });
-});

package/dist/__tests__/reactions.test.d.ts

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

package/dist/__tests__/reactions.test.js

@@ -1,23 +0,0 @@
-import assert from "node:assert";
-import { describe, it } from "node:test";
-import bigInt from "big-integer";
-import { Api } from "telegram/tl/index.js";
-import { reactionToEmoji } from "../telegram-client.js";
-describe("reactionToEmoji", () => {
-    it("returns emoticon for ReactionEmoji", () => {
-        const r = new Api.ReactionEmoji({ emoticon: "👍" });
-        assert.strictEqual(reactionToEmoji(r), "👍");
-    });
-    it("returns custom:<id> for ReactionCustomEmoji", () => {
-        const r = new Api.ReactionCustomEmoji({ documentId: bigInt(12345) });
-        assert.strictEqual(reactionToEmoji(r), "custom:12345");
-    });
-    it("returns star for ReactionPaid", () => {
-        const r = new Api.ReactionPaid();
-        assert.strictEqual(reactionToEmoji(r), "⭐");
-    });
-    it("returns null for ReactionEmpty", () => {
-        const r = new Api.ReactionEmpty();
-        assert.strictEqual(reactionToEmoji(r), null);
-    });
-});

package/dist/__tests__/set-chat-permissions-merge.test.d.ts

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

package/dist/__tests__/set-chat-permissions-merge.test.js

@@ -1,107 +0,0 @@
-import assert from "node:assert";
-import { describe, it } from "node:test";
-import bigInt from "big-integer";
-import { Api } from "telegram/tl/index.js";
-import { mergeBannedRights, TelegramService } from "../telegram-client.js";
-describe("mergeBannedRights", () => {
-    it("preserves omitted flags from current rights", () => {
-        const current = { pinMessages: true, inviteUsers: true, sendMessages: false };
-        const merged = mergeBannedRights(current, { sendMessages: false });
-        assert.strictEqual(merged.sendMessages, true, "user-specified denial applies");
-        assert.strictEqual(merged.pinMessages, true, "omitted flag stays banned");
-        assert.strictEqual(merged.inviteUsers, true, "omitted flag stays banned");
-        assert.strictEqual(merged.sendMedia, false, "omitted flag with no current stays unbanned");
-    });
-    it("user-provided value overrides current", () => {
-        const current = { pinMessages: true };
-        const merged = mergeBannedRights(current, { pinMessages: true });
-        assert.strictEqual(merged.pinMessages, false, "pinMessages:true allowed -> not banned");
-    });
-    it("fills missing flags with false when current is undefined", () => {
-        const merged = mergeBannedRights(undefined, { sendMessages: true });
-        assert.strictEqual(merged.sendMessages, false);
-        assert.strictEqual(merged.sendMedia, false);
-        assert.strictEqual(merged.pinMessages, false);
-    });
-    it("covers all nineteen flags (10 exposed + 9 extra preserved)", () => {
-        const merged = mergeBannedRights(undefined, {});
-        const keys = Object.keys(merged).sort();
-        assert.deepStrictEqual(keys, [
-            "changeInfo",
-            "embedLinks",
-            "inviteUsers",
-            "manageTopics",
-            "pinMessages",
-            "sendAudios",
-            "sendDocs",
-            "sendGames",
-            "sendGifs",
-            "sendInline",
-            "sendMedia",
-            "sendMessages",
-            "sendPhotos",
-            "sendPlain",
-            "sendPolls",
-            "sendRoundvideos",
-            "sendStickers",
-            "sendVideos",
-            "sendVoices",
-        ]);
-    });
-});
-describe("TelegramService.setChatPermissions", () => {
-    it("merges new permissions with existing defaultBannedRights", async () => {
-        const existingRights = new Api.ChatBannedRights({
-            untilDate: 0,
-            pinMessages: true,
-            inviteUsers: true,
-        });
-        const channel = new Api.Channel({
-            id: bigInt(12345),
-            title: "test",
-            photo: new Api.ChatPhotoEmpty(),
-            date: 0,
-            accessHash: bigInt(1),
-            defaultBannedRights: existingRights,
-        });
-        const inputChannel = new Api.InputPeerChannel({ channelId: bigInt(12345), accessHash: bigInt(1) });
-        const invocations = [];
-        const fakeClient = {
-            invoke: async (req) => {
-                invocations.push(req);
-                if (req instanceof Api.channels.GetFullChannel) {
-                    return new Api.messages.ChatFull({
-                        fullChat: new Api.ChannelFull({
-                            id: bigInt(12345),
-                            about: "",
-                            readInboxMaxId: 0,
-                            readOutboxMaxId: 0,
-                            unreadCount: 0,
-                            chatPhoto: new Api.PhotoEmpty({ id: bigInt(0) }),
-                            notifySettings: new Api.PeerNotifySettings({}),
-                            pts: 0,
-                            botInfo: [],
-                        }),
-                        chats: [channel],
-                        users: [],
-                    });
-                }
-                return undefined;
-            },
-            getInputEntity: async () => inputChannel,
-        };
-        const service = new TelegramService(1, "hash");
-        const internals = service;
-        internals.client = fakeClient;
-        internals.connected = true;
-        internals.resolveChat = async () => channel;
-        await service.setChatPermissions("12345", { sendMessages: false });
-        const editCall = invocations.find((r) => r instanceof Api.messages.EditChatDefaultBannedRights);
-        assert.ok(editCall, "EditChatDefaultBannedRights was invoked");
-        const rights = editCall.bannedRights;
-        assert.strictEqual(rights.sendMessages, true, "sendMessages becomes banned");
-        assert.strictEqual(rights.pinMessages, true, "pinMessages stays banned (preserved)");
-        assert.strictEqual(rights.inviteUsers, true, "inviteUsers stays banned (preserved)");
-        assert.strictEqual(rights.sendMedia, false, "omitted flag with no prior value stays unbanned");
-    });
-});

package/dist/__tests__/tools/shared.test.d.ts

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

package/dist/__tests__/tools/shared.test.js

@@ -1,110 +0,0 @@
-import assert from "node:assert";
-import { describe, it } from "node:test";
-import { DESTRUCTIVE, fail, formatReactions, ok, READ_ONLY, sanitize, WRITE } from "../../tools/shared.js";
-describe("shared utilities", () => {
-    describe("ok()", () => {
-        it("should return success response with text content", () => {
-            const result = ok("Operation successful");
-            assert.deepStrictEqual(result, {
-                content: [{ type: "text", text: "Operation successful" }],
-            });
-        });
-        it("should handle empty string", () => {
-            const result = ok("");
-            assert.deepStrictEqual(result, {
-                content: [{ type: "text", text: "" }],
-            });
-        });
-    });
-    describe("fail()", () => {
-        it("should return error response with isError flag", () => {
-            const error = new Error("Something went wrong");
-            const result = fail(error);
-            assert.deepStrictEqual(result, {
-                content: [{ type: "text", text: "Error: Something went wrong" }],
-                isError: true,
-            });
-        });
-        it("should handle non-Error objects", () => {
-            const result = fail({ message: "Custom error" });
-            assert.ok(result.content[0].text.includes("Error:"));
-            assert.strictEqual(result.isError, true);
-        });
-    });
-    describe("sanitize()", () => {
-        it("should remove unpaired high surrogates", () => {
-            const input = "Hello\uD800World";
-            const result = sanitize(input);
-            assert.strictEqual(result, "Hello\uFFFDWorld");
-        });
-        it("should remove unpaired low surrogates", () => {
-            const input = "Hello\uDC00World";
-            const result = sanitize(input);
-            assert.strictEqual(result, "Hello\uFFFDWorld");
-        });
-        it("should preserve valid surrogate pairs", () => {
-            const input = "Hello\uD83D\uDE00World"; // 😀 emoji
-            const result = sanitize(input);
-            assert.strictEqual(result, "Hello\uD83D\uDE00World");
-        });
-        it("should handle normal text without surrogates", () => {
-            const input = "Hello World";
-            const result = sanitize(input);
-            assert.strictEqual(result, "Hello World");
-        });
-        it("should handle empty string", () => {
-            const result = sanitize("");
-            assert.strictEqual(result, "");
-        });
-    });
-    describe("formatReactions()", () => {
-        it("should format reactions with counts", () => {
-            const reactions = [
-                { emoji: "👍", count: 5, me: false },
-                { emoji: "❤️", count: 3, me: true },
-                { emoji: "🔥", count: 1, me: false },
-            ];
-            const result = formatReactions(reactions);
-            assert.strictEqual(result, " [👍×5 ❤️×3(me) 🔥×1]");
-        });
-        it("should mark reactions from current user", () => {
-            const reactions = [{ emoji: "👍", count: 2, me: true }];
-            const result = formatReactions(reactions);
-            assert.strictEqual(result, " [👍×2(me)]");
-        });
-        it("should return empty string for undefined reactions", () => {
-            const result = formatReactions(undefined);
-            assert.strictEqual(result, "");
-        });
-        it("should return empty string for empty reactions array", () => {
-            const result = formatReactions([]);
-            assert.strictEqual(result, "");
-        });
-        it("should handle single reaction", () => {
-            const reactions = [{ emoji: "🎉", count: 1, me: false }];
-            const result = formatReactions(reactions);
-            assert.strictEqual(result, " [🎉×1]");
-        });
-    });
-    describe("MCP tool annotations", () => {
-        it("should define READ_ONLY preset", () => {
-            assert.deepStrictEqual(READ_ONLY, {
-                readOnlyHint: true,
-                openWorldHint: true,
-            });
-        });
-        it("should define WRITE preset", () => {
-            assert.deepStrictEqual(WRITE, {
-                readOnlyHint: false,
-                openWorldHint: true,
-            });
-        });
-        it("should define DESTRUCTIVE preset", () => {
-            assert.deepStrictEqual(DESTRUCTIVE, {
-                readOnlyHint: false,
-                destructiveHint: true,
-                openWorldHint: true,
-            });
-        });
-    });
-});