package ca.cdr.test.app.clients;
/*-
 * #%L
 * Smile CDR - CDR
 * %%
 * Copyright (C) 2016 - 2026 Smile CDR, Inc.
 * %%
 * All rights reserved.
 * #L%
 */

import ca.cdr.api.model.enm.ClientStatusFilterEnum;
import ca.cdr.api.model.json.AuditEventsJson;
import ca.cdr.api.model.json.CdaJson.CdaTemplateJson;
import ca.cdr.api.model.json.CdaJson.CdaTemplateRequestJson;
import ca.cdr.api.model.json.CdaJson.CdaTemplateResponseJson;
import ca.cdr.api.model.json.CdaJson.CdaTemplateViewAllResponseJson;
import ca.cdr.api.model.json.EtlImportProcessFileResponseJson;
import ca.cdr.api.model.json.LoggerConfigJson;
import ca.cdr.api.model.json.MdmAlgorithmsListJson;
import ca.cdr.api.model.json.MdmMetricsJson;
import ca.cdr.api.model.json.OAuth2ClientDetailsJson;
import ca.cdr.api.model.json.OAuth2ClientsJson;
import ca.cdr.api.model.json.OAuth2KeystoreJson;
import ca.cdr.api.model.json.OAuth2KeystoresJson;
import ca.cdr.api.model.json.OAuth2RevokeAllWithScopeResponseJson;
import ca.cdr.api.model.json.OAuth2ServerJson;
import ca.cdr.api.model.json.OAuth2ServersJson;
import ca.cdr.api.model.json.OAuth2WritableClientDetailsJson;
import ca.cdr.api.model.json.PrivacyNoticeAcceptRequestJson;
import ca.cdr.api.model.json.PrivacyNoticeAcceptanceJson;
import ca.cdr.api.model.json.PrivacyNoticeJson;
import ca.cdr.api.model.json.PrivacyNoticeStatusJson;
import ca.cdr.api.model.json.TransactionLogEventCodesJson;
import ca.cdr.api.model.json.TransactionLogEventsJson;
import ca.cdr.api.model.json.UserDetailsJson;
import ca.cdr.api.model.json.batch2json.AllBatch2JobInstancesJson;
import ca.cdr.api.model.json.batch2json.Batch2JobInstanceJson;
import ca.cdr.api.model.json.batch2json.Batch2JobInstancesJson;
import ca.cdr.test.app.clients.common.HttpClientOwnership;
import ca.cdr.test.app.clients.common.RequestFactoryUtil;
import ca.cdr.test.app.clients.common.SmileTestHttpClient;
import ca.cdr.test.model.NodeConfigurations;
import ca.uhn.fhir.context.FhirContext;
import ca.uhn.fhir.context.FhirVersionEnum;
import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import jakarta.annotation.Nonnull;
import jakarta.annotation.Nullable;
import org.apache.commons.lang3.Validate;
import org.hl7.fhir.instance.model.api.IBaseParameters;
import org.hl7.fhir.instance.model.api.IBaseResource;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.core.ParameterizedTypeReference;
import org.springframework.http.MediaType;
import org.springframework.http.client.HttpComponentsClientHttpRequestFactory;
import org.springframework.http.client.support.BasicAuthenticationInterceptor;
import org.springframework.util.LinkedMultiValueMap;
import org.springframework.util.MultiValueMap;
import org.springframework.web.client.HttpClientErrorException;
import org.springframework.web.client.RestClient;
import org.springframework.web.client.RestClientException;
import tools.jackson.core.JacksonException;
import tools.jackson.databind.json.JsonMapper;

import java.time.Duration;
import java.util.Map;
import java.util.Objects;
import java.util.Optional;
import java.util.Set;

import static org.testcontainers.shaded.org.awaitility.Awaitility.await;

// Many new methods generated by Claude Sonnet 3.7

/**
 * AdminJsonRestClient is a client for the Admin API of the CDR.
 * It currently supports anonymous and http-basic authentication.
 */
public class AdminJsonRestClient implements AutoCloseable {
        private static final Logger ourLog = LoggerFactory.getLogger(AdminJsonRestClient.class);
        /**
         * Converts between models and trees the way the client's message converter reads and writes them, except that
         * an unknown property fails the conversion.
         */
        private static final JsonMapper ourJsonMapper = JsonMapper.builderWithJackson2Defaults().build();

        private static final Duration DEFAULT_TIMEOUT = Duration.ofSeconds(90);
        /**
         * Package-private and non-final so tests can inject a smaller poll interval to exercise multi-iteration
         * loop semantics without introducing a public setter on the production API.
         */
        static Duration POLL_INTERVAL = Duration.ofMillis(500);
        private static final String TARGET_STATUS = "STARTED";
        private static final String FAILED_TO_START = "FAILED_TO_START";
        private static final String FAILED_TO_STOP = "FAILED_TO_STOP";
        private static final String NOT_PRESENT = "<NOT_PRESENT>";
        private static final String NO_PROCESSES = "<NO_PROCESSES>";
        private static final String NEVER_OBSERVED = "<NEVER_OBSERVED>";

        final RestClient myRestClient;

        /**
         * Package-private hook so tests can deterministically observe and control the poll-loop sleep
         * (e.g. signal a latch when the worker enters the sleep branch, then perform a real interruptible
         * {@link Thread#sleep(long)}). Production code uses {@link Thread#sleep(long)} directly.
         */
        @FunctionalInterface
        interface InterruptibleSleeper {
                void sleep(long theMillis) throws InterruptedException;
        }

        InterruptibleSleeper mySleeper = Thread::sleep;

        /**
         * The client this one issues on, and whether closing this client should release it.
         * {@literal null} for a client built from a {@link RestClient} directly, which brought no
         * connection pool of its own.
         */
        private final HttpClientOwnership myOwnership;

        AdminJsonRestClient(RestClient theRestClient) {
                this(theRestClient, null);
        }

        private AdminJsonRestClient(RestClient theRestClient, @Nullable HttpClientOwnership theOwnership) {
                myOwnership = theOwnership;
                myRestClient = theRestClient;
        }

        /**
         * Opens a client authenticating as the given user, over a connection pool of its own.
         * <p>
         * The caller owns the pool: open this in a try-with-resources block, or close it from an
         * {@code @AfterAll} when it is a field. Use
         * {@link #issuingOn(SmileTestHttpClient, String, String, String)} instead where a client to
         * issue on already exists.
         *
         * @param theBaseUrl the Admin JSON base URL, including port
         * @param theUsername the user to authenticate as
         * @param thePassword that user's password
         */
        public static @Nonnull AdminJsonRestClient open(
                        @Nonnull String theBaseUrl, @Nonnull String theUsername, @Nonnull String thePassword) {
                HttpClientOwnership ownership = HttpClientOwnership.resolve(null);

                return authenticatedClient(ownership, theBaseUrl, theUsername, thePassword);
        }

        /**
         * Opens a client sending no credentials, over a connection pool of its own.
         * <p>
         * The caller owns the pool — see {@link #open(String, String, String)}.
         *
         * @param theBaseUrl the Admin JSON base URL, including port
         */
        public static @Nonnull AdminJsonRestClient openAnonymous(@Nonnull String theBaseUrl) {
                HttpClientOwnership ownership = HttpClientOwnership.resolve(null);

                return new AdminJsonRestClient(
                        builderForUrlWithJsonDefault(theBaseUrl, ownership.client()).build(), ownership);
        }

        /**
         * Builds a client that issues its requests on {@code theHttpClient}, sharing that client's
         * connection pool and cookie store with everything else built over it. A harness passes its own
         * client here so that a session established through this client is visible to the harness's
         * other clients, and so that {@code clearCookies()} reaches this client too.
         * <p>
         * The pool stays the caller's: {@link #close()} leaves it open, so there is nothing here for the
         * caller to release. Use {@link #open(String, String, String)} to build a pool of your own.
         *
         * @param theHttpClient the client to issue on, which the caller keeps ownership of
         * @param theBaseUrl the Admin JSON base URL, including port
         * @param theUsername the user to authenticate as
         * @param thePassword that user's password
         */
        public static @Nonnull AdminJsonRestClient issuingOn(
                        @Nonnull SmileTestHttpClient theHttpClient,
                        @Nonnull String theBaseUrl,
                        @Nonnull String theUsername,
                        @Nonnull String thePassword) {
                return authenticatedClient(
                        HttpClientOwnership.resolve(theHttpClient), theBaseUrl, theUsername, thePassword);
        }

        private static @Nonnull AdminJsonRestClient authenticatedClient(
                        @Nonnull HttpClientOwnership theOwnership,
                        @Nonnull String theBaseUrl,
                        @Nonnull String theUsername,
                        @Nonnull String thePassword) {
                RestClient restClient = builderForUrlWithJsonDefault(theBaseUrl, theOwnership.client())
                        .requestInterceptor(new BasicAuthenticationInterceptor(theUsername, thePassword))
                        .build();

                return new AdminJsonRestClient(restClient, theOwnership);
        }

        /**
         * @deprecated Use {@link #open(String, String, String)}, whose name says that the client owns the
         *    connection pool it returns and that the caller has to close it.
         */
        @Deprecated(since = "2026.11.R01", forRemoval = true)
        public static @Nonnull AdminJsonRestClient build(
                        @Nonnull String theBaseUrl, @Nonnull String theUsername, @Nonnull String thePassword) {
                return open(theBaseUrl, theUsername, thePassword);
        }

        /**
         * @deprecated Use {@link #openAnonymous(String)}, whose name says that the client owns the
         *    connection pool it returns and that the caller has to close it.
         */
        @Deprecated(since = "2026.11.R01", forRemoval = true)
        public static @Nonnull AdminJsonRestClient buildAnonymous(@Nonnull String theBaseUrl) {
                return openAnonymous(theBaseUrl);
        }

        private static @Nonnull RestClient.Builder builderForUrlWithJsonDefault(
                        String theBaseUrl, @Nonnull SmileTestHttpClient theHttpClient) {
                HttpComponentsClientHttpRequestFactory requestFactory = RequestFactoryUtil.wrap(theHttpClient);

                return RestClient.builder()
                        .baseUrl(theBaseUrl)
                        .requestFactory(requestFactory)
                        .configureMessageConverters(ClientMessageConverters::configure)
                        // This sets the default content type to JSON, but allows the actual request to override it.
                        .defaultRequest(r -> r.accept(MediaType.APPLICATION_JSON));
        }




