mirror of https://github.com/Memo-2023/mana-monorepo.git synced 2026-05-17 04:59:41 +02:00

Till-JS f29ef4aa3a feat(infra): add Telegram Stats Bot for ManaCore analytics

Adds a NestJS service that delivers Umami analytics via Telegram:

- Telegram commands: /start, /stats, /today, /week, /realtime, /users
- Scheduled reports: Daily at 9:00, Weekly on Monday at 9:00
- Umami API integration with token management
- User statistics from auth database
- Docker + CI/CD pipeline integration

Bot: @stats_mana_bot

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-01-23 20:39:04 +01:00

3.5 KiB

Raw Blame History

Telegram Stats Bot - Claude Code Guidelines

Overview

Telegram Stats Bot delivers analytics and statistics from Umami (stats.mana.how) via Telegram. It provides both automated scheduled reports and on-demand commands.

Tech Stack

Framework: NestJS 10
Telegram: nestjs-telegraf + Telegraf
Scheduling: @nestjs/schedule
Analytics: Umami API

Commands

# Development
pnpm start:dev        # Start with hot reload

# Build
pnpm build            # Production build

# Type check
pnpm type-check       # Check TypeScript types

Project Structure

services/telegram-stats-bot/
├── src/
│   ├── main.ts               # Application entry point
│   ├── app.module.ts         # Root module
│   ├── health.controller.ts  # Health check endpoint
│   ├── config/
│   │   └── configuration.ts  # Configuration & website IDs
│   ├── bot/
│   │   ├── bot.module.ts
│   │   ├── bot.service.ts    # Send messages to Telegram
│   │   └── bot.update.ts     # Command handlers
│   ├── umami/
│   │   ├── umami.module.ts
│   │   └── umami.service.ts  # Umami API client
│   ├── analytics/
│   │   ├── analytics.module.ts
│   │   ├── analytics.service.ts  # Data aggregation
│   │   └── formatters.ts     # Message formatters
│   ├── users/
│   │   ├── users.module.ts
│   │   └── users.service.ts  # User count from auth DB
│   └── scheduler/
│       ├── scheduler.module.ts
│       └── report.scheduler.ts  # Cron jobs
└── Dockerfile

Telegram Commands

Command	Description
`/start`	Show help
`/stats`	Overview of all apps (last 30 days)
`/today`	Today's statistics
`/week`	This week's statistics
`/realtime`	Active visitors right now
`/users`	Registered user statistics
`/help`	Show available commands

Scheduled Reports

Report	Schedule	Timezone
Daily	09:00	Europe/Berlin
Weekly	Monday 09:00	Europe/Berlin

Environment Variables

# Server
PORT=3300
TZ=Europe/Berlin

# Telegram
TELEGRAM_BOT_TOKEN=xxx
TELEGRAM_CHAT_ID=xxx

# Umami
UMAMI_API_URL=http://umami:3000
UMAMI_USERNAME=admin
UMAMI_PASSWORD=xxx

# Database (optional, for user counts)
DATABASE_URL=postgresql://...

Adding New Website IDs

Edit src/config/configuration.ts:

export const WEBSITE_IDS: Record<string, string> = {
  'new-app-webapp': 'uuid-from-umami',
};

export const DISPLAY_NAMES: Record<string, string> = {
  'new-app-webapp': 'New App',
};

Docker

# Build locally
docker build -f services/telegram-stats-bot/Dockerfile -t telegram-stats-bot .

# Run
docker run -p 3300:3300 \
  -e TELEGRAM_BOT_TOKEN=xxx \
  -e TELEGRAM_CHAT_ID=xxx \
  -e UMAMI_API_URL=http://umami:3000 \
  -e UMAMI_USERNAME=admin \
  -e UMAMI_PASSWORD=xxx \
  telegram-stats-bot

Health Check

curl http://localhost:3300/health

Testing Bot Commands

In Telegram, send commands to your bot:

/start     # Shows help message
/today     # Gets today's stats
/week      # Gets weekly stats
/realtime  # Shows active visitors

Key Files

File	Purpose
`src/config/configuration.ts`	All Umami website IDs
`src/analytics/formatters.ts`	Report formatting
`src/scheduler/report.scheduler.ts`	Cron job definitions
`src/umami/umami.service.ts`	Umami API authentication

3.5 KiB Raw Blame History