Ratatosk

Note The project was originally named Deveel Messaging: on the day 25.05.2026 it has been rebranded as Ratatosk, after the mythological squirrel that runs up and down Yggdrasil, the World Tree, carrying messages between the eagle at the top and the dragon at the roots — a fitting symbol for a messaging framework.

Ratatosk is a .NET framework that gives you one consistent way to work with SMS, email, push notifications, and chat channels.

Instead of coding directly against each provider SDK, you build an IMessage, send it through an IChannelConnector, and handle a predictable OperationResult<T>. That keeps your app code stable even if providers change.

The repository currently targets .NET 8, .NET 9, and .NET 10.
Current stable release: v1.0.1 (pre-release packages available from main builds).

Features

• Unified message model — IMessage with fluent MessageBuilder, typed endpoints, and 12 content types (text, HTML, media, binary, JSON, location, template, multipart, button, quick reply, carousel, list picker)
• Schema-driven validation — every connector declares capabilities, parameters, and constraints via IChannelSchema; catch invalid messages before they reach the provider
• Pluggable authentication — API key, token, basic auth, OAuth 2.0, Firebase service account, or custom providers
• DI-first design — AddMessaging() + AddConnector<T>() integration with Microsoft.Extensions.DependencyInjection
• Standardized results — all operations return OperationResult<T> with success/failure semantics
• Schema derivation — derive restricted schemas from a master for feature tiers or environment-specific constraints
• IMessagingClient facade — disposable high-level client with lazy initialization and named channel routing
• Extensible — implement ChannelConnectorBase to add any provider; built-in logging scopes, state management, and error wrapping
• 5 ready-made connectors — Twilio (SMS/WhatsApp), SendGrid (email), Firebase (push), Facebook Messenger, Telegram Bot
• Sender identity management — registry-backed senders with resolution, caching, and per-channel selector strategies

What this project does not do

• Queueing and scheduling
• Durable storage for audit/history
• Workflow orchestration

Those are application-level concerns, so you can choose your own architecture.

Packages

Package	Description	NuGet
Ratatosk.Abstractions	Message model with fluent builder, typed endpoints, 12 content types (including interactive), properties, and batch support. Zero external dependencies.
Ratatosk	DI registration (AddMessaging), IMessagingClient facade (disposable), connector factory, service collection extensions.
Ratatosk.Connector.Abstractions	Connector contracts, schemas, authentication, validation, result types. Reference for custom connector libraries.
Ratatosk.Connectors	Abstract connector base (ChannelConnectorBase) with state management and error wrapping, ChannelSchema builder, schema registry, auth manager, connector builder API.
Ratatosk.Twilio	Twilio SMS, MMS, WhatsApp messaging with status callbacks and template support.
Ratatosk.Sendgrid	SendGrid transactional and bulk email with HTML, multipart, templates, attachments, and event webhook processing.
Ratatosk.Firebase	Firebase Cloud Messaging push for device tokens and topics, with batch sends and dry-run mode.
Ratatosk.Facebook	Facebook Messenger Page-based messaging with text, media, quick replies, and webhook inbound.
Ratatosk.Telegram	Telegram bot messaging with rich text, media, locations, and webhook-based updates.
Ratatosk.Senders	Sender identity infrastructure: ISenderRepository<TSender>, ISenderResolver, cache, per-connector configuration, MessageBuilder.FromSender() extension.
Ratatosk.Senders.InMemory	In-memory IRepository<Sender> for development and testing.
Ratatosk.Senders.EntityFramework	EF Core persistence for the sender identity registry (SenderDbContext, EntitySenderRepository, DbSender).
Ratatosk.Extensions.OpenTelemetry	Convenience extensions for wiring Ratatosk telemetry sources into OpenTelemetry SDK.

Quick example

// Register in DI (Startup / Program)
services.AddMessaging()
    .AddTwilioSmsConnector(options => {
        options.AccountSid = "...";
        options.AuthToken = "...";
    });

// Resolve and send
public class NotificationService(IMessagingClient messaging) 
{
    public async Task SendAsync(CancellationToken ct)
    {
        var message = new MessageBuilder()
            .WithId("order-confirm-123")
            .FromPhone("+15550001111")
            .ToPhone("+15550002222")
            .WithText("Your order has been confirmed!")
            .Build();

        var result = await messaging.SendMessageAsync(message, ct);

        if (!result.IsSuccess())
        {
            throw new InvalidOperationException(
                result.Error?.Message ?? "Failed to send message");
        }
    }
}

Documentation

If you want to go deeper, the documentation provides practical, step-by-step guidance for designing channels, wiring connectors, validating messages, and operating the framework in real projects.

Start from the docs home and follow the path that best matches what you are building: docs/README.md.

Suggested reading paths

• First integration - Start with the framework concepts, then wire a minimal implementation, and finally pick a connector guide for your channel. (Framework overview -> Quickstart -> Connector index)
• Custom connector authoring - Learn schema design first, then implement connector behaviour, then register and resolve channels at runtime. (Channel schema -> Connector implementation -> Installation)
• Validation-first integration - Model endpoints, apply validation rules, and extend validation when channel-specific constraints grow. (Message model -> Message validation -> Channel schema)
• Sender identity management - Set up sender registries, define lifecycle rules, and understand runtime resolution and caching. (Sender management -> Sender resolution -> Sender Manager sample)

Roadmap

The project roadmap is tracked in detail in ROADMAP.md. The summary below highlights the upcoming milestones and the main features planned for each release.

v0.4.0 — Framework Foundations ✓

Strengthens quality gates, release automation, observability, and docs completeness across the existing connector ecosystem.

