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

# Angular SDK - Configuration

> NexusConfig field reference and API key guidance for the Angular SDK.

`NexusConfig` is a plain TypeScript interface holding every value required to construct a `NexusClient`. Pass it to `provideNexus(...)` (standalone) or `NexusModule.forRoot(...)` (NgModule).

```ts theme={null}
provideNexus({
  baseUrl: 'https://<slug>.westyx.dev',  // required
  apiKey:  'wxp_...',                // required
  ttlMs:   60_000,                       // optional, default 60 000 ms
  logger:  myLogger,                     // optional
});
```

## Field reference

| Field                  | Type                  | Default                | Description                                                                                                                                                                                                                                                   |
| ---------------------- | --------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `baseUrl`              | `string`              | -                      | Full service URL, e.g. `https://<slug>.westyx.dev`. The slug is also used as the `Host` header on every request (Double-Gate requirement).                                                                                                                    |
| `apiKey`               | `string`              | -                      | Raw `wxp_...` key. Sent in the `X-Nexus-API-Key` header on both `/sync` and `/stream`. The SDK uses fetch-based SSE (not the browser `EventSource` API), so the key travels as a header - never as a `?key=...` query parameter. *(header-only since v0.4.1)* |
| `ttlMs`                | `number`              | `60_000`               | Local cache TTL in milliseconds. After this elapses, the next read triggers a one-shot background refresh while still serving the stale cache.                                                                                                                |
| `logger`               | `NexusLogger`         | `NOOP_LOGGER`          | Optional diagnostic logger. Defaults to a no-op (silent).                                                                                                                                                                                                     |
| `streamObserver`       | `NexusStreamObserver` | `NOOP_STREAM_OBSERVER` | Optional structured callback observer for SSE lifecycle events. See [Stream observer](stream-observer). *(v0.2.0)*                                                                                                                                            |
| `sseReconnectCooldown` | `number \| number[]`  | `undefined`            | Schedule for reconnecting SSE after falling back to TTL polling. Unit: **minutes**. `undefined` = default `[5, 10, 20, 40, 60]` min exponential. Single number = fixed interval. Array = custom schedule (stays at last value). *(v0.6.0)*                    |

## API key types

| Prefix    | Access                                                                           | Browser-safe?                  |
| --------- | -------------------------------------------------------------------------------- | ------------------------------ |
| `wxs_...` | Full - all configs, all secrets, all flags                                       | rejected at runtime by the SDK |
| `wxp_...` | Restricted - only `is_public: true` configs and flags; `secrets` field is absent | yes                            |

Browser SDKs **must** use a `wxp_...` key. The SDK enforces this in three places:

1. **`PublicApiKey` branded type** - when typed strictly, TypeScript prevents passing a plain `string` without `assertPublicKey()`
2. **Runtime guard** - throws `Error('Browser SDKs require a public key (wxp_...)')` before any network call
3. **Backend enforcement** - a request carrying an `wxs_...` key in the `X-Nexus-API-Key` header against a browser/public surface is rejected with `400 Bad Request`

```ts theme={null}
import { assertPublicKey, provideNexus } from '@westyx-nexus/sdk-angular';

const apiKey = 'wxp_...';
assertPublicKey(apiKey);  // narrows to PublicApiKey

provideNexus({ baseUrl: '...', apiKey });
```

## Where to keep the API key

Anywhere your existing build pipeline injects environment-specific config - typically Angular's `environments/environment.ts`:

```ts theme={null}
// environments/environment.prod.ts
export const environment = {
  production: true,
  nexusUrl:    'https://blue-ocean-a5rx7.westyx.dev',
  nexusApiKey: 'wxp_...',
};
```

```ts theme={null}
// app.config.ts
import { environment } from '../environments/environment';

provideNexus({
  baseUrl: environment.nexusUrl,
  apiKey:  environment.nexusApiKey,
});
```

<Note>
  `wxp_...` keys are intended to be **public** - embedding them in a built JavaScript bundle is fine. They cannot read secrets, and the Double-Gate check ensures they only work on the correct subdomain.
</Note>

## Choosing the TTL

The TTL is a tradeoff between staleness window and redundant network traffic. With SSE enabled (the default), **changes propagate in milliseconds regardless of the TTL** - the TTL only matters as a safety net when the stream falls back.

| Use case                                     | Suggested `ttlMs` |
| -------------------------------------------- | ----------------- |
| Frequently-changing flags, latency-sensitive | 30 000 (30 s)     |
| Standard configs with SSE                    | 60 000 (default)  |
| Boot-time only, rarely re-checked            | 600 000 (10 min)  |