RepletoryLib.Communication.Abstractions 1.0.0

RepletoryLib.Communication.Abstractions

Communication abstractions and interfaces for email, SMS, WhatsApp, and push notifications with a unified routing facade.

Part of the RepletoryLib ecosystem -- standalone, reusable .NET 10 libraries with zero business logic.

Overview

RepletoryLib.Communication.Abstractions defines the contracts, models, enums, and options shared across all RepletoryLib communication channels. It includes interfaces for email (IEmailService), SMS (ISmsService), WhatsApp (IWhatsAppService), and push notifications (IPushNotificationService), along with a unified ICommunicationService facade that routes messages to the appropriate channel-specific service at runtime.

This package is the foundation of the communication stack. Reference it when you need the interfaces or models without taking a dependency on a specific provider (e.g., AWS SES, AWS SNS, 360Dialog).

Key Features

• IEmailService -- Send single emails, bulk emails, and templated emails
• ISmsService -- Send single and bulk SMS messages
• IWhatsAppService -- Send text, template, and media messages via WhatsApp
• IPushNotificationService -- Send device-targeted and topic-based push notifications
• ICommunicationService -- Unified facade that routes CommunicationMessage to the correct channel
• CommunicationService -- Default routing implementation with optional channel services resolved from DI
• Rich models -- EmailMessage, SmsMessage, WhatsAppTextMessage, PushNotification, and more
• Result types -- SendResult and BulkSendResult with per-message success/failure tracking
• Enums -- CommunicationChannel, PushProvider, WhatsAppMediaType, SmsType

Installation

dotnet add package RepletoryLib.Communication.Abstractions

Or add to your .csproj:

<PackageReference Include="RepletoryLib.Communication.Abstractions" Version="1.0.0" />

Note: RepletoryLib packages are published to a local BaGet feed. See the main repository README for feed configuration.

Dependencies

Quick Start

using RepletoryLib.Communication.Abstractions.Interfaces;
using RepletoryLib.Communication.Abstractions.Models.Common;
using RepletoryLib.Communication.Abstractions.Enums;

public class NotificationService
{
    private readonly ICommunicationService _communication;

    public NotificationService(ICommunicationService communication) => _communication = communication;

    public async Task<SendResult> NotifyUserAsync(string email, string message)
    {
        return await _communication.SendAsync(new CommunicationMessage
        {
            Channel = CommunicationChannel.Email,
            Recipient = email,
            Subject = "Notification",
            Body = message
        });
    }
}

Configuration

CommunicationOptions

Section name: "Communication"

{
  "Communication": {
    "DefaultFromEmail": "noreply@example.com",
    "DefaultFromName": "My Application",
    "DefaultSmsSenderId": "MyApp",
    "BulkBatchSize": 50,
    "RetryCount": 3
  }
}

Usage Examples

Sending via the Unified Facade

using RepletoryLib.Communication.Abstractions.Enums;
using RepletoryLib.Communication.Abstractions.Interfaces;
using RepletoryLib.Communication.Abstractions.Models.Common;

public class AlertService
{
    private readonly ICommunicationService _communication;

    public AlertService(ICommunicationService communication) => _communication = communication;

    // Send an email
    public async Task SendEmailAlertAsync(string email, string subject, string htmlBody)
    {
        var result = await _communication.SendAsync(new CommunicationMessage
        {
            Channel = CommunicationChannel.Email,
            Recipient = email,
            Subject = subject,
            Body = htmlBody
        });

        if (!result.Success)
            throw new InvalidOperationException($"Email failed: {result.Error}");
    }

    // Send an SMS
    public async Task SendSmsAlertAsync(string phoneNumber, string message)
    {
        var result = await _communication.SendAsync(new CommunicationMessage
        {
            Channel = CommunicationChannel.Sms,
            Recipient = phoneNumber,
            Body = message
        });
    }

    // Send a WhatsApp message
    public async Task SendWhatsAppAlertAsync(string phoneNumber, string message)
    {
        var result = await _communication.SendAsync(new CommunicationMessage
        {
            Channel = CommunicationChannel.WhatsApp,
            Recipient = phoneNumber,
            Body = message
        });
    }

    // Send a push notification
    public async Task SendPushAlertAsync(string deviceToken, string title, string body)
    {
        var result = await _communication.SendAsync(new CommunicationMessage
        {
            Channel = CommunicationChannel.Push,
            Recipient = deviceToken,
            Subject = title,
            Body = body,
            Metadata = new Dictionary<string, string> { ["action"] = "open_alerts" }
        });
    }
}

Bulk Send Across Multiple Channels

using RepletoryLib.Communication.Abstractions.Enums;
using RepletoryLib.Communication.Abstractions.Interfaces;
using RepletoryLib.Communication.Abstractions.Models.Common;

public class BroadcastService
{
    private readonly ICommunicationService _communication;

    public BroadcastService(ICommunicationService communication) => _communication = communication;