        @Nonnull
        public UserDetailsJson userCreate(String theNode, String theModuleId, UserDetailsJson userDetails) {
                Validate.notEmpty(theNode, "Node ID is required");
                Validate.notEmpty(theModuleId, "Module ID is required");
                Validate.notNull(userDetails, "User does not have an assigned pid.  Use userCreate() to create users.");
                UserDetailsJson result = myRestClient
                        .post()
                        .uri("user-management/{nodeId}/{moduleId}", theNode, theModuleId)
                        .body(userDetails)
                        .retrieve()
                        .body(UserDetailsJson.class);
                return Objects.requireNonNull(result);
        }

        @Nonnull
        public UserDetailsJson userUpdate(UserDetailsJson theUserDetails) {
                Validate.notEmpty(theUserDetails.getNodeId(), "Node ID is required");
                Validate.notEmpty(theUserDetails.getModuleId(), "Module ID is required");
                Validate.notNull(
                        theUserDetails.getPid(), "User does not have an assigned pid.  Use userCreate() to create users.");
                UserDetailsJson result = myRestClient
                        .put()
                        .uri(
                                "user-management/{nodeId}/{moduleId}/{userId}",
                                theUserDetails.getNodeId(),
                                theUserDetails.getModuleId(),
                                theUserDetails.getPid())
                        .body(theUserDetails)
                        .retrieve()
                        .body(UserDetailsJson.class);
                return Objects.requireNonNull(result);
        }

        /**
         * @param theResponseType the type to read the response as: Jackson 3's {@link tools.jackson.databind.JsonNode},
         *    or a model class to bind it to
         */
        @Nonnull
        public <T> T userFindByUsername(String theNodeId, String theModuleId, String theUsername, @Nonnull Class<T> theResponseType) {
                Validate.notEmpty(theNodeId, "Node ID is required");
                Validate.notEmpty(theModuleId, "Module ID is required");
                Validate.notEmpty(theUsername, "username is required");
                T result = myRestClient
                        .get()
                        .uri("user-management/{nodeId}/{moduleId}?searchTerm={username}", theNodeId, theModuleId, theUsername)
                        .retrieve()
                        .body(theResponseType);
                return Objects.requireNonNull(result);
        }

        /**
         * @deprecated Use {@link #userFindByUsername(String, String, String, Class)} with Jackson 3's
         *    {@link tools.jackson.databind.JsonNode}. Jackson 2 support will be removed in a later release.
         */
        @Deprecated(since = "2026.11.R01", forRemoval = true)
        @Nonnull
        public JsonNode userFindByUsername(String theNodeId, String theModuleId, String theUsername) {
                return userFindByUsername(theNodeId, theModuleId, theUsername, JsonNode.class);
        }

        /**
         * Find users by username and return the result as a String that can be used with ObjectMapper
         *
         * @param theNodeId   The node ID
         * @param theModuleId The module ID
         * @param theUsername The username to search for
         * @return The JSON string representation of the result
         */
        @Nonnull
        public String userFindByUsernameAsString(String theNodeId, String theModuleId, String theUsername) {
                return userFindByUsername(theNodeId, theModuleId, theUsername, tools.jackson.databind.JsonNode.class)
                        .toString();
        }

        /**
         * @param theResponseType the type to read the response as: Jackson 3's {@link tools.jackson.databind.JsonNode},
         *    or a model class to bind it to
         */
        @Nonnull
        public <T> T userFindAll(String theNodeId, String theModuleId, int thePageSize, @Nonnull Class<T> theResponseType) {
                Validate.notEmpty(theNodeId, "Node ID is required");
                Validate.notEmpty(theModuleId, "Module ID is required");
                T result = myRestClient
                        .get()
                        .uri("user-management/{nodeId}/{moduleId}?pageSize={pageSize}", theNodeId, theModuleId, thePageSize)
                        .retrieve()
                        .body(theResponseType);
                return Objects.requireNonNull(result);
        }

        /**
         * @deprecated Use {@link #userFindAll(String, String, int, Class)} with Jackson 3's
         *    {@link tools.jackson.databind.JsonNode}. Jackson 2 support will be removed in a later release.
         */
        @Deprecated(since = "2026.11.R01", forRemoval = true)
        @Nonnull
        public JsonNode userFindAll(String theNodeId, String theModuleId, int thePageSize) {
                return userFindAll(theNodeId, theModuleId, thePageSize, JsonNode.class);
        }

        /**
         * Find all users and return the result as a String that can be used with ObjectMapper
         *
         * @param theNodeId   The node ID
         * @param theModuleId The module ID
         * @param thePageSize The page size
         * @return The JSON string representation of the result
         */
        @Nonnull
        public String userFindAllAsString(String theNodeId, String theModuleId, int thePageSize) {
                return userFindAll(theNodeId, theModuleId, thePageSize, tools.jackson.databind.JsonNode.class)
                        .toString();
        }

        @Nonnull
        public UserDetailsJson userFetchByPid(String theNodeId, String theModuleId, Long thePid) {
                Validate.notEmpty(theNodeId, "Node ID is required");
                Validate.notEmpty(theModuleId, "Module ID is required");
                Validate.notNull(thePid, "User does not have an assigned pid.  Use userCreate() to create users.");
                UserDetailsJson result = myRestClient
                        .get()
                        .uri("user-management/{nodeId}/{moduleId}/{userId}", theNodeId, theModuleId, thePid)
                        .retrieve()
                        .body(UserDetailsJson.class);
                return Objects.requireNonNull(result);
        }

        /**
         * Get the module configuration for a specific node and module
         *
         * @param theResponseType the type to read the response as: Jackson 3's {@link tools.jackson.databind.JsonNode},
         *    or a model class to bind it to
         */
        @Nonnull
        public <T> T getModuleConfig(String theNodeId, String theModuleId, @Nonnull Class<T> theResponseType) {
                Validate.notEmpty(theNodeId, "Node ID is required");
                Validate.notEmpty(theModuleId, "Module ID is required");
                T result = myRestClient
                        .get()
                        .uri("module-config/{nodeId}/{moduleId}", theNodeId, theModuleId)
                        .retrieve()
                        .body(theResponseType);
                return Objects.requireNonNull(result);
        }

        /**
         * @deprecated Use {@link #getModuleConfig(String, String, Class)} with Jackson 3's
         *    {@link tools.jackson.databind.JsonNode}. Jackson 2 support will be removed in a later release.
         */
        @Deprecated(since = "2026.11.R01", forRemoval = true)
        @Nonnull
        public JsonNode getModuleConfig(String theNodeId, String theModuleId) {
                return getModuleConfig(theNodeId, theModuleId, JsonNode.class);
        }

        /**
         * @param theResponseType the type to read the response as: Jackson 3's {@link tools.jackson.databind.JsonNode},
         *    or a model class to bind it to
         */
        public <T> T getModuleInterceptors(String theNodeId, String theModuleId, @Nonnull Class<T> theResponseType) {
                Validate.notEmpty(theNodeId, "Node ID is required");
                Validate.notEmpty(theModuleId, "Module ID is required");
                T result = myRestClient
                        .get()
                        .uri("module-config/{nodeId}/{moduleId}/interceptors", theNodeId, theModuleId)
                        .retrieve()
                        .body(theResponseType);
                return Objects.requireNonNull(result);
        }

        /**
         * @deprecated Use {@link #getModuleInterceptors(String, String, Class)} with Jackson 3's
         *    {@link tools.jackson.databind.JsonNode}. Jackson 2 support will be removed in a later release.
         */
        @Deprecated(since = "2026.11.R01", forRemoval = true)
        public JsonNode getModuleInterceptors(String theNodeId, String theModuleId) {
                return getModuleInterceptors(theNodeId, theModuleId, JsonNode.class);
        }

        /**
         * Update the configuration for a specific module. When either {@code theRestart} or {@code theReload} is set,
         * the client blocks until the module reports {@value #TARGET_STATUS} (up to {@link #DEFAULT_TIMEOUT}).
         * Use {@link #updateModuleConfig(String, String, tools.jackson.databind.JsonNode, boolean, boolean, boolean)} to
         * opt out of the wait.
         */
        @Nonnull
        public tools.jackson.databind.JsonNode updateModuleConfig(
                String theNodeId,
                String theModuleId,
                tools.jackson.databind.JsonNode theOptions,
                boolean theRestart,
                boolean theReload) {
                return updateModuleConfig(theNodeId, theModuleId, theOptions, theRestart, theReload, true, DEFAULT_TIMEOUT);
        }

        /**
         * Update the configuration for a specific module.
         *
         * @param theShouldWaitForRestart when {@code true} and either {@code theRestart} or {@code theReload} is set,
         *                                the client polls the admin status endpoint until the module reports
         *                                {@value #TARGET_STATUS}, up to {@link #DEFAULT_TIMEOUT}.
         */
        @Nonnull
        public tools.jackson.databind.JsonNode updateModuleConfig(
                String theNodeId,
                String theModuleId,
                tools.jackson.databind.JsonNode theOptions,
                boolean theRestart,
                boolean theReload,
                boolean theShouldWaitForRestart) {
                return updateModuleConfig(theNodeId, theModuleId, theOptions, theRestart, theReload, theShouldWaitForRestart, DEFAULT_TIMEOUT);
        }

        /**
         * Update the configuration for a specific module with a caller-supplied wait timeout.
         *
         * @param theShouldWaitForRestart when {@code true} and either {@code theRestart} or {@code theReload} is set,
         *                                the client polls the admin status endpoint until the module reports
         *                                {@value #TARGET_STATUS}, up to {@code theWaitTimeout}.
         * @param theWaitTimeout          the maximum duration to wait for the module to report {@value #TARGET_STATUS}
         *                                when {@code theShouldWaitForRestart} is {@code true}. Ignored otherwise.
         */
        @Nonnull
        public tools.jackson.databind.JsonNode updateModuleConfig(
                String theNodeId,
                String theModuleId,
                tools.jackson.databind.JsonNode theOptions,
                boolean theRestart,
                boolean theReload,
                boolean theShouldWaitForRestart,
                Duration theWaitTimeout) {
                return putModuleConfig(
                        theNodeId, theModuleId, theOptions, theRestart, theReload, theShouldWaitForRestart, theWaitTimeout,
                        tools.jackson.databind.JsonNode.class);
        }

