sdk.telegram — Telegram

import type { PluginSDK } from "@teleton-agent/sdk";

export const tools = [
  {
    name: "greet",
    description: "Send a greeting with a photo",
    parameters: { chatId: { type: "string" } },
    async execute({ chatId }: { chatId: string }, sdk: PluginSDK) {
      // Who am I?
      const me = sdk.telegram.getMe();

      // Send a text message with an inline button
      const msgId = await sdk.telegram.sendMessage(chatId, "Hello from the plugin!", {
        inlineKeyboard: [[{ text: "Click me", callback_data: "greet:clicked" }]],
      });

      // Send a photo with caption
      await sdk.telegram.sendPhoto(chatId, "/tmp/welcome.jpg", {
        caption: `Sent by @${me?.username ?? "unknown"}`,
        replyToId: msgId,
      });

      return { success: true, messageId: msgId };
    },
  },
];

sendMessage(
  chatId: string,
  text: string,
  opts?: SendMessageOptions
): Promise<number>

const msgId = await sdk.telegram.sendMessage(chatId, "Choose an option:", {
  replyToId: 12345,
  inlineKeyboard: [
    [
      { text: "Option A", callback_data: "choose:a" },
      { text: "Option B", callback_data: "choose:b" },
    ],
    [{ text: "Cancel", callback_data: "choose:cancel" }],
  ],
});

editMessage(
  chatId: string,
  messageId: number,
  text: string,
  opts?: EditMessageOptions
): Promise<number>

sendDice(
  chatId: string,
  emoticon: string,
  replyToId?: number
): Promise<DiceResult>

sendReaction(
  chatId: string,
  messageId: number,
  emoji: string
): Promise<void>

getMe(): TelegramUser | null

const me = sdk.telegram.getMe();
if (!me) return { success: false, error: "Telegram not connected" };
console.log(`I am @${me.username}, ID: ${me.id}`);

sendPhoto(chatId: string, photo: string | Buffer, opts?: MediaSendOptions): Promise<number>
sendVideo(chatId: string, video: string | Buffer, opts?: MediaSendOptions): Promise<number>
sendVoice(chatId: string, voice: string | Buffer, opts?: MediaSendOptions): Promise<number>
sendFile(chatId: string, file: string | Buffer, opts?: MediaSendOptions & { fileName?: string }): Promise<number>
sendGif(chatId: string, gif: string | Buffer, opts?: MediaSendOptions): Promise<number>
sendSticker(chatId: string, sticker: string | Buffer): Promise<number>
downloadMedia(chatId: string, messageId: number): Promise<Buffer | null>

// Photo with caption and reply
await sdk.telegram.sendPhoto(chatId, "/tmp/chart.png", {
  caption: "Daily price chart",
  replyToId: originalMsgId,
});

// Video with dimensions
await sdk.telegram.sendVideo(chatId, videoBuffer, {
  caption: "Screen recording",
  duration: 30,
  width: 1920,
  height: 1080,
});

// File with custom name
await sdk.telegram.sendFile(chatId, reportBuffer, {
  fileName: "report-2026-03.pdf",
  caption: "Monthly report attached",
});

// Download and re-send media
const media = await sdk.telegram.downloadMedia(chatId, 42);
if (media) {
  await sdk.telegram.sendPhoto(otherChatId, media, {
    caption: "Forwarded image",
  });
}

getMessages(chatId: string, limit?: number): Promise<SimpleMessage[]>
searchMessages(chatId: string, query: string, limit?: number): Promise<SimpleMessage[]>
getReplies(chatId: string, messageId: number, limit?: number): Promise<SimpleMessage[]>
deleteMessage(chatId: string, messageId: number, revoke?: boolean): Promise<void>
forwardMessage(fromChatId: string, toChatId: string, messageId: number): Promise<number | null>

// Search for messages mentioning "invoice"
const results = await sdk.telegram.searchMessages(chatId, "invoice", 10);

