Lumarin.Notify.Core 0.8.0-preview.78

Lumarin.Notify

Multi-channel notification infrastructure for .NET. Reliable delivery across in-app feeds, realtime SignalR push, email, SMS, and mobile push — from a single unified API, with durable delivery tracking, templating, retry, rate limiting, and user preference enforcement built in.

var result = await hub.SendAsync(new NotificationRequest(
    ScopeType: "user",
    ScopeId:   "user-123",
    Category:  "order.shipped",
    Content: new NotificationContent("Order shipped", "Your order #456 is on the way!"),
    Recipients: new NotificationRecipients(
        Identities: ["user-123"],
        Channels:   [NotificationChannel.InApp, NotificationChannel.Email]),
    Options: new NotificationOptions(
        IdempotencyKey: "order-456-shipped",
        Priority:       NotificationPriority.High)));

Choose your packages

Installation

# Always required
dotnet add package Lumarin.Notify.Core
dotnet add package Lumarin.Notify.EntityFrameworkCore

# HTTP endpoints for feed, preferences, devices, and template admin
dotnet add package Lumarin.Notify.AspNetCore

# Template engine — required only for SendFromTemplateAsync
dotnet add package Lumarin.Notify.Templates

# Add the channels you need — each requires provider credentials (see below)
dotnet add package Lumarin.Notify.Channels.SignalR
dotnet add package Lumarin.Notify.Channels.Email
dotnet add package Lumarin.Notify.Channels.Push
dotnet add package Lumarin.Notify.Channels.Sms

Provider credential requirements

Channel registration fails fast at startup if required credentials are missing.

Prerequisites

• .NET 8, 9, or 10 SDK
• PostgreSQL or SQL Server for production; EF Core InMemory for dev/tests

Minimal setup

// Program.cs
using Lumarin.Notify.Core.DependencyInjection;
using Lumarin.Notify.EntityFrameworkCore.Extensions;

LumarinNotifyOptions? notifyOptions = null;

builder.Services.AddLumarinNotify(options =>
{
    options.UseDatabase(
        builder.Configuration.GetConnectionString("LumarinNotify")!,
        "postgresql"); // or "sqlserver"

    options.Delivery.MaxRetries = 3;
    notifyOptions = options;
});

builder.Services.AddLumarinNotifyEntityFrameworkCore(notifyOptions!);

var app = builder.Build();
await app.Services.MigrateLumarinNotifyAsync(); // applies EF migrations

app.Run();

Inject INotificationHub and send:

var result = await hub.SendAsync(new NotificationRequest(
    ScopeType: "user",
    ScopeId:   "user-123",
    Category:  "order.shipped",
    Content: new NotificationContent("Order shipped", "Your order #456 is on the way!"),
    Recipients: new NotificationRecipients(
        Identities: ["user-123"],
        Channels:   [NotificationChannel.InApp, NotificationChannel.Email]),
    Options: new NotificationOptions(
        IdempotencyKey: "order-456-shipped",
        Priority:       NotificationPriority.High)));

HTTP endpoints (AspNetCore adapter)

Lumarin.Notify.AspNetCore adds ready-made minimal API endpoints for the notification feed, user preferences, device registration, template admin, and delivery tracking.

// Register the host adapter (after AddLumarinNotify)
builder.Services.AddLumarinNotifyAspNetCore(options =>
{
    options.ScopeType = "user";
    options.Features.EnableTemplates = true;  // template admin endpoints (off by default)
    options.Features.EnableTracking  = true;  // delivery/dead-letter tracking endpoints (off by default)
});

// Optional: resolve the current user identity from HttpContext
// Default: reads ClaimTypes.NameIdentifier
builder.Services.AddSingleton<ILumarinNotifyIdentityResolver, YourIdentityResolver>();

// Map the endpoints
app.MapLumarinNotifyFeedApi();
app.MapLumarinNotifyPreferencesApi();
app.MapLumarinNotifyDevicesApi();
app.MapLumarinNotifyTemplatesApi();  // only active when Features.EnableTemplates = true
app.MapLumarinNotifyTrackingApi();   // only active when Features.EnableTracking = true

Default routes (rebaseable via app.MapGroup(...)):

Security: AddLumarinNotifyAspNetCore registers DevelopmentOnlyLumarinNotifyAuthorizationPolicy by default, which grants all callers access to template admin and tracking endpoints. Register a custom ILumarinNotifyAuthorizationPolicy before deploying to production.

Template sends

var result = await hub.SendFromTemplateAsync(
    scopeType:   "user",
    scopeId:     "user-123",
    templateKey: "order-shipped",
    data:        new { Name = "Alex", OrderId = "456" },
    recipients:  new NotificationRecipients(["user-123"]),
    locale:      "en");

Requires Lumarin.Notify.Templates. Template engine is "scriban" (default) or "liquid".

Channel registration

Each channel is registered separately. Examples:

// SignalR (realtime WebSocket push)
builder.Services.AddLumarinNotifySignalR(options =>
{
    options.HubPath = "/hubs/notifications";
    options.RequireAuthenticatedUser = true;
});
app.MapLumarinNotifySignalR(); // maps the hub

// Email (read from configuration; fails fast if credentials missing)
var emailOptions = builder.Configuration
    .GetSection("Lumarin.Notify:Channels:Email")
    .Get<EmailChannelOptions>() ?? new EmailChannelOptions();

if (emailOptions.Enabled)
    builder.Services.AddEmailChannel(emailOptions);

InMemory database (dev / tests)

builder.Services.AddDbContext<LumarinNotifyDbContext>(opts =>
    opts.UseInMemoryDatabase("LumarinNotify_Dev"));

builder.Services.AddScoped<INotificationRepository, NotificationRepository>();
builder.Services.AddScoped<ITemplateRepository, TemplateRepository>();
builder.Services.AddScoped<IDeliveryRepository, DeliveryRepository>();
builder.Services.AddScoped<IDeviceRepository, DeviceRepository>();
builder.Services.AddScoped<IPreferenceRepository, PreferenceRepository>();

No migrations needed. All data resets on restart.

Docker Compose

# API-only
docker compose --profile api up --build

# API + frontend
docker compose --profile frontend up --build

Copy .env.example as the starting point for runtime parameters.

Next Steps

• Getting Started guide — zero to first notification in 10 minutes
• ASP.NET Core Hosting — HTTP endpoints, identity resolution, authorization
• API Reference — full interface and DI reference
• Channel guides — per-channel setup and credential requirements
• SignalR realtime guide — WebSocket client integration
• Docker Compose guide — production container configuration