        /**
         * @deprecated Use {@link #updateModuleConfig(String, String, tools.jackson.databind.JsonNode, boolean, boolean)}
         *    with Jackson 3's {@link tools.jackson.databind.JsonNode}. Jackson 2 support will be removed in a later release.
         */
        @Deprecated(since = "2026.11.R01", forRemoval = true)
        @Nonnull
        public JsonNode updateModuleConfig(
                String theNodeId,
                String theModuleId,
                JsonNode theOptions,
                boolean theRestart,
                boolean theReload) {
                return updateModuleConfig(theNodeId, theModuleId, theOptions, theRestart, theReload, true, DEFAULT_TIMEOUT);
        }

        /**
         * @deprecated Use
         *    {@link #updateModuleConfig(String, String, tools.jackson.databind.JsonNode, boolean, boolean, boolean)}
         *    with Jackson 3's {@link tools.jackson.databind.JsonNode}. Jackson 2 support will be removed in a later release.
         */
        @Deprecated(since = "2026.11.R01", forRemoval = true)
        @Nonnull
        public JsonNode updateModuleConfig(
                String theNodeId,
                String theModuleId,
                JsonNode theOptions,
                boolean theRestart,
                boolean theReload,
                boolean theShouldWaitForRestart) {
                return updateModuleConfig(theNodeId, theModuleId, theOptions, theRestart, theReload, theShouldWaitForRestart, DEFAULT_TIMEOUT);
        }

        /**
         * @deprecated Use
         *    {@link #updateModuleConfig(String, String, tools.jackson.databind.JsonNode, boolean, boolean, boolean, Duration)}
         *    with Jackson 3's {@link tools.jackson.databind.JsonNode}. Jackson 2 support will be removed in a later release.
         */
        @Deprecated(since = "2026.11.R01", forRemoval = true)
        @Nonnull
        public JsonNode updateModuleConfig(
                String theNodeId,
                String theModuleId,
                JsonNode theOptions,
                boolean theRestart,
                boolean theReload,
                boolean theShouldWaitForRestart,
                Duration theWaitTimeout) {
                return putModuleConfig(
                        theNodeId, theModuleId, theOptions, theRestart, theReload, theShouldWaitForRestart, theWaitTimeout,
                        JsonNode.class);
        }

        @Nonnull
        private <T> T putModuleConfig(
                String theNodeId,
                String theModuleId,
                Object theOptions,
                boolean theRestart,
                boolean theReload,
                boolean theShouldWaitForRestart,
                Duration theWaitTimeout,
                Class<T> theResponseType) {
                Validate.notEmpty(theNodeId, "Node ID is required");
                Validate.notEmpty(theModuleId, "Module ID is required");
                Validate.notNull(theOptions, "Options is required");

                T result =
                        myRestClient.put().uri("module-config/{nodeId}/{theModuleId}/set?restart={theRestart}&reload={theReload}", theNodeId, theModuleId, theRestart, theReload).body(theOptions).retrieve().body(theResponseType);

                if (theShouldWaitForRestart && (theRestart || theReload)) {
                        Validate.notNull(theWaitTimeout, "Wait timeout is required");
                        waitForModuleStarted(theNodeId, theModuleId, theWaitTimeout);
                }

                return Objects.requireNonNull(result);
        }

        /**
         * Request to start a module on all processes
         */
        @Nonnull
        private tools.jackson.databind.JsonNode startModule(String theNodeId, String theModuleId) {
                Validate.notEmpty(theNodeId, "Node ID is required");
                Validate.notEmpty(theModuleId, "Module ID is required");
                tools.jackson.databind.JsonNode result = myRestClient
                        .post()
                        .uri("module-config/{nodeId}/{moduleId}/start", theNodeId, theModuleId)
                        .retrieve()
                        .body(tools.jackson.databind.JsonNode.class);
                return Objects.requireNonNull(result);
        }

        /**
         * Request to stop a module on all processes
         * ModuleProcessesStatusChangeResponseJson
         *
         * @param theResponseType the type to read the response as: Jackson 3's {@link tools.jackson.databind.JsonNode},
         *    or a model class to bind it to
         */
        @Nonnull
        public <T> T stopModule(String theNodeId, String theModuleId, @Nonnull Class<T> theResponseType) {
                Validate.notEmpty(theNodeId, "Node ID is required");
                Validate.notEmpty(theModuleId, "Module ID is required");
                T result = myRestClient
                        .post()
                        .uri("module-config/{nodeId}/{moduleId}/stop", theNodeId, theModuleId)
                        .retrieve()
                        .body(theResponseType);
                return Objects.requireNonNull(result);
        }

        /**
         * @deprecated Use {@link #stopModule(String, String, Class)} with Jackson 3's
         *    {@link tools.jackson.databind.JsonNode}. Jackson 2 support will be removed in a later release.
         */
        @Deprecated(since = "2026.11.R01", forRemoval = true)
        @Nonnull
        public JsonNode stopModule(String theNodeId, String theModuleId) {
                return stopModule(theNodeId, theModuleId, JsonNode.class);
        }

        /**
         * Request to restart a module on all processes. Blocks until the module reports {@value #TARGET_STATUS}
         * (up to {@link #DEFAULT_TIMEOUT}). Use {@link #restartModule(String, String, boolean, Class)} to opt out of the wait.
         *
         * @param theResponseType the type to read the response as: Jackson 3's {@link tools.jackson.databind.JsonNode},
         *    or a model class to bind it to
         */
        @Nonnull
        public <T> T restartModule(String theNodeId, String theModuleId, @Nonnull Class<T> theResponseType) {
                return restartModule(theNodeId, theModuleId, true, DEFAULT_TIMEOUT, theResponseType);
        }

        /**
         * @deprecated Use {@link #restartModule(String, String, Class)} with Jackson 3's
         *    {@link tools.jackson.databind.JsonNode}. Jackson 2 support will be removed in a later release.
         */
        @Deprecated(since = "2026.11.R01", forRemoval = true)
        @Nonnull
        public JsonNode restartModule(String theNodeId, String theModuleId) {
                return restartModule(theNodeId, theModuleId, JsonNode.class);
        }

        /**
         * Request to restart a module on all processes.
         *
         * @param theShouldWaitForRestart when {@code true}, the client polls the admin status endpoint
         *                                until the module reports {@value #TARGET_STATUS},
         *                                up to {@link #DEFAULT_TIMEOUT}.
         *
         * @param theResponseType the type to read the response as: Jackson 3's {@link tools.jackson.databind.JsonNode},
         *    or a model class to bind it to
         */
        @Nonnull
        public <T> T restartModule(String theNodeId, String theModuleId, boolean theShouldWaitForRestart, @Nonnull Class<T> theResponseType) {
                return restartModule(theNodeId, theModuleId, theShouldWaitForRestart, DEFAULT_TIMEOUT, theResponseType);
        }

        /**
         * @deprecated Use {@link #restartModule(String, String, boolean, Class)} with Jackson 3's
         *    {@link tools.jackson.databind.JsonNode}. Jackson 2 support will be removed in a later release.
         */
        @Deprecated(since = "2026.11.R01", forRemoval = true)
        @Nonnull
        public JsonNode restartModule(String theNodeId, String theModuleId, boolean theShouldWaitForRestart) {
                return restartModule(theNodeId, theModuleId, theShouldWaitForRestart, JsonNode.class);
        }

        /**
         * Request to restart a module on all processes with a caller-supplied wait timeout.
         *
         * @param theShouldWaitForRestart when {@code true}, the client polls the admin status endpoint
         *                                until the module reports {@value #TARGET_STATUS},
         *                                up to {@code theWaitTimeout}.
         * @param theWaitTimeout          the maximum duration to wait for the module to report {@value #TARGET_STATUS}
         *                                when {@code theShouldWaitForRestart} is {@code true}. Ignored otherwise.
         *
         * @param theResponseType the type to read the response as: Jackson 3's {@link tools.jackson.databind.JsonNode},
         *    or a model class to bind it to
         */
        @Nonnull
        public <T> T restartModule(String theNodeId, String theModuleId, boolean theShouldWaitForRestart, Duration theWaitTimeout, @Nonnull Class<T> theResponseType) {
                Validate.notEmpty(theNodeId, "Node ID is required");
                Validate.notEmpty(theModuleId, "Module ID is required");
                T result = myRestClient
                        .post()
                        .uri("module-config/{nodeId}/{moduleId}/restart", theNodeId, theModuleId)
                        .retrieve()
                        .body(theResponseType);

                if (theShouldWaitForRestart) {
                        Validate.notNull(theWaitTimeout, "Wait timeout is required");
                        waitForModuleStarted(theNodeId, theModuleId, theWaitTimeout);
                }

                return Objects.requireNonNull(result);
        }

        /**
         * @deprecated Use {@link #restartModule(String, String, boolean, Duration, Class)} with Jackson 3's
         *    {@link tools.jackson.databind.JsonNode}. Jackson 2 support will be removed in a later release.
         */
        @Deprecated(since = "2026.11.R01", forRemoval = true)
        @Nonnull
        public JsonNode restartModule(String theNodeId, String theModuleId, boolean theShouldWaitForRestart, Duration theWaitTimeout) {
                return restartModule(theNodeId, theModuleId, theShouldWaitForRestart, theWaitTimeout, JsonNode.class);
        }

