toptl-grammy

Grammy plugin for TOP.TL — auto-post bot stats and check user votes.

Installation

npm install toptl-grammy toptl grammy

Quick Start

import { Bot, Context } from 'grammy';
import { TopTL } from 'toptl';
import { toptl, TopTLFlavor } from 'toptl-grammy';

type MyContext = Context & TopTLFlavor;

const bot = new Bot<MyContext>('BOT_TOKEN');
const client = new TopTL('YOUR_TOPTL_API_KEY');

// Register the plugin — stats are auto-posted every 30 minutes
bot.use(toptl(client, 'mybot'));

bot.command('start', (ctx) => {
  ctx.reply('Hello!');
});

bot.start();

Stats (unique users, groups, channels) are tracked automatically from incoming updates and posted to TOP.TL in the background.

Vote-Gating

Restrict commands to users who have voted for your bot:

bot.command('premium', async (ctx) => {
  const voted = await ctx.toptl.hasVoted();

  if (!voted) {
    return ctx.reply('Please vote for our bot on https://top.tl/mybot to unlock this command!');
  }

  ctx.reply('Thanks for voting! Here is your premium content.');
});

Check vote status with remaining time:

bot.command('votestatus', async (ctx) => {
  const { voted, timeLeft } = await ctx.toptl.isVoteActive();

  if (voted) {
    const hours = Math.floor(timeLeft / 3600);
    const minutes = Math.floor((timeLeft % 3600) / 60);
    ctx.reply(`Your vote is active! Time remaining: ${hours}h ${minutes}m`);
  } else {
    ctx.reply('You have not voted yet. Vote at https://top.tl/mybot');
  }
});

Options

bot.use(toptl(client, 'mybot', {
  autopost: true,        // Auto-post stats (default: true)
  interval: 1800,        // Post interval in seconds (default: 1800 = 30min)
  onlyOnChange: true,    // Skip posting if stats unchanged (default: true)
  trackGroups: true,     // Track group count (default: true)
  trackChannels: true,   // Track channel count (default: true)
}));

| Option | Type | Default | Description | |---|---|---|---| | autopost | boolean | true | Automatically post stats on an interval | | interval | number | 1800 | Seconds between stat posts | | onlyOnChange | boolean | true | Skip posting when stats have not changed | | trackGroups | boolean | true | Count unique groups from updates | | trackChannels | boolean | true | Count unique channels from updates |

Context Flavor

Use TopTLFlavor to get type-safe access to ctx.toptl:

import { Context } from 'grammy';
import { TopTLFlavor } from 'toptl-grammy';

type MyContext = Context & TopTLFlavor;

ctx.toptl.hasVoted()

Returns Promise<boolean> — whether the current user has an active vote.

ctx.toptl.isVoteActive()

Returns Promise<{ voted: boolean; timeLeft: number }> — vote status and seconds remaining.

Related

• toptl — Core SDK for the TOP.TL API
• TOP.TL — Telegram Bot List

License

MIT - see LICENSE