feat(envelopes): support multiple response types with shared extension methods

Directory.Build.props

@@ -1,6 +1,6 @@
 <Project>
   <PropertyGroup>
-    <Version>2.0.0-beta.6</Version>
+    <Version>2.0.0-beta.7</Version>
     <!-- SPDX license identifier for MIT -->
     <PackageLicenseExpression>MIT</PackageLicenseExpression>
     <!-- Other useful metadata -->

Directory.Packages.props

@@ -17,6 +17,7 @@
     <PackageVersion Include="AutoFixture.Xunit3" Version="4.19.0" />
     <PackageVersion Include="BenchmarkDotNet" Version="0.15.8" />
     <PackageVersion Include="Microsoft.AspNetCore.Hosting.Abstractions" Version="2.3.0" />
+    <PackageVersion Include="Microsoft.AspNetCore.Http.Abstractions" Version="2.3.0" />
     <PackageVersion Include="Microsoft.AspNetCore.Routing" Version="2.3.0" />
     <PackageVersion Include="Microsoft.Extensions.DependencyModel" Version="10.0.1" />
     <PackageVersion Include="Microsoft.Extensions.Http" Version="10.0.1" />

MinimalLambda.sln

@@ -89,6 +89,8 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "MinimalLambda.Testing.UnitT
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Lambdas", "Lambdas", "{D9109C8A-AFA8-49C8-A19C-381500902B4D}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "MinimalLambda.Envelopes", "src\Envelopes\MinimalLambda.Envelopes\MinimalLambda.Envelopes.csproj", "{190CC9C7-007F-48C5-867D-03B911D53397}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -435,6 +437,18 @@ Global
 		{381F49C0-297F-4B61-8A82-E9E502E523AD}.Release|x64.Build.0 = Release|Any CPU
 		{381F49C0-297F-4B61-8A82-E9E502E523AD}.Release|x86.ActiveCfg = Release|Any CPU
 		{381F49C0-297F-4B61-8A82-E9E502E523AD}.Release|x86.Build.0 = Release|Any CPU
+		{190CC9C7-007F-48C5-867D-03B911D53397}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{190CC9C7-007F-48C5-867D-03B911D53397}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{190CC9C7-007F-48C5-867D-03B911D53397}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{190CC9C7-007F-48C5-867D-03B911D53397}.Debug|x64.Build.0 = Debug|Any CPU
+		{190CC9C7-007F-48C5-867D-03B911D53397}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{190CC9C7-007F-48C5-867D-03B911D53397}.Debug|x86.Build.0 = Debug|Any CPU
+		{190CC9C7-007F-48C5-867D-03B911D53397}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{190CC9C7-007F-48C5-867D-03B911D53397}.Release|Any CPU.Build.0 = Release|Any CPU
+		{190CC9C7-007F-48C5-867D-03B911D53397}.Release|x64.ActiveCfg = Release|Any CPU
+		{190CC9C7-007F-48C5-867D-03B911D53397}.Release|x64.Build.0 = Release|Any CPU
+		{190CC9C7-007F-48C5-867D-03B911D53397}.Release|x86.ActiveCfg = Release|Any CPU
+		{190CC9C7-007F-48C5-867D-03B911D53397}.Release|x86.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -471,5 +485,6 @@ Global
 		{7350482B-DFDE-4DCD-A0C5-899D5EA00F74} = {D9109C8A-AFA8-49C8-A19C-381500902B4D}
 		{381F49C0-297F-4B61-8A82-E9E502E523AD} = {D9109C8A-AFA8-49C8-A19C-381500902B4D}
 		{7E7B3004-C6C4-4A8C-8610-2A1CB61F834A} = {D9109C8A-AFA8-49C8-A19C-381500902B4D}
+		{190CC9C7-007F-48C5-867D-03B911D53397} = {1C3C52D9-2936-4A0C-A9C8-F330F22B8359}
 	EndGlobalSection
 EndGlobal

README.md