        /**
         * Package-private overload that accepts a custom timeout. Primarily intended for tests that need to
         * exercise the timeout branch without waiting 90 seconds.
         *
         * Polls {@link #getNodeStatuses(Class)} until the first process of the given module on the given node reports
         * {@value #TARGET_STATUS}, up to {@code theTimeout}. Throws {@link IllegalStateException} on timeout
         * or terminal failure ({@value #FAILED_TO_START} / {@value #FAILED_TO_STOP}).
         */
        void waitForModuleStarted(String theNodeId, String theModuleId, Duration theTimeout) {
                Validate.notEmpty(theNodeId, "Node ID is required");
                Validate.notEmpty(theModuleId, "Module ID is required");
                Validate.notNull(theTimeout, "Timeout is required");

                long deadlineNanos = System.nanoTime() + theTimeout.toNanos();
                int completedProbes = 0;
                String lastObservedStatus = NEVER_OBSERVED;
                RuntimeException lastException = null;
                int transientErrorCount = 0;

                while (true) {
                        ModuleStatusProbe probe = null;
                        try {
                                tools.jackson.databind.JsonNode statuses = getNodeStatuses(tools.jackson.databind.JsonNode.class);
                                probe = extractModuleProcessStatus(statuses, theNodeId, theModuleId);
                                completedProbes++;
                        } catch (RestClientException e) {
                                // Narrow catch: only Spring HTTP-layer transients (RestClientException covers ResourceAccessException,
                                // HttpServerErrorException, HttpClientErrorException, etc.). Programmer errors like NPE, IAE, ISE
                                // from extractModuleProcessStatus or elsewhere propagate up immediately so they aren't masked
                                // by a 90s timeout.
                                lastException = e;
                                transientErrorCount++;
                                ourLog.debug("Transient error while polling node statuses for module '{}' on node '{}' (transient #{}): {}",
                                        theModuleId, theNodeId, transientErrorCount, e.toString());
                        }

                        if (probe != null) {
                                lastObservedStatus = probe.presence();
                                if (probe.rawStatus() != null) {
                                        if (TARGET_STATUS.equals(probe.rawStatus())) {
                                                ourLog.debug("Module '{}' on node '{}' reported {} after {} completed probe(s)",
                                                        theModuleId, theNodeId, TARGET_STATUS, completedProbes);
                                                return;
                                        }
                                        if (probe.terminalFailure()) {
                                                // Throw terminal-failure OUTSIDE the try/catch above so it is never classified as transient.
                                                throw new IllegalStateException(String.format(
                                                        "Module '%s' on node '%s' reached terminal failure status '%s' after %d completed probe(s)",
                                                        theModuleId, theNodeId, probe.rawStatus(), completedProbes));
                                        }
                                }
                        }

                        if (System.nanoTime() >= deadlineNanos) {
                                String message = String.format(
                                        "Timed out after %d ms waiting for module '%s' on node '%s' to reach status '%s' (last observed status: %s, poll attempts: %d, transient errors: %d)",
                                        theTimeout.toMillis(), theModuleId, theNodeId, TARGET_STATUS, lastObservedStatus, completedProbes, transientErrorCount);
                                if (lastException != null) {
                                        // Use the FQN so subclasses (e.g. HttpServerErrorException$InternalServerError) still surface
                                        // the parent class name in the timeout message.
                                        String causeSummary = lastException.getClass().getName() + ": " + lastException.getMessage();
                                        throw new IllegalStateException(message + "; last error: " + causeSummary, lastException);
                                }
                                throw new IllegalStateException(message);
                        }

                        try {
                                mySleeper.sleep(POLL_INTERVAL.toMillis());
                        } catch (InterruptedException e) {
                                Thread.currentThread().interrupt();
                                throw new IllegalStateException(
                                        "Interrupted while waiting for module '" + theModuleId + "' on node '" + theNodeId + "' to start",
                                        e);
                        }
                }
        }

        /**
         * Result of probing the {@code node-statuses/complete} payload for a specific node/module.
         *
         * <p>The record stores only {@code rawStatus} and (when {@code rawStatus} is {@code null}) an
         * {@code absenceLabel} that explains why no status was observed ({@value #NOT_PRESENT} or
         * {@value #NO_PROCESSES}). The observability-friendly {@link #presence()} label and the
         * {@link #terminalFailure()} flag are derived from {@code rawStatus} so there is a single source
         * of truth and no two fields to keep in sync.
         *
         * @param rawStatus    the raw {@code processes[0].status} string, or {@code null} when the module row was
         *                     absent, the processes array was empty, or the status field was missing.
         * @param absenceLabel when {@code rawStatus} is {@code null}, one of {@value #NOT_PRESENT} or
         *                     {@value #NO_PROCESSES}. Ignored (and may be {@code null}) when {@code rawStatus}
         *                     is non-null.
         */
        private record ModuleStatusProbe(@Nullable String rawStatus, @Nullable String absenceLabel) {
                boolean terminalFailure() {
                        return FAILED_TO_START.equals(rawStatus) || FAILED_TO_STOP.equals(rawStatus);
                }

                String presence() {
                        return rawStatus != null ? rawStatus : absenceLabel;
                }
        }

        /**
         * Walk the raw {@code node-statuses/complete} payload to extract the first process status for the given
         * {@code nodeId} / {@code moduleId}.
         *
         * Expected shape: {@code { "nodes": [ { "nodeId": "...", "modules": [ { "moduleId": "...", "processes": [ { "status": "..." } ] } ] } ] } }.
         */
        @Nonnull
        private static ModuleStatusProbe extractModuleProcessStatus(
                tools.jackson.databind.JsonNode theStatuses, String theNodeId, String theModuleId) {
                if (theStatuses == null) {
                        return new ModuleStatusProbe(null, NOT_PRESENT);
                }
                tools.jackson.databind.JsonNode nodes = theStatuses.get("nodes");
                if (nodes == null || !nodes.isArray()) {
                        return new ModuleStatusProbe(null, NOT_PRESENT);
                }
                for (tools.jackson.databind.JsonNode node : nodes) {
                        tools.jackson.databind.JsonNode nodeId = node.get("nodeId");
                        if (nodeId == null || !theNodeId.equals(nodeId.asString())) {
                                continue;
                        }
                        tools.jackson.databind.JsonNode modules = node.get("modules");
                        if (modules == null || !modules.isArray()) {
                                continue;
                        }
                        for (tools.jackson.databind.JsonNode module : modules) {
                                tools.jackson.databind.JsonNode moduleId = module.get("moduleId");
                                if (moduleId == null || !theModuleId.equals(moduleId.asString())) {
                                        continue;
                                }
                                tools.jackson.databind.JsonNode processes = module.get("processes");
                                if (processes == null || !processes.isArray() || processes.isEmpty()) {
                                        // Node+module matched, but no processes are reporting yet.
                                        return new ModuleStatusProbe(null, NO_PROCESSES);
                                }
                                tools.jackson.databind.JsonNode status = processes.get(0).get("status");
                                if (status == null) {
                                        return new ModuleStatusProbe(null, NO_PROCESSES);
                                }
                                return new ModuleStatusProbe(status.asString(), null);
                        }
                }
                return new ModuleStatusProbe(null, NOT_PRESENT);
        }

        /**
         * Get a list of restore points for a node
         *
         * @param theResponseType the type to read the response as: Jackson 3's {@link tools.jackson.databind.JsonNode},
         *    or a model class to bind it to
         */
        @Nonnull
        public <T> T getRestorePoints(
                String theNodeId, @Nullable String theVersion, @Nullable String theFromDate, @Nullable String theToDate, int theOffset, int theCount,
                        @Nonnull Class<T> theResponseType) {
                Validate.notEmpty(theNodeId, "Node ID is required");

                T result = myRestClient.get()
                        .uri("module-config/{theNodeId}/restorePoints", builder->{
                                builder.queryParamIfPresent("version", Optional.ofNullable(theVersion));
                                builder.queryParamIfPresent("from", Optional.ofNullable(theFromDate));
                                builder.queryParamIfPresent("to", Optional.ofNullable(theToDate));
                                builder.queryParam("offset", theOffset);
                                builder.queryParam("count", theCount);
                                return builder.build(theNodeId);
                        }).retrieve().body(theResponseType);

                return Objects.requireNonNull(result);
        }

        /**
         * @deprecated Use {@link #getRestorePoints(String, String, String, String, int, int, Class)} with Jackson 3's
         *    {@link tools.jackson.databind.JsonNode}. Jackson 2 support will be removed in a later release.
         */
        @Deprecated(since = "2026.11.R01", forRemoval = true)
        @Nonnull
        public JsonNode getRestorePoints(
                String theNodeId, @Nullable String theVersion, @Nullable String theFromDate, @Nullable String theToDate, int theOffset, int theCount) {
                return getRestorePoints(theNodeId, theVersion, theFromDate, theToDate, theOffset, theCount, JsonNode.class);
        }

        /**
         * Get a specific restore point
         *
         * @param theResponseType the type to read the response as: Jackson 3's {@link tools.jackson.databind.JsonNode},
         *    or a model class to bind it to
         */
        @Nonnull
        public <T> T getRestorePoint(String theNodeId, Long theId, @Nonnull Class<T> theResponseType) {
                Validate.notEmpty(theNodeId, "Node ID is required");
                Validate.notNull(theId, "Restore point ID is required");
                T result = myRestClient
                        .get()
                        .uri("module-config/{nodeId}/restorePoints/{id}", theNodeId, theId)
                        .retrieve()
                        .body(theResponseType);
                return Objects.requireNonNull(result);
        }

        /**
         * @deprecated Use {@link #getRestorePoint(String, Long, Class)} with Jackson 3's
         *    {@link tools.jackson.databind.JsonNode}. Jackson 2 support will be removed in a later release.
         */
        @Deprecated(since = "2026.11.R01", forRemoval = true)
        @Nonnull
        public JsonNode getRestorePoint(String theNodeId, Long theId) {
                return getRestorePoint(theNodeId, theId, JsonNode.class);
        }

        /**
         * Restore the system to a specific restore point
         */
        public void restoreSystem(String theNodeId, Long theRestorePointId) {
                Validate.notEmpty(theNodeId, "Node ID is required");
                Validate.notNull(theRestorePointId, "Restore point ID is required");
                myRestClient
                        .post()
                        .uri("module-config/{nodeId}/restorePoints/{id}/restore", theNodeId, theRestorePointId)
                        .retrieve()
                        .toBodilessEntity();
        }

        /**
         * Get health checks for all modules
         *
         * @param theResponseType the type to read the response as: Jackson 3's {@link tools.jackson.databind.JsonNode},
         *    or a model class to bind it to
         */
        @Nonnull
        public <T> T getHealthChecks(boolean theOnlyRunning, @Nonnull Class<T> theResponseType) {
                T result = myRestClient.get().uri("runtime-status/node-statuses/health-checks?onlyRunning={onlyRunning}", theOnlyRunning).retrieve().body(theResponseType);
                return Objects.requireNonNull(result);
        }

        /**
         * @deprecated Use {@link #getHealthChecks(boolean, Class)} with Jackson 3's
         *    {@link tools.jackson.databind.JsonNode}. Jackson 2 support will be removed in a later release.
         */
        @Deprecated(since = "2026.11.R01", forRemoval = true)
        @Nonnull
        public JsonNode getHealthChecks(boolean theOnlyRunning) {
                return getHealthChecks(theOnlyRunning, JsonNode.class);
        }

        /**
         * Get node statuses
         *
         * @param theResponseType the type to read the response as: Jackson 3's {@link tools.jackson.databind.JsonNode},
         *    or a model class to bind it to
         */
        @Nonnull
        public <T> T getNodeStatuses(@Nonnull Class<T> theResponseType) {
                T result = myRestClient
                        .get()
                        .uri("runtime-status/node-statuses/complete")
                        .retrieve()
                        .body(theResponseType);
                return Objects.requireNonNull(result);
        }

