{"id":48905356,"url":"https://github.com/banghasan/telegram-statistic-bot","last_synced_at":"2026-04-16T19:59:46.546Z","repository":{"id":328964759,"uuid":"1116611618","full_name":"banghasan/telegram-statistic-bot","owner":"banghasan","description":"Telegram Bot Statistic","archived":false,"fork":false,"pushed_at":"2025-12-17T16:35:15.000Z","size":113,"stargazers_count":0,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-16T19:59:02.264Z","etag":null,"topics":["bot","statistics","telegram"],"latest_commit_sha":null,"homepage":"https://t.me/gedebugbot","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/banghasan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-15T06:06:47.000Z","updated_at":"2025-12-17T16:35:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/banghasan/telegram-statistic-bot","commit_stats":null,"previous_names":["banghasan/telegram-statistic-bot"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/banghasan/telegram-statistic-bot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/banghasan%2Ftelegram-statistic-bot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/banghasan%2Ftelegram-statistic-bot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/banghasan%2Ftelegram-statistic-bot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/banghasan%2Ftelegram-statistic-bot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/banghasan","download_url":"https://codeload.github.com/banghasan/telegram-statistic-bot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/banghasan%2Ftelegram-statistic-bot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31902123,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-16T18:22:33.417Z","status":"ssl_error","status_checked_at":"2026-04-16T18:21:47.142Z","response_time":69,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bot","statistics","telegram"],"created_at":"2026-04-16T19:59:45.859Z","updated_at":"2026-04-16T19:59:46.538Z","avatar_url":"https://github.com/banghasan.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Telegram Group Stats Bot\n\nA comprehensive Telegram bot that tracks user activity in groups and displays\ndetailed statistics through a dynamic Web App. Built with\n[Bun](https://bun.sh/), [GramIO](https://gram.io/), [Hono](https://hono.dev/),\n[Drizzle ORM](https://orm.drizzle.team/), and [MariaDB](https://mariadb.org/).\n\n## Features\n\n- **Robust Statistics Tracking**: Monitors messages, word counts, stickers, and\n  media usage per user and group.\n- **MariaDB Backend**: Scalable and reliable data storage using MariaDB.\n- **Dynamic Web App**:\n  - **User Stats**: View your personal activity statistics.\n  - **Admin Dashboard**: (Admin/Owner only) View top groups and top users\n    leaderboards with pagination.\n  - Built with **Alpine.js** and **Tailwind-like** CSS for a responsive, modern\n    UI.\n- **Flexible Deployment**: Supports both `polling` and `webhook` modes.\n- **Secure**: Web app data is verified using HMAC signatures from Telegram.\n\n## Project Structure\n\n```\n.\n├── src/\n│   ├── bot.ts            # Main entry point (Bot + Web Server)\n│   ├── config.ts         # Configuration loader (Zod)\n│   ├── db/               # Database logic (Drizzle ORM)\n│   │   ├── index.ts      # DB connection\n│   │   └── schema.ts     # MariaDB tables (users, groups, etc.)\n│   ├── services/         # Business logic\n│   │   └── stats.service.ts # Core stats processing\n│   ├── commands/         # Bot commands (/stats, etc.)\n│   ├── web/              # Web application backend (Hono)\n│   │   ├── index.ts      # Web server setup\n│   │   └── routes/       # API endpoints\n│   └── webapp/           # Frontend (Alpine.js)\n│       ├── index.html\n│       ├── style.css\n│       └── script.js\n├── config.yml            # Main configuration file\n├── package.json\n└── README.md\n```\n\n## Prerequisites\n\n- **Bun** runtime installed.\n- **MariaDB** server running and accessible.\n- A **Telegram Bot Token**.\n\n## Setup Guide\n\n### 1. Clone \u0026 Install\n\n```bash\ngit clone \u003crepository-url\u003e\ncd \u003crepository-directory\u003e\nbun install\n```\n\n### 2. Configure Database \u0026 Bot\n\nCopy the example config:\n\n```bash\ncp config.example.yml config.yml\n```\n\nEdit `config.yml`:\n\n```yaml\n# General Bot Configuration\ntimezone: \"Asia/Jakarta\"\n\n# The time in seconds to wait before deleting the /stats message in groups.\n# Set to 0 to disable.\ndelete_message_delay: 60\n\n# Telegram Bot Configuration\nbot:\n  # Your Telegram bot token from @BotFather\n  token: \"YOUR_BOT_TOKEN\"\n\n  # The mode to run the bot in. Can be 'polling' or 'webhook'.\n  mode: \"polling\"\n\n  # Settings for webhook mode\n  webhook:\n    # The public URL for your webhook (e.g., https://your-domain.com/bot)\n    # This should point to the server host and port defined below.\n    url: \"https://example.com/bot\"\n\n# Mini Web App Configuration\nwebapp:\n  # The public URL of your Mini Web App\n  # This is the URL that will be opened from the /stats command\n  url: \"YOUR_WEB_APP_URL\"\n\n# Server configuration for the Web App and/or Webhook\nserver:\n  host: \"localhost\"\n  port: 8101\n\n# Database configuration\ndatabase:\n  # Connection details for MariaDB\n  host: \"localhost\"\n  port: 3306\n  username: \"root\"\n  password: \"password\"\n  database: \"telegram_stats\"\n\n# User IDs for access control\nowner: 123456789\nadmins:\n  - 987654321\n  - 112233445\n\n```\n\n### 3. Database Migration\n\nThe bot uses Drizzle ORM. You may need to push the schema to your MariaDB\ninstance:\n\n```bash\n# If you have drizzle-kit configured in package.json\nbun run db:push\n# Or ensure the bot creates tables on startup if configured (currently handled via code or manual push)\n```\n\n_Note: The current setup assumes the database exists. Tables are defined in\n`src/db/schema.ts`._\n\n### 4. Run the Bot\n\n```bash\nbun start\n# or for development\nbun run dev\n```\n\n## Usage\n\n1. **Add to Group**: Add the bot to your group and promote it to Admin\n   (optional, but recommended for full access).\n2. **Track Activity**: The bot automatically records activity for every message.\n3. **View Stats**:\n   - Send `/stats` in the group or private chat.\n   - Click the **\"Open Web App\"** button.\n   - **Regular Users**: See their own stats.\n   - **Admins/Owner**: Can switch tabs to view **Top Groups** and **Top Users**\n     (filtered for activity in the last 3 months).\n\n## Development\n\n- **Linting**: `bun lint`\n- **Formatting**: `bun format`\n\n## Docker Deployment\n\n### Using Docker Compose\n\n1. Ensure `docker-compose.yml` is present.\n2. Ensure `config.yml` is configured.\n3. Run:\n\n```bash\ndocker-compose up -d\n```\n\n### Database Migration\n\nMigrations are now bundled in the Docker image. To apply them:\n\n```bash\ndocker-compose run --rm migrator\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbanghasan%2Ftelegram-statistic-bot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbanghasan%2Ftelegram-statistic-bot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbanghasan%2Ftelegram-statistic-bot/lists"}