Skip to main content
The SDK opens a persistent fetch-based SSE connection to GET <baseUrl>/v1/stream. The API key is sent as the X-Nexus-API-Key request header - the same header used by all other endpoints. The ?key= query parameter is no longer used. After the initial sync completes, whenever the Nexus backend emits a change event (config.updated, flag.toggled, resync, …), the SDK triggers an immediate full re-sync - so the in-memory cache is updated within milliseconds of a change, instead of waiting for the next TTL tick.

Authentication

The Angular SDK sends the API key as the X-Nexus-API-Key header on the stream connection. Unlike EventSource, the fetch API supports custom request headers on streaming responses, so no query parameter workaround is needed.
Secret keys (wxs_…) are rejected at NexusClient.create() time. Only public keys (wxp_…) may be used with browser SDKs.

Angular zone integration

Stream events are processed outside Angular’s zone. The SDK automatically re-enters the zone (via NgZone.run(...)) before calling observer callbacks, so component bindings and signals update correctly. This is handled by provideNexus() and NexusModule.forRoot() - no extra configuration is needed.

Reconnect and error handling

After a transport failure the SDK schedules a reconnect with exponential backoff (1 s → 30 s capped). After 3 consecutive failures, the SDK falls back to TTL polling and emits FALLBACK_REASON_MAX_ERRORS. The SDK then automatically schedules an SSE reconnect using the sseReconnectCooldown schedule (default: 5 → 10 → 20 → 40 → 60 min). When the timer fires, the failure counter resets and connectStream() is called automatically. (v0.6.0)

429 Rate limiting and quarantine

If the server responds with HTTP 429, the SDK checks the response body:
  • {"error":"quarantined"} → fires onQuarantined(reason, expiresAt) and reconnects after the quarantine window.
  • Any other 429 → fires onFallback("rate-limited"). If Retry-After is present, reconnects after the indicated value (clamped to 5–300 s). If absent, falls back to TTL polling and schedules reconnect via the sseReconnectCooldown schedule. (v0.6.0)

Reactive flag signals (v0.6.1)

Use getFlagSignal() to get a Signal<boolean> that updates automatically whenever the cache refreshes after an SSE event or TTL poll:
The signal reads from an internal _snapshotVersion counter that the SDK bumps inside NgZone after every snapshot replacement. No manual subscribe(), effect(), or change-detection calls needed - Angular handles re-rendering automatically. The equivalent for config values will follow in a future release.

Disabling SSE

The SDK calls connectStream() automatically. To opt out at runtime:

What events trigger a sync

Lifecycle

Stream connection is automatic; teardown is also automatic when the Angular application is destroyed (the SDK listens for DestroyRef). Manual disconnectStream() is available but rarely needed in single-page apps.