[Advanced] Resilient reconnecting WebSocket signals client + live example

[Eras256]

Difficulty: Advanced (senior · 7/10). ~12–18h. WebSocket lifecycle, backoff/reconnection, typed events.

Context

The Nirium agent streams live signals over wss://nirium-agent.fly.dev/ws/signals?token=JWT. The SDK has a basic subscribe() but no resilient client that survives dropped connections — which is exactly what any real integration needs.

Goal

A robust reconnecting WebSocket signals client plus a small live example that renders the stream and its connection state.

Scope / Deliverables

1. Client: connect + auto-reconnect (exponential backoff with jitter, max-retries cap), heartbeat/ping, typed onSignal / onStatus / onError callbacks, graceful close(), and a token-refresh hook for JWT expiry.
2. Burst handling: basic backpressure / de-duplication so a flood of messages doesn't drop or double-fire.
3. Example: a minimal live feed (Node console or a tiny web page) showing incoming signals and the current connection state.
4. Tests: reconnection logic + event parsing against a mock WS server (force a disconnect and assert it recovers).
5. README with usage.

Acceptance criteria

• Survives a forced disconnect and reconnects automatically (a test proves it).
• No unhandled promise rejections; typed public surface; the example runs against the live testnet WS.

Pointers

• Builds on the SDK's subscribe() / WebSocket signal path; ws or the native WebSocket.

Reward

Eligibility is subject to GrantFox review after the campaign (Official Campaign | FWC26). Rewards are decided by GrantFox based on quality and available budget and are not guaranteed.