@xiboplayer/xmds 0.1.0

package/docs/README.md

@@ -0,0 +1,60 @@
+# @xiboplayer/xmds Documentation
+
+**XMDS (XML-based Media Distribution Service) SOAP client.**
+
+## Overview
+
+SOAP client for Xibo CMS communication:
+
+- Display registration
+- Content synchronization
+- File downloads
+- Proof of play submission
+- Log reporting
+
+## Installation
+
+```bash
+npm install @xiboplayer/xmds
+```
+
+## Usage
+
+```javascript
+import { XMDSClient } from '@xiboplayer/xmds';
+
+const client = new XMDSClient({
+  cmsUrl: 'https://cms.example.com',
+  serverKey: 'abc123',
+  hardwareKey: 'def456'
+});
+
+// Register display
+await client.registerDisplay();
+
+// Get required files
+const files = await client.requiredFiles();
+
+// Download file
+const blob = await client.getFile(fileId, fileType);
+```
+
+## SOAP Methods
+
+- `RegisterDisplay` - Register/verify display
+- `RequiredFiles` - Get content to download
+- `GetFile` - Download media file
+- `SubmitStats` - Send proof of play
+- `SubmitLog` - Report errors
+
+## Dependencies
+
+- `@xiboplayer/utils` - Logger
+
+## Related Packages
+
+- [@xiboplayer/core](../../core/docs/) - Player core
+
+---
+
+**Package Version**: 1.0.0

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@xiboplayer/xmds",
+  "version": "0.1.0",
+  "description": "XMDS SOAP client for Xibo CMS communication",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./xmds": "./src/xmds.js"
+  },
+  "dependencies": {
+    "@xiboplayer/utils": "0.1.0"
+  },
+  "devDependencies": {
+    "vitest": "^2.0.0"
+  },
+  "keywords": [
+    "xibo",
+    "digital-signage",
+    "xmds",
+    "soap",
+    "cms"
+  ],
+  "author": "Pau Aliagas <linuxnow@gmail.com>",
+  "license": "AGPL-3.0-or-later",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xibo-players/xiboplayer.git",
+    "directory": "packages/xmds"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  }
+}

package/src/index.js

@@ -0,0 +1,4 @@
+// @xiboplayer/xmds - XMDS clients (REST and SOAP)
+export { RestClient } from './rest-client.js';
+export { XmdsClient } from './xmds-client.js';
+export { parseScheduleResponse } from './schedule-parser.js';

package/src/rest-client.js