        /**
         * @deprecated Use {@link #getNodeStatuses(Class)} with Jackson 3's
         *    {@link tools.jackson.databind.JsonNode}. Jackson 2 support will be removed in a later release.
         */
        @Deprecated(since = "2026.11.R01", forRemoval = true)
        @Nonnull
        public JsonNode getNodeStatuses() {
                return getNodeStatuses(JsonNode.class);
        }

        /**
         * Cancel a batch job
         */
        public void cancelBatchJob(String theModuleId, String theJobId) {
                Validate.notEmpty(theModuleId, "Module ID is required");
                Validate.notEmpty(theJobId, "Job ID is required");
                myRestClient
                        .get()
                        .uri("batch2-jobs/modules/{moduleId}/jobs/{jobId}/cancel", theModuleId, theJobId)
                        .retrieve()
                        .toBodilessEntity();
        }

        /**
         * Get all module IDs that support batch jobs
         */
        @Nonnull
        public String[] getAllBatchJobModuleIds() {
                String[] result = myRestClient
                        .get()
                        .uri("batch2-jobs/modules")
                        .retrieve()
                        .body(String[].class);
                return Objects.requireNonNull(result);
        }

        /**
         * Get a specific batch job instance by ID
         */
        @Nonnull
        public Batch2JobInstanceJson getBatchJobInstance(String theModuleId, String theJobId) {
                Validate.notEmpty(theModuleId, "Module ID is required");
                Validate.notEmpty(theJobId, "Job ID is required");
                Batch2JobInstanceJson result = myRestClient
                        .get()
                        .uri("batch2-jobs/modules/{moduleId}/jobs/{jobId}", theModuleId, theJobId)
                        .retrieve()
                        .body(Batch2JobInstanceJson.class);
                return Objects.requireNonNull(result);
        }

        @Nonnull
        public AllBatch2JobInstancesJson getBatchJobInstances(String theModuleId) {
                return getBatchJobInstances(theModuleId, new LinkedMultiValueMap<>());
        }

        @Nonnull
        public AllBatch2JobInstancesJson getBatchJobInstances(
                String theModuleId, @Nonnull MultiValueMap<String, String> theQueryParams) {
                Validate.notEmpty(theModuleId, "Module ID is required");

                AllBatch2JobInstancesJson result = myRestClient
                        .get()
                        .uri("batch2-jobs/modules/{moduleId}", builder -> builder.queryParams(theQueryParams).build(theModuleId))
                        .retrieve()
                        .body(AllBatch2JobInstancesJson.class);
                return Objects.requireNonNull(result);
        }

        @Nonnull
        public Batch2JobInstancesJson getBatchJobInstancesByName(
                String theModuleId, String theJobDefinitionId, @Nullable Boolean theEnded, int theStart, int theCount) {
                Validate.notEmpty(theModuleId, "Module ID is required");
                Validate.notEmpty(theJobDefinitionId, "Job definition ID is required");

                Batch2JobInstancesJson result = myRestClient
                        .get()
                        .uri("batch2-jobs/modules/{moduleId}/names/{name}/jobs", builder -> {
                                builder.queryParam("start", theStart);
                                builder.queryParam("count", theCount);
                                builder.queryParamIfPresent("ended", Optional.ofNullable(theEnded));
                                return builder.build(theModuleId, theJobDefinitionId);
                        })
                        .retrieve()
                        .body(Batch2JobInstancesJson.class);
                return Objects.requireNonNull(result);
        }

        /**
         * Process a bulk ETL import file
         * @param theModuleId the id of the etl module to target
         * @param theFilename the optional filename as a hint for the import process
         * @param theContent the body of the csv file to import
         */
        @Nonnull
        public EtlImportProcessFileResponseJson processBulkImport(@Nonnull String theModuleId, @Nullable String theFilename, @Nonnull String theContent) {
                return processBulkImport(theModuleId, theFilename, null, theContent);
        }

        /**
         * Process a bulk ETL import file
         * @param theModuleId the id of the etl module to target
         * @param theFilename the optional filename as a hint for the import process
         * @param theUserJobType the optional job type to use for the import process
         * @param theContent the body of the csv file to import
         */
        @Nonnull
        public EtlImportProcessFileResponseJson processBulkImport(@Nonnull String theModuleId, @Nullable String theFilename, @Nullable String theUserJobType, @Nonnull String theContent) {
                Validate.notEmpty(theModuleId, "Module ID is required");
                Validate.notNull(theContent, "Content is required");

                EtlImportProcessFileResponseJson result = myRestClient
                        .post()
                        .uri("bulk-import/process-etl-file/{moduleId}", builder-> {
                                builder.queryParamIfPresent("filename", Optional.ofNullable(theFilename));
                                builder.queryParamIfPresent("userJobType", Optional.ofNullable(theUserJobType));
                                return builder.build(Map.of("moduleId", theModuleId));
                        })
                        .accept(MediaType.APPLICATION_JSON)
                        .body(theContent)
                        .retrieve()
                        .body(EtlImportProcessFileResponseJson.class);
                return Objects.requireNonNull(result);
        }

        /**
         * Get transaction logs
         */
        @Nonnull
        public TransactionLogEventsJson getTransactionLogs() {
                TransactionLogEventsJson result =
                        myRestClient.get().uri("transaction-log").retrieve().body(TransactionLogEventsJson.class);
                return Objects.requireNonNull(result);
        }

        @Nonnull
        public TransactionLogEventsJson getTransactionLogs(@Nonnull MultiValueMap<String, String> theQueryParams) {
                TransactionLogEventsJson result = myRestClient
                        .get()
                        .uri("transaction-log", builder -> builder.queryParams(theQueryParams).build())
                        .retrieve()
                        .body(TransactionLogEventsJson.class);
                return Objects.requireNonNull(result);
        }

        @Nonnull
        public TransactionLogEventCodesJson getTransactionLogEventCodes() {
                TransactionLogEventCodesJson result = myRestClient
                        .get()
                        .uri("transaction-log/event-codes")
                        .retrieve()
                        .body(TransactionLogEventCodesJson.class);
                return Objects.requireNonNull(result);
        }

        @Nonnull
        public AuditEventsJson getAuditEvents() {
                return getAuditEvents(new LinkedMultiValueMap<>());
        }

        @Nonnull
        public AuditEventsJson getAuditEvents(@Nonnull MultiValueMap<String, String> theQueryParams) {
                AuditEventsJson result = myRestClient
                        .get()
                        .uri("audit-log", builder -> builder.queryParams(theQueryParams).build())
                        .retrieve()
                        .body(AuditEventsJson.class);
                return Objects.requireNonNull(result);
        }

        @Nonnull
        public MdmAlgorithmsListJson getMdmAlgorithms(String theModuleId) {
                Validate.notEmpty(theModuleId, "Module ID is required");

                MdmAlgorithmsListJson result = myRestClient
                        .get()
                        .uri("mdm/{moduleId}/mdm-algorithms", theModuleId)
                        .retrieve()
                        .body(MdmAlgorithmsListJson.class);
                return Objects.requireNonNull(result);
        }

        @Nonnull
        public MdmMetricsJson getMdmMetrics(String theModuleId, String theResourceType) {
                Validate.notEmpty(theModuleId, "Module ID is required");
                Validate.notEmpty(theResourceType, "Resource type is required");

                MdmMetricsJson result = myRestClient
                        .get()
                        .uri("mdm/{moduleId}/mdm-metrics?resourceType={resourceType}", theModuleId, theResourceType)
                        .retrieve()
                        .body(MdmMetricsJson.class);
                return Objects.requireNonNull(result);
        }

        @Nonnull
        public Set<LoggerConfigJson> getTroubleshootingLoggers() {
                Set<LoggerConfigJson> result = myRestClient
                        .get()
                        .uri("troubleshooting-log/configuration")
                        .retrieve()
                        .body(new ParameterizedTypeReference<>() {});
                return Objects.requireNonNull(result);
        }

        @Nonnull
        public Set<LoggerConfigJson> updateTroubleshootingLoggers(@Nonnull Set<LoggerConfigJson> theLoggers) {
                Set<LoggerConfigJson> result = myRestClient
                        .post()
                        .uri("troubleshooting-log/configuration")
                        .contentType(MediaType.APPLICATION_JSON)
                        .body(theLoggers)
                        .retrieve()
                        .body(new ParameterizedTypeReference<>() {});
                return Objects.requireNonNull(result);
        }

        @Nonnull
        public LoggerConfigJson updateTroubleshootingLoggerLevel(String theLoggerName, String theLoggerLevel) {
                Validate.notEmpty(theLoggerName, "Logger name is required");
                Validate.notEmpty(theLoggerLevel, "Logger level is required");

                LoggerConfigJson result = myRestClient
                        .put()
                        .uri("troubleshooting-log/configuration/{loggerName}?loggerLevel={loggerLevel}", theLoggerName, theLoggerLevel)
                        .retrieve()
                        .body(LoggerConfigJson.class);
                return Objects.requireNonNull(result);
        }

        /**
         * Get a specific transaction log event with its body
         */
        @Nonnull
        public TransactionLogEventsJson.TransactionLogEventJson getTransactionLogEvent(
                Long theEventId, boolean theIncludeBody) {
                Validate.notNull(theEventId, "Event ID is required");

                TransactionLogEventsJson.TransactionLogEventJson result =
                        myRestClient.get().uri("transaction-log/event/{theEventId}?includeBody={includeBody}", theEventId, theIncludeBody).retrieve().body(TransactionLogEventsJson.TransactionLogEventJson.class);
                return Objects.requireNonNull(result);
        }

        /**
         * Create an OAuth client for a specific module
         */
        @Nonnull
        public OAuth2ClientDetailsJson createOAuthClient(
                String theNodeId, String theModuleId, OAuth2WritableClientDetailsJson theClientDetails) {
                Validate.notEmpty(theNodeId, "Node ID is required");
                Validate.notEmpty(theModuleId, "Module ID is required");
                Validate.notEmpty(theClientDetails.getClientId(), "Client ID is required");
                Validate.notNull(theClientDetails, "Client details are required");

                OAuth2ClientDetailsJson result;
                try {
                        result = myRestClient
                                .post()
                                .uri("openid-connect-clients/{nodeId}/{moduleId}", theNodeId, theModuleId)
                                .body(theClientDetails)
                                .retrieve()
                                .body(OAuth2ClientDetailsJson.class);
                } catch (HttpClientErrorException e) {
                        ourLog.warn("Failed to create OIDC client, going to try update instead: " + e.toString());
                        result = myRestClient
                                .post()
                                .uri("openid-connect-clients/{nodeId}/{moduleId}/{clientId}", theNodeId, theModuleId, theClientDetails.getClientId())
                                .body(theClientDetails)
                                .retrieve()
                                .body(OAuth2ClientDetailsJson.class);
                }
                return Objects.requireNonNull(result);
        }

