@webex/plugin-meetings 3.0.0-beta.21 → 3.0.0-beta.211

package/src/controls-options-manager/index.ts

@@ -0,0 +1,278 @@
+import {camelCase} from 'lodash';
+import PermissionError from '../common/errors/permission';
+import {CONTROLS, HTTP_VERBS} from '../constants';
+import MeetingRequest from '../meeting/request';
+import LoggerProxy from '../common/logs/logger-proxy';
+import {Control, Setting} from './enums';
+import {ControlConfig} from './types';
+import Util from './util';
+import {CAN_SET, CAN_UNSET, ENABLED} from './constants';
+
+/**
+ * docs
+ * https://sqbu-github.cisco.com/pages/WebExSquared/locus/guides/mute.html
+ * https://confluence-eng-gpk2.cisco.com/conf/display/LOCUS/Hard+Mute+and+Audio+Privacy#HardMuteandAudioPrivacy-SelfMuteonEntry
+ * https://confluence-eng-gpk2.cisco.com/conf/pages/viewpage.action?spaceKey=UC&title=WEBEX-124454%3A+UCF%3A+Hard+mute+support+for+Teams+joining+Webex+meeting
+ * https://jira-eng-gpk2.cisco.com/jira/browse/SPARK-180867
+ * https://jira-eng-gpk2.cisco.com/jira/browse/SPARK-393351
+ */
+
+/**
+ * @description ControlsOptionsManager is responsible for handling the behavior of participant controls when somebody joins a meeting
+ * @export
+ * @private
+ * @class Recording
+ */
+export default class ControlsOptionsManager {
+  /**
+   * @instance
+   * @type {MeetingRequest}
+   * @private
+   * @memberof ControlsOptionsManager
+   */
+  private request: MeetingRequest;
+
+  /**
+   * @instance
+   * @type {Array}
+   * @private
+   * @memberof ControlsOptionsManager
+   */
+  private displayHints: Array<string> = [];
+
+  /**
+   * @instance
+   * @type {string}
+   * @private
+   * @memberof ControlsOptionsManager
+   */
+  private locusUrl: string;
+
+  /**
+   * @param {MeetingRequest} request
+   * @param {Object} options
+   * @constructor
+   * @memberof ControlsOptionsManager
+   */
+  constructor(
+    request: MeetingRequest,
+    options?: {
+      locusUrl: string;
+      displayHints?: Array<string>;
+    }
+  ) {
+    this.initialize(request);
+    this.set(options);
+  }
+
+  /**
+   * @param {MeetingRequest} request
+   * @returns {void}
+   * @private
+   * @memberof ControlsOptionsManager
+   */
+  private initialize(request: MeetingRequest) {
+    this.request = request;
+  }
+
+  /**
+   * @param {Object} options
+   * @returns {void}
+   * @public
+   * @memberof ControlsOptionsManager
+   */
+  public set(options?: {locusUrl: string; displayHints?: Array<string>}) {
+    this.extract(options);
+  }
+
+  /**
+   * @param {string} url
+   * @returns {void}
+   * @public
+   * @memberof ControlsOptionsManager
+   */
+  public setLocusUrl(url: string) {
+    this.locusUrl = url;
+  }
+
+  /**
+   * @param {Array} hints
+   * @returns {void}
+   * @public
+   * @memberof ControlsOptionsManager
+   */
+  public setDisplayHints(hints: Array<string>) {
+    this.displayHints = hints;
+  }
+
+  /**
+   * @returns {string}
+   * @public
+   * @memberof ControlsOptionsManager
+   */
+  public getLocusUrl() {
+    return this.locusUrl;
+  }
+
+  /**
+   * @returns {Array}
+   * @public
+   * @memberof ControlsOptionsManager
+   */
+  public getDisplayHints() {
+    return this.displayHints;
+  }
+
+  /**
+   * @param {Object} options
+   * @returns {void}
+   * @private
+   * @memberof ControlsOptionsManager
+   */
+  private extract(options?: {locusUrl: string; displayHints?: Array<string>}) {
+    this.setDisplayHints(options?.displayHints);
+    this.setLocusUrl(options?.locusUrl);
+  }
+
+  /**
+   * Set controls for this meeting.
+   *
+   * @param {Array<ControlConfig>} controls - Spread Array of ControlConfigs
+   * @returns {Promise<Array<any>>}- Promise resolving if the request was successful.
+   */
+  public update(...controls: Array<ControlConfig>) {
+    const payloads = controls.map((control) => {
+      if (!Object.keys(Control).includes(control.scope)) {
+        throw new Error(
+          `updating meeting control scope "${control.scope}" is not a supported scope`
+        );
+      }
+
+      if (!Util.canUpdate(control, this.displayHints)) {
+        throw new PermissionError(
+          `updating meeting control scope "${control.scope}" not allowed, due to moderator property.`
+        );
+      }
+
+      return {
+        [control.scope]: control.properties,
+      };
+    });
+
+    return payloads.reduce((previous, payload) => {
+      return previous.then(() =>
+        // @ts-ignore
+        this.request.request({
+          uri: `${this.locusUrl}/${CONTROLS}`,
+          body: payload,
+          method: HTTP_VERBS.PATCH,
+        })
+      );
+    }, Promise.resolve());
+  }
+
+  /**
+   * @param {Setting} setting
+   * @private
+   * @memberof ControlsOptionsManager
+   * @returns {Promise}
+   */
+  private setControls(setting: {[key in Setting]?: boolean}): Promise<any> {
+    LoggerProxy.logger.log(
+      `ControlsOptionsManager:index#setControls --> ${JSON.stringify(setting)}`
+    );
+
+    const body: Record<string, any> = {};
+    let error: PermissionError;
+
+    let shouldSkipCheckToMergeBody = false;
+
+    Object.entries(setting).forEach(([key, value]) => {
+      if (
+        !shouldSkipCheckToMergeBody &&
+        !Util?.[`${value ? CAN_SET : CAN_UNSET}${key}`](this.displayHints)
+      ) {
+        error = new PermissionError(`${key} [${value}] not allowed, due to moderator property.`);
+      }
+
+      if (error) {
+        return;
+      }
+
+      switch (key) {
+        case Setting.muted:
+          shouldSkipCheckToMergeBody = true;
+          body.audio = body.audio
+            ? {...body.audio, [camelCase(key)]: value}
+            : {[camelCase(key)]: value};
+          break;
+
+        case Setting.disallowUnmute:
+        case Setting.muteOnEntry:
+          if (Object.keys(setting).includes(Setting.muted)) {
+            body.audio = body.audio
+              ? {...body.audio, [camelCase(key)]: value}
+              : {[camelCase(key)]: value};
+            body.audio[camelCase(key)] = value;
+          } else {
+            body[camelCase(key)] = {[ENABLED]: value};
+          }
+          break;
+
+        default:
+          error = new PermissionError(`${key} [${value}] not allowed, due to moderator property.`);
+      }
+    });
+
+    if (error) {
+      return Promise.reject(error);
+    }
+
+    // @ts-ignore
+    return this.request.request({
+      uri: `${this.locusUrl}/${CONTROLS}`,
+      body,
+      method: HTTP_VERBS.PATCH,
+    });
+  }
+
+  /**
+   * @public
+   * @param {boolean} enabled
+   * @memberof ControlsOptionsManager
+   * @returns {Promise}
+   */
+  public setMuteOnEntry(enabled: boolean): Promise<any> {
+    return this.setControls({[Setting.muteOnEntry]: enabled});
+  }
+
+  /**
+   * @public
+   * @param {boolean} enabled
+   * @memberof ControlsOptionsManager
+   * @returns {Promise}
+   */
+  public setDisallowUnmute(enabled: boolean): Promise<any> {
+    return this.setControls({[Setting.disallowUnmute]: enabled});
+  }
+
+  /**
+   * @public
+   * @param {boolean} mutedEnabled
+   * @param {boolean} disallowUnmuteEnabled
+   * @param {boolean} muteOnEntryEnabled
+   * @memberof ControlsOptionsManager
+   * @returns {Promise}
+   */
+  public setMuteAll(
+    mutedEnabled: boolean,
+    disallowUnmuteEnabled: boolean,
+    muteOnEntryEnabled: boolean
+  ): Promise<any> {
+    return this.setControls({
+      [Setting.muted]: mutedEnabled,
+      [Setting.disallowUnmute]: disallowUnmuteEnabled,
+      [Setting.muteOnEntry]: muteOnEntryEnabled,
+    });
+  }
+}