@@ -0,0 +1,342 @@
+/**
+ * REST transport client for Xibo CMS.
+ *
+ * Uses the /pwa REST API endpoints with JSON payloads and ETag caching.
+ * Lighter than SOAP — ~30% smaller payloads, standard HTTP semantics.
+ *
+ * Protocol: https://github.com/linuxnow/xibo_players_docs
+ */
+import { createLogger, fetchWithRetry } from '@xiboplayer/utils';
+import { parseScheduleResponse } from './schedule-parser.js';
+
+const log = createLogger('REST');
+
+export class RestClient {
+  constructor(config) {
+    this.config = config;
+    this.schemaVersion = 7;
+    this.retryOptions = config.retryOptions || { maxRetries: 2, baseDelayMs: 2000 };
+
+    // ETag-based HTTP caching
+    this._etags = new Map();         // endpoint → ETag string
+    this._responseCache = new Map(); // endpoint → cached parsed response
+
+    log.info('Using REST transport');
+  }
+
+  // ─── Transport helpers ──────────────────────────────────────────
+
+  /**
+   * Get the REST API base URL.
+   * Falls back to /pwa path relative to the CMS address.
+   */
+  getRestBaseUrl() {
+    const base = this.config.restApiUrl || `${this.config.cmsAddress}/pwa`;
+    return base.replace(/\/+$/, '');
+  }
+
+  /**
+   * Make a REST GET request with optional ETag caching.
+   * Returns the parsed JSON body, or cached data on 304.
+   */
+  async restGet(path, queryParams = {}) {
+    const url = new URL(`${this.getRestBaseUrl()}${path}`);
+    url.searchParams.set('serverKey', this.config.cmsKey);
+    url.searchParams.set('hardwareKey', this.config.hardwareKey);
+    url.searchParams.set('v', String(this.schemaVersion));
+    for (const [key, value] of Object.entries(queryParams)) {
+      url.searchParams.set(key, String(value));
+    }
+
+    const cacheKey = path;
+    const headers = {};
+    const cachedEtag = this._etags.get(cacheKey);
+    if (cachedEtag) {
+      headers['If-None-Match'] = cachedEtag;
+    }
+
+    log.debug(`GET ${path}`, queryParams);
+
+    const response = await fetchWithRetry(url.toString(), {
+      method: 'GET',
+      headers,
+    }, this.retryOptions);
+
+    // 304 Not Modified — return cached response
+    if (response.status === 304) {
+      const cached = this._responseCache.get(cacheKey);
+      if (cached) {
+        log.debug(`${path} → 304 (using cache)`);
+        return cached;
+      }
+      // Cache miss despite 304 — fall through to fetch fresh
+    }
+
+    if (!response.ok) {
+      const errorBody = await response.text().catch(() => '');
+      throw new Error(`REST GET ${path} failed: ${response.status} ${response.statusText} ${errorBody}`);
+    }
+
+    // Store ETag for future requests
+    const etag = response.headers.get('ETag');
+    if (etag) {
+      this._etags.set(cacheKey, etag);
+    }
+
+    const contentType = response.headers.get('Content-Type') || '';
+    let data;
+    if (contentType.includes('application/json')) {
+      data = await response.json();
+    } else {
+      // XML or HTML — return raw text
+      data = await response.text();
+    }
+
+    // Cache parsed response for 304 reuse
+    this._responseCache.set(cacheKey, data);
+    return data;
+  }
+
+  /**
+   * Make a REST POST/PUT request with JSON body.
+   * Returns the parsed JSON response.
+   */
+  async restSend(method, path, body = {}) {
+    const url = new URL(`${this.getRestBaseUrl()}${path}`);
+    url.searchParams.set('v', String(this.schemaVersion));
+
+    log.debug(`${method} ${path}`);
+
+    const response = await fetchWithRetry(url.toString(), {
+      method,
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        serverKey: this.config.cmsKey,
+        hardwareKey: this.config.hardwareKey,
+        ...body,
+      }),
+    }, this.retryOptions);
+
+    if (!response.ok) {
+      const errorBody = await response.text().catch(() => '');
+      throw new Error(`REST ${method} ${path} failed: ${response.status} ${response.statusText} ${errorBody}`);
+    }
+
+    const contentType = response.headers.get('Content-Type') || '';
+    if (contentType.includes('application/json')) {
+      return await response.json();
+    }
+    return await response.text();
+  }
+
+  // ─── Public API ─────────────────────────────────────────────────
+
+  /**
+   * RegisterDisplay - authenticate and get settings
+   * POST /register → JSON with display settings
+   */
+  async registerDisplay() {
+    const os = typeof navigator !== 'undefined'
+      ? `${navigator.platform} ${navigator.userAgent}`
+      : 'unknown';
+
+    const json = await this.restSend('POST', '/register', {
+      displayName: this.config.displayName,
+      clientType: 'chromeOS',
+      clientVersion: '0.1.0',
+      clientCode: 1,
+      operatingSystem: os,
+      macAddress: this.config.macAddress || 'n/a',
+      xmrChannel: this.config.xmrChannel,
+      xmrPubKey: '',
+    });
+
+    return this._parseRegisterDisplayJson(json);
+  }
+
+  /**
+   * Parse REST JSON RegisterDisplay response into the same format as SOAP.
+   */
+  _parseRegisterDisplayJson(json) {
+    // Handle both direct object and wrapped {display: ...} forms
+    const display = json.display || json;
+    const attrs = display['@attributes'] || {};
+    const code = attrs.code || display.code;
+    const message = attrs.message || display.message || '';
+
+    if (code !== 'READY') {
+      return { code, message, settings: null };
+    }
+
+    const settings = {};
+    for (const [key, value] of Object.entries(display)) {
+      if (key === '@attributes' || key === 'commands' || key === 'file') continue;
+      settings[key] = typeof value === 'object' ? JSON.stringify(value) : String(value);
+    }
+
+    const checkRf = attrs.checkRf || '';
+    const checkSchedule = attrs.checkSchedule || '';
+
+    // Extract sync group config if present (multi-display sync coordination)
+    // syncGroup: "lead" if this display is leader, or leader's LAN IP if follower
+    const syncConfig = display.syncGroup ? {
+      syncGroup: String(display.syncGroup),
+      syncPublisherPort: parseInt(display.syncPublisherPort || '9590', 10),
+      syncSwitchDelay: parseInt(display.syncSwitchDelay || '750', 10),
+      syncVideoPauseDelay: parseInt(display.syncVideoPauseDelay || '100', 10),
+      isLead: String(display.syncGroup) === 'lead',
+    } : null;
+
+    return { code, message, settings, checkRf, checkSchedule, syncConfig };
+  }
+
+  /**
+   * RequiredFiles - get list of files to download
+   * GET /requiredFiles → JSON file manifest (with ETag caching)
+   */
+  async requiredFiles() {
+    const json = await this.restGet('/requiredFiles');
+    return this._parseRequiredFilesJson(json);
+  }
+
+  /**
+   * Parse REST JSON RequiredFiles into the same array format as SOAP.
+   */
+  _parseRequiredFilesJson(json) {
+    const files = [];
+    let fileList = json.file || [];
+
+    // Normalize single item to array
+    if (!Array.isArray(fileList)) {
+      fileList = [fileList];
+    }
+
+    for (const f of fileList) {
+      const attrs = f['@attributes'] || f;
+      const path = attrs.path || null;
+      files.push({
+        type: attrs.type || null,
+        id: attrs.id || null,
+        size: parseInt(attrs.size || '0'),
+        md5: attrs.md5 || null,
+        download: attrs.download || null,
+        path,
+        code: attrs.code || null,
+        layoutid: attrs.layoutid || null,
+        regionid: attrs.regionid || null,
+        mediaid: attrs.mediaid || null,
+      });
+    }
+
+    return files;
+  }
+
+  /**
+   * Schedule - get layout schedule
+   * GET /schedule → XML (preserved for layout parser compatibility, with ETag caching)
+   */
+  async schedule() {
+    const xml = await this.restGet('/schedule');
+    return parseScheduleResponse(xml);
+  }
+
+  /**
+   * GetResource - get rendered widget HTML
+   * GET /getResource → HTML string
+   */
+  async getResource(layoutId, regionId, mediaId) {
+    return this.restGet('/getResource', {
+      layoutId: String(layoutId),
+      regionId: String(regionId),
+      mediaId: String(mediaId),
+    });
+  }
+
+  /**
+   * NotifyStatus - report current status
+   * PUT /status → JSON acknowledgement
+   * @param {Object} status - Status object with currentLayoutId, deviceName, etc.
+   */
+  async notifyStatus(status) {
+    // Enrich with storage estimate if available
+    if (typeof navigator !== 'undefined' && navigator.storage?.estimate) {
+      try {
+        const estimate = await navigator.storage.estimate();
+        status.availableSpace = estimate.quota - estimate.usage;
+        status.totalSpace = estimate.quota;
+      } catch (_) { /* storage estimate not supported */ }
+    }
+
+    // Add timezone if not already provided
+    if (!status.timeZone && typeof Intl !== 'undefined') {
+      status.timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    }
+
+    return this.restSend('PUT', '/status', {
+      statusData: status,
+    });
+  }
+
+  /**
+   * MediaInventory - report downloaded files
+   * POST /mediaInventory → JSON acknowledgement
+   */
+  async mediaInventory(inventoryXml) {
+    // Accept array (JSON-native) or string (XML) — send under the right key
+    const body = Array.isArray(inventoryXml)
+      ? { inventoryItems: inventoryXml }
+      : { inventory: inventoryXml };
+    return this.restSend('POST', '/mediaInventory', body);
+  }
+
+  /**
+   * BlackList - report broken media to CMS
+   *
+   * BlackList has no REST equivalent endpoint.
+   * Log a warning and return false.
+   */
+  async blackList(mediaId, type, reason) {
+    log.warn(`BlackList not available via REST (${type}/${mediaId}: ${reason})`);
+    return false;
+  }
+
+  /**
+   * SubmitLog - submit player logs to CMS
+   * POST /log → JSON acknowledgement
+   */
+  async submitLog(logXml) {
+    // Accept array (JSON-native) or string (XML) — send under the right key
+    const body = Array.isArray(logXml) ? { logs: logXml } : { logXml };
+    const result = await this.restSend('POST', '/log', body);
+    return result?.success === true;
+  }
+
+  /**
+   * SubmitScreenShot - submit screenshot to CMS
+   * POST /screenshot → JSON acknowledgement
+   */
+  async submitScreenShot(base64Image) {
+    const result = await this.restSend('POST', '/screenshot', {
+      screenshot: base64Image,
+    });
+    return result?.success === true;
+  }
+
+  /**
+   * SubmitStats - submit proof of play statistics
+   * POST /stats → JSON acknowledgement
+   */
+  async submitStats(statsXml) {
+    try {
+      // Accept array (JSON-native) or string (XML) — send under the right key
+      const body = Array.isArray(statsXml) ? { stats: statsXml } : { statXml: statsXml };
+      const result = await this.restSend('POST', '/stats', body);
+      const success = result?.success === true;
+      log.info(`SubmitStats result: ${success}`);
+      return success;
+    } catch (error) {
+      log.error('SubmitStats failed:', error);
+      throw error;
+    }
+  }
+}

