@overpod/mcp-telegram 1.24.1 → 1.26.0

package/CHANGELOG.md

@@ -5,7 +5,73 @@ 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).
 
-## [Unreleased]
+## [1.26.0] - 2026-04-20
+
+### Added
+- **Phase 2 — Admin Toggles, Customization, Stats (8 tools)**
+  - `telegram-toggle-channel-signatures` — toggle post signatures on a channel
+  - `telegram-toggle-anti-spam` — toggle native anti-spam in a supergroup (`ban_users` admin)
+  - `telegram-toggle-forum-mode` — enable/disable forum mode on a supergroup (disable requires `confirm: true` — destructive, removes all topics)
+  - `telegram-approve-join-request` — approve or reject a single chat join request
+  - `telegram-toggle-prehistory-hidden` — show/hide pre-history for new supergroup members
+  - `telegram-set-chat-reactions` — set allowed reactions on a chat (`all` / `some` / `none`)
+  - `telegram-get-broadcast-stats` — channel stats overview (Premium admin may be required; pass `includeGraphs: true` for raw series)
+  - `telegram-get-megagroup-stats` — supergroup stats overview (rate-limited by Telegram to ~1 req/30 min per channel)
+- **Phase 3 — Inline Bots, Buttons, Real-Time Updates (7 tools)**
+  - `telegram-inline-query` — query an inline bot in a chat context (queryId TTL ≈ 1 min)
+  - `telegram-inline-query-send` — send an inline bot result by queryId + result id
+  - `telegram-press-button` — press a callback button on a message by row/col or raw data
+  - `telegram-get-message-buttons` — list a message's reply-markup buttons with indices and types
+  - `telegram-get-state` — initialize a polling cursor (`pts`, `qts`, `date`, `seq`)
+  - `telegram-get-updates` — fetch global updates since a known cursor via `updates.GetDifference`; returns `{newMessages, deletedMessageIds, otherUpdates, state, isFinal}` and surfaces `DifferenceTooLong` as a history-fallback hint
+  - `telegram-get-channel-updates` — per-channel polling via `updates.GetChannelDifference`
+  - Cursors are client-owned (stateless server) — the agent stores `{pts, qts, date}` between calls
+- **Phase 4 ship — Stories, Boosts, Business (8 tools)**
+  - `telegram-get-all-stories` — list stories across peers with pagination state
+  - `telegram-get-peer-stories` — list stories posted by one peer (compact, media refs only)
+  - `telegram-get-stories-by-id` — fetch specific story items by id
+  - `telegram-get-story-views` — list views on your own stories (Premium for full stats)
+  - `telegram-get-my-boosts` — list boost slots assigned by your account
+  - `telegram-get-boosts-status` — boost status for a channel/supergroup
+  - `telegram-get-boosts-list` — list boosters for a channel (admin)
+  - `telegram-get-business-chat-links` — list your Telegram Business chat links
+- **Phase 4 opt-in (env-gated, 6 tools)** — registered only when the corresponding flag is set:
+  - `MCP_TELEGRAM_ENABLE_GROUP_CALLS=1` → `telegram-get-group-call`, `telegram-get-group-call-participants`
+  - `MCP_TELEGRAM_ENABLE_STARS=1` → `telegram-get-stars-status`, `telegram-get-stars-transactions`
+  - `MCP_TELEGRAM_ENABLE_QUICK_REPLIES=1` → `telegram-get-quick-replies`, `telegram-get-quick-reply-messages`
+
+## [1.25.0] - 2026-04-20
+
+### Added
+- **Scheduled messages** — `telegram-get-scheduled`, `telegram-delete-scheduled`
+- **Threads & replies** — `telegram-get-replies` for channel post comments
+- **Message links** — `telegram-get-message-link` returns public t.me URL for a message
+- **Mentions & unread reactions** — `telegram-get-unread-mentions`, `telegram-get-unread-reactions`
+- **Translate** — `telegram-translate-message` (requires Telegram Premium)
+- **Typing indicator** — `telegram-send-typing` with configurable action
+- **Dialog management** — `telegram-archive-chat`, `telegram-pin-chat`, `telegram-mark-dialog-unread`
+- **Drafts** — `telegram-save-draft`, `telegram-get-drafts`, `telegram-clear-drafts`
+- **Saved Messages dialogs** — `telegram-get-saved-dialogs` for the new per-peer Saved Messages folders
+- **Admin log** — `telegram-get-admin-log` for channel/supergroup moderation history
+- **Reactions catalog** — `telegram-set-default-reaction`, `telegram-get-top-reactions`, `telegram-get-recent-reactions`
+- **Chat permissions** — `telegram-set-chat-permissions` for default banned rights
+- **Slow mode** — `telegram-set-slow-mode` for supergroups
+- **Forum topics CRUD** — `telegram-create-topic`, `telegram-edit-topic`, `telegram-delete-topic`
+- **Web page preview** — `telegram-get-web-preview` to inspect link previews before sending
+
+### Fixed
+- `telegram-set-chat-permissions` now merges with the chat's current `defaultBannedRights` — omitted flags keep their current state instead of being silently cleared
+- `telegram-clear-drafts` requires `chatId` (single-chat) or `confirmAllChats: true` to wipe drafts account-wide, preventing accidental loss of all drafts in one call
+- `telegram-get-unread-mentions` and `telegram-get-unread-reactions` are now annotated as `WRITE` — they mark the listed items as read on the server
+- `telegram-translate-message` is now annotated as `WRITE` (consumes Premium translate quota); `toLang` is validated against an ISO-639 / locale pattern and `messageIds` is capped at 1–100 positive integers
+- `telegram-delete-scheduled` caps `messageIds` at 1–100 positive integers
+- `telegram-set-default-reaction` validates `emoji` length (1–8 characters)
+- `telegram-get-web-preview` rejects non-`http(s)` URLs, preventing use as an SSRF proxy
+- `telegram-send-typing` throttles non-`cancel` actions to once per 10 seconds per chat
+- `telegram-get-saved-dialogs` no longer returns a hard-coded `unreadCount: 0`
+- `telegram-create-topic` now reads the new topic ID from `UpdateNewChannelMessage` (authoritative) and fails loudly if neither source is available
+- `telegram-save-draft` drops `replyTo` when the draft text is empty, avoiding `MESSAGE_EMPTY` errors when clearing drafts
+- Removed unused `chatMap` build in `getAdminLog`
 
 ## [1.24.1] - 2026-04-20
 

