tg-bot-template

Template repository for Telegram bots that track user-selected activity sources.

This project is intentionally a generic foundation. It keeps the reusable structure from the Polymarket tracker reference project: TypeScript, grammY, SQLite, per-chat subscriptions, admin authorization, runtime error notifications, tests, and systemd deployment assets. It does not include Polymarket API querying, polling, watermarking, or alert semantics.

What this template provides

• A single Node.js process that runs a Telegram bot.
• /start, Subscribe, Unsubscribe, and /admin flows.
• Per-chat subscription ownership.
• Admin access controlled by ADMIN_TELEGRAM_USER_IDS.
• SQLite storage for:
  • subscribers
  • chat_sessions
  • tracked_items
  • subscriptions
• Generic tracked-item resolver that accepts one URL or identifier.
• Fatal startup/runtime/bot-handler error notifications to configured admins.
• Vitest coverage for config, repository behavior, Telegram flows, and utilities.
• systemd deployment template and install script.

Extension point

Replace the default resolver in src/services/tracking.ts when building a real bot.

For a Polymarket tracker, this is where future implementation should add:

• Polymarket profile URL and wallet parsing.
• Profile or wallet resolution.
• Activity polling.
• Activity watermarking.
• Alert formatting and delivery.
• Domain-specific admin reports or telemetry.

Keep those rules out of this template unless they are reusable for every bot created from it.

Environment variables

• TELEGRAM_BOT_TOKEN required.
• ADMIN_TELEGRAM_USER_IDS optional comma-separated Telegram user IDs, for example 12345,67890.
• SQLITE_PATH required.
• SUBSCRIBE_MODE_TTL_MS default 600000.
• TELEGRAM_TIMEOUT_MS default 5000.
• HTTP_TIMEOUT_MS default 15000.
• HTTP_RETRIES default 2.
• DEBUG default 0.

See .env.example.

Local development

pnpm install
cp .env.example .env
# edit .env
pnpm run dev

Run checks:

pnpm run typecheck
pnpm test
pnpm run build

Deployment

Recommended deployment is one long-running systemd service on a Linux host with a persistent SQLite file.

See docs/deployment.md.

This template intentionally does not include an active GitHub Actions deployment workflow. Add CI/CD only after choosing a host, service name, deploy user, and SQLite storage location for a concrete bot.