        /**
         * Update an OAuth client for a specific module
         */
        @Nonnull
        public OAuth2ClientDetailsJson updateOAuthClient(
                String theNodeId,
                String theModuleId,
                String theClientId,
                OAuth2WritableClientDetailsJson theClientDetails) {
                Validate.notEmpty(theNodeId, "Node ID is required");
                Validate.notEmpty(theModuleId, "Module ID is required");
                Validate.notEmpty(theClientId, "Client ID is required");
                Validate.notNull(theClientDetails, "Client details are required");

                OAuth2ClientDetailsJson result = myRestClient
                        .put()
                        .uri("openid-connect-clients/{nodeId}/{moduleId}/{clientId}", Map.of(
                                "nodeId", theNodeId,
                                "moduleId", theModuleId,
                                "clientId", theClientId))
                        .body(theClientDetails)
                        .retrieve()
                        .body(OAuth2ClientDetailsJson.class);
                return Objects.requireNonNull(result);
        }

        /**
         * Delete an OAuth client
         */
        public void deleteOAuthClient(String theNodeId, String theModuleId, String theClientId) {
                Validate.notEmpty(theNodeId, "Node ID is required");
                Validate.notEmpty(theModuleId, "Module ID is required");
                Validate.notEmpty(theClientId, "Client ID is required");

                myRestClient
                        .delete()
                        .uri("openid-connect-clients/{nodeId}/{moduleId}/{clientId}", theNodeId, theModuleId, theClientId)
                        .retrieve()
                        .toBodilessEntity();
        }

        @Nonnull
        public OAuth2ClientsJson getOAuthClients(int thePageIndex, int thePageSize, @Nullable ClientStatusFilterEnum theClientStatus) {
                OAuth2ClientsJson result = myRestClient
                        .get()
                        .uri("openid-connect-clients", builder -> {
                                builder.queryParam("pageIndex", thePageIndex);
                                builder.queryParam("pageSize", thePageSize);
                                builder.queryParamIfPresent("clientStatus", Optional.ofNullable(theClientStatus));
                                return builder.build();
                        })
                        .retrieve()
                        .body(OAuth2ClientsJson.class);
                return Objects.requireNonNull(result);
        }

        /**
         * Get an OAuth client
         */
        @Nonnull
        public OAuth2ClientDetailsJson getOAuthClient(String theNodeId, String theModuleId, String theClientId) {
                Validate.notEmpty(theNodeId, "Node ID is required");
                Validate.notEmpty(theModuleId, "Module ID is required");
                Validate.notEmpty(theClientId, "Client ID is required");

                OAuth2ClientDetailsJson result = myRestClient
                        .get()
                        .uri("openid-connect-clients/{nodeId}/{moduleId}/{clientId}", theNodeId, theModuleId, theClientId)
                        .retrieve()
                        .body(OAuth2ClientDetailsJson.class);
                return Objects.requireNonNull(result);
        }

        /**
         * Create an OIDC server for a specific module
         */
        @Nonnull
        public tools.jackson.databind.JsonNode createOidcServer(
                String theNodeId, String theModuleId, tools.jackson.databind.JsonNode theServerDetails) {
                return postOidcServer(theNodeId, theModuleId, theServerDetails, tools.jackson.databind.JsonNode.class);
        }

        /**
         * @deprecated Use {@link #createOidcServer(String, String, tools.jackson.databind.JsonNode)} with Jackson 3's
         *    {@link tools.jackson.databind.JsonNode}. Jackson 2 support will be removed in a later release.
         */
        @Deprecated(since = "2026.11.R01", forRemoval = true)
        @Nonnull
        public JsonNode createOidcServer(String theNodeId, String theModuleId, JsonNode theServerDetails) {
                return postOidcServer(theNodeId, theModuleId, theServerDetails, JsonNode.class);
        }

        @Nonnull
        private <T> T postOidcServer(String theNodeId, String theModuleId, Object theServerDetails, Class<T> theResponseType) {
                Validate.notEmpty(theNodeId, "Node ID is required");
                Validate.notEmpty(theModuleId, "Module ID is required");
                Validate.notNull(theServerDetails, "Server details are required");

                T result = myRestClient
                        .post()
                        .uri("openid-connect-servers/{nodeId}/{moduleId}", theNodeId, theModuleId)
                        .body(theServerDetails)
                        .retrieve()
                        .body(theResponseType);
                return Objects.requireNonNull(result);
        }

        @Nonnull
        public OAuth2ServerJson createOidcServer(String theNodeId, String theModuleId, @Nonnull OAuth2ServerJson theServer) {
                Validate.notEmpty(theNodeId, "Node ID is required");
                Validate.notEmpty(theModuleId, "Module ID is required");
                Validate.notNull(theServer, "Server is required");

                OAuth2ServerJson result = myRestClient
                        .post()
                        .uri("openid-connect-servers/{nodeId}/{moduleId}", theNodeId, theModuleId)
                        .contentType(MediaType.APPLICATION_JSON)
                        .body(theServer)
                        .retrieve()
                        .body(OAuth2ServerJson.class);
                return Objects.requireNonNull(result);
        }

        @Nonnull
        public OAuth2ServerJson getOidcServer(String theNodeId, String theModuleId, String theIssuerUrl) {
                Validate.notEmpty(theNodeId, "Node ID is required");
                Validate.notEmpty(theModuleId, "Module ID is required");
                Validate.notEmpty(theIssuerUrl, "Issuer URL is required");

                OAuth2ServerJson result = myRestClient
                        .get()
                        .uri("openid-connect-servers/{nodeId}/{moduleId}?issuer_url={issuerUrl}", theNodeId, theModuleId, theIssuerUrl)
                        .retrieve()
                        .body(OAuth2ServerJson.class);
                return Objects.requireNonNull(result);
        }

        @Nonnull
        public OAuth2ServersJson getOidcServers(
                @Nullable String theNodeId, @Nullable String theModuleId, int thePageIndex, int thePageSize) {
                OAuth2ServersJson result = myRestClient
                        .get()
                        .uri("openid-connect-servers", builder -> {
                                builder.queryParamIfPresent("node_id", Optional.ofNullable(theNodeId));
                                builder.queryParamIfPresent("module_id", Optional.ofNullable(theModuleId));
                                builder.queryParam("pageIndex", thePageIndex);
                                builder.queryParam("pageSize", thePageSize);
                                return builder.build();
                        })
                        .retrieve()
                        .body(OAuth2ServersJson.class);
                return Objects.requireNonNull(result);
        }

        /**
         * Update an OIDC server
         */
        @Nonnull
        public tools.jackson.databind.JsonNode updateOidcServer(
                String theNodeId, String theModuleId, String theServerId, tools.jackson.databind.JsonNode theServerDetails) {
                return putOidcServer(theNodeId, theModuleId, theServerId, theServerDetails, tools.jackson.databind.JsonNode.class);
        }

        /**
         * @deprecated Use {@link #updateOidcServer(String, String, String, tools.jackson.databind.JsonNode)} with
         *    Jackson 3's {@link tools.jackson.databind.JsonNode}. Jackson 2 support will be removed in a later release.
         */
        @Deprecated(since = "2026.11.R01", forRemoval = true)
        @Nonnull
        public JsonNode updateOidcServer(
                String theNodeId, String theModuleId, String theServerId, JsonNode theServerDetails) {
                return putOidcServer(theNodeId, theModuleId, theServerId, theServerDetails, JsonNode.class);
        }

        @Nonnull
        private <T> T putOidcServer(
                String theNodeId, String theModuleId, String theServerId, Object theServerDetails, Class<T> theResponseType) {
                Validate.notEmpty(theNodeId, "Node ID is required");
                Validate.notEmpty(theModuleId, "Module ID is required");
                Validate.notEmpty(theServerId, "Server ID is required");
                Validate.notNull(theServerDetails, "Server details are required");

                T result = myRestClient
                        .put()
                        .uri("openid-connect-servers/{nodeId}/{moduleId}/{serverId}", theNodeId, theModuleId, theServerId)
                        .body(theServerDetails)
                        .retrieve()
                        .body(theResponseType);
                return Objects.requireNonNull(result);
        }

        @Nonnull
        public OAuth2ServerJson updateOidcServer(String theNodeId, String theModuleId, @Nonnull OAuth2ServerJson theServer) {
                Validate.notEmpty(theNodeId, "Node ID is required");
                Validate.notEmpty(theModuleId, "Module ID is required");
                Validate.notNull(theServer, "Server is required");
                Validate.notNull(theServer.getPid(), "Server PID is required");

                OAuth2ServerJson result = myRestClient
                        .put()
                        .uri("openid-connect-servers/{nodeId}/{moduleId}/{pid}", theNodeId, theModuleId, theServer.getPid())
                        .contentType(MediaType.APPLICATION_JSON)
                        .body(theServer)
                        .retrieve()
                        .body(OAuth2ServerJson.class);
                return Objects.requireNonNull(result);
        }

        @Nonnull
        public CdaTemplateJson createCdaTemplate(
                String theModuleId, String theTemplateId, @Nonnull CdaTemplateRequestJson theTemplate) {
                return writeCdaTemplate(myRestClient.post(), theModuleId, theTemplateId, theTemplate);
        }

        @Nonnull
        public CdaTemplateJson updateCdaTemplate(
                String theModuleId, String theTemplateId, @Nonnull CdaTemplateRequestJson theTemplate) {
                return writeCdaTemplate(myRestClient.put(), theModuleId, theTemplateId, theTemplate);
        }

        private CdaTemplateJson writeCdaTemplate(
                RestClient.RequestBodyUriSpec theMethod,
                String theModuleId,
                String theTemplateId,
                CdaTemplateRequestJson theTemplate) {
                Validate.notEmpty(theModuleId, "Module ID is required");
                Validate.notEmpty(theTemplateId, "Template ID is required");
                Validate.notNull(theTemplate, "Template is required");

                CdaTemplateJson result = theMethod
                        .uri("cda/{moduleId}/template/{templateId}", theModuleId, theTemplateId)
                        .contentType(MediaType.APPLICATION_JSON)
                        .body(theTemplate)
                        .retrieve()
                        .body(CdaTemplateJson.class);
                return Objects.requireNonNull(result);
        }

