@studyportals/ws-client 0.1.1-beta.0

package/README.md

@@ -0,0 +1,180 @@
+# @studyportals/ws-client
+
+Typed WebSocket client with automatic reconnect, exponential backoff, heartbeat, and a mitt-powered event bus.
+
+Designed to replace and generalise the inline WebSocket logic previously embedded in `CampaignManagementAPIClient`.
+
+---
+
+## Installation
+
+```bash
+npm install @studyportals/ws-client
+```
+
+---
+
+## Usage
+
+### 1. Initialise with `RealWebSocketTransport`
+
+```ts
+import {
+  eventBus,
+  WebSocketManager,
+  RealWebSocketTransport,
+} from '@studyportals/ws-client';
+
+const transport = new RealWebSocketTransport();
+
+const manager = WebSocketManager.getInstance(eventBus, {
+  url: 'wss://api.example.com/ws',
+  transport,
+  // Optional overrides (shown with defaults):
+  maxReconnectAttempts: 10,
+  baseReconnectDelayMs: 500,
+  maxReconnectDelayMs: 30_000,
+  heartbeatIntervalMs: 30_000,
+  heartbeatMessage: { type: 'ping' },
+});
+
+eventBus.on('ws:connected', () => {
+  console.log('Connected. connectionId:', manager.getConnectionId());
+});
+
+eventBus.on('ws:max-retries-exceeded', () => {
+  console.error('WebSocket gave up reconnecting.');
+});
+```
+
+### 2. Subscribe to a domain event
+
+The server must push JSON frames shaped as `{ "type": "<event-key>", "payload": { ... } }`.
+
+```ts
+import { eventBus } from '@studyportals/ws-client';
+import type { CampaignSavingPayload } from '@studyportals/ws-client';
+
+eventBus.on('campaign:saving', (payload: CampaignSavingPayload) => {
+  if (payload.status === 'success') {
+    console.log('Campaign saved successfully.');
+  } else if (payload.status === 'failed') {
+    console.error('Save failed:', payload.error);
+  }
+});
+```
+
+#### Adding custom domain events
+
+Extend `WsEventMap` via TypeScript module augmentation:
+
+```ts
+// my-app/ws-events.d.ts
+import '@studyportals/ws-client';
+
+declare module '@studyportals/ws-client' {
+  interface WsEventMap {
+    'invoice:generated': { invoiceId: string; amount: number };
+  }
+}
+```
+
+Then subscribe with full type safety:
+
+```ts
+eventBus.on('invoice:generated', ({ invoiceId, amount }) => {
+  // invoiceId: string, amount: number  ✓
+});
+```
+
+### 3. Mock transport in unit tests and Cypress
+
+```ts
+import {
+  eventBus,
+  WebSocketManager,
+  MockWebSocketTransport,
+} from '@studyportals/ws-client';
+import type { CampaignSavingPayload } from '@studyportals/ws-client';
+
+// --- Setup (beforeEach) ---
+const transport = new MockWebSocketTransport();
+
+WebSocketManager.reset(); // clear singleton between tests
+const manager = WebSocketManager.getInstance(eventBus, {
+  url: 'wss://irrelevant-in-tests',
+  transport,
+});
+
+// MockWebSocketTransport.connect() fires onopen on the next tick.
+// Await a tick before asserting connected state:
+await new Promise((resolve) => setTimeout(resolve, 0));
+
+// --- Simulate a server message ---
+const payload: CampaignSavingPayload = { status: 'success' };
+transport.simulateMessage(JSON.stringify({ type: 'campaign:saving', payload }));
+
+// --- Simulate a server-initiated disconnect ---
+transport.simulateClose(1001);
+
+// --- Simulate the connection identity handshake ---
+transport.simulateMessage(
+  JSON.stringify({ type: 'ws:identified', payload: { connectionId: 'abc-123' } })
+);
+console.log(manager.getConnectionId()); // 'abc-123'
+
+// --- Teardown (afterEach) ---
+manager.disconnect();
+WebSocketManager.reset();
+eventBus.all.clear();
+```
+
+---
+
+## Server message format
+
+All server-pushed frames must be valid JSON with this shape:
+
+```json
+{ "type": "campaign:saving", "payload": { "status": "success" } }
+```
+
+Frames that are not valid JSON or lack a string `type` field are emitted as `ws:unparseable` with the raw string as the payload.
+
+The `ws:identified` event is a reserved internal type. When the server sends it, the manager caches the `connectionId` internally (accessible via `manager.getConnectionId()`) and also emits it on the bus.
+
+---
+
+## API
+
+### `WebSocketManager`
+
+| Member | Description |
+|---|---|
+| `getInstance(bus, config)` | Returns (or creates) the singleton. |
+| `reset()` | Destroys the singleton. Use between tests. |
+| `getConnectionId()` | Returns the last received `connectionId`, or `undefined`. |
+| `disconnect()` | Graceful close; suppresses auto-reconnect. |
+
+### `WebSocketManagerConfig`
+
+| Field | Type | Default |
+|---|---|---|
+| `url` | `string` | — |
+| `transport` | `IWebSocketTransport` | — |
+| `maxReconnectAttempts` | `number` | `10` |
+| `baseReconnectDelayMs` | `number` | `500` |
+| `maxReconnectDelayMs` | `number` | `30000` |
+| `heartbeatIntervalMs` | `number` | `30000` |
+| `heartbeatMessage` | `Record<string, unknown>` | `{ type: "ping" }` |
+
+### Internal bus events
+
+| Event | Payload |
+|---|---|
+| `ws:connected` | `undefined` |
+| `ws:disconnected` | `CloseEvent` |
+| `ws:error` | `Event` |
+| `ws:max-retries-exceeded` | `undefined` |
+| `ws:unparseable` | `string` (raw frame) |
+| `ws:identified` | `{ connectionId: string }` |

