A sophisticated Telegram bot designed to seamlessly track user reputation (karma) within group chats, now rebuilt with the power and structure of NestJS.

KarmaBot allows group members to easily give or take karma points from each other, fostering community interaction and providing valuable insights. It features comprehensive leaderboards, individual karma tracking, and exposes a robust API perfect for its accompanying Telegram Mini App.

• ✨ KarmaBot: A Modern Telegram Karma Bot ✨
  • 📖 Table of Contents
  • 🚀 For Group Members
    • Key Features
    • Getting Started
  • 👨‍💻 For Developers
    • Architectural Philosophy
    • 💻 Technology Stack
    • 🔧 Installation & Setup
    • 📂 Project Structure
    • 🙌 Contributing
    • 📜 License
    • 👤 Author
    • 🙏 Acknowledgments

• 👍 Give Karma: Reply +1 to a message to award a karma point.
• 👎 Give Hate: Reply -1 to a message to deduct a karma point (hate).
• ⏱️ Cooldown System: A 1-minute cooldown prevents spamming karma.
• 👤 Your Status (/me): Check your own karma score and see how much karma and hate you've given.
• 🏆 Leaderboards:
  • /top: The top 10 users with the most karma.
  • /hate: The top 10 users with the least karma.
  • /mostgivers: See who gives the most karma and hate.
• 📅 Periodic Rankings:
  • /today: Top users by karma received in the last 24 hours.
  • /month: Top users by karma received in the last 30 days.
  • /year: Top users by karma received in the last 365 days.
• 💸 Transfer Karma (/send <amount>): Reply to a user's message to send them some of your own karma points.
• 📜 Karma History:
  • /history: View your own last 10 karma changes.
  • /gethistory <user>: View the history for a specific user.
• 📱 Mini App Integration: Most commands include an "Open Mini App" button for a rich, interactive experience.

1. Add the Bot: An admin must invite KarmaBot to your Telegram group.
2. Give Karma: Simply reply to a user's message with +1 or -1.
3. Use Commands: Type commands like /me, /top, or /help directly in the chat to interact with the bot.

This project is a complete migration of a classic Node.js bot to a modern, scalable, and type-safe NestJS architecture. It serves as a real-world example of applying enterprise-level software design principles to a Telegram bot.

The codebase is structured following SOLID principles to ensure it is maintainable, testable, and easy to extend.

• Modular & Scalable: Built on the NestJS module system, each domain (users, groups, karma) is a self-contained module with its own repository and service, promoting low coupling.
• SOLID Principles:
  • Single Responsibility: Services are decoupled. KarmaService depends on UsersService, not UsersRepository, ensuring that each service is the single source of truth for its domain.
  • Open/Closed: The application is open for extension but closed for modification.
• Command Pattern: Adding a new command is as simple as creating a new CommandHandler class that implements a generic interface (ICommandHandler). The core TelegramService discovers and registers it without needing any modification.
• Type Safety: Fully written in TypeScript, using custom types (TextCommandContext), DTOs, and generics to prevent common runtime errors and ensure a reliable developer experience.

1. Prerequisites:

   • Node.js (v18.x or higher)
   • npm or yarn
   • A running MongoDB instance (local or cloud)
   • A Telegram Bot Token and Username (from @BotFather)

2. Clone the Repository:

   git clone https://github.com/WilliamsMata/karma_bot
   cd karma_bot

3. Install Dependencies:

   npm install

4. Configure Environment Variables: Create a .env file in the project root by copying the example: cp .env.example .env. Then, fill in the required variables:

   # .env
   
   # Your Telegram bot token from @BotFather
   TELEGRAM_BOT_TOKEN=YOUR_TELEGRAM_BOT_TOKEN_HERE
   
   # Your bot's username
   TELEGRAM_BOT_USERNAME=YOUR_TELEGRAM_BOT_USERNAME_HERE
   
   # MongoDB connection string
   MONGODB_CNN=mongodb://localhost:27017/karma_bot
   
   # The port for the API server
   PORT=3000

5. Run the Application:

   • Development Mode (with auto-reload):

     npm run start:dev

   • Production Mode:

     npm run build
     npm run start:prod

src
├── api/                # API controllers and modules (for the Mini App)
│   ├── karma/
│   └── users/
├── karma/              # Core business logic for karma
│   ├── dto/
│   ├── schemas/
│   ├── karma.module.ts
│   ├── karma.repository.ts
│   └── karma.service.ts
├── telegram/           # All Telegram-specific logic
│   ├── commands/       # Command pattern implementation
│   │   ├── handlers/   # Individual classes for each command (/me, /top, etc.)
│   │   └── commands.module.ts
│   ├── handlers/       # Handlers for non-command events (e.g., +1 messages)
│   ├── shared/         # Shared utilities (e.g., keyboard service)
│   ├── telegram.module.ts
│   └── telegram.service.ts # Main service for bot connection and event routing
├── users/              # Business logic for users
├── groups/             # Business logic for groups
├── database/           # Abstract repository and database module setup
├── app.module.ts       # Root module of the application
└── main.ts             # Application entry point

Contributions are highly welcome! If you have ideas for improvements or find a bug, please feel free to:

1. Fork the repository.
2. Create a new branch for your feature or fix.
3. Make your changes and commit them with clear messages.
4. Push to your branch and open a Pull Request.

This project is licensed under the ISC License.

• Williams Mata - GitHub

This project was inspired by the karma bot from hbourgeot.