jmri-client 2.2.0 → 3.0.0

package/README.md

@@ -1,76 +1,138 @@
-jmri-client
+# jmri-client
+
 [![Build](https://github.com/yamanote1138/jmri-client/actions/workflows/build-and-test.yml/badge.svg?branch=main)](https://github.com/yamanote1138/jmri-client/actions/workflows/build-and-test.yml)
 ![License](https://img.shields.io/npm/l/jmri-client)
 ![NPM Version](https://img.shields.io/npm/v/jmri-client)
-=========
 
-node client to connect to a [JMRI](http://jmri.sourceforge.net/) xmlio webservice
-this allows basic control of a model railroad layout via DCC
+WebSocket client for [JMRI](http://jmri.sourceforge.net/) with real-time updates and full throttle control.
 
 [![NPM](https://nodei.co/npm/jmri-client.png?compact=true)](https://nodei.co/npm/jmri-client/)
 
-## Usage
+## Features
 
-### setup and instantiate client
-```javascript
-"use strict";
+- ✅ **WebSocket-based** - Real-time bidirectional communication
+- ✅ **Event-driven** - Subscribe to power changes, throttle updates, and more
+- ✅ **Full Throttle Control** - Speed (0.0-1.0), direction, and functions (F0-F28)
+- ✅ **Mock Mode** - Test and demo without JMRI hardware
+- ✅ **Auto-reconnection** - Exponential backoff with jitter
+- ✅ **Heartbeat monitoring** - Automatic ping/pong keepalive
+- ✅ **TypeScript** - Full type definitions included
+- ✅ **Dual module support** - ESM and CommonJS
 
-import { JmriClient } from "jmri-client";
+## Installation
 
-const client = new JmriClient('http', 'jmri.local', 12080);
+```bash
+npm install jmri-client
 ```
 
-### getPower
-get status of layout power (on or off)
-```javascript
-await client.getPower().then((res) => {
-  console.log(res);
+**Requirements:** Node.js 18+
+
+## Quick Start
+
+```typescript
+import { JmriClient, PowerState } from 'jmri-client';
+
+// Create client
+const client = new JmriClient({
+  host: 'jmri.local',
+  port: 12080
 });
-```
 
-### setPower
-turn layout power on/off
-```javascript
-await client.setPower(true).then((res) => {
-  console.log(res);
+// Listen for events
+client.on('connected', () => console.log('Connected!'));
+client.on('power:changed', (state) => {
+  console.log('Power:', state === PowerState.ON ? 'ON' : 'OFF');
 });
+
+// Control power
+await client.powerOn();
+
+// Acquire and control a throttle
+const throttleId = await client.acquireThrottle({ address: 3 });
+await client.setThrottleSpeed(throttleId, 0.5);  // 50% speed
+await client.setThrottleDirection(throttleId, true);  // Forward
+await client.setThrottleFunction(throttleId, 'F0', true);  // Headlight on
+
+// Clean up
+await client.releaseThrottle(throttleId);
+await client.disconnect();
 ```
 
-## future functionality
+## Documentation
+
+- **[API Reference](docs/API.md)** - Complete API documentation
+- **[Examples](docs/EXAMPLES.md)** - Common usage patterns
+- **[Mock Mode](docs/MOCK_MODE.md)** - Testing without hardware
+- **[Migration Guide](docs/MIGRATION.md)** - Upgrading from v2.x
+- **[Troubleshooting](docs/TROUBLESHOOTING.md)** - Common issues and solutions
+
+## Key Concepts
 
-### getThrottle
-get full status data for a given address or array of addresses (eg [11, 38])
-```javascript
-await client.getThrottle(addresses);
+### Event-Driven Architecture
+
+Subscribe to real-time updates from JMRI:
+
+```typescript
+client.on('connected', () => { });
+client.on('disconnected', (reason) => { });
+client.on('power:changed', (state) => { });
+client.on('throttle:updated', (id, data) => { });
 ```
 
-### setThrottleSpeed
-set speed for specified throttle address
-```javascript
-await client.setThrottleSpeed(address, speed);
+### Throttle Control
+
+Full control of DCC locomotives:
+
+```typescript
+const throttle = await client.acquireThrottle({ address: 3 });
+await client.setThrottleSpeed(throttle, 0.5);
+await client.setThrottleDirection(throttle, true);
+await client.setThrottleFunction(throttle, 'F0', true);
+await client.releaseThrottle(throttle);
 ```
 
-### setThrottleDirection
-set direction for specified address
-use 'true' for forward, 'false' for backward
-```javascript
-await client.setThrottleDirection(address, direction);
+### Auto-Reconnection
+
+Automatically reconnects with exponential backoff:
+
+```typescript
+client.on('reconnecting', (attempt, delay) => {
+  console.log(`Reconnecting attempt ${attempt} in ${delay}ms`);
+});
 ```
 
-### setThrottleFunction
-set function value specified address and function
-```javascript
-await client.setThrottleFunction(address, functionNumber, value);
+## Testing
+
+**Unit Tests** (no hardware required):
+```bash
+npm test
 ```
 
-### getTurnouts
-list all turnouts with current status
-```javascript
-await client.getTurnouts();
+**Mock Mode Demo** (no hardware required):
+```bash
+npm run demo:mock
 ```
 
-### setTurnout
-set status of specific turnout by address
-```javascript
-await client.setTurnout(address, value);
+**Functional Test** (requires JMRI hardware):
+```bash
+npm run functional
 ```
+
+⚠️ **Safety**: Includes automatic power-off on exit, errors, and Ctrl+C.
+
+See **[Mock Mode Guide](docs/MOCK_MODE.md)** and **[Testing Guide](docs/TESTING.md)** for complete instructions.
+
+## Contributing
+
+Issues and pull requests welcome! Please see the [GitHub repository](https://github.com/yamanote1138/jmri-client).
+
+## License
+
+MIT
+
+## Links
+
+- [GitHub Repository](https://github.com/yamanote1138/jmri-client)
+- [NPM Package](https://www.npmjs.com/package/jmri-client)
+- [JMRI Project](http://jmri.sourceforge.net/)
+- [JMRI JSON Protocol](https://www.jmri.org/help/en/html/web/JsonServlet.shtml)

package/dist/cjs/client.js

@@ -0,0 +1,245 @@
+"use strict";
+/**
+ * Main JMRI client class
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JmriClient = void 0;
+const events_1 = require("events");
+const websocket_client_js_1 = require("./core/websocket-client.js");
+const power_manager_js_1 = require("./managers/power-manager.js");
+const roster_manager_js_1 = require("./managers/roster-manager.js");
+const throttle_manager_js_1 = require("./managers/throttle-manager.js");
+const client_options_js_1 = require("./types/client-options.js");
+/**
+ * JMRI WebSocket Client
+ * Provides event-driven interface to JMRI with throttle control
+ */
+class JmriClient extends events_1.EventEmitter {
+    /**
+     * Create a new JMRI client
+     *
+     * @param options - Client configuration options
+     *
+     * @example
+     * ```typescript
+     * const client = new JmriClient({
+     *   host: 'jmri.local',
+     *   port: 12080
+     * });
+     *
+     * client.on('connected', () => console.log('Connected!'));
+     * client.on('power:changed', (state) => console.log('Power:', state));
+     * ```
+     */
+    constructor(options) {
+        super();
+        // Merge options with defaults
+        this.options = (0, client_options_js_1.mergeOptions)(options);
+        // Create WebSocket client
+        this.wsClient = new websocket_client_js_1.WebSocketClient(this.options);
+        // Create managers
+        this.powerManager = new power_manager_js_1.PowerManager(this.wsClient);
+        this.rosterManager = new roster_manager_js_1.RosterManager(this.wsClient);
+        this.throttleManager = new throttle_manager_js_1.ThrottleManager(this.wsClient);
+        // Forward events from WebSocket client
+        this.wsClient.on('connected', () => this.emit('connected'));
+        this.wsClient.on('disconnected', (reason) => this.emit('disconnected', reason));
+        this.wsClient.on('reconnecting', (attempt, delay) => this.emit('reconnecting', attempt, delay));
+        this.wsClient.on('reconnected', () => this.emit('reconnected'));
+        this.wsClient.on('reconnectionFailed', (attempts) => this.emit('reconnectionFailed', attempts));
+        this.wsClient.on('connectionStateChanged', (state) => this.emit('connectionStateChanged', state));
+        this.wsClient.on('error', (error) => this.emit('error', error));
+        this.wsClient.on('heartbeat:sent', () => this.emit('heartbeat:sent'));
+        this.wsClient.on('heartbeat:timeout', () => this.emit('heartbeat:timeout'));
+        // Forward events from managers
+        this.powerManager.on('power:changed', (state) => this.emit('power:changed', state));
+        this.throttleManager.on('throttle:acquired', (id) => this.emit('throttle:acquired', id));
+        this.throttleManager.on('throttle:updated', (id, data) => this.emit('throttle:updated', id, data));
+        this.throttleManager.on('throttle:released', (id) => this.emit('throttle:released', id));
+        this.throttleManager.on('throttle:lost', (id) => this.emit('throttle:lost', id));
+        // Auto-connect if enabled
+        if (this.options.autoConnect) {
+            this.connect().catch((error) => {
+                this.emit('error', error);
+            });
+        }
+    }
+    /**
+     * Connect to JMRI server
+     */
+    async connect() {
+        return this.wsClient.connect();
+    }
+    /**
+     * Disconnect from JMRI server
+     * Releases all throttles and closes connection
+     */
+    async disconnect() {
+        // Release all throttles first
+        await this.throttleManager.releaseAllThrottles();
+        // Disconnect WebSocket
+        return this.wsClient.disconnect();
+    }
+    /**
+     * Get current connection state
+     */
+    getConnectionState() {
+        return this.wsClient.getState();
+    }
+    /**
+     * Check if connected to JMRI
+     */
+    isConnected() {
+        return this.wsClient.isConnected();
+    }
+    // ============================================================================
+    // Power Control
+    // ============================================================================
+    /**
+     * Get current track power state
+     */
+    async getPower() {
+        return this.powerManager.getPower();
+    }
+    /**
+     * Set track power state
+     */
+    async setPower(state) {
+        return this.powerManager.setPower(state);
+    }
+    /**
+     * Turn track power on
+     */
+    async powerOn() {
+        return this.powerManager.powerOn();
+    }
+    /**
+     * Turn track power off
+     */
+    async powerOff() {
+        return this.powerManager.powerOff();
+    }
+    // ============================================================================
+    // Roster Management
+    // ============================================================================
+    /**
+     * Get all roster entries
+     */
+    async getRoster() {
+        return this.rosterManager.getRoster();
+    }
+    /**
+     * Get roster entry by name
+     */
+    async getRosterEntryByName(name) {
+        return this.rosterManager.getRosterEntryByName(name);
+    }
+    /**
+     * Get roster entry by address
+     */
+    async getRosterEntryByAddress(address) {
+        return this.rosterManager.getRosterEntryByAddress(address);
+    }
+    /**
+     * Search roster by partial name match
+     */
+    async searchRoster(query) {
+        return this.rosterManager.searchRoster(query);
+    }
+    // ============================================================================
+    // Throttle Control
+    // ============================================================================
+    /**
+     * Acquire a throttle for a locomotive
+     *
+     * @param options - Throttle acquisition options
+     * @returns Throttle ID for use in other throttle methods
+     *
+     * @example
+     * ```typescript
+     * const throttleId = await client.acquireThrottle({ address: 3 });
+     * await client.setThrottleSpeed(throttleId, 0.5); // Half speed
+     * ```
+     */
+    async acquireThrottle(options) {
+        return this.throttleManager.acquireThrottle(options);
+    }
+    /**
+     * Release a throttle
+     */
+    async releaseThrottle(throttleId) {
+        return this.throttleManager.releaseThrottle(throttleId);
+    }
+    /**
+     * Set throttle speed (0.0 to 1.0)
+     *
+     * @param throttleId - Throttle ID from acquireThrottle
+     * @param speed - Speed value between 0.0 (stopped) and 1.0 (full speed)
+     */
+    async setThrottleSpeed(throttleId, speed) {
+        return this.throttleManager.setSpeed(throttleId, speed);
+    }
+    /**
+     * Set throttle direction
+     *
+     * @param throttleId - Throttle ID from acquireThrottle
+     * @param forward - True for forward, false for reverse
+     */
+    async setThrottleDirection(throttleId, forward) {
+        return this.throttleManager.setDirection(throttleId, forward);
+    }
+    /**
+     * Set throttle function (F0-F28)
+     *
+     * @param throttleId - Throttle ID from acquireThrottle
+     * @param functionKey - Function key (F0-F28)
+     * @param value - True to activate, false to deactivate
+     *
+     * @example
+     * ```typescript
+     * await client.setThrottleFunction(throttleId, 'F0', true);  // Headlight on
+     * await client.setThrottleFunction(throttleId, 'F2', true);  // Horn
+     * ```
+     */
+    async setThrottleFunction(throttleId, functionKey, value) {
+        return this.throttleManager.setFunction(throttleId, functionKey, value);
+    }
+    /**
+     * Emergency stop for a throttle (speed to 0)
+     */
+    async emergencyStop(throttleId) {
+        return this.throttleManager.emergencyStop(throttleId);
+    }
+    /**
+     * Set throttle to idle (speed to 0, maintain direction)
+     */
+    async idleThrottle(throttleId) {
+        return this.throttleManager.idle(throttleId);
+    }
+    /**
+     * Get throttle state
+     */
+    getThrottleState(throttleId) {
+        return this.throttleManager.getThrottleState(throttleId);
+    }
+    /**
+     * Get all throttle IDs
+     */
+    getThrottleIds() {
+        return this.throttleManager.getThrottleIds();
+    }
+    /**
+     * Get all throttle states
+     */
+    getAllThrottles() {
+        return this.throttleManager.getAllThrottles();
+    }
+    /**
+     * Release all throttles
+     */
+    async releaseAllThrottles() {
+        return this.throttleManager.releaseAllThrottles();
+    }
+}
+exports.JmriClient = JmriClient;
+//# sourceMappingURL=client.js.map

package/dist/cjs/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"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"}

package/dist/cjs/core/connection-state-manager.js

@@ -0,0 +1,85 @@
+"use strict";
+/**
+ * Connection state management with state machine
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConnectionStateManager = void 0;
+const events_1 = require("events");
+const events_js_1 = require("../types/events.js");
+/**
+ * Valid state transitions
+ */
+const VALID_TRANSITIONS = {
+    [events_js_1.ConnectionState.DISCONNECTED]: [events_js_1.ConnectionState.CONNECTING],
+    [events_js_1.ConnectionState.CONNECTING]: [events_js_1.ConnectionState.CONNECTED, events_js_1.ConnectionState.DISCONNECTED],
+    [events_js_1.ConnectionState.CONNECTED]: [events_js_1.ConnectionState.DISCONNECTED, events_js_1.ConnectionState.RECONNECTING],
+    [events_js_1.ConnectionState.RECONNECTING]: [events_js_1.ConnectionState.CONNECTED, events_js_1.ConnectionState.DISCONNECTED]
+};
+/**
+ * Manages connection state with validation
+ */
+class ConnectionStateManager extends events_1.EventEmitter {
+    constructor() {
+        super(...arguments);
+        this.currentState = events_js_1.ConnectionState.DISCONNECTED;
+    }
+    /**
+     * Get current connection state
+     */
+    getState() {
+        return this.currentState;
+    }
+    /**
+     * Check if currently connected
+     */
+    isConnected() {
+        return this.currentState === events_js_1.ConnectionState.CONNECTED;
+    }
+    /**
+     * Check if currently connecting
+     */
+    isConnecting() {
+        return this.currentState === events_js_1.ConnectionState.CONNECTING;
+    }
+    /**
+     * Check if currently disconnected
+     */
+    isDisconnected() {
+        return this.currentState === events_js_1.ConnectionState.DISCONNECTED;
+    }
+    /**
+     * Check if currently reconnecting
+     */
+    isReconnecting() {
+        return this.currentState === events_js_1.ConnectionState.RECONNECTING;
+    }
+    /**
+     * Transition to new state
+     * Validates transition and emits event
+     */
+    transition(newState) {
+        const validTransitions = VALID_TRANSITIONS[this.currentState];
+        if (!validTransitions.includes(newState)) {
+            throw new Error(`Invalid state transition: ${this.currentState} -> ${newState}`);
+        }
+        const previousState = this.currentState;
+        this.currentState = newState;
+        this.emit('stateChanged', newState, previousState);
+    }
+    /**
+     * Force state without validation (use with caution)
+     */
+    forceState(newState) {
+        const previousState = this.currentState;
+        this.currentState = newState;
+        this.emit('stateChanged', newState, previousState);
+    }
+    /**
+     * Reset to disconnected state
+     */
+    reset() {
+        this.forceState(events_js_1.ConnectionState.DISCONNECTED);
+    }
+}
+exports.ConnectionStateManager = ConnectionStateManager;
+//# sourceMappingURL=connection-state-manager.js.map

package/dist/cjs/core/connection-state-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-state-manager.js","sourceRoot":"","sources":["../../../src/core/connection-state-manager.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAEH,mCAAsC;AACtC,kDAAqD;AAErD;;GAEG;AACH,MAAM,iBAAiB,GAA+C;IACpE,CAAC,2BAAe,CAAC,YAAY,CAAC,EAAE,CAAC,2BAAe,CAAC,UAAU,CAAC;IAC5D,CAAC,2BAAe,CAAC,UAAU,CAAC,EAAE,CAAC,2BAAe,CAAC,SAAS,EAAE,2BAAe,CAAC,YAAY,CAAC;IACvF,CAAC,2BAAe,CAAC,SAAS,CAAC,EAAE,CAAC,2BAAe,CAAC,YAAY,EAAE,2BAAe,CAAC,YAAY,CAAC;IACzF,CAAC,2BAAe,CAAC,YAAY,CAAC,EAAE,CAAC,2BAAe,CAAC,SAAS,EAAE,2BAAe,CAAC,YAAY,CAAC;CAC1F,CAAC;AAEF;;GAEG;AACH,MAAa,sBAAuB,SAAQ,qBAAY;IAAxD;;QACU,iBAAY,GAAoB,2BAAe,CAAC,YAAY,CAAC;IAuEvE,CAAC;IArEC;;OAEG;IACH,QAAQ;QACN,OAAO,IAAI,CAAC,YAAY,CAAC;IAC3B,CAAC;IAED;;OAEG;IACH,WAAW;QACT,OAAO,IAAI,CAAC,YAAY,KAAK,2BAAe,CAAC,SAAS,CAAC;IACzD,CAAC;IAED;;OAEG;IACH,YAAY;QACV,OAAO,IAAI,CAAC,YAAY,KAAK,2BAAe,CAAC,UAAU,CAAC;IAC1D,CAAC;IAED;;OAEG;IACH,cAAc;QACZ,OAAO,IAAI,CAAC,YAAY,KAAK,2BAAe,CAAC,YAAY,CAAC;IAC5D,CAAC;IAED;;OAEG;IACH,cAAc;QACZ,OAAO,IAAI,CAAC,YAAY,KAAK,2BAAe,CAAC,YAAY,CAAC;IAC5D,CAAC;IAED;;;OAGG;IACH,UAAU,CAAC,QAAyB;QAClC,MAAM,gBAAgB,GAAG,iBAAiB,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QAE9D,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;YACzC,MAAM,IAAI,KAAK,CACb,6BAA6B,IAAI,CAAC,YAAY,OAAO,QAAQ,EAAE,CAChE,CAAC;QACJ,CAAC;QAED,MAAM,aAAa,GAAG,IAAI,CAAC,YAAY,CAAC;QACxC,IAAI,CAAC,YAAY,GAAG,QAAQ,CAAC;QAE7B,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,QAAQ,EAAE,aAAa,CAAC,CAAC;IACrD,CAAC;IAED;;OAEG;IACH,UAAU,CAAC,QAAyB;QAClC,MAAM,aAAa,GAAG,IAAI,CAAC,YAAY,CAAC;QACxC,IAAI,CAAC,YAAY,GAAG,QAAQ,CAAC;QAC7B,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,QAAQ,EAAE,aAAa,CAAC,CAAC;IACrD,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,UAAU,CAAC,2BAAe,CAAC,YAAY,CAAC,CAAC;IAChD,CAAC;CACF;AAxED,wDAwEC"}

package/dist/cjs/core/heartbeat-manager.js

@@ -0,0 +1,80 @@
+"use strict";
+/**
+ * Heartbeat (ping/pong) management
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HeartbeatManager = void 0;
+const events_1 = require("events");
+/**
+ * Manages WebSocket heartbeat via ping/pong
+ */
+class HeartbeatManager extends events_1.EventEmitter {
+    constructor(options) {
+        super();
+        this.isRunning = false;
+        this.options = options;
+    }
+    /**
+     * Start heartbeat monitoring
+     * @param sendPing - Callback to send ping message
+     */
+    start(sendPing) {
+        if (!this.options.enabled || this.isRunning) {
+            return;
+        }
+        this.isRunning = true;
+        // Send ping at regular intervals
+        this.pingInterval = setInterval(() => {
+            sendPing();
+            this.emit('pingSent');
+            // Start pong timeout
+            this.pongTimeout = setTimeout(() => {
+                this.emit('timeout');
+            }, this.options.timeout);
+        }, this.options.interval);
+    }
+    /**
+     * Stop heartbeat monitoring
+     */
+    stop() {
+        this.isRunning = false;
+        if (this.pingInterval) {
+            clearInterval(this.pingInterval);
+            this.pingInterval = undefined;
+        }
+        if (this.pongTimeout) {
+            clearTimeout(this.pongTimeout);
+            this.pongTimeout = undefined;
+        }
+    }
+    /**
+     * Handle pong received from server
+     */
+    receivedPong() {
+        // Clear pong timeout
+        if (this.pongTimeout) {
+            clearTimeout(this.pongTimeout);
+            this.pongTimeout = undefined;
+        }
+        this.emit('pongReceived');
+    }
+    /**
+     * Check if heartbeat is running
+     */
+    running() {
+        return this.isRunning;
+    }
+    /**
+     * Update heartbeat options
+     */
+    updateOptions(options) {
+        const wasRunning = this.isRunning;
+        if (wasRunning) {
+            this.stop();
+        }
+        this.options = { ...this.options, ...options };
+        // Note: Caller must call start() again if needed
+    }
+}
+exports.HeartbeatManager = HeartbeatManager;
+//# sourceMappingURL=heartbeat-manager.js.map

package/dist/cjs/core/heartbeat-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"heartbeat-manager.js","sourceRoot":"","sources":["../../../src/core/heartbeat-manager.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAEH,mCAAsC;AAGtC;;GAEG;AACH,MAAa,gBAAiB,SAAQ,qBAAY;IAMhD,YAAY,OAAyB;QACnC,KAAK,EAAE,CAAC;QAHF,cAAS,GAAY,KAAK,CAAC;QAIjC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,QAAoB;QACxB,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YAC5C,OAAO;QACT,CAAC;QAED,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QAEtB,iCAAiC;QACjC,IAAI,CAAC,YAAY,GAAG,WAAW,CAAC,GAAG,EAAE;YACnC,QAAQ,EAAE,CAAC;YACX,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YAEtB,qBAAqB;YACrB,IAAI,CAAC,WAAW,GAAG,UAAU,CAAC,GAAG,EAAE;gBACjC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YACvB,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAC3B,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC5B,CAAC;IAED;;OAEG;IACH,IAAI;QACF,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC;QAEvB,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YACtB,aAAa,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YACjC,IAAI,CAAC,YAAY,GAAG,SAAS,CAAC;QAChC,CAAC;QAED,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACrB,YAAY,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;YAC/B,IAAI,CAAC,WAAW,GAAG,SAAS,CAAC;QAC/B,CAAC;IACH,CAAC;IAED;;OAEG;IACH,YAAY;QACV,qBAAqB;QACrB,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACrB,YAAY,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;YAC/B,IAAI,CAAC,WAAW,GAAG,SAAS,CAAC;QAC/B,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;IAC5B,CAAC;IAED;;OAEG;IACH,OAAO;QACL,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAED;;OAEG;IACH,aAAa,CAAC,OAAkC;QAC9C,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC;QAElC,IAAI,UAAU,EAAE,CAAC;YACf,IAAI,CAAC,IAAI,EAAE,CAAC;QACd,CAAC;QAED,IAAI,CAAC,OAAO,GAAG,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE,GAAG,OAAO,EAAE,CAAC;QAE/C,iDAAiD;IACnD,CAAC;CACF;AApFD,4CAoFC"}

package/dist/cjs/core/index.js

@@ -0,0 +1,25 @@
+"use strict";
+/**
+ * Core infrastructure exports
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./websocket-client.js"), exports);
+__exportStar(require("./connection-state-manager.js"), exports);
+__exportStar(require("./reconnection-manager.js"), exports);
+__exportStar(require("./heartbeat-manager.js"), exports);
+__exportStar(require("./message-queue.js"), exports);
+//# sourceMappingURL=index.js.map

package/dist/cjs/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/index.ts"],"names":[],"mappings":";AAAA;;GAEG;;;;;;;;;;;;;;;;AAEH,wDAAsC;AACtC,gEAA8C;AAC9C,4DAA0C;AAC1C,yDAAuC;AACvC,qDAAmC"}