Spring Boot SDK - API Reference

Every public symbol exported by dev.westyx.nexus.*. The auto-configuration creates the NexusClient bean and starts the SSE stream - for most users, the read methods (getConfig, getFlag, getSecret) are the entire API surface.

Construction

`NexusClient.create(NexusConfig config)`

Creates a client and runs a blocking initial sync. Used internally by the auto-configuration; rarely called directly.

NexusClient client = NexusClient.create(NexusConfig.builder()
        .baseUrl("...")
        .apiKey("...")
        .build());

Throws	When
`NexusInitException`	Initial sync failed for any reason. The `getCause()` returns the underlying exception.
`IllegalArgumentException`	`baseUrl` or `apiKey` missing or invalid.

Configs

`Optional<JsonValue> getConfig(String key)`

Returns the resolved config value as a JsonValue (the wire-decoded JSON), or Optional.empty() when the key is absent. JsonValue is the SDK’s own immutable tree rather than a Jackson JsonNode, which is what lets one artifact serve Spring Boot 3 and 4.

String dbUrl = client.getConfig("database.url")
                     .orElseThrow()
                     .asString();

`<T> Optional<T> getConfigAs(String key, Class<T> type)`

Returns the config value coerced to the given type, using Jackson’s treeToValue.

Optional<Integer>  port = client.getConfigAs("server.port", Integer.class);
Optional<String[]> tags = client.getConfigAs("app.tags", String[].class);

`Map<String, JsonValue> getAllConfigs()`

Snapshot copy of every config key-value pair currently in the cache. public-key (wxp_) clients receive all configs and flags, the same set a secret key sees; what they do not receive is secrets, which are absent from the sync response entirely.

Feature flags

`boolean getFlag(String key)` / `boolean getFlag(String key, boolean defaultValue)`

Returns the is_active state of a flag, or defaultValue (default false) when the key is absent.

boolean isOn = client.getFlag("checkout.v2");           // false if missing
boolean isOn = client.getFlag("checkout.v2", true);     // true if missing

`Optional<Boolean> findFlag(String key)` (v0.12.0)

Returns the is_active state, or an empty Optional when the flag is not defined. getFlag cannot express the difference between “the flag does not exist” and “it exists and is off” - both are false. It is what the OpenFeature provider uses to report FLAG_NOT_FOUND, and why an unknown key is never sent to evaluateAB: the endpoint answers false for a key it does not know. getFlag is expressed in terms of findFlag, so the two cannot drift apart.

`Map<String, Boolean> getAllFlags()`

Snapshot copy of every flag key-is_active pair in the cache.

AB Testing (v0.3.0)

`Map<String, Boolean> evaluateAB(List<String> keys, String userId, Map<String, String> attributes)`

Batch-evaluates feature flags with AB Testing semantics. Posts to POST /v1/flags/evaluate-ab and returns the server’s results map verbatim. Unlike getFlag, this method always makes a network call. The call is blocking; run it off the request thread if your handler is latency-sensitive.

Map<String, Boolean> results = client.evaluateAB(
        List.of("checkout.v2", "new-pricing-banner"),
        "user-42",
        Map.of("country", "DE", "plan", "pro"));

boolean newCheckout = results.getOrDefault("checkout.v2", false);

At most 200 keys per call. Attribute values are strings (narrowed from Object in v0.12.0). The endpoint binds them as a string-to-string map and cohort conditions compare them as strings, so formatting the value at the call site is what lets you control exactly what the rule is matched against. A null value is treated as unset and dropped - sent as "" it could satisfy an eq "" condition. Requires the AB Testing add-on to be active on the project; otherwise the server returns HTTP 403.

Throws	When
`NexusAbAddonNotAvailableException`	Server returned HTTP 403 - AB Testing add-on not active for the project.
`NexusUnauthorizedException`	Server returned HTTP 401.
`NexusBillingException`	Server returned HTTP 402 - tenant billing overdue.
`NexusException`	Any other transport, protocol, or JSON-decoding error.

Secrets (secret key only)

`String getSecret(String key)`

Returns the plaintext value of a secret.

