@xiboplayer/xmds 0.6.3 → 0.6.5

package/README.md

@@ -1,15 +1,42 @@
 # @xiboplayer/xmds
 
-**XMDS SOAP + REST client for Xibo CMS communication.**
+**XMDS/REST dual-transport CMS client for Xibo digital signage -- auto-detects REST or SOAP based on CMS capabilities.**
 
 ## Overview
 
-Dual-transport client supporting both Xibo communication protocols:
+Unified abstraction over Xibo's two communication protocols:
 
-- **XMDS SOAP** (v3-v7) — standard Xibo player protocol with XML encoding
-- **REST API** — lighter JSON transport (~30% smaller payloads) with ETag caching
+- **REST API v2** -- JSON-based, JWT auth, ETag caching, ~30% smaller payloads
+- **XMDS SOAP** (v3-v7) -- XML-based, universal compatibility with all Xibo CMS versions
 
-Both transports expose the same API. The REST client is preferred when available.
+Both expose an identical public API. At startup, `ProtocolDetector` probes the CMS to select the optimal transport -- fallback to SOAP if REST is unavailable.
+
+### Capabilities
+
+- **Dual-transport abstraction** -- RestClient and XmdsClient implement the same interface
+- **Auto-detection** -- quick health probe (3s timeout) to select REST or SOAP
+- **HTTP caching** -- REST client uses ETags to avoid redundant GETs
+- **Retry & backoff** -- exponential backoff with jitter (default: 2 retries, 2s base delay)
+- **JWT auth** -- REST client auto-refreshes tokens 60s before expiry
+- **CRC checksums** -- `checkRf` and `checkSchedule` allow skipping unchanged data
+- **Delegated reporting** -- stats/logs can be submitted on behalf of other displays (follower -> lead delegation)
+
+## Architecture
+
+```
+Player Core                        Transport Selection                CMS
+-----------                       --------------------              -----
+
+registerDisplay()                  Is REST available?
+requiredFiles()     Same API       (GET /api/v2/player/health)
+schedule()                 Yes --> RestClient (JWT, ETag)   --> /api/v2/player/*
+getResource()              No  --> XmdsClient (SOAP XML)    --> /xmds.php
+notify()
+submitStats()
+submitLog()
+```
+
+Both clients share the same return types. The scheduler, renderer, and sync modules consume only the CmsClient interface -- they're transport-agnostic.
 
 ## Installation
 
@@ -19,37 +46,164 @@ npm install @xiboplayer/xmds
 
 ## Usage
 
+### Auto-detect and instantiate
+
+```javascript
+import { ProtocolDetector, RestClient, XmdsClient } from '@xiboplayer/xmds';
+
+const detector = new ProtocolDetector(cmsUrl, RestClient, XmdsClient);
+const { client, protocol } = await detector.detect({
+  cmsUrl: 'https://cms.example.com',
+  cmsKey: 'your-server-key',
+  hardwareKey: 'display-123',
+  displayName: 'Main Screen',
+});
+
+console.log(`Using ${protocol} transport`);
+
+const display = await client.registerDisplay();
+const files = await client.requiredFiles();
+const schedule = await client.schedule();
+```
+
+### Force a specific transport
+
+```javascript
+const { client } = await detector.detect(config, 'xmds');  // Force SOAP
+const { client } = await detector.detect(config, 'rest');   // Force REST
+```
+
+### Direct RestClient usage
+
 ```javascript
 import { RestClient } from '@xiboplayer/xmds';
 
 const client = new RestClient({
-  cmsUrl: 'https://your-cms.example.com',
-  serverKey: 'your-key',
-  hardwareKey: 'display-id',
+  cmsUrl: 'https://cms.example.com',
+  cmsKey: 'server-key',
+  hardwareKey: 'display-key',
+  displayName: 'Display 1',
 });
 
-const result = await client.registerDisplay();
-const files = await client.requiredFiles();
-const schedule = await client.schedule();
+const { code, message, settings, syncConfig } = await client.registerDisplay();
+const { files, purge } = await client.requiredFiles();
+```
+
+### Direct XmdsClient usage
+
+```javascript
+import { XmdsClient } from '@xiboplayer/xmds';
+
+const client = new XmdsClient({
+  cmsUrl: 'https://cms.example.com',
+  cmsKey: 'server-key',
+  hardwareKey: 'display-key',
+  displayName: 'Display 1',
+  xmrChannel: 'ch-123',
+  xmrPubKey: '-----BEGIN PUBLIC KEY-----\n...',
+});
+
+const display = await client.registerDisplay();
+```
+
+### Parse schedule without network call
+
+```javascript
+import { parseScheduleResponse } from '@xiboplayer/xmds';
+
+const parsed = parseScheduleResponse(scheduleXml);
+// { default, layouts, campaigns, overlays, actions, commands, dataConnectors }
 ```
 
 ## Methods
 
-| Method | Description |
-|--------|-------------|
-| `registerDisplay()` | Register/authorize the display with the CMS |
-| `requiredFiles()` | Get list of required media files and layouts |
-| `schedule()` | Get the current schedule XML |
-| `getResource(regionId, mediaId)` | Get rendered widget HTML |
-| `notifyStatus(status)` | Report display status to CMS |
-| `mediaInventory(inventory)` | Report cached media inventory |
-| `submitStats(stats, hardwareKeyOverride?)` | Submit proof of play statistics (optional `hardwareKeyOverride` for delegated submissions on behalf of another display) |
-| `submitScreenShot(base64)` | Upload a screenshot to the CMS |
-| `submitLog(logs, hardwareKeyOverride?)` | Submit display logs (optional `hardwareKeyOverride` for delegated submissions on behalf of another display) |
+All methods available on both `RestClient` and `XmdsClient` with identical signatures:
+
+| Method | Parameters | Returns | Description |
+|--------|------------|---------|-------------|
+| `registerDisplay()` | -- | `RegisterDisplayResult` | Authenticate, get settings, tags, commands, sync config |
+| `requiredFiles()` | -- | `RequiredFilesResult` | Get media, layouts, widgets, and files to purge |
+| `schedule()` | -- | `ScheduleObject` | Get complete schedule |
+| `getResource(layoutId, regionId, mediaId)` | number x 3 | `string` | Get rendered widget HTML |
+| `notifyStatus(status)` | Object | JSON/XML | Report display status |
+| `mediaInventory(inventoryXml)` | string/Array | JSON/XML | Report cached media |
+| `submitStats(statsXml, hardwareKeyOverride?)` | string, string? | boolean | Submit proof-of-play (optional override for delegated reporting) |
+| `submitLog(logXml, hardwareKeyOverride?)` | string, string? | boolean | Submit logs (optional override for delegated reporting) |
+| `submitScreenShot(base64Image)` | string | boolean | Upload screenshot |
+| `reportFaults(faultJson)` | string/Object | boolean | Report hardware/software faults |
+| `blackList(mediaId, type, reason)` | string, string, string | boolean | Blacklist broken media |
+| `getWeather()` | -- | JSON/XML | Get weather data for schedule criteria |
+
+### Key Response Types
+
+**RegisterDisplayResult:**
+```typescript
+{
+  code: 'READY' | 'WRONG_SCHEDULE_KEY' | 'DISPLAY_NOT_LICENSED' | ...,
+  message: string,
+  settings: { [key: string]: any },
+  tags: string[],
+  commands: Array<{ commandCode, commandString }>,
+  checkRf: string,         // CRC32 of RequiredFiles (skip if unchanged)
+  checkSchedule: string,   // CRC32 of Schedule (skip if unchanged)
+  syncConfig: {             // Multi-display sync (null if not enabled)
+    syncGroup: string,
+    syncPublisherPort: number,
+    syncSwitchDelay: number,
+    isLead: boolean
+  } | null
+}
+```
+
+## Transport Comparison
+
+| Aspect | REST (v2) | XMDS (SOAP) |
+|--------|-----------|-------------|
+| **Protocol** | JSON over HTTP | XML-RPC over HTTP |
+| **Auth** | JWT (Bearer token) | Per-request params (serverKey) |
+| **Payload size** | ~30% smaller | Baseline |
+| **Caching** | ETags + response cache | No caching |
+| **Availability** | Custom CMS images (Xibo 3.0+) | All Xibo versions (v3-v7+) |
+| **Fallback** | SOAP (automatic) | None |
+
+## Error Handling
+
+**Retry:** Both clients use `fetchWithRetry()` with exponential backoff (2 retries, 2s base delay).
+
+**Token expiry (REST):** 401 response triggers automatic re-authentication and request retry.
+
+**SOAP faults:** XmdsClient parses `<soap:Fault>` and throws with fault message.
+
+**Custom retry strategy:**
+```javascript
+const client = new RestClient({
+  ...config,
+  retryOptions: { maxRetries: 5, baseDelayMs: 5000 }
+});
+```
+
+## Constructor Options
+
+```typescript
+{
+  cmsUrl: string,                // Base URL of Xibo CMS
+  cmsKey: string,                // Server authentication key
+  hardwareKey: string,           // Unique display identifier
+  displayName?: string,          // Human-readable display name
+  clientVersion?: string,        // Default: '0.1.0'
+  clientType?: string,           // Default: 'linux'
+  xmrChannel?: string,           // XMR channel ID
+  xmrPubKey?: string,            // XMR public key (PEM)
+  retryOptions?: {
+    maxRetries?: number,         // Default: 2
+    baseDelayMs?: number         // Default: 2000
+  }
+}
+```
 
 ## Dependencies
 