// Forward the first match to the admin chat
if (results.length > 0) {
  await sdk.telegram.forwardMessage(chatId, adminChatId, results[0].id);
}

// Get thread replies
const replies = await sdk.telegram.getReplies(chatId, parentMsgId, 20);
console.log(`Thread has ${replies.length} replies`);

scheduleMessage(chatId: string, text: string, scheduleDate: number): Promise<number | null>
getScheduledMessages(chatId: string): Promise<SimpleMessage[]>
deleteScheduledMessage(chatId: string, messageId: number): Promise<void>
sendScheduledNow(chatId: string, messageId: number): Promise<void>

// Schedule a reminder for 1 hour from now
const oneHour = Math.floor(Date.now() / 1000) + 3600;
const scheduledId = await sdk.telegram.scheduleMessage(
  chatId,
  "Reminder: team standup in 5 minutes!",
  oneHour
);

// List all scheduled messages
const pending = await sdk.telegram.getScheduledMessages(chatId);
console.log(`${pending.length} messages scheduled`);

// Send one immediately
if (pending.length > 0) {
  await sdk.telegram.sendScheduledNow(chatId, pending[0].id);
}

// Or cancel one
if (scheduledId) {
  await sdk.telegram.deleteScheduledMessage(chatId, scheduledId);
}

pinMessage(
  chatId: string,
  messageId: number,
  opts?: { silent?: boolean; unpin?: boolean }
): Promise<void>

// Pin silently (no notification to members)
await sdk.telegram.pinMessage(chatId, importantMsgId, { silent: true });

// Unpin
await sdk.telegram.pinMessage(chatId, importantMsgId, { unpin: true });

getChatInfo(chatId: string): Promise<ChatInfo | null>
getUserInfo(userId: number | string): Promise<UserInfo | null>
resolveUsername(username: string): Promise<ResolvedPeer | null>
getParticipants(chatId: string, limit?: number): Promise<UserInfo[]>
getDialogs(limit?: number): Promise<Dialog[]>
getHistory(chatId: string, limit?: number): Promise<SimpleMessage[]>

// Resolve a username to get their ID
const peer = await sdk.telegram.resolveUsername("durov");
if (peer) {
  console.log(`@durov is a ${peer.type} with ID ${peer.id}`);
}

// Get chat info
const chat = await sdk.telegram.getChatInfo(chatId);
if (chat) {
  console.log(`${chat.title} (${chat.type}) — ${chat.membersCount ?? "?"} members`);
}

// List recent dialogs
const dialogs = await sdk.telegram.getDialogs(20);
for (const d of dialogs) {
  console.log(`${d.title} [${d.type}] unread: ${d.unreadCount}`);
}

// Browse history
const history = await sdk.telegram.getHistory(chatId, 30);
console.log(`Last ${history.length} messages fetched`);

createPoll(
  chatId: string,
  question: string,
  answers: string[],
  opts?: PollOptions
): Promise<number | null>

createQuiz(
  chatId: string,
  question: string,
  answers: string[],
  correctIndex: number,
  explanation?: string
): Promise<number | null>

// Anonymous poll with multiple choice
await sdk.telegram.createPoll(chatId, "Favorite blockchain?", [
  "TON", "Ethereum", "Solana", "Bitcoin"
], {
  isAnonymous: true,
  multipleChoice: false,
});

// Quiz with explanation
await sdk.telegram.createQuiz(
  chatId,
  "What is the native token of TON?",
  ["ETH", "TON", "SOL", "BTC"],
  1, // correct index (TON)
  "Toncoin (TON) is the native cryptocurrency of The Open Network."
);

banUser(chatId: string, userId: number | string): Promise<void>
unbanUser(chatId: string, userId: number | string): Promise<void>
muteUser(chatId: string, userId: number | string, untilDate: number): Promise<void>
kickUser(chatId: string, userId: number | string): Promise<void>

// Mute for 1 hour
const oneHourFromNow = Math.floor(Date.now() / 1000) + 3600;
await sdk.telegram.muteUser(chatId, spammerId, oneHourFromNow);