package/src/controls-options-manager/types.ts

@@ -0,0 +1,59 @@
+import {Control} from './enums';
+
+export interface ControlProperties {
+  /**
+   * A list of additional properties that apply to various specific settings.
+   *
+   * @remarks
+   * The values stored here, per the service, are fully ambiguous, an can vary
+   * depending on which control scope is being configured.
+   */
+  [key: string]: boolean;
+}
+
+export interface AudioProperties {
+  muted?: boolean;
+  disallowUnmute?: boolean;
+  muteOnEntry?: boolean;
+}
+
+export interface RaiseHandProperties {
+  enabled?: boolean;
+}
+
+export interface ReactionsProperties {
+  enabled?: boolean;
+  showDisplayNameWithReactions?: boolean;
+}
+
+export interface ShareControlProperties {
+  control?: 'ANYONE' | 'MODERATOR_PRESENTER';
+}
+
+export interface VideoProperties {
+  enabled?: boolean;
+}
+
+export interface ViewTheParticipantListProperties {
+  enabled?: boolean;
+}
+
+export type Properties =
+  | AudioProperties
+  | RaiseHandProperties
+  | ReactionsProperties
+  | ShareControlProperties
+  | VideoProperties
+  | ViewTheParticipantListProperties;
+
+export interface ControlConfig<Props = Properties> {
+  /**
+   * The scope of the control within this object.
+   */
+  scope: Control;
+
+  /**
+   * The properties to assign to this control.
+   */
+  properties: Props;
+}

