Java SDK

io.github.suman0359:sentriq-java is a server-only SDK — it holds a secret key and must never run in browser-facing code. For browser-side tracking, see the Browser SDK. Java 17+, built on the JDK's own java.net.http.HttpClient — no OkHttp, no Apache HttpClient. Not yet published to Maven Central — install via a local mvn install against a checked-out commit until a release process exists.

Install

<dependency>
  <groupId>io.github.suman0359</groupId>
  <artifactId>sentriq-java</artifactId>
  <version>0.1.0</version>
</dependency>

Initialize

SentriqClient client = SentriqClient.builder()
    .secretKey(System.getenv("SENTRIQ_SECRET_KEY"))
    // Optional. Defaults to the hosted Sentriq API.
    .apiUrl(System.getenv("SENTRIQ_API_URL"))
    // Optional. Defaults to 10 seconds.
    .timeout(Duration.ofSeconds(10))
    // Optional. Automatic retries for idempotent GET requests only. Default 2.
    .maxRetries(2)
    .build();

Resources

client.events().retrieve(eventId);
client.events().list(environmentId, new ListEventsParams());
client.events().submitOutcome(eventId, SubmitOutcomeRequest.builder()
    .label(OutcomeLabel.LEGITIMATE)
    .build());
client.events().listOutcomes(eventId, page);

client.devices().retrieve(deviceId);
client.devices().list(environmentId, page);
client.devices().listEvents(deviceId, page);
client.devices().listAccounts(deviceId, page);
client.devices().listSignals(deviceId);
client.devices().listResolutions(deviceId, page);
client.devices().trust(environmentId, externalAccountId, deviceId);
client.devices().revokeTrust(environmentId, externalAccountId, deviceId);

client.accounts().listDevices(environmentId, externalAccountId, page);

client.risk().list(environmentId, new ListRiskAssessmentsParams());

client.network().list(environmentId, page);

client.webhooks().verifySignature(rawBody, timestamp, signature, secret);

Synchronous only

SentriqClient is blocking/synchronous. An async client (backed by HttpClient.sendAsync and returning CompletableFuture) was deliberately deferred rather than shipped half-finished — wrap calls in your own executor (e.g. CompletableFuture.supplyAsync(() -> client.events().retrieve(id), executor)) if you need non-blocking usage today.

Errors

try {
    client.events().retrieve(eventId);
} catch (SentriqAuthenticationException e) {
    // 401
} catch (SentriqNotFoundException e) {
    // 404
} catch (SentriqValidationException e) {
    // 422 — e.getFields()
} catch (SentriqRateLimitException e) {
    // 429 — e.getRetryAfterSeconds()
} catch (SentriqApiException e) {
    // any other 4xx/5xx — e.getStatusCode(), e.getRequestId()
} catch (SentriqTransportException e) {
    // network failure — e.isTimeout()
}

A real exception hierarchy rooted at SentriqException (unchecked), matching Node/PHP's own convention rather than Go's flat sentinel-error style.

Retries

A GET request retries automatically (bounded exponential backoff plus jitter) on a network error, timeout, 429, or 5xx, honoring Retry-After (seconds or an HTTP-date). Mutations (POST/DELETE) are never automatically retried — this API has no generic idempotency-key mechanism today, so blindly retrying a mutation could double-apply it. Backoff sleeps are interrupt-safe: an InterruptedException during backoff restores the thread's interrupt flag and aborts the retry rather than being swallowed.

Webhook signatures

boolean valid = client.webhooks().verifySignature(rawBody, timestamp, signature, webhookSecret);

HMAC-SHA256 over the same canonical string as every other SDK, compared with MessageDigest.isEqual — constant-time, not a plain String.equals.

Version compatibility

Java 17+ (CI covers 17 and 21). One runtime dependency, jackson-databind, for typed request/response mapping.