Slck.Envelope 1.2.0

Slck.Envelope

Slck.Envelope is a lightweight, zero-dependency library for ASP.NET Core (Minimal APIs and MVC) that wraps every response in a consistent ApiResponse<T> envelope — success, error, pagination, correlation ID, and timestamp included out of the box.

✨ Features

📦 Installation

dotnet add package Slck.Envelope

Targets net9.0 and depends only on Microsoft.AspNetCore.App (no extra NuGet packages).

🚀 Quick Start

1. Register (optional — all defaults are safe)

builder.Services.AddApiEnvelope(opts =>
{
    opts.IncludeExceptionDetails = builder.Environment.IsDevelopment();
    opts.CorrelationIdHeader = "X-Correlation-ID"; // default

    // Map domain exceptions to HTTP status codes — no try/catch in handlers
    opts.MapException<KeyNotFoundException>(404, "not_found")
        .MapException<UnauthorizedAccessException>(401, "unauthorized");

    // Attach OpenTelemetry trace ID to every error envelope
    opts.OnBeforeWriteError = (ex, response) =>
        response with { RequestId = Activity.Current?.TraceId.ToString() ?? response.RequestId };
});

2. Add middleware + (optional) MVC filter

app.UseApiEnvelope(); // global unhandled-exception handler

// For MVC controllers:
builder.Services.AddControllers().AddEnvelopeFilter();

3. Return envelopes from Minimal API endpoints

app.MapGet("/ticket/{id}", (string id) =>
{
    var ticket = db.Find(id);
    return ticket is null
        ? Envelope.NotFound($"Ticket '{id}' not found")
        : Envelope.Ok(ticket);
});

app.MapGet("/tickets", (int page = 1, int pageSize = 10) =>
{
    var meta = new PaginationMeta { Page = page, PageSize = pageSize, Total = total };
    return Envelope.Ok(paged, meta);
});

app.MapPost("/ticket", (Ticket t) => Envelope.Created($"/ticket/{t.Id}", t));

app.MapPost("/jobs", (Job j) => Envelope.Accepted(new { j.Id, Status = "queued" }, $"/jobs/{j.Id}/status"));

📐 Response Shape

Success — 200 OK

{
  "success": true,
  "data": { "id": "123", "title": "Sample Ticket" },
  "meta": { "page": 1, "pageSize": 10, "total": 3, "hasMore": false },
  "requestId": "0HNK...",
  "timestamp": "2026-04-16T08:00:00+00:00"
}

Error — 404 Not Found

{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "Ticket '999' not found"
  },
  "requestId": "0HNK...",
  "timestamp": "2026-04-16T08:00:01+00:00"
}

Validation Error — 422 Unprocessable Entity

{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "Validation failed",
    "details": {
      "id":    ["Id is required."],
      "title": ["Title is required."]
    }
  },
  "requestId": "0HNK...",
  "timestamp": "2026-04-16T08:00:02+00:00"
}

🛠️ Full API Reference

Envelope — Minimal API static helpers

ApiResponseExtensions — bridge from domain layer to IResult

EnvelopeFactory.Ok(data).ToOkResult();
EnvelopeFactory.Fail<T>("not_found", "...").ToNotFoundResult();
EnvelopeFactory.Ok(job).ToAcceptedResult("/jobs/1/status");
response.ToResult(207); // any status code

[SkipEnvelope] — opt-out

// Minimal API
app.MapGet("/report/download", ...).WithMetadata(new SkipEnvelopeAttribute());

// MVC
[SkipEnvelope]
public class HealthController : ControllerBase { ... }

⚙️ EnvelopeOptions

📄 License

MIT — see LICENSE.