@webex/plugin-meetings 3.0.0-beta.17 → 3.0.0-beta.170

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,286 @@
+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 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,37 @@
+/* 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,
+  LocalTrackEvents,
+  type TrackMuteEvent,
+  type ServerMuteReason,
+  LocalMicrophoneTrackEvents,
+  LocalCameraTrackEvents,
+  LocalMicrophoneTrack,
+  LocalCameraTrack,
+  createMicrophoneTrack,
+  createCameraTrack,
+  createDisplayTrack,
+  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';

package/src/interpretation/README.md

@@ -0,0 +1,51 @@
+# Simultaneous Interpretation
+
+Simultaneous Interpretation (SI) feature provides support for interpretation of in-meeting audio. The host will specify the target languages at schedule time and assign language pairs to the desired interpreters. Each interpreter will use their client to indicate the language spoken at any point in time. For example, Alice might be translating between English and French. When an English speaker is talking in the meeting, Alice will use her client to indicate she is speaking French. When a French speaker is talking, Alice will indicate that she is speaking English. The host’s client will display the status of each interpreter including the current interpretation direction.
+
+### Structure
+SI languages are available in the siLanguages collection. List the languages which current meeting support to do simultaneous interpretation. Can subscribe the language's voice channel which you want to listen from the list.
+
+```javascript
+interpretation.siLanguages;
+```
+### Attendee functionality
+```javascript
+//subscribe this si language's voice channel
+siLanguage.subscribe();
+
+//unsubscribe this si language's voice channel
+siLanguage.unsubscribe();
+```
+### Host functionality
+The following are methods available to the host of a meeting.
+
+```javascript
+//get the support list of interpretation languages. only host is allowed to call it
+interpretation.getSupportLanguages();
+
+//get the interpreters list of the meeting
+interpretation.getInterpreters();
+
+//update the interpreters list, input parameter is an array of interpreters
+interpretation.updateInterpreters([{
+  sourceLanguage : 'fr-FR',
+  targetLanguage : 'zh-ZH',
+  usingResource : {
+    id : 'a96747e2-1fc6-41d3-9ac7-512dd9478b6e'
+  },
+  order : 0
+},]);
+```
+
+### Interpreter functionality
+
+The following are methods available to the interpreters of a meeting.
+
+```javascript
+//Change direction of interpretation for an interpreter participant
+interpretation.changeDirection();
+
+//Handoff between interpreters, will implement them later
+interpretation.handoff(participantId)
+
+```