@xiboplayer/xmr 0.2.0 → 0.3.1

package/README.md

@@ -1,20 +1,21 @@
-# @xiboplayer/xmr Documentation
+# @xiboplayer/xmr
 
-**XMR (Xibo Message Relay) WebSocket client for real-time CMS commands.**
+**XMR WebSocket client for real-time Xibo CMS commands.**
 
 ## Overview
 
-The XMR package provides WebSocket integration with Xibo CMS, enabling real-time push commands from CMS to player without polling.
+Listens for push commands from the CMS over WebSocket with automatic reconnection:
 
-### Key Features
-
-- **Real-time commands**: Instant content updates via WebSocket
-- **Automatic reconnection**: Exponential backoff with max 10 attempts
-- **Connection management**: Handles disconnects, errors, and network issues
-- **7 CMS commands**: collectNow, screenShot, changeLayout, criteriaUpdate, and more
-- **Event-driven**: Clean event-based API for command handling
-- **Memory efficient**: Proper cleanup of timers and event listeners
-- **Production ready**: Comprehensive test suite with 48 test cases
+- **collectNow** — trigger an immediate collection cycle
+- **screenshot** — request a display screenshot
+- **changeLayout** — switch to a specific layout
+- **overlayLayout** — show an overlay layout
+- **revertToSchedule** — return to the scheduled playlist
+- **purgeAll** — clear all cached content
+- **dataUpdate** — notify of updated widget data
+- **triggerWebhook** — fire a webhook action
+- **commandAction** — execute a shell command
+- **criteriaUpdate** — update geo/criteria filters
 
 ## Installation
 