        @Nonnull
        public CdaTemplateJson updateCdaTemplateScript(String theModuleId, String theTemplateId, String theScript) {
                Validate.notEmpty(theModuleId, "Module ID is required");
                Validate.notEmpty(theTemplateId, "Template ID is required");
                Validate.notNull(theScript, "Script is required");

                CdaTemplateJson result = myRestClient
                        .put()
                        .uri("cda/{moduleId}/template/{templateId}/script", theModuleId, theTemplateId)
                        .contentType(MediaType.parseMediaType("application/javascript"))
                        .body(theScript)
                        .retrieve()
                        .body(CdaTemplateJson.class);
                return Objects.requireNonNull(result);
        }

        @Nonnull
        public CdaTemplateViewAllResponseJson getCdaTemplates(String theModuleId) {
                Validate.notEmpty(theModuleId, "Module ID is required");

                CdaTemplateViewAllResponseJson result = myRestClient
                        .get()
                        .uri("cda/{moduleId}/template", theModuleId)
                        .retrieve()
                        .body(CdaTemplateViewAllResponseJson.class);
                return Objects.requireNonNull(result);
        }

        @Nonnull
        public CdaTemplateResponseJson getCdaTemplate(String theModuleId, String theTemplateId) {
                Validate.notEmpty(theModuleId, "Module ID is required");
                Validate.notEmpty(theTemplateId, "Template ID is required");

                CdaTemplateResponseJson result = myRestClient
                        .get()
                        .uri("cda/{moduleId}/template/{templateId}", theModuleId, theTemplateId)
                        .retrieve()
                        .body(CdaTemplateResponseJson.class);
                return Objects.requireNonNull(result);
        }

        public void deleteCdaTemplate(String theModuleId, String theTemplateId) {
                Validate.notEmpty(theModuleId, "Module ID is required");
                Validate.notEmpty(theTemplateId, "Template ID is required");

                myRestClient
                        .delete()
                        .uri("cda/{moduleId}/template/{templateId}", theModuleId, theTemplateId)
                        .retrieve()
                        .toBodilessEntity();
        }

        @Nonnull
        public PrivacyNoticeJson getPrivacyNotice() {
                PrivacyNoticeJson result = myRestClient
                        .get()
                        .uri("admin-json/privacy-notice")
                        .retrieve()
                        .body(PrivacyNoticeJson.class);
                return Objects.requireNonNull(result);
        }

        @Nonnull
        public PrivacyNoticeStatusJson getPrivacyNoticeStatus() {
                PrivacyNoticeStatusJson result = myRestClient
                        .get()
                        .uri("admin-json/privacy-notice/status")
                        .retrieve()
                        .body(PrivacyNoticeStatusJson.class);
                return Objects.requireNonNull(result);
        }

        @Nonnull
        public PrivacyNoticeAcceptanceJson acceptPrivacyNotice(String theVersion) {
                Validate.notEmpty(theVersion, "Version is required");

                PrivacyNoticeAcceptanceJson result = myRestClient
                        .post()
                        .uri("admin-json/privacy-notice/accept")
                        .contentType(MediaType.APPLICATION_JSON)
                        .body(new PrivacyNoticeAcceptRequestJson(theVersion))
                        .retrieve()
                        .body(PrivacyNoticeAcceptanceJson.class);
                return Objects.requireNonNull(result);
        }

        @Nonnull
        public OAuth2KeystoresJson getKeystores(int thePageIndex, int thePageSize) {
                OAuth2KeystoresJson result = myRestClient
                        .get()
                        .uri("keystores?pageIndex={pageIndex}&pageSize={pageSize}", thePageIndex, thePageSize)
                        .retrieve()
                        .body(OAuth2KeystoresJson.class);
                return Objects.requireNonNull(result);
        }

        @Nonnull
        public OAuth2KeystoreJson getKeystore(String theKeystoreId) {
                Validate.notEmpty(theKeystoreId, "Keystore ID is required");

                OAuth2KeystoreJson result = myRestClient
                        .get()
                        .uri("keystores/{keystoreId}", theKeystoreId)
                        .retrieve()
                        .body(OAuth2KeystoreJson.class);
                return Objects.requireNonNull(result);
        }

        @Nonnull
        public OAuth2KeystoreJson createKeystore(@Nonnull OAuth2KeystoreJson theKeystore) {
                Validate.notNull(theKeystore, "Keystore is required");

                OAuth2KeystoreJson result = myRestClient
                        .post()
                        .uri("keystores")
                        .contentType(MediaType.APPLICATION_JSON)
                        .body(theKeystore)
                        .retrieve()
                        .body(OAuth2KeystoreJson.class);
                return Objects.requireNonNull(result);
        }

        @Nonnull
        public OAuth2KeystoreJson updateKeystore(String theKeystoreId, @Nonnull OAuth2KeystoreJson theKeystore) {
                Validate.notEmpty(theKeystoreId, "Keystore ID is required");
                Validate.notNull(theKeystore, "Keystore is required");

                OAuth2KeystoreJson result = myRestClient
                        .put()
                        .uri("keystores/{keystoreId}", theKeystoreId)
                        .contentType(MediaType.APPLICATION_JSON)
                        .body(theKeystore)
                        .retrieve()
                        .body(OAuth2KeystoreJson.class);
                return Objects.requireNonNull(result);
        }

        public void deleteKeystore(String theKeystoreId) {
                Validate.notEmpty(theKeystoreId, "Keystore ID is required");

                myRestClient
                        .delete()
                        .uri("keystores/{keystoreId}", theKeystoreId)
                        .retrieve()
                        .toBodilessEntity();
        }

        @Nonnull
        public OAuth2RevokeAllWithScopeResponseJson revokeAllTokens(
                @Nullable String theNodeId, @Nullable String theModuleId, @Nullable String theScope) {
                OAuth2RevokeAllWithScopeResponseJson result = myRestClient
                        .delete()
                        .uri("openid-connect-sessions/revoke/all-tokens", builder -> {
                                builder.queryParamIfPresent("node_id", Optional.ofNullable(theNodeId));
                                builder.queryParamIfPresent("module_id", Optional.ofNullable(theModuleId));
                                builder.queryParamIfPresent("scope", Optional.ofNullable(theScope));
                                return builder.build();
                        })
                        .retrieve()
                        .body(OAuth2RevokeAllWithScopeResponseJson.class);
                return Objects.requireNonNull(result);
        }

        /**
         * Get MDM links
         *
         * @param theResponseType the type to read the response as: Jackson 3's {@link tools.jackson.databind.JsonNode},
         *    or a model class to bind it to
         */
        @Nonnull
        public <T> T getMdmLinks(String theModuleId, @Nonnull Class<T> theResponseType) {
                Validate.notEmpty(theModuleId, "Module ID is required");

                T result = myRestClient
                        .get()
                        .uri("mdm/{moduleId}/query-links", theModuleId)
                        .retrieve()
                        .body(theResponseType);
                return Objects.requireNonNull(result);
        }

        /**
         * @deprecated Use {@link #getMdmLinks(String, Class)} with Jackson 3's
         *    {@link tools.jackson.databind.JsonNode}. Jackson 2 support will be removed in a later release.
         */
        @Deprecated(since = "2026.11.R01", forRemoval = true)
        @Nonnull
        public JsonNode getMdmLinks(String theModuleId) {
                return getMdmLinks(theModuleId, JsonNode.class);
        }

        /**
         * Merge MDM golden resources
         *
         * @param theResponseType the type to read the response as: Jackson 3's {@link tools.jackson.databind.JsonNode},
         *    or a model class to bind it to
         */
        @Nonnull
        public <T> T mergeMdmGoldenResources(String theModuleId, Object theRequest, @Nonnull Class<T> theResponseType) {
                Validate.notEmpty(theModuleId, "Module ID is required");
                Validate.notNull(theRequest, "Request is required");

                T result = myRestClient
                        .post()
                        .uri("mdm/{moduleId}/merge-golden-resources", theModuleId)
                        .body(theRequest)
                        .retrieve()
                        .body(theResponseType);
                return Objects.requireNonNull(result);
        }

        /**
         * @deprecated Use {@link #mergeMdmGoldenResources(String, Object, Class)} with Jackson 3's
         *    {@link tools.jackson.databind.JsonNode}. Jackson 2 support will be removed in a later release.
         */
        @Deprecated(since = "2026.11.R01", forRemoval = true)
        @Nonnull
        public JsonNode mergeMdmGoldenResources(String theModuleId, Object theRequest) {
                return mergeMdmGoldenResources(theModuleId, theRequest, JsonNode.class);
        }

        /**
         * Update MDM link
         *
         * @param theResponseType the type to read the response as: Jackson 3's {@link tools.jackson.databind.JsonNode},
         *    or a model class to bind it to
         */
        @Nonnull
        public <T> T updateMdmLink(String theModuleId, Object theRequest, @Nonnull Class<T> theResponseType) {
                Validate.notEmpty(theModuleId, "Module ID is required");
                Validate.notNull(theRequest, "Request is required");

                T result = myRestClient
                        .post()
                        .uri("mdm/{moduleId}/update-link", theModuleId)
                        .body(theRequest)
                        .retrieve()
                        .body(theResponseType);
                return Objects.requireNonNull(result);
        }

        /**
         * @deprecated Use {@link #updateMdmLink(String, Object, Class)} with Jackson 3's
         *    {@link tools.jackson.databind.JsonNode}. Jackson 2 support will be removed in a later release.
         */
        @Deprecated(since = "2026.11.R01", forRemoval = true)
        @Nonnull
        public JsonNode updateMdmLink(String theModuleId, Object theRequest) {
                return updateMdmLink(theModuleId, theRequest, JsonNode.class);
        }

        /**
         * Get MDM duplicate golden resources
         *
         * @param theResponseType the type to read the response as: Jackson 3's {@link tools.jackson.databind.JsonNode},
         *    or a model class to bind it to
         */
        @Nonnull
        public <T> T getMdmDuplicateGoldenResources(String theModuleId, @Nonnull Class<T> theResponseType) {
                Validate.notEmpty(theModuleId, "Module ID is required");

                T result = myRestClient
                        .get()
                        .uri("mdm/{moduleId}/duplicate-golden-resources", theModuleId)
                        .retrieve()
                        .body(theResponseType);
                return Objects.requireNonNull(result);
        }

