toptl 0.1.0

Official Dart SDK for the TOP.TL Telegram directory API — post bot stats, check votes, and manage vote webhooks.

toptl

Official Dart SDK for TOP.TL — post bot stats, check votes, and manage vote webhooks from your Telegram bot.

Install

dependencies:
  toptl: ^0.1.0

Dart >=3.0.0.

Quick start

import 'package:toptl/toptl.dart';

Future<void> main() async {
  final client = TopTL('toptl_xxx');

  // Look up a listing
  final listing = await client.getListing('durov');
  print('${listing.title} — ${listing.voteCount} votes');

  // Post stats for a bot you own
  await client.postStats(
    'mybot',
    memberCount: 5000,
    groupCount: 1200,
    channelCount: 300,
  );

  // Reward voters
  final check = await client.hasVoted('mybot', 123456789);
  if (check.voted) {
    // grant premium …
  }

  client.close();
}

Autoposter

For long-running bots:

final poster = Autoposter(
  client: client,
  username: 'mybot',
  statsCallback: () async => {
    'memberCount': await getUserCount(),
    'groupCount': await getGroupCount(),
  },
  interval: const Duration(minutes: 30),
  onlyOnChange: true,
)..start();

// poster.stop(); on shutdown

Webhooks

await client.setWebhook(
  'mybot',
  'https://mybot.example.com/toptl-vote',
  rewardTitle: '30-day premium',
);

final result = await client.testWebhook('mybot');
print(result.success);

Batch stats

Up to 25 listings per request:

await client.batchPostStats([
  {'username': 'bot1', 'memberCount': 1200},
  {'username': 'bot2', 'memberCount': 5400},
]);

Error handling

Everything throws a subclass of TopTLException:

try {
  await client.postStats('mybot', memberCount: 5000);
} on AuthenticationException {
  // bad token / missing scope
} on NotFoundException {
  // listing doesn't exist
} on RateLimitException {
  // back off and retry
} on ValidationException catch (e) {
  print(e.message); // server payload
}

License

MIT.