@webex/plugin-meetings 2.59.8 → 2.60.0-next.2

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

@@ -3,7 +3,8 @@ 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 Setting from './enums';
+import {Control, Setting} from './enums';
+import {ControlConfig} from './types';
 import Util from './util';
 import {CAN_SET, CAN_UNSET, ENABLED} from './constants';
 
@@ -133,32 +134,106 @@ export default class ControlsOptionsManager {
     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
-   * @param {boolean} enabled
    * @private
    * @memberof ControlsOptionsManager
    * @returns {Promise}
    */
-  private setControls(setting: Setting, enabled: boolean): Promise<any> {
-    LoggerProxy.logger.log(`ControlsOptionsManager:index#setControls --> ${setting} [${enabled}]`);
-
-    if (Util?.[`${enabled ? CAN_SET : CAN_UNSET}${setting}`](this.displayHints)) {
-      // @ts-ignore
-      return this.request.request({
-        uri: `${this.locusUrl}/${CONTROLS}`,
-        body: {
-          [camelCase(setting)]: {
-            [ENABLED]: enabled,
-          },
-        },
-        method: HTTP_VERBS.PATCH,
-      });
+  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);
     }
 
-    return Promise.reject(
-      new PermissionError(`${setting} [${enabled}] not allowed, due to moderator property.`)
-    );
+    // @ts-ignore
+    return this.request.request({
+      uri: `${this.locusUrl}/${CONTROLS}`,
+      body,
+      method: HTTP_VERBS.PATCH,
+    });
   }
 
   /**
@@ -168,7 +243,7 @@ export default class ControlsOptionsManager {
    * @returns {Promise}
    */
   public setMuteOnEntry(enabled: boolean): Promise<any> {
-    return this.setControls(Setting.muteOnEntry, enabled);
+    return this.setControls({[Setting.muteOnEntry]: enabled});
   }
 
   /**
@@ -178,6 +253,26 @@ export default class ControlsOptionsManager {
    * @returns {Promise}
    */
   public setDisallowUnmute(enabled: boolean): Promise<any> {
-    return this.setControls(Setting.disallowUnmute, enabled);
+    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

@@ -1,20 +1,300 @@
 import {DISPLAY_HINTS} from '../constants';
+import {Control} from './enums';
+import {
+  ControlConfig,
+  AudioProperties,
+  RaiseHandProperties,
+  ReactionsProperties,
+  ViewTheParticipantListProperties,
+  VideoProperties,
+} from './types';
 
-const canSetMuteOnEntry = (displayHints: Array<string>): boolean =>
-  displayHints.includes(DISPLAY_HINTS.ENABLE_MUTE_ON_ENTRY);
+/**
+ * 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);
+  }
 
-const canSetDisallowUnmute = (displayHints: Array<string>): boolean =>
-  displayHints.includes(DISPLAY_HINTS.ENABLE_HARD_MUTE);
+  /**
+   * 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);
+  }
 
-const canUnsetMuteOnEntry = (displayHints: Array<string>): boolean =>
-  displayHints.includes(DISPLAY_HINTS.DISABLE_MUTE_ON_ENTRY);
+  /**
+   * 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);
+  }
 
-const canUnsetDisallowUnmute = (displayHints: Array<string>): boolean =>
-  displayHints.includes(DISPLAY_HINTS.DISABLE_HARD_MUTE);
+  /**
+   * 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);
+  }
 
-export default {
-  canSetMuteOnEntry,
-  canSetDisallowUnmute,
-  canUnsetMuteOnEntry,
-  canUnsetDisallowUnmute,
-};
+  /**
+   * 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,40 @@
+/* eslint-env browser */
+import {registerPlugin} from '@webex/webex-core';
+
+import Meetings from './meetings';
+import config from './config';
+
+registerPlugin('meetings', Meetings, {
+  config,
+});
+
+export {
+  getDevices,
+  LocalStream,
+  LocalDisplayStream,
+  LocalSystemAudioStream,
+  LocalStreamEventNames,
+  StreamEventNames,
+  type ServerMuteReason,
+  LocalMicrophoneStreamEventNames,
+  LocalCameraStreamEventNames,
+  LocalMicrophoneStream,
+  LocalCameraStream,
+  createMicrophoneStream,
+  createCameraStream,
+  createDisplayStream,
+  createDisplayStreamWithAudio,
+  FacingMode,
+  DisplaySurface,
+  PresetCameraConstraints,
+  type VideoContentHint,
+} 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,60 @@
+# 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, input paramerter participantId is the target to handoff
+interpretation.handoffInterpreter(participantId);
+
+//in-active interpreter request to handoff to self
+interpretation.requestHandoff();
+
+//accept the request of handoff, input paramter url is from last approval event which generate by server side
+interpretation.acceptRequest(url);
+
+//decline the request of handoff, input paramter url is from last approval event which generate by server side
+interpretation.declineRequest(url);
+
+```

package/src/interpretation/collection.ts

@@ -0,0 +1,19 @@
+/*!
+ * Copyright (c) 2015-2023 Cisco Systems, Inc. See LICENSE file.
+ */
+
+import AmpCollection from 'ampersand-collection';
+
+import {MEETINGS} from '../constants';
+
+import SILanguage from './siLanguage';
+
+const SILanguageCollection = AmpCollection.extend({
+  model: SILanguage,
+
+  namespace: MEETINGS,
+
+  mainIndex: 'languageName',
+});
+
+export default SILanguageCollection;