Lumarin.Notify.Admin 0.8.0-preview.199

Lumarin.Notify.Admin

Lumarin.Notify.Admin is the optional ASP.NET Core control-plane package for Lumarin.Notify.

What it includes

• route and contract wiring for the admin HTTP surface
• stable OpenAPI operation names and frontend-friendly response shapes
• a typed .NET HTTP client for the locked admin control-plane contract
• admin authorization seams and RFC 9457 problem-details behavior
• service-driven module activation so hosts only expose the modules they actually register

What it does not include

• a second delivery or template runtime
• EF Core persistence by itself
• direct outbox package dependencies
• cluster-wide runtime control semantics

Optional companions

• Lumarin.Notify.Admin.Claims for typed claims-based IAdminAuthorizationPolicy registration
• Lumarin.Notify.Admin.EntityFrameworkCore for EF-backed dashboard, delivery, dead-letter, audit, recipient, provider, and policy services
• Lumarin.Notify.Admin.Outbox for outbox summary, entry, replay, requeue, and process-local pause or resume routes

Control-plane truth model

Use the published Admin truth-model docs when you are wiring an Admin UI or reviewing operator-facing semantics:

• Admin Control Plane
• Admin Capabilities
• Admin Runtime Scope
• Admin Provider Readiness

Basic activation

using Lumarin.Notify.DependencyInjection;

builder.Services.AddLumarinNotify(options =>
{
    options.EnableAdminDefaults(admin =>
    {
        admin.RoutePrefix = "/api/admin";
    });
});

var app = builder.Build();
app.MapLumarinNotify();

Direct AddLumarinNotifyAdmin(...) and MapLumarinNotifyAdminApi() calls remain available for advanced composition when the host intentionally wants only the admin surface.

EnableAdminDefaults(...) enables the common operator modules, including analytics and policy management, while keeping sandbox access, outbox activation, route mapping, and host authorization explicit.

If you want the EF-backed admin query and mutation services, add AddLumarinNotifyAdminEntityFrameworkCore() and run MigrateLumarinNotifyAdminAsync() before enabling admin mutations against an existing database. The admin migration stream applies the provider, policy, and durable admin audit schema, and EF-backed responses include TenantId when multi-tenancy is enabled and the host supplies an ambient tenant context.

EF-backed provider inventory, provider validation, and policy simulation responses are intentionally explicit about what they do and do not prove. Provider inventory/detail payloads may add ValidationAttempted, ValidationMode, IsRuntimeOnly, IsCodeRegistered, EditabilityReason, LastSignalSource, Limitations, and Warnings; provider validation results may add ValidationAttempted, LastSignalSource, Limitations, and Warnings; policy simulation may add SimulationMode, delivery/probe/readiness booleans, actor/runtime/tenant scope, SourceModules, Limitations, Warnings, and EvaluatedAtUtc. Those additions qualify the current response without changing the locked route set.

Recommended host recipe

using Lumarin.Notify.Admin.Abstractions;
using Lumarin.Notify.Admin.EntityFrameworkCore.Extensions;
using Lumarin.Notify.DependencyInjection;

builder.Services.AddOpenApi();

builder.Services.AddLumarinNotify(options =>
{
    options.EnableAdminDefaults(admin =>
    {
        admin.RoutePrefix = "/api/admin";
    });
});

builder.Services.AddLumarinNotifyAdminEntityFrameworkCore();
builder.Services.AddSingleton<IAdminAuthorizationPolicy, YourAppAdminAuthorizationPolicy>();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

app.MapLumarinNotify();
await app.Services.MigrateLumarinNotifyAdminAsync();

This recipe gives operators a stable bootstrap surface at GET /api/admin/me, the locked root document at GET /api/admin, and the OpenAPI document at GET /openapi/v1.json in Development.

When AddLumarinNotifyAdminEntityFrameworkCore() is present, the base Admin package also exposes service-backed audit inspection at GET /api/admin/audit and GET /api/admin/audit/{id} and includes ambient TenantId in EF-backed list and detail payloads when multi-tenancy is active.

Embedded-host route groups

If the host already owns the /ops prefix and a staff-only authorization policy, mount Admin directly onto that host-owned route group instead of proxying it through a second controller layer:

app.UseAuthentication();
app.UseAuthorization();

app.MapGroup("/ops/admin")
    .RequireAuthorization("NotifyStaff")
    .MapLumarinNotifyAdminApi();

This keeps route ownership and policy ownership in the host while preserving the library-owned Admin contract. The compile-verified reference for this shape is samples/Lumarin.Notify.Sample.EmbeddedHost.

If the host already normalizes admin roles, scopes, or permissions onto HttpContext.User, install Lumarin.Notify.Admin.Claims and call AddLumarinNotifyClaimsAdminAuthorization(...) after enabling Admin. The helper replaces the base deny-all policy with a typed claims-based implementation while keeping route-level authentication fully host-owned.

Typed client

using Lumarin.Notify.Admin.Client.Configuration;
using Lumarin.Notify.Admin.DependencyInjection;

builder.Services.AddLumarinNotifyAdminHttpClient(
    new Uri("https://ops.example"),
    configure: options =>
    {
        options.Routes.Apply(LumarinNotifyAdminHttpRoutes.ForRoutePrefix("/ops/admin"));
    });

The typed client tracks the locked LumarinNotifyAdminContract.Current route set and throws a typed HTTP exception for RFC 9457 problem responses. Read operations that still hit a placeholder-backed admin surface fail fast with a descriptive InvalidOperationException instead of silently deserializing the placeholder payload as a service-backed response.

Use GetCurrentOperatorAsync() first when bootstrapping an Admin UI or operator workflow. It returns the effective module capability matrix for the current caller, including the currently mapped ReadOperations and ManageOperations per module, so the UI does not need to probe routes speculatively.