@xiboplayer/xmds 0.6.2 → 0.6.4

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.2",
+  "version": "0.6.4",
   "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.2"
+    "@xiboplayer/utils": "0.6.4"
   },
   "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.d.ts

@@ -36,4 +36,21 @@ export class XmdsClient {
   mediaInventory(inventoryXml: string): Promise<boolean>;
 }
 
+export class ProtocolDetector {
+  constructor(
+    cmsUrl: string,
+    RestClientClass: typeof RestClient,
+    XmdsClientClass: typeof XmdsClient,
+    options?: { probeTimeoutMs?: number }
+  );
+
+  protocol: 'rest' | 'xmds' | null;
+  lastProbeTime: number;
+
+  probe(): Promise<boolean>;
+  detect(config: any, forceProtocol?: 'rest' | 'xmds'): Promise<{ client: any; protocol: 'rest' | 'xmds' }>;
+  reprobe(config: any): Promise<{ client: any; protocol: 'rest' | 'xmds'; changed: boolean }>;
+  getProtocol(): 'rest' | 'xmds' | null;
+}
+
 export function parseScheduleResponse(data: any): any;

package/src/index.js

@@ -3,4 +3,6 @@ import pkg from '../package.json' with { type: 'json' };
 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

@@ -0,0 +1,159 @@
+/**
+ * CMS Protocol Auto-Detector
+ *
+ * Probes the CMS to determine which communication protocol to use:
+ *   - REST/PlayerRestApi — optimized JSON protocol (custom CMS image)
+ *   - SOAP/XMDS — universal XML protocol (any vanilla Xibo CMS)
+ *
+ * Detection logic:
+ *   1. GET {cmsUrl}${PLAYER_API}/health with a 3-second timeout
+ *   2. If 200 + valid JSON → REST
+ *   3. If 404/error/timeout → SOAP (fallback)
+ *
+ * The detected protocol is cached and can be re-probed on connection errors.
+ *
+ * @example
+ *   import { ProtocolDetector } from '@xiboplayer/xmds';
+ *   import { RestClient, XmdsClient } from '@xiboplayer/xmds';
+ *
+ *   const detector = new ProtocolDetector(config.cmsUrl, RestClient, XmdsClient);
+ *   const xmds = await detector.detect(config);
+ *   // xmds is either a RestClient or XmdsClient instance
+ *
+ *   // On connection errors, re-probe:
+ *   const newXmds = await detector.reprobe(config);
+ */
+
+import { createLogger } from '@xiboplayer/utils';
+import { assertCmsClient } from './cms-client.js';
+
+const log = createLogger('Protocol');
+
+/** Default probe timeout in milliseconds */
+const PROBE_TIMEOUT_MS = 3000;
+
+export class ProtocolDetector {
+  /**
+   * @param {string} cmsUrl - CMS base URL
+   * @param {typeof import('./rest-client.js').RestClient} RestClientClass - RestClient constructor
+   * @param {typeof import('./xmds-client.js').XmdsClient} XmdsClientClass - XmdsClient constructor
+   * @param {Object} [options]
+   * @param {number} [options.probeTimeoutMs=3000] - Timeout for health probe
+   */
+  constructor(cmsUrl, RestClientClass, XmdsClientClass, options = {}) {
+    this.cmsUrl = cmsUrl;
+    this.RestClient = RestClientClass;
+    this.XmdsClient = XmdsClientClass;
+    this.probeTimeoutMs = options.probeTimeoutMs || PROBE_TIMEOUT_MS;
+
+    /** @type {'rest'|'xmds'|null} Detected protocol (null = not yet probed) */
+    this.protocol = null;
+
+    /** @type {number} Timestamp of last successful probe */
+    this.lastProbeTime = 0;
+  }
+
+  /**
+   * Probe the CMS health endpoint to determine protocol availability.
+   * @returns {Promise<boolean>} true if REST/PlayerRestApi is available
+   */
+  async probe() {
+    const available = await this.RestClient.isAvailable(this.cmsUrl, {
+      maxRetries: 0,
+      timeoutMs: this.probeTimeoutMs,
+    });
+    this.lastProbeTime = Date.now();
+    return available;
+  }
+
+  /**
+   * Detect the best protocol and create the appropriate client.
+   * On first call, probes the CMS. On subsequent calls, returns the cached
+   * protocol unless reprobe() is called.
+   *
+   * @param {Object} config - Player configuration (passed to client constructor)
+   * @param {string} [forceProtocol] - 'rest'|'xmds' to skip detection
+   * @returns {Promise<{client: any, protocol: 'rest'|'xmds'}>}
+   */
+  async detect(config, forceProtocol) {
+    if (forceProtocol === 'rest') {
+      this.protocol = 'rest';
+      log.info('Using REST transport (forced)');
+      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)');
+      const client = new this.XmdsClient(config);
+      assertCmsClient(client, 'XmdsClient');
+      return { client, protocol: 'xmds' };
+    }
+
+    // Auto-detect
+    log.info('Probing CMS for REST API availability...');
+    let isRest = false;
+    try {
+      isRest = await this.probe();
+    } catch (e) {
+      log.warn('REST probe failed:', e?.message || e);
+    }
+
+    if (isRest) {
+      this.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');
+    const client = new this.XmdsClient(config);
+    assertCmsClient(client, 'XmdsClient');
+    return { client, protocol: 'xmds' };
+  }
+
+  /**
+   * Re-probe the CMS and potentially switch protocols.
+   * Called on connection errors to check if the CMS was upgraded/downgraded.
+   *
+   * @param {Object} config - Player configuration
+   * @returns {Promise<{client: any, protocol: 'rest'|'xmds', changed: boolean}>}
+   */
+  async reprobe(config) {
+    const previousProtocol = this.protocol;
+
+    log.info('Re-probing CMS protocol...');
+    let isRest = false;
+    try {
+      isRest = await this.probe();
+    } catch (e) {
+      log.warn('Re-probe failed:', e?.message || e);
+    }
+
+    const newProtocol = isRest ? 'rest' : 'xmds';
+    const changed = newProtocol !== previousProtocol;
+
+    if (changed) {
+      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 };
+    }
+
+    log.info(`Protocol unchanged: ${newProtocol}`);
+    return { client: null, protocol: newProtocol, changed: false };
+  }
+
+  /**
+   * Get the currently detected protocol.
+   * @returns {'rest'|'xmds'|null}
+   */
+  getProtocol() {
+    return this.protocol;
+  }
+}