package/README.md

@@ -18,7 +18,7 @@ An MCP (Model Context Protocol) server that connects AI assistants like Claude t
 
 ## Features
 
-- **59 tools** -- the most comprehensive Telegram MCP server available
+- **Comprehensive tool coverage** -- the most full-featured Telegram MCP server available (80+ tools)
 - **MTProto protocol** -- direct Telegram API access, not the limited Bot API
 - **Userbot** -- operates as your personal account, not a bot
 - **Full-featured** -- messaging, reactions, polls, scheduled messages, stickers, media, contacts, and more
@@ -26,6 +26,12 @@ An MCP (Model Context Protocol) server that connects AI assistants like Claude t
 - **Stickers** -- search sticker sets, browse installed/recent stickers, send stickers to any chat
 - **Account management** -- update profile, manage privacy settings, sessions, auto-delete timers
 - **Global search** -- search messages across all chats at once
+- **Real-time polling** -- fetch updates via stateless cursors; agent owns `{pts, qts, date}` state
+- **Inline bots & buttons** -- query inline bots, send results, press callback buttons
+- **Stories** -- read stories from peers, get story view stats
+- **Admin controls** -- toggle channel signatures, anti-spam, forum mode, prehistory; approve join requests
+- **Stats** -- channel and supergroup analytics (GetBroadcastStats / GetMegagroupStats)
+- **Boosts & Business** -- boost status, boosters list, Telegram Business chat links
 - **QR code login** -- authenticate by scanning a QR code in the Telegram app
 - **Session persistence** -- login once, stay connected across restarts
 - **Human-readable output** -- sender names are resolved, not just numeric IDs