// Kick (can rejoin)
await sdk.telegram.kickUser(chatId, troublemaker);

// Permanent ban
await sdk.telegram.banUser(chatId, spammerId);

// Forgive and unban
await sdk.telegram.unbanUser(chatId, spammerId);

getStarsBalance(): Promise<number>
getStarsTransactions(limit?: number): Promise<StarsTransaction[]>

const balance = await sdk.telegram.getStarsBalance();
console.log(`Stars balance: ${balance}`);

const txs = await sdk.telegram.getStarsTransactions(10);
for (const tx of txs) {
  const direction = tx.amount > 0 ? "received" : "spent";
  console.log(`${direction} ${Math.abs(tx.amount)} stars — ${tx.description ?? "no description"}`);
}

sendGift(
  userId: number | string,
  giftId: string,
  opts?: { message?: string; anonymous?: boolean }
): Promise<void>

getAvailableGifts(): Promise<StarGift[]>
getMyGifts(limit?: number): Promise<ReceivedGift[]>
getResaleGifts(giftId: string, limit?: number): Promise<StarGift[]>
buyResaleGift(giftId: string): Promise<void>

// Browse available gifts
const gifts = await sdk.telegram.getAvailableGifts();
const cheapest = gifts.sort((a, b) => a.starsAmount - b.starsAmount)[0];

// Send the cheapest gift anonymously
await sdk.telegram.sendGift(userId, cheapest.id, {
  message: "A small gift for you!",
  anonymous: true,
});

// Check received gifts
const myGifts = await sdk.telegram.getMyGifts(10);
console.log(`Received ${myGifts.length} gifts`);

// Browse resale market for a specific collection
const resale = await sdk.telegram.getResaleGifts(cheapest.id, 20);
if (resale.length > 0) {
  await sdk.telegram.buyResaleGift(resale[0].id);
}

transferCollectible(msgId: number, toUserId: number | string): Promise<TransferResult>

setCollectiblePrice(msgId: number, price: number): Promise<void>

getCollectibleInfo(slug: string): Promise<CollectibleInfo | null>

getUniqueGift(slug: string): Promise<UniqueGift | null>

getUniqueGiftValue(slug: string): Promise<GiftValue | null>

sendGiftOffer(
  userId: number | string,
  giftSlug: string,
  price: number,
  opts?: GiftOfferOptions
): Promise<void>

// Look up a unique NFT gift
const gift = await sdk.telegram.getUniqueGift("blue-diamond-42");
if (!gift) return { success: false, error: "Gift not found" };

console.log(`${gift.title} #${gift.num} owned by ${gift.owner.name}`);
console.log(`Attributes: ${gift.attributes.map(a => a.name).join(", ")}`);

// Check its market value
const value = await sdk.telegram.getUniqueGiftValue("blue-diamond-42");
if (value) {
  console.log(`Floor: ${value.floorPrice} | Avg: ${value.averagePrice}`);
}

// Send a buy offer (valid for 24h by default)
await sdk.telegram.sendGiftOffer(gift.owner.id!, "blue-diamond-42", 5000);

// Or with custom duration (minimum 6 hours = 21600 seconds)
await sdk.telegram.sendGiftOffer(gift.owner.id!, "blue-diamond-42", 5000, {
  duration: 43200, // 12 hours
});

// Transfer a collectible you own
const myGifts = await sdk.telegram.getMyGifts(50);
const collectible = myGifts.find(g => g.messageId);
if (collectible?.messageId) {
  const result = await sdk.telegram.transferCollectible(collectible.messageId, recipientId);
  console.log(`Transferred to ${result.transferredTo}, paid: ${result.paidTransfer}`);
}

// Set resale price (in Stars)
await sdk.telegram.setCollectiblePrice(collectible!.messageId!, 2500);

// Unlist from resale
await sdk.telegram.setCollectiblePrice(collectible!.messageId!, 0);

