Catspeak.Shared.Notification 2.7.1

Catspeak.Shared.Notification

Shared notification services for Catspeak applications. Supports Firestore in-app notifications, SMTP email (via MailKit), and background processing via System.Threading.Channels.

Features

• INotificationService - High-level notification API
• INotificationOrchestrator - Queue-based background processing
• IFirestoreNotificationService - Firestore in-app notifications
• IEmailSender - SMTP email sending via MailKit
• OtpEmailTemplate - Static helper for OTP email templates
• Background processing - System.Threading.Channels for async notification dispatch

Installation

dotnet add package Catspeak.Shared.Notification

Configuration

// Program.cs or Startup.cs
builder.Services.AddCatspeakNotification(options =>
{
    options.Provider = NotificationProvider.Firestore;

    options.Firestore.ProjectId = "your-firestore-project-id";

    options.Smtp.Host = "smtp.gmail.com";
    options.Smtp.Port = 587;
    options.Smtp.Username = "your-smtp-user";
    options.Smtp.Password = "your-smtp-password";
    options.Smtp.FromEmail = "noreply@catspeak.com.vn";
    options.Smtp.FromName = "Cat Speak";
    options.Smtp.ReplyToEmail = "support@catspeak.com.vn";
    options.Smtp.ReplyToName = "Cat Speak Support";

    // Fallback transport (personal Gmail). Used only when the primary
    // provider fails and the message allows fallback (never broadcast).
    options.Smtp.FallbackHost = "smtp.gmail.com";
    options.Smtp.FallbackPort = 587;
    options.Smtp.FallbackUsername = "catspeak.vn@gmail.com";
    options.Smtp.FallbackPassword = "<gmail-app-password>";
    options.Smtp.FallbackFromEmail = "catspeak.vn@gmail.com";

    // Internal recipients (read by admin-notification flows).
    options.AdminEmails.Support = "support@catspeak.com.vn";
    options.AdminEmails.Tech = "tech@catspeak.com.vn";
});

Configuration Keys (flat structure)

Monitoring

Email failover and broadcast retries emit structured logs with stable event IDs. Alert when FallbackUsed spikes (primary provider throttling) or BroadcastDropped appears:

Suggested alert: more than 10 FallbackUsed (6102) in 5 minutes → primary quota/auth issue, check Resend dashboard.

Usage

Send In-App Notification

var notificationService = serviceProvider.GetRequiredService<INotificationService>();

await notificationService.SendNotificationAsync(new NotificationRequest
{
    UserId = 123,
    Title = "Welcome!",
    Body = "Your account has been created.",
    Type = "welcome",
    Channel = NotificationChannels.InApp
});

Send Email Notification

await notificationService.SendNotificationAsync(new NotificationRequest
{
    UserId = 123,
    Channel = NotificationChannels.Email,
    EmailAddress = "user@example.com",
    EmailSubject = "Verify your email",
    EmailHtmlBody = "<h1>Your OTP: 123456</h1>"
});

Send OTP Email

var (subject, htmlBody) = OtpEmailTemplate.GenerateOtpEmail(
    username: "JohnDoe",
    otp: "123456",
    expiryMinutes: 10,
    purpose: "Password Reset");

await emailSender.SendEmailAsync("user@example.com", subject, htmlBody);

Queue Background Notification

var orchestrator = serviceProvider.GetRequiredService<INotificationOrchestrator>();

await orchestrator.EnqueueAsync(new NotificationMessage
{
    UserId = 123,
    Title = "New message",
    Body = "You have a new message",
    Type = "chat",
    Channel = NotificationChannels.Both,
    EmailAddress = "user@example.com",
    EmailSubject = "New message from Chat",
    EmailHtmlBody = "<p>You have a new message</p>"
});

Dependencies

• Google.Cloud.Firestore
• MailKit
• Microsoft.Extensions.DependencyInjection.Abstractions
• Microsoft.Extensions.Logging.Abstractions
• Microsoft.Extensions.Options