MKT-20: Rewrite getBotUsers for faster bot reachability analytics #28

Merged

backmeupplz merged 2 commits from mkt-20-rewrite-reachability into master

2026-05-13 18:33:33 +00:00

backmeupplz commented

2026-05-13 17:32:26 +00:00

(Migrated from github.com)

Summary

Rewrote getBotUsers for faster, resumable, and more detailed bot reachability analytics.

Changes

Bounded concurrency: 30 parallel Telegram API calls (configurable)
Caching/incremental state: JSON file-based cache with 24h TTL, saves incrementally every 5 batches
Retry/backoff: Exponential backoff + special handling for Telegram 429 rate limits (retry_after)
Resumable progress: Cache survives crashes; only stale entries are re-checked
New reachability metrics: Uses getChat (non-message-sending) to classify chats as reachable/unreachable by type
Split by chat type: direct (private), group, supergroup, channel counts and audience estimates
Unavailable tracking: Unreachable chats counted separately
Legacy API preserved: getBotUsers and getBotUsersForSpeller still return the same total user count
New detailed API: getBotReachability and getBotReachabilityForSpeller return full metrics
New endpoint: /reachability exposes detailed per-bot metrics
Tests: 18 tests covering concurrency limiting, retry behavior, metric aggregation, caching, legacy preservation
TypeScript upgrade: 3.5.3 → 4.9.5 (needed for modern .d.ts parsing with jest)

Test Results

Test Suites: 1 passed, 1 total
Tests:       18 passed, 18 total

API Impact

/count now includes reachability sub-object with detailed metrics
New /reachability endpoint returns just the detailed metrics

## Summary Rewrote `getBotUsers` for faster, resumable, and more detailed bot reachability analytics. ## Changes - **Bounded concurrency**: 30 parallel Telegram API calls (configurable) - **Caching/incremental state**: JSON file-based cache with 24h TTL, saves incrementally every 5 batches - **Retry/backoff**: Exponential backoff + special handling for Telegram 429 rate limits (retry_after) - **Resumable progress**: Cache survives crashes; only stale entries are re-checked - **New reachability metrics**: Uses `getChat` (non-message-sending) to classify chats as reachable/unreachable by type - **Split by chat type**: direct (private), group, supergroup, channel counts and audience estimates - **Unavailable tracking**: Unreachable chats counted separately - **Legacy API preserved**: `getBotUsers` and `getBotUsersForSpeller` still return the same total user count - **New detailed API**: `getBotReachability` and `getBotReachabilityForSpeller` return full metrics - **New endpoint**: `/reachability` exposes detailed per-bot metrics - **Tests**: 18 tests covering concurrency limiting, retry behavior, metric aggregation, caching, legacy preservation - **TypeScript upgrade**: 3.5.3 → 4.9.5 (needed for modern .d.ts parsing with jest) ## Test Results ``` Test Suites: 1 passed, 1 total Tests: 18 passed, 18 total ``` ## API Impact - `/count` now includes `reachability` sub-object with detailed metrics - New `/reachability` endpoint returns just the detailed metrics