feat(sdk): Add WebSocket subscription support for real-time event streaming

[Vincent6581]

Summary

Implements a WebSocket-based event subscription client (EventStream) for real-time updates, per issue #190.

The client opens a single WebSocket connection to an event relay and multiplexes any number of typed subscriptions over it, with reconnection, filtering and stale-detection handled transparently.

What's included

Acceptance criterion	Status
EventStream class with subscribe(eventType, callback)	✅ subscribe(eventType, callback, filter?) returns an unsubscribe fn
Events: Transfer, Trade, DividendClaim, KYCUpdate, CustodyAttestation	✅ STREAM_EVENT_TYPES
Auto-reconnect with exponential backoff	✅ configurable base/max delay, multiplier, jitter, attempt cap
Filtering by token_address, user_address	✅ per-subscription EventFilter (single value or list), applied client-side and sent to the relay
Heartbeat / ping for stale detection	✅ periodic ping + stale timer that forces a reconnect

Design notes

• Injectable transport — config.webSocketImpl accepts any browser-WebSocket-shaped constructor (the ws package, or a mock WS server in tests). Falls back to the global WebSocket when present.
• Lazy connect — the socket opens on the first subscribe() call; subscriptions are re-registered automatically on every reconnect.
• Lifecycle events — stream.on('open' | 'close' | 'error' | 'reconnecting' | 'stale', listener).
• Deterministic backoff jitter — jitter is derived from the attempt number (no Math.random) so reconnection timing is testable.
• eventMatchesFilter() and computeBackoffDelay() are exposed for direct unit testing of the filter and backoff logic.

Files changed

• sdk/src/eventStream.ts (new) — EventStream implementation
• sdk/src/types.ts — StreamEvent, EventFilter, EventStreamConfig, lifecycle + WebSocket structural types
• sdk/src/index.ts — export EventStream and related types

Usage

import { EventStream } from 'stellar-rwa-sdk';

const stream = new EventStream({ url: 'wss://relay.example/events' });

const off = stream.subscribe(
  'Transfer',
  (e) => console.log('transfer', e.data),
  { tokenAddress: 'C...ABC', userAddress: ['G...1', 'G...2'] }
);

stream.on('reconnecting', ({ attempt, delayMs }) =>
  console.warn(`reconnecting (#${attempt}) in ${delayMs}ms`)
);

// later
off();
stream.close();

Closes #190

[drips-wave]

@Vincent6581 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits