idbot-api-gram

API to resolve Telegram usernames to IDs and basic channel info.

Run

• Dev: npm run dev
• Build: npm run build
• Start: npm start (after build)

Server binds to HOST:PORT (defaults 127.0.0.1:3456).

Environment variables:

• API_ID (required)
• API_HASH (required)
• TOKEN1, TOKEN2, ... (at least TOKEN1 required)
• HOST (default 127.0.0.1)
• PORT (default 3456)
• SESSIONS_FILE (default <cwd>/data/session.json)
• USER_CACHE_TTL_MS (default 300000 i.e. 5 minutes)
• MAX_ACTIVE_SESSIONS (default 4)
• REQUEST_TIMEOUT_MS (default 3000 ms)
• ENABLE_TEST_ENDPOINTS (default 0)
• ENABLE_TEST_UI (default 0)

Minimal manual testing

Open the tester UI (served from public/):

• Browser: http://127.0.0.1:3456/
  • Click Ping to check readiness or bans
  • Enter username (with or without @) and click Check
  • Try the provided sample links (e.g., telegram, durov, eth_jobs)

Direct endpoints:

• GET /ping → { status: "ok" } or { status: "banned", retryAfterSeconds } (also sets Retry-After header)
• GET /username/:username → JSON describing user or channel, or an error shape
  • When all sessions are banned: HTTP 429 with { status: "banned", retryAfterSeconds } and Retry-After header

Minimal automated smoke test

Ensure server is running, then:

npm run smoke

Environment overrides (optional):

HOST=127.0.0.1 PORT=3456 npm run smoke

The smoke test accepts HTTP 200 or 429 for resilience; on 429 it validates retry info.

Docker

Build:

docker build -t idbot-api .

Run (local UI disabled by default):

docker run --rm \
  -e API_ID=123456 -e API_HASH=your_api_hash \
  -e TOKEN1=111111111:token_a \
  -e HOST=0.0.0.0 -e PORT=3456 \
  -p 3456:3456 \
  -v $(pwd)/data:/app/data \
  idbot-api

Enable test UI if desired:

docker run --rm -e ENABLE_TEST_UI=1 ... idbot-api

Stress test (real or mock)

Real mode (will hit Telegram via your configured tokens; can trigger real limits):

npm run dev
npm run stress -- --rate=4 --duration=30

Mock mode (no Telegram traffic; simulate bans with dev endpoints):

ENABLE_TEST_ENDPOINTS=1 npm run dev
npm run stress -- --mock --rate=10 --duration=15

Notes:

• --rate is requests per second target (approximate)
• --duration is test length in seconds
• When mock is enabled, the server exposes POST /test/ban-all/:seconds and POST /test/reset-bans