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,
): NexusClient

Creates a new NexusClient and performs an initial synchronous sync before returning. Throws NexusInitException wrapping any underlying failure if the initial sync does not succeed. The engine parameter is optional and is intended for testing with MockEngine.

Config / secret / flag getters

All getters call ensureFresh() internally, which triggers a background sync if the snapshot is older than config.ttl. They never block on the network call - the stale value is returned immediately while sync runs in the background.

`getString`

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

Returns the string value for key from the config snapshot, or default if the key is not present or the value is empty.

`getBoolean`

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

Returns the boolean value for key. Parses "true" / "false" (case-insensitive strict). Returns default if the key is missing or the value cannot be parsed.

`getInt`

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

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

`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.

`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 wxp_... key
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 to a temporary file containing the value of secret key. Only available for secrets of type file. The file is created during sync and deleted when close() is called. Throws:

NexusPublicKeyException - when the client was created with a wxp_... key
NexusSecretNotFoundException - when key is not a known file-type secret

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.

`setSecret`

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

Creates or updates a secret with the given key, plaintext value, and optional type (defaults to "text").

try {
    client.setSecret("stripe_secret_key", "sk_test_1234...")
} catch (e: NexusRateLimitedException) {
    logger.error("Rate limit hit on setSecret - retry after ${e.retryAfter}")
}

Throws:

NexusPublicKeyException - when the client uses a wxp_... key
NexusRateLimitedException - HTTP 429 on write endpoint
NexusUnauthorizedException - HTTP 401
NexusBillingException - HTTP 402 (billing overdue)
NexusException - any other error

`deleteSecret`

suspend fun deleteSecret(key: String)

Deletes a secret and all its versions.

try {
    client.deleteSecret("old_api_key")
} catch (e: NexusRateLimitedException) {
    logger.error("Rate limit hit on deleteSecret - retry after ${e.retryAfter}")
}

Throws:

NexusPublicKeyException - when the client uses a wxp_... key
NexusRateLimitedException - HTTP 429 on write endpoint
NexusUnauthorizedException - HTTP 401
NexusBillingException - HTTP 402 (billing overdue)
NexusException - any other error

`deleteSecretVersion`

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

Deletes a specific version of a secret.

try {
    client.deleteSecretVersion("stripe_secret_key", 3)
} catch (e: NexusRateLimitedException) {
    logger.error("Rate limit hit on deleteSecretVersion - retry after ${e.retryAfter}")
}

Throws:

NexusPublicKeyException - when the client uses a wxp_... key
NexusRateLimitedException - HTTP 429 on write endpoint
NexusUnauthorizedException - HTTP 401
NexusBillingException - HTTP 402 (billing overdue)
NexusException - any other error

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.

val results = client.evaluateAB(
    keys       = listOf("checkout-v2", "banner-v3"),
    userId     = "user-42",
    attributes = mapOf("country" to "HU", "plan" to "pro"),
)
if (results["checkout-v2"] == true) {
    showNewCheckout()
}

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). Updates the in-memory snapshot atomically on success. Throws:

NexusUnauthorizedException - HTTP 401
NexusBillingException - HTTP 402 (also sets billing-overdue flag and calls observer.onBillingOverdue())
NexusNotFoundException - HTTP 404
NexusQuarantinedException - HTTP 429 with quarantine body

Stream

`connectStream`

fun connectStream()

Starts the SSE stream connection in a background coroutine. Config changes and flag toggles published on the Nexus platform trigger a sync() call automatically. The stream reconnects with exponential back-off on transient failures.

`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`	Stream gave up after `MAX_STREAM_ERRORS` (3) consecutive failures; TTL sync remains active
`DISCONNECTED`	Not connected; either never started, or temporarily between reconnect attempts

Lifecycle

`close`

fun close()

Cancels the internal coroutine scope, closes both HTTP clients, and deletes all temp files written by getSecretFilePath. Call this when the application shuts down. After close(), the client is unusable.

Overview

Backend SDKs

Browser SDKs

OpenFeature Providers

Kotlin SDK - API Reference

Factory

`NexusClient.create`

Config / secret / flag getters

`getString`

`getBoolean`

`getInt`

`getDouble`

`getJson`

`getFlag`

`getSecret`

`getSecretFilePath`

Write API (v0.5.0)

`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

​getDouble

​getJson

​getFlag

​getSecret

​getSecretFilePath

​Write API (v0.5.0)

​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`

`getDouble`

`getJson`

`getFlag`

`getSecret`

`getSecretFilePath`

Write API (v0.5.0)

`setSecret`

`deleteSecret`

`deleteSecretVersion`

A/B evaluation

`evaluateAB`

Sync

`sync`

Stream

`connectStream`

`disconnectStream`

`streamStatus`

Lifecycle

`close`