Kotlin SDK - API Reference

All public API is in the dev.westyx.nexus package.

Factory

`NexusClient.create`

suspend fun create(
    config: NexusConfig,
    engine: HttpClientEngine? = null,
    metadataEngine: HttpClientEngine? = null,
): NexusClient

Validates the configuration, resolves the WIF credential if enabled, and performs an initial sync before returning.

engine - the Ktor engine to use. The SDK bundles none, so when this is null exactly one engine artifact must be on the classpath. Pass one to share the application’s own configuration (proxy, TLS, connection pool). See Installation.
metadataEngine - engine for cloud metadata/IMDS calls. The metadata client is separate and hardened (no redirects, no proxy, short timeout), which is why it is not simply the caller’s own HTTP client.

Throws:

NexusConfigException - an invalid option, named in the message: a non-https baseUrl, a non-positive ttl, a blank or missing apiKey, an sseReconnectCooldown entry below one minute
NexusNoHttpEngineException - no Ktor engine available
NexusWifNotConfiguredException - WIF is enabled but no credential resolved; the client is not created
NexusInitException - the initial sync or session exchange failed, wrapping the cause

Config / secret / flag getters

All getters run a freshness check internally, which triggers a coalesced background sync if the snapshot is older than config.ttl. They never block on the network and never throw because of a network problem - the cached value is returned immediately while the sync runs. See Caching behaviour.

`getString`

fun getString(key: String, default: String): String

Returns the string value for key from the config snapshot. A JSON string is returned verbatim, including an intentionally empty one - an empty string is a value the service set, not a missing key. A JSON number or boolean is rendered as its literal text. An object or array yields default; use getJson for composite values.

`getBoolean`

fun getBoolean(key: String, default: Boolean): Boolean

Returns the boolean value for key. A JSON boolean is used directly. A JSON string is accepted when it reads exactly true or false (case-insensitive, trimmed), because a config surface may store a boolean as text. Anything else - "yes", 1, an object - yields default.

`getInt`

fun getInt(key: String, default: Int): Int

Returns the integer value for key. Returns default if the key is missing, the value is not numeric, has a fractional part, or does not fit in 32 bits - the latter two are also logged at warn, naming which of the two it was. 8 and 8.0 both read as 8: JSON has a single number type, so a whole number is one whether or not it was written with a decimal point. 8.5 does not read as 8 - a fractional value and an out-of-range one are both mismatches rather than something to truncate or saturate, because a wrong number returned as if it were the configured one cannot be detected by the caller. Use getLong for identifiers, amounts in minor units and nanosecond timestamps, and getDouble for a genuine fraction.

`getLong`

fun getLong(key: String, default: Long): Long

Returns the integer value for key as a Long, or default if the key is missing or the value is not an integer that fits in 64 bits. This is the accessor that survives the JSON large-integer problem: the SDK keeps a JSON number as text until the caller names the type it wants, so 9007199254740993 is carried through exactly rather than being rounded on the way in.

`getDouble`

fun getDouble(key: String, default: Double): Double

Returns the double value for key. Returns default if the key is missing or the value is not a valid double.

`getJson`

fun getJson(key: String): JsonElement?

Returns the raw JsonElement value stored in the snapshot for key, or null if not found. Use when the value type is not known at compile time.

`getFlag`

fun getFlag(key: String, default: Boolean = false): Boolean

Returns true if the feature flag key is active, false if it is inactive, or default if the key is not found in the flags snapshot.

`findFlag`

fun findFlag(key: String): Boolean?

Returns whether the flag is active, or null when the flag does not exist. getFlag collapses “absent” and “off” into one boolean, which is usually what a caller wants but leaves no way to report a missing flag; the OpenFeature provider uses this to report FLAG_NOT_FOUND.

`syncedAt`

fun syncedAt(): Instant

When the cached snapshot was last confirmed current - by a 200 OK or a 304 Not Modified.

`getSecret`

fun getSecret(key: String): String

Returns the plaintext value of secret key from the in-memory snapshot. Throws:

NexusPublicKeyException - when the client was created with a public key (wxp_…, browser/frontend, safe to expose)
NexusServiceKindMismatchException - when the service is of kind frontend
NexusSecretNotFoundException - when key is not present in the secrets snapshot

`getSecretFilePath`

fun getSecretFilePath(key: String): String

Returns the absolute path of a file containing the value of secret key. Only available for secrets of type file. The file is 0600 from creation, inside a per-client 0700 directory created on first use. It is removed by close(), or by a JVM shutdown hook if the application exits without calling it. The file name is a SHA-256 hash of both key and value, because the path reaches application logs, environment variables and process listings. See Caching behaviour. Throws:

NexusPublicKeyException - when the client was created with a public key (wxp_…, browser/frontend, safe to expose)
NexusServiceKindMismatchException - when the service is of kind frontend; a path is the secret’s contents, so the same gate as getSecret applies
NexusSecretNotFoundException - when key is not a known file-type secret

`setSecret`

suspend fun setSecret(key: String, value: String, type: String = "text")

Creates or overwrites the secret with the given key. Sends POST /v1/secrets with a JSON body of {"key", "value", "type"}. On success the server responds with 201 Created. Requires a secret key (wxs_…, backend services). Parameters:

key - the secret key to create or overwrite
value - the plaintext secret value
type - the secret type; defaults to "text"

Throws:

NexusPublicKeyException - when the client was created with a public key (wxp_…, browser/frontend, safe to expose)
NexusUnauthorizedException - HTTP 401
NexusBillingException - HTTP 402
NexusNotFoundException - HTTP 404
NexusRateLimitedException - HTTP 429 (non-quarantine rate limit on write endpoints)