@@ -304,21 +310,23 @@ const telegramMcp = new MCPClient({
 });
 ```
 
-## Tools (59)
+## Tools
 
 All tools are auto-discoverable via MCP — your AI client will see the full list with parameters and descriptions when connected.
 
 | Category | Tools |
 |----------|-------|
 | **Auth** | `telegram-status`, `telegram-login` |
-| **Messaging** | `telegram-send-message`, `telegram-edit-message`, `telegram-delete-message`, `telegram-forward-message`, `telegram-send-scheduled` |
-| **Reading** | `telegram-list-chats`, `telegram-read-messages`, `telegram-search-messages`, `telegram-search-global`, `telegram-search-chats`, `telegram-get-unread`, `telegram-mark-as-read` |
-| **Forum Topics** | `telegram-list-topics`, `telegram-read-topic-messages` |
+| **Messaging** | `telegram-send-message`, `telegram-edit-message`, `telegram-delete-message`, `telegram-forward-message`, `telegram-send-scheduled`, `telegram-send-typing`, `telegram-translate-message`, `telegram-get-message-link` |
+| **Scheduled** | `telegram-get-scheduled`, `telegram-delete-scheduled` |
+| **Reading** | `telegram-list-chats`, `telegram-read-messages`, `telegram-search-messages`, `telegram-search-global`, `telegram-search-chats`, `telegram-get-unread`, `telegram-mark-as-read`, `telegram-get-replies`, `telegram-get-unread-mentions`, `telegram-get-unread-reactions`, `telegram-get-saved-dialogs` |
+| **Drafts** | `telegram-save-draft`, `telegram-get-drafts`, `telegram-clear-drafts` |
+| **Forum Topics** | `telegram-list-topics`, `telegram-read-topic-messages`, `telegram-create-topic`, `telegram-edit-topic`, `telegram-delete-topic` |
 | **Polls** | `telegram-create-poll` |
-| **Reactions** | `telegram-send-reaction`, `telegram-get-reactions` |
+| **Reactions** | `telegram-send-reaction`, `telegram-get-reactions`, `telegram-set-default-reaction`, `telegram-get-top-reactions`, `telegram-get-recent-reactions` |
 | **Stickers** | `telegram-send-sticker`, `telegram-get-installed-stickers`, `telegram-get-recent-stickers`, `telegram-get-sticker-set`, `telegram-search-sticker-sets` |
-| **Media** | `telegram-send-file`, `telegram-download-media`, `telegram-get-profile-photo` |
-| **Groups** | `telegram-create-group`, `telegram-edit-group`, `telegram-invite-to-group`, `telegram-join-chat`, `telegram-leave-group`, `telegram-kick-user`, `telegram-ban-user`, `telegram-unban-user`, `telegram-set-admin`, `telegram-remove-admin`, `telegram-get-my-role` |
+| **Media** | `telegram-send-file`, `telegram-download-media`, `telegram-get-profile-photo`, `telegram-get-web-preview` |
+| **Groups** | `telegram-create-group`, `telegram-edit-group`, `telegram-invite-to-group`, `telegram-join-chat`, `telegram-leave-group`, `telegram-kick-user`, `telegram-ban-user`, `telegram-unban-user`, `telegram-set-admin`, `telegram-remove-admin`, `telegram-get-my-role`, `telegram-set-chat-permissions`, `telegram-set-slow-mode`, `telegram-get-admin-log` |
 | **Chat Info** | `telegram-get-chat-info`, `telegram-get-chat-members`, `telegram-get-chat-folders` |
 | **Invite Links** | `telegram-create-invite-link`, `telegram-get-invite-links`, `telegram-revoke-invite-link` |
 | **Contacts** | `telegram-get-contacts`, `telegram-add-contact`, `telegram-get-contact-requests` |
@@ -326,10 +334,29 @@ All tools are auto-discoverable via MCP — your AI client will see the full lis
 | **Profiles** | `telegram-get-profile`, `telegram-update-profile` |
 | **Account** | `telegram-get-sessions`, `telegram-terminate-session`, `telegram-set-privacy`, `telegram-set-auto-delete` |
 | **Pinning** | `telegram-pin-message`, `telegram-unpin-message` |
-| **Chat Settings** | `telegram-mute-chat` |
+| **Chat Settings** | `telegram-mute-chat`, `telegram-archive-chat`, `telegram-pin-chat`, `telegram-mark-dialog-unread` |
+| **Admin Toggles** | `telegram-toggle-channel-signatures`, `telegram-toggle-anti-spam`, `telegram-toggle-forum-mode`, `telegram-toggle-prehistory-hidden`, `telegram-set-chat-reactions`, `telegram-approve-join-request` |
+| **Stats** | `telegram-get-broadcast-stats`, `telegram-get-megagroup-stats` |
+| **Inline Bots & Buttons** | `telegram-inline-query`, `telegram-inline-query-send`, `telegram-press-button`, `telegram-get-message-buttons` |
+| **Real-Time Polling** | `telegram-get-state`, `telegram-get-updates`, `telegram-get-channel-updates` |
+| **Stories** | `telegram-get-all-stories`, `telegram-get-peer-stories`, `telegram-get-stories-by-id`, `telegram-get-story-views` |
+| **Boosts & Business** | `telegram-get-my-boosts`, `telegram-get-boosts-status`, `telegram-get-boosts-list`, `telegram-get-business-chat-links` |
+| **Opt-in (env-gated)** | `telegram-get-group-call`, `telegram-get-group-call-participants` (requires `MCP_TELEGRAM_ENABLE_GROUP_CALLS=1`), `telegram-get-stars-status`, `telegram-get-stars-transactions` (requires `MCP_TELEGRAM_ENABLE_STARS=1`), `telegram-get-quick-replies`, `telegram-get-quick-reply-messages` (requires `MCP_TELEGRAM_ENABLE_QUICK_REPLIES=1`) |
 
 > **Tip**: Ask your AI assistant *"What Telegram tools are available?"* to get the full list with parameters and descriptions.
 
+## Optional Features
+
+Some tools are disabled by default and must be opted in via environment variables:
+
+| Variable | Value | Tools enabled |
+|----------|-------|---------------|
+| `MCP_TELEGRAM_ENABLE_GROUP_CALLS` | `1` | `telegram-get-group-call`, `telegram-get-group-call-participants` |
+| `MCP_TELEGRAM_ENABLE_STARS` | `1` | `telegram-get-stars-status`, `telegram-get-stars-transactions` |
+| `MCP_TELEGRAM_ENABLE_QUICK_REPLIES` | `1` | `telegram-get-quick-replies`, `telegram-get-quick-reply-messages` |
+
+Add these to your `.env` file or MCP client config to enable them.
+
 ## Development
 
 ```bash
