Node.js SDK - API Reference

Every public symbol exported by @westyx-nexus/sdk-nodejs. All read methods are synchronous (cache-backed); only create, evaluateFlags, evaluateAB, and close are async.

Construction

`NexusClient.create(config: NexusConfig): Promise<NexusClient>`

Creates a client and runs a blocking initial sync.

const client = await NexusClient.create({
  endpoint: '...',
  apiKey:   '...',
});

Throws	When
`NexusInitError`	The initial sync failed for any reason. The `cause` property carries the underlying error (often `NexusUnauthorizedError` or a transport-level error).

The SSE stream and the polling timer start automatically once the initial sync succeeds.

Configs

`client.getConfig(key: string): unknown`

Returns the resolved config value, or undefined if the key is absent. An integer beyond Number.MAX_SAFE_INTEGER is returned as a bigint rather than a silently different number - see Config values.

const dbHost = client.getConfig('DB_HOST');

a public-key client receives the same configs and flags a secret key does; what it does not receive is secrets, which are absent from the sync response entirely.

`client.getConfigRaw(key: string): string | undefined`

Returns the config value as JSON text, exactly as the SDK holds it, or undefined when the key is absent. See Config values for why this exists.

`client.getAllConfigs(): Record<string, unknown>`

Snapshot copy of every config key-value pair currently in the cache.

Feature flags

`client.getFlag(key: string, defaultValue?: boolean): boolean`

Returns the is_active state of a flag, or defaultValue (default false) when the key is absent.

client.getFlag('checkout.v2');           // false if missing
client.getFlag('checkout.v2', true);     // true if missing

`client.hasFlag(key: string): boolean`

Reports whether a flag exists in the current snapshot - distinguishing “absent” from “present and false”, which getFlag cannot since both return false.

`client.getAllFlags(): Record<string, boolean>`

Snapshot copy of every flag key-is_active pair in the cache.

`client.evaluateFlags(keys: string[]): Promise<Record<string, boolean>>`

Live network call to the server’s batch evaluator. Useful when you need the most recent state and don’t want to wait for the next sync.

const result = await client.evaluateFlags(['flag-a', 'flag-b']);
// => { 'flag-a': true, 'flag-b': false }

Missing keys resolve to false - never throws for an unknown key.

Throws	When
`NexusUnauthorizedError`	HTTP 401
`NexusBillingError`	HTTP 402 - tenant has overdue invoices
`NexusNotFoundError`	HTTP 404
`NexusQuarantinedError`	HTTP 429 quarantine body
`NexusRateLimitedError`	HTTP 429 (non-quarantine)

`client.evaluateAB(keys, userId, attributes?): Promise<Record<string, boolean>>`

Per-user AB evaluation (requires the AB Testing add-on on your project).

await client.evaluateAB(
  ['checkout-v2', 'dark-mode'],
  'user-abc123',
  { plan: 'pro', country: 'HU' },
);
// => { 'checkout-v2': true, 'dark-mode': false }

Throws	When
`NexusUnauthorizedError`	HTTP 401
`NexusBillingError`	HTTP 402 - tenant has overdue invoices
`NexusNotFoundError`	HTTP 404
`NexusAbAddonNotAvailableError`	HTTP 403 - the AB Testing add-on is not active on this project
`NexusQuarantinedError`	HTTP 429 quarantine body
`NexusRateLimitedError`	HTTP 429 (non-quarantine)

Secrets (secret key only)

`client.getSecret(key: string): string`

Returns the plaintext value of a text-type secret.

const password = client.getSecret('DB_PASSWORD');

Throws	When
`NexusPublicKeyError`	The client uses a public key
`NexusServiceKindMismatchError`	The service’s `kind` is `"frontend"`
`NexusSecretNotFoundError`	The key is not in the cache, or it is a file-type secret (use `getSecretFilePath`)

`client.getSecretFilePath(key: string): string | undefined`

Returns the filesystem path of a file-type secret (PEM cert, JSON service account key, etc.), or undefined if the key does not exist or is a text-type secret.

const certPath = client.getSecretFilePath('TLS_CERT');
// /tmp/nexus-secrets-Xf3k9a/nexus-9c1d4e77b2a0-5b8e0f31c7d2
// Per-client directory (0700); both filename components are hashes, so neither the
// secret's name nor its value appears on the filesystem.