package/src/protocol-detector.test.js

@@ -0,0 +1,244 @@
+/**
+ * ProtocolDetector Tests
+ *
+ * Tests CMS protocol auto-detection logic:
+ * - REST probing via RestClient.isAvailable()
+ * - Fallback to XMDS/SOAP when REST is unavailable
+ * - Forced protocol selection (bypass auto-detection)
+ * - Re-probing on connection errors
+ */
+
+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;
+  let MockXmdsClient;
+  let config;
+
+  beforeEach(() => {
+    config = {
+      cmsUrl: 'https://cms.example.com',
+      cmsKey: 'test-key',
+      hardwareKey: 'test-hw',
+    };
+
+    MockRestClient = vi.fn(function (cfg) {
+      this.config = cfg;
+      this.type = 'rest';
+    });
+    MockRestClient.isAvailable = vi.fn();
+    addCmsClientStubs(MockRestClient);
+
+    MockXmdsClient = vi.fn(function (cfg) {
+      this.config = cfg;
+      this.type = 'xmds';
+    });
+    addCmsClientStubs(MockXmdsClient);
+  });
+
+  // ── detect() ─────────────────────────────────────────────────────
+
+  describe('detect()', () => {
+    it('should detect REST when health endpoint returns 200', async () => {
+      MockRestClient.isAvailable.mockResolvedValue(true);
+
+      const detector = new ProtocolDetector('https://cms.example.com', MockRestClient, MockXmdsClient);
+      const { client, protocol } = await detector.detect(config);
+
+      expect(protocol).toBe('rest');
+      expect(client.type).toBe('rest');
+      expect(detector.getProtocol()).toBe('rest');
+      expect(MockRestClient.isAvailable).toHaveBeenCalledWith('https://cms.example.com', {
+        maxRetries: 0,
+        timeoutMs: 3000,
+      });
+    });
+
+    it('should fall back to XMDS when REST is unavailable', async () => {
+      MockRestClient.isAvailable.mockResolvedValue(false);
+
+      const detector = new ProtocolDetector('https://cms.example.com', MockRestClient, MockXmdsClient);
+      const { client, protocol } = await detector.detect(config);
+
+      expect(protocol).toBe('xmds');
+      expect(client.type).toBe('xmds');
+      expect(detector.getProtocol()).toBe('xmds');
+    });
+
+    it('should fall back to XMDS when probe throws', async () => {
+      MockRestClient.isAvailable.mockRejectedValue(new Error('Network error'));
+
+      const detector = new ProtocolDetector('https://cms.example.com', MockRestClient, MockXmdsClient);
+      // probe() will throw, but detect() should handle it
+      // Actually, isAvailable catches internally and returns false
+      // Let's test the direct throw case by mocking probe
+      const { client, protocol } = await detector.detect(config);
+
+      expect(protocol).toBe('xmds');
+      expect(client.type).toBe('xmds');
+    });
+
+    it('should use forced REST protocol without probing', async () => {
+      const detector = new ProtocolDetector('https://cms.example.com', MockRestClient, MockXmdsClient);
+      const { client, protocol } = await detector.detect(config, 'rest');
+
+      expect(protocol).toBe('rest');
+      expect(client.type).toBe('rest');
+      expect(MockRestClient.isAvailable).not.toHaveBeenCalled();
+    });
+
+    it('should use forced XMDS protocol without probing', async () => {
+      const detector = new ProtocolDetector('https://cms.example.com', MockRestClient, MockXmdsClient);
+      const { client, protocol } = await detector.detect(config, 'xmds');
+
+      expect(protocol).toBe('xmds');
+      expect(client.type).toBe('xmds');
+      expect(MockRestClient.isAvailable).not.toHaveBeenCalled();
+    });
+
+    it('should pass config to client constructor', async () => {
+      MockRestClient.isAvailable.mockResolvedValue(true);
+
+      const detector = new ProtocolDetector('https://cms.example.com', MockRestClient, MockXmdsClient);
+      const { client } = await detector.detect(config);
+
+      expect(MockRestClient).toHaveBeenCalledWith(config);
+      expect(client.config).toBe(config);
+    });
+
+    it('should use custom probe timeout', async () => {
+      MockRestClient.isAvailable.mockResolvedValue(true);
+
+      const detector = new ProtocolDetector('https://cms.example.com', MockRestClient, MockXmdsClient, {
+        probeTimeoutMs: 5000,
+      });
+      await detector.detect(config);
+
+      expect(MockRestClient.isAvailable).toHaveBeenCalledWith('https://cms.example.com', {
+        maxRetries: 0,
+        timeoutMs: 5000,
+      });
+    });
+
+    it('should record lastProbeTime after detection', async () => {
+      MockRestClient.isAvailable.mockResolvedValue(true);
+
+      const detector = new ProtocolDetector('https://cms.example.com', MockRestClient, MockXmdsClient);
+      expect(detector.lastProbeTime).toBe(0);
+
+      await detector.detect(config);
+
+      expect(detector.lastProbeTime).toBeGreaterThan(0);
+      expect(detector.lastProbeTime).toBeLessThanOrEqual(Date.now());
+    });
+  });
+
+  // ── reprobe() ────────────────────────────────────────────────────
+
+  describe('reprobe()', () => {
+    it('should detect protocol change from XMDS to REST', async () => {
+      MockRestClient.isAvailable.mockResolvedValueOnce(false); // initial detect
+      const detector = new ProtocolDetector('https://cms.example.com', MockRestClient, MockXmdsClient);
+      await detector.detect(config);
+      expect(detector.getProtocol()).toBe('xmds');
+
+      MockRestClient.isAvailable.mockResolvedValueOnce(true); // reprobe
+      const { client, protocol, changed } = await detector.reprobe(config);
+
+      expect(changed).toBe(true);
+      expect(protocol).toBe('rest');
+      expect(client.type).toBe('rest');
+      expect(detector.getProtocol()).toBe('rest');
+    });
+
+    it('should detect protocol change from REST to XMDS', async () => {
+      MockRestClient.isAvailable.mockResolvedValueOnce(true); // initial detect
+      const detector = new ProtocolDetector('https://cms.example.com', MockRestClient, MockXmdsClient);
+      await detector.detect(config);
+      expect(detector.getProtocol()).toBe('rest');
+
+      MockRestClient.isAvailable.mockResolvedValueOnce(false); // reprobe
+      const { client, protocol, changed } = await detector.reprobe(config);
+
+      expect(changed).toBe(true);
+      expect(protocol).toBe('xmds');
+      expect(client.type).toBe('xmds');
+      expect(detector.getProtocol()).toBe('xmds');
+    });
+
+    it('should return changed=false when protocol is unchanged', async () => {
+      MockRestClient.isAvailable.mockResolvedValueOnce(true); // initial detect
+      const detector = new ProtocolDetector('https://cms.example.com', MockRestClient, MockXmdsClient);
+      await detector.detect(config);
+
+      MockRestClient.isAvailable.mockResolvedValueOnce(true); // reprobe (same)
+      const { client, protocol, changed } = await detector.reprobe(config);
+
+      expect(changed).toBe(false);
+      expect(protocol).toBe('rest');
+      expect(client).toBeNull(); // No new client when unchanged
+    });
+
+    it('should update lastProbeTime on reprobe', async () => {
+      MockRestClient.isAvailable.mockResolvedValue(true);
+      const detector = new ProtocolDetector('https://cms.example.com', MockRestClient, MockXmdsClient);
+      await detector.detect(config);
+      const firstProbe = detector.lastProbeTime;
+
+      // Small delay to ensure different timestamp
+      await new Promise(r => setTimeout(r, 5));
+
+      await detector.reprobe(config);
+      expect(detector.lastProbeTime).toBeGreaterThanOrEqual(firstProbe);
+    });
+  });
+
+  // ── getProtocol() ────────────────────────────────────────────────
+
+  describe('getProtocol()', () => {
+    it('should return null before detection', () => {
+      const detector = new ProtocolDetector('https://cms.example.com', MockRestClient, MockXmdsClient);
+      expect(detector.getProtocol()).toBeNull();
+    });
+
+    it('should return detected protocol after detect()', async () => {
+      MockRestClient.isAvailable.mockResolvedValue(true);
+      const detector = new ProtocolDetector('https://cms.example.com', MockRestClient, MockXmdsClient);
+      await detector.detect(config);
+      expect(detector.getProtocol()).toBe('rest');
+    });
+  });
+
+  // ── probe() ──────────────────────────────────────────────────────
+
+  describe('probe()', () => {
+    it('should call RestClient.isAvailable with correct URL and timeout', async () => {
+      MockRestClient.isAvailable.mockResolvedValue(true);
+      const detector = new ProtocolDetector('https://cms.example.com', MockRestClient, MockXmdsClient);
+      const result = await detector.probe();
+
+      expect(result).toBe(true);
+      expect(MockRestClient.isAvailable).toHaveBeenCalledWith('https://cms.example.com', {
+        maxRetries: 0,
+        timeoutMs: 3000,
+      });
+    });
+
+    it('should return false when REST is unavailable', async () => {
+      MockRestClient.isAvailable.mockResolvedValue(false);
+      const detector = new ProtocolDetector('https://cms.example.com', MockRestClient, MockXmdsClient);
+      const result = await detector.probe();
+
+      expect(result).toBe(false);
+    });
+  });
+});

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
@@ -526,7 +526,13 @@ export class RestClient {
         (window.electronAPI?.isElectron || window.location.hostname === 'localhost');
       const base = isProxy ? '' : cmsUrl.replace(/\/+$/, '');
       const url = `${base}${PLAYER_API}/health`;
-      const response = await fetchWithRetry(url, { method: 'GET' }, retryOptions || { maxRetries: 0 });
+      const timeoutMs = retryOptions?.timeoutMs || 3000;
+      const fetchOptions = { method: 'GET' };
+      // Apply timeout via AbortSignal (short timeout avoids delaying startup)
+      if (typeof AbortSignal !== 'undefined' && AbortSignal.timeout) {
+        fetchOptions.signal = AbortSignal.timeout(timeoutMs);
+      }
+      const response = await fetchWithRetry(url, fetchOptions, retryOptions || { maxRetries: 0 });
       if (!response.ok) return false;
       const data = await response.json();
       return data.version === 2 && data.status === 'ok';

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
  *