package/src/controls-options-manager/util.ts

@@ -0,0 +1,300 @@
+import {DISPLAY_HINTS} from '../constants';
+import {Control} from './enums';
+import {
+  ControlConfig,
+  AudioProperties,
+  RaiseHandProperties,
+  ReactionsProperties,
+  ViewTheParticipantListProperties,
+  VideoProperties,
+} from './types';
+
+/**
+ * The Controls Options Manager utilities
+ *
+ * @internal
+ */
+class Utils {
+  /**
+   * Validate if enabling mute on entry can be set.
+   *
+   * @param {Array<string>} displayHints - Display Hints to use when validating.
+   * @returns {boolean} - True if the action is allowed.
+   */
+  public static canSetMuteOnEntry(displayHints: Array<string>): boolean {
+    return displayHints.includes(DISPLAY_HINTS.ENABLE_MUTE_ON_ENTRY);
+  }
+
+  /**
+   * Validate if allowing unmuting can be set.
+   *
+   * @param {Array<string>} displayHints - Display Hints to use when validating.
+   * @returns {boolean} - True if the action is allowed.
+   */
+  public static canSetDisallowUnmute(displayHints: Array<string>): boolean {
+    return displayHints.includes(DISPLAY_HINTS.ENABLE_HARD_MUTE);
+  }
+
+  /**
+   * Validate if disabling mute on entry can be set.
+   *
+   * @param {Array<string>} displayHints - Display Hints to use when validating.
+   * @returns {boolean} - True if the action is allowed.
+   */
+  public static canUnsetMuteOnEntry(displayHints: Array<string>): boolean {
+    return displayHints.includes(DISPLAY_HINTS.DISABLE_MUTE_ON_ENTRY);
+  }
+
+  /**
+   * Validate if enabling muting can be set.
+   *
+   * @param {Array<string>} displayHints - Display Hints to use when validating.
+   * @returns {boolean} - True if the action is allowed.
+   */
+  public static canUnsetDisallowUnmute(displayHints: Array<string>): boolean {
+    return displayHints.includes(DISPLAY_HINTS.DISABLE_HARD_MUTE);
+  }
+
+  /**
+   * Validate if muting all can be set.
+   *
+   * @param {Array<string>} displayHints - Display Hints to use when validating.
+   * @returns {boolean} - True if the action is allowed.
+   */
+  public static canSetMuted(displayHints: Array<string>): boolean {
+    return displayHints.includes(DISPLAY_HINTS.MUTE_ALL);
+  }
+
+  /**
+   * Validate if unmuting all can be set.
+   *
+   * @param {Array<string>} displayHints - Display Hints to use when validating.
+   * @returns {boolean} - True if the action is allowed.
+   */
+  public static canUnsetMuted(displayHints: Array<string>): boolean {
+    return displayHints.includes(DISPLAY_HINTS.UNMUTE_ALL);
+  }
+
+  /**
+   * Validate an array of hints are allowed based on a full collection of hints.
+   *
+   * @param {Object} config - Configuration Object.
+   * @param {Array<string>} config.requiredHints - Hints required for validation.
+   * @param {Array<string>} config.displayHints - All available hints.
+   * @returns {boolean} - True if all of the actions are allowed.
+   */
+  public static hasHints(config: {requiredHints: Array<string>; displayHints: Array<string>}) {
+    const {requiredHints, displayHints} = config;
+
+    return requiredHints.every((hint) => displayHints.includes(hint));
+  }
+
+  /**
+   * Validate that the self policy object contains the required policies.
+   *
+   * @param {Object} config - Configuration Object.
+   * @param {Array<string>} config.requiredPolicies - Policies required for validation.
+   * @param {Array<string>} config.policies - All available policies.
+   * @returns {boolean} - True if all of the actions are allowed.
+   */
+  public static hasPolicies(config: {requiredPolicies: Array<string>; policies: Array<string>}) {
+    const {requiredPolicies, policies = {}} = config;
+
+    return requiredPolicies.every((hint) => policies[hint]);
+  }
+
+  /**
+   * Validate if an audio-scoped control is allowed to be sent to the service.
+   *
+   * @param {ControlConfig<AudioProperties>} control - Audio control config to validate.
+   * @param {Array<string>} displayHints - All available hints.
+   * @returns {boolean} - True if all of the actions are allowed.
+   */
+  public static canUpdateAudio(
+    control: ControlConfig<AudioProperties>,
+    displayHints: Array<string>
+  ) {
+    const requiredHints = [];
+
+    if (control.properties.muted === true) {
+      requiredHints.push(DISPLAY_HINTS.MUTE_ALL);
+    }
+    if (control.properties.muted === false) {
+      requiredHints.push(DISPLAY_HINTS.UNMUTE_ALL);
+    }
+    if (control.properties.disallowUnmute === true) {
+      requiredHints.push(DISPLAY_HINTS.ENABLE_HARD_MUTE);
+    }
+    if (control.properties.disallowUnmute === false) {
+      requiredHints.push(DISPLAY_HINTS.DISABLE_HARD_MUTE);
+    }
+    if (control.properties.muteOnEntry === true) {
+      requiredHints.push(DISPLAY_HINTS.ENABLE_MUTE_ON_ENTRY);
+    }
+    if (control.properties.muteOnEntry === false) {
+      requiredHints.push(DISPLAY_HINTS.DISABLE_MUTE_ON_ENTRY);
+    }
+
+    return Utils.hasHints({requiredHints, displayHints});
+  }
+
+  public static canUpdateRaiseHand(
+    control: ControlConfig<RaiseHandProperties>,
+    displayHints: Array<string>
+  ) {
+    const requiredHints = [];
+
+    if (control.properties.enabled === true) {
+      requiredHints.push(DISPLAY_HINTS.ENABLE_RAISE_HAND);
+    }
+    if (control.properties.enabled === false) {
+      requiredHints.push(DISPLAY_HINTS.DISABLE_RAISE_HAND);
+    }
+
+    return Utils.hasHints({requiredHints, displayHints});
+  }
+
+  /**
+   * Validate if an reactions-scoped control is allowed to be sent to the service.
+   *
+   * @param {ControlConfig<ReactionsProperties>} control - Reaction control config to validate.
+   * @param {Array<string>} displayHints - All available hints.
+   * @returns {boolean} - True if all of the actions are allowed.
+   */
+  public static canUpdateReactions(
+    control: ControlConfig<ReactionsProperties>,
+    displayHints: Array<string>
+  ) {
+    const requiredHints = [];
+
+    // This additional if statement avoids the display hint discrepency due to
+    // the service blocking partial requests with this property only.
+    if (control.properties.showDisplayNameWithReactions !== undefined) {
+      if (control.properties.showDisplayNameWithReactions === true) {
+        requiredHints.push(DISPLAY_HINTS.ENABLE_SHOW_DISPLAY_NAME);
+      }
+      if (control.properties.showDisplayNameWithReactions === false) {
+        requiredHints.push(DISPLAY_HINTS.DISABLE_SHOW_DISPLAY_NAME);
+      }
+    } else {
+      if (control.properties.enabled === true) {
+        requiredHints.push(DISPLAY_HINTS.ENABLE_REACTIONS);
+      }
+      if (control.properties.enabled === false) {
+        requiredHints.push(DISPLAY_HINTS.DISABLE_REACTIONS);
+      }
+    }
+
+    return Utils.hasHints({requiredHints, displayHints});
+  }
+
+  /**
+   * Validate if an share-control-scoped control is allowed to be sent to the service.
+   *
+   * @param {Array<string>} displayHints - All available hints.
+   * @returns {boolean} - True if all of the actions are allowed.
+   */
+  public static canUpdateShareControl(displayHints: Array<string>) {
+    return Utils.hasHints({requiredHints: [DISPLAY_HINTS.SHARE_CONTROL], displayHints});
+  }
+
+  /**
+   * Validate if an view-the-participants-list-scoped control is allowed to be sent to the service.
+   *
+   * @param {ControlConfig<ViewTheParticipantListProperties>} control - View Participants List control config to validate.
+   * @param {Array<string>} displayHints - All available hints.
+   * @returns {boolean} - True if all of the actions are allowed.
+   */
+  public static canUpdateViewTheParticipantsList(
+    control: ControlConfig<ViewTheParticipantListProperties>,
+    displayHints: Array<string>
+  ) {
+    const requiredHints = [];
+
+    if (control.properties.enabled === true) {
+      requiredHints.push(DISPLAY_HINTS.ENABLE_VIEW_THE_PARTICIPANT_LIST);
+    }
+    if (control.properties.enabled === false) {
+      requiredHints.push(DISPLAY_HINTS.DISABLE_VIEW_THE_PARTICIPANT_LIST);
+    }
+
+    return Utils.hasHints({requiredHints, displayHints});
+  }
+
+  /**
+   * Validate if a video-scoped control is allowed to be sent to the service.
+   *
+   * @param {ControlConfig<VideoProperties>} control - Video control config to validate.
+   * @param {Array<string>} displayHints - All available hints.
+   * @returns {boolean} - True if all of the actions are allowed.
+   */
+  public static canUpdateVideo(
+    control: ControlConfig<VideoProperties>,
+    displayHints: Array<string>
+  ) {
+    const requiredHints = [];
+
+    if (control.properties.enabled === true) {
+      requiredHints.push(DISPLAY_HINTS.ENABLE_VIDEO);
+    }
+    if (control.properties.enabled === false) {
+      requiredHints.push(DISPLAY_HINTS.DISABLE_VIDEO);
+    }
+
+    return Utils.hasHints({requiredHints, displayHints});
+  }
+
+  /**
+   * Validate that a control can be sent to the service based on the provided
+   * display hints.
+   *
+   * @param {ControlConfig} control - Control to validate.
+   * @param {Array<string>} displayHints - All available hints.
+   * @returns {boolean} - True if all of the actions are allowed.
+   */
+  public static canUpdate(control: ControlConfig, displayHints: Array<string>) {
+    let determinant: boolean;
+
+    switch (control.scope) {
+      case Control.audio:
+        determinant = Utils.canUpdateAudio(control as ControlConfig<AudioProperties>, displayHints);
+        break;
+
+      case Control.raiseHand:
+        determinant = Utils.canUpdateRaiseHand(
+          control as ControlConfig<RaiseHandProperties>,
+          displayHints
+        );
+        break;
+
+      case Control.reactions:
+        determinant = Utils.canUpdateReactions(
+          control as ControlConfig<ReactionsProperties>,
+          displayHints
+        );
+        break;
+
+      case Control.shareControl:
+        determinant = Utils.canUpdateShareControl(displayHints);
+        break;
+
+      case Control.video:
+        determinant = Utils.canUpdateVideo(control as ControlConfig<VideoProperties>, displayHints);
+        break;
+
+      case Control.viewTheParticipantList:
+        determinant = Utils.canUpdateViewTheParticipantsList(
+          control as ControlConfig<ViewTheParticipantListProperties>,
+          displayHints
+        );
+        break;
+
+      default:
+        determinant = false;
+    }
+
+    return determinant;
+  }
+}
+
+export default Utils;

package/src/index.ts

@@ -0,0 +1,39 @@
+/* eslint-env browser */
+import {registerPlugin} from '@webex/webex-core';
+
+import Meetings from './meetings';
+import config from './config';
+
+registerPlugin('meetings', Meetings, {
+  config,
+});
+
+export {
+  getDevices,
+  LocalTrack,
+  LocalDisplayTrack,
+  LocalSystemAudioTrack,
+  LocalTrackEvents,
+  type TrackMuteEvent,
+  type ServerMuteReason,
+  LocalMicrophoneTrackEvents,
+  LocalCameraTrackEvents,
+  LocalMicrophoneTrack,
+  LocalCameraTrack,
+  createMicrophoneTrack,
+  createCameraTrack,
+  createDisplayTrack,
+  createDisplayTrackWithAudio,
+  FacingMode,
+  DisplaySurface,
+  PresetCameraConstraints,
+} from '@webex/media-helpers';
+
+export default Meetings;
+
+export * as CONSTANTS from './constants';
+export * as REACTIONS from './reactions/reactions';
+
+export {RemoteMedia} from './multistream/remoteMedia';
+
+export {default as TriggerProxy} from './common/events/trigger-proxy';