package cloud.nstart.terravault.ordinis.restapi.service;

import java.util.Optional;

/**
 * Phase 2 contract: resolve sub → user info via Keycloak Admin API. The
 * implementation (Phase 2) will be an HTTP client using a service-account
 * client + role {@code view-users} on realm {@code nstart}.
 *
 * <p>{@link UserDisplayService} consumes this as an optional dependency —
 * if no bean exists in the context, the third resolve tier is skipped and
 * UserCell falls back to short UUID. This keeps the Phase 1 (DB cache only)
 * deployment runnable without Keycloak admin creds.
 *
 * <p>Implementations must throw {@link RuntimeException} on transient errors
 * (network, 5xx) so the caller can log and continue. Return {@link Optional#empty()}
 * for definitive 404 — sub does not exist in the realm.
 */
public interface KeycloakUserResolver {

  Optional<KeycloakUser> findById(String sub);

  record KeycloakUser(String sub, String preferredUsername, String name, String email) {}
}
