@xiboplayer/xmr 0.6.10 → 0.6.12

package/README.md

@@ -103,9 +103,40 @@ new XmrWrapper(config, player)
 
 ## Dependencies
 
-- `@xibosignage/xibo-communication-framework` -- XMR protocol implementation
 - `@xiboplayer/utils` -- logger
 
+No external XMR dependencies. The native `XmrClient` (`xmr-client.js`) replaces the
+upstream `@xibosignage/xibo-communication-framework`, providing a complete implementation
+with generic action dispatch and zero third-party dependencies (no luxon, no nanoevents).
+
+### Upstream comparison
+
+| Feature | upstream `xibo-communication-framework@0.0.6` | native `XmrClient` |
+|---------|------------------------------------------------|---------------------|
+| `collectNow` | hardcoded | generic dispatch |
+| `screenShot` | hardcoded | generic dispatch |
+| `licenceCheck` | hardcoded | generic dispatch |
+| `criteriaUpdate` | hardcoded | generic dispatch |
+| `commandAction` (showStatusWindow) | hardcoded, splits commandCode | generic dispatch (full message) |
+| `commandAction` (forceUpdateChromeOS) | hardcoded, splits commandCode | generic dispatch (full message) |
+| `commandAction` (currentGeoLocation) | hardcoded, splits commandCode | generic dispatch (full message) |
+| `commandAction` (other) | **missing** -- `console.error('unknown action')` | generic dispatch (full message) |
+| `changeLayout` | **missing** -- `console.error('unknown action')` | generic dispatch |
+| `overlayLayout` | **missing** -- `console.error('unknown action')` | generic dispatch |
+| `revertToSchedule` | **missing** -- `console.error('unknown action')` | generic dispatch |
+| `purgeAll` | **missing** -- `console.error('unknown action')` | generic dispatch |
+| `triggerWebhook` | **missing** -- `console.error('unknown action')` | generic dispatch |
+| `dataUpdate` | **missing** -- `console.error('unknown action')` | generic dispatch |
+| `rekeyAction` | **missing** -- `console.error('unknown action')` | generic dispatch |
+| Any future CMS action | requires library update | works automatically |
+| TTL check | luxon `DateTime.fromISO().plus()` (68KB) | native `Date.parse()` (0KB) |
+| Event emitter | nanoevents (external) | built-in `Map<Set>` (0KB) |
+| Bundle size impact | ~70KB (luxon + nanoevents + framework) | ~2KB |
+| Reconnect interval | 60s `setInterval` | 60s `setInterval` (same) |
+| `isActive()` check | 15min silence threshold | 15min silence threshold (same) |
+| Init handshake | `{type:'init', key, channel}` | `{type:'init', key, channel}` (same) |
+| Heartbeat handling | `"H"` → update lastMessageAt | `"H"` → update lastMessageAt (same) |
+
 ---
 
 [xiboplayer.org](https://xiboplayer.org) · **Part of the [XiboPlayer SDK](https://github.com/xibo-players/xiboplayer)**

package/docs/XMR_COMMANDS.md

@@ -119,7 +119,7 @@ xmr.send('rekey');
 
 ---
 
-### criteriaUpdate (New in v0.0.6)
+### criteriaUpdate (since v0.9.0)
 
 Updates display criteria and triggers immediate re-collection.
 
@@ -142,7 +142,7 @@ await player.collect(); // Gets new criteria from registerDisplay
 
 ---
 
-### currentGeoLocation (New in v0.0.6)
+### currentGeoLocation (since v0.9.0)
 
 Reports current geographic location to CMS.
 
@@ -285,19 +285,25 @@ To add support for a new XMR command:
 
 ## Version History
 
-### v0.0.6 (Current)
-- ✅ Added `criteriaUpdate` command
-- ✅ Added `currentGeoLocation` command
+### v0.10.0 (Current)
+- ✅ Replaced upstream library with native `XmrClient` (generic action dispatch)
+- ✅ All 14 CMS commands supported (upstream only handled 5)
+- ✅ Any future CMS action works automatically (no code changes needed)
+- ✅ Eliminated luxon (68KB) and nanoevents dependencies
+- ✅ 82 tests (26 XmrClient + 56 XmrWrapper)
+
+### v0.9.0
+- ✅ Added `criteriaUpdate` and `currentGeoLocation` commands
 - ✅ Intentional shutdown flag (no reconnect on stop)
-- ✅ Comprehensive test suite (48 tests)
+- ✅ Comprehensive test suite
 
-### v0.0.5 and earlier
-- Basic commands: collectNow, screenShot, changeLayout, licenceCheck, rekey
+### v0.8.0
+- Initial implementation with full command set
 - Connection lifecycle management
-- Automatic reconnection with exponential backoff
+- Automatic reconnection with 60s health-check interval
 
 ## References
 
-- **XMR Library**: @xibosignage/xibo-communication-framework
+- **XMR Client**: Native `XmrClient` (`xmr-client.js`) — full XMR protocol implementation
 - **Xibo CMS**: https://xibosignage.com
 - **XMR Protocol**: WebSocket-based push messaging

package/docs/XMR_TESTING.md

@@ -32,24 +32,32 @@ npm run test:watch
 
 ### Test Coverage
 
-Current coverage: **48 test cases**
-
-Categories:
-- ✅ **Constructor** (2 tests) - Initialization and state
-- ✅ **Connection lifecycle** (8 tests) - Start, stop, reconnect
-- ✅ **Connection events** (4 tests) - connected, disconnected, error
-- ✅ **CMS commands** (14 tests) - All 7 commands + error handling
-- ✅ **Reconnection logic** (4 tests) - Exponential backoff, max attempts
-- ✅ **stop() method** (4 tests) - Cleanup, error handling
+Current coverage: **82 test cases** (26 XmrClient + 56 XmrWrapper)
+
+**XmrClient** (`xmr-client.test.js`):
+- ✅ **start()** (5 tests) - WebSocket open, init handshake, close, error, reconnect
+- ✅ **Message handling** (7 tests) - Heartbeat, JSON dispatch, TTL check, generic dispatch, commandAction, malformed JSON
+- ✅ **isActive()** (3 tests) - Connected + recent, 15min timeout, not connected
+- ✅ **Reconnect interval** (2 tests) - 60s health check, no reconnect after stop
+- ✅ **stop()** (2 tests) - Cleanup, safe when not started
+- ✅ **on()/emit()** (4 tests) - Multiple listeners, unsubscribe, error isolation
+- ✅ **send()** (2 tests) - JSON via WebSocket, throw when disconnected
+
+**XmrWrapper** (`xmr-wrapper.test.js`):
+- ✅ **Constructor** (1 test) - Initialization and state
+- ✅ **Connection lifecycle** (7 tests) - Start, stop, reuse, custom channel
+- ✅ **Connection events** (3 tests) - connected, disconnected, error
+- ✅ **CMS commands** (31 tests) - All 13 commands + error handling
+- ✅ **stop() method** (3 tests) - Cleanup, error handling
 - ✅ **isConnected()** (3 tests) - Connection state queries
 - ✅ **send()** (4 tests) - Sending messages to CMS
 - ✅ **Edge cases** (3 tests) - Simultaneous commands, rapid cycles
-- ✅ **Memory management** (2 tests) - Timer cleanup, garbage collection
+- ✅ **Memory management** (1 test) - Instance cleanup
 
 ### Test Structure
 
 Tests use Vitest with:
-- **Mocking**: `vi.mock()` for @xibosignage/xibo-communication-framework
+- **Mocking**: `vi.mock()` for `./xmr-client.js` (native XmrClient)
 - **Fake timers**: `vi.useFakeTimers()` for reconnection testing
 - **Async handling**: `vi.runAllTimersAsync()` for event handlers
 
@@ -504,6 +512,6 @@ jobs:
 ## References
 
 - XMR Commands: [XMR_COMMANDS.md](./XMR_COMMANDS.md)
-- XMR Library: [@xibosignage/xibo-communication-framework](https://www.npmjs.com/package/@xibosignage/xibo-communication-framework)
+- XMR Client: Native `XmrClient` (`xmr-client.js`) — full XMR protocol implementation
 - Xibo CMS: https://xibosignage.com
 - WebSocket Testing: https://github.com/websockets/wscat

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xiboplayer/xmr",
-  "version": "0.6.10",
+  "version": "0.6.12",
   "description": "XMR WebSocket client for real-time Xibo CMS commands",
   "type": "module",
   "main": "./src/index.js",
@@ -9,8 +9,7 @@
     ".": "./src/index.js"
   },
   "dependencies": {
-    "@xibosignage/xibo-communication-framework": "^0.0.6",
-    "@xiboplayer/utils": "0.6.10"
+    "@xiboplayer/utils": "0.6.12"
   },
   "devDependencies": {
     "vitest": "^2.0.0"

package/src/index.d.ts

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2024-2026 Pau Aliagas <linuxnow@gmail.com>
 export const VERSION: string;
 
 export class XmrWrapper {

package/src/index.js

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2024-2026 Pau Aliagas <linuxnow@gmail.com>
 // @xiboplayer/xmr - XMR WebSocket client
 import pkg from '../package.json' with { type: 'json' };
 export const VERSION = pkg.version;

package/src/test-utils.js

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2024-2026 Pau Aliagas <linuxnow@gmail.com>
 /**
  * Test Utilities for XMR Package
  *
@@ -20,13 +22,13 @@ export function createSpy() {
 }
 
 /**
- * Mock Xmr class from @xibosignage/xibo-communication-framework
+ * Mock XmrClient class (native xmr-client.js)
  *
  * Usage:
- *   const MockXmr = mockXmr();
+ *   const MockXmrClient = mockXmrClient();
  *   // Use in tests
  */
-export function mockXmr() {
+export function mockXmrClient() {
   class MockXmr {
     constructor(channel) {
       this.channel = channel;

package/src/xmr-client.js

@@ -0,0 +1,179 @@
+/**
+ * Native XMR (Xibo Message Relay) WebSocket Client
+ *
+ * Drop-in replacement for @xibosignage/xibo-communication-framework.
+ * Uses a generic action dispatcher — emit(message.action, message) — so
+ * every CMS action works automatically without a hardcoded if-else chain.
+ *
+ * API-compatible with the upstream Xmr class:
+ *   new XmrClient(channel) → .init() → .start(url, key) → .on(event, cb)
+ */
+
+export class XmrClient {
+  /**
+   * @param {string} channel - XMR channel identifier (e.g. "player-HWKEY")
+   */
+  constructor(channel) {
+    this.channel = channel;
+    this.url = null;
+    this.cmsKey = null;
+    this.socket = null;
+    this.isConnected = false;
+    this.isConnectionWanted = false;
+    this.lastMessageAt = 0;
+    this._interval = null;
+    this._listeners = new Map(); // event → Set<callback>
+  }
+
+  /**
+   * Register an event listener.
+   * @param {string} event
+   * @param {Function} callback
+   * @returns {Function} Unsubscribe function
+   */
+  on(event, callback) {
+    if (!this._listeners.has(event)) {
+      this._listeners.set(event, new Set());
+    }
+    this._listeners.get(event).add(callback);
+    return () => this._listeners.get(event)?.delete(callback);
+  }
+
+  /**
+   * Emit an event to all registered listeners.
+   * @param {string} event
+   * @param {...*} args
+   */
+  emit(event, ...args) {
+    const listeners = this._listeners.get(event);
+    if (!listeners) return;
+    for (const cb of listeners) {
+      try {
+        cb(...args);
+      } catch (e) {
+        console.error(`XmrClient: listener error for '${event}':`, e);
+      }
+    }
+  }
+
+  /**
+   * Initialize the reconnect interval (60s health check).
+   * Same cadence as upstream framework.
+   */
+  async init() {
+    if (this._interval) return;
+    this._interval = setInterval(() => {
+      if (this.isConnectionWanted && !this.isActive()) {
+        this.start(this.url || 'DISABLED', this.cmsKey || 'n/a');
+      }
+    }, 60_000);
+  }
+
+  /**
+   * Connect to XMR WebSocket server.
+   * @param {string} url - WebSocket URL (ws:// or wss://)
+   * @param {string} cmsKey - CMS authentication key
+   */
+  async start(url, cmsKey) {
+    this.url = url;
+    this.cmsKey = cmsKey;
+    this.isConnectionWanted = true;
+
+    // Close existing socket if any
+    if (this.socket) {
+      try { this.socket.close(); } catch (_) { /* ignore */ }
+      this.socket = null;
+      this.isConnected = false;
+    }
+
+    try {
+      this.socket = new WebSocket(url);
+    } catch (e) {
+      this.emit('error', 'Failed to connect');
+      return;
+    }
+
+    this.socket.addEventListener('open', () => {
+      this.socket.send(JSON.stringify({
+        type: 'init',
+        key: this.cmsKey,
+        channel: this.channel,
+      }));
+      this.isConnected = true;
+      this.lastMessageAt = Date.now();
+      this.emit('connected');
+    });
+
+    this.socket.addEventListener('close', () => {
+      this.isConnected = false;
+      this.emit('disconnected');
+    });
+
+    this.socket.addEventListener('error', () => {
+      this.emit('error', 'error');
+    });
+
+    this.socket.addEventListener('message', (event) => {
+      this.lastMessageAt = Date.now();
+
+      // Heartbeat
+      if (event.data === 'H') return;
+
+      // JSON action message
+      try {
+        const message = JSON.parse(event.data);
+        if (!message.action) return;
+
+        // TTL check: createdDt (ISO 8601) + ttl seconds > now
+        if (message.createdDt && message.ttl) {
+          const created = Date.parse(message.createdDt);
+          if (!isNaN(created)) {
+            const expiresAt = created + parseInt(message.ttl) * 1000;
+            if (expiresAt < Date.now()) return; // expired
+          }
+        }
+
+        // Generic dispatch — every CMS action works automatically
+        this.emit(message.action, message);
+      } catch (e) {
+        console.error('XmrClient: failed to parse message:', e);
+      }
+    });
+  }
+
+  /**
+   * Stop the connection and clear the reconnect interval.
+   */
+  async stop() {
+    this.isConnectionWanted = false;
+    if (this._interval) {
+      clearInterval(this._interval);
+      this._interval = null;
+    }
+    if (this.socket) {
+      this.socket.close();
+      this.socket = null;
+      this.isConnected = false;
+    }
+  }
+
+  /**
+   * Send a message to the server via WebSocket.
+   * @param {string} action - Action name
+   * @param {*} data - Data payload
+   */
+  async send(action, data) {
+    if (!this.socket || !this.isConnected) {
+      throw new Error('Not connected');
+    }
+    this.socket.send(JSON.stringify({ action, ...data }));
+  }
+
+  /**
+   * Check if the connection is active (connected + message within 15min).
+   * @returns {boolean}
+   */
+  isActive() {
+    return this.isConnected && (Date.now() - this.lastMessageAt) < 15 * 60 * 1000;
+  }
+}