@@ -55,6 +55,7 @@ including SQS, SNS, API Gateway, Kinesis, and more.
 
 | Package                                                                                              | NuGet                                                                                                                                                            | Downloads                                                                                                                                                              |
 |------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| [**MinimalLambda.Envelopes**](./src/Envelopes/MinimalLambda.Envelopes/README.md)                   | [![NuGet](https://img.shields.io/nuget/v/MinimalLambda.Envelopes.svg)](https://www.nuget.org/packages/MinimalLambda.Envelopes)                                 | [![Downloads](https://img.shields.io/nuget/dt/MinimalLambda.Envelopes.svg)](https://www.nuget.org/packages/MinimalLambda.Envelopes/)                                 |
 | [**MinimalLambda.Envelopes.Sqs**](./MinimalLambda.Envelopes.Sqs/README.md)                         | [![NuGet](https://img.shields.io/nuget/v/MinimalLambda.Envelopes.Sqs.svg)](https://www.nuget.org/packages/MinimalLambda.Envelopes.Sqs)                         | [![Downloads](https://img.shields.io/nuget/dt/MinimalLambda.Envelopes.Sqs.svg)](https://www.nuget.org/packages/MinimalLambda.Envelopes.Sqs/)                         |
 | [**MinimalLambda.Envelopes.ApiGateway**](./MinimalLambda.Envelopes.ApiGateway/README.md)           | [![NuGet](https://img.shields.io/nuget/v/MinimalLambda.Envelopes.ApiGateway.svg)](https://www.nuget.org/packages/MinimalLambda.Envelopes.ApiGateway)           | [![Downloads](https://img.shields.io/nuget/dt/MinimalLambda.Envelopes.ApiGateway.svg)](https://www.nuget.org/packages/MinimalLambda.Envelopes.ApiGateway/)           |
 | [**MinimalLambda.Envelopes.Sns**](./MinimalLambda.Envelopes.Sns/README.md)                         | [![NuGet](https://img.shields.io/nuget/v/MinimalLambda.Envelopes.Sns.svg)](https://www.nuget.org/packages/MinimalLambda.Envelopes.Sns)                         | [![Downloads](https://img.shields.io/nuget/dt/MinimalLambda.Envelopes.Sns.svg)](https://www.nuget.org/packages/MinimalLambda.Envelopes.Sns/)                         |

docs/features/envelopes.md

@@ -26,6 +26,7 @@ Install only the envelopes you need; each one lives in its own NuGet package.
 
 | Event Source                    | Package                                                                                                                                                | NuGet                                                                                                                                                            |
 |---------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Infrastructure / Base           | [MinimalLambda.Envelopes](https://github.com/j-d-ha/minimal-lambda/tree/main/src/Envelopes/MinimalLambda.Envelopes)                                 | [![NuGet](https://img.shields.io/nuget/v/MinimalLambda.Envelopes.svg)](https://www.nuget.org/packages/MinimalLambda.Envelopes)                                 |
 | SQS                             | [MinimalLambda.Envelopes.Sqs](https://github.com/j-d-ha/minimal-lambda/tree/main/src/Envelopes/MinimalLambda.Envelopes.Sqs)                         | [![NuGet](https://img.shields.io/nuget/v/MinimalLambda.Envelopes.Sqs.svg)](https://www.nuget.org/packages/MinimalLambda.Envelopes.Sqs)                         |
 | SNS                             | [MinimalLambda.Envelopes.Sns](https://github.com/j-d-ha/minimal-lambda/tree/main/src/Envelopes/MinimalLambda.Envelopes.Sns)                         | [![NuGet](https://img.shields.io/nuget/v/MinimalLambda.Envelopes.Sns.svg)](https://www.nuget.org/packages/MinimalLambda.Envelopes.Sns)                         |
 | API Gateway / HTTP API          | [MinimalLambda.Envelopes.ApiGateway](https://github.com/j-d-ha/minimal-lambda/tree/main/src/Envelopes/MinimalLambda.Envelopes.ApiGateway)           | [![NuGet](https://img.shields.io/nuget/v/MinimalLambda.Envelopes.ApiGateway.svg)](https://www.nuget.org/packages/MinimalLambda.Envelopes.ApiGateway)           |
@@ -35,6 +36,11 @@ Install only the envelopes you need; each one lives in its own NuGet package.
 | CloudWatch Logs                 | [MinimalLambda.Envelopes.CloudWatchLogs](https://github.com/j-d-ha/minimal-lambda/tree/main/src/Envelopes/MinimalLambda.Envelopes.CloudWatchLogs)   | [![NuGet](https://img.shields.io/nuget/v/MinimalLambda.Envelopes.CloudWatchLogs.svg)](https://www.nuget.org/packages/MinimalLambda.Envelopes.CloudWatchLogs)   |
 | Application Load Balancer (ALB) | [MinimalLambda.Envelopes.Alb](https://github.com/j-d-ha/minimal-lambda/tree/main/src/Envelopes/MinimalLambda.Envelopes.Alb)                         | [![NuGet](https://img.shields.io/nuget/v/MinimalLambda.Envelopes.Alb.svg)](https://www.nuget.org/packages/MinimalLambda.Envelopes.Alb)                         |
 
+!!! note "Infrastructure Package"
+    `MinimalLambda.Envelopes` is automatically referenced by ALB and API Gateway packages. It provides
+    `IHttpResult<TSelf>` and extension methods for the response builder API. You don't need to install
+    it directly.
+
 Each package ships with README examples in the repository if you need event-specific guidance.
 
 ## Quick Start
@@ -75,6 +81,125 @@ await lambda.RunAsync();
 internal sealed record OrderMessage(string OrderId, decimal Amount);
 ```
 
+## Response Builder API
+
+For HTTP-based event sources (API Gateway, ALB), result classes provide a fluent API for building
+responses. **Key benefit**: Return multiple strongly typed models from the same handler—for example,
+different success and error response types.
+
+```csharp title="API Gateway Example" linenums="1"
+using MinimalLambda.Envelopes.ApiGateway;
+
+lambda.MapHandler(([Event] ApiGatewayRequestEnvelope<LoginRequest> request) =>
+{
+    // Each return statement uses a different strongly typed model
+    if (string.IsNullOrEmpty(request.BodyContent?.Username))
+        return ApiGatewayResult.BadRequest(new ValidationError("Username required"));
+
+    if (!authService.Authenticate(request.BodyContent))
+        return ApiGatewayResult.Unauthorized(new AuthError("Invalid credentials"));
+
+    return ApiGatewayResult.Ok(new LoginSuccess(token, expiresAt));
+});
+
+internal record LoginRequest(string Username, string Password);
+internal record ValidationError(string Message);
+internal record AuthError(string Message);
+internal record LoginSuccess(string Token, DateTime ExpiresAt);
+```
+
+### Available Result Classes
+
+| Class                  | Package                              | Use Case                                    |
+|------------------------|--------------------------------------|---------------------------------------------|
+| `AlbResult`            | MinimalLambda.Envelopes.Alb          | Application Load Balancer responses         |
+| `ApiGatewayResult`     | MinimalLambda.Envelopes.ApiGateway   | REST API / HTTP API v1 / WebSocket          |
+| `ApiGatewayV2Result`   | MinimalLambda.Envelopes.ApiGateway   | HTTP API v2 responses                       |
+
+Common methods: `Ok()`, `Created()`, `NoContent()`, `BadRequest()`, `Unauthorized()`, `NotFound()`,
+`Conflict()`, `UnprocessableEntity()`, `InternalServerError()`, `StatusCode(int)`, `Text(int,
+string)`, `Json<T>(int, T)`. All methods have overloads with and without body content.
+
+### When to Use Results vs. Envelopes
+
+**Use result classes** when you need to return multiple strongly typed models from the same handler.
+Provides convenient methods for common HTTP status codes.
+
+**Use envelope classes directly** when you need custom serialization (e.g., XML) or want to extend
+envelope base classes for custom behavior.
+
+!!! tip "Complete API Reference"
+    For detailed method documentation, AOT configuration, and advanced usage, see the package README
+    files:
+
+    - [ALB Package README](https://github.com/j-d-ha/minimal-lambda/tree/main/src/Envelopes/MinimalLambda.Envelopes.Alb)
+    - [API Gateway Package README](https://github.com/j-d-ha/minimal-lambda/tree/main/src/Envelopes/MinimalLambda.Envelopes.ApiGateway)
+
+!!! note
+    Result classes use their respective envelope classes internally (`AlbResponseEnvelope<T>`,
+    `ApiGatewayResponseEnvelope<T>`, etc.). They're a convenience layer over the envelope
+    infrastructure.
+
+## AOT Support
+
+When using .NET Native AOT, register all envelope and payload types in your `JsonSerializerContext`.
+
+!!! tip "Register Both Envelope and Payload Types"
+    You must register **both** the envelope type (e.g., `ApiGatewayRequestEnvelope<LoginRequest>`)
+    **and** the inner payload type (e.g., `LoginRequest`). The envelope wraps the AWS event
+    structure, while the payload is your business type inside the envelope.
+
+### Basic Envelope Setup
+
+```csharp title="Program.cs" linenums="1"
+using System.Text.Json.Serialization;
+
+[JsonSerializable(typeof(ApiGatewayRequestEnvelope<LoginRequest>))]  // Envelope wrapper
+[JsonSerializable(typeof(ApiGatewayResponseEnvelope<LoginSuccess>))] // Envelope wrapper
+[JsonSerializable(typeof(LoginRequest))]                             // Inner payload type
+[JsonSerializable(typeof(LoginSuccess))]                             // Inner payload type
+internal partial class SerializerContext : JsonSerializerContext;
+```
+
+### Result Classes with Multiple Return Types
+
+When using result classes (`AlbResult`, `ApiGatewayResult`, `ApiGatewayV2Result`), register each
+response type separately:
+
+```csharp title="Program.cs" linenums="1"
+using System.Text.Json.Serialization;
+
+[JsonSerializable(typeof(ApiGatewayRequestEnvelope<LoginRequest>))]
+[JsonSerializable(typeof(ApiGatewayResult))]
+[JsonSerializable(typeof(LoginRequest))]
+[JsonSerializable(typeof(ValidationError))]
+[JsonSerializable(typeof(AuthError))]
+[JsonSerializable(typeof(LoginSuccess))]
+internal partial class SerializerContext : JsonSerializerContext;
+```
+
+### Registering the Serializer Context
+
+Register the serializer and configure envelope options to use the context:
+
+```csharp title="Program.cs" linenums="1"
+var builder = LambdaApplication.CreateBuilder();
+
+builder.Services.AddLambdaSerializerWithContext<SerializerContext>();
+
+builder.Services.ConfigureEnvelopeOptions(options =>
+{
+    options.JsonOptions.TypeInfoResolver = SerializerContext.Default;
+});
+```
+
+!!! important "Why Register in Two Places?"
+    The context must be registered as the type resolver for **both** the envelope options and the
+    Lambda serializer because deserialization happens at different steps:
+
+    1. **Lambda serializer** deserializes the raw AWS event (e.g., API Gateway event structure)
+    2. **Envelope options** deserialize the envelope content into your payload types
+
 ## Custom Serialization & EnvelopeOptions
 
 All envelope packages respect the global `EnvelopeOptions` configuration. Call

docs/getting-started/installation.md

@@ -190,6 +190,7 @@ Envelope packages provide type-safe, strongly-typed event handling for specific
 
 | Package                                      | Event Source              | When to Use                   |
 |----------------------------------------------|---------------------------|-------------------------------|
+| **MinimalLambda.Envelopes**                 | Infrastructure            | HTTP response builders (auto-referenced) |
 | **MinimalLambda.Envelopes.Sqs**             | Amazon SQS                | Processing SQS queue messages |
 | **MinimalLambda.Envelopes.Sns**             | Amazon SNS                | Handling SNS notifications    |
 | **MinimalLambda.Envelopes.ApiGateway**      | API Gateway               | Building REST/HTTP APIs       |

docs/index.md

@@ -95,12 +95,7 @@ already know, while still embracing Lambda’s execution model.
             var greeting = await service.GreetAsync(request.BodyContent.Name, cancellationToken);
 
             // ✅ Type-safe response - automatic JSON serialization
-            return new ApiGatewayResponseEnvelope<GreetingResponse>
-            {
-                BodyContent = new GreetingResponse(greeting, DateTime.UtcNow),
-                StatusCode = 200,
-                Headers = new Dictionary<string, string> { ["Content-Type"] = "application/json" },
-            };
+            return ApiGatewayResult.Ok(new GreetingResponse(greeting, DateTime.UtcNow));
         }
     );
 
@@ -211,6 +206,7 @@ deserialization.
 
 | Package                                                                                | Description                                           | NuGet                                                                                                                                                            | Downloads                                                                                                                                                              |
 |----------------------------------------------------------------------------------------|-------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| **MinimalLambda.Envelopes**                              | Infrastructure package for HTTP response builders     | [![NuGet](https://img.shields.io/nuget/v/MinimalLambda.Envelopes.svg)](https://www.nuget.org/packages/MinimalLambda.Envelopes)                                 | [![Downloads](https://img.shields.io/nuget/dt/MinimalLambda.Envelopes.svg)](https://www.nuget.org/packages/MinimalLambda.Envelopes/)                                 |
 | **MinimalLambda.Envelopes.Sqs**                          | Simple Queue Service events with typed message bodies | [![NuGet](https://img.shields.io/nuget/v/MinimalLambda.Envelopes.Sqs.svg)](https://www.nuget.org/packages/MinimalLambda.Envelopes.Sqs)                         | [![Downloads](https://img.shields.io/nuget/dt/MinimalLambda.Envelopes.Sqs.svg)](https://www.nuget.org/packages/MinimalLambda.Envelopes.Sqs/)                         |
 | **MinimalLambda.Envelopes.Sns**                          | Simple Notification Service messages                  | [![NuGet](https://img.shields.io/nuget/v/MinimalLambda.Envelopes.Sns.svg)](https://www.nuget.org/packages/MinimalLambda.Envelopes.Sns)                         | [![Downloads](https://img.shields.io/nuget/dt/MinimalLambda.Envelopes.Sns.svg)](https://www.nuget.org/packages/MinimalLambda.Envelopes.Sns/)                         |
 | **MinimalLambda.Envelopes.ApiGateway**           | REST, HTTP, and WebSocket APIs                        | [![NuGet](https://img.shields.io/nuget/v/MinimalLambda.Envelopes.ApiGateway.svg)](https://www.nuget.org/packages/MinimalLambda.Envelopes.ApiGateway)           | [![Downloads](https://img.shields.io/nuget/dt/MinimalLambda.Envelopes.ApiGateway.svg)](https://www.nuget.org/packages/MinimalLambda.Envelopes.ApiGateway/)           |