The SDK writes the secret content to a temp file on every sync when the value changes. Old temp files for the same key are deleted automatically. client.close() removes all temp files.

Throws	When
`NexusPublicKeyError`	The client uses a public key
`NexusServiceKindMismatchError`	The service’s `kind` is `"frontend"`

Write API (secret key only)

The write API lets you create, update, and delete secrets programmatically. All three methods check the key type before making any network call - public keys throw NexusPublicKeyError immediately.

`client.setSecret(key: string, value: string): Promise<void>`

Creates or updates a secret (POST /v1/secrets, type: "text").

await client.setSecret('stripe.key', newKey);

Throws	When
`NexusPublicKeyError`	public key (no HTTP call)
`NexusUnauthorizedError`	HTTP 401
`NexusBillingError`	HTTP 402 - tenant has overdue invoices
`NexusQuarantinedError`	HTTP 429 quarantine body
`NexusRateLimitedError`	HTTP 429 (non-quarantine)
`NexusError`	any other non-2xx response

`client.deleteSecret(key: string): Promise<void>`

Deletes all versions of a secret (DELETE /v1/secrets/:key). Key is URL-encoded automatically.

await client.deleteSecret('old.api.key');

Throws	When
`NexusPublicKeyError`	public key (no HTTP call)
`NexusUnauthorizedError`	HTTP 401
`NexusBillingError`	HTTP 402 - tenant has overdue invoices
`NexusNotFoundError`	HTTP 404 - key doesn’t exist
`NexusQuarantinedError`	HTTP 429 quarantine body
`NexusRateLimitedError`	HTTP 429 (non-quarantine)
`NexusError`	any other non-2xx response

`client.deleteSecretVersion(key: string, version: number): Promise<void>`

Deletes a specific version of a secret (DELETE /v1/secrets/:key?version=N).

await client.deleteSecretVersion('db.password', 2);

Throws	When
`NexusPublicKeyError`	public key (no HTTP call)
`NexusUnauthorizedError`	HTTP 401
`NexusBillingError`	HTTP 402 - tenant has overdue invoices
`NexusNotFoundError`	HTTP 404 - key or version doesn’t exist
`NexusQuarantinedError`	HTTP 429 quarantine body
`NexusRateLimitedError`	HTTP 429 (non-quarantine)
`NexusError`	any other non-2xx response

Metadata

Property	Type	Description
`client.keyType`	`'sk' \| 'pk' \| ''`	The classified API key. `''` when WIF supplies the credential and there is no key to classify. Once a snapshot exists, the backend’s own classification is honoured - not merely the key’s prefix.
`client.kind`	`string`	The service kind reported by the backend: `"frontend"`, `"backend"`, or `''` if not yet known. Available after the first successful sync (or token exchange when WIF is enabled).
`client.syncedAt`	`Date \| null`	Timestamp of the last successful sync.
`client.streamStatus`	`'connected' \| 'fallback' \| 'disconnected'`	Current SSE state.
`client.streamConnected`	`boolean`	`true` while the SSE stream is connected and delivering events.
`client.billingOverdue`	`boolean`	`true` after the most recent sync attempt returned HTTP 402. Cleared automatically as soon as any sync succeeds.

Sync / lifecycle

`client.connectStream()` / `client.disconnectStream()`

The stream starts automatically after the initial sync. Call disconnectStream() to opt out (e.g. on a “go offline” signal); call connectStream() to restart.

`client.refresh(): Promise<void>`

Refreshes the cache now, bypassing the TTL. Errors are thrown rather than logged, since the caller asked for this sync. A sync already in flight is awaited instead of a second one being started.

Throws	When
`NexusQuarantinedError`	The service is quarantined - the SDK will not send a request the backend has told it to stop sending.

`client.close(): Promise<void>`

Stops the SSE connection, the polling timer, and removes all temp secret files. Always call on shutdown.

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

Error types

