Telegrator

A modern reactive framework for Telegram bots in C# with aspect-oriented design, mediator-based dispatching, and flexible architecture.

---

🚀 About Telegrator

Telegrator is a next-generation framework for building Telegram bots in C#, inspired by AOP (Aspect-Oriented Programming) and the mediator pattern. It enables decentralized, easily extensible, and maintainable bot logic without traditional state machines or monolithic handlers.

---

✨ Key Features

• Aspect-oriented approach: Handlers and filters are "aspects" of the bot, easily composable and extendable.
• Decentralized logic: Each handler is an independent module—no more giant switch/case blocks.
• Mediator-based dispatching: All updates are routed through a powerful mediator-dispatcher.
• Flexible filtering: Filters for commands, text, sender, chat, regex, and much more.
• Execution order and priorities: Easily control handler priorities and execution order.
• Thread safety and concurrency control: Limit the number of concurrent handlers, await other updates inside a handler.
• Extensibility via attributes and providers: Easily add your own filters, handlers, and state keepers.
• Minimal boilerplate—maximum declarativity!

---

🧩 Architecture & Approach

• Decentralization: Bot logic is split into independent handlers (aspects), each responsible for its own part.
• Mediator: All Telegram updates go through a mediator, which decides which handlers should process them and in what order.
• Filters: Describe handler trigger conditions in a flexible, declarative way.
• State: Built-in mechanisms for user/chat state without manual state machines.

---

🛠️ Quick Start

1. Installation

# .NET CLI
dotnet add package Telegrator

# NuGet CLI
NuGet\Install-Package Telegrator

2. Minimal Bot Example

using Telegrator.Handlers;
using Telegrator.Annotations;

[MessageHandler]
public class HelloHandler : MessageHandler
{
    public override async Task<Result> Execute(IAbstractHandlerContainer<Message> container, CancellationToken cancellation)
    {
        await Reply("Hello, world!", cancellationToken: cancellation);
        return Result.Ok();
    }
}

// Registration and launch:
var bot = new TelegratorClient("<YOUR_BOT_TOKEN>");
bot.Handlers.AddHandler<HelloHandler>();
bot.StartReceiving();

3. Adding Filtering and Commands

using Telegram.Bot.Types.Enums;
using Telegrator.Handlers;
using Telegrator.Annotations;

[CommandHandler, CommandAllias("start", "hello"), ChatType(ChatType.Private)]
public class StartCommandHandler : CommandHandler
{
    public override async Task<Result> Execute(IAbstractHandlerContainer<Message> container, CancellationToken cancellation)
    {
        await Responce("Welcome!", cancellationToken: cancellation);
        return Result.Ok();
    }
}

// Registration:
bot.Handlers.AddHandler<StartCommandHandler>();

4. State Management Example

using Telegrator.Handlers;
using Telegrator.Annotations;

[CommandHandler, CommandAllias("first"), NumericState(SpecialState.NoState)]
public class StateKeepFirst : CommandHandler
{
    public override async Task<Result> Execute(IAbstractHandlerContainer<Message> container, CancellationToken cancellation)
    {
        container.CreateNumericState();
        container.ForwardNumericState();
        await Reply("first state moved (1)", cancellationToken: cancellation);
        return Result.Ok();
    }
}

// Registration:
bot.Handlers.AddHandler<StateKeepFirst>();

---

🏆 Why Telegrator over state machines?

• No tangled switch/case—logic is split into independent handlers.
• Flexible dispatching—the mediator decides who and when processes an event.
• Simple state management—no need to implement state machines manually.
• Easy scaling—add new handlers without rewriting old ones.
• High code readability and maintainability.

---

📚 Documentation & Examples

• Documentation
• Usage examples (WIP)

---

🤝 Contribution & Feedback

We welcome your questions, suggestions, and pull requests! Open issues or contact us directly.

---

⚡ License

GPLv3