`deleteSecret`

suspend fun deleteSecret(key: String)

Deletes all versions of the secret with the given key. Sends DELETE /v1/secrets/:key. On success the server responds with 200 OK. Requires a secret key (wxs_…). Throws:

NexusPublicKeyException - when the client was created with a public key (wxp_…, browser/frontend, safe to expose)
NexusUnauthorizedException - HTTP 401
NexusBillingException - HTTP 402
NexusNotFoundException - HTTP 404
NexusRateLimitedException - HTTP 429 (non-quarantine rate limit on write endpoints)

`deleteSecretVersion`

suspend fun deleteSecretVersion(key: String, version: Int)

Deletes a specific version of the secret with the given key. Sends DELETE /v1/secrets/:key?version=N. On success the server responds with 200 OK. Requires a secret key (wxs_…). Parameters:

key - the secret key
version - the version number to delete

Throws:

NexusPublicKeyException - when the client was created with a public key (wxp_…, browser/frontend, safe to expose)
NexusUnauthorizedException - HTTP 401
NexusBillingException - HTTP 402
NexusNotFoundException - HTTP 404
NexusRateLimitedException - HTTP 429 (non-quarantine rate limit on write endpoints)

A/B evaluation

`evaluateAB`

suspend fun evaluateAB(
    keys:       List<String>,
    userId:     String,
    attributes: Map<String, String> = emptyMap(),
): Map<String, Boolean>

Sends a server-side A/B evaluation request to POST /v1/flags/evaluate-ab. Returns a map of flag key to true/false for the given userId and optional attributes. Throws:

NexusAbAddonNotAvailableException - when the A/B testing add-on is not active for this project (HTTP 403)
NexusException - for any other non-success HTTP status

Sync

`sync`

suspend fun sync()

Manually triggers a full sync against GET /v1/sync. Uses ETag/If-None-Match to skip the response body when nothing has changed (304 Not Modified), which also resets the freshness stamp. Updates the in-memory snapshot atomically on success, serialised with any background refresh so responses cannot apply out of order. Throws:

NexusClosedException - the client has been closed
NexusUnauthorizedException - HTTP 401
NexusBillingException - HTTP 402 (also backs the background refresh off for five minutes and calls observer.onBillingOverdue())
NexusForbiddenException - HTTP 403
NexusNotFoundException - HTTP 404
NexusQuarantinedException - HTTP 429 with a quarantine body, its deadline clamped to at most 24 hours
NexusRateLimitedException - HTTP 429 without one
NexusResponseTooLargeException - the body exceeded 8 MiB

Stream

`connectStream`

fun connectStream()

Starts the SSE stream in a background coroutine. Changes published on the Nexus platform trigger a coalesced sync automatically. The stream reconnects with exponential back-off on transport failures, and also after a clean server close - which is what a deploy and a WIF session rollover produce. Idempotent: calling it while a stream is running leaves that stream in place. Throws: NexusClosedException on a closed client. See SSE live updates.

`disconnectStream`

fun disconnectStream()

Cancels all active stream coroutines and sets streamStatus to DISCONNECTED. Does not affect the background TTL sync or the HTTP client.

`streamStatus`

val streamStatus: StateFlow<StreamStatus>

A StateFlow that reflects the current stream connection state. Possible values:

Value	Meaning
`CONNECTED`	SSE connection is established and receiving events
`FALLBACK`	The stream gave up for now - 3 consecutive failures, a quarantine, or a rate limit - and TTL sync is covering freshness; a reconnect is scheduled
`DISCONNECTED`	Not connected; either never started, or temporarily between reconnect attempts

Lifecycle

`close`

override fun close()

NexusClient implements AutoCloseable. close() cancels the internal coroutine scope (including the stream), closes both HTTP clients and the metadata client, closes the WIF credential source - releasing an AWS credentials provider’s IMDS client and refresh thread - and removes every file written for a file-type secret. It is idempotent and final: a closed client raises NexusClosedException from sync(), connectStream() and the write methods, and streamStatus reads DISCONNECTED. Cached getters keep working, since they touch nothing that was released.

NexusClient.create(config).use { client ->
    // ...
}

Overview

Backend SDKs

Browser SDKs

OpenFeature Providers

Kotlin SDK - API Reference

Factory

`NexusClient.create`

Config / secret / flag getters

`getString`

`getBoolean`

`getInt`

`getLong`

`getDouble`

`getJson`

`getFlag`

`findFlag`

`syncedAt`

`getSecret`

`getSecretFilePath`

`setSecret`

`deleteSecret`

`deleteSecretVersion`

A/B evaluation

`evaluateAB`

Sync

`sync`

Stream

`connectStream`

`disconnectStream`

`streamStatus`

Lifecycle

`close`

​Factory

​NexusClient.create

​Config / secret / flag getters

​getString

​getBoolean

​getInt

​getLong

​getDouble

​getJson

​getFlag

​findFlag

​syncedAt

​getSecret

​getSecretFilePath

​setSecret

​deleteSecret

​deleteSecretVersion

​A/B evaluation

​evaluateAB

​Sync

​sync

​Stream

​connectStream

​disconnectStream

​streamStatus

​Lifecycle

​close

Factory

`NexusClient.create`

Config / secret / flag getters

`getString`

`getBoolean`

`getInt`

`getLong`

`getDouble`

`getJson`

`getFlag`

`findFlag`

`syncedAt`

`getSecret`

`getSecretFilePath`

`setSecret`

`deleteSecret`

`deleteSecretVersion`

A/B evaluation

`evaluateAB`

Sync

`sync`

Stream

`connectStream`

`disconnectStream`

`streamStatus`

Lifecycle

`close`