    public async Task BroadcastAsync(
        string subject,
        string body,
        IEnumerable<(CommunicationChannel Channel, string Recipient)> targets)
    {
        var messages = targets.Select(t => new CommunicationMessage
        {
            Channel = t.Channel,
            Recipient = t.Recipient,
            Subject = subject,
            Body = body
        });

        var result = await _communication.SendBulkAsync(messages);

        Console.WriteLine($"Sent: {result.SuccessCount}, Failed: {result.FailureCount}");
    }
}

Using Channel-Specific Services Directly

using RepletoryLib.Communication.Abstractions.Interfaces;
using RepletoryLib.Communication.Abstractions.Models.Email;

public class WelcomeEmailService
{
    private readonly IEmailService _emailService;

    public WelcomeEmailService(IEmailService emailService) => _emailService = emailService;

    public async Task SendWelcomeAsync(string email, string name)
    {
        var result = await _emailService.SendAsync(new EmailMessage
        {
            To = [email],
            Subject = $"Welcome, {name}!",
            HtmlBody = $"<h1>Hello {name}</h1><p>Thanks for joining us.</p>",
            TextBody = $"Hello {name}\n\nThanks for joining us."
        });

        if (!result.Success)
            throw new InvalidOperationException($"Welcome email failed: {result.Error}");
    }

    public async Task SendTemplatedWelcomeAsync(string email, string name)
    {
        var result = await _emailService.SendTemplateAsync(new TemplatedEmailMessage
        {
            To = [email],
            TemplateName = "WelcomeTemplate",
            TemplateData = new Dictionary<string, string>
            {
                ["name"] = name,
                ["year"] = DateTime.UtcNow.Year.ToString()
            }
        });
    }
}

Working with SendResult and BulkSendResult

using RepletoryLib.Communication.Abstractions.Enums;
using RepletoryLib.Communication.Abstractions.Models.Common;

// SendResult factory methods
var success = SendResult.Succeeded(CommunicationChannel.Email, "msg-12345");
var failure = SendResult.Failed(CommunicationChannel.Sms, "Rate limit exceeded");

// Inspect the result
if (success.Success)
    Console.WriteLine($"Message sent: {success.MessageId}");

if (!failure.Success)
    Console.WriteLine($"Send failed on {failure.Channel}: {failure.Error}");

// BulkSendResult aggregation
var bulk = new BulkSendResult
{
    Results = [success, failure]
};

Console.WriteLine($"Total: {bulk.Results.Count}, OK: {bulk.SuccessCount}, Failed: {bulk.FailureCount}");

API Reference

Interfaces

IEmailService

ISmsService

IWhatsAppService

IPushNotificationService

ICommunicationService

Models

EmailMessage

TemplatedEmailMessage

EmailAttachment

SmsMessage

WhatsAppTextMessage

WhatsAppTemplateMessage

WhatsAppMediaMessage

PushNotification

TopicPushNotification

CommunicationMessage

SendResult

BulkSendResult

Enums

CommunicationChannel

PushProvider

WhatsAppMediaType

SmsType

Integration with Other RepletoryLib Packages

Testing

using Moq;
using RepletoryLib.Communication.Abstractions.Enums;
using RepletoryLib.Communication.Abstractions.Interfaces;
using RepletoryLib.Communication.Abstractions.Models.Common;
using RepletoryLib.Communication.Abstractions.Models.Email;
using RepletoryLib.Communication.Abstractions.Services;

[Fact]
public async Task CommunicationService_routes_email_to_email_service()
{
    var mockEmail = new Mock<IEmailService>();
    mockEmail
        .Setup(e => e.SendAsync(It.IsAny<EmailMessage>(), It.IsAny<CancellationToken>()))
        .ReturnsAsync(SendResult.Succeeded(CommunicationChannel.Email, "msg-001"));

    var service = new CommunicationService(emailService: mockEmail.Object);

    var result = await service.SendAsync(new CommunicationMessage
    {
        Channel = CommunicationChannel.Email,
        Recipient = "user@example.com",
        Subject = "Test",
        Body = "<p>Hello</p>"
    });

    result.Success.Should().BeTrue();
    result.MessageId.Should().Be("msg-001");
    result.Channel.Should().Be(CommunicationChannel.Email);

    mockEmail.Verify(e => e.SendAsync(
        It.Is<EmailMessage>(m => m.To.Contains("user@example.com")),
        It.IsAny<CancellationToken>()), Times.Once);
}

[Fact]
public async Task CommunicationService_returns_failure_when_channel_not_registered()
{
    var service = new CommunicationService(); // No services registered

    var result = await service.SendAsync(new CommunicationMessage
    {
        Channel = CommunicationChannel.Sms,
        Recipient = "+27821234567",
        Body = "Hello"
    });

    result.Success.Should().BeFalse();
    result.Error.Should().Contain("not registered");
}

Troubleshooting

License

This project is licensed under the MIT License.

Copyright (c) 2024-2026 Repletory.

For complete documentation, infrastructure setup, and configuration reference, see the RepletoryLib main repository.