IBeam.Communications 2.6.0

IBeam.Communications

IBeam.Communications is the provider-neutral communications foundation for IBeam. It defines the email, SMS, template, option, validation, and exception contracts that application services use without depending directly on SMTP, SendGrid, Azure Communication Services, Twilio, or another delivery provider.

When To Use This

• You want application services to send email or SMS through stable IBeam interfaces.
• You want to swap communication providers without rewriting business services.
• You need shared message models, default sender options, and validation behavior.
• You want templated email support that can be paired with any IEmailService provider.

What This Package Contains

Architecture Fit

IBeam keeps application code on this path:

API <-- DTO/model object --> Service <-- Entity --> Repository

This package belongs at the abstraction/model layer. Controllers should not call provider SDKs directly. Domain services should decide when a communication should be sent, then call IEmailService, ISmsService, or ITemplatedEmailService.

Provider packages implement the transport boundary. Repositories are not involved unless a consuming service stores its own notification/audit entity.

Quick Start

Register shared communications first, then register one concrete email/SMS provider package.

using IBeam.Communications.Abstractions;
using IBeam.Communications.Email.Smtp;

builder.Services.AddIBeamCommunications(builder.Configuration);
builder.Services.AddIBeamSmtpEmail(builder.Configuration);

Send email from a service:

public sealed class WelcomeMessageService
{
    private readonly IEmailService _email;

    public WelcomeMessageService(IEmailService email)
    {
        _email = email;
    }

    public Task SendWelcomeAsync(string emailAddress, CancellationToken ct = default)
    {
        var message = new EmailMessage
        {
            Subject = "Welcome",
            TextBody = "Your account is ready."
        };
        message.To.Add(emailAddress);

        return _email.SendAsync(message, ct: ct);
    }
}

Send SMS from a service:

public sealed class SmsNotificationService
{
    private readonly ISmsService _sms;

    public SmsNotificationService(ISmsService sms)
    {
        _sms = sms;
    }

    public Task SendCodeAsync(string phoneNumber, string code, CancellationToken ct = default)
    {
        var message = new SmsMessage
        {
            Body = $"Your verification code is {code}."
        };
        message.To.Add(phoneNumber);

        return _sms.SendAsync(message, ct: ct);
    }
}

Configuration

Shared configuration sections:

{
  "IBeam": {
    "Communications": {
      "Email": {
        "FromAddress": "noreply@example.com",
        "FromName": "Example App"
      },
      "Sms": {
        "FromPhoneNumber": "+16145551212",
        "DefaultToUs": true
      }
    },
    "EmailTemplating": {
      "BasePath": "Templates/Email",
      "HtmlExtension": ".html",
      "TextExtension": ".txt"
    }
  }
}

Service Operations, Auditing, And Permissions

This package does not define business service operations directly. The consuming service that decides to send a message should own the audit and permission operation name.

using IBeam.Services.Abstractions;

[IBeamOperation("patients.discharge")]
public Task DischargeAsync(Guid tenantId, Guid patientId, CancellationToken ct = default)
    => _operations.ExecuteAsync(
        this,
        token => DischargeCoreAsync(tenantId, patientId, token),
        new ServiceOperationExecutionOptions
        {
            TenantId = tenantId,
            EntityId = patientId
        },
        ct);

private async Task DischargeCoreAsync(Guid tenantId, Guid patientId, CancellationToken ct)
{
    // Business rules and data changes happen here.
    await _email.SendAsync(BuildDischargeEmail(patientId), ct: ct);
}

Keep communication providers focused on delivery. Do not put patient, billing, identity, or workflow permission rules inside provider implementations.

Data Storage

This package does not create database tables, Azure Table Storage tables, queues, containers, or durable stores. If a consuming app needs message history, notification outbox rows, retries, or delivery receipts, that should be modeled in the consuming service and repository package.

Extension Points

Package Relationships

Extended Examples And Agent Guidance

• Project agent prompt: .agent/prompt.md
• Repository implementation guide: ../.agent/implementation-guide.md
• Consuming API migration prompt: ../IBeam.AI.Enablement/examples/consuming-api-migration-prompt.md
• Builder onboarding prompt: ../IBeam.AI.Enablement/examples/builder-onboarding-prompt.md

Agents should read the project prompt and root implementation guide before changing provider boundaries or adding service operation/audit behavior.

Troubleshooting

Version Notes

• Targets net10.0.
• Packages are versioned by the repository release workflow.
• Provider implementations should remain replaceable behind these abstractions.