Cayaqui.MPS.ApiClient 0.1.0

Cayaqui.MPS.ApiClient

Cliente HTTP tipado y Result-based para consumir APIs MPS desde Blazor / MAUI / cualquier .NET. Espeja el contrato de errores del companion server: el API serializa DomainError→ProblemDetails; este paquete deserializa ProblemDetails→Result<T>.Failure(DomainError). Nunca lanza por error de negocio — todo 4xx/5xx con ProblemDetails se mapea a Result<T> Failure.

Distribución propietaria — requiere contrato comercial con Cayaqui. Ver LICENSE.txt.

Instalación

<PackageReference Include="Cayaqui.MPS.ApiClient" Version="0.1.0" />

Depende de Cayaqui.MPS.BuildingBlocks ≥ 0.4.0 (Result<T>, DomainError, ErrorType, Unit). Sin dependencia ASP.NET (cliente puro).

Servicio tipado

Todos los servicios API implementan el marker IBaseApiService (regla global Cayaqui) y heredan de BaseApiService, que expone verb-helpers que devuelven Result<T>:

using MPS.ApiClient;
using MPS.BuildingBlocks.Application;   // Result<T>, Unit

public interface INotificationsApiService : IBaseApiService
{
    Task<Result<PagedResult<NotificationDto>>> GetMineAsync(bool unreadOnly, int page, int pageSize, CancellationToken ct);
    Task<Result<Unit>> MarkAsReadAsync(MarkAsReadRequest req, CancellationToken ct);
}

internal sealed class NotificationsApiService(HttpClient http)
    : BaseApiService(http), INotificationsApiService
{
    public Task<Result<PagedResult<NotificationDto>>> GetMineAsync(bool unreadOnly, int page, int pageSize, CancellationToken ct) =>
        GetAsync<PagedResult<NotificationDto>>($"api/notifications?unreadOnly={unreadOnly}&page={page}&pageSize={pageSize}", ct);

    public Task<Result<Unit>> MarkAsReadAsync(MarkAsReadRequest req, CancellationToken ct) =>
        PostAsync("api/notifications/mark-as-read", req, ct);   // → Result<Unit>
}

Verb-helpers (protected en BaseApiService)

Comportamiento del núcleo:

• 2xx con body → Result.Success. Body JSON inválido o null → Failure(Unexpected) (deserialization_error / empty_response).
• 204 / vacío en overload Unit → Success(Unit.Value).
• 4xx/5xx → deserializa ProblemDetails → Result.Failure(DomainError) (Type/Code/Message/Metadata recuperados).
• Transporte / timeout → Failure(Unexpected, "transport_error"). La cancelación real del CancellationToken del llamador sí propaga.
• JSON: default web (camelCase, case-insensitive) + enums como string. Deben coincidir con las options del API. Overridable por ctor.

Consumo del resultado

var result = await notifications.GetMineAsync(unreadOnly: true, 1, 20, ct);
if (result.IsSuccess)
    Render(result.Value);
else
    ShowError(result.Error.Message);   // result.Error : DomainError (Code, Message, Type, Metadata)

Autenticación

El paquete provee IAccessTokenProvider (lo implementa la app) + BearerTokenHandler:

services.AddMpsApiClientCore();                              // registra BearerTokenHandler
services.AddMpsAccessTokenProvider<OboAccessTokenProvider>();// tu impl
services.AddHttpClient<INotificationsApiService, NotificationsApiService>(c => c.BaseAddress = apiBaseUrl)
        .AddHttpMessageHandler<BearerTokenHandler>()
        .AddStandardResilienceHandler();                    // Polly — decisión tuya, no del paquete

⚠ Contrato del provider. IHttpClientFactory poolea los handlers (~2 min), así que la instancia de IAccessTokenProvider se reusa entre requests/usuarios. Tu impl debe leer el usuario actual en cada GetAccessTokenAsync (fuente context-dynamic), no cachear en campos.

• API/MVC/Razor Pages: ITokenAcquisition.GetAccessTokenForUserAsync funciona — IHttpContextAccessor es AsyncLocal.
• MAUI: MSAL AcquireTokenSilent/Interactive (PublicClientApplication singleton).
• 🔴 Blazor Server (InteractiveServer): las llamadas desde componentes interactivos corren en el circuit sin HttpContext → OBO vía ITokenAcquisition falla, y el handler pooleado no ve el circuit. Obtené el token por un mecanismo circuit-safe: adquirirlo en el servicio tipado (circuit scope) y attachearlo per-call, un provider sobre AuthenticationStateProvider + token store server-side, o Microsoft.Identity.Web.IDownstreamApi.

Contrato de errores (round-trip)

Simétrico a MPS.BuildingBlocks.AspNetCore.ProblemDetailsMapper (garantizado por test):

ErrorType: Validation(400) · Unauthorized(401) · Forbidden(403) · NotFound(404) · Conflict/Concurrency(409) · Unexpected(500).

Versiones

v0.1.0 — Release inicial

Marker IBaseApiService, BaseApiService (verb-helpers Result-based, nunca lanza), mapeo inverso ProblemDetails→Result<DomainError>, IAccessTokenProvider + BearerTokenHandler, DI mínimo (AddMpsApiClientCore, AddMpsAccessTokenProvider<T>). Depende de Cayaqui.MPS.BuildingBlocks 0.4.0.