adds Utilities Resource

Author: MarketDataDev03

src/integrationTest/java/com/marketdata/sdk/markets/MarketsStatusIT.java

@@ -14,7 +14,7 @@
  *
  * <p>Requires a valid {@code MARKETDATA_TOKEN} env var (or {@code .env} entry). Without one the
  * client enters demo mode and the {@code /markets/status/} endpoint is not on the demo allow-list,
- * so the test would receive an {@code AuthenticationError}.
+ * so the test would receive an {@code AuthenticationException}.
  *
  * <p>Each scenario runs once for {@link CallMode#SYNC} and once for {@link CallMode#ASYNC} so we
  * satisfy SDK requirements §13's "tests must cover both sync and async variants for every endpoint"

src/integrationTest/java/com/marketdata/sdk/utilities/UtilitiesHeadersIT.java

@@ -0,0 +1,85 @@
+package com.marketdata.sdk.utilities;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import com.marketdata.sdk.MarketDataClient;
+import java.util.concurrent.CompletionException;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.EnumSource;
+
+/**
+ * Hits the live {@code GET /headers/} endpoint (root-level, no {@code /v1/} prefix). The endpoint
+ * echoes back the headers the API received from us, so this is the strongest end-to-end check that
+ * the SDK is actually sending the right Authorization, User-Agent, etc.
+ *
+ * <p>Gated by the {@code integrationTest} source set ({@code
+ * MARKETDATA_RUN_INTEGRATION_TESTS=true}); requires a valid {@code MARKETDATA_TOKEN}.
+ *
+ * <p>Each scenario runs once for sync and once for async per SDK requirements §13.
+ */
+class UtilitiesHeadersIT {
+
+  @ParameterizedTest
+  @EnumSource(CallMode.class)
+  void headersEchoesUserAgentAndAuthorization(CallMode mode) {
+    try (var client = MarketDataClient.builder().validateOnStartup(false).build()) {
+      RequestHeaders headers = mode.headers(client.utilities());
+
+      assertThat(headers.isEmpty()).isFalse();
+
+      // The SDK's User-Agent must be sent on every request (SDK requirements §1.1):
+      assertThat(headers.get("user-agent"))
+          .as("the API echoes back the User-Agent we sent")
+          .get()
+          .asString()
+          .startsWith("marketdata-sdk-java/");
+
+      // Authorization is forwarded (and partially redacted in the response per the API docs):
+      assertThat(headers.get("authorization"))
+          .as("Authorization header was sent and echoed (redacted)")
+          .get()
+          .asString()
+          .startsWith("Bearer ");
+
+      // Accept comes from buildRequest in HttpTransport:
+      assertThat(headers.get("accept")).get().asString().contains("application/json");
+    }
+  }
+
+  @ParameterizedTest
+  @EnumSource(CallMode.class)
+  void headerLookupsAreCaseInsensitive(CallMode mode) {
+    try (var client = MarketDataClient.builder().validateOnStartup(false).build()) {
+      RequestHeaders headers = mode.headers(client.utilities());
+
+      // The API normalizes keys to lowercase but our deserializer also forces lowercase, so
+      // any of these capitalizations should resolve to the same value.
+      assertThat(headers.get("User-Agent")).isEqualTo(headers.get("user-agent"));
+      assertThat(headers.get("USER-AGENT")).isEqualTo(headers.get("user-agent"));
+    }
+  }
+
+  enum CallMode {
+    SYNC {
+      @Override
+      RequestHeaders headers(UtilitiesResource r) {
+        return r.headers();
+      }
+    },
+    ASYNC {
+      @Override
+      RequestHeaders headers(UtilitiesResource r) {
+        try {
+          return r.headersAsync().join();
+        } catch (CompletionException e) {
+          if (e.getCause() instanceof RuntimeException re) {
+            throw re;
+          }
+          throw e;
+        }
+      }
+    };
+
+    abstract RequestHeaders headers(UtilitiesResource r);
+  }
+}

src/integrationTest/java/com/marketdata/sdk/utilities/UtilitiesStatusIT.java

@@ -0,0 +1,80 @@
+package com.marketdata.sdk.utilities;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import com.marketdata.sdk.MarketDataClient;
+import java.util.concurrent.CompletionException;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.EnumSource;
+
+/**
+ * Hits the live {@code GET /status/} endpoint (root-level, no {@code /v1/} prefix). Gated by the
+ * {@code integrationTest} source set ({@code MARKETDATA_RUN_INTEGRATION_TESTS=true}).
+ *
+ * <p>This endpoint does <em>not</em> require authentication, but the SDK will still send the {@code
+ * Authorization} header if a token is configured — the API simply ignores it for status lookups. We
+ * don't validate that here because there's no observable difference.
+ *
+ * <p>Each scenario runs once for sync and once for async per SDK requirements §13.
+ */
+class UtilitiesStatusIT {
+
+  @ParameterizedTest
+  @EnumSource(CallMode.class)
+  void statusReturnsServicesWithStructuralInvariants(CallMode mode) {
+    try (var client = MarketDataClient.builder().validateOnStartup(false).build()) {
+      ServiceStatus status = mode.status(client.utilities());
+
+      assertThat(status.services()).isNotEmpty();
+      assertThat(status.services())
+          .allSatisfy(
+              s -> {
+                assertThat(s.service()).isNotBlank();
+                assertThat(s.status()).isIn("online", "offline");
+                // online flag is consistent with the human-readable status:
+                assertThat(s.online()).isEqualTo("online".equals(s.status()));
+                assertThat(s.uptimePct30d()).isBetween(0.0, 1.0);
+                assertThat(s.uptimePct90d()).isBetween(0.0, 1.0);
+                assertThat(s.updated()).isNotNull();
+              });
+    }
+  }
+
+  @ParameterizedTest
+  @EnumSource(CallMode.class)
+  void statusUrlIsRootLevelNotV1(CallMode mode) {
+    // No direct way to introspect the URL from a successful call, but the
+    // fact that the call doesn't 404 (which it would if we mistakenly hit
+    // /v1/status/) is the implicit assertion. If this passes, the
+    // RequestSpec.getAtRoot wiring is correctly skipping the version
+    // prefix.
+    try (var client = MarketDataClient.builder().validateOnStartup(false).build()) {
+      ServiceStatus result = mode.status(client.utilities());
+      assertThat(result).isNotNull();
+    }
+  }
+
+  enum CallMode {
+    SYNC {
+      @Override
+      ServiceStatus status(UtilitiesResource r) {
+        return r.status();
+      }
+    },
+    ASYNC {
+      @Override
+      ServiceStatus status(UtilitiesResource r) {
+        try {
+          return r.statusAsync().join();
+        } catch (CompletionException e) {
+          if (e.getCause() instanceof RuntimeException re) {
+            throw re;
+          }
+          throw e;
+        }
+      }
+    };
+
+    abstract ServiceStatus status(UtilitiesResource r);
+  }
+}

src/integrationTest/java/com/marketdata/sdk/utilities/UtilitiesUserIT.java

@@ -0,0 +1,72 @@
+package com.marketdata.sdk.utilities;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import com.marketdata.sdk.MarketDataClient;
+import java.util.concurrent.CompletionException;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.EnumSource;
+
+/**
+ * Hits the live {@code GET /user/} endpoint and validates the round-trip. Gated by the {@code
+ * integrationTest} source set ({@code MARKETDATA_RUN_INTEGRATION_TESTS=true}); requires a valid
+ * {@code MARKETDATA_TOKEN}.
+ *
+ * <p>Each scenario runs once for sync and once for async per SDK requirements §13.
+ */
+class UtilitiesUserIT {
+
+  @ParameterizedTest
+  @EnumSource(CallMode.class)
+  void userReturnsAccountSnapshot(CallMode mode) {
+    try (var client = MarketDataClient.builder().validateOnStartup(false).build()) {
+      UserInfo info = mode.user(client.utilities());
+
+      // We don't know exact quota numbers (depends on the test account / time of day),
+      // but the structural invariants hold for any well-formed account.
+      assertThat(info.requestsLimit()).isPositive();
+      assertThat(info.requestsRemaining()).isGreaterThanOrEqualTo(0);
+      assertThat(info.requestsRemaining()).isLessThanOrEqualTo(info.requestsLimit());
+      assertThat(info.optionsDataPermissions()).isNotNull();
+    }
+  }
+
+  @ParameterizedTest
+  @EnumSource(CallMode.class)
+  void afterUserCallTheClientHasAFreshRateLimitSnapshot(CallMode mode) {
+    try (var client = MarketDataClient.builder().validateOnStartup(false).build()) {
+      assertThat(client.getRateLimits()).isNull();
+
+      mode.user(client.utilities());
+
+      // §8.1: x-api-ratelimit-* headers populate the snapshot on the way back.
+      assertThat(client.getRateLimits()).isNotNull();
+      assertThat(client.getRateLimits().limit()).isPositive();
+    }
+  }
+
+  /** Mirrors the test-side {@code CallMode} from the unit suite. */
+  enum CallMode {
+    SYNC {
+      @Override
+      UserInfo user(UtilitiesResource r) {
+        return r.user();
+      }
+    },
+    ASYNC {
+      @Override
+      UserInfo user(UtilitiesResource r) {
+        try {
+          return r.userAsync().join();
+        } catch (CompletionException e) {
+          if (e.getCause() instanceof RuntimeException re) {
+            throw re;
+          }
+          throw e;
+        }
+      }
+    };
+
+    abstract UserInfo user(UtilitiesResource r);
+  }
+}

src/main/java/com/marketdata/sdk/MarketDataClient.java

@@ -6,6 +6,7 @@
 import com.marketdata.sdk.internal.Version;
 import com.marketdata.sdk.internal.http.HttpTransport;
 import com.marketdata.sdk.markets.MarketsResource;
+import com.marketdata.sdk.utilities.UtilitiesResource;
 import java.time.Duration;
 import java.util.logging.Level;
 import java.util.logging.Logger;
@@ -50,6 +51,7 @@ public final class MarketDataClient implements AutoCloseable {
   // one record-shaped object per resource group. Worth revisiting if the
   // resource count grows large.
   private final MarketsResource markets;
+  private final UtilitiesResource utilities;
 
   private MarketDataClient(Builder builder) {
     Configuration config = Configuration.loadFromProcess();
@@ -67,6 +69,7 @@ private MarketDataClient(Builder builder) {
 
     this.transport = new HttpTransport(this.baseUrl, this.apiVersion, this.userAgent, this.token);
     this.markets = new MarketsResource(this.transport);
+    this.utilities = new UtilitiesResource(this.transport);
 
     LOG.log(
         Level.INFO,
@@ -80,8 +83,14 @@ private MarketDataClient(Builder builder) {
       LOG.log(Level.FINE, "Token: {0}", Tokens.redact(token));
     }
 
-    // SDK requirements §5: validate on startup by default. The actual
-    // /user/ call lands with the user resource; this flag is the seam.
+    // SDK requirements §5: validate the token by hitting /user/ unless either
+    // (a) the caller explicitly disabled it, or (b) we're in demo mode (no
+    // token to validate). This also populates the rate-limit snapshot at
+    // construction time per §8.1 — the response headers feed the transport's
+    // latestRateLimits as a side-effect of the call.
+    if (validateOnStartup && !demoMode) {
+      this.utilities.user();
+    }
   }
 
   public static Builder builder() {
@@ -97,6 +106,11 @@ public MarketsResource markets() {
     return markets;
   }
 
+  /** Façade for the {@code utilities} resource group ({@code /v1/user/}, plus more later). */
+  public UtilitiesResource utilities() {
+    return utilities;
+  }
+
   // ---------------------------------------------------------------------
   // Configuration accessors
   // ---------------------------------------------------------------------

src/main/java/com/marketdata/sdk/exception/AuthenticationError.java

@@ -0,0 +1,15 @@
+package com.marketdata.sdk.exception;
+
+import org.jspecify.annotations.Nullable;
+
+/** The API rejected the credentials (HTTP 401). */
+public final class AuthenticationException extends MarketDataException {
+
+  public AuthenticationException(String message, ErrorContext context) {
+    super(message, context, null);
+  }
+
+  public AuthenticationException(String message, ErrorContext context, @Nullable Throwable cause) {
+    super(message, context, cause);
+  }
+}

src/main/java/com/marketdata/sdk/exception/AuthenticationException.java

@@ -0,0 +1,15 @@
+package com.marketdata.sdk.exception;
+
+import org.jspecify.annotations.Nullable;
+
+/** The request was malformed or invalid (HTTP 400 / 422). */
+public final class BadRequestException extends MarketDataException {
+
+  public BadRequestException(String message, ErrorContext context) {
+    super(message, context, null);
+  }
+
+  public BadRequestException(String message, ErrorContext context, @Nullable Throwable cause) {
+    super(message, context, cause);
+  }
+}

src/main/java/com/marketdata/sdk/exception/BadRequestError.java

@@ -16,13 +16,13 @@
  * any HTTP request is dispatched.
  */
 public abstract sealed class MarketDataException extends RuntimeException
-    permits AuthenticationError,
-        BadRequestError,
-        NotFoundError,
-        RateLimitError,
-        ServerError,
-        NetworkError,
-        ParseError {
+    permits AuthenticationException,
+        BadRequestException,
+        NotFoundException,
+        RateLimitException,
+        ServerException,
+        NetworkException,
+        ParseException {
 
   private static final ZoneId EASTERN = ZoneId.of("America/New_York");
   private static final DateTimeFormatter TIMESTAMP_FORMAT =