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

package/src/meetings/index.ts

@@ -1,13 +1,17 @@
 /* eslint no-shadow: ["error", { "allow": ["eventType"] }] */
 
 import '@webex/internal-plugin-mercury';
+import '@webex/internal-plugin-conversation';
+import '@webex/internal-plugin-metrics';
 // @ts-ignore
 import {WebexPlugin} from '@webex/webex-core';
+import {setLogger} from '@webex/internal-media-core';
+
+import * as mediaHelpersModule from '@webex/media-helpers';
 
 import 'webrtc-adapter';
 
 import Metrics from '../metrics';
-import {trigger, eventType} from '../metrics/config';
 import LoggerConfig from '../common/logs/logger-config';
 import StaticConfig from '../common/config';
 import LoggerProxy from '../common/logs/logger-proxy';
@@ -38,11 +42,14 @@ import {
   MEETING_REMOVED_REASON,
   _CONVERSATION_URL_,
   CONVERSATION_URL,
+  MEETINGNUMBER,
+  _JOINED_,
+  _MOVED_,
 } from '../constants';
 import BEHAVIORAL_METRICS from '../metrics/constants';
 import MeetingInfo from '../meeting-info';
 import MeetingInfoV2 from '../meeting-info/meeting-info-v2';
-import Meeting from '../meeting';
+import Meeting, {CallStateForMetrics} from '../meeting';
 import PersonalMeetingRoom from '../personal-meeting-room';
 import Reachability from '../reachability';
 import Request from './request';
@@ -51,7 +58,38 @@ import CaptchaError from '../common/errors/captcha-error';
 
 import MeetingCollection from './collection';
 import MeetingsUtil from './util';
+import PermissionError from '../common/errors/permission';
+import {INoiseReductionEffect, IVirtualBackgroundEffect} from './meetings.types';
+import {SpaceIDDeprecatedError} from '../common/errors/webex-errors';
+import NoMeetingInfoError from '../common/errors/no-meeting-info';
+
+let mediaLogger;
+
+class MediaLogger {
+  info(...args) {
+    LoggerProxy.logger.info(...args);
+  }
 
+  log(...args) {
+    LoggerProxy.logger.log(...args);
+  }
+
+  error(...args) {
+    LoggerProxy.logger.error(...args);
+  }
+
+  warn(...args) {
+    LoggerProxy.logger.warn(...args);
+  }
+
+  trace(...args) {
+    LoggerProxy.logger.trace(...args);
+  }
+
+  debug(...args) {
+    LoggerProxy.logger.debug(...args);
+  }
+}
 /**
  * Meetings Ready Event
  * Emitted when the meetings instance on webex is ready
@@ -110,12 +148,13 @@ export default class Meetings extends WebexPlugin {
   meetingCollection: any;
   personalMeetingRoom: any;
   preferredWebexSite: any;
-  reachability: any;
+  reachability: Reachability;
   registered: any;
   request: any;
   geoHintInfo: any;
   meetingInfo: any;
-
+  mediaHelpers: any;
+  breakoutLocusForHandleLater: any;
   namespace = MEETINGS;
 
   /**
@@ -127,6 +166,17 @@ export default class Meetings extends WebexPlugin {
   constructor(...args) {
     super(...args);
 
+    /**
+     * The webrtc-core media helpers. This is a temporary solution required for the SDK sample app
+     * to be able to call media helper functions.
+     *
+     * @instance
+     * @type {Object}
+     * @private
+     * @memberof Meetings
+     */
+    this.mediaHelpers = mediaHelpersModule;
+
     /**
      * The Meetings request to interact with server
      * @instance
@@ -154,15 +204,17 @@ export default class Meetings extends WebexPlugin {
      * @memberof Meetings
      */
     this.personalMeetingRoom = null;
+
     /**
-     * The Reachability object to interact with server, starts as null until {@link Meeting#setReachability} is called
+     * The Reachability object to interact with server
      * starts as null
      * @instance
      * @type {Object}
      * @private
      * @memberof Meetings
      */