package/dist/event-bus.d.ts

@@ -0,0 +1,6 @@
+import mitt from 'mitt';
+import type { WsEventMap } from './types';
+type MittMap = WsEventMap & Record<string | symbol, unknown>;
+export type EventBus = ReturnType<typeof mitt<MittMap>>;
+export declare const eventBus: EventBus;
+export {};

package/dist/event-bus.js

@@ -0,0 +1,2 @@
+import mitt from 'mitt';
+export const eventBus = mitt();

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { eventBus } from './event-bus';
+export type { EventBus } from './event-bus';
+export { WebSocketManager } from './websocket-manager';
+export type { WsEventMap, WsIdentifiedPayload, CampaignSavingPayload, WebSocketManagerConfig, IncomingMessage, } from './types';
+export { wsIdentifiedPayloadSchema, campaignSavingPayloadSchema, incomingMessageSchema, } from './types';
+export type { IWebSocketTransport } from './transport.interface';
+export { RealWebSocketTransport } from './transports/real.transport';
+export { MockWebSocketTransport } from './transports/mock.transport';

package/dist/index.js

@@ -0,0 +1,9 @@
+// Event bus
+export { eventBus } from './event-bus';
+// Manager
+export { WebSocketManager } from './websocket-manager';
+// Zod validators (useful for consumers and tests)
+export { wsIdentifiedPayloadSchema, campaignSavingPayloadSchema, incomingMessageSchema, } from './types';
+// Transport implementations
+export { RealWebSocketTransport } from './transports/real.transport';
+export { MockWebSocketTransport } from './transports/mock.transport';

package/dist/transport.interface.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Abstraction over a WebSocket connection.
+ *
+ * The manager wires up the callbacks and calls connect() / send() / close().
+ * Implementations handle the actual I/O (or simulation in tests).
+ */
+export interface IWebSocketTransport {
+    onopen: (() => void) | null;
+    onmessage: ((data: string) => void) | null;
+    onclose: ((event: CloseEvent) => void) | null;
+    onerror: ((event: Event) => void) | null;
+    /** Open the connection to the given URL. */
+    connect(url: string): void;
+    /** Send a raw string frame. */
+    send(data: string): void;
+    /** Close the connection with an optional status code and reason. */
+    close(code?: number, reason?: string): void;
+}

package/dist/transport.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/transports/mock.transport.d.ts

@@ -0,0 +1,28 @@
+import type { IWebSocketTransport } from '../transport.interface';
+/**
+ * In-memory WebSocket transport for use in unit tests and Cypress specs.
+ *
+ * Wire it up via WebSocketManagerConfig.transport, then drive the connection
+ * state with simulateMessage() and simulateClose().
+ */
+export declare class MockWebSocketTransport implements IWebSocketTransport {
+    onopen: (() => void) | null;
+    onmessage: ((data: string) => void) | null;
+    onclose: ((event: CloseEvent) => void) | null;
+    onerror: ((event: Event) => void) | null;
+    private connected;
+    connect(_url: string): void;
+    /** No-op by design. Spy on this method to assert outgoing frames in tests. */
+    send(_data: string): void;
+    close(code?: number, _reason?: string): void;
+    /**
+     * Deliver a raw message string directly to the manager's onmessage handler.
+     * Call this from tests/Cypress to simulate server-pushed frames.
+     */
+    simulateMessage(data: string): void;
+    /**
+     * Fire a CloseEvent on the manager's onclose handler.
+     * Call this from tests/Cypress to simulate a server-initiated disconnect.
+     */
+    simulateClose(code?: number): void;
+}

