@overpod/mcp-telegram 1.33.0 → 1.34.0

package/CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.34.0] — 2026-04-24
+
+### Added
+
+**Star Gifts (7 new tools, opt-in `MCP_TELEGRAM_ENABLE_STARS=1`):**
+- **telegram-get-available-star-gifts** — List all available Star Gift catalog items: gift ID, cost in Stars, conversion value, limited-edition availability, and upgrade cost
+- **telegram-get-saved-star-gifts** — List Star Gifts received by a user/chat. Supports pagination (`offset`/`nextOffset`), filter flags (`excludeUnsaved`, `excludeSaved`, `excludeUnlimited`, `excludeLimited`, `excludeUnique`), and `sortByValue`. Returns kind (regular/unique), from-peer, date, and upgrade eligibility
+- **telegram-save-star-gift** — Show or hide a received gift on your profile. For personal gifts pass `msgId`; for chat/channel gifts pass `chatId` + `savedId`. Set `unsave=true` to hide, omit to show
+- **telegram-convert-star-gift** — Convert a received gift into Stars (non-reversible, removes gift from profile). Same addressing as save: `msgId` for personal, `chatId`+`savedId` for chat gifts
+- **telegram-get-stars-topup-options** — List available Stars top-up tiers with star count, currency, price amount (smallest currency units), and extended/standard tier flag
+- **telegram-get-stars-subscriptions** — List active Stars subscriptions for a peer (`me` for self). Returns subscription ID, peer, until date, billing period (seconds), price in Stars, canceled status, and title. Pagination via `offset`
+- **telegram-change-stars-subscription** — Cancel or restore a Stars subscription by ID. `canceled=true` to cancel before next renewal, `canceled=false` to restore
+
 ## [1.33.0] — 2026-04-24
 
 ### Added

package/dist/telegram-client.d.ts

@@ -901,6 +901,75 @@ export declare class TelegramService {
         offset?: string;
         limit?: number;
     }): Promise<StarsStatusSummary>;
+    getAvailableStarGifts(): Promise<Array<{
+        id: string;
+        stars: string;
+        convertStars: string;
+        limited: boolean;
+        availabilityRemains?: number;
+        availabilityTotal?: number;
+        upgradeStars?: string;
+    }>>;
+    getSavedStarGifts(chatId: string, opts?: {
+        limit?: number;
+        offset?: string;
+        excludeUnsaved?: boolean;
+        excludeSaved?: boolean;
+        excludeUnlimited?: boolean;
+        excludeLimited?: boolean;
+        excludeUnique?: boolean;
+        sortByValue?: boolean;
+    }): Promise<{
+        count: number;
+        nextOffset?: string;
+        gifts: Array<{
+            giftId: string;
+            giftKind: "regular" | "unique";
+            giftTitle?: string;
+            stars?: string;
+            convertStars?: string;
+            msgId?: number;
+            savedId?: string;
+            fromPeerId?: string;
+            date: number;
+            unsaved: boolean;
+            canUpgrade: boolean;
+            upgradeStars?: string;
+        }>;
+    }>;
+    saveStarGift(opts: {
+        msgId?: number;
+        chatId?: string;
+        savedId?: string;
+        unsave?: boolean;
+    }): Promise<void>;
+    convertStarGift(opts: {
+        msgId?: number;
+        chatId?: string;
+        savedId?: string;
+    }): Promise<void>;
+    getStarsTopupOptions(): Promise<Array<{
+        stars: string;
+        currency: string;
+        amount: string;
+        extended: boolean;
+    }>>;
+    getStarsSubscriptions(chatId: string, opts?: {
+        offset?: string;
+        missingBalance?: boolean;
+    }): Promise<{
+        subscriptions: Array<{
+            id: string;
+            peerId: string;
+            untilDate: number;
+            periodSeconds: number;
+            priceStars: string;
+            canceled: boolean;
+            title?: string;
+        }>;
+        nextOffset?: string;
+    }>;
+    changeStarsSubscription(chatId: string, subscriptionId: string, canceled: boolean): Promise<void>;
     getQuickReplies(hash?: string): Promise<QuickRepliesSummary>;
     getQuickReplyMessages(shortcutId: number, options?: {
         ids?: number[];

package/dist/telegram-client.js

@@ -4196,6 +4196,152 @@ export class TelegramService {
             return summarizeStarsStatus(response);
         }, `getStarsTransactions ${chatId}`);
     }