// Look up a Fragment collectible (username or phone)
const info = await sdk.telegram.getCollectibleInfo("durov");
if (info) {
  console.log(`@${info.value} purchased on ${info.purchaseDate} for ${info.cryptoAmount} ${info.cryptoCurrency}`);
}

sendStory(
  mediaPath: string,
  opts?: { caption?: string }
): Promise<number | null>

const storyId = await sdk.telegram.sendStory("/tmp/daily-chart.jpg", {
  caption: "Today's market overview",
});
if (storyId) {
  console.log(`Story posted: ${storyId}`);
}

setTyping(chatId: string): Promise<void>
getRawClient(): unknown | null
isAvailable(): boolean

// Always check availability first
if (!sdk.telegram.isAvailable()) {
  return { success: false, error: "Telegram not connected" };
}

// Show typing while processing
await sdk.telegram.setTyping(chatId);

// Use raw client for inline bot results
const client = sdk.telegram.getRawClient();
if (client) {
  const { Api } = require("telegram");
  const results = await (client as any).invoke(
    new Api.messages.GetInlineBotResults({
      bot: "@pic",
      query: "sunset",
      peer: chatId,
      offset: "",
    })
  );
  console.log(`Got ${results.results.length} inline results`);
}

interface SendMessageOptions {
  /** Message ID to reply to */
  replyToId?: number;
  /** Inline keyboard buttons (2D array: rows of buttons) */
  inlineKeyboard?: InlineButton[][];
}

interface EditMessageOptions {
  /** Updated inline keyboard (omit to keep existing) */
  inlineKeyboard?: InlineButton[][];
}

interface InlineButton {
  /** Button label text */
  text: string;
  /** Callback data sent when button is pressed */
  callback_data: string;
}

interface MediaSendOptions {
  /** Media caption text */
  caption?: string;
  /** Message ID to reply to */
  replyToId?: number;
  /** Inline keyboard buttons */
  inlineKeyboard?: InlineButton[][];
  /** Duration in seconds (for video/voice) */
  duration?: number;
  /** Width in pixels (for video) */
  width?: number;
  /** Height in pixels (for video) */
  height?: number;
}

interface PollOptions {
  /** Whether voters are anonymous (default: true) */
  isAnonymous?: boolean;
  /** Allow multiple answers (default: false) */
  multipleChoice?: boolean;
}

interface SimpleMessage {
  /** Message ID */
  id: number;
  /** Message text */
  text: string;
  /** Sender user ID */
  senderId: number;
  /** Sender username */
  senderUsername?: string;
  /** Message timestamp */
  timestamp: Date;
}

interface TelegramUser {
  /** Telegram user ID */
  id: number;
  /** Username without @ (may be undefined) */
  username?: string;
  /** First name */
  firstName?: string;
  /** Whether the user is a bot */
  isBot: boolean;
}

interface ChatInfo {
  /** Chat ID as string */
  id: string;
  /** Chat title (or user's first name for private chats) */
  title: string;
  /** Chat type */
  type: "private" | "group" | "supergroup" | "channel";
  /** Number of members (groups/channels only) */
  membersCount?: number;
  /** Chat username without @ (if public) */
  username?: string;
  /** Chat/channel description/bio */
  description?: string;
}

interface UserInfo {
  /** Telegram user ID */
  id: number;
  /** First name */
  firstName: string;
  /** Last name */
  lastName?: string;
  /** Username without @ */
  username?: string;
  /** Whether the user is a bot */
  isBot: boolean;
}

interface ResolvedPeer {
  /** Entity ID */
  id: number;
  /** Entity type */
  type: "user" | "chat" | "channel";
  /** Username if available */
  username?: string;
  /** Title (for groups/channels) or first name (for users) */
  title?: string;
}

interface DiceResult {
  /** The dice value (1-6 for dice, 1-64 for slots, etc.) */
  value: number;
  /** Message ID of the dice message */
  messageId: number;
}