package/dist/transports/mock.transport.js

@@ -0,0 +1,47 @@
+/**
+ * In-memory WebSocket transport for use in unit tests and Cypress specs.
+ *
+ * Wire it up via WebSocketManagerConfig.transport, then drive the connection
+ * state with simulateMessage() and simulateClose().
+ */
+export class MockWebSocketTransport {
+    constructor() {
+        this.onopen = null;
+        this.onmessage = null;
+        this.onclose = null;
+        this.onerror = null;
+        this.connected = false;
+    }
+    connect(_url) {
+        this.connected = true;
+        // Simulate async open so callers can register handlers before the event fires
+        setTimeout(() => {
+            this.onopen?.();
+        }, 0);
+    }
+    /** No-op by design. Spy on this method to assert outgoing frames in tests. */
+    send(_data) {
+        // intentionally empty
+    }
+    close(code = 1000, _reason) {
+        if (!this.connected)
+            return;
+        this.simulateClose(code);
+    }
+    /**
+     * Deliver a raw message string directly to the manager's onmessage handler.
+     * Call this from tests/Cypress to simulate server-pushed frames.
+     */
+    simulateMessage(data) {
+        this.onmessage?.(data);
+    }
+    /**
+     * Fire a CloseEvent on the manager's onclose handler.
+     * Call this from tests/Cypress to simulate a server-initiated disconnect.
+     */
+    simulateClose(code = 1000) {
+        this.connected = false;
+        const event = new CloseEvent('close', { code, wasClean: code === 1000 });
+        this.onclose?.(event);
+    }
+}

package/dist/transports/real.transport.d.ts

@@ -0,0 +1,11 @@
+import type { IWebSocketTransport } from '../transport.interface';
+export declare class RealWebSocketTransport implements IWebSocketTransport {
+    private socket;
+    onopen: (() => void) | null;
+    onmessage: ((data: string) => void) | null;
+    onclose: ((event: CloseEvent) => void) | null;
+    onerror: ((event: Event) => void) | null;
+    connect(url: string): void;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+}

package/dist/transports/real.transport.js

@@ -0,0 +1,34 @@
+export class RealWebSocketTransport {
+    constructor() {
+        this.socket = null;
+        this.onopen = null;
+        this.onmessage = null;
+        this.onclose = null;
+        this.onerror = null;
+    }
+    connect(url) {
+        this.socket = new WebSocket(url);
+        this.socket.addEventListener('open', () => {
+            this.onopen?.();
+        });
+        this.socket.addEventListener('message', (event) => {
+            if (typeof event.data === 'string') {
+                this.onmessage?.(event.data);
+            }
+        });
+        this.socket.addEventListener('close', (event) => {
+            this.onclose?.(event);
+        });
+        this.socket.addEventListener('error', (event) => {
+            this.onerror?.(event);
+        });
+    }
+    send(data) {
+        if (this.socket?.readyState === WebSocket.OPEN) {
+            this.socket.send(data);
+        }
+    }
+    close(code, reason) {
+        this.socket?.close(code, reason);
+    }
+}

package/dist/types/campaign-saving.d.ts

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+export declare const campaignSavingPayloadSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    status: z.ZodLiteral<"start">;
+}, z.core.$strip>, z.ZodObject<{
+    status: z.ZodLiteral<"success">;
+}, z.core.$strip>, z.ZodObject<{
+    status: z.ZodLiteral<"failed">;
+    error: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>], "status">;
+export type CampaignSavingPayload = z.infer<typeof campaignSavingPayloadSchema>;

package/dist/types/campaign-saving.js

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+const campaignSavingStartSchema = z.object({
+    status: z.literal('start'),
+});
+const campaignSavingSuccessSchema = z.object({
+    status: z.literal('success'),
+});
+const campaignSavingFailedSchema = z.object({
+    status: z.literal('failed'),
+    error: z.record(z.string(), z.unknown()),
+});
+export const campaignSavingPayloadSchema = z.discriminatedUnion('status', [
+    campaignSavingStartSchema,
+    campaignSavingSuccessSchema,
+    campaignSavingFailedSchema,
+]);

