> ## 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 - API Reference

> Every public method, getter, and remote evaluator in the Node.js SDK.

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.

```ts theme={null}
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): string | undefined`

Returns the resolved config value, or `undefined` if the key is absent.

```ts theme={null}
const dbHost = client.getConfig('DB_HOST');
```

public-key clients only see configs where `is_public: true`.

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

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.

```ts theme={null}
client.getFlag('checkout.v2');           // false if missing
client.getFlag('checkout.v2', true);     // true if missing
```

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

```ts theme={null}
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.

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

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

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

Throws `NexusAbAddonNotAvailableError` (HTTP 403) if the AB Testing add-on is not active on this project.

## Secrets (secret key only)

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

Returns the plaintext value of a text-type secret.

```ts theme={null}
const password = client.getSecret('DB_PASSWORD');
```

| Throws                     | When                                                                               |
| -------------------------- | ---------------------------------------------------------------------------------- |
| `NexusPublicKeyError`      | The client uses a public key                                                       |
| `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.

```ts theme={null}
const certPath = client.getSecretFilePath('TLS_CERT');
// /tmp/nexus-secrets/nexus-TLS_CERT-abc123def456
```

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 |

## 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"`).

```ts theme={null}
await client.setSecret('stripe.key', newKey);
```

| Throws                   | When                      |
| ------------------------ | ------------------------- |
| `NexusPublicKeyError`    | public key (no HTTP call) |
| `NexusUnauthorizedError` | HTTP 401                  |
| `NexusRateLimitedError`  | HTTP 429                  |

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

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

```ts theme={null}
await client.deleteSecret('old.api.key');
```

| Throws                  | When                         |
| ----------------------- | ---------------------------- |
| `NexusPublicKeyError`   | public key (no HTTP call)    |
| `NexusNotFoundError`    | HTTP 404 - key doesn't exist |
| `NexusRateLimitedError` | HTTP 429                     |

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

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

```ts theme={null}
await client.deleteSecretVersion('db.password', 2);
```

| Throws                  | When                                    |
| ----------------------- | --------------------------------------- |
| `NexusPublicKeyError`   | public key (no HTTP call)               |
| `NexusNotFoundError`    | HTTP 404 - key or version doesn't exist |
| `NexusRateLimitedError` | HTTP 429                                |

## Metadata

| Property              | Type                                          | Description                            |
| --------------------- | --------------------------------------------- | -------------------------------------- |
| `client.keyType`      | `'sk' \| 'pk'`                                | Detected from the configured `apiKey`. |
| `client.syncedAt`     | `Date \| null`                                | Timestamp of the last successful sync. |
| `client.streamStatus` | `'connected' \| 'fallback' \| 'disconnected'` | Current SSE state.                     |

## 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.close(): Promise<void>`

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

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

## Error types

```ts theme={null}
import {
  NexusError,                  // base class
  NexusInitError,              // initial sync failure (cause carries detail)
  NexusUnauthorizedError,      // HTTP 401
  NexusNotFoundError,          // HTTP 404
  NexusPublicKeyError,         // getSecret with public key
  NexusSecretNotFoundError,    // unknown secret key
  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)
} from '@westyx-nexus/sdk-nodejs';
```

See [Error handling](error-handling) for full semantics and examples.