feat(sdk): resilient reconnecting WebSocket signals client (#45)

[M0nsxx]

Resilient Reconnecting WebSocket Signals Client & Example (#45)

Overview

This PR implements ResilientSignalClient in @nirium/sdk (exported as ResilientSignalClient) to handle WebSocket signal stream connectivity with automatic exponential backoff, token refresh hooks, heartbeat ping/pong keepalives, and burst signal deduplication. It also adds a runnable example project in examples/ws-signals-resilient/.

Summary of Changes

1. SDK Class (packages/sdk/src/resilient-ws.ts & packages/sdk/src/index.ts):

   • ResilientSignalClient: Auto-reconnecting WebSocket client with exponential backoff and random jitter (initialBackoffMs defaulting to 1000ms up to maxBackoffMs defaulting to 30000ms).
   • Token Refresh Hook (onTokenRefresh): Executes before establishing reconnect attempts to automatically update JWT auth headers/queries.
   • Heartbeat Management: Sends periodic { type: 'ping' } frames (or native WS ping frames) every pingIntervalMs and detects lost connectivity if no pong arrives within twice the ping interval.
   • Deduplication Buffer: Suppresses identical signal events received within dedupWindowMs (60s default) to handle network bursts and redundant transmissions cleanly.
   • Lifecycle Callbacks: onStatus, onSignal, and onError event handling with graceful teardown (close()).

2. Automated Unit Tests (packages/sdk/test/ws-resilient.test.ts):

   • Tested duplicate signal burst suppression over real local WebSocket server instances.
   • Tested automatic reconnection and execution of token refresh hooks upon forced server socket termination.

3. Runnable Example Project (examples/ws-signals-resilient/):

   • Live CLI client (index.ts) formatting signals and rendering real-time connection status transitions (connecting, connected, reconnecting, disconnected).
   • Includes standalone smoke test suite (test/smoke.test.js) and documentation (README.md).

Verification

• Unit tests run and pass cleanly via node --experimental-strip-types --test test/ws-resilient.test.ts.
• Smoke tests for example run and pass via npm test in examples/ws-signals-resilient.