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

# Node.js SDK

> Official Node.js SDK for Westyx Nexus - zero external dependencies, typed error hierarchy.

Official Node.js SDK for [Westyx Nexus](https://westyx.dev) - the centralised secrets, feature flags, and config service.

```ts theme={null}
import { NexusClient } from '@westyx-nexus/sdk-nodejs';

const client = await NexusClient.create({
  endpoint: 'https://swift-ocean-a5rx7.westyx.dev',
  apiKey:   'wxs_...',
});

const dbHost = client.getConfig('DB_HOST');
const dbPass = client.getSecret('DB_PASSWORD');           // secret key only
const isOn   = client.getFlag('new-checkout', false);

process.on('SIGTERM', async () => { await client.close(); process.exit(0); });
```

## 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 endpoint host - a captured request is valid for that one service only, and there is nothing to configure. See [Workload identity](workload-identity#aws-iam-non-eks-aws-compute).
* **Azure Workload Identity (AKS)** - the `azure` provider now prefers the projected federated token file (`$AZURE_FEDERATED_TOKEN_FILE`) before falling back to IMDS; auto-detection probes the file too.
* **Probe-based auto-detection** - auto-detect now stats the Kubernetes / AWS-IRSA / Azure token files and live-probes the GCP and Azure metadata servers (\~1 s timeout), instead of keying on environment variables absent on real cloud nodes.
* **Security hardening** - `NexusClient.create()` rejects plain-http endpoints (loopback excepted); the Azure IMDS path refuses the generic default audience (must be `api://<client-id>`); expired WIF sessions refresh on write paths too (fail-closed).

## What's new in v0.8.0

* **`getConfig()` return type fix** - `getConfig()` now returns `unknown` (was `string | undefined`). Config values from the backend are JSON-typed (numbers, booleans, objects, arrays). Use type narrowing or an `as` cast where you need a specific type.
* **`getAllConfigs()` return type fix** - return type changed from `Record<string, string>` to `Record<string, unknown>`.
* **OpenFeature provider** - new `@westyx-nexus/openfeature-provider-nodejs` sub-package wrapping `NexusClient` as an [OpenFeature Server SDK](https://openfeature.dev) provider. See [OpenFeature](openfeature).

## What's new in v0.5.1

* **Security improvements** - exception messages contain only status codes; `file`-type secret paths are fully hashed.
* **Node.js 22+ required** - `engines.node` set to `>=22` (Node 18 and 20 are EOL).
* **Enhanced observability** - background sync activity and WIF session refresh events are now surfaced via the optional `config.logger` or Node.js `process.emitWarning`.
* **`NexusConfig.logger`** - optional logger interface for SDK diagnostic output.
* **CI** - test stage runs on merge requests; publish is restricted to `main`-branch tags.

## What's new in v0.5.0

* **Write API** - `setSecret(key, value)`, `deleteSecret(key)`, `deleteSecretVersion(key, version)` for programmatic secret management. secret keys only; public keys get `NexusPublicKeyError` immediately without a network call.
* **`NexusRateLimitedError`** - new typed error thrown on HTTP 429 from write endpoints.

## What's new in v0.4.0

* **Path prefix change** - all API calls now target `/v1/` (was `/api/v1/`). Update proxy/firewall rules if you filter on URL paths.
* **`NexusQuarantinedError`** - new typed error thrown by `_doSync` when the backend returns `429` with a quarantine body. The background sync guard respects `expiresAt` automatically.
* **`NexusAbAddonNotAvailableError`** - new typed error thrown by `evaluateAB` on HTTP 403 (AB Testing add-on not active for this project).
* **`StreamObserver.onQuarantined`** - new optional callback fired when the SSE stream receives a quarantine `429`; the stream sleeps until `expiresAt` and reconnects automatically without counting toward `MAX_FAILURES`.
* **`ConfigEntry.is_public` removed** - the field is no longer part of the sync response shape.

## What's new in v0.3.1

* **`Retry-After`-aware SSE 429 handling** - when the server returns `429 Too Many Requests` on `/v1/stream` with a parseable `Retry-After` header, the stream now sleeps the indicated delay (clamped to `[5 s, 5 min]`) and reconnects automatically. The Retry-After delay does **not** count toward `MAX_FAILURES`.

## Highlights

* **Node.js 18+** - single package, **zero external dependencies** (stdlib only)
* **Thread-safe TTL cache** with atomic snapshot replacement and ETag/304 support
* **Background refresh** - request handlers are never blocked on cache expiry
* **SSE live updates** - propagates remote changes within milliseconds; falls back to TTL polling after 3 transport errors
* **File-type secrets** - automatic temp-file management for PEM certs, JSON keys, etc.
* **Typed error hierarchy** - `NexusError` base + 12 subclasses for `instanceof` checks
* **Workload Identity Federation** *(v0.2.0)* - Kubernetes / AWS IRSA / GCP / Azure auto-detection; bearer JWT auth; **AWS IAM (`aws_iam`)** for ECS/Fargate/Lambda/plain-EC2 *(v0.9.0)*
* **Stream observer hooks** *(v0.2.0)* - structured callbacks for SSE lifecycle events

## Package

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

```sh theme={null}
npm install @westyx-nexus/sdk-nodejs
```

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

## Pages

| Page                                   | Description                                           |
| -------------------------------------- | ----------------------------------------------------- |
| [Installation](installation)           | Register the GitLab npm registry, install the package |
| [Configuration](configuration)         | `NexusConfig` field reference                         |
| [API reference](api-reference)         | Every public method, getter, and remote evaluator     |
| [Error handling](error-handling)       | Error hierarchy + when each is thrown                 |
| [SSE live updates](sse-live-updates)   | How live propagation works, 429 handling              |
| [Stream observer](stream-observer)     | `StreamObserver` reference                            |
| [Workload identity](workload-identity) | WIF setup, providers, custom token sources            |
| [Caching behaviour](caching-behaviour) | When does the SDK hit the network                     |
| [OpenFeature](openfeature)             | OpenFeature Server SDK provider                       |