@@ -351,14 +378,19 @@ src/
   qr-login-cli.ts     -- CLI utility for QR code login
   tools/              -- Modular tool definitions
     auth.ts           -- Connection & login
-    messages.ts       -- Send, read, search, edit, delete, forward
-    chats.ts          -- Chat listing, group management, admin
+    messages.ts       -- Send, read, search, edit, delete, forward; inline bots; real-time polling
+    chats.ts          -- Chat listing, group management, admin toggles, stats
     contacts.ts       -- Contacts, profiles, moderation
     media.ts          -- Files, photos, downloads
-    reactions.ts      -- Reactions
+    reactions.ts      -- Reactions, set-chat-reactions
     extras.ts         -- Pin, schedule, polls, topics
     stickers.ts       -- Sticker sets, send, search, browse
-    account.ts        -- Sessions, privacy, auto-delete, profile, chat mute/folders, invite links
+    account.ts        -- Sessions, privacy, auto-delete, profile, chat mute/folders, invite links, business chat links
+    boosts.ts         -- Boost status, my boosts, boosters list
+    stories.ts        -- Stories: list all, peer, by-id, view stats
+    group-calls.ts    -- Group call info and participants (opt-in: MCP_TELEGRAM_ENABLE_GROUP_CALLS)
+    stars.ts          -- Stars wallet status and transactions (opt-in: MCP_TELEGRAM_ENABLE_STARS)
+    quick-replies.ts  -- Quick replies and messages (opt-in: MCP_TELEGRAM_ENABLE_QUICK_REPLIES)
     shared.ts         -- Shared utilities
 ```
 

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

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

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

@@ -0,0 +1,41 @@
+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__/approve-join-request.test.d.ts

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

package/dist/__tests__/approve-join-request.test.js

@@ -0,0 +1,107 @@
+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(entity, user, invocations) {
+    const fakeClient = {
+        invoke: async (req) => {
+            invocations.push(req);
+            return undefined;
+        },
+        getEntity: async (_id) => user,
+    };
+    const service = new TelegramService(1, "hash");
+    const internals = service;
+    internals.client = fakeClient;
+    internals.connected = true;
+    internals.resolveChat = async () => entity;
+    return service;
+}
+describe("TelegramService.approveChatJoinRequest", () => {
+    const makeUser = (id) => new Api.User({
+        id: bigInt(id),
+        accessHash: bigInt(42),
+        firstName: "Test",
+    });
+    it("invokes HideChatJoinRequest with approved=true for channel peer", async () => {
+        const megagroup = new Api.Channel({
+            id: bigInt(10000),
+            title: "sg",
+            photo: new Api.ChatPhotoEmpty(),
+            date: 0,
+            accessHash: bigInt(1),
+            megagroup: true,
+        });
+        const invocations = [];
+        const service = makeService(megagroup, makeUser(555), invocations);
+        await service.approveChatJoinRequest("10000", "555", true);
+        const call = invocations.find((r) => r instanceof Api.messages.HideChatJoinRequest);
+        assert.ok(call, "HideChatJoinRequest was invoked");
+        assert.strictEqual(call.approved, true);
+        assert.ok(call.userId instanceof Api.InputUser);
+        assert.strictEqual(call.userId.userId.toString(), "555");
+    });
+    it("invokes HideChatJoinRequest with approved=false (denied)", async () => {
+        const megagroup = new Api.Channel({
+            id: bigInt(20000),
+            title: "sg",
+            photo: new Api.ChatPhotoEmpty(),
+            date: 0,
+            accessHash: bigInt(1),
+            megagroup: true,
+        });
+        const invocations = [];
+        const service = makeService(megagroup, makeUser(777), invocations);
+        await service.approveChatJoinRequest("20000", "777", false);
+        const call = invocations.find((r) => r instanceof Api.messages.HideChatJoinRequest);
+        assert.ok(call);
+        assert.strictEqual(call.approved, false);
+    });
+    it("rejects basic Chat peer (basic groups do not support join requests)", async () => {
+        const chat = new Api.Chat({
+            id: bigInt(33333),
+            title: "basic group",
+            photo: new Api.ChatPhotoEmpty(),
+            participantsCount: 5,
+            date: 0,
+            version: 0,
+        });
+        const invocations = [];
+        const service = makeService(chat, makeUser(888), invocations);
+        await assert.rejects(service.approveChatJoinRequest("33333", "888", true), /supergroups and channels/i);
+        assert.strictEqual(invocations.find((r) => r instanceof Api.messages.HideChatJoinRequest), undefined, "no API call for basic group");
+    });
+    it("rejects when user resolves to non-User entity", async () => {
+        const megagroup = new Api.Channel({
+            id: bigInt(44444),
+            title: "sg",
+            photo: new Api.ChatPhotoEmpty(),
+            date: 0,
+            accessHash: bigInt(1),
+            megagroup: true,
+        });
+        const notAUser = new Api.Chat({
+            id: bigInt(99),
+            title: "not a user",
+            photo: new Api.ChatPhotoEmpty(),
+            participantsCount: 1,
+            date: 0,
+            version: 0,
+        });
+        const invocations = [];
+        const service = makeService(megagroup, notAUser, invocations);
+        await assert.rejects(service.approveChatJoinRequest("44444", "99", true), /not a user/i);
+        assert.strictEqual(invocations.find((r) => r instanceof Api.messages.HideChatJoinRequest), undefined, "no API call when target is not a user");
+    });
+    it("rejects when chat entity is a private user (not a group/channel)", async () => {
+        const userPeer = new Api.User({
+            id: bigInt(1),
+            accessHash: bigInt(1),
+            firstName: "Peer",
+        });
+        const invocations = [];
+        const service = makeService(userPeer, makeUser(123), invocations);
+        await assert.rejects(service.approveChatJoinRequest("1", "123", true), /supergroups and channels/i);
+    });
+});

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

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

package/dist/__tests__/boosts.test.js

@@ -0,0 +1,310 @@
+import assert from "node:assert";
+import { describe, it } from "node:test";
+import bigInt from "big-integer";
+import { Api } from "telegram/tl/index.js";
+import { summarizeBoost, summarizeBoostsList, summarizeBoostsStatus, summarizeMyBoost, summarizeMyBoosts, summarizePrepaidGiveaway, 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("summarizeMyBoost", () => {
+    it("maps slot, peer, dates and cooldown", () => {
+        const boost = new Api.MyBoost({
+            slot: 2,
+            peer: new Api.PeerChannel({ channelId: bigInt(900) }),
+            date: 1710000000,
+            expires: 1720000000,
+            cooldownUntilDate: 1715000000,
+        });
+        const out = summarizeMyBoost(boost);
+        assert.strictEqual(out.slot, 2);
+        assert.deepStrictEqual(out.peer, { kind: "channel", id: "900" });
+        assert.strictEqual(out.date, 1710000000);
+        assert.strictEqual(out.expires, 1720000000);
+        assert.strictEqual(out.cooldownUntilDate, 1715000000);
+    });
+    it("leaves peer undefined when boost is unassigned", () => {
+        const boost = new Api.MyBoost({
+            slot: 1,
+            date: 100,
+            expires: 200,
+        });
+        const out = summarizeMyBoost(boost);
+        assert.strictEqual(out.slot, 1);
+        assert.strictEqual(out.peer, undefined);
+        assert.strictEqual(out.cooldownUntilDate, undefined);
+    });
+});
+describe("summarizeMyBoosts", () => {
+    it("computes count from myBoosts length and maps each entry", () => {
+        const resp = new Api.premium.MyBoosts({
+            myBoosts: [
+                new Api.MyBoost({
+                    slot: 1,
+                    peer: new Api.PeerChannel({ channelId: bigInt(10) }),
+                    date: 1,
+                    expires: 2,
+                }),
+                new Api.MyBoost({ slot: 2, date: 3, expires: 4 }),
+            ],
+            chats: [],
+            users: [],
+        });
+        const out = summarizeMyBoosts(resp);
+        assert.strictEqual(out.count, 2);
+        assert.strictEqual(out.myBoosts.length, 2);
+        assert.deepStrictEqual(out.myBoosts[0].peer, { kind: "channel", id: "10" });
+        assert.strictEqual(out.myBoosts[1].peer, undefined);
+    });
+    it("handles empty boost list", () => {
+        const resp = new Api.premium.MyBoosts({ myBoosts: [], chats: [], users: [] });
+        const out = summarizeMyBoosts(resp);
+        assert.strictEqual(out.count, 0);
+        assert.deepStrictEqual(out.myBoosts, []);
+    });
+});
+describe("summarizePrepaidGiveaway", () => {
+    it("maps premium PrepaidGiveaway (months + quantity)", () => {
+        const g = new Api.PrepaidGiveaway({
+            id: bigInt(123),
+            months: 3,
+            quantity: 10,
+            date: 1700000000,
+        });
+        const out = summarizePrepaidGiveaway(g);
+        assert.deepStrictEqual(out, {
+            kind: "premium",
+            id: "123",
+            months: 3,
+            quantity: 10,
+            date: 1700000000,
+        });
+    });
+    it("maps PrepaidStarsGiveaway with stars + boosts", () => {
+        const g = new Api.PrepaidStarsGiveaway({
+            id: bigInt(456),
+            stars: bigInt(5000),
+            quantity: 20,
+            boosts: 4,
+            date: 1710000000,
+        });
+        const out = summarizePrepaidGiveaway(g);
+        assert.deepStrictEqual(out, {
+            kind: "stars",
+            id: "456",
+            stars: "5000",
+            quantity: 20,
+            boosts: 4,
+            date: 1710000000,
+        });
+    });
+});
+describe("summarizeBoostsStatus", () => {
+    it("maps core counters and boost url", () => {
+        const resp = new Api.premium.BoostsStatus({
+            level: 3,
+            currentLevelBoosts: 10,
+            boosts: 15,
+            giftBoosts: 2,
+            nextLevelBoosts: 25,
+            boostUrl: "https://t.me/boost/test",
+            myBoost: true,
+            myBoostSlots: [1, 2],
+        });
+        const out = summarizeBoostsStatus(resp);
+        assert.strictEqual(out.level, 3);
+        assert.strictEqual(out.boosts, 15);
+        assert.strictEqual(out.currentLevelBoosts, 10);
+        assert.strictEqual(out.nextLevelBoosts, 25);
+        assert.strictEqual(out.giftBoosts, 2);
+        assert.strictEqual(out.boostUrl, "https://t.me/boost/test");
+        assert.strictEqual(out.myBoost, true);
+        assert.deepStrictEqual(out.myBoostSlots, [1, 2]);
+        assert.strictEqual(out.premiumAudience, undefined);
+        assert.strictEqual(out.prepaidGiveaways, undefined);
+    });
+    it("includes premiumAudience and prepaidGiveaways when present", () => {
+        const resp = new Api.premium.BoostsStatus({
+            level: 1,
+            currentLevelBoosts: 0,
+            boosts: 5,
+            boostUrl: "https://t.me/boost/x",
+            premiumAudience: new Api.StatsPercentValue({ part: 2, total: 100 }),
+            prepaidGiveaways: [new Api.PrepaidGiveaway({ id: bigInt(1), months: 6, quantity: 5, date: 111 })],
+        });
+        const out = summarizeBoostsStatus(resp);
+        assert.deepStrictEqual(out.premiumAudience, { part: 2, total: 100 });
+        assert.ok(out.prepaidGiveaways);
+        assert.strictEqual(out.prepaidGiveaways?.length, 1);
+        assert.strictEqual(out.prepaidGiveaways?.[0].kind, "premium");
+        assert.strictEqual(out.prepaidGiveaways?.[0].id, "1");
+    });
+    it("omits empty prepaidGiveaways list", () => {
+        const resp = new Api.premium.BoostsStatus({
+            level: 0,
+            currentLevelBoosts: 0,
+            boosts: 0,
+            boostUrl: "https://t.me/boost/y",
+            prepaidGiveaways: [],
+        });
+        const out = summarizeBoostsStatus(resp);
+        assert.strictEqual(out.prepaidGiveaways, undefined);
+    });
+});
+describe("TelegramService.getBoostsStatus", () => {
+    it("invokes premium.GetBoostsStatus with resolved peer and returns summary", async () => {
+        const invocations = [];
+        const service = makeService(invocations, () => new Api.premium.BoostsStatus({
+            level: 2,
+            currentLevelBoosts: 5,
+            boosts: 7,
+            boostUrl: "https://t.me/boost/foo",
+        }));
+        const internals = service;
+        internals.resolvePeer = async (_id) => new Api.InputPeerChannel({ channelId: bigInt(500), accessHash: bigInt(0) });
+        const out = await service.getBoostsStatus("@foo");
+        const call = invocations.find((r) => r instanceof Api.premium.GetBoostsStatus);
+        assert.ok(call);
+        assert.strictEqual(out.level, 2);
+        assert.strictEqual(out.boosts, 7);
+        assert.strictEqual(out.boostUrl, "https://t.me/boost/foo");
+    });
+});
+describe("summarizeBoost", () => {
+    it("maps core boost fields and converts bigInt ids to strings", () => {
+        const boost = new Api.Boost({
+            id: "boost-1",
+            userId: bigInt(123),
+            date: 1700000000,
+            expires: 1702000000,
+            gift: true,
+            giveaway: false,
+            unclaimed: false,
+            giveawayMsgId: 55,
+            usedGiftSlug: "slug-abc",
+            multiplier: 2,
+            stars: bigInt(500),
+        });
+        const out = summarizeBoost(boost);
+        assert.strictEqual(out.id, "boost-1");
+        assert.strictEqual(out.userId, "123");
+        assert.strictEqual(out.date, 1700000000);
+        assert.strictEqual(out.expires, 1702000000);
+        assert.strictEqual(out.gift, true);
+        assert.strictEqual(out.giveaway, false);
+        assert.strictEqual(out.unclaimed, false);
+        assert.strictEqual(out.giveawayMsgId, 55);
+        assert.strictEqual(out.usedGiftSlug, "slug-abc");
+        assert.strictEqual(out.multiplier, 2);
+        assert.strictEqual(out.stars, "500");
+    });
+    it("leaves optional fields undefined when missing", () => {
+        const boost = new Api.Boost({
+            id: "boost-2",
+            date: 10,
+            expires: 20,
+        });
+        const out = summarizeBoost(boost);
+        assert.strictEqual(out.id, "boost-2");
+        assert.strictEqual(out.userId, undefined);
+        assert.strictEqual(out.stars, undefined);
+        assert.strictEqual(out.multiplier, undefined);
+    });
+});
+describe("summarizeBoostsList", () => {
+    it("maps count, boosts and nextOffset", () => {
+        const resp = new Api.premium.BoostsList({
+            count: 2,
+            boosts: [
+                new Api.Boost({ id: "a", userId: bigInt(1), date: 1, expires: 2 }),
+                new Api.Boost({ id: "b", giveaway: true, date: 3, expires: 4 }),
+            ],
+            nextOffset: "cursor-xyz",
+            users: [],
+        });
+        const out = summarizeBoostsList(resp);
+        assert.strictEqual(out.count, 2);
+        assert.strictEqual(out.boosts.length, 2);
+        assert.strictEqual(out.boosts[0].id, "a");
+        assert.strictEqual(out.boosts[0].userId, "1");
+        assert.strictEqual(out.boosts[1].giveaway, true);
+        assert.strictEqual(out.nextOffset, "cursor-xyz");
+    });
+    it("handles empty boosts and missing nextOffset", () => {
+        const resp = new Api.premium.BoostsList({
+            count: 0,
+            boosts: [],
+            users: [],
+        });
+        const out = summarizeBoostsList(resp);
+        assert.strictEqual(out.count, 0);
+        assert.deepStrictEqual(out.boosts, []);
+        assert.strictEqual(out.nextOffset, undefined);
+    });
+});
+describe("TelegramService.getBoostsList", () => {
+    it("invokes premium.GetBoostsList with defaults (empty offset, limit 50)", async () => {
+        const invocations = [];
+        const service = makeService(invocations, () => new Api.premium.BoostsList({
+            count: 1,
+            boosts: [new Api.Boost({ id: "boost-1", userId: bigInt(7), date: 10, expires: 20 })],
+            nextOffset: "next",
+            users: [],
+        }));
+        const internals = service;
+        internals.resolvePeer = async (_id) => new Api.InputPeerChannel({ channelId: bigInt(500), accessHash: bigInt(0) });
+        const out = await service.getBoostsList("@foo");
+        const call = invocations.find((r) => r instanceof Api.premium.GetBoostsList);
+        assert.ok(call);
+        assert.strictEqual(call.offset, "");
+        assert.strictEqual(call.limit, 50);
+        assert.strictEqual(call.gifts, undefined);
+        assert.strictEqual(out.count, 1);
+        assert.strictEqual(out.boosts[0].id, "boost-1");
+        assert.strictEqual(out.nextOffset, "next");
+    });
+    it("passes gifts/offset/limit through to GetBoostsList", async () => {
+        const invocations = [];
+        const service = makeService(invocations, () => new Api.premium.BoostsList({ count: 0, boosts: [], users: [] }));
+        const internals = service;
+        internals.resolvePeer = async (_id) => new Api.InputPeerChannel({ channelId: bigInt(1), accessHash: bigInt(0) });
+        await service.getBoostsList("@bar", { gifts: true, offset: "cur", limit: 10 });
+        const call = invocations.find((r) => r instanceof Api.premium.GetBoostsList);
+        assert.ok(call);
+        assert.strictEqual(call.gifts, true);
+        assert.strictEqual(call.offset, "cur");
+        assert.strictEqual(call.limit, 10);
+    });
+});
+describe("TelegramService.getMyBoosts", () => {
+    it("invokes premium.GetMyBoosts and returns summary", async () => {
+        const invocations = [];
+        const service = makeService(invocations, () => new Api.premium.MyBoosts({
+            myBoosts: [
+                new Api.MyBoost({
+                    slot: 1,
+                    peer: new Api.PeerChannel({ channelId: bigInt(42) }),
+                    date: 100,
+                    expires: 200,
+                }),
+            ],
+            chats: [],
+            users: [],
+        }));
+        const out = await service.getMyBoosts();
+        const call = invocations.find((r) => r instanceof Api.premium.GetMyBoosts);
+        assert.ok(call);
+        assert.strictEqual(out.count, 1);
+        assert.strictEqual(out.myBoosts[0].slot, 1);
+        assert.deepStrictEqual(out.myBoosts[0].peer, { kind: "channel", id: "42" });
+    });
+});

package/dist/__tests__/broadcast-stats.test.d.ts

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