Cayaqui.ApiClient 0.4.21

Cayaqui.ApiClient

Cliente HTTP tipado y Result-based para consumir APIs Cayaqui 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.ApiClient" Version="0.2.0" />

Depende de Cayaqui.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 Cayaqui.ApiClient;
using Cayaqui.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.AddCayaquiApiClientCore();                              // registra BearerTokenHandler
services.AddCayaquiAccessTokenProvider<OboAccessTokenProvider>();// tu impl
services.AddHttpClient<INotificationsApiService, NotificationsApiService>(c => c.BaseAddress = apiBaseUrl)
        .AddHttpMessageHandler<BearerTokenHandler>()
        .AddStandardResilienceHandler();                    // Polly — decisión tuya, no del paquete

Aspire / service discovery

El cliente es scheme-agnóstico (usa URIs relativas contra tu HttpClient), así que funciona con service discovery sin wrapper — seteá la BaseAddress al nombre del recurso y agregá .AddServiceDiscovery():

builder.Services.AddServiceDiscovery();
builder.Services.AddCayaquiApiClientCore();
builder.Services.AddCayaquiAccessTokenProvider<TokenProvider>();
builder.Services.AddHttpClient<INotificationsApiService, NotificationsApiService>(
        c => c.BaseAddress = new("https+http://daica-api"))   // service discovery, no URL hardcodeada
    .AddHttpMessageHandler<BearerTokenHandler>()
    .AddServiceDiscovery();

⚠ 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 Cayaqui.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 (AddCayaquiApiClientCore, AddCayaquiAccessTokenProvider<T>). Depende de Cayaqui.BuildingBlocks 0.4.0.