+    // ─── Star Gifts (v1.34.0) ──────────────────────────────────────────────────
+    async getAvailableStarGifts() {
+        if (!this.client || !this.connected)
+            throw new Error(NOT_CONNECTED_ERROR);
+        const result = await this.client.invoke(new Api.payments.GetStarGifts({ hash: 0 }));
+        if (result.className === "payments.StarGiftsNotModified")
+            return [];
+        const gifts = result.className === "payments.StarGifts" ? result.gifts : [];
+        return gifts
+            .filter((g) => g instanceof Api.StarGift)
+            .map((g) => ({
+            id: g.id.toString(),
+            stars: g.stars.toString(),
+            convertStars: g.convertStars.toString(),
+            limited: g.limited ?? false,
+            availabilityRemains: g.availabilityRemains,
+            availabilityTotal: g.availabilityTotal,
+            upgradeStars: g.upgradeStars?.toString(),
+        }));
+    }
+    async getSavedStarGifts(chatId, opts = {}) {
+        if (!this.client || !this.connected)
+            throw new Error(NOT_CONNECTED_ERROR);
+        const client = this.client;
+        const peer = await this.resolvePeer(chatId);
+        const resolved = await client.getInputEntity(peer);
+        const result = await client.invoke(new Api.payments.GetSavedStarGifts({
+            peer: resolved,
+            offset: opts.offset ?? "",
+            limit: opts.limit ?? 20,
+            excludeUnsaved: opts.excludeUnsaved,
+            excludeSaved: opts.excludeSaved,
+            excludeUnlimited: opts.excludeUnlimited,
+            excludeLimited: opts.excludeLimited,
+            excludeUnique: opts.excludeUnique,
+            sortByValue: opts.sortByValue,
+        }));
+        const r = result;
+        return {
+            count: r.count,
+            nextOffset: r.nextOffset,
+            gifts: r.gifts.map((sg) => {
+                const gift = sg.gift;
+                if (gift instanceof Api.StarGift) {
+                    return {
+                        giftId: gift.id.toString(),
+                        giftKind: "regular",
+                        stars: gift.stars.toString(),
+                        convertStars: gift.convertStars.toString(),
+                        msgId: sg.msgId ?? undefined,
+                        savedId: sg.savedId?.toString(),
+                        fromPeerId: sg.fromId ? summarizePeer(sg.fromId).id : undefined,
+                        date: sg.date,
+                        unsaved: sg.unsaved ?? false,
+                        canUpgrade: sg.canUpgrade ?? false,
+                        upgradeStars: sg.upgradeStars?.toString(),
+                    };
+                }
+                const u = gift;
+                return {
+                    giftId: u.id.toString(),
+                    giftKind: "unique",
+                    giftTitle: u.title,
+                    msgId: sg.msgId ?? undefined,
+                    savedId: sg.savedId?.toString(),
+                    fromPeerId: sg.fromId ? summarizePeer(sg.fromId).id : undefined,
+                    date: sg.date,
+                    unsaved: sg.unsaved ?? false,
+                    canUpgrade: false,
+                };
+            }),
+        };
+    }
+    async saveStarGift(opts) {
+        if (!this.client || !this.connected)
+            throw new Error(NOT_CONNECTED_ERROR);
+        const client = this.client;
+        let stargift;
+        if (opts.msgId !== undefined) {
+            stargift = new Api.InputSavedStarGiftUser({ msgId: opts.msgId });
+        }
+        else if (opts.chatId && opts.savedId) {
+            const peer = await this.resolvePeer(opts.chatId);
+            const inputPeer = await client.getInputEntity(peer);
+            stargift = new Api.InputSavedStarGiftChat({ peer: inputPeer, savedId: bigInt(opts.savedId) });
+        }
+        else {
+            throw new Error("Provide msgId (user gift) or both chatId and savedId (chat gift)");
+        }
+        await client.invoke(new Api.payments.SaveStarGift({ stargift, unsave: opts.unsave }));
+    }
+    async convertStarGift(opts) {
+        if (!this.client || !this.connected)
+            throw new Error(NOT_CONNECTED_ERROR);
+        const client = this.client;
+        let stargift;
+        if (opts.msgId !== undefined) {
+            stargift = new Api.InputSavedStarGiftUser({ msgId: opts.msgId });
+        }
+        else if (opts.chatId && opts.savedId) {
+            const peer = await this.resolvePeer(opts.chatId);
+            const inputPeer = await client.getInputEntity(peer);
+            stargift = new Api.InputSavedStarGiftChat({ peer: inputPeer, savedId: bigInt(opts.savedId) });
+        }
+        else {
+            throw new Error("Provide msgId (user gift) or both chatId and savedId (chat gift)");
+        }
+        await client.invoke(new Api.payments.ConvertStarGift({ stargift }));
+    }
+    async getStarsTopupOptions() {
+        if (!this.client || !this.connected)
+            throw new Error(NOT_CONNECTED_ERROR);
+        const result = await this.client.invoke(new Api.payments.GetStarsTopupOptions());
+        return result.map((o) => ({
+            stars: o.stars.toString(),
+            currency: o.currency,
+            amount: o.amount.toString(),
+            extended: o.extended ?? false,
+        }));
+    }
+    async getStarsSubscriptions(chatId, opts = {}) {
+        if (!this.client || !this.connected)
+            throw new Error(NOT_CONNECTED_ERROR);
+        const peer = await this.resolvePeer(chatId);
+        const result = await this.client.invoke(new Api.payments.GetStarsSubscriptions({ peer, offset: opts.offset ?? "", missingBalance: opts.missingBalance }));
+        const r = result;
+        const subs = r.subscriptions ?? [];
+        return {
+            subscriptions: subs.map((s) => ({
+                id: s.id,
+                peerId: summarizePeer(s.peer).id,
+                untilDate: s.untilDate,
+                periodSeconds: s.pricing.period,
+                priceStars: s.pricing.amount.toString(),
+                canceled: s.canceled ?? false,
+                title: s.title,
+            })),
+            nextOffset: r.subscriptionsNextOffset,
+        };
+    }
+    async changeStarsSubscription(chatId, subscriptionId, canceled) {
+        if (!this.client || !this.connected)
+            throw new Error(NOT_CONNECTED_ERROR);
+        const peer = await this.resolvePeer(chatId);
+        await this.client.invoke(new Api.payments.ChangeStarsSubscription({ peer, subscriptionId, canceled }));
+    }
     // ─── Quick replies ─────────────────────────────────────────────────────────
     async getQuickReplies(hash) {
         if (!this.client || !this.connected)

package/dist/tools/stars.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { fail, ok, READ_ONLY, requireConnection } from "./shared.js";
+import { fail, ok, READ_ONLY, requireConnection, WRITE } from "./shared.js";
 export function isStarsEnabled() {
     return process.env.MCP_TELEGRAM_ENABLE_STARS === "1";
 }
@@ -68,4 +68,181 @@ export function registerStarsTools(server, telegram) {
             return fail(e);
         }
     });