import {
  NexusError,                        // base class
  NexusConfigError,                  // invalid NexusConfig option
  NexusInitError,                    // initial sync failure (cause carries detail)
  NexusUnauthorizedError,            // HTTP 401
  NexusNotFoundError,                // HTTP 404
  NexusPublicKeyError,               // getSecret with public key
  NexusSecretNotFoundError,          // unknown secret key
  NexusBillingError,                 // HTTP 402 - tenant overdue
  NexusServiceKindMismatchError,     // getSecret on a frontend-kind service
  NexusWIFNotConfiguredError,        // no usable WIF provider matched
  NexusWIFTokenExchangeFailedError,  // token-exchange request failed
  NexusSessionExpiredError,          // WIF session expired and refresh failed
  NexusRateLimitedError,             // HTTP 429 on write endpoints (v0.5.0)
  NexusQuarantinedError,             // HTTP 429 quarantine body (v0.4.0)
  NexusAbAddonNotAvailableError,     // HTTP 403 on evaluateAB (v0.4.0)
  NexusResponseTooLargeError,        // response body exceeded the SDK's ceiling
  NexusTimeoutError,                 // connection or request exceeded its deadline
  NexusClientClosedError,            // a call after client.close()
} from '@westyx-nexus/sdk-nodejs';

See Error handling for full semantics and examples.

Overview

Backend SDKs

Browser SDKs

OpenFeature Providers

Node.js SDK - API Reference

Construction

`NexusClient.create(config: NexusConfig): Promise<NexusClient>`

Configs

`client.getConfig(key: string): unknown`

`client.getConfigRaw(key: string): string | undefined`

`client.getAllConfigs(): Record<string, unknown>`

Feature flags

`client.getFlag(key: string, defaultValue?: boolean): boolean`

`client.hasFlag(key: string): boolean`

`client.getAllFlags(): Record<string, boolean>`

`client.evaluateFlags(keys: string[]): Promise<Record<string, boolean>>`

`client.evaluateAB(keys, userId, attributes?): Promise<Record<string, boolean>>`

Secrets (secret key only)

`client.getSecret(key: string): string`

`client.getSecretFilePath(key: string): string | undefined`

Write API (secret key only)

`client.setSecret(key: string, value: string): Promise<void>`

`client.deleteSecret(key: string): Promise<void>`

`client.deleteSecretVersion(key: string, version: number): Promise<void>`

Metadata

Sync / lifecycle

`client.connectStream()` / `client.disconnectStream()`

`client.refresh(): Promise<void>`

`client.close(): Promise<void>`

Error types

​Construction

​NexusClient.create(config: NexusConfig): Promise<NexusClient>

​Configs

​client.getConfig(key: string): unknown

​client.getConfigRaw(key: string): string | undefined

​client.getAllConfigs(): Record<string, unknown>

​Feature flags

​client.getFlag(key: string, defaultValue?: boolean): boolean

​client.hasFlag(key: string): boolean

​client.getAllFlags(): Record<string, boolean>

​client.evaluateFlags(keys: string[]): Promise<Record<string, boolean>>

​client.evaluateAB(keys, userId, attributes?): Promise<Record<string, boolean>>

​Secrets (secret key only)

​client.getSecret(key: string): string

​client.getSecretFilePath(key: string): string | undefined

​Write API (secret key only)

​client.setSecret(key: string, value: string): Promise<void>

​client.deleteSecret(key: string): Promise<void>

​client.deleteSecretVersion(key: string, version: number): Promise<void>

​Metadata

​Sync / lifecycle

​client.connectStream() / client.disconnectStream()

​client.refresh(): Promise<void>

​client.close(): Promise<void>

​Error types

Construction

`NexusClient.create(config: NexusConfig): Promise<NexusClient>`

Configs

`client.getConfig(key: string): unknown`

`client.getConfigRaw(key: string): string | undefined`

`client.getAllConfigs(): Record<string, unknown>`

Feature flags

`client.getFlag(key: string, defaultValue?: boolean): boolean`

`client.hasFlag(key: string): boolean`

`client.getAllFlags(): Record<string, boolean>`

`client.evaluateFlags(keys: string[]): Promise<Record<string, boolean>>`

`client.evaluateAB(keys, userId, attributes?): Promise<Record<string, boolean>>`

Secrets (secret key only)

`client.getSecret(key: string): string`

`client.getSecretFilePath(key: string): string | undefined`

Write API (secret key only)

`client.setSecret(key: string, value: string): Promise<void>`

`client.deleteSecret(key: string): Promise<void>`

`client.deleteSecretVersion(key: string, version: number): Promise<void>`

Metadata

Sync / lifecycle

`client.connectStream()` / `client.disconnectStream()`

`client.refresh(): Promise<void>`

`client.close(): Promise<void>`

Error types