@@ -22,339 +23,26 @@ The XMR package provides WebSocket integration with Xibo CMS, enabling real-time
 npm install @xiboplayer/xmr
 ```
 
-## Quick Start
-
-```javascript
-import { XmrWrapper } from '@xiboplayer/xmr';
-
-// Create wrapper
-const config = {
-  cmsAddress: 'https://cms.example.com',
-  hardwareKey: 'player-hw-key-123',
-  xmrChannel: 'player-channel' // Optional, defaults to player-{hardwareKey}
-};
-
-const player = {
-  collect: async () => { /* ... */ },
-  captureScreenshot: async () => { /* ... */ },
-  changeLayout: async (layoutId) => { /* ... */ },
-  reportGeoLocation: async (data) => { /* ... */ },
-  updateStatus: (status) => { /* ... */ }
-};
-
-const xmr = new XmrWrapper(config, player);
-
-// Start connection
-const connected = await xmr.start('wss://cms.example.com:9505', 'cms-key-123');
-
-if (connected) {
-  console.log('XMR connected');
-}
-
-// Check connection status
-if (xmr.isConnected()) {
-  console.log('Currently connected');
-}
-
-// Stop connection
-await xmr.stop();
-```
-
-## Supported Commands
-
-### Core Commands
-
-| Command | Description | Player Method |
-|---------|-------------|---------------|
-| `collectNow` | Force immediate XMDS sync | `player.collect()` |
-| `screenShot` | Capture screenshot | `player.captureScreenshot()` |
-| `changeLayout` | Switch to specific layout | `player.changeLayout(layoutId)` |
-| `licenceCheck` | Validate license (no-op for Linux) | None |
-| `rekey` | Rotate RSA keys | None (future) |
-
-### New in v0.0.6
-
-| Command | Description | Player Method |
-|---------|-------------|---------------|
-| `criteriaUpdate` | Update display criteria | `player.collect()` |
-| `currentGeoLocation` | Report geo location | `player.reportGeoLocation(data)` |
-
-See [XMR_COMMANDS.md](./XMR_COMMANDS.md) for complete command reference.
-
-## Connection Lifecycle
-
-```
-                    ┌──────────┐
-                    │  start() │
-                    └─────┬────┘
-                          │
-                          ▼
-                    ┌──────────┐
-              ┌─────│Connected │◄─────┐
-              │     └─────┬────┘      │
-              │           │           │
-    Network   │           │Commands   │Auto
-    Error     │           │Flowing    │Reconnect
-              │           │           │
-              ▼           ▼           │
-        ┌──────────┐            ┌──────────┐
-        │Disconnect│────────────│Reconnect │
-        └─────┬────┘  Backoff   └──────────┘
-              │
-              │stop()
-              ▼
-        ┌──────────┐
-        │ Stopped  │
-        └──────────┘
-```
-
-### Reconnection Logic
-
-- **Exponential backoff**: 5s, 10s, 15s, 20s, 25s, 30s, 35s, 40s, 45s, 50s
-- **Max attempts**: 10 (then waits for next collection cycle)
-- **Intentional shutdown**: No reconnect when `stop()` is called
-- **Connection events**: `connected`, `disconnected`, `error`
-
-## API Reference
-
-### XmrWrapper
-
-#### Constructor
-
-```javascript
-new XmrWrapper(config, player)
-```
-
-**Parameters**:
-- `config` (Object): Player configuration
-  - `hardwareKey` (string): Player hardware key
-  - `xmrChannel` (string, optional): Custom channel ID
-- `player` (Object): Player instance with command handlers
-
-#### Methods
-
-##### start(xmrUrl, cmsKey)
-
-Start XMR connection.
-
-```javascript
-await xmr.start('wss://cms.example.com:9505', 'cms-key-123');
-```
-
-**Returns**: `Promise<boolean>` - True if connected, false if failed
-
-##### stop()
-
-Stop XMR connection and cancel reconnection.
-
-```javascript
-await xmr.stop();
-```
-
-##### isConnected()
-
-Check connection status.
-
-```javascript
-const connected = xmr.isConnected();
-```
-
-**Returns**: `boolean`
-
-##### send(action, data)
-
-Send message to CMS (for future features).
-
-```javascript
-await xmr.send('customAction', { key: 'value' });
-```
-
-**Returns**: `Promise<boolean>` - True if sent successfully
-
-### Player Interface
-
-Your player object should implement these methods:
-
-```javascript
-{
-  // Required
-  collect: async () => Promise<void>,
-  captureScreenshot: async () => Promise<void>,
-  changeLayout: async (layoutId) => Promise<void>,
-
-  // Optional
-  reportGeoLocation: async (data) => Promise<void>,
-  updateStatus: (status) => void
-}
-```
-
-## Testing
-
-### Run Tests
-
-```bash
-# Run all tests
-npm test
-
-# Watch mode
-npm run test:watch
-
-# Coverage report
-npm run test:coverage
-```
-
-### Test Coverage
-
-- ✅ 48 test cases
-- ✅ Constructor and initialization
-- ✅ Connection lifecycle (start, stop, reconnect)
-- ✅ All 7 CMS commands
-- ✅ Error handling and edge cases
-- ✅ Memory management and cleanup
-
-See [XMR_TESTING.md](./XMR_TESTING.md) for comprehensive testing guide.
-
-## Configuration
-
-### From registerDisplay
-
-XMR settings are typically received from CMS `registerDisplay` response:
-
-```json
-{
-  "settings": {
-    "xmrWebSocketAddress": "wss://cms.example.com:9505",
-    "xmrCmsKey": "abcdef123456",
-    "xmrChannel": "player-hw-key-123"
-  }
-}
-```
-
-Use these values with `start()`:
-
-```javascript
-const { xmrWebSocketAddress, xmrCmsKey } = settings;
-await xmr.start(xmrWebSocketAddress, xmrCmsKey);
-```
-
-### Custom Channel
-
-Override default channel (player-{hardwareKey}):
+## Usage
 
 ```javascript