+    server.registerTool("telegram-get-available-star-gifts", {
+        description: "List all available Telegram Star Gifts that can be sent to other users. Returns gift ID, cost in Stars, conversion value, availability (for limited gifts), and upgrade cost. Opt-in: register only when MCP_TELEGRAM_ENABLE_STARS=1. Read-only.",
+        inputSchema: {},
+        annotations: READ_ONLY,
+    }, async () => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const gifts = await telegram.getAvailableStarGifts();
+            return ok(JSON.stringify(gifts));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-saved-star-gifts", {
+        description: "List Star Gifts received by a user or chat. Pass 'me' for your own gifts. Supports pagination via offset/nextOffset and filtering flags. Returns gift ID, kind (regular/unique), stars cost, from-peer, date, and upgrade eligibility. Opt-in: register only when MCP_TELEGRAM_ENABLE_STARS=1. Read-only.",
+        inputSchema: {
+            chatId: z.string().describe("User or chat to fetch received gifts for — 'me' for self"),
+            limit: z.number().int().min(1).max(100).default(20).describe("Max gifts per page"),
+            offset: z.string().optional().describe("Pagination cursor from a prior response's nextOffset"),
+            excludeUnsaved: z.boolean().optional().describe("Skip gifts the recipient chose to hide"),
+            excludeSaved: z.boolean().optional().describe("Skip gifts the recipient chose to show"),
+            excludeUnlimited: z.boolean().optional().describe("Skip unlimited-edition gifts"),
+            excludeLimited: z.boolean().optional().describe("Skip limited-edition gifts"),
+            excludeUnique: z.boolean().optional().describe("Skip unique gifts"),
+            sortByValue: z.boolean().optional().describe("Sort by Star value descending instead of date"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ chatId, limit, offset, excludeUnsaved, excludeSaved, excludeUnlimited, excludeLimited, excludeUnique, sortByValue, }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.getSavedStarGifts(chatId, {
+                limit,
+                offset,
+                excludeUnsaved,
+                excludeSaved,
+                excludeUnlimited,
+                excludeLimited,
+                excludeUnique,
+                sortByValue,
+            });
+            return ok(JSON.stringify(result));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-save-star-gift", {
+        description: "Show or hide a received Star Gift on your profile. Pass msgId for a gift received as a personal message (DM), or chatId + savedId for a gift in a chat/channel. Set unsave=true to hide the gift (remove from profile display). Opt-in: register only when MCP_TELEGRAM_ENABLE_STARS=1.",
+        inputSchema: {
+            msgId: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("Message ID of the gift (from your DMs) — use this for personal gifts"),
+            chatId: z
+                .string()
+                .optional()
+                .describe("Chat/channel ID where the gift was received (required with savedId for chat gifts)"),
+            savedId: z
+                .string()
+                .regex(/^\d+$/, "must be a numeric saved gift ID")
+                .optional()
+                .describe("Saved gift ID (from get-saved-star-gifts) — required with chatId for chat gifts"),
+            unsave: z.boolean().optional().describe("true = hide the gift from profile; false/omit = show it"),
+        },
+        annotations: WRITE,
+    }, async ({ msgId, chatId, savedId, unsave }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        if (msgId === undefined && !(chatId && savedId)) {
+            return fail(new Error("Provide msgId, or both chatId and savedId"));
+        }
+        try {
+            await telegram.saveStarGift({ msgId, chatId, savedId, unsave });
+            return ok(unsave ? "Gift hidden from profile" : "Gift shown on profile");
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-convert-star-gift", {
+        description: "Convert a received Star Gift into Stars (non-reversible). The gift is removed from your profile and its conversion value is added to your Stars balance. Pass msgId for personal gifts or chatId + savedId for chat gifts. Opt-in: register only when MCP_TELEGRAM_ENABLE_STARS=1.",
+        inputSchema: {
+            msgId: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("Message ID of the gift (from your DMs) — for personal gifts"),
+            chatId: z.string().optional().describe("Chat/channel ID (for chat gifts, required with savedId)"),
+            savedId: z
+                .string()
+                .regex(/^\d+$/, "must be a numeric saved gift ID")
+                .optional()
+                .describe("Saved gift ID — for chat gifts, required with chatId"),
+        },
+        annotations: WRITE,
+    }, async ({ msgId, chatId, savedId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        if (msgId === undefined && !(chatId && savedId)) {
+            return fail(new Error("Provide msgId, or both chatId and savedId"));
+        }
+        try {
+            await telegram.convertStarGift({ msgId, chatId, savedId });
+            return ok("Gift converted to Stars");
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-stars-topup-options", {
+        description: "List available Telegram Stars top-up tiers (from payments.GetStarsTopupOptions). Returns each option with star count, currency, price amount (in smallest currency units), and whether it is an extended/premium tier. Opt-in: register only when MCP_TELEGRAM_ENABLE_STARS=1. Read-only.",
+        inputSchema: {},
+        annotations: READ_ONLY,
+    }, async () => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const options = await telegram.getStarsTopupOptions();
+            return ok(JSON.stringify(options));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-stars-subscriptions", {
+        description: "List active Telegram Stars subscriptions for a peer (payments.GetStarsSubscriptions). Pass 'me' for your own account or a bot/channel you own. Returns subscription ID, peer, renewal date, period, price in Stars, and canceled status. Paginate with offset. Opt-in: register only when MCP_TELEGRAM_ENABLE_STARS=1. Read-only.",
+        inputSchema: {
+            chatId: z.string().describe("Peer to query — 'me' for your own subscriptions, or a bot/channel you own"),
+            offset: z.string().optional().describe("Pagination cursor from a prior nextOffset"),
+            missingBalance: z.boolean().optional().describe("If true, return only subscriptions with missing balance"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ chatId, offset, missingBalance }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.getStarsSubscriptions(chatId, { offset, missingBalance });
+            return ok(JSON.stringify(result));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-change-stars-subscription", {
+        description: "Cancel or restore a Telegram Stars subscription (payments.ChangeStarsSubscription). Pass canceled=true to cancel an active subscription before its next renewal, or false to restore a previously canceled one. Opt-in: register only when MCP_TELEGRAM_ENABLE_STARS=1.",
+        inputSchema: {
+            chatId: z
+                .string()
+                .describe("The peer the subscription belongs to — 'me' for your own subscriptions or a bot/channel you own"),
+            subscriptionId: z.string().min(1).describe("Subscription ID (from telegram-get-stars-subscriptions)"),
+            canceled: z.boolean().describe("true = cancel the subscription; false = restore a canceled subscription"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, subscriptionId, canceled }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.changeStarsSubscription(chatId, subscriptionId, canceled);
+            return ok(canceled ? `Subscription ${subscriptionId} canceled` : `Subscription ${subscriptionId} restored`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
 }

package/package.json

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