-    this.reachability = null;
+    // @ts-ignore
+    this.reachability = new Reachability(this.webex);
 
     /**
      * If the meetings plugin has been registered and listening via {@link Meetings#register}
@@ -192,30 +244,137 @@ export default class Meetings extends WebexPlugin {
      */
     this.media = {
       getUserMedia: Media.getUserMedia,
-      getSupportedDevice: Media.getSupportedDevice,
     };
 
     this.onReady();
   }
 
   /**
-   * handle locus events and takes meeting actions with them as they come in
+   * check whether you need to handle this main session's locus data or not
+   * @param {Object} meeting current meeting data
+   * @param {Object} newLocus new locus data
+   * @returns {boolean}
+   * @private
+   * @memberof Meetings
+   */
+  private isNeedHandleMainLocus(meeting: any, newLocus: any) {
+    const breakoutUrl = newLocus.controls?.breakout?.url;
+    const breakoutLocus = this.meetingCollection.getActiveBreakoutLocus(breakoutUrl);
+
+    const isSelfJoined = newLocus?.self?.state === _JOINED_;
+    const isSelfMoved = newLocus?.self?.state === _LEFT_ && newLocus?.self?.reason === _MOVED_;
+    // @ts-ignore
+    const deviceFromNewLocus = MeetingsUtil.getThisDevice(newLocus, this.webex.internal.device.url);
+    const isResourceMovedOnThisDevice =
+      deviceFromNewLocus?.state === _LEFT_ && deviceFromNewLocus?.reason === _MOVED_;
+
+    const isNewLocusJoinThisDevice = MeetingsUtil.joinedOnThisDevice(
+      meeting,
+      newLocus,
+      // @ts-ignore
+      this.webex.internal.device.url
+    );
+    const isBreakoutLocusJoinThisDevice =
+      breakoutLocus?.joinedWith?.correlationId &&
+      breakoutLocus.joinedWith.correlationId === meeting?.correlationId;
+
+    if (isSelfJoined && isNewLocusJoinThisDevice) {
+      LoggerProxy.logger.log(
+        'Meetings:index#isNeedHandleMainLocus --> self this device shown as JOINED in the main session'
+      );
+      if (breakoutLocus?.joinedWith && deviceFromNewLocus) {
+        const breakoutReplaceAt =
+          breakoutLocus.joinedWith.replaces?.length > 0
+            ? breakoutLocus.joinedWith.replaces[0].replaceAt
+            : '';
+        const newLocusReplaceAt =
+          deviceFromNewLocus.replaces?.length > 0 ? deviceFromNewLocus.replaces[0].replaceAt : '';
+        if (breakoutReplaceAt && newLocusReplaceAt && breakoutReplaceAt > newLocusReplaceAt) {
+          LoggerProxy.logger.log(
+            `Meetings:index#isNeedHandleMainLocus --> this is expired main joined status locus_dto replacedAt ${newLocusReplaceAt} bo replacedAt ${breakoutReplaceAt}`
+          );
+
+          return false;
+        }
+      }
+
+      return true;
+    }
+    if (isBreakoutLocusJoinThisDevice) {
+      LoggerProxy.logger.log(
+        `Meetings:index#isNeedHandleMainLocus --> there is active breakout session and joined on this device, and don't need to handle main session: ${breakoutUrl}`
+      );
+
+      return false;
+    }
+    if (isSelfMoved && (newLocus?.self?.removed || isResourceMovedOnThisDevice)) {
+      LoggerProxy.logger.log(
+        'Meetings:index#isNeedHandleMainLocus --> self moved main locus with self removed status or with device resource moved, not need to handle'
+      );
+
+      return false;
+    }
+    if (isSelfJoined && isResourceMovedOnThisDevice) {
+      LoggerProxy.logger.log(
+        'Meetings:index#isNeedHandleMainLocus --> self device left&moved in main locus with self joined status, not need to handle'
+      );
+
+      return false;
+    }
+    LoggerProxy.logger.log(
+      'Meetings:index#isNeedHandleMainLocus --> this is a normal main session locusDTO update case'
+    );
+
+    return true;
+  }
+
+  /**
+   * check whether you need to handle this locus data or not
+   * @param {Object} meeting old locus data
+   * @param {Object} newLocus new locus data
+   * @returns {boolean}
+   * @private
+   * @memberof Meetings
+   */
+  private isNeedHandleLocusDTO(meeting: any, newLocus: any) {
+    if (newLocus) {
+      const isNewLocusAsBreakout = MeetingsUtil.isBreakoutLocusDTO(newLocus);
+      const isSelfMoved = newLocus?.self?.state === _LEFT_ && newLocus?.self?.reason === _MOVED_;
+      if (!meeting) {
+        if (isNewLocusAsBreakout) {
+          LoggerProxy.logger.log(
+            `Meetings:index#isNeedHandleLocusDTO --> the first breakout session locusDTO active status: ${newLocus.fullState?.active}`
+          );
+
+          return newLocus.self?.state === _JOINED_;
+        }
+
+        return this.isNeedHandleMainLocus(meeting, newLocus);
+      }
+      if (!isNewLocusAsBreakout) {
+        return this.isNeedHandleMainLocus(meeting, newLocus);
+      }
+
+      return !isSelfMoved;
+    }
+
+    return true;
+  }
+
+  /**
+   * get corresponding meeting object by locus data
    * @param {Object} data a locus event
    * @param {String} data.locusUrl
    * @param {Object} data.locus
-   * @param {Boolean} useRandomDelayForInfo whether a random delay should be added to fetching meeting info
-   * @param {String} data.eventType
-   * @returns {undefined}
+   * @returns {Object}
    * @private
    * @memberof Meetings
    */