package/src/schedule-parser.js

@@ -0,0 +1,172 @@
+/**
+ * Shared schedule XML parser used by both RestClient and XmdsClient.
+ *
+ * Both transports return the same XML structure for the Schedule endpoint,
+ * so the parsing logic lives here to avoid duplication.
+ */
+
+/**
+ * Parse criteria child elements from a layout/overlay element.
+ * Criteria are conditions that must be met for the item to display.
+ *
+ * XML format: <criteria metric="dayOfWeek" condition="equals" type="string">Monday</criteria>
+ *
+ * @param {Element} parentEl - Parent XML element containing <criteria> children
+ * @returns {Array<{metric: string, condition: string, type: string, value: string}>}
+ */
+function parseCriteria(parentEl) {
+  const criteria = [];
+  for (const criteriaEl of parentEl.querySelectorAll(':scope > criteria')) {
+    criteria.push({
+      metric: criteriaEl.getAttribute('metric') || '',
+      condition: criteriaEl.getAttribute('condition') || '',
+      type: criteriaEl.getAttribute('type') || 'string',
+      value: criteriaEl.textContent || ''
+    });
+  }
+  return criteria;
+}
+
+/**
+ * Parse Schedule XML response into a normalized schedule object.
+ *
+ * @param {string} xml - Raw XML string from CMS schedule endpoint
+ * @returns {Object} Parsed schedule with default, layouts, campaigns, overlays, actions, commands, dataConnectors
+ */
+export function parseScheduleResponse(xml) {
+  const parser = new DOMParser();
+  const doc = parser.parseFromString(xml, 'text/xml');
+
+  const schedule = {
+    default: null,
+    layouts: [],
+    campaigns: [],
+    overlays: [],
+    actions: [],
+    commands: [],
+    dataConnectors: []
+  };
+
+  const defaultEl = doc.querySelector('default');
+  if (defaultEl) {
+    schedule.default = defaultEl.getAttribute('file');
+  }
+
+  // Parse campaigns (groups of layouts with shared priority)
+  for (const campaignEl of doc.querySelectorAll('campaign')) {
+    const campaign = {
+      id: campaignEl.getAttribute('id'),
+      priority: parseInt(campaignEl.getAttribute('priority') || '0'),
+      fromdt: campaignEl.getAttribute('fromdt'),
+      todt: campaignEl.getAttribute('todt'),
+      scheduleid: campaignEl.getAttribute('scheduleid'),
+      layouts: []
+    };
+
+    // Parse layouts within this campaign
+    for (const layoutEl of campaignEl.querySelectorAll('layout')) {
+      const fileId = layoutEl.getAttribute('file');
+      campaign.layouts.push({
+        id: String(fileId), // Normalized string ID for consistent type usage
+        file: fileId,
+        // Layouts in campaigns inherit timing from campaign level
+        fromdt: layoutEl.getAttribute('fromdt') || campaign.fromdt,
+        todt: layoutEl.getAttribute('todt') || campaign.todt,
+        scheduleid: campaign.scheduleid,
+        priority: campaign.priority, // Priority at campaign level
+        campaignId: campaign.id,
+        maxPlaysPerHour: parseInt(layoutEl.getAttribute('maxPlaysPerHour') || '0'),
+        isGeoAware: layoutEl.getAttribute('isGeoAware') === '1',
+        geoLocation: layoutEl.getAttribute('geoLocation') || '',
+        syncEvent: layoutEl.getAttribute('syncEvent') === '1',
+        shareOfVoice: parseInt(layoutEl.getAttribute('shareOfVoice') || '0'),
+        criteria: parseCriteria(layoutEl)
+      });
+    }
+
+    schedule.campaigns.push(campaign);
+  }
+
+  // Parse standalone layouts (not in campaigns)
+  for (const layoutEl of doc.querySelectorAll('schedule > layout')) {
+    const fileId = layoutEl.getAttribute('file');
+    schedule.layouts.push({
+      id: String(fileId), // Normalized string ID for consistent type usage
+      file: fileId,
+      fromdt: layoutEl.getAttribute('fromdt'),
+      todt: layoutEl.getAttribute('todt'),
+      scheduleid: layoutEl.getAttribute('scheduleid'),
+      priority: parseInt(layoutEl.getAttribute('priority') || '0'),
+      campaignId: null, // Standalone layout
+      maxPlaysPerHour: parseInt(layoutEl.getAttribute('maxPlaysPerHour') || '0'),
+      isGeoAware: layoutEl.getAttribute('isGeoAware') === '1',
+      geoLocation: layoutEl.getAttribute('geoLocation') || '',
+      syncEvent: layoutEl.getAttribute('syncEvent') === '1',
+      shareOfVoice: parseInt(layoutEl.getAttribute('shareOfVoice') || '0'),
+      criteria: parseCriteria(layoutEl)
+    });
+  }
+
+  // Parse overlay layouts (appear on top of main layouts)
+  const overlaysContainer = doc.querySelector('overlays');
+  if (overlaysContainer) {
+    for (const overlayEl of overlaysContainer.querySelectorAll('overlay')) {
+      const fileId = overlayEl.getAttribute('file');
+      schedule.overlays.push({
+        id: String(fileId), // Normalized string ID for consistent type usage
+        duration: parseInt(overlayEl.getAttribute('duration') || '60'),
+        file: fileId,
+        fromDt: overlayEl.getAttribute('fromdt'),
+        toDt: overlayEl.getAttribute('todt'),
+        priority: parseInt(overlayEl.getAttribute('priority') || '0'),
+        scheduleId: overlayEl.getAttribute('scheduleid'),
+        isGeoAware: overlayEl.getAttribute('isGeoAware') === '1',
+        geoLocation: overlayEl.getAttribute('geoLocation') || '',
+        syncEvent: overlayEl.getAttribute('syncEvent') === '1',
+        maxPlaysPerHour: parseInt(overlayEl.getAttribute('maxPlaysPerHour') || '0'),
+        criteria: parseCriteria(overlayEl)
+      });
+    }
+  }
+
+  // Parse action events (scheduled triggers)
+  const actionsContainer = doc.querySelector('actions');
+  if (actionsContainer) {
+    for (const actionEl of actionsContainer.querySelectorAll('action')) {
+      schedule.actions.push({
+        actionType: actionEl.getAttribute('actionType') || '',
+        triggerCode: actionEl.getAttribute('triggerCode') || '',
+        layoutCode: actionEl.getAttribute('layoutCode') || '',
+        commandCode: actionEl.getAttribute('commandCode') || '',
+        duration: parseInt(actionEl.getAttribute('duration') || '0'),
+        fromDt: actionEl.getAttribute('fromdt'),
+        toDt: actionEl.getAttribute('todt'),
+        priority: parseInt(actionEl.getAttribute('priority') || '0'),
+        scheduleId: actionEl.getAttribute('scheduleid'),
+        isGeoAware: actionEl.getAttribute('isGeoAware') === '1',
+        geoLocation: actionEl.getAttribute('geoLocation') || ''
+      });
+    }
+  }
+
+  // Parse server commands (remote control)
+  for (const cmdEl of doc.querySelectorAll('schedule > command')) {
+    schedule.commands.push({
+      code: cmdEl.getAttribute('command') || '',
+      date: cmdEl.getAttribute('date') || ''
+    });
+  }
+
+  // Parse data connectors (real-time data sources for widgets)
+  for (const dcEl of doc.querySelectorAll('dataconnector')) {
+    schedule.dataConnectors.push({
+      id: dcEl.getAttribute('id') || '',
+      dataConnectorId: dcEl.getAttribute('dataConnectorId') || '',
+      dataKey: dcEl.getAttribute('dataKey') || '',
+      url: dcEl.getAttribute('url') || '',
+      updateInterval: parseInt(dcEl.getAttribute('updateInterval') || '300', 10)
+    });
+  }
+
+  return schedule;
+}