@reveldigital/player-client 1.0.13 → 1.0.15

package/lib/interfaces/client.interface.d.ts

@@ -1,164 +1,406 @@
 import { IDictionary } from "./config.interface";
-/** @ignore */
+/**
+ * Core interface defining the contract for Revel Digital player client implementations.
+ *
+ * This interface represents the complete API available for gadgets and web applications
+ * to interact with the Revel Digital player environment. It provides methods for:
+ *
+ * - **Device Information**: Access device details, timezone, language, and hardware specs
+ * - **Communication**: Send commands locally and to remote devices
+ * - **Analytics**: Track events, measure performance, and manage user sessions
+ * - **Player Control**: Manage gadget lifecycle and player transitions
+ * - **Configuration**: Apply and manage gadget preferences and settings
+ *
+ * Implementations of this interface handle the actual communication with the player
+ * environment, while providing a consistent API for client code regardless of the
+ * underlying platform or deployment scenario.
+ *
+ * ```typescript
+ * // Typical usage through PlayerClientService
+ * class MyGadget {
+ *   constructor(private client: PlayerClientService) {}
+ *
+ *   async initialize() {
+ *     const device = await this.client.getDevice();
+ *     const time = await this.client.getDeviceTime();
+ *     this.client.track('gadget_initialized', { deviceType: device.deviceType });
+ *   }
+ * }
+ * ```
+ *
+ * @export
+ * @interface IClient
+ * @since 1.0.0
+ */
 export interface IClient {
     /**
-     * Callback to the player.
-     * This is the primary method of communication between the client and the player.
+     * Sends a callback to the player with optional arguments.
      *
-     * @param {...any[]} args
-     * @returns {void}
-     * @memberof IClient
+     * This is the primary method for bi-directional communication between the gadget
+     * and player scripting. When called, it triggers any callback handlers that have
+     * been configured in the player template scripting.
+     *
+     * @param args - Variable number of arguments to pass to the player callback handler
+     *
+     * ```typescript
+     * // Simple callback without arguments
+     * client.callback();
+     *
+     * // Callback with data
+     * client.callback('user_action', { buttonId: 'start', timestamp: Date.now() });
+     *
+     * // Multiple arguments
+     * client.callback('event_name', 'event_data', { additional: 'context' });
+     * ```
      */
     callback(...args: any[]): void;
     /**
-     * Get device name
+     * Gets the current device time in the device's configured timezone.
+     *
+     * Returns the current time adjusted to the timezone assigned to the device
+     * in the Revel Digital CMS. If a date is provided, it will be converted
+     * to the device's timezone.
+     *
+     * @param date - Optional date to convert to device time. If omitted, returns current device time
+     * @returns Promise resolving to ISO8601 formatted date string in device timezone
      *
-     * @returns {Promise<string | null>}
-     * @memberof IClient
+     * ```typescript
+     * // Get current device time
+     * const now = await client.getDeviceTime();
+     *
+     * // Convert specific time to device timezone
+     * const utcTime = new Date('2023-12-25T12:00:00Z');
+     * const localTime = await client.getDeviceTime(utcTime);
+     * ```
      */
     getDeviceTime(date?: Date): Promise<string | null>;
     /**
-     * Get device time zone name
+     * Gets the timezone name currently assigned to the device.
+     *
+     * Returns the human-readable timezone name as configured in the device
+     * settings within the Revel Digital CMS.
+     *
+     * @returns Promise resolving to timezone name (e.g., "America/New_York", "Europe/London")
      *
-     * @returns {Promise<string | null>}
-     * @memberof IClient
+     * ```typescript
+     * const timezoneName = await client.getDeviceTimeZoneName();
+     * console.log(`Device timezone: ${timezoneName}`);
+     * ```
      */
     getDeviceTimeZoneName(): Promise<string | null>;
     /**
-     * Get device time zone ID
+     * Gets the timezone identifier currently assigned to the device.
      *
-     * @returns {Promise<string | null>}
-     * @memberof IClient
+     * Returns the timezone ID/identifier as configured for this device.
+     * This may be different from the timezone name depending on the system configuration.
+     *
+     * @returns Promise resolving to timezone identifier
+     *
+     * ```typescript
+     * const timezoneId = await client.getDeviceTimeZoneID();
+     * // Use for timezone-specific operations
+     * ```
      */
     getDeviceTimeZoneID(): Promise<string | null>;
     /**
-     * Get device time zone offset
+     * Gets the numerical offset from GMT for the device's configured timezone.
+     *
+     * Returns the number of hours the device's timezone is offset from GMT.
+     * Positive values indicate timezones east of GMT, negative values indicate
+     * timezones west of GMT.
      *
-     * @returns {Promise<number | null>}
-     * @memberof IClient
+     * @returns Promise resolving to timezone offset in hours (e.g., -5 for EST, +1 for CET)
+     *
+     * ```typescript
+     * const offset = await client.getDeviceTimeZoneOffset();
+     * console.log(`Device is ${offset} hours from GMT`);
+     * ```
      */
     getDeviceTimeZoneOffset(): Promise<number | null>;
     /**
-     * Get device language code
+     * Gets the language code currently assigned to the device.
+     *
+     * Returns the language/locale code configured for this device in the CMS.
+     * This can be used for localization and internationalization purposes.
+     *
+     * @returns Promise resolving to language code (e.g., "en-US", "fr-FR", "de-DE")
      *
-     * @returns {Promise<string | null>}
-     * @memberof IClient
+     * ```typescript
+     * const langCode = await client.getLanguageCode();
+     * if (langCode === 'fr-FR') {
+     *   this.loadFrenchContent();
+     * }
+     * ```
      */
     getLanguageCode(): Promise<string | null>;
     /**
-     * Get device key
+     * Gets the unique device key (registration key) for this player device.
      *
-     * @returns {Promise<string | null>}
-     * @memberof IClient
+     * The device key is a unique identifier assigned to each device when it's
+     * registered with the Revel Digital system. This key can be used for
+     * device-specific operations and remote command targeting.
+     *
+     * @returns Promise resolving to the device's unique registration key
+     *
+     * ```typescript
+     * const deviceKey = await client.getDeviceKey();
+     * console.log(`This device key: ${deviceKey}`);
+     * // Use for analytics or device-specific configuration
+     * ```
      */
     getDeviceKey(): Promise<string | null>;
     /**
-     * Send command to device
+     * Sends a command to the local player device.
+     *
+     * Commands are used to trigger specific behaviors or actions on the player.
+     * The command is processed immediately by the local player only.
      *
-     * @param name
-     * @param arg
-     * @returns {void}
-     * @memberof IClient
+     * @param name - The command identifier/name
+     * @param arg - Command argument or payload data
+     *
+     * ```typescript
+     * // Simple command
+     * client.sendCommand('restart', '');
+     *
+     * // Command with parameters
+     * client.sendCommand('setVolume', '75');
+     * client.sendCommand('loadContent', JSON.stringify({ url: 'http://example.com' }));
+     * ```
      */
     sendCommand(name: string, arg: string): void;
     /**
-     * Send remote command to device
+     * Sends a command to one or more remote player devices.
+     *
+     * Enables cross-device communication by sending commands to other devices
+     * within the same Revel Digital account. Useful for synchronized displays,
+     * coordinated actions, or remote device control.
      *
-     * @param deviceKeys
-     * @param name
-     * @param arg
-     * @returns {void}
-     * @memberof IClient
+     * @param deviceKeys - Array of target device keys to receive the command
+     * @param name - The command identifier/name
+     * @param arg - Command argument or payload data
+     *
+     * ```typescript
+     * // Send to multiple devices
+     * const targets = ['lobby-display', 'kiosk-001', 'kiosk-002'];
+     * client.sendRemoteCommand(targets, 'updateContent', 'new-content-id');
+     *
+     * // Broadcast synchronization command
+     * client.sendRemoteCommand(['device1', 'device2'], 'sync', Date.now().toString());
+     * ```
      */
     sendRemoteCommand(deviceKeys: string[], name: string, arg: string): void;
     /**
-     * Track event
+     * Tracks an analytics event with optional properties.
+     *
+     * Events are logged for analytics and reporting purposes, providing insights
+     * into gadget usage, performance, and user interactions. For timed events,
+     * the duration is automatically calculated from the timeEvent() call to this track() call.
      *
-     * In the case of a timed event, the duration is calculated from the timeEvent call to the track call.
+     * @param eventName - Unique identifier for the event
+     * @param properties - Optional JSON string containing event properties and metadata
      *
-     * @param eventName
-     * @param properties
-     * @returns {void}
-     * @memberof IClient
+     * ```typescript
+     * // Simple event
+     * client.track('gadget_loaded', '');
+     *
+     * // Event with properties
+     * const props = JSON.stringify({
+     *   action: 'button_click',
+     *   button_id: 'submit',
+     *   timestamp: Date.now()
+     * });
+     * client.track('user_interaction', props);
+     * ```
      */
     track(eventName: string, properties?: string): void;
     /**
-     * Start tracking of event with duration
+     * Begins timing measurement for a named event.
+     *
+     * This starts a timer for performance measurement. The timer is stopped
+     * and duration calculated when track() is called with the same event name.
+     * Multiple concurrent timers can be active for different event names.
+     *
+     * @param eventName - Unique identifier for the timed event
      *
-     * @param eventName
-     * @returns {void}
-     * @memberof IClient
+     * ```typescript
+     * // Start timing a video playback
+     * client.timeEvent('video_playback');
+     * // ... video plays for some duration ...
+     * client.track('video_playback', JSON.stringify({ videoId: 'abc123' }));
+     * // Duration is automatically included in the tracked event
+     * ```
      */
     timeEvent(eventName: string): void;
     /**
-     * Start a new session
+     * Creates a new analytics event session for grouping related events.
+     *
+     * Sessions provide a way to group related events together for analysis.
+     * Each subsequent event tracked will be associated with this session
+     * until a new session is started.
+     *
+     * @param id - Optional custom session identifier. If not provided, a random ID is generated
+     *
+     * ```typescript
+     * // Start new session with auto-generated ID
+     * client.newEventSession();
+     * client.track('session_start', '');
      *
-     * @param id optional session ID
-     * @returns {void}
-     * @memberof IClient
+     * // Start session with custom ID
+     * client.newEventSession('user-123-workflow');
+     * client.track('workflow_begin', '');
+     * ```
      */
     newEventSession(id?: string): void;
     /**
-     * Get the root directory of the Revel system
+     * Gets the root directory path where the Revel Digital system stores files.
      *
-     * @returns {Promise<string | null>}
-     * @memberof IClient
+     * Returns the base file system path used by the player for storing
+     * content, cache, and other system files on the local device.
+     *
+     * @returns Promise resolving to the root directory path
+     *
+     * ```typescript
+     * const rootPath = await client.getRevelRoot();
+     * console.log(`System root: ${rootPath}`);
+     * // Use for file operations or path construction
+     * ```
      */
     getRevelRoot(): Promise<string | null>;
     /**
-     * Get the command map
+     * Gets the current command map configuration for this device.
+     *
+     * Returns a JSON string containing the mapping of command names to their
+     * configurations as defined in the device's current template or playlist.
      *
-     * @returns {Promise<string | null>}
-     * @memberof IClient
+     * @returns Promise resolving to JSON string of command mappings
+     *
+     * ```typescript
+     * const commandMapJson = await client.getCommandMap();
+     * const commandMap = JSON.parse(commandMapJson);
+     * if (commandMap['customCommand']) {
+     *   console.log('Custom command is available');
+     * }
+     * ```
      */
     getCommandMap(): Promise<string | null>;
     /**
-     * Signals to the player that the client is finished and the player can transition to the next source
+     * Signals that the gadget has completed its visualization and the player can proceed.
+     *
+     * This notifies the player that the current content has finished displaying
+     * and it's safe to transition to the next item in a playlist or perform
+     * other scheduled actions.
+     *
+     * ```typescript
+     * // After animation completes
+     * setTimeout(() => {
+     *   client.finish();
+     * }, 5000);
+     *
+     * // After user interaction
+     * button.onclick = () => {
+     *   this.processAction();
+     *   client.finish();
+     * };
+     * ```
      */
     finish(): void;
     /**
-     * Get device information
+     * Gets comprehensive information about the current device.
+     *
+     * Returns detailed device information including registration details,
+     * hardware type, location, and configuration as a JSON string.
+     *
+     * @returns Promise resolving to JSON string containing device information
      *
-     * @returns {Promise<string | null>}
-     * @memberof IClient
+     * ```typescript
+     * const deviceJson = await client.getDevice();
+     * const device = JSON.parse(deviceJson);
+     * console.log(`Device: ${device.name} (${device.devicetype})`);
+     * console.log(`Location: ${device.location?.city}, ${device.location?.state}`);
+     * ```
      */
     getDevice(): Promise<string | null>;
     /**
-     * Get width of the visualization area
+     * Gets the width of the available visualization area in pixels.
      *
-     * @returns {Promise<number | null>}
-     * @memberof IClient
+     * Returns the display width available for gadget content, which may
+     * differ from screen resolution based on template layout and player configuration.
+     *
+     * @returns Promise resolving to width in pixels
+     *
+     * ```typescript
+     * const width = await client.getWidth();
+     * if (width < 800) {
+     *   this.enableMobileLayout();
+     * }
+     * ```
      */
     getWidth(): Promise<number | null>;
     /**
-     * Get height of the visualization area
+     * Gets the height of the available visualization area in pixels.
+     *
+     * Returns the display height available for gadget content, which may
+     * differ from screen resolution based on template layout and player configuration.
      *
-     * @returns {Promise<number | null>}
-     * @memberof IClient
+     * @returns Promise resolving to height in pixels
+     *
+     * ```typescript
+     * const height = await client.getHeight();
+     * const width = await client.getWidth();
+     * const aspectRatio = width / height;
+     * this.adjustLayout(aspectRatio);
+     * ```
      */
     getHeight(): Promise<number | null>;
     /**
-     * Get the duration of the currently playing source
-     * (only applicable when associated with a playlist)
+     * Gets the duration assigned to the current playlist item.
+     *
+     * Returns the time duration (in milliseconds) that this content should
+     * be displayed when running as part of a playlist. Only applicable
+     * when the gadget is associated with a playlist.
+     *
+     * @returns Promise resolving to duration in milliseconds
      *
-     * @returns {Promise<number | null>}
-     * @memberof IClient
+     * ```typescript
+     * const duration = await client.getDuration();
+     * if (duration) {
+     *   // Auto-finish after the assigned duration
+     *   setTimeout(() => client.finish(), duration);
+     * }
+     * ```
      */
     getDuration(): Promise<number | null>;
     /**
-     * Get the SDK version
+     * Gets the version of the Revel Digital SDK.
      *
-     * @returns {Promise<string | null>}
-     * @memberof IClient
+     * Returns the current version string of the SDK/client library.
+     *
+     * @returns Promise resolving to version string
+     *
+     * ```typescript
+     * const version = await client.getSdkVersion();
+     * console.log(`SDK Version: ${version}`);
+     * ```
      */
     getSdkVersion(): Promise<string | null>;
     /**
-     * Sends the preference values to the CMS for assignement to the gadget configuration.
+     * Applies configuration preferences to the gadget (design-time only).
+     *
+     * This method is used during gadget design/configuration to apply
+     * preference changes. It sends the updated preferences to the CMS
+     * for assignment to the gadget configuration. Only available during
+     * design-time operations.
      *
-     * Provides the ability to have the gadget present a UI for setting preferences.
-     * Only available during design time.
+     * @param prefs - Dictionary of preference key-value pairs to apply
      *
-     * @param prefs key/value pairs of preferences to apply
+     * ```typescript
+     * // Apply configuration changes in design mode
+     * client.applyConfig({
+     *   'title': 'Updated Title',
+     *   'backgroundColor': '#ff0000',
+     *   'autoRefresh': true
+     * });
+     * ```
      */
     applyConfig(prefs: IDictionary<any>): void;
 }

