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

# Node.js SDK - Version history

> What changed in each release of the Node.js SDK packages, and how to migrate across a breaking change.

Every release of the four packages (`@westyx-nexus/sdk-nodejs`, `@westyx-nexus/sdk-nestjs`,
`@westyx-nexus/openfeature-provider-nodejs`, `@westyx-nexus/wif-aws-nodejs`), newest first. All
four release from one tag and share one version number. Where a release broke something, its
**Migrating** section shows the change to make. The repository's
[`CHANGELOG.md`](https://gitlab.com/westyx/nexus/sdk/nodejs/-/blob/main/CHANGELOG.md) carries the
same releases in full detail.

## v0.20.1 - 2026-11-19

* **Stream observer on `423 service_locked`:** calls `onDisconnected(new NexusServiceLockedError('stream'))` after `onFallback(FALLBACK_REASON_SERVICE_LOCKED)` when the SSE stream exits on `423`.

## v0.20.0 (2026-11-19)

* **HTTP 423 `service_locked`:** adds `NexusServiceLockedError`, `SERVICE_LOCKED_CODE`, and `FALLBACK_REASON_SERVICE_LOCKED`; stops SSE reconnects immediately and halts background sync retries until an explicit sync succeeds.
* **OpenFeature provider:** suppresses repeated `evaluate-ab` requests while the service is locked down, serving the cached snapshot as `STALE`.

## v0.19.1 - 2026-11-12

* **The OpenFeature provider stops asking a switched-off environment.** While the environment is switched off in the console, a targeted evaluation serves the snapshot as `STALE` and the provider sends no `evaluateAB` request - for any user - for the `addonSuppressionMs` window, with one warning; any success clears it.
* **The OpenFeature provider, `@westyx-nexus/sdk-nestjs` and `@westyx-nexus/wif-aws-nodejs` require `@westyx-nexus/sdk-nodejs` `>=0.19.1`.**

## v0.19.0 - 2026-11-11

* **A switched-off environment is reported by name.** When a project switches the service's
  environment off, every request is refused with `403 {"error":"environment_disabled"}`, and the
  SDK throws `NexusEnvironmentDisabledError` instead of a generic 403. The cache keeps serving; the
  background refresh and the stream wait five minutes between attempts
  (`onFallback('environment-disabled')`), and the first successful sync clears it.
* **Every API error carries its status and code.** A response no more specific error describes
  throws `NexusApiError` with `status` and `code` (the response's `error` field). The message
  never carries the response body.
* **The startup summary.** After the first sync the client logs `nexus: client loaded` at `info`,
  naming the configs, secrets and flags it received - names only, never a value. The NestJS module
  shows it in the application log with nothing configured. Without a `logger`,
  `WESTYX_NEXUS_LOG_STARTUP=1` writes it to standard error.
* **`NODE_DEBUG=westyx-nexus`.** Without a `logger`, the SDK's `debug` and `info` records go to
  `util.debuglog`, Node's own switch for library diagnostics.
* **The safety-net poll returns to your `ttl`** when the stream disconnects or falls back; it
  stayed at 60 seconds once the stream had connected.
* **A retry after the stream's cooldown starts the backoff at 1 s.**
* **Breaking - `exchangePayload` returns a credential, not JSON.** See below.
* **Node.js 26 LTS** is part of every test run, for the core and all three sibling packages.
* **The three sibling packages require the SDK at `>=0.19.0`.**

### Migrating to v0.19.0

`wif.exchangePayload` resolves to an `ExchangeCredential` and the SDK writes the request body:

```ts theme={null}
// before
exchangePayload: async () => JSON.stringify({ oidc_token: await readToken() }),
// now
exchangePayload: async () => ({ kind: 'oidc', token: await readToken() }),
```

`awsIamExchangePayload()` needs no change - upgrade `@westyx-nexus/wif-aws-nodejs` together with
the SDK. `signAwsIamPayload` returns `{ kind: 'aws_iam', headers, body }` instead of a string.

Code that matched the old message of an unmapped status (`unexpected status 500`) reads
`err.status` instead.

## v0.18.0 - 2026-10-04

* **The client tells you what the server left out.** A sync response can report resources it did
  not deliver - a secret that has no value yet, a config whose `{{secret:KEY}}` reference does not
  resolve. The client logs each one as a warning, once, when it first appears, and
  `client.getSyncErrors()` returns the current list. `logSyncErrors: false` keeps the list without
  the log lines.
* **The three sibling packages require the SDK at `>=0.18.0`.**

## v0.17.0 - 2026-09-29

* **The endpoint can come from the environment.** When `endpoint` is omitted, the client reads
  `WESTYX_SERVICE_ENDPOINT`, so the same code runs against any environment, and a Developer WIF
  credential written by `westyx dev setup` is found with no endpoint in application code. The config
  field wins when both are set.
* **The three sibling packages require the SDK at `>=0.17.0`.**

## v0.16.1 - 2026-09-27

* **A service with no configs or no feature flags reads exactly like one that has them.**
  `/v1/sync` leaves a map out of the response entirely when the service has none of that
  kind, so the client normalises the payload before caching it: `getConfig`, `getFlag`,
  `hasFlag`, `getAllConfigs` and `getAllFlags` return the absent-value result, and
  `create()` completes. A service that starts with no flags and gains them later needs no
  change.
* **The three sibling packages require the SDK at `>=0.16.1`.** All four publish from one
  tag, and CI asserts the floor names the released version.

## v0.16.0 - 2026-08-27

* **A custom `logger` whose method throws no longer fails an SDK operation.** Every
  internal log call is contained, so a logging sink that raises - a full disk, a down
  syslog target - is dropped and the read, refresh, or `create()` that logged continues.
  The stream observer already had this guarantee; it now covers the logger too. The
  Workload Identity credential source is deliberately not contained - it is on the auth
  path and still surfaces its error.

## v0.15.0 - 2026-08-12

* **`instanceof` holds across the ESM and CommonJS builds.** One process can hold both -
  an application importing the SDK and a dependency requiring it - and an error raised
  through either is recognised by the other's classes, base and subclass alike. Catching
  by type is the documented form and it works whichever build a given module resolved.
* **The signed service identity carries a non-default port.** `ExchangeContext.serverId`
  is the endpoint's host including its port - the value the request's `Host` header
  holds, and the one the backend validates `X-Nexus-Server-ID` against. `aws_iam`
  therefore authenticates on a deployment that does not listen on the scheme's default
  port, and a `developer` credential is selected per service rather than per hostname.
* **File-type secrets are written without blocking the event loop**, so materialising a
  secret during a background sync does not stall the requests a server is handling.
* **The three sibling packages require the SDK at `>=0.15.0`.** All four publish from one
  tag, and CI asserts the floor names the released version.

## v0.14.0 - 2026-08-10

* **The `developer` Workload Identity provider.** A session issued by `westyx dev setup`
  is used as the Bearer directly - there is no token exchange on this path - so a laptop
  can authenticate to a WIF-enforced service. It is probed last, behind every cloud
  provider, so a workload's own credential always wins on a real cloud host.
* **A provider constant carries its literal type**, so a `switch` over one narrows and
  the resolver is exhaustiveness-checked. `provider: 'custom'` is now a compile error:
  `'custom'` is the label the SDK reports for `tokenSource` and `exchangePayload`, not a
  selector.
* **`provider: 'aws_iam'` combined with a `tokenSource` throws** the message naming
  `@westyx-nexus/wif-aws-nodejs`, instead of sending a bearer token.
* **A client renders a redacted summary when it is logged or inspected** - endpoint, key
  type, provider and cache counts, never a credential.

## v0.13.0 - 2026-08-06

* **A composite (object or array) OpenFeature resolution carries an integer beyond
  `Number.MAX_SAFE_INTEGER` as its exact decimal string** - at any depth, in objects and
  arrays alike, so the resolved value survives `JSON.stringify`. Ordinary numbers are
  untouched, and the scalar number resolution still answers `TYPE_MISMATCH` for the
  same value.

## v0.12.0 - 2026-07-31

* **[The OpenFeature provider resolves per user](https://docs.westyx.dev/sdks/nodejs/openfeature.md#per-user-targeting).** An `EvaluationContext` carrying a `targetingKey` now selects a per-user boolean evaluation through the Nexus AB Testing add-on, so rollout percentages and cohort rules apply. One request covers every flag in the snapshot, results are memoised per user for 30 seconds, and concurrent evaluations for the same user coalesce into one call.
* **[The provider takes options](https://docs.westyx.dev/sdks/nodejs/openfeature.md#options)** - `targetingTtlMs`, `maxTargetingKeys` and `addonSuppressionMs`, each validated at construction.

Upgrading needs no source change. The core SDK, the NestJS module and the AWS IAM provider release on the same version with no changes of their own.

## v0.11.0 - 2026-07-28

Four packages now ship from this repository: the SDK, the [NestJS module](https://docs.westyx.dev/sdks/nodejs/nestjs.md), the [OpenFeature provider](https://docs.westyx.dev/sdks/nodejs/openfeature.md), and the [AWS IAM WIF provider](https://docs.westyx.dev/sdks/nodejs/workload-identity.md).

* **Dual ESM + CommonJS.** `import` and `require` both work, each resolving to the right build and the right type declarations.
* **Zero runtime dependencies.** The AWS credential chain moved to `@westyx-nexus/wif-aws-nodejs`, so installing the SDK installs one package - 544 KB, against 34 packages and 14 MB before.
* **[Config integers stay exact at any size](https://docs.westyx.dev/sdks/nodejs/config-values.md).** An integer beyond 2^53 arrives as a `bigint` rather than as a silently different `number`; `getConfigRaw` gives you the JSON text.
* **[Structured logging](https://docs.westyx.dev/sdks/nodejs/logging.md).** Four levels, values carried as fields, every record tagged with the component that produced it.
* **[SSE idle detection](https://docs.westyx.dev/sdks/nodejs/sse-live-updates.md#deadlines).** A connection that has stopped delivering is reconnected instead of being reported as healthy, and establishing the connection has a deadline of its own.
* **[A NestJS module](https://docs.westyx.dev/sdks/nodejs/nestjs.md)** - `forRoot` / `forRootAsync`, `NexusClient` as an injectable singleton, teardown that closes the client.
* **[Configuration is validated at construction](https://docs.westyx.dev/sdks/nodejs/configuration.md)**, with the offending option and value named, instead of being coerced.
* **An observer callback that throws is contained** rather than ending the process. See [Stream observer](https://docs.westyx.dev/sdks/nodejs/stream-observer.md).
* **A billing 402 throttles background refresh rather than stopping it**, so settling the invoice restores service without a restart.
* New: `getConfigRaw`, `hasFlag`, `refresh()`, `streamConnected`, `streamIdleTimeout`, `connectTimeout`, `requestTimeout`.

Breaking: `aws_iam` moved to its own package and is selected through `wif.exchangePayload`; the logger interface gained three levels and a fields argument; coerced configuration values are now rejected. See the [file-type secret guarantees](https://docs.westyx.dev/sdks/nodejs/file-secret-security.md) too.

## v0.10.0 - 2026-07-05

* Version alignment across the Westyx Nexus SDK suite.

## v0.9.0 - 2026-07-03

* **`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](https://docs.westyx.dev/sdks/nodejs/workload-identity.md#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).

## v0.8.0 - 2026-06-16

* **`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](https://docs.westyx.dev/sdks/nodejs/openfeature.md).

### Migrating to v0.8.0

`getConfig()` returns `unknown` instead of `string | undefined`. Where you relied on the old type,
narrow with `typeof value === 'string'` or cast with `as string`.

## v0.5.1 - 2026-06-03

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

## v0.5.0 - 2026-06-01

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

## v0.4.0 - 2026-05-28

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

## v0.3.1 - 2026-05-13

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.