String dbPass = client.getSecret("DB_PASSWORD");

Throws	When
`NexusPublicKeyException`	The client uses a public key
`NexusSecretNotFoundException`	The key is not in the cache

`Optional<String> getSecretFilePath(String key)` (v0.3.0)

Returns the absolute path to the on-disk file where the SDK has materialised a type="file" secret, or Optional.empty() when the key is unknown or the secret is of type="text".

String credsPath = client.getSecretFilePath("gcp.service-account.json")
                         .orElseThrow(() -> new IllegalStateException("missing GCP creds"));

GoogleCredentials creds = GoogleCredentials.fromStream(new FileInputStream(credsPath));

Write API (v0.5.0)

The write API allows programmatic secret creation and deletion. Available for secret keys only. Using a public key throws NexusPublicKeyException immediately, before the network call.

`void setSecret(String key, String value)`

Creates or updates a secret with the given key and plaintext value. The secret defaults to type="text".

try {
    client.setSecret("stripe_secret_key", "sk_test_1234...");
} catch (NexusRateLimitedException e) {
    log.error("Rate limit hit on setSecret - retry after {}", e.getRetryAfter());
}

Throws	When
`NexusPublicKeyException`	The client uses a public key
`NexusRateLimitedException`	Server returned HTTP 429 (rate limited on write endpoint)
`NexusUnauthorizedException`	Server returned HTTP 401
`NexusBillingException`	Server returned HTTP 402 - billing overdue
`NexusException`	Any other transport, protocol, or JSON-decoding error

`void deleteSecret(String key)`

Deletes a secret and all its versions.

try {
    client.deleteSecret("old_api_key");
} catch (NexusRateLimitedException e) {
    log.error("Rate limit hit on deleteSecret - retry after {}", e.getRetryAfter());
}

Throws	When
`NexusPublicKeyException`	The client uses a public key
`NexusRateLimitedException`	Server returned HTTP 429 (rate limited on write endpoint)
`NexusUnauthorizedException`	Server returned HTTP 401
`NexusBillingException`	Server returned HTTP 402 - billing overdue
`NexusException`	Any other transport, protocol, or JSON-decoding error

`void deleteSecretVersion(String key, int version)`

Deletes a specific version of a secret.

try {
    client.deleteSecretVersion("stripe_secret_key", 3);
} catch (NexusRateLimitedException e) {
    log.error("Rate limit hit on deleteSecretVersion - retry after {}", e.getRetryAfter());
}

Throws	When
`NexusPublicKeyException`	The client uses a public key
`NexusRateLimitedException`	Server returned HTTP 429 (rate limited on write endpoint)
`NexusUnauthorizedException`	Server returned HTTP 401
`NexusBillingException`	Server returned HTTP 402 - billing overdue
`NexusException`	Any other transport, protocol, or JSON-decoding error

Metadata

Method	Return type	Description
`getKeyType()`	`String`	`"sk"` or `"pk"` - derived from the configured `apiKey`
`getSyncedAt()`	`Instant`	Timestamp of the last successful sync
`isStreamConnected()`	`boolean`	`true` while the SSE stream is connected and pushing events

Sync / lifecycle

`void sync()`

Forces a sync now, bypassing the TTL. Atomically replaces the cache. ETag / If-None-Match is used automatically; a 304 resets the TTL without downloading data. Rarely needed.

`void connectStream()` / `void disconnectStream()`

Start/stop the SSE thread. The auto-configuration calls connectStream() automatically (unless nexus.stream=false). Idempotent.

`void close()`

Stops the SSE thread, removes any temp files created for type="file" secrets, and releases the SDK-owned HTTP clients. The auto-configuration registers this as the bean’s destroy method (destroyMethod = "close"), so it fires automatically on Spring context shutdown. NexusClient implements AutoCloseable, so try-with-resources also works:

try (NexusClient client = NexusClient.create(config)) {
    // use client
}

Exception hierarchy

