feat(api,core,infra): refactor endpoint routing and add institution account discovery

- Move login and refresh endpoints under a unified /auth route group
- Relocate institution connection logic from /accounts to /institutions
- Implement GET /institutions/{id}/available to fetch real-time Plaid
accounts
- Introduce HttpRequestBuilder utility to streamline integration testing
- Enhance PlaidService with GetAccountsAsync to support account fetching
- Clean up global usings and project structure for better domain
isolation

src/FiscalOS.API/Institutions/Connect/Endpoint.cs

@@ -0,0 +1,57 @@
+namespace FiscalOS.API.Institutions.Connect;
+
+internal static class Endpoint
+{
+  private const string Route = "/connect";
+
+  public static RouteHandlerBuilder MapConnectEndpoint(this RouteGroupBuilder groupBuilder)
+  {
+    return groupBuilder.MapPost(Route, HandleAsync);
+  }
+
+  private static async Task<IResult> HandleAsync(
+    HttpContext httpContext,
+    [FromBody] Request request,
+    [FromServices] AppDbContext appDbContext,
+    [FromServices] PlaidService plaidService,
+    [FromServices] IEncryptor encryptor,
+    CancellationToken ct
+  )
+  {
+    var userId = httpContext.GetUserId();
+
+    var user = await appDbContext.Users
+      .Include(u => u.Institutions
+        .Where(
+          i => i.Metadata is PlaidMetadata &&
+            ((PlaidMetadata)i.Metadata).PlaidId == request.PlaidInstitutionId
+        )
+      )
+      .ThenInclude(i => i.Metadata)
+      .SingleOrDefaultAsync(u => u.Id == userId, ct);
+
+    if (user is null)
+    {
+      return Results.Unauthorized();
+    }
+
+    if (user.Institutions.Any())
+    {
+      return Results.Conflict();
+    }
+
+    var (itemId, accessToken) = await plaidService.ExchangeTokenAsync(request.PublicToken);
+    var item = await plaidService.GetItemAsync(accessToken);
+
+    var encryptedAccessToken = await encryptor.EncryptAsyncFor(user, accessToken, ct);
+
+    var plaidMetadata = PlaidMetadata.From(item.InstitutionId, item.InstitutionName, encryptedAccessToken);
+    var institution = Institution.From(item.InstitutionName, plaidMetadata);
+
+    user.AddInstitution(institution);
+
+    await appDbContext.SaveChangesAsync(ct);
+
+    return Results.Ok();
+  }
+}

src/FiscalOS.API/Institutions/Connect/Request.cs

@@ -0,0 +1,22 @@
+namespace FiscalOS.API.Institutions.Connect;
+
+public record Request : IValidatableObject
+{
+  public string PublicToken { get; init; } = string.Empty;
+  public string PlaidInstitutionId { get; init; } = string.Empty;
+
+  public IEnumerable<ValidationResult> Validate(ValidationContext validationContext)
+  {
+    if (string.IsNullOrWhiteSpace(PublicToken))
+    {
+      var fieldName = nameof(PublicToken);
+      yield return new($"The {fieldName} field is required.", [fieldName]);
+    }
+
+    if (string.IsNullOrWhiteSpace(PlaidInstitutionId))
+    {
+      var fieldName = nameof(PlaidInstitutionId);
+      yield return new($"The {fieldName} field is required.", [fieldName]);
+    }
+  }
+}

src/FiscalOS.API/Institutions/GetAvailable/Endpoint.cs

@@ -0,0 +1,50 @@
+namespace FiscalOS.API.Institutions.GetAvailable;
+
+internal static class Endpoint
+{
+  private const string Route = "/{id}/available";
+
+  public static RouteHandlerBuilder MapGetAvailableEndpoint(this RouteGroupBuilder groupBuilder)
+  {
+    return groupBuilder.MapGet(Route, HandleAsync);
+  }
+
+  private static async Task<IResult> HandleAsync(
+    HttpContext httpContext,
+    [FromRoute] Guid id,
+    [FromServices] AppDbContext appDbContext,
+    [FromServices] PlaidService plaidService,
+    [FromServices] IEncryptor encryptor,
+    CancellationToken ct
+  )
+  {
+    var userId = httpContext.GetUserId();
+
+    var user = await appDbContext.Users
+      .Include(u => u.Institutions.Where(i => i.Id == id))
+      .ThenInclude(i => i.Metadata)
+      .SingleOrDefaultAsync(u => u.Id == userId, ct);
+
+    if (user is null)
+    {
+      return Results.Unauthorized();
+    }
+
+    if (user.Institutions.Any() is false)
+    {
+      return Results.NotFound();
+    }
+
+    var institution = user.Institutions.First();
+
+    if (institution.Metadata is not PlaidMetadata plaidMetadata)
+    {
+      return Results.BadRequest();
+    }
+
+    var accessToken = await encryptor.DecryptAsyncFor(user, plaidMetadata.EncryptedAccessToken, ct);
+    var accounts = await plaidService.GetAccountsAsync(accessToken);
+
+    return Results.Ok(accounts);
+  }
+}

src/FiscalOS.API/Institutions/InstitutionsExtensions.cs

@@ -0,0 +1,17 @@
+namespace FiscalOS.API.Institutions;
+
+internal static class InstitutionsExtensions
+{
+  private const string RouteGroupPrefix = "/institutions";
+
+  public static RouteGroupBuilder MapInstitutionsEndpoints(this WebApplication app)
+  {
+    var institutionsGroup = app.MapGroup(RouteGroupPrefix)
+      .RequireAuthorization();
+
+    institutionsGroup.MapConnectEndpoint();
+    institutionsGroup.MapGetAvailableEndpoint();
+
+    return institutionsGroup;
+  }
+}