-- `@xiboplayer/utils` — logger, events, fetchWithRetry
+- `@xiboplayer/utils` -- logger, fetchWithRetry
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xiboplayer/xmds",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "description": "XMDS SOAP client for Xibo CMS communication",
   "type": "module",
   "main": "./src/index.js",
@@ -12,7 +12,7 @@
     "./schedule-parser": "./src/schedule-parser.js"
   },
   "dependencies": {
-    "@xiboplayer/utils": "0.6.3"
+    "@xiboplayer/utils": "0.6.5"
   },
   "devDependencies": {
     "vitest": "^2.0.0"

package/src/cms-client.js

@@ -0,0 +1,89 @@
+/**
+ * CmsClient interface definition — the unified contract for CMS communication.
+ *
+ * Both RestClient and XmdsClient implement this interface identically.
+ * PlayerCore calls these methods without knowing which transport is underneath.
+ * ProtocolDetector selects the implementation at startup.
+ *
+ * This file provides:
+ *   1. JSDoc type definitions for the interface
+ *   2. CMS_CLIENT_METHODS — canonical list of required methods
+ *   3. assertCmsClient() — runtime conformance check
+ *
+ * @example
+ *   import { ProtocolDetector, RestClient, XmdsClient } from '@xiboplayer/xmds';
+ *
+ *   const detector = new ProtocolDetector(cmsUrl, RestClient, XmdsClient);
+ *   const { client } = await detector.detect(config);
+ *   // client implements CmsClient — PlayerCore doesn't care which one
+ */
+
+/**
+ * @typedef {Object} RegisterDisplayResult
+ * @property {string} code - 'READY' or error code
+ * @property {string} message - Human-readable status message
+ * @property {Object|null} settings - Display settings (null if not READY)
+ * @property {string[]} tags - Display tags
+ * @property {Array<{commandCode: string, commandString: string}>} commands - Scheduled commands
+ * @property {Object} displayAttrs - Server-provided attributes (date, timezone, status)
+ * @property {string} checkRf - CRC checksum for RequiredFiles (skip if unchanged)
+ * @property {string} checkSchedule - CRC checksum for Schedule (skip if unchanged)
+ * @property {Object|null} syncConfig - Multi-display sync configuration
+ */
+
+/**
+ * @typedef {Object} RequiredFilesResult
+ * @property {Array<{type: string, id: string, size: number, md5: string, download: string, path: string, saveAs: string|null}>} files
+ * @property {Array<{id: string, storedAs: string}>} purge - Files to delete
+ */
+
+/**
+ * @typedef {Object} CmsClient
+ * @property {() => Promise<RegisterDisplayResult>} registerDisplay
+ * @property {() => Promise<RequiredFilesResult>} requiredFiles
+ * @property {() => Promise<Object>} schedule
+ * @property {(layoutId: string, regionId: string, mediaId: string) => Promise<string>} getResource
+ * @property {(status: Object) => Promise<any>} notifyStatus
+ * @property {(inventoryXml: string|Array) => Promise<any>} mediaInventory
+ * @property {(mediaId: string, type: string, reason: string) => Promise<boolean>} blackList
+ * @property {(logXml: string|Array, hardwareKeyOverride?: string) => Promise<boolean>} submitLog
+ * @property {(base64Image: string) => Promise<boolean>} submitScreenShot
+ * @property {(statsXml: string|Array, hardwareKeyOverride?: string) => Promise<boolean>} submitStats
+ * @property {(faultJson: string|Object) => Promise<boolean>} reportFaults
+ * @property {() => Promise<Object>} getWeather
+ */
+
+/**
+ * Canonical list of methods that every CmsClient implementation must provide.
+ * Used for runtime conformance checks and test assertions.
+ */
+export const CMS_CLIENT_METHODS = [
+  'registerDisplay',
+  'requiredFiles',
+  'schedule',
+  'getResource',
+  'notifyStatus',
+  'mediaInventory',
+  'blackList',
+  'submitLog',
+  'submitScreenShot',
+  'submitStats',
+  'reportFaults',
+  'getWeather',
+];
+
+/**
+ * Verify that an object implements the CmsClient interface.
+ * Throws if any required method is missing or not a function.
+ *
+ * @param {any} client - Object to check
+ * @param {string} [label] - Label for error messages (e.g. 'RestClient')
+ * @throws {Error} If the client doesn't conform
+ */
+export function assertCmsClient(client, label = 'client') {
+  for (const method of CMS_CLIENT_METHODS) {
+    if (typeof client[method] !== 'function') {
+      throw new Error(`${label} missing CmsClient method: ${method}()`);
+    }
+  }
+}

package/src/cms-client.test.js

@@ -0,0 +1,51 @@
+// @vitest-environment node
+import { describe, it, expect } from 'vitest';
+import { CMS_CLIENT_METHODS, assertCmsClient } from './cms-client.js';
+import { RestClient } from './rest-client.js';
+import { XmdsClient } from './xmds-client.js';
+
+const mockConfig = {
+  cmsUrl: 'https://example.com',
+  cmsKey: 'test',
+  hardwareKey: 'hw-001',
+  displayName: 'Test Display',
+  xmrChannel: '',
+};
+
+describe('CmsClient interface conformance', () => {
+  const restClient = new RestClient(mockConfig);
+  const xmdsClient = new XmdsClient(mockConfig);
+
+  it('CMS_CLIENT_METHODS lists 12 methods', () => {
+    expect(CMS_CLIENT_METHODS).toHaveLength(12);
+  });
+
+  for (const method of CMS_CLIENT_METHODS) {
+    it(`RestClient implements ${method}()`, () => {
+      expect(typeof restClient[method]).toBe('function');
+    });
+
+    it(`XmdsClient implements ${method}()`, () => {
+      expect(typeof xmdsClient[method]).toBe('function');
+    });
+  }
+
+  it('assertCmsClient passes for RestClient', () => {
+    expect(() => assertCmsClient(restClient, 'RestClient')).not.toThrow();
+  });
+
+  it('assertCmsClient passes for XmdsClient', () => {
+    expect(() => assertCmsClient(xmdsClient, 'XmdsClient')).not.toThrow();
+  });
+
+  it('assertCmsClient throws for incomplete client', () => {
+    const partial = { registerDisplay: () => {} };
+    expect(() => assertCmsClient(partial, 'partial')).toThrow('partial missing CmsClient method');
+  });
+
+  it('assertCmsClient throws for non-function property', () => {
+    const bad = Object.fromEntries(CMS_CLIENT_METHODS.map(m => [m, () => {}]));
+    bad.schedule = 'not a function';
+    expect(() => assertCmsClient(bad, 'bad')).toThrow('bad missing CmsClient method: schedule()');
+  });
+});

package/src/index.js

@@ -4,4 +4,5 @@ export const VERSION = pkg.version;
 export { RestClient } from './rest-client.js';
 export { XmdsClient } from './xmds-client.js';
 export { ProtocolDetector } from './protocol-detector.js';
+export { CMS_CLIENT_METHODS, assertCmsClient } from './cms-client.js';
 export { parseScheduleResponse } from './schedule-parser.js';

package/src/protocol-detector.js

@@ -2,11 +2,11 @@
  * CMS Protocol Auto-Detector
  *
  * Probes the CMS to determine which communication protocol to use:
- *   - REST/PlayerApiV2 — optimized JSON protocol (custom CMS image)
+ *   - REST/PlayerRestApi — optimized JSON protocol (custom CMS image)
  *   - SOAP/XMDS — universal XML protocol (any vanilla Xibo CMS)
  *
  * Detection logic:
- *   1. GET {cmsUrl}/api/v2/player/health with a 3-second timeout
+ *   1. GET {cmsUrl}${PLAYER_API}/health with a 3-second timeout
  *   2. If 200 + valid JSON → REST
  *   3. If 404/error/timeout → SOAP (fallback)
  *
@@ -25,6 +25,7 @@
  */
 
 import { createLogger } from '@xiboplayer/utils';
+import { assertCmsClient } from './cms-client.js';
 
 const log = createLogger('Protocol');
 
@@ -54,7 +55,7 @@ export class ProtocolDetector {
 
   /**
    * Probe the CMS health endpoint to determine protocol availability.
-   * @returns {Promise<boolean>} true if REST/PlayerApiV2 is available
+   * @returns {Promise<boolean>} true if REST/PlayerRestApi is available
    */
   async probe() {
     const available = await this.RestClient.isAvailable(this.cmsUrl, {
@@ -78,13 +79,17 @@ export class ProtocolDetector {
     if (forceProtocol === 'rest') {
       this.protocol = 'rest';
       log.info('Using REST transport (forced)');
-      return { client: new this.RestClient(config), protocol: 'rest' };
+      const client = new this.RestClient(config);
+      assertCmsClient(client, 'RestClient');
+      return { client, protocol: 'rest' };
     }
 
     if (forceProtocol === 'xmds') {
       this.protocol = 'xmds';
       log.info('Using XMDS/SOAP transport (forced)');
-      return { client: new this.XmdsClient(config), protocol: 'xmds' };
+      const client = new this.XmdsClient(config);
+      assertCmsClient(client, 'XmdsClient');
+      return { client, protocol: 'xmds' };
     }
 
     // Auto-detect
@@ -98,13 +103,17 @@ export class ProtocolDetector {
 
     if (isRest) {
       this.protocol = 'rest';
-      log.info('REST transport detected — using PlayerApiV2');
-      return { client: new this.RestClient(config), protocol: 'rest' };
+      log.info('REST transport detected — using PlayerRestApi');
+      const client = new this.RestClient(config);
+      assertCmsClient(client, 'RestClient');
+      return { client, protocol: 'rest' };
     }
 
     this.protocol = 'xmds';
     log.info('REST unavailable — using XMDS/SOAP transport');
-    return { client: new this.XmdsClient(config), protocol: 'xmds' };
+    const client = new this.XmdsClient(config);
+    assertCmsClient(client, 'XmdsClient');
+    return { client, protocol: 'xmds' };
   }
 
   /**
@@ -132,6 +141,7 @@ export class ProtocolDetector {
       log.info(`Protocol changed: ${previousProtocol} → ${newProtocol}`);
       this.protocol = newProtocol;
       const client = isRest ? new this.RestClient(config) : new this.XmdsClient(config);
+      assertCmsClient(client, isRest ? 'RestClient' : 'XmdsClient');
       return { client, protocol: newProtocol, changed: true };
     }
 

package/src/protocol-detector.test.js

@@ -10,6 +10,14 @@
 
 import { describe, it, expect, beforeEach, vi } from 'vitest';
 import { ProtocolDetector } from './protocol-detector.js';
+import { CMS_CLIENT_METHODS } from './cms-client.js';
+
+// Stub all CmsClient methods on a mock constructor's prototype
+function addCmsClientStubs(MockClass) {
+  for (const method of CMS_CLIENT_METHODS) {
+    MockClass.prototype[method] = vi.fn();
+  }
+}
 
 describe('ProtocolDetector', () => {
   let MockRestClient;
@@ -28,11 +36,13 @@ describe('ProtocolDetector', () => {
       this.type = 'rest';
     });
     MockRestClient.isAvailable = vi.fn();
+    addCmsClientStubs(MockRestClient);
 
     MockXmdsClient = vi.fn(function (cfg) {
       this.config = cfg;
       this.type = 'xmds';
     });
+    addCmsClientStubs(MockXmdsClient);
   });
 
   // ── detect() ─────────────────────────────────────────────────────

package/src/rest-client.js

@@ -513,7 +513,7 @@ export class RestClient {
 
   /**
    * Probe whether the CMS supports API v2.
-   * GET /api/v2/player/health → { version: 2, status: "ok" }
+   * GET ${PLAYER_API}/health → { version: 2, status: "ok" }
    *
    * @param {string} cmsUrl - CMS base URL
    * @param {Object} [retryOptions] - Retry options for fetch

package/src/xmds.rest.integration.test.js

@@ -5,7 +5,7 @@
  * with the Player API module deployed.
  *
  * Prerequisites:
- *   - CMS at CMS_URL must have /api/v2/player/* endpoints deployed
+ *   - CMS at CMS_URL must have ${PLAYER_API}/* endpoints deployed
  *   - A display with the given HARDWARE_KEY must exist and be authorized
  *   - The SERVER_KEY must match the CMS setting
  *