senza-sdk 4.4.6 → 4.4.8

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "senza-sdk",
-    "version": "4.4.6",
+    "version": "4.4.8",
     "main": "./src/api.js",
     "description": "API for Senza application",
     "license": "MIT",
@@ -34,7 +34,7 @@
         "eslint-plugin-jest": "^28.11.0",
         "globals": "^16.0.0",
         "jest": "^30.2.0",
-        "jest-environment-jsdom" : "^30.2.0",
+        "jest-environment-jsdom": "^30.2.0",
         "jsdoc-to-markdown": "^7.1.1",
         "webpack": "^5.72.1",
         "webpack-cli": "^5.1.4"

package/src/implementation/api.js

@@ -20,6 +20,7 @@ let authToken;
 
 const API_VERSION = "1.0";
 let interfaceVersion;
+let uiReadyHasBeenCalled = false;
 
 /** @namespace auth
  *@example
@@ -262,6 +263,7 @@ export function isRunningE2E() {
 
 /** Call this API once after application startup, when the ui is ready to accept keys/events */
 export function uiReady() {
+    uiReadyHasBeenCalled = true;
     if (window.cefQuery) {
         window.cefQuery({
             request: "uiReady",
@@ -278,6 +280,13 @@ export function uiReady() {
     }
 }
 
+/**
+ * @private
+ */
+export function _isUiReady() {
+    return uiReadyHasBeenCalled;
+}
+
 import "./devHelper.js";
 
 /**

package/src/implementation/deviceManager.js

@@ -1,4 +1,4 @@
-import { DeviceManager as DeviceManagerInterface } from "../interface/deviceManager";
+import { DeviceManager as DeviceManagerInterface} from "../interface/deviceManager";
 import { getFCID, sdkLogger, getRestResponse } from "./utils";
 import { sessionInfo } from "./SessionInfo";
 
@@ -9,6 +9,186 @@ let wifi_status_last_update = 0;
 const WIFI_STATUS_CACHE_SECONDS = 5;
 const FACTORY_RESET_TIMEOUT_SECONDS = 5;
 
+const byteSize = str => new Blob([str]).size;
+
+/**
+ *  MessageChannel is not extended from the interface as its objects are only instantiated internally.
+ *  The implementation here needs to match the interface definition which exists purely for documentation.
+ */
+class MessageChannel extends EventTarget {
+    constructor(deviceManager, channelType) {
+        super();
+        switch (channelType) {
+        case deviceManager.DeviceMessageChannelType.SZE_HOST_APP:
+            this._type = deviceManager.DeviceMessageChannelType.SZE_HOST_APP;
+            this._description = "Message channel for bidirectional communication with the Senza Embedded device's host application";
+            this._capabilities = {
+                send: true,
+                receive: true,
+                dataTypes: ["string"],
+                maxMessageSize: 60 * 1024 // 60KB - to account for SCTP default max message size of 64Kb minus the wrapping object overhead
+            };
+            break;
+        case deviceManager.DeviceMessageChannelType.USB_SERIAL:
+            this._type = deviceManager.DeviceMessageChannelType.USB_SERIAL;
+            this._description = "Message channel for sending messages to the device's USB serial interface";
+            this._capabilities = {
+                send: true,
+                receive: false,
+                dataTypes: ["string"],
+                maxMessageSize: 60 * 1024 // 60KB
+            };
+            break;
+        default:
+            throw new Error("Invalid channel type");
+        }
+
+        this._open = true;
+        this._manager = deviceManager;
+    }
+
+    /**
+     * Calls EventTarget's addEventListener after checking if channel is open
+     */
+    addEventListener(type, callback) {
+        if (!this._open) throw new Error("Channel is closed");
+        EventTarget.prototype.addEventListener.call(this, type, callback);
+    }
+
+    /**
+     * Calls EventTarget's removeEventListener after checking if channel is open
+     */
+    removeEventListener(type, callback) {
+        if (!this._open) throw new Error("Channel is closed");
+        EventTarget.prototype.removeEventListener.call(this, type, callback);
+    }
+
+    /**
+     * Marks channel as closed and not usable anymore. Also removes it from the DeviceManager's createdChannels map.
+     */
+    dispose() {
+        if (!this._open) throw new Error("Channel is closed");
+        this._open = false;
+        if (this._manager && typeof this._manager._removeChannel === "function") {
+            this._manager._removeChannel(this._type);
+        }
+    }
+
+    /**
+     * Get the type of this message channel.
+     * @returns {DeviceMessageChannelType} The channel type
+     */
+    get type() {
+        if (!this._open) throw new Error("Channel is closed");
+        return this._type;
+    }
+
+    /**
+     * Get the description of this message channel.
+     * @returns {string} The channel description
+     */
+    get description() {
+        if (!this._open) throw new Error("Channel is closed");
+        return this._description;
+    }
+
+    /**
+     * Get the capabilities of this message channel.
+     * @returns {Object} The capabilities object containing send/receive flags, supported data types, etc.
+     */
+    get capabilities() {
+        if (!this._open) throw new Error("Channel is closed");
+        return this._capabilities;
+    }
+
+    /**
+     * @private
+     * Performs checks to see if a message can be sent through this channel.
+     * @param {*} message The message to check
+     */
+    _checkMessageBeforeSend(message) {
+        if (!this._open) throw new Error("Channel is closed");
+        if (typeof window === "undefined" || typeof window.cefQuery !== "function") {
+            throw new Error("cefQuery is not available");
+        }
+        if (typeof message !== "string" && !(message instanceof String)) {
+            throw new Error("message must be a string");
+        }
+        // Enforce maxMessageSize limit
+        const maxSize = this.capabilities.maxMessageSize;
+        const messageSize = byteSize(message);
+        if (messageSize > maxSize) {
+            throw new Error(`Message size (${messageSize} bytes) exceeds maximum allowed size (${maxSize} bytes)`);
+        }
+    }
+}
+
+/**
+ * Senza Embedded Host App Message Channel
+ */
+class SzeHostAppMessageChannel extends MessageChannel {
+    _docListener = (e) => {
+        const logger = sdkLogger.withFields({ "FCID": e?.detail?.fcid });
+        logger.log("Got hs/deviceMsgSzeHostApp", JSON.stringify(e?.detail));
+
+        const event = new Event("message");
+        event.message = e?.detail?.message || "";
+        this.dispatchEvent(event);
+    };
+
+    constructor(deviceManager) {
+        super(deviceManager, deviceManager.DeviceMessageChannelType.SZE_HOST_APP);
+        // Listen for device host app to web app messages and forward to EventTarget listeners
+        if (typeof document !== "undefined") {
+            document.addEventListener("hs/deviceMsgSzeHostApp", this._docListener);
+        }
+    }
+
+    async sendMessage(message) {
+        this._checkMessageBeforeSend(message);
+        const tc_message = { type: "deviceMsgSzeHostApp", message: message };
+        const request = {
+            target: "TC",
+            waitForResponse: false,
+            message: JSON.stringify(tc_message)
+        };
+        return new Promise((resolve, reject) => {
+            window.cefQuery({
+                request: JSON.stringify(request),
+                persistent: false,
+                onSuccess: () => {
+                    resolve();
+                },
+                onFailure: (code, msg) => {
+                    reject(new Error(`Request failed: ${code} ${msg}`));
+                }
+            });
+        });
+    }
+
+    dispose() {
+        if (typeof document !== "undefined") {
+            document.removeEventListener("hs/deviceMsgSzeHostApp", this._docListener);
+        }
+        super.dispose();
+    }
+}
+
+/**
+ * USB Serial Message Channel implementation
+ */
+class UsbSerialMessageChannel extends MessageChannel {
+    constructor(deviceManager) {
+        super(deviceManager, deviceManager.DeviceMessageChannelType.USB_SERIAL);
+    }
+
+    async sendMessage(message) {
+        this._checkMessageBeforeSend(message);
+        // Use the existing sendDataToDevice functionality
+        return getDeviceManagerInstance().sendDataToDevice(message);
+    }
+}
+
 async function getWifiApData() {
     // Wi-Fi access point data is static, so it needs to be retrieved only once
     if (!wifi_ap_data) {
@@ -38,6 +218,13 @@ class DeviceManager extends DeviceManagerInterface {
 
     constructor() {
         super();
+        this.availableMessageChannels = [
+            // Future enhancement: add available channels based on cfg or some device info
+            this.DeviceMessageChannelType.SZE_HOST_APP,
+            this.DeviceMessageChannelType.USB_SERIAL
+        ];
+        // Track created channels in a map to enforce one-per-type limit, i.e. only one SZE_HOST_APP channel at a time
+        this.createdChannels = new Map();
     }
 
     get deviceInfo() {
@@ -202,10 +389,67 @@ class DeviceManager extends DeviceManagerInterface {
         await Promise.all([getWifiApData(), getWifiStatus()]);
         return { ...wifi_ap_data, ...wifi_status };
     }
+
+    /**
+     * Returns a list of available message channels for the device.
+     * @returns {DeviceMessageChannelType[]} An array of DeviceMessageChannelType values representing the available message channels.
+     */
+    getAvailableMessageChannels() {
+        return this.availableMessageChannels || [];
+    }
+
+    /**
+     * Create a message channel of the specified type.
+     * Only one channel of each type can be created at a time.
+     * @param {DeviceMessageChannelType} type The type of message channel to create.
+     * @returns {MessageChannel} A MessageChannel object representing the created message channel.
+     * @throws {Error} If the specified type is not supported or already exists.
+     */
+    createMessageChannel(type) {
+        const channelType = this.availableMessageChannels.find(c => c === type);
+        const availableTypes = this.availableMessageChannels.join(", ");
+        if (!channelType) {
+            throw new Error(`Unsupported channel type: ${type}. Available types: ${availableTypes}`);
+        }
+        // Check if a channel of this type already exists
+        if (this.createdChannels.has(type)) {
+            throw new Error(`A message channel of type '${type}' already exists. Only one channel per type is allowed.`);
+        }
+        // Create channel implementation based on type
+        let channel;
+        if (type === this.DeviceMessageChannelType.SZE_HOST_APP) {
+            channel = new SzeHostAppMessageChannel(this);
+        } else if (type === this.DeviceMessageChannelType.USB_SERIAL) {
+            channel = new UsbSerialMessageChannel(this);
+        }
+        // else channel type is unsupported, but is already checked above
+
+        this.createdChannels.set(type, channel);
+        return channel;
+    }
+
+    /**
+     * Remove a message channel of the specified type.
+     * @private
+     * @param {DeviceMessageChannelType} type The type of message channel to remove.
+     */
+    _removeChannel(type) {
+        if (!this.createdChannels || !this.createdChannels.has(type)) {
+            throw new Error(`No channel of type '${type}' exists.`);
+        }
+        this.createdChannels.delete(type);
+    }
 }
 
-/**
+// Create the singleton instance
+const deviceManagerInstance = new DeviceManager();
+
+// Function to get the singleton instance (for forward reference)
+function getDeviceManagerInstance() {
+    return deviceManagerInstance;
+}
 
+/**
  * @module
  * @example
  * import { deviceManager } from "senza-sdk";
@@ -214,6 +458,13 @@ class DeviceManager extends DeviceManagerInterface {
  * await deviceManager.clearWifi();
  * deviceManager.reboot();
  *
+ * // Message channels
+ * const channels = deviceManager.getAvailableMessageChannels();
+ * const channel = deviceManager.createMessageChannel(deviceManager.DeviceMessageChannelType.SZE_HOST_APP);
+ * channel.addEventListener('message', (event) => {
+ *     console.log(`Received: ${event.message}`);
+ * });
+ *
  * @return {DeviceManager} pointer to the DeviceManager singleton
  */
-export const deviceManager = new DeviceManager();
+export const deviceManager = deviceManagerInstance;

package/src/implementation/lifecycle.js

@@ -1,5 +1,5 @@
 import { Lifecycle as LifecycleInterface } from "../interface/lifecycle.js";
-import { getPlatformInfo } from "./api.js";
+import { getPlatformInfo, _isUiReady } from "./api.js";
 import { alarmManager } from "./alarmManager.js";
 import {
     getFCID,
@@ -108,6 +108,8 @@ class Lifecycle extends LifecycleInterface {
          */
         this._isSuspendTriggeredByTimer = false;
 
+        this._isInTransitionToSuspended = false;
+
     }
 
     /**
@@ -705,7 +707,6 @@ class Lifecycle extends LifecycleInterface {
         return this._inTransitionToForeground || this._inTransitionToBackground || this._inTransitionToStandby;
     }
 
-
     getState() {
         if (window.cefQuery) {
             return new Promise((resolve, reject) => {
@@ -727,6 +728,13 @@ class Lifecycle extends LifecycleInterface {
     }
 
     moveToForeground() {
+        if (!_isUiReady()) {
+            sdkLogger.warn("lifecycle moveToForeground: UI is not ready yet. Make sure to call senza.uiReady() before calling lifecycle.moveToForeground()");
+        }
+        if (this._isInTransitionToSuspended) {
+            sdkLogger.error("lifecycle moveToForeground: Currently in transition to suspend, cannot move to foreground");
+            return Promise.resolve(false);
+        }
         // Reset activity timestamp when moving to foreground
         this._lastActivityTimestamp = Date.now();
 
@@ -911,7 +919,10 @@ class Lifecycle extends LifecycleInterface {
     }
 
     moveToBackground(isTriggeredByTimer = false) {
-
+        if (this._isInTransitionToSuspended) {
+            sdkLogger.error("lifecycle moveToBackground: Currently in transition to suspend, cannot move to background");
+            return Promise.resolve(false);
+        }
         // If the background transition is triggered by the auto background timer, set the flag
         this._isBackgroundTriggeredByTimer = isTriggeredByTimer;
 
@@ -1073,6 +1084,7 @@ class Lifecycle extends LifecycleInterface {
             return Promise.reject(errorMsg);
         }
 
+        this._isInTransitionToSuspended = true;
         // Report metrics for time between background and suspend
         const duration = (Date.now() - this._backgroundTimestamp) / 1000;
 
@@ -1109,6 +1121,7 @@ class Lifecycle extends LifecycleInterface {
                         resolve(true);
                     },
                     onFailure: (code, msg) => {
+                        this._isInTransitionToSuspended = false;
                         logger.error(`moveToSuspended failed: ${code} ${msg}`);
                         reject(new SenzaError(code, msg));
                     }

package/src/implementation/remotePlayer.js

@@ -15,7 +15,7 @@ import {
     isAppVersionAboveOrEqual
 } from "./utils";
 import { lifecycle } from "./lifecycle";
-import { writeLicenseResponse } from "./api";
+import { writeLicenseResponse, _isUiReady } from "./api";
 import { mergeAutoTranslationLanguages } from "./subtitlesUtils";
 
 // This is the delay we wait for to detect if the web application is seeking multiple times
@@ -736,6 +736,9 @@ class RemotePlayer extends RemotePlayerInterface {
      *
      * */
     async load(url, position) {
+        if (!_isUiReady()) {
+            sdkLogger.warn("remotePlayer load: UI is not ready yet. Make sure to call senza.uiReady() before calling remotePlayer.load()");
+        }
         return this._load(url, position);
     }
 
@@ -942,6 +945,9 @@ class RemotePlayer extends RemotePlayerInterface {
      * @throws {RemotePlayerError} error object contains code & msg
      */
     play(autoTune = false) {
+        if (!_isUiReady()) {
+            sdkLogger.warn("remotePlayer play: UI is not ready yet. Make sure to call senza.uiReady() before calling remotePlayer.play()");
+        }
         if (!this._isInitialized) {
             throw new RemotePlayerError(6500, "Cannot call play() if remote player is not initialized");
         }

package/src/interface/deviceManager.js

@@ -4,6 +4,15 @@ import { sdkLogger, noop } from "./utils.js";
  * DeviceManager is a singleton class that manages the device.<br>
  */
 export class DeviceManager extends EventTarget {
+    /**
+     * @typedef {Object} DeviceMessageChannelType Defines the types of message channels available for communication with the device.
+     * @property {string} SZE_HOST_APP Message channel for bidirectional communication with the Senza Embedded device host application.
+     * @property {string} USB_SERIAL Message channel for sending messages to the device's USB serial interface.
+     */
+    DeviceMessageChannelType = Object.freeze({
+        SZE_HOST_APP: "SZE_HOST_APP",
+        USB_SERIAL: "USB_SERIAL"
+    });
 
     /**
      * @property {object} DeviceInfo
@@ -97,8 +106,117 @@ export class DeviceManager extends EventTarget {
     async getWifiInfo() {
         return Promise.resolve({});
     }
+
+    /**
+     * Returns a list of available message channels for the device.
+     * @returns {DeviceMessageChannelType[]} An array of DeviceMessageChannelType objects representing the available message channels.
+     * @example
+     * import { deviceManager } from "senza-sdk";
+     * const channelType = deviceManager.getAvailableMessageChannels();
+     * channels.forEach(channel => {
+     *     console.log(`Channel Type: ${channel.type}, Description: ${channel.description}`);
+     * });
+     */
+    getAvailableMessageChannels() {
+        return noop("DeviceManager.getAvailableMessageChannels");
+    }
+
+    /**
+     * Create a message channel of the specified type.
+     * Only one channel of each type can be created at a time.
+     * @param {DeviceMessageChannelType} type The type of message channel to create.
+     * @returns {MessageChannel} A MessageChannel object representing the created message channel.
+     * @throws {Error} If the specified type is not supported or already exists.
+     * @example
+     * import { deviceManager } from "senza-sdk";
+     * const channel = deviceManager.createMessageChannel(deviceManager.DeviceMessageChannelType.SZE_HOST_APP);
+     * channel.sendMessage("Hello Senza Embedded host application");
+     */
+    createMessageChannel(type) {
+        return noop("DeviceManager.createMessageChannel", type);
+    }
 }
 
+/**
+ * MessageChannel represents a communication channel to the device.
+ * Objects of this type are created via DeviceManager.createMessageChannel().
+ * Available channel types depend on the device and are queried at runtime via DeviceManager.getAvailableMessageChannels().
+ * <pre>
+ *   type: DeviceMessageChannelType.SZE_HOST_APP
+ *   description: Message channel for bidirectional communication ...
+ *   capabilities:
+ *      send: true
+ *      receive: true
+ *      dataTypes: [string] // string messages are supported using the sendMessage() method and 'message' event
+ *      maxMessageSize: 61440
+ * </pre>
+ */
+// eslint-disable-next-line no-unused-vars
+class MessageChannel extends EventTarget {
+    /**
+     * Send a string message to the device via this message channel.
+     * @param {string} message The message to send.
+     * @returns {Promise<void>} Promise that resolves when message is sent
+     * @example
+     * const channel = deviceManager.createMessageChannel(DeviceMessageChannelType.SZE_HOST_APP);
+     * await channel.sendMessage("Hello Senza Embedded host application");
+     */
+    sendMessage() {
+        return noop("MessageChannel.sendMessage");
+    }
+
+    /**
+     * Get the type of this message channel.
+     * @returns {DeviceMessageChannelType} The channel type
+     */
+    get type() {
+        return noop("MessageChannel.get() type");
+    }
+
+    /**
+     * Get the description of this message channel.
+     * @returns {string} The channel description
+     */
+    get description() {
+        return noop("MessageChannel.get() description");
+    }
+
+    /**
+     * Get the capabilities of this message channel.
+     * @returns {Object} The capabilities object containing send/receive flags, supported data types, max message size.
+     */
+    get capabilities() {
+        return noop("MessageChannel.get() capabilities");
+    }
+
+    /**
+     * Listen for events on this channel.
+     * @param {string} type Event type. 'message' is currently the only supported event type.
+     * @param {Function} listener The event listener function
+     *
+     * Events fired:
+     *  - 'message': Fired when a message is received from the device. The event object has a 'message' property containing the message string.
+     *
+     * @example
+     * // Listen for messages
+     * channel.addEventListener('message', (event) => {
+     *     console.log(`Received message: ${event.message}`);
+     * });
+     *
+     * // remove listener
+     * channel.removeEventListener('message', messageHandler);
+     */
+
+    /** dispose of this message channel.
+     * After calling dispose(), the channel is no longer usable.
+     * You may create a new channel of the same type if needed via the DeviceManager.
+     * @example
+     * channel.dispose();
+     */
+    dispose() {
+        return noop("MessageChannel.dispose");
+    }
+}
 
 /**
  * @module
@@ -110,6 +228,14 @@ export class DeviceManager extends EventTarget {
  * await deviceManager.clearWifi();
  * deviceManager.reboot();
  *
+ * // Message channel example
+ * const channels = deviceManager.getAvailableMessageChannels();
+ * const channel = deviceManager.createMessageChannel(deviceManager.DeviceMessageChannelType.SZE_HOST_APP);
+ * channel.addEventListener('message', (event) => {
+ *     console.log(`Received: ${event.message}`);
+ * });
+ * await channel.sendMessage("Hello Senza Embedded host application");
+ *
  * @return {DeviceManager} pointer to the DeviceManager singleton
  */
 "needed for the module doc comment to be recognized";

package/src/interface/lifecycle.js

@@ -16,9 +16,9 @@ import {
 /**
  * @event Lifecycle#beforestatechange
  * @description Fired before transitioning to a new state. This event is cancelable.<br>
- * Currently only fired when transitioning to BACKGROUND state (e.g., from autoBackground feature).<br>
+ * Currently only fired when transitioning to BACKGROUND and SUSPENDED state (e.g., from autoBackground feature).<br>
  * The actual state transition will occur after all event listeners have completed processing.
- * Can be used to prevent automatic transitions to background state when using autoBackground feature.
+ * Can be used to prevent automatic transitions to background state when using autoBackground feature, or for suspneded from autoSuspended feature .
  * @property {UiState} state - Indicates the target state the lifecycle is trying to transition to.
  * @property {boolean} cancelable - true, indicating the event can be cancelled using preventDefault()
  * @example
@@ -87,13 +87,15 @@ class Lifecycle extends EventTarget {
      * @property {string} IN_TRANSITION_TO_FOREGROUND - ui is about to be displayed
      * @property {string} BACKGROUND - remote player is playing (full screen playback is displayed)
      * @property {string} IN_TRANSITION_TO_BACKGROUND - remote player is about to be playing
+     * @property {string} SUSPENDED - application is suspended. This state is used for the beforestatechange event only.
      */
     UiState = Object.freeze({
         UNKNOWN: "unknown",
         FOREGROUND: "foreground",
         IN_TRANSITION_TO_FOREGROUND: "inTransitionToForeground",
         BACKGROUND: "background",
-        IN_TRANSITION_TO_BACKGROUND: "inTransitionToBackground"
+        IN_TRANSITION_TO_BACKGROUND: "inTransitionToBackground",
+        SUSPENDED: "suspended"
     });
 
     /**

package/src/interface/version.js

@@ -1 +1 @@
-export const version = "4.4.6";
+export const version = "4.4.8";