package/dist/types/index.d.ts

@@ -0,0 +1,8 @@
+export type { WsEventMap } from './ws-event-map';
+export type { WsIdentifiedPayload } from './ws-identified';
+export { wsIdentifiedPayloadSchema } from './ws-identified';
+export type { CampaignSavingPayload } from './campaign-saving';
+export { campaignSavingPayloadSchema } from './campaign-saving';
+export type { WebSocketManagerConfig } from './ws-manager-config';
+export type { IncomingMessage } from './ws-message';
+export { incomingMessageSchema } from './ws-message';

package/dist/types/index.js

@@ -0,0 +1,3 @@
+export { wsIdentifiedPayloadSchema } from './ws-identified';
+export { campaignSavingPayloadSchema } from './campaign-saving';
+export { incomingMessageSchema } from './ws-message';

package/dist/types/ws-event-map.d.ts

@@ -0,0 +1,12 @@
+import type { WsIdentifiedPayload } from './ws-identified';
+import type { CampaignSavingPayload } from './campaign-saving';
+export interface WsEventMap {
+    'ws:connected': undefined;
+    'ws:disconnected': CloseEvent;
+    'ws:error': Event;
+    'ws:max-retries-exceeded': undefined;
+    'ws:unparseable': string;
+    /** Emitted when the server sends a message with type "ws:identified". */
+    'ws:identified': WsIdentifiedPayload;
+    'campaign:saving': CampaignSavingPayload;
+}

package/dist/types/ws-event-map.js

@@ -0,0 +1 @@
+export {};

package/dist/types/ws-identified.d.ts

@@ -0,0 +1,5 @@
+import { z } from 'zod';
+export declare const wsIdentifiedPayloadSchema: z.ZodObject<{
+    connectionId: z.ZodString;
+}, z.core.$strip>;
+export type WsIdentifiedPayload = z.infer<typeof wsIdentifiedPayloadSchema>;

package/dist/types/ws-identified.js

@@ -0,0 +1,4 @@
+import { z } from 'zod';
+export const wsIdentifiedPayloadSchema = z.object({
+    connectionId: z.string(),
+});

package/dist/types/ws-manager-config.d.ts

@@ -0,0 +1,18 @@
+import type { IWebSocketTransport } from '../transport.interface';
+export type WebSocketManagerConfig = {
+    /** WebSocket endpoint URL (e.g. "wss://api.example.com/ws"). */
+    url: string;
+    /** Transport implementation. Use RealWebSocketTransport in production,
+     *  MockWebSocketTransport in tests. */
+    transport: IWebSocketTransport;
+    /** Maximum number of reconnect attempts before giving up. Default: 10. */
+    maxReconnectAttempts?: number;
+    /** Base delay (ms) for exponential backoff. Default: 500. */
+    baseReconnectDelayMs?: number;
+    /** Upper cap (ms) for reconnect delay. Default: 30 000. */
+    maxReconnectDelayMs?: number;
+    /** Interval (ms) between heartbeat messages while connected. Default: 30 000. */
+    heartbeatIntervalMs?: number;
+    /** Payload sent as the heartbeat message. Default: `{ "type": "ping" }`. */
+    heartbeatMessage?: Record<string, unknown>;
+};

package/dist/types/ws-manager-config.js

@@ -0,0 +1 @@
+export {};

package/dist/types/ws-message.d.ts

@@ -0,0 +1,6 @@
+import { z } from 'zod';
+export declare const incomingMessageSchema: z.ZodObject<{
+    type: z.ZodString;
+    payload: z.ZodUnknown;
+}, z.core.$strip>;
+export type IncomingMessage = z.infer<typeof incomingMessageSchema>;

package/dist/types/ws-message.js

@@ -0,0 +1,5 @@
+import { z } from 'zod';
+export const incomingMessageSchema = z.object({
+    type: z.string(),
+    payload: z.unknown(),
+});

package/dist/types.d.ts