-  private handleLocusEvent(data: {locusUrl: string; locus: any}, useRandomDelayForInfo = false) {
-    let meeting = null;
-
+  getCorrespondingMeetingByLocus(data) {
     // getting meeting by correlationId. This will happen for the new event
     // Either the locus
     // TODO : Add check for the callBack Address
-    meeting =
+    return (
       this.meetingCollection.getByKey(LOCUS_URL, data.locusUrl) ||
       // @ts-ignore
       this.meetingCollection.getByKey(
@@ -231,7 +390,24 @@ export default class Meetings extends WebexPlugin {
       ) ||
       (data.locus.info?.isUnifiedSpaceMeeting
         ? undefined
-        : this.meetingCollection.getByKey(CONVERSATION_URL, data.locus.conversationUrl));
+        : this.meetingCollection.getByKey(CONVERSATION_URL, data.locus.conversationUrl)) ||
+      this.meetingCollection.getByKey(MEETINGNUMBER, data.locus?.info?.webExMeetingId)
+    );
+  }
+
+  /**
+   * handle locus events and takes meeting actions with them as they come in
+   * @param {Object} data a locus event
+   * @param {String} data.locusUrl
+   * @param {Object} data.locus
+   * @param {Boolean} useRandomDelayForInfo whether a random delay should be added to fetching meeting info
+   * @param {String} data.eventType
+   * @returns {undefined}
+   * @private
+   * @memberof Meetings
+   */
+  private handleLocusEvent(data: {locusUrl: string; locus: any}, useRandomDelayForInfo = false) {
+    let meeting = this.getCorrespondingMeetingByLocus(data);
 
     // Special case when locus has got replaced, This only happend once if a replace locus exists
     // https://sqbu-github.cisco.com/WebExSquared/locus/wiki/Locus-changing-mid-call
@@ -244,6 +420,16 @@ export default class Meetings extends WebexPlugin {
       );
     }
 
+    if (meeting && !MeetingsUtil.isBreakoutLocusDTO(data.locus)) {
+      meeting.locusInfo.updateMainSessionLocusCache(data.locus);
+    }
+    if (!this.isNeedHandleLocusDTO(meeting, data.locus)) {
+      LoggerProxy.logger.log(
+        `Meetings:index#handleLocusEvent --> doesn't need to process locus event`
+      );
+
+      return;
+    }
     if (!meeting) {
       // TODO: create meeting when we get a meeting object
       // const checkForEnded = (locus) => {
@@ -300,6 +486,7 @@ export default class Meetings extends WebexPlugin {
 
           // It's a new meeting so initialize the locus data
           meeting.locusInfo.initialSetup(data.locus);
+          this.checkHandleBreakoutLocus(data.locus);
         })
         .catch((e) => {
           LoggerProxy.logger.error(e);
@@ -309,10 +496,15 @@ export default class Meetings extends WebexPlugin {
           // because the other user left so before sending 'added' event make sure it exists in the collection
 
           if (this.getMeetingByType(_ID_, meeting.id)) {
-            Metrics.postEvent({
-              event: eventType.REMOTE_STARTED,
-              meeting,
-              data: {trigger: trigger.MERCURY_EVENT},
+            // @ts-ignore
+            this.webex.internal.newMetrics.submitClientEvent({
+              name: 'client.call.remote-started',
+              payload: {
+                trigger: 'mercury-event',
+              },
+              options: {
+                meetingId: meeting.id,
+              },
             });
             Trigger.trigger(
               this,
@@ -431,6 +623,9 @@ export default class Meetings extends WebexPlugin {
       // @ts-ignore
       LoggerProxy.set(this.webex.logger);
 
+      mediaLogger = new MediaLogger();
+      setLogger(mediaLogger);
+
       /**
        * The MeetingInfo object to interact with server
        * @instance
@@ -462,7 +657,7 @@ export default class Meetings extends WebexPlugin {
 
       MeetingsUtil.checkH264Support({disableNotifications: true});
       // @ts-ignore
-      Metrics.initialSetup(this.meetingCollection, this.webex);
+      Metrics.initialSetup(this.webex);
     });
   }
 
@@ -486,21 +681,6 @@ export default class Meetings extends WebexPlugin {
     }
   }
 
-  /**
-   * API to enable or disable TURN discovery
-   * @param {Boolean} enable
-   * @private
-   * @memberof Meetings
-   * @returns {undefined}
-   */
-  private _toggleTurnDiscovery(enable: boolean) {
-    if (typeof enable !== 'boolean') {
-      return;
-    }
-    // @ts-ignore
-    this.config.experimental.enableTurnDiscovery = enable;
-  }
-
   /**
    * API to toggle starting adhoc meeting
    * @param {Boolean} changeState
@@ -631,6 +811,36 @@ export default class Meetings extends WebexPlugin {
     );
   }
 
+  /**
+   * Creates a noise reduction effect
+   *
+   * @param {INoiseReductionEffect} options optional custom effect options
+   * @returns {Promise<effect>} noise reduction effect.
+   * @public
+   * @memberof Meetings
+   */
+  createNoiseReductionEffect = async (options?: INoiseReductionEffect) => {
+    // @ts-ignore
+    const authToken = this.webex.credentials.supertoken.access_token;
+
+    return new mediaHelpersModule.NoiseReductionEffect({authToken, ...options});
+  };
+
+  /**
+   * Creates a virtual background effect
+   *
+   * @param {IVirtualBackgroundEffect} options optional custom effect options
+   * @returns {Promise<effect>} virtual background effect.
+   * @public
+   * @memberof Meetings
+   */
+  createVirtualBackgroundEffect = async (options?: IVirtualBackgroundEffect) => {
+    // @ts-ignore
+    const authToken = this.webex.credentials.supertoken.access_token;
+
+    return new mediaHelpersModule.VirtualBackgroundEffect({authToken, ...options});
+  };
+
   /**
    * Uploads logs to the webex services for tracking
    * @param {Object} [options={}]
@@ -645,8 +855,10 @@ export default class Meetings extends WebexPlugin {
    */
   uploadLogs(
     options: {
+      autoupload?: boolean;
       callStart?: string;
       feedbackId?: string;
+      locussessionid?: string;
       locusId?: string;
       correlationId?: string;
       meetingId?: string;
@@ -663,6 +875,7 @@ export default class Meetings extends WebexPlugin {
           'Meetings:index#uploadLogs --> Upload logs for meeting completed.',
           uploadResult
         );
+        Metrics.sendBehavioralMetric(BEHAVIORAL_METRICS.UPLOAD_LOGS_SUCCESS, options);
         Trigger.trigger(
           this,
           {
@@ -697,8 +910,7 @@ export default class Meetings extends WebexPlugin {
         );
 
         Metrics.sendBehavioralMetric(BEHAVIORAL_METRICS.UPLOAD_LOGS_FAILURE, {
-          // @ts-ignore - seems like typo
-          meetingId: options.meetingsId,
+          ...options,
           reason: uploadError.message,
           stack: uploadError.stack,
           code: uploadError.code,
@@ -706,17 +918,6 @@ export default class Meetings extends WebexPlugin {
       });
   }
 
-  /**
-   * initializes the reachability instance for Meetings
-   * @returns {undefined}
-   * @public
-   * @memberof Meetings
-   */
-  setReachability() {
-    // @ts-ignore
-    this.reachability = new Reachability(this.webex);
-  }
-
   /**
    * gets the reachability instance for Meetings
    * @returns {Reachability}
@@ -734,10 +935,6 @@ export default class Meetings extends WebexPlugin {
    * @memberof Meetings
    */
   startReachability() {
-    if (!this.reachability) {
-      this.setReachability();
-    }
-
     return this.getReachability().gatherReachability();
   }
 
@@ -765,6 +962,29 @@ export default class Meetings extends WebexPlugin {
       if (res) {
         this.preferredWebexSite = MeetingsUtil.parseDefaultSiteFromMeetingPreferences(res);
       }
+
+      // fall back to getting the preferred site from the user information
+      if (!this.preferredWebexSite) {
+        // @ts-ignore
+        return this.webex.internal.user
+          .get()
+          .then((user) => {
+            const preferredWebexSite =
+              user?.userPreferences?.userPreferencesItems?.preferredWebExSite;
+            if (preferredWebexSite) {
+              this.preferredWebexSite = preferredWebexSite;
+            } else {
+              throw new Error('site not found');
+            }
+          })
+          .catch(() => {
+            LoggerProxy.logger.error(
+              'Failed to fetch preferred site from user - no site will be set'
+            );
+          });
+      }
+
+      return Promise.resolve();
     });
   }
 
@@ -805,29 +1025,48 @@ export default class Meetings extends WebexPlugin {
   }
 
   /**
-   * Create a meeting.
-   * @param {string} destination - sipURL, spaceId, phonenumber, or locus object}
+   * Create a meeting or return an existing meeting.
+   * @param {string} destination - sipURL, phonenumber, or locus object}
    * @param {string} [type] - the optional specified type, such as locusId
    * @param {Boolean} useRandomDelayForInfo - whether a random delay should be added to fetching meeting info
+   * @param {Object} infoExtraParams extra parameters to be provided when fetching meeting info
+   * @param {string} correlationId - the optional specified correlationId (callStateForMetrics.correlationId can be provided instead)
+   * @param {Boolean} failOnMissingMeetingInfo - whether to throw an error if meeting info fails to fetch (for calls that are not 1:1 or content share)
+   * @param {CallStateForMetrics} callStateForMetrics - information about call state for metrics
    * @returns {Promise<Meeting>} A new Meeting.
    * @public
    * @memberof Meetings
    */
-  public create(destination: string, type: string = null, useRandomDelayForInfo = false) {
+  public create(
+    destination: string,
+    type: string = null,
+    useRandomDelayForInfo = false,
+    infoExtraParams = {},
+    correlationId: string = undefined,
+    failOnMissingMeetingInfo = false,
+    callStateForMetrics: CallStateForMetrics = undefined
+  ) {
     // TODO: type should be from a dictionary
 
     // Validate meeting information based on the provided destination and
     // type. This must be performed prior to determining if the meeting is
     // found in the collection, as we mutate the destination for hydra person
     // id values.
+    if (correlationId) {
+      callStateForMetrics = {...(callStateForMetrics || {}), correlationId};
+    }
+
     return (
       this.meetingInfo
         .fetchInfoOptions(destination, type)
         // Catch a failure to fetch info options.
         .catch((error) => {
-          LoggerProxy.logger.info(
-            `Meetings:index#create --> INFO, unable to determine info options: ${error.message}`
+          LoggerProxy.logger.error(
+            `Meetings:index#create --> ERROR, unable to determine info options: ${error.message}`
           );
+          if (error instanceof SpaceIDDeprecatedError) {
+            throw new SpaceIDDeprecatedError();
+          }
         })
         .then((options: any = {}) => {
           // Normalize the destination.
@@ -858,49 +1097,59 @@ export default class Meetings extends WebexPlugin {
           // Validate if a meeting was found.
           if (!meeting) {
             // Create a meeting based on the normalized destination and type.
-            return this.createMeeting(targetDest, type, useRandomDelayForInfo).then(
-              (createdMeeting: any) => {
-                // If the meeting was successfully created.
-                if (createdMeeting && createdMeeting.on) {
-                  // Create a destruction event for the meeting.
-                  createdMeeting.on(EVENTS.DESTROY_MEETING, (payload) => {
-                    // @ts-ignore
-                    if (this.config.autoUploadLogs) {
-                      this.uploadLogs({
-                        callStart: createdMeeting.locusInfo?.fullState?.lastActive,
-                        correlationId: createdMeeting.correlationId,
-                        feedbackId: createdMeeting.correlationId,
-                        locusId: createdMeeting.locusId,
-                        meetingId: createdMeeting.locusInfo?.info?.webExMeetingId,
-                      }).then(() => this.destroy(createdMeeting, payload.reason));
-                    } else {
-                      this.destroy(createdMeeting, payload.reason);
-                    }
-                  });
-
-                  createdMeeting.on(EVENTS.REQUEST_UPLOAD_LOGS, (meetingInstance) => {
-                    // @ts-ignore
-                    if (this.config.autoUploadLogs) {
-                      this.uploadLogs({
-                        callStart: meetingInstance?.locusInfo?.fullState?.lastActive,
-                        correlationId: meetingInstance.correlationId,
-                        feedbackId: meetingInstance.correlationId,
-                        locusId: meetingInstance.locusId,
-                        meetingId: meetingInstance.locusInfo?.info?.webExMeetingId,
-                      });
-                    }
-                  });
-                } else {
-                  LoggerProxy.logger.error(
-                    `Meetings:index#create --> ERROR, meeting does not have on method, will not be destroyed, meeting cleanup impossible for meeting: ${meeting}`
-                  );
-                }
-
-                // Return the newly created meeting.
-                return Promise.resolve(createdMeeting);
+            return this.createMeeting(
+              targetDest,
+              type,
+              useRandomDelayForInfo,
+              infoExtraParams,
+              callStateForMetrics,
+              failOnMissingMeetingInfo
+            ).then((createdMeeting: any) => {
+              // If the meeting was successfully created.
+              if (createdMeeting && createdMeeting.on) {
+                // Create a destruction event for the meeting.
+                createdMeeting.on(EVENTS.DESTROY_MEETING, (payload) => {
+                  // @ts-ignore
+                  if (this.config.autoUploadLogs) {
+                    this.uploadLogs({
+                      callStart: createdMeeting.locusInfo?.fullState?.lastActive,
+                      locussessionid: createdMeeting.locusInfo?.fullState?.sessionId,
+                      correlationId: createdMeeting.correlationId,
+                      feedbackId: createdMeeting.correlationId,
+                      locusId: createdMeeting.locusId,
+                      meetingId: createdMeeting.locusInfo?.info?.webExMeetingId,
+                      autoupload: true,
+                    }).then(() => this.destroy(createdMeeting, payload.reason));
+                  } else {
+                    this.destroy(createdMeeting, payload.reason);
+                  }
+                });
+
+                createdMeeting.on(EVENTS.REQUEST_UPLOAD_LOGS, (meetingInstance) => {
+                  // @ts-ignore
+                  if (this.config.autoUploadLogs) {
+                    this.uploadLogs({
+                      callStart: meetingInstance?.locusInfo?.fullState?.lastActive,
+                      locussessionid: meetingInstance?.locusInfo?.fullState?.sessionId,
+                      correlationId: meetingInstance.correlationId,
+                      feedbackId: meetingInstance.correlationId,
+                      locusId: meetingInstance.locusId,
+                      meetingId: meetingInstance.locusInfo?.info?.webExMeetingId,
+                      autoupload: true,
+                    });
+                  }
+                });
+              } else {
+                LoggerProxy.logger.error(
+                  `Meetings:index#create --> ERROR, meeting does not have on method, will not be destroyed, meeting cleanup impossible for meeting: ${meeting}`
+                );
               }
-            );
+
+              // Return the newly created meeting.
+              return Promise.resolve(createdMeeting);
+            });
           }
+          meeting.setCallStateForMetrics(callStateForMetrics);
 
           // Return the existing meeting.
           return Promise.resolve(meeting);
@@ -912,6 +1161,9 @@ export default class Meetings extends WebexPlugin {
    * @param {String} destination see create()
    * @param {String} type see create()
    * @param {Boolean} useRandomDelayForInfo whether a random delay should be added to fetching meeting info
+   * @param {Object} infoExtraParams extra parameters to be provided when fetching meeting info
+   * @param {CallStateForMetrics} callStateForMetrics - information about call state for metrics
+   * @param {Boolean} failOnMissingMeetingInfo - whether to throw an error if meeting info fails to fetch (for calls that are not 1:1 or content share)
    * @returns {Promise} a new meeting instance complete with meeting info and destination
    * @private
    * @memberof Meetings
@@ -919,7 +1171,10 @@ export default class Meetings extends WebexPlugin {
   private async createMeeting(
     destination: any,
     type: string = null,
-    useRandomDelayForInfo = false
+    useRandomDelayForInfo = false,
+    infoExtraParams = {},
+    callStateForMetrics: CallStateForMetrics = undefined,
+    failOnMissingMeetingInfo = false
   ) {
     const meeting = new Meeting(
       {
@@ -929,11 +1184,11 @@ export default class Meetings extends WebexPlugin {
         deviceUrl: this.webex.internal.device.url,
         // @ts-ignore
         orgId: this.webex.internal.device.orgId,
-        roapSeq: 0,
         locus: type === _LOCUS_ID_ ? destination : null, // pass the locus object if present
         meetingInfoProvider: this.meetingInfo,
         destination,
         destinationType: type,
+        callStateForMetrics,
       },
       {
         // @ts-ignore
@@ -968,19 +1223,38 @@ export default class Meetings extends WebexPlugin {
 
       if (enableUnifiedMeetings && !isMeetingActive && useRandomDelayForInfo && waitingTime > 0) {
         meeting.fetchMeetingInfoTimeoutId = setTimeout(
-          () => meeting.fetchMeetingInfo({}),
+          () =>
+            meeting.fetchMeetingInfo({
+              extraParams: infoExtraParams,
+              sendCAevents: !!callStateForMetrics?.correlationId, // if client sends correlation id as argument of public create(), then it means that this meeting creation is part of a pre-join intent from user
+            }),
           waitingTime
         );
         meeting.parseMeetingInfo(undefined, destination);
       } else {
-        await meeting.fetchMeetingInfo({});
+        await meeting.fetchMeetingInfo({
+          extraParams: infoExtraParams,
+          sendCAevents: !!callStateForMetrics?.correlationId, // if client sends correlation id as argument of public create(), then it means that this meeting creation is part of a pre-join intent from user
+        });
       }
     } catch (err) {
-      if (!(err instanceof CaptchaError) && !(err instanceof PasswordError)) {
-        // if there is no meeting info we assume its a 1:1 call or wireless share
+      if (
+        !(err instanceof CaptchaError) &&
+        !(err instanceof PasswordError) &&
+        !(err instanceof PermissionError)
+      ) {
         LoggerProxy.logger.info(
           `Meetings:index#createMeeting --> Info Unable to fetch meeting info for ${destination}.`
         );
+        if (failOnMissingMeetingInfo) {
+          LoggerProxy.logger.info(
+            `Meetings:index#createMeeting --> Destroying meeting due to missing meeting info.`
+          );
+          // @ts-ignore
+          this.destroy(meeting, MEETING_REMOVED_REASON.MISSING_MEETING_INFO);
+          throw new NoMeetingInfoError();
+        }
+        // if there is no meeting info and no error should be thrown then we assume its a 1:1 call or wireless share
         LoggerProxy.logger.info(
           'Meetings:index#createMeeting --> Info assuming this destination is a 1:1 or wireless share'
         );
@@ -1033,7 +1307,7 @@ export default class Meetings extends WebexPlugin {
     //
     // Our job is to determine the appropriate one
     // and its corresponding service so that developers
-    // need only sipURL or spaceID to get a meeting
+    // need only sipURL to get a meeting
     // and its ID, but have the option to use createWithType()
     // and specify those types to get meetingInfo
   }
@@ -1077,33 +1351,108 @@ export default class Meetings extends WebexPlugin {
    * @memberof Meetings
    */
   public syncMeetings() {
-    return this.request.getActiveMeetings().then((locusArray) => {
-      const activeLocusUrl = [];
-
-      if (locusArray?.loci && locusArray.loci.length > 0) {
-        locusArray.loci.forEach((locus) => {
-          activeLocusUrl.push(locus.url);
-          this.handleLocusEvent({
-            locus,
-            locusUrl: locus.url,
+    return this.request
+      .getActiveMeetings()
+      .then((locusArray) => {
+        const activeLocusUrl = [];
+
+        if (locusArray?.loci && locusArray.loci.length > 0) {
+          const lociToUpdate = this.sortLocusArrayToUpdate(locusArray.loci);
+          lociToUpdate.forEach((locus) => {
+            activeLocusUrl.push(locus.url);
+            this.handleLocusEvent({
+              locus,
+              locusUrl: locus.url,
+            });
           });
-        });
-      }
-      const meetingsCollection = this.meetingCollection.getAll();
+        }
+        const meetingsCollection = this.meetingCollection.getAll();
 
-      if (Object.keys(meetingsCollection).length > 0) {
-        // Some time the mercury event is missed after mercury reconnect
-        // if sync returns no locus then clear all the meetings
-        for (const meeting of Object.values(meetingsCollection)) {
-          // @ts-ignore
-          if (!activeLocusUrl.includes(meeting.locusUrl)) {
-            // destroy function also uploads logs
+        if (Object.keys(meetingsCollection).length > 0) {
+          // Some time the mercury event is missed after mercury reconnect
+          // if sync returns no locus then clear all the meetings
+          for (const meeting of Object.values(meetingsCollection)) {
             // @ts-ignore
-            this.destroy(meeting, MEETING_REMOVED_REASON.NO_MEETINGS_TO_SYNC);
+            if (!activeLocusUrl.includes(meeting.locusUrl)) {
+              // destroy function also uploads logs
+              // @ts-ignore
+              this.destroy(meeting, MEETING_REMOVED_REASON.NO_MEETINGS_TO_SYNC);
+            }
           }
         }
+      })
+      .catch((error) => {
+        LoggerProxy.logger.error(
+          `Meetings:index#syncMeetings --> failed to sync meetings, ${error}`
+        );
+        throw new Error(error);
+      });
+  }
+
+  /**
+   * sort out locus array for initial creating
+   * @param {Array} loci original locus array
+   * @returns {undefined}
+   * @public
+   * @memberof Meetings
+   */
+  sortLocusArrayToUpdate(loci: any[]) {
+    const mainLoci = loci.filter((locus) => !MeetingsUtil.isBreakoutLocusDTO(locus));
+    const breakoutLoci = loci.filter((locus) => MeetingsUtil.isValidBreakoutLocus(locus));
+    this.breakoutLocusForHandleLater = [];
+    const lociToUpdate = [...mainLoci];
+    breakoutLoci.forEach((breakoutLocus) => {
+      const associateMainLocus = mainLoci.find(
+        (mainLocus) => mainLocus.controls?.breakout?.url === breakoutLocus.controls?.breakout?.url
+      );
+      const existCorrespondingMeeting = this.getCorrespondingMeetingByLocus({
+        locus: breakoutLocus,
+        locusUrl: breakoutLocus.url,
+      });
+
+      if (associateMainLocus && !existCorrespondingMeeting) {
+        // if exists both main session and breakout session locus of the same non-exist meeting, handle main locus first,
+        // after meeting create with main locus, then handle the associate breakout locus.
+        // if only handle breakout locus, will miss some date
+        this.breakoutLocusForHandleLater.push(breakoutLocus);
+      } else {
+        lociToUpdate.push(breakoutLocus);
       }
     });
+
+    return lociToUpdate;
+  }
+
+  /**
+   * check breakout locus which waiting for main locus's meeting to be created, then handle the breakout locus
+   * @param {Object} newCreatedLocus the locus which just create meeting object of it
+   * @returns {undefined}
+   * @public
+   * @memberof Meetings
+   */
+  checkHandleBreakoutLocus(newCreatedLocus) {
+    if (
+      !newCreatedLocus ||
+      !this.breakoutLocusForHandleLater ||
+      !this.breakoutLocusForHandleLater.length
+    ) {
+      return;
+    }
+    if (MeetingsUtil.isBreakoutLocusDTO(newCreatedLocus)) {
+      return;
+    }
+    const existIndex = this.breakoutLocusForHandleLater.findIndex(
+      (breakoutLocus) =>
+        breakoutLocus.controls?.breakout?.url === newCreatedLocus.controls?.breakout?.url
+    );
+
+    if (existIndex < 0) {
+      return;
+    }
+
+    const associateBreakoutLocus = this.breakoutLocusForHandleLater[existIndex];
+    this.handleLocusEvent({locus: associateBreakoutLocus, locusUrl: associateBreakoutLocus.url});
+    this.breakoutLocusForHandleLater.splice(existIndex, 1);
   }
 
   /**
@@ -1125,4 +1474,15 @@ export default class Meetings extends WebexPlugin {
   getLogger() {
     return LoggerProxy.get();
   }
+
+  /**
+   * Returns the first meeting it finds that has the webrtc media connection created.
+   * Useful for debugging in the console.
+   *
+   * @private
+   * @returns {Meeting} Meeting object that has a webrtc media connection, else undefined
+   */
+  getActiveWebrtcMeeting() {
+    return this.meetingCollection.getActiveWebrtcMeeting();
+  }
 }