Merge branch 'main' into feat/DC-150-step-up

Author: noxmwalsh

src/SEBT.Portal.Api/Controllers/Household/HouseholdController.cs

@@ -58,13 +58,15 @@ public async Task<IActionResult> GetHouseholdData(
     /// <param name="cancellationToken">A token to monitor for cancellation requests.</param>
     /// <returns>No content on success; otherwise, BadRequest or Unauthorized.</returns>
     /// <response code="204">Address updated successfully.</response>
-    /// <response code="400">Validation failed (missing fields or invalid format).</response>
+    /// <response code="400">Validation failed (missing fields, invalid format, or address could not be verified).</response>
     /// <response code="403">User is not authorized or no household identifier could be resolved from token.</response>
+    /// <response code="502">Address verification provider error or timeout.</response>
     [HttpPut("address")]
     [Authorize]
     [ProducesResponseType(StatusCodes.Status204NoContent)]
     [ProducesResponseType(typeof(ValidationProblemDetails), StatusCodes.Status400BadRequest)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status403Forbidden)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status502BadGateway)]
     public async Task<IActionResult> UpdateAddress(
         [FromBody] UpdateAddressRequest request,
         [FromServices] ICommandHandler<UpdateAddressCommand> commandHandler,

src/SEBT.Portal.Api/appsettings.co.example.json

@@ -1,4 +1,12 @@
 {
+  "AddressValidationPolicy": {
+    "AllowGeneralDelivery": true
+  },
+  "Smarty": {
+    "Enabled": false,
+    "AuthId": "",
+    "AuthToken": ""
+  },
   "Socure": {
     "Enabled": false
   },

src/SEBT.Portal.Api/appsettings.dc.example.json

@@ -1,4 +1,12 @@
 {
+  "AddressValidationPolicy": {
+    "AllowGeneralDelivery": true
+  },
+  "Smarty": {
+    "Enabled": false,
+    "AuthId": "",
+    "AuthToken": ""
+  },
   "Socure": {
     "Enabled": true,
     "UseStub": true,

src/SEBT.Portal.Api/appsettings.json

@@ -91,6 +91,16 @@
       "ProfileId": ""
     }
   },
+  "Smarty": {
+    "Enabled": false,
+    "AuthId": "",
+    "AuthToken": "",
+    "BaseUrl": "https://us-street.api.smartystreets.com",
+    "TimeoutSeconds": 20
+  },
+  "AddressValidationPolicy": {
+    "AllowGeneralDelivery": true
+  },
   "FeatureManagement": {
     "email_dob_opt_in": false,
     "show_application_number": true,

src/SEBT.Portal.Core/AppSettings/AddressValidationPolicySettings.cs

@@ -0,0 +1,15 @@
+namespace SEBT.Portal.Core.AppSettings;
+
+/// <summary>
+/// Per-state policy for address updates. Override in <c>appsettings.{state}.json</c> as needed.
+/// </summary>
+public sealed class AddressValidationPolicySettings
+{
+    public const string SectionName = "AddressValidationPolicy";
+
+    /// <summary>
+    /// When true, USPS General Delivery addresses validated via Smarty are accepted.
+    /// When false, General Delivery is rejected with a structured validation error.
+    /// </summary>
+    public bool AllowGeneralDelivery { get; set; } = true;
+}

src/SEBT.Portal.Core/AppSettings/SmartySettings.cs

@@ -0,0 +1,29 @@
+using System.ComponentModel.DataAnnotations;
+
+namespace SEBT.Portal.Core.AppSettings;
+
+/// <summary>
+/// Configuration for Smarty US Street Address API.
+/// </summary>
+public sealed class SmartySettings
+{
+    public const string SectionName = "Smarty";
+
+    /// <summary>
+    /// When false, the portal uses pass-through normalization only (no HTTP calls to Smarty).
+    /// </summary>
+    public bool Enabled { get; set; }
+
+    /// <summary>Smarty embedded key auth-id.</summary>
+    public string? AuthId { get; set; }
+
+    /// <summary>Smarty embedded key auth-token (secret).</summary>
+    public string? AuthToken { get; set; }
+
+    /// <summary>API host without trailing slash (e.g. https://us-street.api.smartystreets.com).</summary>
+    public string BaseUrl { get; set; } = "https://us-street.api.smartystreets.com";
+
+    /// <summary>HTTP timeout for Smarty requests.</summary>
+    [Range(1, 120)]
+    public int TimeoutSeconds { get; set; } = 20;
+}

src/SEBT.Portal.Core/Models/AddressUpdate/AddressUpdateOperationRequest.cs

@@ -0,0 +1,47 @@
+using SEBT.Portal.Core.Models.Household;
+
+namespace SEBT.Portal.Core.Models.AddressUpdate;
+
+/// <summary>
+/// Canonical input for shared address validation and normalization (portal handlers and state connectors).
+/// Carries optional identifiers and metadata so callers can correlate requests without coupling to HTTP.
+/// </summary>
+public sealed record AddressUpdateOperationRequest
+{
+    /// <summary>Line-one street address or USPS-style General Delivery line.</summary>
+    public required string StreetAddress1 { get; init; }
+
+    /// <summary>Optional secondary line (unit, suite, etc.).</summary>
+    public string? StreetAddress2 { get; init; }
+
+    /// <summary>City or USPS post office location for General Delivery.</summary>
+    public required string City { get; init; }
+
+    /// <summary>US state name or two-letter abbreviation.</summary>
+    public required string State { get; init; }
+
+    /// <summary>US ZIP or ZIP+4.</summary>
+    public required string PostalCode { get; init; }
+
+    /// <summary>Optional end-to-end correlation id (logging, support).</summary>
+    public string? CorrelationId { get; init; }
+
+    /// <summary>Optional state case or eligibility system identifier for the household.</summary>
+    public string? HouseholdExternalId { get; init; }
+
+    /// <summary>Optional opaque key/value metadata (connector-specific; not sent to Smarty).</summary>
+    public IReadOnlyDictionary<string, string>? Metadata { get; init; }
+
+    /// <summary>
+    /// Builds a request from the domain <see cref="Household.Address"/> model.
+    /// </summary>
+    public static AddressUpdateOperationRequest FromHouseholdAddress(Address address) =>
+        new()
+        {
+            StreetAddress1 = address.StreetAddress1 ?? string.Empty,
+            StreetAddress2 = address.StreetAddress2,
+            City = address.City ?? string.Empty,
+            State = address.State ?? string.Empty,
+            PostalCode = address.PostalCode ?? string.Empty
+        };
+}

src/SEBT.Portal.Core/Models/AddressUpdate/AddressUpdateSuccess.cs

@@ -0,0 +1,18 @@
+using SEBT.Portal.Core.Models.Household;
+
+namespace SEBT.Portal.Core.Models.AddressUpdate;
+
+/// <summary>
+/// Successful outcome of <see cref="SEBT.Portal.Core.Services.IAddressUpdateService"/>.
+/// </summary>
+public sealed record AddressUpdateSuccess
+{
+    /// <summary>USPS-style normalized mailing address.</summary>
+    public required Address NormalizedAddress { get; init; }
+
+    /// <summary>True when Smarty indicates USPS General Delivery (record type G or equivalent).</summary>
+    public bool IsGeneralDelivery { get; init; }
+
+    /// <summary>True when normalized fields differ from the submitted input (casing, abbreviations, ZIP+4).</summary>
+    public bool WasCorrected { get; init; }
+}

src/SEBT.Portal.Core/Services/IAddressUpdateService.cs

@@ -0,0 +1,20 @@
+using SEBT.Portal.Core.Models.AddressUpdate;
+using SEBT.Portal.Kernel;
+using SEBT.Portal.Kernel.Results;
+
+namespace SEBT.Portal.Core.Services;
+
+/// <summary>
+/// Validates and normalizes mailing addresses using Smarty (when enabled) and state policy from configuration.
+/// Intended for use by portal use cases and state connectors so validation rules stay consistent.
+/// </summary>
+public interface IAddressUpdateService
+{
+    /// <summary>
+    /// Validates the address with Smarty (or pass-through when disabled), applies per-state policy
+    /// (e.g. General Delivery), and returns a normalized address or structured validation errors.
+    /// </summary>
+    Task<Result<AddressUpdateSuccess>> ValidateAndNormalizeAsync(
+        AddressUpdateOperationRequest request,
+        CancellationToken cancellationToken = default);
+}

src/SEBT.Portal.Core/Services/IAddressValidationService.cs

@@ -3,8 +3,8 @@
 namespace SEBT.Portal.Core.Services;
 
 /// <summary>
-/// Validates a mailing address against an external service (e.g., Smarty).
-/// Implementations may autocomplete, suggest alternatives, or reject invalid addresses.
+/// Legacy façade over <see cref="IAddressUpdateService"/> for simple valid/invalid checks.
+/// Prefer <see cref="IAddressUpdateService"/> for structured errors, identifiers, and metadata.
 /// </summary>
 public interface IAddressValidationService
 {
@@ -19,14 +19,17 @@ public interface IAddressValidationService
 /// Result of an address validation call.
 /// </summary>
 /// <param name="IsValid">Whether the address passed validation.</param>
+/// <param name="NormalizedAddress">USPS-normalized address when valid, if available.</param>
 /// <param name="SuggestedAddress">An alternative address suggested by the validation service, if any.</param>
 /// <param name="ErrorMessage">A user-facing error message if validation failed.</param>
 public record AddressValidationResult(
     bool IsValid,
+    Address? NormalizedAddress = null,
     Address? SuggestedAddress = null,
     string? ErrorMessage = null)
 {
-    public static AddressValidationResult Valid() => new(true);
+    public static AddressValidationResult Valid(Address? normalizedAddress = null) =>
+        new(true, NormalizedAddress: normalizedAddress);
 
     public static AddressValidationResult Invalid(string errorMessage) => new(false, ErrorMessage: errorMessage);