@webex/plugin-meetings 3.8.1 → 3.9.0-next.10

package/src/meeting/request.ts

@@ -32,6 +32,7 @@ import {
   BrbOptions,
   ToggleReactionsOptions,
   PostMeetingDataConsentOptions,
+  SynchronizeVideoLayout,
 } from './request.type';
 import MeetingUtil from './util';
 import {AnnotationInfo} from '../annotation/annotation.types';
@@ -969,4 +970,19 @@ export default class MeetingRequest extends StatelessWebexPlugin {
       },
     });
   }
+
+  /**
+   * Synchronize the stage for a meeting
+   *
+   * @param {LocusUrl} locusUrl The locus URL
+   * @param {SetStageVideoLayout} videoLayout The video layout to synchronize
+   * @returns {Promise} The locus request
+   */
+  synchronizeStage(locusUrl: string, videoLayout: SynchronizeVideoLayout) {
+    return this.locusDeltaRequest({
+      method: HTTP_VERBS.PATCH,
+      uri: `${locusUrl}/${CONTROLS}`,
+      body: {videoLayout},
+    });
+  }
 }

package/src/meeting/request.type.ts

@@ -25,3 +25,67 @@ export type PostMeetingDataConsentOptions = {
   deviceUrl: string;
   selfId: string;
 };
+
+export type StageCustomLogoPositions =
+  | 'LowerLeft'
+  | 'LowerMiddle'
+  | 'LowerRight'
+  | 'UpperLeft'
+  | 'UpperMiddle'
+  | 'UpperRight';
+
+export type StageNameLabelType = 'Primary' | 'PrimaryInverted' | 'Secondary' | 'SecondaryInverted';
+
+export type StageCustomBackground = {
+  url: string;
+  [others: string]: unknown;
+};
+
+export type StageCustomLogo = {
+  url: string;
+  position: StageCustomLogoPositions;
+  [others: string]: unknown;
+};
+
+export type StageCustomNameLabel = {
+  accentColor: string;
+  background: {color: string};
+  border: {color: string};
+  content: {displayName: {color: string}; subtitle: {color: string}};
+  decoration: {color: string};
+  fadeOut?: {delay: number};
+  type: StageNameLabelType;
+  [others: string]: unknown;
+};
+
+export type SetStageOptions = {
+  activeSpeakerProportion?: number;
+  customBackground?: StageCustomBackground;
+  customLogo?: StageCustomLogo;
+  customNameLabel?: StageCustomNameLabel;
+  importantParticipants?: {mainCsi: number; participantId: string}[];
+  lockAttendeeViewOnStage?: boolean;
+  showActiveSpeaker?: boolean;
+};
+
+export type SetStageVideoLayout = {
+  overrideDefault: true;
+  lockAttendeeViewOnStageOnly: boolean;
+  stageParameters: {
+    importantParticipants?: {participantId: string; mainCsi: number; order: number}[];
+    showActiveSpeaker: {show: boolean; order: number};
+    activeSpeakerProportion: number;
+    stageManagerType: number;
+  };
+  customLayouts?: {
+    background?: StageCustomBackground;
+    logo?: StageCustomLogo;
+  };
+  nameLabelStyle?: StageCustomNameLabel;
+};
+
+export type UnsetStageVideoLayout = {
+  overrideDefault: false;
+};
+
+export type SynchronizeVideoLayout = SetStageVideoLayout | UnsetStageVideoLayout;

package/src/meeting/type.ts

@@ -0,0 +1,9 @@
+export type Invitee = {
+  memberId: string;
+  emailAddress: string;
+  email: string;
+  phoneNumber: string;
+  roles: Array<string>;
+  skipEmailValidation?: boolean;
+  isInternalNumber?: boolean;
+};

package/src/meeting/util.ts

@@ -197,6 +197,17 @@ const MeetingUtil = {
         });
 
         return parsed;
+      })
+      .catch((err) => {
+        webex.internal.newMetrics.submitClientEvent({
+          name: 'client.locus.join.response',
+          payload: {
+            identifiers: {meetingLookupUrl: meeting.meetingInfo?.meetingLookupUrl},
+          },
+          options: {meetingId: meeting.id, rawError: err},
+        });
+
+        throw err;
       });
   },
 