interface StarGift {
  /** Gift ID */
  id: string;
  /** Cost in Telegram Stars */
  starsAmount: number;
  /** Remaining available (limited gifts) */
  availableAmount?: number;
  /** Total supply (limited gifts) */
  totalAmount?: number;
}

interface ReceivedGift {
  /** Gift ID */
  id: string;
  /** Sender user ID */
  fromId?: number;
  /** Unix timestamp when received */
  date: number;
  /** Stars value */
  starsAmount: number;
  /** Whether saved to profile */
  saved: boolean;
  /** Associated message ID */
  messageId?: number;
}

interface Dialog {
  /** Chat ID */
  id: string | null;
  /** Chat title or name */
  title: string;
  /** Chat type */
  type: "dm" | "group" | "channel";
  /** Number of unread messages */
  unreadCount: number;
  /** Number of unread mentions */
  unreadMentionsCount: number;
  /** Whether the chat is pinned */
  isPinned: boolean;
  /** Whether the chat is archived */
  isArchived: boolean;
  /** Last message date (unix timestamp) */
  lastMessageDate: number | null;
  /** Last message preview (truncated) */
  lastMessage: string | null;
}

interface StarsTransaction {
  /** Transaction ID */
  id: string;
  /** Amount (positive = received, negative = spent) */
  amount: number;
  /** Transaction date (unix timestamp) */
  date: number;
  /** Peer info */
  peer?: string;
  /** Description */
  description?: string;
}

interface TransferResult {
  /** Message ID of the transferred gift */
  msgId: number;
  /** Recipient identifier */
  transferredTo: string;
  /** Whether transfer cost Stars */
  paidTransfer: boolean;
  /** Stars spent (if paid transfer) */
  starsSpent?: string;
}

interface CollectibleInfo {
  /** Collectible type */
  type: "username" | "phone";
  /** The username or phone number */
  value: string;
  /** Purchase date (ISO 8601) */
  purchaseDate: string;
  /** Fiat currency */
  currency: string;
  /** Fiat amount */
  amount?: string;
  /** Crypto currency (e.g. "TON") */
  cryptoCurrency?: string;
  /** Crypto amount */
  cryptoAmount?: string;
  /** Fragment URL */
  url?: string;
}

interface UniqueGift {
  /** Gift ID */
  id: string;
  /** Collection gift ID */
  giftId: string;
  /** URL slug */
  slug: string;
  /** Gift title */
  title: string;
  /** Number in collection */
  num: number;
  /** Owner info */
  owner: {
    id?: string;
    name?: string;
    address?: string;
    username?: string;
  };
  /** TON address of the gift NFT */
  giftAddress?: string;
  /** NFT attributes */
  attributes: Array<{ type: string; name: string; rarityPercent?: number }>;
  /** Availability info */
  availability?: { total: number; remaining: number };
  /** Link to NFT page */
  nftLink: string;
}

interface GiftValue {
  /** NFT slug */
  slug: string;
  /** Initial sale date (ISO 8601) */
  initialSaleDate?: string;
  /** Initial sale price in Stars */
  initialSaleStars?: string;
  /** Last sale date (ISO 8601) */
  lastSaleDate?: string;
  /** Last sale price */
  lastSalePrice?: string;
  /** Floor price */
  floorPrice?: string;
  /** Average price */
  averagePrice?: string;
  /** Number listed */
  listedCount?: number;
  /** Currency */
  currency?: string;
}

interface GiftOfferOptions {
  /** Offer validity in seconds (default: 86400 = 24h, min: 21600 = 6h) */
  duration?: number;
}

interface StartContext {
  /** Telegram bridge for advanced operations */
  bridge: unknown;
  /** Plugin's isolated SQLite database (null if unavailable) */
  db: unknown;
  /** Sanitized application config (no API keys) */
  config: Record<string, unknown>;
  /** Plugin-specific config from config.yaml */
  pluginConfig: Record<string, unknown>;
  /** Prefixed logger */
  log: PluginLogger;
}