> ## Documentation Index
> Fetch the complete documentation index at: https://docs.westyx.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Kotlin SDK

> Official Kotlin/JVM SDK for Westyx Nexus - coroutines, type-safe getters, WIF.

The official Kotlin/JVM SDK for [Westyx Nexus](https://westyx.dev) - the platform for managing configs, secrets, and feature flags across your services.

The SDK gives your JVM application a local in-memory cache of all config entries, secrets, and feature flags for its service. Values are kept fresh via background TTL-based sync against the Nexus API. An optional SSE stream delivers push updates so your application reacts to changes within seconds.

```kotlin theme={null}
// build.gradle.kts
dependencies {
    implementation("dev.westyx.nexus:nexus-kotlin-sdk:0.10.0")
}
```

## Highlights

* **Type-safe getters** - `getString`, `getBoolean`, `getInt`, `getDouble`, `getJson`
* **Secrets** - in-memory access via `getSecret`, temp-file access via `getSecretFilePath`
* **Feature flags** - `getFlag` with safe boolean default
* **A/B testing** - server-side `evaluateAB` with user ID and attributes
* **SSE live updates** - `connectStream()` pushes config/flag changes in real time
* **Workload identity federation (WIF)** - Kubernetes, AWS IRSA, GCP, Azure, developer mode, and **AWS IAM (`aws_iam`)** for ECS/Fargate/Lambda/plain-EC2 *(v0.9.0)*
* **Observability** - `NexusObserver` hooks for connect, disconnect, reconnect, quarantine, billing events
* **Resilience** - exponential back-off, quarantine pause, billing-overdue pause, TTL fallback

## What's new in v0.10.0

* Version alignment across the Westyx Nexus SDK suite.

## What's new in v0.9.0

* **`aws_iam` WIF provider (AWS IAM Caller Identity)** - authenticates non-EKS AWS compute (**ECS/Fargate, Lambda, plain EC2**) that has IAM credentials but no OIDC token. The SDK SigV4-signs an STS `GetCallerIdentity` request (never sent to AWS) and posts it to `/v1/auth/token-exchange`; Nexus replays it against a pinned STS endpoint to prove your IAM role. The signed `X-Nexus-Server-ID` is your service's own base-URL host - a captured request is valid for that one service only, and there is nothing to configure. Requires the optional `software.amazon.awssdk:auth` + `:regions` dependencies. See [Workload identity](workload-identity).
* **Azure fix (was requesting an ARM token)** - the `azure` provider no longer requests the privileged `management.azure.com` resource; it now prefers the projected federated token file (`$AZURE_FEDERATED_TOKEN_FILE`, AKS) and otherwise requests the configured `api://<client-id>` audience on IMDS, refusing the generic default.
* **Probe-based auto-detection + hardened metadata client** - auto-detect now stats the token files and live-probes the metadata servers (\~1 s timeout); the metadata Ktor client no longer follows redirects and does not use a system proxy.
* **Security hardening** - `NexusClient.create` rejects plain-http base URLs (loopback excepted); expired WIF sessions refresh transparently on reads and fail closed; the `expires_in<=60` refresh loop is fixed; metadata reads are bounded.

## What's new in v0.8.0

* **OpenFeature provider** - new `nexus-kotlin-openfeature` sub-module. See [OpenFeature](openfeature).

## What's new in v0.6.0

* **SSE reconnect after polling fallback** - the SDK re-attempts the SSE stream after falling back
  to TTL polling. `sseReconnectCooldown` controls the delay (clamped 1s-300s).

## What's new in v0.4.0

* Added `evaluateAB` for server-side A/B flag evaluation per user
* Quarantine support: server-driven pause on `POST /v1/sync` and `/v1/stream` 429 responses; the SDK sleeps until `expiresAt` and reconnects without incrementing the failure counter
* `auth_expiring` SSE event: proactive WIF session refresh before the session token expires
* `getSecretFilePath` for file-type secrets written to a temp directory
* `NexusObserver.onQuarantined(reason, expiresAt)` callback
* `streamStatus: StateFlow<StreamStatus>` exposed as a public property

## Package

Hosted on the [GitLab Maven Package Registry](https://gitlab.com/westyx/nexus/sdk/kotlin/-/packages). Install:

```kotlin theme={null}
// build.gradle.kts
repositories {
    maven {
        url = uri("https://gitlab.com/api/v4/projects/82635144/packages/maven")
        credentials(HttpHeaderCredentials::class) {
            name = "Deploy-Token"
            value = System.getenv("NEXUS_DEPLOY_TOKEN")
        }
        authentication { create<HttpHeaderAuthentication>("header") }
    }
}

dependencies {
    implementation("dev.westyx.nexus:nexus-kotlin-sdk:0.10.0")
}
```

Latest release: **v0.10.0** *(2026-07-05 - version alignment across the Westyx Nexus SDK suite)*.

## What's new in v0.5.1

* **Security improvements** - exception messages contain only status codes; `file`-type secret paths are fully hashed so key names are never visible on the filesystem.
* **Thread-safe WIF session** - session state is an atomic reference pair; concurrent token refresh calls are serialised with a `Mutex`.
* **CI improvements** - test stage runs on every MR; publish is restricted to `main`-branch tags.

## What's new in v0.5.0

* **Write API** - `setSecret`, `deleteSecret`, `deleteSecretVersion` for programmatic secret management. secret keys only; public keys throw `NexusPublicKeyException` immediately without a network call.
* **`NexusRateLimitedException`** - new exception for HTTP 429 on write endpoints.

## Pages

| Page                                   | Description                                                |
| -------------------------------------- | ---------------------------------------------------------- |
| [Installation](installation)           | Gradle and Maven setup, registry URL, version requirements |
| [Configuration](configuration)         | `NexusConfig` field reference                              |
| [API reference](api-reference)         | All public methods with signatures                         |
| [Error handling](error-handling)       | Exception table and catch examples                         |
| [SSE live updates](sse-live-updates)   | Stream connection, reconnect, quarantine, rate-limit       |
| [Stream observer](stream-observer)     | `NexusObserver` callback reference                         |
| [Workload identity](workload-identity) | WIF providers, token exchange, trust policies              |
| [Caching behaviour](caching-behaviour) | TTL sync, ETag/304, quarantine/billing pauses              |