@webex/plugin-meetings 2.60.0 → 2.60.1-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,44 @@
+/* eslint-env browser */
+import {registerPlugin} from '@webex/webex-core';
+
+import Meetings from './meetings';
+import config from './config';
+import {LocusRetryStatusInterceptor} from './interceptors';
+
+registerPlugin('meetings', Meetings, {
+  config,
+  interceptors: {
+    LocusRetryStatusInterceptor: LocusRetryStatusInterceptor.create,
+  },
+});
+
+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/interceptors/index.ts

@@ -0,0 +1,3 @@
+import LocusRetryStatusInterceptor from './locusRetry';
+
+export {LocusRetryStatusInterceptor};

package/src/interceptors/locusRetry.ts

@@ -0,0 +1,67 @@
+/*!
+ * Copyright (c) 2015-2020 Cisco Systems, Inc. See LICENSE file.
+ */
+
+import {Interceptor} from '@webex/http-core';
+
+const rateLimitExpiryTime = new WeakMap();
+/**
+ * @class
+ */
+export default class LocusRetryStatusInterceptor extends Interceptor {
+  /**
+   * @returns {LocusRetryStatusInterceptor}
+   */
+  static create() {
+    // @ts-ignore
+    return new LocusRetryStatusInterceptor({webex: this});
+  }
+
+  /**
+   * Handle response errors
+   * @param {Object} options
+   * @param {WebexHttpError} reason
+   * @returns {Promise<WebexHttpError>}
+   */
+  onResponseError(options, reason) {
+    if ((reason.statusCode === 503 || reason.statusCode === 429) && options.uri.includes('locus')) {
+      const hasRetriedLocusRequest = rateLimitExpiryTime.get(this);
+      const retryAfterTime = options.headers['retry-after'] || 2000;
+
+      if (hasRetriedLocusRequest) {
+        rateLimitExpiryTime.set(this, false);
+
+        return Promise.reject(options);
+      }
+      rateLimitExpiryTime.set(this, true);
+
+      return this.handleRetryRequestLocusServiceError(options, retryAfterTime);
+    }
+
+    return Promise.reject(reason);
+  }
+
+  /**
+   * Handle retries for locus service unavailable errors
+   * @param {Object} options associated with the request
+   * @param {number} retryAfterTime retry after time in milliseconds
+   * @returns {Promise}
+   */
+  handleRetryRequestLocusServiceError(options, retryAfterTime) {
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        clearTimeout(timeout);
+
+        // @ts-ignore
+        this.webex
+          .request({
+            method: options.method,
+            uri: options.uri,
+            body: options.body,
+          })
+          .then(resolve)
+          .catch(reject);
+      }, retryAfterTime);
+    });
+  }
+}