@@ -0,0 +1,46 @@
+import type { IWebSocketTransport } from './transport.interface';
+export type WsIdentifiedPayload = {
+    connectionId: string;
+};
+export type CampaignSavingPayload = {
+    status: 'success' | 'start' | 'failed';
+    error?: Record<string, unknown>;
+};
+export type UserUpdatedPayload = {
+    userId: string;
+    [key: string]: unknown;
+};
+export type NotificationReceivedPayload = {
+    id: string;
+    message: string;
+    [key: string]: unknown;
+};
+export interface WsEventMap {
+    'ws:connected': undefined;
+    'ws:disconnected': CloseEvent;
+    'ws:error': Event;
+    'ws:max-retries-exceeded': undefined;
+    'ws:unparseable': string;
+    /** Emitted when the server sends a message with type "ws:identified". */
+    'ws:identified': WsIdentifiedPayload;
+    'campaign:saving': CampaignSavingPayload;
+    'user:updated': UserUpdatedPayload;
+    'notification:received': NotificationReceivedPayload;
+}
+export interface WebSocketManagerConfig {
+    /** WebSocket endpoint URL (e.g. "wss://api.example.com/ws"). */
+    url: string;
+    /** Transport implementation. Use RealWebSocketTransport in production,
+     *  MockWebSocketTransport in tests. */
+    transport: IWebSocketTransport;
+    /** Maximum number of reconnect attempts before giving up. Default: 10. */
+    maxReconnectAttempts?: number;
+    /** Base delay (ms) for exponential backoff. Default: 500. */
+    baseReconnectDelayMs?: number;
+    /** Upper cap (ms) for reconnect delay. Default: 30 000. */
+    maxReconnectDelayMs?: number;
+    /** Interval (ms) between heartbeat messages while connected. Default: 30 000. */
+    heartbeatIntervalMs?: number;
+    /** Payload sent as the heartbeat message. Default: `{ "type": "ping" }`. */
+    heartbeatMessage?: Record<string, unknown>;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/websocket-manager.d.ts

@@ -0,0 +1,34 @@
+import type { EventBus } from './event-bus';
+import type { WebSocketManagerConfig } from './types';
+export type { WebSocketManagerConfig } from './types';
+export declare class WebSocketManager {
+    private static instance;
+    private readonly bus;
+    private readonly config;
+    private reconnectAttempts;
+    private intentionalClose;
+    private heartbeatTimer;
+    private reconnectTimer;
+    private connectionId;
+    private constructor();
+    /**
+     * Returns the singleton instance, creating it on first call.
+     * Subsequent calls ignore `bus` and `config` — pass them only on first call.
+     */
+    static getInstance(bus: EventBus, config: WebSocketManagerConfig): WebSocketManager;
+    /**
+     * Destroy the singleton.
+     * Call before re-initialising in tests or when switching environments.
+     */
+    static reset(): void;
+    /** Returns the connectionId received from the last "ws:identified" message. */
+    getConnectionId(): string | undefined;
+    /** Gracefully close the connection without triggering automatic reconnect. */
+    disconnect(): void;
+    private connect;
+    private handleMessage;
+    private scheduleReconnect;
+    private clearReconnectTimer;
+    private startHeartbeat;
+    private clearHeartbeat;
+}

package/dist/websocket-manager.js

@@ -0,0 +1,131 @@
+import { incomingMessageSchema, wsIdentifiedPayloadSchema } from './types';
+const DEFAULT_MAX_RECONNECT_ATTEMPTS = 10;
+const DEFAULT_BASE_RECONNECT_DELAY_MS = 500;
+const DEFAULT_MAX_RECONNECT_DELAY_MS = 30000;
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 30000;
+const DEFAULT_HEARTBEAT_MESSAGE = { type: 'ping' };
+export class WebSocketManager {
+    constructor(bus, config) {
+        this.reconnectAttempts = 0;
+        this.intentionalClose = false;
+        this.bus = bus;
+        this.config = {
+            url: config.url,
+            transport: config.transport,
+            maxReconnectAttempts: config.maxReconnectAttempts ?? DEFAULT_MAX_RECONNECT_ATTEMPTS,
+            baseReconnectDelayMs: config.baseReconnectDelayMs ?? DEFAULT_BASE_RECONNECT_DELAY_MS,
+            maxReconnectDelayMs: config.maxReconnectDelayMs ?? DEFAULT_MAX_RECONNECT_DELAY_MS,
+            heartbeatIntervalMs: config.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS,
+            heartbeatMessage: config.heartbeatMessage ?? DEFAULT_HEARTBEAT_MESSAGE,
+        };
+        this.connect();
+    }
+    /**
+     * Returns the singleton instance, creating it on first call.
+     * Subsequent calls ignore `bus` and `config` — pass them only on first call.
+     */
+    static getInstance(bus, config) {
+        if (!WebSocketManager.instance) {
+            WebSocketManager.instance = new WebSocketManager(bus, config);
+        }
+        return WebSocketManager.instance;
+    }
+    /**
+     * Destroy the singleton.
+     * Call before re-initialising in tests or when switching environments.
+     */
+    static reset() {
+        WebSocketManager.instance = undefined;
+    }
+    /** Returns the connectionId received from the last "ws:identified" message. */
+    getConnectionId() {
+        return this.connectionId;
+    }
+    /** Gracefully close the connection without triggering automatic reconnect. */
+    disconnect() {
+        this.intentionalClose = true;
+        this.clearHeartbeat();
+        this.clearReconnectTimer();
+        this.config.transport.close(1000, 'client disconnect');
+    }
+    connect() {
+        const { transport, url } = this.config;
+        transport.onopen = () => {
+            this.reconnectAttempts = 0;
+            this.intentionalClose = false;
+            this.startHeartbeat();
+            this.bus.emit('ws:connected', undefined);
+        };
+        transport.onmessage = (data) => {
+            this.handleMessage(data);
+        };
+        transport.onclose = (event) => {
+            this.clearHeartbeat();
+            this.connectionId = undefined;
+            this.bus.emit('ws:disconnected', event);
+            if (!this.intentionalClose) {
+                this.scheduleReconnect();
+            }
+        };
+        transport.onerror = (event) => {
+            this.bus.emit('ws:error', event);
+        };
+        transport.connect(url);
+    }
+    handleMessage(raw) {
+        let parsedJson;
+        try {
+            parsedJson = JSON.parse(raw);
+        }
+        catch {
+            this.bus.emit('ws:unparseable', raw);
+            return;
+        }
+        const msgResult = incomingMessageSchema.safeParse(parsedJson);
+        if (!msgResult.success) {
+            this.bus.emit('ws:unparseable', raw);
+            return;
+        }
+        const msg = msgResult.data;
+        if (msg.type === 'ws:identified') {
+            const idResult = wsIdentifiedPayloadSchema.safeParse(msg.payload);
+            if (idResult.success) {
+                this.connectionId = idResult.data.connectionId;
+            }
+        }
+        this.bus.emit(msg.type, msg.payload);
+    }
+    scheduleReconnect() {
+        if (this.reconnectAttempts >= this.config.maxReconnectAttempts) {
+            this.bus.emit('ws:max-retries-exceeded', undefined);
+            return;
+        }
+        const { baseReconnectDelayMs, maxReconnectDelayMs } = this.config;
+        const exponential = baseReconnectDelayMs * Math.pow(2, this.reconnectAttempts);
+        const capped = Math.min(exponential, maxReconnectDelayMs);
+        // Add random jitter up to one base interval to avoid thundering herd
+        const delay = capped + Math.random() * baseReconnectDelayMs;
+        this.reconnectAttempts++;
+        this.reconnectTimer = setTimeout(() => {
+            this.connect();
+        }, delay);
+    }
+    clearReconnectTimer() {
+        if (this.reconnectTimer !== undefined) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = undefined;
+        }
+    }
+    startHeartbeat() {
+        this.clearHeartbeat();
+        this.heartbeatTimer = setInterval(() => {
+            this.config.transport.send(JSON.stringify(this.config.heartbeatMessage));
+        }, this.config.heartbeatIntervalMs);
+    }
+    clearHeartbeat() {
+        if (this.heartbeatTimer !== undefined) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = undefined;
+        }
+    }
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@studyportals/ws-client",
+  "version": "0.1.1-beta.0",
+  "description": "WebSocket client with reconnect, heartbeat, and typed event bus",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "type-check": "tsc --noEmit",
+	"release": "npm publish --access public",
+    "release:major": "npm run build && npm version major && npm run release",
+    "release:minor": "npm run build && npm version minor && npm run release",
+    "release:patch": "npm run build && npm version patch && npm run release",
+    "release:beta": "npm run build && npm version prerelease --preid beta && npm run release -- --tag beta"
+  },
+  "dependencies": {
+    "mitt": "^3.0.1",
+    "zod": "^4.3.6"
+  },
+  "peerDependencies": {
+    "typescript": ">=5.0"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.2"
+  }
+}