import dev.westyx.nexus.NexusException;                  // abstract base
import dev.westyx.nexus.NexusInitException;              // initial sync failure
import dev.westyx.nexus.NexusUnauthorizedException;      // HTTP 401
import dev.westyx.nexus.NexusNotFoundException;          // HTTP 404
import dev.westyx.nexus.NexusPublicKeyException;         // getSecret with public key
import dev.westyx.nexus.NexusSecretNotFoundException;    // unknown secret key
import dev.westyx.nexus.NexusAbAddonNotAvailableException; // evaluateAB HTTP 403 (v0.3.0)
import dev.westyx.nexus.NexusQuarantinedException;         // sync 429 quarantine (v0.4.0)

All concrete exceptions extend NexusException. See Error handling for full semantics.

Logger SPI

public interface NexusLogger {
    void debug(String message);
    void info(String message);
    void error(String message, Throwable cause);
}

The auto-configuration installs an SLF4J-backed adapter writing to the logger named dev.westyx.nexus.NexusClient. To override, register your own NexusLogger bean.

Overview

Backend SDKs

Browser SDKs

OpenFeature Providers

Spring Boot SDK - API Reference

Construction

`NexusClient.create(NexusConfig config)`

Configs

`Optional<JsonValue> getConfig(String key)`

`<T> Optional<T> getConfigAs(String key, Class<T> type)`

`Map<String, JsonValue> getAllConfigs()`

Feature flags

`boolean getFlag(String key)` / `boolean getFlag(String key, boolean defaultValue)`

`Optional<Boolean> findFlag(String key)` (v0.12.0)

`Map<String, Boolean> getAllFlags()`

AB Testing (v0.3.0)

`Map<String, Boolean> evaluateAB(List<String> keys, String userId, Map<String, String> attributes)`

Secrets (secret key only)

`String getSecret(String key)`

`Optional<String> getSecretFilePath(String key)` (v0.3.0)

Write API (v0.5.0)

`void setSecret(String key, String value)`

`void deleteSecret(String key)`

`void deleteSecretVersion(String key, int version)`

Metadata

Sync / lifecycle

`void sync()`

`void connectStream()` / `void disconnectStream()`

`void close()`

Exception hierarchy

Logger SPI

​Construction

​NexusClient.create(NexusConfig config)

​Configs

​Optional<JsonValue> getConfig(String key)

​<T> Optional<T> getConfigAs(String key, Class<T> type)

​Map<String, JsonValue> getAllConfigs()

​Feature flags

​boolean getFlag(String key) / boolean getFlag(String key, boolean defaultValue)

​Optional<Boolean> findFlag(String key) (v0.12.0)

​Map<String, Boolean> getAllFlags()

​AB Testing (v0.3.0)

​Map<String, Boolean> evaluateAB(List<String> keys, String userId, Map<String, String> attributes)

​Secrets (secret key only)

​String getSecret(String key)

​Optional<String> getSecretFilePath(String key) (v0.3.0)

​Write API (v0.5.0)

​void setSecret(String key, String value)

​void deleteSecret(String key)

​void deleteSecretVersion(String key, int version)

​Metadata

​Sync / lifecycle

​void sync()

​void connectStream() / void disconnectStream()

​void close()

​Exception hierarchy

​Logger SPI

Construction

`NexusClient.create(NexusConfig config)`

Configs

`Optional<JsonValue> getConfig(String key)`

`<T> Optional<T> getConfigAs(String key, Class<T> type)`

`Map<String, JsonValue> getAllConfigs()`

Feature flags

`boolean getFlag(String key)` / `boolean getFlag(String key, boolean defaultValue)`

`Optional<Boolean> findFlag(String key)` (v0.12.0)

`Map<String, Boolean> getAllFlags()`

AB Testing (v0.3.0)

`Map<String, Boolean> evaluateAB(List<String> keys, String userId, Map<String, String> attributes)`

Secrets (secret key only)

`String getSecret(String key)`

`Optional<String> getSecretFilePath(String key)` (v0.3.0)

Write API (v0.5.0)

`void setSecret(String key, String value)`

`void deleteSecret(String key)`

`void deleteSecretVersion(String key, int version)`

Metadata

Sync / lifecycle

`void sync()`

`void connectStream()` / `void disconnectStream()`

`void close()`

Exception hierarchy

Logger SPI