@webex/plugin-meetings 3.12.0-next.10 → 3.12.0-next.12

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

@@ -1,6 +1,6 @@
 import {camelCase} from 'lodash';
+import ParameterError from '../common/errors/parameter';
 import PermissionError from '../common/errors/permission';
-import {CONTROLS, HTTP_VERBS} from '../constants';
 import MeetingRequest from '../meeting/request';
 import LoggerProxy from '../common/logs/logger-proxy';
 import {Control, Setting} from './enums';
@@ -153,6 +153,12 @@ export default class ControlsOptionsManager {
    * @returns {Promise<Array<any>>}- Promise resolving if the request was successful.
    */
   public update(...controls: Array<ControlConfig>) {
+    if (!this.locusUrl) {
+      return Promise.reject(
+        new ParameterError('The associated locusUrl for update() controls must be defined.')
+      );
+    }
+
     const payloads = controls.map((control) => {
       if (!Object.keys(Control).includes(control.scope)) {
         throw new Error(
@@ -172,18 +178,15 @@ export default class ControlsOptionsManager {
     });
 
     return payloads.reduce((previous, payload) => {
-      const extraBody =
-        this.mainLocusUrl && this.mainLocusUrl !== this.locusUrl
-          ? {authorizingLocusUrl: this.locusUrl}
-          : {};
+      const requestParams = Util.getControlsRequestParams({
+        body: payload,
+        locusUrl: this.locusUrl,
+        mainLocusUrl: this.mainLocusUrl,
+      });
 
       return previous.then(() =>
         // @ts-ignore
-        this.request.request({
-          uri: `${this.mainLocusUrl || this.locusUrl}/${CONTROLS}`,
-          body: {...payload, ...extraBody},
-          method: HTTP_VERBS.PATCH,
-        })
+        this.request.request(requestParams)
       );
     }, Promise.resolve());
   }
@@ -200,6 +203,12 @@ export default class ControlsOptionsManager {
     [Setting.muteOnEntry]?: boolean;
     [Setting.roles]?: Array<string>;
   }): Promise<any> {
+    if (!this.locusUrl) {
+      return Promise.reject(
+        new ParameterError('The associated locusUrl for setControls() must be defined.')
+      );
+    }
+
     LoggerProxy.logger.log(
       `ControlsOptionsManager:index#setControls --> ${JSON.stringify(setting)}`
     );
@@ -258,17 +267,15 @@ export default class ControlsOptionsManager {
     if (error) {
       return Promise.reject(error);
     }
-    const extraBody =
-      this.mainLocusUrl && this.mainLocusUrl !== this.locusUrl
-        ? {authorizingLocusUrl: this.locusUrl}
-        : {};
 
-    // @ts-ignore
-    return this.request.request({
-      uri: `${this.mainLocusUrl || this.locusUrl}/${CONTROLS}`,
-      body: {...body, ...extraBody},
-      method: HTTP_VERBS.PATCH,
+    const requestParams = Util.getControlsRequestParams({
+      body,
+      locusUrl: this.locusUrl,
+      mainLocusUrl: this.mainLocusUrl,
     });
+
+    // @ts-ignore
+    return this.request.request(requestParams);
   }
 
   /**

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

@@ -1,5 +1,6 @@
-import {DISPLAY_HINTS} from '../constants';
+import {CONTROLS, DISPLAY_HINTS, HTTP_VERBS} from '../constants';
 import {Control} from './enums';
+import {AUDIO_CONTROL_BODY_KEYS} from './constants';
 import {
   ControlConfig,
   AudioProperties,
@@ -400,6 +401,85 @@ class Utils {
 
     return determinant;
   }
+
+  /**
+   * Check if all body keys represent audio controls.
+   *
+   * @param {Record<string, any>} body - The request body to inspect.
+   * @returns {boolean} - True if every key in the body is an audio control key.
+   */
+  public static isAudioControl(body: Record<string, any>): boolean {
+    return Object.keys(body).every((key) => AUDIO_CONTROL_BODY_KEYS.has(key));
+  }
+
+  /**
+   * Check if the current locus URL differs from the main locus URL,
+   * indicating a breakout session.
+   *
+   * @param {string} locusUrl - The current locus URL.
+   * @param {string} [mainLocusUrl] - The main locus URL.
+   * @returns {boolean} - True if in a breakout session.
+   */
+  public static isBreakoutLocusUrl(locusUrl: string, mainLocusUrl?: string): boolean {
+    return Boolean(mainLocusUrl) && mainLocusUrl !== locusUrl;
+  }
+
+  /**
+   * Resolve the target URL and extra body fields for a controls request,
+   * handling breakout session routing. Note: This is a pure computation function.
+   * It does not validate that locusUrl is
+   * defined. Callers must guard against falsy locusUrl before
+   * invoking this function.
+   * Mixed audio and non-audio keys in a single body (e.g., {audio: {...},
+   * raiseHand: {...}}) are treated as non-audio and routed to mainLocusUrl with
+   * authorizingLocusUrl. This means the audio portion would go through unsupported
+   * cross-locus authorization. Callers must not produce mixed payloads — update()
+   * sends each control scope as a separate request, and setControls() only handles
+   * audio-related settings.
+   *
+   * The authorizingLocusUrl mechanism on PATCH /loci/{lid}/controls is not supported
+   * for audio control updates (mute/unmute, muteOnEntry, disallowUnmute).
+   * Audio controls are not wired into the cross-locus GraphQL authorization path that
+   * other control types (raiseHand, viewParticipantList, admit, reactions, etc.) use.
+   * Specifically, the GraphQL authorization layer does not recognize audio as a control
+   * type eligible for remote locus authorization.
+   * This means authorizingLocusUrl is effectively ignored for audio controls and the
+   * server evaluates the request against the target locus only, where the host may not
+   * be currently joined.
+   * Audio control updates must be sent directly to the locus the user is currently in.
+   * If the host is in a breakout and wants to mute participants in that breakout, the
+   * request should target the breakout locus URL directly, not the main session locus
+   * with authorizingLocusUrl.
+   * Meeting-wide audio control actions (e.g., muting panelists across all breakouts
+   * from a single request) are not currently supported through this mechanism.
+   *
+   * @param {object} options
+   * @param {Record<string, any>} options.body - The request body.
+   * @param {string} options.locusUrl - The current locus URL. Must be defined (callers must validate).
+   * @param {string} [options.mainLocusUrl] - The main locus URL.
+   * @returns {{ uri: string, body: Record<string, any>, method: string }}
+   */
+  public static getControlsRequestParams(options: {
+    body: Record<string, any>;
+    locusUrl: string;
+    mainLocusUrl?: string;
+  }): {
+    uri: string;
+    body: Record<string, any>;
+    method: string;
+  } {
+    const {body, locusUrl, mainLocusUrl} = options;
+
+    const isAudio = Utils.isAudioControl(body);
+    const inBreakout = Utils.isBreakoutLocusUrl(locusUrl, mainLocusUrl);
+    const targetUrl = inBreakout && !isAudio ? mainLocusUrl : locusUrl;
+
+    return {
+      uri: `${targetUrl}/${CONTROLS}`,
+      body: inBreakout && !isAudio ? {...body, authorizingLocusUrl: locusUrl} : body,
+      method: HTTP_VERBS.PATCH,
+    };
+  }
 }
 
 export default Utils;

package/src/hashTree/hashTreeParser.ts

@@ -57,10 +57,15 @@ export const LocusInfoUpdateType = {
 } as const;
 
 export type LocusInfoUpdateType = Enum<typeof LocusInfoUpdateType>;
-export type LocusInfoUpdateCallback = (
-  updateType: LocusInfoUpdateType,
-  data?: {updatedObjects: HashTreeObject[]}
-) => void;
+export type LocusInfoUpdate =
+  | {
+      updateType: typeof LocusInfoUpdateType.OBJECTS_UPDATED;
+      updatedObjects: HashTreeObject[];
+    }
+  | {
+      updateType: typeof LocusInfoUpdateType.MEETING_ENDED;
+    };
+export type LocusInfoUpdateCallback = (update: LocusInfoUpdate) => void;
 
 interface LeafInfo {
   type: ObjectType;
@@ -227,7 +232,7 @@ class HashTreeParser {
   private initializeNewVisibleDataSet(
     visibleDataSetInfo: VisibleDataSetInfo,
     dataSetInfo: DataSet
-  ): Promise<{updateType: LocusInfoUpdateType; updatedObjects?: HashTreeObject[]}> {
+  ): Promise<LocusInfoUpdate> {
     if (this.isVisibleDataSet(dataSetInfo.name)) {
       LoggerProxy.logger.info(
         `HashTreeParser#initializeNewVisibleDataSet --> ${this.debugId} Data set "${dataSetInfo.name}" already exists, skipping init`
@@ -264,7 +269,7 @@ class HashTreeParser {
   private sendInitializationSyncRequestToLocus(
     datasetName: string,
     debugText: string
-  ): Promise<{updateType: LocusInfoUpdateType; updatedObjects?: HashTreeObject[]}> {
+  ): Promise<LocusInfoUpdate> {
     const dataset = this.dataSets[datasetName];
 
     if (!dataset) {
@@ -272,7 +277,7 @@ class HashTreeParser {
         `HashTreeParser#sendInitializationSyncRequestToLocus --> ${this.debugId} No data set found for ${datasetName}, cannot send the request for leaf data`
       );
 
-      return Promise.resolve(null);
+      return Promise.resolve({updateType: LocusInfoUpdateType.OBJECTS_UPDATED, updatedObjects: []});
     }
 
     const emptyLeavesData = new Array(dataset.leafCount).fill([]);
@@ -1014,7 +1019,7 @@ class HashTreeParser {
 
     // when we detect new visible datasets, it may be that the metadata about them is not
     // available in the message, they will require separate async initialization
-    let dataSetsRequiringInitialization = [];
+    let dataSetsRequiringInitialization: VisibleDataSetInfo[] = [];
 
     // first find out if there are any visible data set changes - they're signalled in Metadata object updates
     const metadataUpdates = (message.locusStateElements || []).filter((object) =>
@@ -1022,7 +1027,7 @@ class HashTreeParser {
     );
 
     if (metadataUpdates.length > 0) {
-      const updatedMetadataObjects = [];
+      const updatedMetadataObjects: HashTreeObject[] = [];
 
       metadataUpdates.forEach((object) => {
         // todo: once Locus supports it, we will use the "view" field here instead of dataSetNames
@@ -1051,7 +1056,7 @@ class HashTreeParser {
       }
     }
 
-    if (message.locusStateElements?.length > 0) {
+    if (message.locusStateElements && message.locusStateElements.length > 0) {
       // by this point we now have this.dataSets setup for data sets from this message
       // and hash trees created for the new visible data sets,
       // so we can now process all the updates from the message
@@ -1147,20 +1152,17 @@ class HashTreeParser {
    * @param {Object} updates parsed from a Locus message
    * @returns {void}
    */
-  private callLocusInfoUpdateCallback(updates: {
-    updateType: LocusInfoUpdateType;
-    updatedObjects?: HashTreeObject[];
-  }) {
+  private callLocusInfoUpdateCallback(updates: LocusInfoUpdate) {
     if (this.state === 'stopped') {
       return;
     }
 
-    const {updateType, updatedObjects} = updates;
+    const {updateType} = updates;
 
-    if (updateType === LocusInfoUpdateType.OBJECTS_UPDATED && updatedObjects?.length > 0) {
+    if (updateType === LocusInfoUpdateType.OBJECTS_UPDATED && updates.updatedObjects?.length > 0) {
       // Filter out updates for objects that already have a higher version in their datasets,
       // or removals for objects that still exist in any of their datasets
-      const filteredUpdates = updatedObjects.filter((object) => {
+      const filteredUpdates = updates.updatedObjects.filter((object) => {
         const {elementId} = object.htMeta;
         const {type, id, version} = elementId;
 
@@ -1197,10 +1199,10 @@ class HashTreeParser {
       });
 
       if (filteredUpdates.length > 0) {
-        this.locusInfoUpdateCallback(updateType, {updatedObjects: filteredUpdates});
+        this.locusInfoUpdateCallback({updateType, updatedObjects: filteredUpdates});
       }
     } else if (updateType !== LocusInfoUpdateType.OBJECTS_UPDATED) {
-      this.locusInfoUpdateCallback(updateType, {updatedObjects});
+      this.locusInfoUpdateCallback({updateType});
     }
   }
 
@@ -1457,6 +1459,16 @@ class HashTreeParser {
     this.state = 'stopped';
   }
 
+  /**
+   * Cleans up the HashTreeParser, stopping all timers and clearing all internal state.
+   * After calling this, the parser should not be used anymore.
+   * @returns {void}
+   */
+  public cleanUp() {
+    this.stop();
+    this.dataSets = {};
+  }
+
   /**
    * Resumes the HashTreeParser that was previously stopped.
    * @param {HashTreeMessage} message - The message to resume with, it must contain metadata with visible data sets info
@@ -1591,15 +1603,20 @@ class HashTreeParser {
     );
 
     const url = `${dataSet.url}/sync`;
-    const body = {
+    const body: {
+      leafCount: number;
+      leafDataEntries: {leafIndex: number; elementIds: LeafDataItem[]}[];
+    } = {
       leafCount: dataSet.leafCount,
       leafDataEntries: [],
     };
 
     Object.keys(mismatchedLeavesData).forEach((index) => {
+      const leafIndex = parseInt(index, 10);
+
       body.leafDataEntries.push({
-        leafIndex: parseInt(index, 10),
-        elementIds: mismatchedLeavesData[index],
+        leafIndex,
+        elementIds: mismatchedLeavesData[leafIndex],
       });
     });
 

package/src/locus-info/index.ts

@@ -34,6 +34,7 @@ import BEHAVIORAL_METRICS from '../metrics/constants';
 import HashTreeParser, {
   DataSet,
   HashTreeMessage,
+  LocusInfoUpdate,
   LocusInfoUpdateType,
   Metadata,
 } from '../hashTree/hashTreeParser';
@@ -545,7 +546,7 @@ export default class LocusInfo extends EventsScope {
       dataSets: Array<DataSet>;
       locus: any;
     };
-    metadata: Metadata;
+    metadata: Metadata | null;
     replacedAt?: string;
   }): HashTreeParser {
     const parser = new HashTreeParser({
@@ -553,7 +554,7 @@ export default class LocusInfo extends EventsScope {
       metadata,
       webexRequest: this.webex.request.bind(this.webex),
       locusInfoUpdateCallback: this.updateFromHashTree.bind(this, locusUrl),
-      debugId: `HT-${locusUrl.split('/').pop().substring(0, 4)}`,
+      debugId: `HT-${locusUrl.split('/')?.pop()?.substring(0, 4)}`,
       excludedDataSets: this.webex.config.meetings.locus?.excludedDataSets,
     });
 
@@ -656,7 +657,7 @@ export default class LocusInfo extends EventsScope {
           );
           // first create the HashTreeParser, but don't initialize it with any data yet
           const hashTreeParser = this.createHashTreeParser({
-            locusUrl: data.locus.url,
+            locusUrl: data.locus.url as string,
             initialLocus: {
               locus: null,
               dataSets: [], // empty, because we don't have them yet
@@ -965,7 +966,7 @@ export default class LocusInfo extends EventsScope {
       // but it's buried inside the message, we need to find it and pass it to HashTreeParser constructor
       const metadata = message.locusStateElements?.find((el) => isMetadata(el));
 
-      if (metadata?.data?.visibleDataSets?.length > 0) {
+      if (metadata && metadata.data?.visibleDataSets?.length > 0) {
         LoggerProxy.logger.info(
           `Locus-info:index#handleHashTreeParserSwitch --> no hash tree parser found for locusUrl ${message.locusUrl}, creating a new one`
         );
@@ -1056,7 +1057,10 @@ export default class LocusInfo extends EventsScope {
 
     const entry = this.hashTreeParsers.get(message.locusUrl);
 
-    entry.parser.handleMessage(message);
+    // the check is just for typescript, the case of no entry in hashTreeParsers is handled in handleHashTreeParserSwitch() above
+    if (entry) {
+      entry.parser.handleMessage(message);
+    }
   }
 
   /**
@@ -1064,16 +1068,11 @@ export default class LocusInfo extends EventsScope {
    * Updates our locus info based on the data parsed by the hash tree parser.
    *
    * @param {string} locusUrl - the locus URL for which the update is received
-   * @param {LocusInfoUpdateType} updateType - The type of update received.
-   * @param {Object} [data] - Additional data for the update, if applicable.
+   * @param {LocusInfoUpdate} update - Details about the update.
    * @returns {void}
    */
-  private updateFromHashTree(
-    locusUrl: string,
-    updateType: LocusInfoUpdateType,
-    data?: {updatedObjects: HashTreeObject[]}
-  ) {
-    switch (updateType) {
+  private updateFromHashTree(locusUrl: string, update: LocusInfoUpdate) {
+    switch (update.updateType) {
       case LocusInfoUpdateType.OBJECTS_UPDATED: {
         // initialize our new locus
         let locus: LocusDTO = {
@@ -1087,7 +1086,7 @@ export default class LocusInfo extends EventsScope {
         // first go over all the updates and check what happens with the main locus object
         let locusObjectStateAfterUpdates: LocusObjectStateAfterUpdates =
           LocusObjectStateAfterUpdates.unchanged;
-        data.updatedObjects.forEach((object) => {
+        update.updatedObjects.forEach((object) => {
           if (object.htMeta.elementId.type.toLowerCase() === ObjectType.locus) {
             if (locusObjectStateAfterUpdates === LocusObjectStateAfterUpdates.updated) {
               // this code doesn't supported it right now,
@@ -1116,6 +1115,14 @@ export default class LocusInfo extends EventsScope {
 
         const hashTreeParserEntry = this.hashTreeParsers.get(locusUrl);
 
+        if (!hashTreeParserEntry) {
+          LoggerProxy.logger.warn(
+            `Locus-info:index#updateFromHashTree --> no HashTreeParser found for locusUrl ${locusUrl} when trying to apply updates from hash tree`
+          );
+
+          return;
+        }
+
         if (!hashTreeParserEntry.initializedFromHashTree) {
           // this is the first time we're getting an update for this locusUrl,
           // so it's probably a move to/from breakout. We need to start from a clean state,
@@ -1124,7 +1131,8 @@ export default class LocusInfo extends EventsScope {
             `Locus-info:index#updateFromHashTree --> first INITIAL update for locusUrl ${locusUrl}, starting from empty state`
           );
           hashTreeParserEntry.initializedFromHashTree = true;
-          locus.jsSdkMeta.forceReplaceMembers = true;
+          // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+          locus.jsSdkMeta!.forceReplaceMembers = true;
         } else if (
           // if Locus object is unchanged or removed, we need to keep using the existing locus
           // because the rest of the locusInfo code expects locus to always be present (with at least some of the fields)
@@ -1137,7 +1145,7 @@ export default class LocusInfo extends EventsScope {
           // copy over all of existing locus except participants
           LocusDtoTopLevelKeys.forEach((key) => {
             if (key !== 'participants') {
-              locus[key] = cloneDeep(this[key]);
+              (locus as Record<string, any>)[key] = cloneDeep((this as Record<string, any>)[key]);
             }
           });
         } else {
@@ -1145,14 +1153,16 @@ export default class LocusInfo extends EventsScope {
           // (except participants, which need to stay empty - that means "no participant changes")
           Object.values(ObjectTypeToLocusKeyMap).forEach((locusDtoKey) => {
             if (locusDtoKey !== 'participants') {
-              locus[locusDtoKey] = cloneDeep(this[locusDtoKey]);
+              (locus as Record<string, any>)[locusDtoKey] = cloneDeep(
+                (this as Record<string, any>)[locusDtoKey]
+              );
             }
           });
         }
 
         LoggerProxy.logger.info(
           `Locus-info:index#updateFromHashTree --> LOCUS object is ${locusObjectStateAfterUpdates}, all updates: ${JSON.stringify(
-            data.updatedObjects.map((o) => ({
+            update.updatedObjects.map((o) => ({
               type: o.htMeta.elementId.type,
               id: o.htMeta.elementId.id,
               hasData: !!o.data,
@@ -1160,7 +1170,7 @@ export default class LocusInfo extends EventsScope {
           )}`
         );
         // now apply all the updates from the hash tree onto the locus
-        data.updatedObjects.forEach((object) => {
+        update.updatedObjects.forEach((object) => {
           locus = this.updateLocusFromHashTreeObject(object, locus);
         });
 
@@ -1260,16 +1270,16 @@ export default class LocusInfo extends EventsScope {
    * @param {string} debugText string explaining the trigger for this call, added to logs for debugging purposes
    * @param {object} locus locus object
    * @param {object} metadata locus hash trees metadata
-   * @param {string} eventType locus event
    * @param {DataSet[]} dataSets
+   * @param {string} eventType locus event
    * @returns {void}
    */
   private onFullLocusWithHashTrees(
     debugText: string,
     locus: any,
     metadata: Metadata,
-    eventType?: string,
-    dataSets?: Array<DataSet>
+    dataSets: Array<DataSet>,
+    eventType?: string
   ) {
     if (!this.hashTreeParsers.has(locus.url)) {
       LoggerProxy.logger.info(
@@ -1289,7 +1299,8 @@ export default class LocusInfo extends EventsScope {
         metadata,
       });
       // we have a full locus to start with, so we consider Locus info to be "initialized"
-      this.hashTreeParsers.get(locus.url).initializedFromHashTree = true;
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      this.hashTreeParsers.get(locus.url)!.initializedFromHashTree = true;
       this.onFullLocusCommon(locus, eventType);
     } else {
       // in this case the Locus we're getting is not necessarily the full one
@@ -1351,7 +1362,7 @@ export default class LocusInfo extends EventsScope {
         );
       }
       // this is the new hashmap Locus DTO format (only applicable to webinars for now)
-      this.onFullLocusWithHashTrees(debugText, locus, metadata, eventType, dataSets);
+      this.onFullLocusWithHashTrees(debugText, locus, metadata, dataSets, eventType);
     } else {
       this.onFullLocusClassic(debugText, locus, eventType);
     }
@@ -2859,4 +2870,17 @@ export default class LocusInfo extends EventsScope {
   clearMainSessionLocusCache() {
     this.mainSessionLocusCache = null;
   }
+
+  /**
+   * Cleans up all hash tree parsers and clears internal maps.
+   * @returns {void}
+   * @memberof LocusInfo
+   */
+  cleanUp() {
+    this.hashTreeParsers.forEach((entry) => {
+      entry.parser.cleanUp();
+    });
+    this.hashTreeParsers.clear();
+    this.hashTreeObjectId2ParticipantId.clear();
+  }
 }

package/src/meeting/util.ts

@@ -371,6 +371,7 @@ const MeetingUtil = {
     meeting.breakouts.cleanUp();
     meeting.webinar.cleanUp();
     meeting.simultaneousInterpretation.cleanUp();
+    meeting.locusInfo.cleanUp();
     meeting.locusMediaRequest = undefined;
 
     meeting.webex?.internal?.newMetrics?.callDiagnosticMetrics?.clearEventLimitsForCorrelationId(