        /**
         * @deprecated Use {@link #getMdmDuplicateGoldenResources(String, Class)} with Jackson 3's
         *    {@link tools.jackson.databind.JsonNode}. Jackson 2 support will be removed in a later release.
         */
        @Deprecated(since = "2026.11.R01", forRemoval = true)
        @Nonnull
        public JsonNode getMdmDuplicateGoldenResources(String theModuleId) {
                return getMdmDuplicateGoldenResources(theModuleId, JsonNode.class);
        }

        /**
         * Submit an MDM operation to perform batch matching on all resources
         *
         * @param theModuleId   The module ID
         * @param theParameters The parameters for the MDM operation
         * @return The response as a String
         */
        @Nonnull
        public String submitMdmOperation(String theModuleId, IBaseParameters theParameters) {
                Validate.notEmpty(theModuleId, "Module ID is required");

                String body = toJsonString(theParameters);

                String result = myRestClient
                        .post()
                        .uri("{moduleId}/mdm-submit", theModuleId)
                        .body(body)
                        .retrieve()
                        .body(String.class);

                return result != null ? result : "";
        }

        public static String toJsonString(IBaseResource theResource) {
                FhirVersionEnum version = FhirVersionEnum.determineVersionForType(theResource.getClass());
                FhirContext ctx = FhirContext.forCached(version);
                return ctx.newJsonParser().encodeResourceToString(theResource);
        }

        /**
         * Exception thrown when a forbidden operation is attempted
         */
        public static class ForbiddenOperationException extends RuntimeException {
                public ForbiddenOperationException(String message, Throwable cause) {
                        super(message, cause);
                }
        }

        /**
         * Get the node configurations from the admin API.
         *
         * @return The node configurations
         */
        @Nonnull
        public NodeConfigurations getNodeConfigurations() {
                NodeConfigurations result = myRestClient
                        .get()
                        .uri("/module-config/")
                        .retrieve()
                        .body(NodeConfigurations.class);
                return Objects.requireNonNull(result);
        }

        /**
         * Get the port number for a specific module from the node configurations.
         *
         * @param theModuleId The ID of the module to get the port for
         * @return The port number, or the default FHIR port (8000) if not found
         */
        public int getPortFromModule(String theModuleId) {
                Validate.notEmpty(theModuleId, "Module ID is required");
                NodeConfigurations config = getNodeConfigurations();

                // Find the first node (assuming there's only one node in the container)
                if (config.getNodes().isEmpty()) {
                        throw new IllegalStateException("No nodes found in node configuration");
                } else {
                        NodeConfigurations.NodeConfiguration node = config.getNodes().get(0);

                        // Find the module with the given ID
                        return node.getModule(theModuleId)
                                .map(module -> {
                                        // Look for the port property in the module's configuration
                                        for (NodeConfigurations.ModuleConfigProperty property : module.getConfigProperties()) {
                                                if (property.getKey().equals("port")) {
                                                        try {
                                                                return Integer.parseInt(property.getValue());
                                                        } catch (NumberFormatException e) {
                                                                // If the port is not a valid integer, fail.
                                                                throw new IllegalArgumentException("Invalid port number: " + property.getValue(), e);
                                                        }
                                                }
                                        }
                                        // If no port property is found, return the default FHIR port
                                        return null;
                                })
                                .orElseThrow(() -> new IllegalArgumentException("Module with ID " + theModuleId + " not found in node configuration"));
                }

        }

        /**
         * Find the module ID of the FHIR endpoint (FHIR REST, hybrid providers, or FHIR gateway) running
         * on the given port.
         *
         * @param thePort The port to look up
         * @return The module ID of the FHIR endpoint module running on the given port
         * @throws IllegalArgumentException if no FHIR endpoint module is found running on the given port
         * @throws IllegalStateException if no nodes are found in the node configuration
         */
        @Nonnull
        public String getFhirEndpointModuleIdFromPort(int thePort) {
                final NodeConfigurations config = getNodeConfigurations();
                // Find the first node (assuming there's only one node in the container)
                if (config.getNodes().isEmpty()) {
                        throw new IllegalStateException("No nodes found in node configuration");
                } else {
                        final NodeConfigurations.NodeConfiguration node = config.getNodes().get(0);
                        // Find the module with the given ID
                        return node.getModules().stream()
                                .filter(theModuleConfiguration -> theModuleConfiguration.isFhirEndpointModuleType()
                                        && thePort == Integer.parseInt(theModuleConfiguration.getConfigProperty("port")))
                                .findFirst()
                                .map(NodeConfigurations.ModuleConfiguration::getModuleId)
                                .orElseThrow(() -> new IllegalArgumentException("Unable to find FHIR Endpoint module running on Port " + thePort));
                }
        }

        /**
         * Binds a JSON tree to a model class. Methods that take a response type can bind to the model directly instead.
         *
         * @param theJsonNode the tree to bind
         * @param theModelClass the class to bind it to
         * @return the model
         * @throws tools.jackson.core.JacksonException if the tree does not match the model
         */
        public <T> T convertJsonNodeToModel(tools.jackson.databind.JsonNode theJsonNode, Class<T> theModelClass) {
                return ourJsonMapper.treeToValue(theJsonNode, theModelClass);
        }

        /**
         * Writes a model as a JSON tree.
         *
         * @param theModel the model to write
         * @param theNodeType the Jackson 3 node type to return, normally {@link tools.jackson.databind.JsonNode}
         * @return the tree
         */
        public <N extends tools.jackson.databind.JsonNode> N convertModelToJsonNode(Object theModel, Class<N> theNodeType) {
                return theNodeType.cast(ourJsonMapper.valueToTree(theModel));
        }

        /**
         * Since many  methods currently return JsonNode, if you have a known model you would like to bind to, you can convert a json object to it using this method
         *
         * @deprecated Use {@link #convertJsonNodeToModel(tools.jackson.databind.JsonNode, Class)} with Jackson 3's
         *    {@link tools.jackson.databind.JsonNode}. Jackson 2 support will be removed in a later release.
         */
        @Deprecated(since = "2026.11.R01", forRemoval = true)
        public <T> T convertJsonNodeToModel(JsonNode jsonNode, Class<T> modelClass) throws JsonProcessingException {
                // This is a hack to work around many of our return types being hidden in cdr-api instead of cdr-api-public.
                // From Gary: We can't extract them cleanly yet to the fact that they often are relying on enums in clustermgr
                // or enums in api that we do not currently want to make public,
                // usually via 3 separate levels of nesting (e.g. node configurations -> module config -> ModuleTypeEnum
                // TODO: Fix these, and move them to public, updating the method types to our model classes.

                try {
                        // The models carry Jackson 3 annotations only, so bind with Jackson 3 by way of the JSON text
                        return ourJsonMapper.readValue(jsonNode.toString(), modelClass);
                } catch (JacksonException e) {
                        // Log the error with the actual JSON content for debugging
                        ourLog.error("Failed to convert JsonNode to " + modelClass.getSimpleName() +
                                ". JSON content: " + jsonNode.toString(), e);
                        throw new JsonProcessingException(e.getMessage(), e) {};
                }
        }

        /**
         * @deprecated Use {@link #convertModelToJsonNode(Object, Class)} with Jackson 3's
         *    {@link tools.jackson.databind.JsonNode}. Jackson 2 support will be removed in a later release.
         */
        @Deprecated(since = "2026.11.R01", forRemoval = true)
        public <T> JsonNode convertModelToJsonNode(T model) throws JsonProcessingException {
                try {
                        // The models carry Jackson 3 annotations only, so write with Jackson 3 and read the text as a Jackson 2 tree
                        return new ObjectMapper().readTree(ourJsonMapper.writeValueAsString(model));
                } catch (Exception e) {
                        throw new JsonProcessingException("Error converting model to JsonNode") {} ;
                }
        }


        @Nullable
        public TransactionLogEventsJson.TransactionLogEventJson getMostRecentTransactionLogEntry() {
                TransactionLogEventsJson events = myRestClient.get().uri("/transaction-log/?pageSize=1").retrieve().body(TransactionLogEventsJson.class);
                if (events == null || events.getEvents() == null || events.getEvents().isEmpty()) {
                        return null;
                } else {
                        return events.getEvents().get(0);
                }
        }

        @Nullable
        public Long getMostRecentTransactionLogEntryId() {
                TransactionLogEventsJson.TransactionLogEventJson entry = getMostRecentTransactionLogEntry();
                if (entry != null) {
                        return entry.getId();
                } else {
                        return null;
                }
        }

        public void awaitNewTransactionLogEntry(Long theMostRecentTxLogEntryId) {
                await().until(this::getMostRecentTransactionLogEntryId, t -> !Objects.equals(theMostRecentTxLogEntryId, t));
        }

        /**
         * Fetch a transaction log entry by ID and return all details (includes the body)
         */
        public TransactionLogEventsJson.TransactionLogEventJson getTransactionLogEntryById(Long theId) {
                return myRestClient.get().uri("/transaction-log/clustermgr/event/" +theId+ "?includeBody=true").retrieve().body(TransactionLogEventsJson.TransactionLogEventJson.class);
        }

        /**
         * Perform a generic GET request to the specified path and return the response as JsonNode
         *
         * @param thePath The path to perform the GET request on
         * @param theResponseType the type to read the response as: Jackson 3's {@link tools.jackson.databind.JsonNode},
         *    or a model class to bind it to
         * @return The response, read as {@code theResponseType}
         */
        @Nonnull
        public <T> T get(String thePath, @Nonnull Class<T> theResponseType) {
                Validate.notEmpty(thePath, "Path is required");
                T result = myRestClient
                        .get()
                        .uri(thePath)
                        .retrieve()
                        .body(theResponseType);
                return Objects.requireNonNull(result);
        }

        /**
         * @deprecated Use {@link #get(String, Class)} with Jackson 3's
         *    {@link tools.jackson.databind.JsonNode}. Jackson 2 support will be removed in a later release.
         */
        @Deprecated(since = "2026.11.R01", forRemoval = true)
        @Nonnull
        public JsonNode get(String thePath) {
                return get(thePath, JsonNode.class);
        }

        /**
         * Releases the connection pool this client built for itself. A no-op when the client was built
         * over one supplied by a caller, which owns its own pool.
         */
        @Override
        public void close() {
                if (myOwnership != null) {
                        myOwnership.closeIfOwned();
                }
        }
}