package/lib/interfaces/client.interface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.interface.d.ts","sourceRoot":"","sources":["../../../../../projects/reveldigital/player-client/src/lib/interfaces/client.interface.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjD,cAAc;AACd,MAAM,WAAW,OAAO;IAEpB;;;;;;;OAOG;IACH,QAAQ,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IAE/B;;;;;OAKG;IACH,aAAa,CAAC,IAAI,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAEnD;;;;;OAKG;IACH,qBAAqB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAEhD;;;;;OAKG;IACH,mBAAmB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAE9C;;;;;OAKG;IACH,uBAAuB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAElD;;;;;OAKG;IACH,eAAe,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAE1C;;;;;OAKG;IACH,YAAY,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAEvC;;;;;;;OAOG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAE7C;;;;;;;;OAQG;IACH,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAEzE;;;;;;;;;OASG;IACH,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAEpD;;;;;;OAMG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAEnC;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAEnC;;;;;OAKG;IACH,YAAY,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAEvC;;;;;OAKG;IACH,aAAa,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAExC;;OAEG;IACH,MAAM,IAAI,IAAI,CAAC;IAEf;;;;;OAKG;IACH,SAAS,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAEpC;;;;;OAKG;IACH,QAAQ,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAEnC;;;;;OAKG;IACH,SAAS,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAEpC;;;;;;OAMG;IACH,WAAW,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAEtC;;;;;OAKG;IACH,aAAa,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAExC;;;;;;;OAOG;IACH,WAAW,CAAC,KAAK,EAAE,WAAW,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;CAC9C"}
+{"version":3,"file":"client.interface.d.ts","sourceRoot":"","sources":["../../../../../projects/reveldigital/player-client/src/lib/interfaces/client.interface.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,WAAW,OAAO;IAEpB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IAE/B;;;;;;;;;;;;;;;;;;OAkBG;IACH,aAAa,CAAC,IAAI,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAEnD;;;;;;;;;;;;OAYG;IACH,qBAAqB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAEhD;;;;;;;;;;;;OAYG;IACH,mBAAmB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAE9C;;;;;;;;;;;;;OAaG;IACH,uBAAuB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAElD;;;;;;;;;;;;;;OAcG;IACH,eAAe,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAE1C;;;;;;;;;;;;;;OAcG;IACH,YAAY,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAEvC;;;;;;;;;;;;;;;;;OAiBG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAE7C;;;;;;;;;;;;;;;;;;;OAmBG;IACH,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAEzE;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAEpD;;;;;;;;;;;;;;;;OAgBG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAEnC;;;;;;;;;;;;;;;;;;OAkBG;IACH,eAAe,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAEnC;;;;;;;;;;;;;OAaG;IACH,YAAY,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAEvC;;;;;;;;;;;;;;;OAeG;IACH,aAAa,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAExC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,IAAI,IAAI,CAAC;IAEf;;;;;;;;;;;;;;OAcG;IACH,SAAS,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAEpC;;;;;;;;;;;;;;OAcG;IACH,QAAQ,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAEnC;;;;;;;;;;;;;;OAcG;IACH,SAAS,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAEpC;;;;;;;;;;;;;;;;OAgBG;IACH,WAAW,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAEtC;;;;;;;;;;;OAWG;IACH,aAAa,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAExC;;;;;;;;;;;;;;;;;;OAkBG;IACH,WAAW,CAAC,KAAK,EAAE,WAAW,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;CAC9C"}

package/lib/interfaces/command.interface.d.ts

@@ -1,18 +1,78 @@
+/**
+ * Interface representing a command sent to or from the Revel Digital player.
+ *
+ * Commands are the primary mechanism for triggering actions and behaviors
+ * in the player environment. They consist of a name identifier and an
+ * optional argument payload that provides additional context or parameters.
+ *
+ * Commands can originate from:
+ * - Remote devices via sendRemoteCommand()
+ * - Template scripting via player callbacks
+ * - Playlist actions and transitions
+ * - Manual triggers from the CMS interface
+ *
+ * ```typescript
+ * // Subscribe to incoming commands
+ * this.client.onCommand$.subscribe((command: ICommand) => {
+ *   switch (command.name) {
+ *     case 'refresh':
+ *       this.refreshContent();
+ *       break;
+ *     case 'updateConfig':
+ *       this.applyNewConfig(JSON.parse(command.arg));
+ *       break;
+ *     case 'customAction':
+ *       this.handleCustomAction(command.arg);
+ *       break;
+ *   }
+ * });
+ * ```
+ *
+ * @export
+ * @interface ICommand
+ * @since 1.0.0
+ */
 export interface ICommand {
     /**
-     * Command name
+     * The command identifier or action name.
      *
-     * @type {string}
+     * This is a string that uniquely identifies the type of command or action
+     * to be performed. Command names should be descriptive and consistent
+     * across the application.
      *
-     * @memberof Command
+     * Common command names:
+     * - "refresh" - Reload content or data
+     * - "restart" - Restart the application or component
+     * - "updateConfig" - Apply new configuration settings
+     * - "setVolume" - Adjust audio volume
+     * - "loadContent" - Load specific content by ID
+     * - "sync" - Synchronize with other devices
      */
     name: string;
     /**
-     * Command arguments
+     * Optional command argument or payload data.
      *
-     * @type {Array<string>}
+     * This string contains any additional data required by the command.
+     * For complex data structures, this is typically a JSON-encoded string
+     * that can be parsed by the command handler.
      *
-     * @memberof ICommand
+     * ```typescript
+     * // Simple string argument
+     * { name: "setVolume", arg: "75" }
+     *
+     * // JSON payload for complex data
+     * {
+     *   name: "loadContent",
+     *   arg: JSON.stringify({
+     *     contentId: "abc123",
+     *     transition: "fade",
+     *     duration: 5000
+     *   })
+     * }
+     *
+     * // Empty argument for parameterless commands
+     * { name: "refresh", arg: "" }
+     * ```
      */
     arg: string;
 }

package/lib/interfaces/command.interface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command.interface.d.ts","sourceRoot":"","sources":["../../../../../projects/reveldigital/player-client/src/lib/interfaces/command.interface.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,QAAQ;IACrB;;;;;;OAMG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;;;;OAMG;IACH,GAAG,EAAE,MAAM,CAAC;CACf"}
+{"version":3,"file":"command.interface.d.ts","sourceRoot":"","sources":["../../../../../projects/reveldigital/player-client/src/lib/interfaces/command.interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,WAAW,QAAQ;IACrB;;;;;;;;;;;;;;OAcG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,GAAG,EAAE,MAAM,CAAC;CACf"}