-const config = {
-  hardwareKey: 'hw-123',
-  xmrChannel: 'custom-channel-name' // Use this instead
-};
-```
-
-## Error Handling
-
-All command handlers include error handling:
+import { XmrClient } from '@xiboplayer/xmr';
 
-```javascript
-this.xmr.on('collectNow', async () => {
-  console.log('[XMR] Received collectNow command');
-  try {
-    await this.player.collect();
-    console.log('[XMR] collectNow completed successfully');
-  } catch (error) {
-    console.error('[XMR] collectNow failed:', error);
-  }
+const xmr = new XmrClient({
+  wsUrl: 'wss://your-cms.example.com/xmr',
+  channel: 'display-channel-key',
+  rsaKey: 'display-rsa-key',
 });
-```
-
-Errors don't:
-- ❌ Crash the player
-- ❌ Disconnect XMR
-- ❌ Prevent other commands
-
-They do:
-- ✅ Log to console
-- ✅ Preserve connection state
-- ✅ Continue processing other commands
-
-## Troubleshooting
-
-### Connection Issues
-
-**Problem**: XMR won't connect
-
-**Solution**:
-1. Verify XMR enabled in CMS settings
-2. Check firewall allows port 9505
-3. Verify `xmrWebSocketAddress` from registerDisplay
-4. Check browser console for errors
-
-### Commands Not Executing
-
-**Problem**: collectNow sent but nothing happens
-
-**Solution**:
-1. Check `xmr.isConnected()` returns true
-2. Verify player methods exist (`player.collect`, etc.)
-3. Check console for command reception logs
-4. Look for errors in command handler
-
-### Reconnection Loops
-
-**Problem**: Keeps reconnecting forever
-
-**Solution**:
-1. Verify XMR server is running
-2. Check cmsKey is correct
-3. Monitor `reconnectAttempts` counter
-4. Manually stop: `await xmr.stop()`
 
-See [XMR_TESTING.md](./XMR_TESTING.md#troubleshooting) for more.
+xmr.on('collectNow', () => player.collect());
+xmr.on('screenshot', () => captureScreenshot());
+xmr.connect();
+```
 
 ## Dependencies
 
-- `@xibosignage/xibo-communication-framework@^0.0.6` - Official XMR library
-- `@xiboplayer/utils` - Logging and utilities
-
-## Version History
-
-### v0.9.0 (Current)
-- ✅ Upgraded to @xibosignage/xibo-communication-framework@0.0.6
-- ✅ Added `criteriaUpdate` command
-- ✅ Added `currentGeoLocation` command
-- ✅ Intentional shutdown flag (no reconnect on stop)
-- ✅ Comprehensive test suite (48 tests)
-- ✅ Complete documentation
-
-### Previous Versions
-- Basic XMR integration
-- Core commands (collectNow, screenShot, changeLayout)
-- Automatic reconnection
-
-## Contributing
-
-When adding new XMR commands:
-
-1. Add event handler in `setupEventHandlers()`
-2. Update [XMR_COMMANDS.md](./XMR_COMMANDS.md)
-3. Add tests in `xmr-wrapper.test.js`
-4. Implement player method if needed
-
-See [XMR_TESTING.md](./XMR_TESTING.md#adding-new-commands) for details.
-
-## Related Packages
-
-- [@xiboplayer/core](../../core/docs/) - Player core orchestration
-- [@xiboplayer/xmds](../../xmds/docs/) - XMDS SOAP client
-- [@xiboplayer/schedule](../../schedule/docs/) - Schedule engine
-
-## Support
-
-- **GitHub Issues**: https://github.com/xibo/xibo-players/issues
-- **Documentation**: [XMR_COMMANDS.md](./XMR_COMMANDS.md), [XMR_TESTING.md](./XMR_TESTING.md)
-- **Xibo Community**: https://community.xibo.org.uk
+- `@xiboplayer/utils` — logger, events
 
 ---
 
-**Package Version**: 0.9.0 | **XMR Library**: 0.0.6
-
-## License
-
-AGPL-3.0-or-later
+**Part of the [XiboPlayer SDK](https://github.com/xibo-players/xiboplayer)** | [MCP Server](https://github.com/xibo-players/xiboplayer/tree/main/mcp-server) for AI-assisted development

package/package.json

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

package/src/index.js

@@ -1,2 +1,4 @@
 // @xiboplayer/xmr - XMR WebSocket client
+import pkg from '../package.json' with { type: 'json' };
+export const VERSION = pkg.version;
 export { XmrWrapper } from './xmr-wrapper.js';