• Test coverage target (≥ 80%) — Enforce minimum line coverage per library in CI.
• CI/CD pipeline hardening — Automate build, test, compatibility checks, signing, and NuGet publishing from release tags.
• Structured logging improvements — Standardize event IDs, scopes, and LoggerMessage patterns across connectors.
• Documentation completeness — Complete XML API docs and connector guides with consistent coverage.

v0.5.0 — Inbound Messaging ✓

Completes the receive-side model for current connectors to support bidirectional messaging scenarios.

• Twilio inbound messages (SMS/WhatsApp) — Parse inbound payloads into framework messages and endpoints.
• SendGrid inbound parse support — Map multipart inbound emails, content, and attachments into the message model.
• Firebase inbound messages — Support upstream device data messages through the same receive abstractions.

v1.0.0 — First Stable Release ✓

Locks the public API and ships stable package releases with production-ready guarantees.

• API freeze and compatibility enforcement — Prevent breaking API changes without a major version bump.
• NuGet GA release — Publish stable Ratatosk.* packages without prerelease suffixes.
• Interactive content model — Add cross-channel abstractions for buttons, quick replies, carousels, and lists.
• Sender identity model — Provide typed sender identities for phone, email, and bot-based channels.

v1.1.0 — Resilience & Observability

Adds retry/circuit-breaker policies, OpenTelemetry signals, health checks, and timeout controls.

• Retry policies — Polly-based retry and circuit-breaker integrated at the connector base level.
• OpenTelemetry tracing & metrics — ActivitySources, Meters, and histograms per connector.
• Health checks — ASP.NET Core IHealthCheck implementations auto-registered per connector.
• Connector-level timeout configuration — Per-operation timeout via the DI registration API.

v1.2.0 — New SaaS Connectors

Extends the connector ecosystem with additional major cloud messaging providers.

• Slack — Incoming Webhooks and Bot API support with Block Kit content mapping.
• Microsoft Teams — Incoming Webhooks and Bot Framework API with Adaptive Card support.
• WhatsApp Business API — Direct Meta Cloud API connector (text, media, interactive, templates).
• Viber Business — Viber Business Messages API (text, image, rich media, keyboards).
• LINE — LINE Messaging API (text, image, video, audio, Flex Messages).

v1.3.0 — Protocol Connectors

Raw protocol support for teams with direct carrier or Apple developer relationships.

• Protocol connector base classes — Session management, connection lifecycle, reconnection policies.
• SMPP — Direct SMSC connectivity (v3.4 session client, submit_sm/deliver_sm mapping).
• SMTP — Direct email delivery via MailKit (RFC 5321 MIME messages).
• RCS — Rich Communication Services Business Messaging API.
• APNs (direct) — Apple Push Notification HTTP/2 API without Firebase dependency.

v1.4.0 — Content Adaptation & Transcoding

Transcoding layer that converts content between types for multi-channel delivery.

• IContentTranscoder abstraction — Generic content conversion with resolution registry.
• Built-in transcoders — HTML-to-plaintext, HTML-to-Markdown, Markdown-to-GSM-7, and more.
• Channel-aware content fallback — Automatic fallback to best available content type per channel.
• SMS segmentation — GSM-7/UCS-2 segment counting and encoding analysis.
• Character encoding detection — SmsEncodingAnalyzer for pre-send encoding warnings.

v1.5.0 — Address & Number Validation

Validation layer for recipient addresses across all channels.

• E.164 normalization — libphonenumber-based canonical phone number formatting.
• HLR lookup — Optional Home Location Register reachability checks before SMS send.
• Number portability awareness — Ported number routing in the SMPP connector.
• Email address validation — RFC 5321 syntax, MX record, and disposable domain checks.
• IAddressValidator abstraction — Extensible validation chain per connector.

v1.6.0 — Tooling & Instrumentation

Developer and operator tooling for the framework.

• dotnet new connector scaffold — Template package for bootstrapping new connectors.
• ASP.NET Core diagnostic middleware — Runtime connector state, health, and counters endpoint.

v2.0.0 — Conversations

Conversation management as a first-class framework concept.

• IConversation abstraction — Thread of messages with participants, status, and history.
• Conversation state model — State transitions, persistence, in-memory store for testing.
• Conversation correlation — Link inbound replies to originating conversations.
• Multi-channel conversations — Span single conversations across SMS, WhatsApp, email, and more.
• Multi-tenant channel registry — Tenant-aware connector and schema resolution.
• xUnit test helpers — Fake inbound injectors and assertion helpers for conversation flows.

v2.1.0 — Message Templates

Provider-agnostic template model with local and server-side rendering.

• IMessageTemplate abstraction — Named templates with locale, content structure, and variable schema.
• Variable substitution engine — Local rendering with placeholder resolution and type-safe binding.
• Per-connector template rendering — Bridge between framework templates and provider-native systems.
• Template registry — Central store with startup validation and locale-aware resolution.

For milestone-level detail, rationale, and dependencies, see ROADMAP.md.

Versioning and Releases

The project uses a simple GitHub Flow-based release model:

• main is the only long-lived branch
• merges to main produce preview packages with an -alpha.N suffix
• stable packages are produced only from vX.Y.Z tags on commits already in main

Package versions are calculated automatically with GitVersion, so versions should not be edited manually in project files.

Contributing

Contributions are welcome and appreciated.

If you want to contribute:

• Open an issue to discuss bugs, features, or design changes
• Check the existing documentation and package boundaries before proposing API changes
• Submit focused pull requests with tests when behavior changes

The contribution workflow follows GitHub Flow: create a short-lived branch from main, open a pull request, and let CI produce preview packages from main after merge.

For local setup, coding conventions, and the contribution workflow, read CONTRIBUTING.md.

License

This project is released under the MIT License.

You can use it in personal, academic, and commercial projects, including closed-source applications, provided that the license notice is preserved.

See LICENSE for the full text and terms.

Contributors