IBeam.Communications.Sms.Twilio 2.12.2

IBeam.Communications.Sms.Twilio

IBeam.Communications.Sms.Twilio is reserved for a future Twilio-backed ISmsService provider. The current project is scaffolded only and does not yet contain a production SMS implementation.

When To Use This

Do not use this package for production SMS delivery yet.

Use this project when:

• You are implementing the Twilio provider for IBeam.
• You need a package placeholder to preserve naming and package structure.
• You are reviewing provider boundaries before adding real Twilio delivery code.

For production SMS today, use IBeam.Communications.Sms.AzureCommunications or provide a custom ISmsService implementation.

Current Contents

Intended Architecture Fit

When implemented, this package should follow the same IBeam communications provider pattern:

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

Expected boundaries:

• Domain services call ISmsService.
• This package implements Twilio SMS transport only.
• Controllers do not call Twilio SDKs directly.
• Repositories do not send SMS.
• Business rules, permissions, and audit operation names stay in consuming services.

Intended Public Surface

A future complete implementation should likely include:

Proposed Configuration

This configuration does not exist yet. It is a proposed shape for future implementation:

{
  "IBeam": {
    "Communications": {
      "Sms": {
        "FromPhoneNumber": "+16145551212",
        "Twilio": {
          "AccountSid": "<twilio-account-sid>",
          "AuthToken": "<secret>",
          "MessagingServiceSid": "<optional-messaging-service-sid>",
          "DefaultFromPhoneNumber": "+16145551212"
        }
      }
    }
  }
}

Proposed Usage

This API does not exist yet. It shows the expected provider pattern:

using IBeam.Communications.Abstractions;
using IBeam.Communications.Sms.Twilio;

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

Consuming services should continue to depend on ISmsService:

public sealed class ReminderSmsService
{
    private readonly ISmsService _sms;

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

    public Task SendReminderAsync(string phoneNumber, CancellationToken ct = default)
    {
        var message = new SmsMessage { Body = "Reminder: your appointment is tomorrow." };
        message.To.Add(phoneNumber);

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

Service Operations, Auditing, And Permissions

When Twilio support is implemented, keep audit and permission boundaries in the consuming service method, not in the Twilio transport.

[IBeamOperation("appointments.reminder.send")]
public Task SendReminderAsync(Guid tenantId, Guid appointmentId, CancellationToken ct = default)
    => _operations.ExecuteAsync(
        this,
        token => SendReminderCoreAsync(tenantId, appointmentId, token),
        new ServiceOperationExecutionOptions
        {
            TenantId = tenantId,
            EntityId = appointmentId
        },
        ct);

Data Storage

This package currently creates no stores. A future Twilio provider should also avoid owning application storage.

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

Agents implementing this package should first replace the placeholder with a real ISmsService implementation, add options validation, add DI registration, and add provider tests.

Troubleshooting

Version Notes

• Targets net10.0.
• Current status: scaffold/reserved package, not production-ready.
• Package version is assigned by the repository release workflow.