Node.js SDK

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

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

​

What’s new in v0.15.0

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

​

What’s new in v0.14.0

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

​

What’s new in v0.13.0

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

​

What’s new in v0.12.0

• The OpenFeature provider resolves per user. 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 - targetingTtlMs, maxTargetingKeys and addonSuppressionMs, each validated at construction.

​

What’s new in v0.11.0

• 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. An integer beyond 2^53 arrives as a bigint rather than as a silently different number; getConfigRaw gives you the JSON text.
• Structured logging. Four levels, values carried as fields, every record tagged with the component that produced it.
• SSE idle detection. 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 - forRoot / forRootAsync, NexusClient as an injectable singleton, teardown that closes the client.
• Configuration is validated at construction, 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.
• 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.

​

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.
• 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 provider. See 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 22+ - the oldest line still receiving security patches; CI tests 22, 24 and 26
• Zero runtime dependencies in the core package - stdlib only
• Dual ESM + CommonJS, verified by attw and publint on every pipeline run
• In-memory snapshot cache with atomic 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 + 17 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

npm install @westyx-nexus/sdk-nodejs

npm install @westyx-nexus/sdk-nestjs
npm install @westyx-nexus/openfeature-provider-nodejs @openfeature/server-sdk
npm install @westyx-nexus/wif-aws-nodejs

​

Pages