@@ -208,6 +219,10 @@ const MeetingUtil = {
     meeting.simultaneousInterpretation.cleanUp();
     meeting.locusMediaRequest = undefined;
 
+    meeting.webex?.internal?.newMetrics?.callDiagnosticMetrics?.clearEventLimitsForCorrelationId(
+      meeting.correlationId
+    );
+
     // make sure we send last metrics before we close the peerconnection
     const stopStatsAnalyzer = meeting.statsAnalyzer
       ? meeting.statsAnalyzer.stopAnalyzer()
@@ -328,10 +343,57 @@ const MeetingUtil = {
     meeting.resourceId = meeting.resourceId || options.resourceId;
 
     if (meeting.requiredCaptcha) {
-      return Promise.reject(new CaptchaError());
+      const errorToThrow = new CaptchaError();
+
+      // @ts-ignore
+      webex.internal.newMetrics.submitClientEvent({
+        name: 'client.meetinginfo.response',
+        options: {
+          meetingId: meeting.id,
+        },
+        payload: {
+          errors: [
+            {
+              fatal: false,
+              category: 'expected',
+              name: 'other',
+              shownToUser: false,
+              errorCode: errorToThrow.code,
+              errorDescription: errorToThrow.name,
+              rawErrorMessage: errorToThrow.sdkMessage,
+            },
+          ],
+        },
+      });
+
+      return Promise.reject(errorToThrow);
     }
+
     if (meeting.passwordStatus === PASSWORD_STATUS.REQUIRED) {
-      return Promise.reject(new PasswordError());
+      const errorToThrow = new PasswordError();
+
+      // @ts-ignore
+      webex.internal.newMetrics.submitClientEvent({
+        name: 'client.meetinginfo.response',
+        options: {
+          meetingId: meeting.id,
+        },
+        payload: {
+          errors: [
+            {
+              fatal: false,
+              category: 'expected',
+              name: 'other',
+              shownToUser: false,
+              errorCode: errorToThrow.code,
+              errorDescription: errorToThrow.name,
+              rawErrorMessage: errorToThrow.sdkMessage,
+            },
+          ],
+        },
+      });
+
+      return Promise.reject(errorToThrow);
     }
 
     if (options.pin) {
@@ -542,6 +604,15 @@ const MeetingUtil = {
   canStartManualCaption: (displayHints) =>
     displayHints.includes(DISPLAY_HINTS.MANUAL_CAPTION_START),
 
+  isLocalRecordingStarted: (displayHints) =>
+    displayHints.includes(DISPLAY_HINTS.LOCAL_RECORDING_STATUS_STARTED),
+
+  isLocalRecordingStopped: (displayHints) =>
+    displayHints.includes(DISPLAY_HINTS.LOCAL_RECORDING_STATUS_STOPPED),
+
+  isLocalRecordingPaused: (displayHints) =>
+    displayHints.includes(DISPLAY_HINTS.LOCAL_RECORDING_STATUS_PAUSED),
+
   canStopManualCaption: (displayHints) => displayHints.includes(DISPLAY_HINTS.MANUAL_CAPTION_STOP),
 
   isManualCaptionActive: (displayHints) =>

package/src/meetings/index.ts

@@ -1560,11 +1560,12 @@ export default class Meetings extends WebexPlugin {
       {
         // @ts-ignore
         parent: this.webex,
+      },
+      (newMeeting) => {
+        this.meetingCollection.set(newMeeting);
       }
     );
 
-    this.meetingCollection.set(meeting);
-
     try {
       // if no participant has joined the scheduled meeting (meaning meeting is not active) and we get a locusEvent,
       // it means the meeting will start in 5-6 min. In that case, we want to fetchMeetingInfo

package/src/members/index.ts

@@ -30,6 +30,7 @@ import MembersUtil from './util';
 import {ReceiveSlotManager} from '../multistream/receiveSlotManager';
 import {MediaRequestManager} from '../multistream/mediaRequestManager';
 import {ServerRoleShape} from './types';
+import {Invitee} from '../meeting/type';
 
 /**
  * Members Update Event
@@ -800,18 +801,18 @@ export default class Members extends StatelessWebexPlugin {
 
   /**
    * Adds a guest Member to the associated meeting
-   * @param {String} invitee
+   * @param {Invitee} invitee
    * @param {Boolean} [alertIfActive]
    * @returns {Promise}
    * @memberof Members
    */
-  addMember(invitee: any, alertIfActive?: boolean) {
+  addMember(invitee: Invitee, alertIfActive?: boolean) {
     if (!this.locusUrl) {
       return Promise.reject(
         new ParameterError('The associated locus url for this meeting object must be defined.')
       );
     }
-    if (MembersUtil.isInvalidInvitee(invitee)) {
+    if (invitee?.skipEmailValidation !== true && MembersUtil.isInvalidInvitee(invitee)) {
       return Promise.reject(
         new ParameterError(
           'The invitee must be defined with either a valid email, emailAddress or phoneNumber property.'
@@ -825,11 +826,11 @@ export default class Members extends StatelessWebexPlugin {
 
   /**
    * Cancels an outgoing PSTN call to the associated meeting
-   * @param {String} invitee
+   * @param {Invitee} invitee
    * @returns {Promise}
    * @memberof Members
    */
-  cancelPhoneInvite(invitee: any) {
+  cancelPhoneInvite(invitee: Invitee) {
     if (!this.locusUrl) {
       return Promise.reject(
         new ParameterError('The associated locus url for this meeting object must be defined.')
@@ -846,12 +847,14 @@ export default class Members extends StatelessWebexPlugin {
   }
 
   /**
-   * Cancels an SIP call to the associated meeting
-   * @param {String} invitee
+   * Cancels an SIP/phone call to the associated meeting
+   * @param {Invitee} invitee
+   * @param {String} invitee.memberId - The memberId of the invitee
+   * @param {Boolean} [invitee.isInternalNumber] - When cancel phone invitation, if the number is internal
    * @returns {Promise}
    * @memberof Members
    */
-  cancelSIPInvite(invitee: any) {
+  cancelInviteByMemberId(invitee: Invitee) {
     if (!this.locusUrl) {
       return Promise.reject(
         new ParameterError('The associated locus url for this meeting object must be defined.')
@@ -862,9 +865,9 @@ export default class Members extends StatelessWebexPlugin {
         new ParameterError('The invitee must be defined with a memberId property.')
       );
     }
-    const options = MembersUtil.cancelSIPInviteOptions(invitee, this.locusUrl);
+    const options = MembersUtil.cancelInviteByMemberIdOptions(invitee, this.locusUrl);
 
-    return this.membersRequest.cancelSIPInvite(options);
+    return this.membersRequest.cancelInviteByMemberId(options);
   }
 
   /**
@@ -1178,11 +1181,17 @@ export default class Members extends StatelessWebexPlugin {
    * @param {string} memberId - id of the participant who is receiving request
    * @param {string} requestingParticipantId - id of the participant who is sending request (optional)
    * @param {string} [alias] - alias name
+   * @param {string} [suffix] - name suffix (optional)
    * @returns {Promise}
    * @public
    * @memberof Members
    */
-  public editDisplayName(memberId: string, requestingParticipantId: string, alias: string) {
+  public editDisplayName(
+    memberId: string,
+    requestingParticipantId: string,
+    alias: string,
+    suffix?: string
+  ) {
     if (!this.locusUrl) {
       return Promise.reject(
         new ParameterError(
@@ -1202,7 +1211,8 @@ export default class Members extends StatelessWebexPlugin {
       memberId,
       requestingParticipantId,
       alias,
-      locusUrl
+      locusUrl,
+      suffix
     );
 
     return this.membersRequest.editDisplayNameMember(options);

package/src/members/request.ts

@@ -285,14 +285,14 @@ export default class MembersRequest extends StatelessWebexPlugin {
    * @throws {Error} if the options are not valid and complete, must have invitee with memberId AND locusUrl
    * @memberof MembersRequest
    */
-  cancelSIPInvite(options: any) {
+  cancelInviteByMemberId(options: any) {
     if (!options?.invitee?.memberId || !options?.locusUrl) {
       throw new ParameterError(
         'invitee must be passed and the associated locus url for this meeting object must be defined.'
       );
     }
 
-    const requestParams = MembersUtil.generateCancelSIPInviteRequestParams(options);
+    const requestParams = MembersUtil.generateCancelInviteByMemberIdRequestParams(options);
 
     return this.locusDeltaRequest(requestParams);
   }

package/src/members/util.ts

@@ -1,4 +1,5 @@
 import uuid from 'uuid';
+import {has} from 'lodash';
 import {
   HTTP_VERBS,
   CONTROLS,
@@ -13,6 +14,7 @@ import {
 } from '../constants';
 
 import {RoleAssignmentOptions, RoleAssignmentRequest, ServerRoleShape} from './types';
+import {Invitee} from '../meeting/type';
 
 const MembersUtil = {
   /**
@@ -47,6 +49,9 @@ const MembersUtil = {
         address:
           options.invitee.emailAddress || options.invitee.email || options.invitee.phoneNumber,
         ...(options.invitee.roles ? {roles: options.invitee.roles} : {}),
+        ...(has(options.invitee, 'isInternalNumber')
+          ? {isInternalNumber: options.invitee.isInternalNumber}
+          : {}),
       },
     ],
     alertIfActive: options.alertIfActive,
@@ -101,12 +106,16 @@ const MembersUtil = {
     return requestParams;
   },
 
-  isInvalidInvitee: (invitee) => {
+  isInvalidInvitee: (invitee: Invitee) => {
     if (!(invitee && (invitee.email || invitee.emailAddress || invitee.phoneNumber))) {
       return true;
     }
 
     if (invitee.phoneNumber) {
+      if (invitee.isInternalNumber) {
+        return !DIALER_REGEX.INTERNAL_NUMBER.test(invitee.phoneNumber);
+      }
+
       return !DIALER_REGEX.E164_FORMAT.test(invitee.phoneNumber);
     }
 
@@ -181,13 +190,21 @@ const MembersUtil = {
    * @param {String} requestingParticipantId id of the participant who is sending request (optional)
    * @param {String} alias alias name
    * @param {String} locusUrl url
+   * @param {String} suffix optional suffix
    * @returns {Object} consists of {memberID: string, requestingParticipantId: string, alias: string, locusUrl: string}
    */
-  generateEditDisplayNameMemberOptions: (memberId, requestingParticipantId, alias, locusUrl) => ({
+  generateEditDisplayNameMemberOptions: (
+    memberId,
+    requestingParticipantId,
+    alias,
+    locusUrl,
+    suffix
+  ) => ({
     memberId,
     requestingParticipantId,
     alias,
     locusUrl,
+    suffix,
   }),
 
   getMuteMemberRequestParams: (options) => {
@@ -292,10 +309,18 @@ const MembersUtil = {
    * @returns {Object} request parameters (method, uri, body) needed to make a editDisplayName request
    */
   editDisplayNameMemberRequestParams: (options) => {
-    const body = {
+    const body: {
+      aliasValue: string;
+      requestingParticipantId: string;
+      suffixValue?: string;
+    } = {
       aliasValue: options.alias,
       requestingParticipantId: options.requestingParticipantId,
     };
+
+    if (options.suffix !== undefined) {
+      body.suffixValue = options.suffix;
+    }
     const uri = `${options.locusUrl}/${PARTICIPANT}/${options.memberId}/${ALIAS}`;
 
     return {
@@ -371,17 +396,20 @@ const MembersUtil = {
     return requestParams;
   },
 
-  cancelSIPInviteOptions: (invitee, locusUrl) => ({
+  cancelInviteByMemberIdOptions: (invitee, locusUrl) => ({
     invitee,
     locusUrl,
   }),
 
-  generateCancelSIPInviteRequestParams: (options) => {
+  generateCancelInviteByMemberIdRequestParams: (options) => {
+    const {memberId, isInternalNumber} = options.invitee;
+    const hasIsInternalNumberProp = has(options.invitee, 'isInternalNumber');
     const body = {
       actionType: _REMOVE_,
       invitees: [
         {
-          address: options.invitee.memberId,
+          address: memberId,
+          ...(hasIsInternalNumberProp ? {isInternalNumber} : {}),
         },
       ],
     };

package/src/metrics/constants.ts

@@ -72,6 +72,7 @@ const BEHAVIORAL_METRICS = {
   MEETING_INFO_POLICY_ERROR: 'js_sdk_meeting_info_policy_error',
   LOCUS_DELTA_SYNC_FAILED: 'js_sdk_locus_delta_sync_failed',
   LOCUS_DELTA_OUT_OF_ORDER: 'js_sdk_locus_delta_ooo',
+  LOCUS_SYNC_HANDLING_FAILED: 'js_sdk_locus_sync_handling_failed',
   PERMISSION_TOKEN_REFRESH: 'js_sdk_permission_token_refresh',
   PERMISSION_TOKEN_REFRESH_ERROR: 'js_sdk_permission_token_refresh_error',
   TURN_DISCOVERY_LATENCY: 'js_sdk_turn_discovery_latency',

package/src/multistream/mediaRequestManager.ts

@@ -15,7 +15,7 @@ import {cloneDeepWith, debounce, isEmpty} from 'lodash';
 import LoggerProxy from '../common/logs/logger-proxy';
 
 import {ReceiveSlot, ReceiveSlotEvents} from './receiveSlot';
-import {getMaxFs} from './remoteMedia';
+import {MAX_FS_VALUES} from './remoteMedia';
 
 export interface ActiveSpeakerPolicyInfo {
   policy: 'active-speaker';
@@ -123,12 +123,12 @@ export class MediaRequestManager {
 
   private getDegradedClientRequests(clientRequests: ClientRequestsMap) {
     const maxFsLimits = [
-      getMaxFs('best'),
-      getMaxFs('large'),
-      getMaxFs('medium'),
-      getMaxFs('small'),
-      getMaxFs('very small'),
-      getMaxFs('thumbnail'),
+      MAX_FS_VALUES['1080p'],
+      MAX_FS_VALUES['720p'],
+      MAX_FS_VALUES['540p'],
+      MAX_FS_VALUES['360p'],
+      MAX_FS_VALUES['180p'],
+      MAX_FS_VALUES['90p'],
     ];
 
     // reduce max-fs until total macroblocks is below limit

package/src/multistream/remoteMedia.ts

@@ -19,17 +19,18 @@ export type RemoteVideoResolution =
   | 'large' // 1080p or less
   | 'best'; // highest possible resolution
 
-const MAX_FS_VALUES = {
+export const MAX_FS_VALUES = {
   '90p': 60,
   '180p': 240,
   '360p': 920,
+  '540p': 2040,
   '720p': 3600,
   '1080p': 8192,
 };
 
 /**
  * Converts pane size into h264 maxFs
- * @param {PaneSize} paneSize
+ * @param {RemoteVideoResolution} paneSize
  * @returns {number}
  */
 export function getMaxFs(paneSize: RemoteVideoResolution): number {
@@ -89,6 +90,13 @@ export class RemoteMedia extends EventsScope {
 
   public readonly id: RemoteMediaId;
 
+  /**
+   * The max frame size of the media request, used for logging and media requests.
+   * Set by setSizeHint() based on video element dimensions.
+   * When > 0, this value takes precedence over options.resolution in sendMediaRequest().
+   */
+  private maxFrameSize = 0;
+
   /**
    * Constructs RemoteMedia instance
    *
@@ -136,15 +144,34 @@ export class RemoteMedia extends EventsScope {
       fs = MAX_FS_VALUES['180p'];
     } else if (height < getThresholdHeight(360)) {
       fs = MAX_FS_VALUES['360p'];
+    } else if (height < getThresholdHeight(540)) {
+      fs = MAX_FS_VALUES['540p'];
     } else if (height <= 720) {
       fs = MAX_FS_VALUES['720p'];
     } else {
       fs = MAX_FS_VALUES['1080p'];
     }
 
+    this.maxFrameSize = fs;
     this.receiveSlot?.setMaxFs(fs);
   }
 
+  /**
+   * Get the current effective maxFs value that would be used in media requests
+   * @returns {number | undefined} The maxFs value, or undefined if no constraints
+   */
+  public getEffectiveMaxFs(): number | undefined {
+    if (this.maxFrameSize > 0) {
+      return this.maxFrameSize;
+    }
+
+    if (this.options.resolution) {
+      return getMaxFs(this.options.resolution);
+    }
+
+    return undefined;
+  }
+
   /**
    * Invalidates the remote media by clearing the reference to a receive slot and
    * cancelling the media request.
@@ -185,6 +212,9 @@ export class RemoteMedia extends EventsScope {
       throw new Error('sendMediaRequest() called on an invalidated RemoteMedia instance');
     }
 
+    // Use maxFrameSize from setSizeHint if available, otherwise fallback to options.resolution
+    const maxFs = this.getEffectiveMaxFs();
+
     this.mediaRequestId = this.mediaRequestManager.addRequest(
       {
         policyInfo: {
@@ -192,9 +222,9 @@ export class RemoteMedia extends EventsScope {
           csi,
         },
         receiveSlots: [this.receiveSlot],
-        codecInfo: this.options.resolution && {
+        codecInfo: maxFs && {
           codec: 'h264',
-          maxFs: getMaxFs(this.options.resolution),
+          maxFs,
         },
       },
       commit

package/src/multistream/remoteMediaGroup.ts

@@ -215,6 +215,9 @@ export class RemoteMediaGroup {
   private sendActiveSpeakerMediaRequest(commit: boolean) {
     this.cancelActiveSpeakerMediaRequest(false);
 
+    // Calculate the effective maxFs based on all unpinned RemoteMedia instances
+    const effectiveMaxFs = this.getEffectiveMaxFsForActiveSpeaker();
+
     this.mediaRequestId = this.mediaRequestManager.addRequest(
       {
         policyInfo: {
@@ -230,9 +233,9 @@ export class RemoteMediaGroup {
         receiveSlots: this.unpinnedRemoteMedia.map((remoteMedia) =>
           remoteMedia.getUnderlyingReceiveSlot()
         ) as ReceiveSlot[],
-        codecInfo: this.options.resolution && {
+        codecInfo: effectiveMaxFs && {
           codec: 'h264',
-          maxFs: getMaxFs(this.options.resolution),
+          maxFs: effectiveMaxFs,
         },
       },
       commit
@@ -300,4 +303,36 @@ export class RemoteMediaGroup {
       this.unpinnedRemoteMedia.includes(remoteMedia) || this.pinnedRemoteMedia.includes(remoteMedia)
     );
   }
+
+  /**
+   * Calculate the effective maxFs for the active speaker media request based on unpinned RemoteMedia instances
+   * @returns {number | undefined} The calculated maxFs value, or undefined if no constraints
+   * @private
+   */
+  private getEffectiveMaxFsForActiveSpeaker(): number | undefined {
+    // Get all effective maxFs values from unpinned RemoteMedia instances
+    const maxFsValues = this.unpinnedRemoteMedia
+      .map((remoteMedia) => remoteMedia.getEffectiveMaxFs())
+      .filter((maxFs) => maxFs !== undefined);
+
+    // Use the highest maxFs value to ensure we don't under-request resolution for any instance
+    if (maxFsValues.length > 0) {
+      return Math.max(...maxFsValues);
+    }
+
+    // Fall back to group's resolution option
+    if (this.options.resolution) {
+      return getMaxFs(this.options.resolution);
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Get the current effective maxFs that would be used for the active speaker media request
+   * @returns {number | undefined} The effective maxFs value
+   */
+  public getEffectiveMaxFs(): number | undefined {
+    return this.getEffectiveMaxFsForActiveSpeaker();
+  }
 }