@webex/plugin-meetings 3.10.0-next.8 → 3.10.0-webex-services-ready.1

package/dist/types/hashTree/hashTreeParser.d.ts

@@ -0,0 +1,260 @@
+import HashTree from './hashTree';
+import { Enum } from '../constants';
+import { HtMeta } from './types';
+import { LocusDTO } from '../locus-info/types';
+export interface DataSet {
+    url: string;
+    root: string;
+    version: number;
+    leafCount: number;
+    name: string;
+    idleMs: number;
+    backoff: {
+        maxMs: number;
+        exponent: number;
+    };
+}
+export interface HashTreeObject {
+    htMeta: HtMeta;
+    data: Record<string, any>;
+}
+export interface RootHashMessage {
+    dataSets: Array<DataSet>;
+}
+export interface HashTreeMessage {
+    dataSets: Array<DataSet>;
+    visibleDataSetsUrl: string;
+    locusStateElements?: Array<HashTreeObject>;
+    locusSessionId?: string;
+    locusUrl: string;
+}
+interface InternalDataSet extends DataSet {
+    hashTree?: HashTree;
+    timer?: ReturnType<typeof setTimeout>;
+}
+type WebexRequestMethod = (options: Record<string, any>) => Promise<any>;
+export declare const LocusInfoUpdateType: {
+    readonly OBJECTS_UPDATED: "OBJECTS_UPDATED";
+    readonly MEETING_ENDED: "MEETING_ENDED";
+};
+export type LocusInfoUpdateType = Enum<typeof LocusInfoUpdateType>;
+export type LocusInfoUpdateCallback = (updateType: LocusInfoUpdateType, data?: {
+    updatedObjects: HashTreeObject[];
+}) => void;
+/**
+ * Checks if the given hash tree object is of type "self"
+ * @param {HashTreeObject} object object to check
+ * @returns {boolean} True if the object is of type "self", false otherwise
+ */
+export declare function isSelf(object: HashTreeObject): boolean;
+/**
+ * Parses hash tree eventing locus data
+ */
+declare class HashTreeParser {
+    dataSets: Record<string, InternalDataSet>;
+    visibleDataSetsUrl: string;
+    webexRequest: WebexRequestMethod;
+    locusInfoUpdateCallback: LocusInfoUpdateCallback;
+    visibleDataSets: string[];
+    debugId: string;
+    /**
+     * Constructor for HashTreeParser
+     * @param {Object} options
+     * @param {Object} options.initialLocus The initial locus data containing the hash tree information
+     */
+    constructor(options: {
+        initialLocus: {
+            dataSets: Array<DataSet>;
+            locus: any;
+        };
+        webexRequest: WebexRequestMethod;
+        locusInfoUpdateCallback: LocusInfoUpdateCallback;
+        debugId: string;
+    });
+    /**
+     * Initializes a new visible data set by creating a hash tree for it, adding it to all the internal structures,
+     * and sending an initial sync request to Locus with empty leaf data - that will trigger Locus to gives us all the data
+     * from that dataset (in the response or via messages).
+     *
+     * @param {DataSet} dataSet The new data set to be added
+     * @returns {Promise}
+     */
+    private initializeNewVisibleDataSet;
+    /**
+     * Sends a special sync request to Locus with all leaves empty - this is a way to get all the data for a given dataset.
+     *
+     * @param {string} datasetName - name of the dataset for which to send the request
+     * @param {string} debugText - text to include in logs
+     * @returns {Promise}
+     */
+    private sendInitializationSyncRequestToLocus;
+    /**
+     * Queries Locus for information about all the data sets
+     *
+     * @param {string} url - url from which we can get info about all data sets
+     * @returns {Promise}
+     */
+    private getAllDataSetsMetadata;
+    /**
+     * Initializes the hash tree parser from a message received from Locus.
+     *
+     * @param {HashTreeMessage} message - initial hash tree message received from Locus
+     * @returns {Promise}
+     */
+    initializeFromMessage(message: HashTreeMessage): Promise<void>;
+    /**
+     * Initializes the hash tree parser from GET /loci API response by fetching all data sets metadata
+     * first and then doing an initialization sync on each data set
+     *
+     * This function requires that this.visibleDataSets have been already populated correctly by the constructor.
+     *
+     * @param {LocusDTO} locus - locus object received from GET /loci
+     * @returns {Promise}
+     */
+    initializeFromGetLociResponse(locus: LocusDTO): Promise<void>;
+    /**
+     * Initializes data sets by doing an initialization sync on each visible data set that doesn't have a hash tree yet.
+     *
+     * @param {DataSet[]} dataSets Array of DataSet objects to initialize
+     * @param {string} debugText Text to include in logs for debugging purposes
+     * @returns {Promise}
+     */
+    private initializeDataSets;
+    /**
+     * Each dataset exists at a different place in the dto
+     * iterate recursively over the locus and if it has a htMeta key,
+     * create an object with the type, id and version and add it to the appropriate leafData array
+     *
+     * @param {any} locus - The current part of the locus being processed
+     * @param {Object} [options]
+     * @param {boolean} [options.copyData=false] - Whether to copy the data for each leaf into returned result
+     * @returns {any} - An object mapping dataset names to arrays of leaf data
+     */
+    private analyzeLocusHtMeta;
+    /**
+     * Checks if the provided hash tree message indicates the end of the meeting and that there won't be any more updates.
+     *
+     * @param {HashTreeMessage} message - The hash tree message to check
+     * @returns {boolean} - Returns true if the message indicates the end of the meeting, false otherwise
+     */
+    private isEndMessage;
+    /**
+     * Handles the root hash heartbeat message
+     *
+     * @param {RootHashMessage} message - The root hash heartbeat message
+     * @returns {void}
+     */
+    private handleRootHashHeartBeatMessage;
+    /**
+     * This method should be called when we receive a partial locus DTO that contains dataSets and htMeta information
+     * It updates the hash trees with the new leaf data based on the received Locus
+     *
+     * @param {Object} update - The locus update containing data sets and locus information
+     * @returns {void}
+     */
+    handleLocusUpdate(update: {
+        dataSets?: Array<DataSet>;
+        locus: any;
+    }): void;
+    /**
+     * Updates the internal data set information based on the received data set from Locus.
+     *
+     * @param {DataSet} receivedDataSet - The latest data set information received from Locus to update the internal state.
+     * @returns {void}
+     */
+    private updateDataSetInfo;
+    /**
+     * Checks for changes in the visible data sets based on the updated objects.
+     * @param {HashTreeObject[]} updatedObjects - The list of updated hash tree objects.
+     * @returns {Object} An object containing the removed and added visible data sets.
+     */
+    private checkForVisibleDataSetChanges;
+    /**
+     * Deletes the hash tree for the specified data set.
+     *
+     * @param {string} dataSetName name of the data set to delete
+     * @returns {void}
+     */
+    private deleteHashTree;
+    /**
+     * Adds entries to the passed in updateObjects array
+     * for the changes that result from removing visible data sets and creates hash
+     * trees for the new visible data sets, but without populating the hash trees.
+     *
+     * This function is synchronous. If we are missing information about some new
+     * visible data sets and they require async initialization, the names of these data sets
+     * are returned in an array.
+     *
+     * @param {string[]} removedDataSets - The list of removed data sets.
+     * @param {string[]} addedDataSets - The list of added data sets.
+     * @param {HashTreeObject[]} updatedObjects - The list of updated hash tree objects to which changes will be added.
+     * @returns {string[]} names of data sets that couldn't be initialized synchronously
+     */
+    private processVisibleDataSetChanges;
+    /**
+     * Adds entries to the passed in updateObjects array
+     * for the changes that result from adding and removing visible data sets.
+     *
+     * @param {HashTreeMessage} message - The hash tree message that triggered the visible data set changes.
+     * @param {string[]} addedDataSets - The list of added data sets.
+     * @returns {Promise<void>}
+     */
+    private initializeNewVisibleDataSets;
+    /**
+     * Parses incoming hash tree messages, updates the hash trees and returns information about the changes
+     *
+     * @param {HashTreeMessage} message - The hash tree message containing data sets and objects to be processed
+     * @param {string} [debugText] - Optional debug text to include in logs
+     * @returns {Promise}
+     */
+    private parseMessage;
+    /**
+     * Handles incoming hash tree messages, updates the hash trees and calls locusInfoUpdateCallback
+     *
+     * @param {HashTreeMessage} message - The hash tree message containing data sets and objects to be processed
+     * @param {string} [debugText] - Optional debug text to include in logs
+     * @returns {void}
+     */
+    handleMessage(message: HashTreeMessage, debugText?: string): Promise<void>;
+    /**
+     * Calls the updateInfo callback if there are any updates to report
+     *
+     * @param {Object} updates parsed from a Locus message
+     * @returns {void}
+     */
+    private callLocusInfoUpdateCallback;
+    /**
+     * Calculates a weighted backoff time that should be used for syncs
+     *
+     * @param {Object} backoff - The backoff configuration containing maxMs and exponent
+     * @returns {number} - A weighted backoff time based on the provided configuration, using algorithm supplied by Locus team
+     */
+    private getWeightedBackoffTime;
+    /**
+     * Runs the sync algorithm for the given data set.
+     *
+     * @param {DataSet} receivedDataSet - The data set to run the sync algorithm for.
+     * @returns {void}
+     */
+    private runSyncAlgorithm;
+    /**
+     * Stops all timers for the data sets to prevent any further sync attempts.
+     * @returns {void}
+     */
+    private stopAllTimers;
+    /**
+     * Gets the current hashes from the locus for a specific data set.
+     * @param {string} dataSetName
+     * @returns {string[]}
+     */
+    private getHashesFromLocus;
+    /**
+     * Sends a sync request to Locus for the specified data set.
+     *
+     * @param {InternalDataSet} dataSet The data set to sync.
+     * @param {Record<number, LeafDataItem[]>} mismatchedLeavesData The mismatched leaves data to include in the sync request.
+     * @returns {Promise<HashTreeMessage|null>}
+     */
+    private sendSyncRequestToLocus;
+}
+export default HashTreeParser;

package/dist/types/hashTree/types.d.ts

@@ -0,0 +1,25 @@
+import { Enum } from '../constants';
+export declare const ObjectType: {
+    readonly participant: "participant";
+    readonly self: "self";
+    readonly locus: "locus";
+    readonly mediaShare: "mediashare";
+    readonly info: "info";
+    readonly fullState: "fullstate";
+};
+export type ObjectType = Enum<typeof ObjectType>;
+export declare const ObjectTypeToLocusKeyMap: {
+    info: string;
+    fullstate: string;
+    self: string;
+    participant: string;
+    mediashare: string;
+};
+export interface HtMeta {
+    elementId: {
+        type: ObjectType;
+        id: number;
+        version: number;
+    };
+    dataSetNames: string[];
+}

package/dist/types/hashTree/utils.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Analyzes given part of Locus DTO recursively and delete any nested objects that have their own htMeta
+ *
+ * @param {Object} currentLocusPart part of locus DTO to analyze
+ * @param {Object} parent parent object
+ * @param {string|number} currentKey key of the parent object that currentLocusPart is
+ * @returns {void}
+ */
+export declare const deleteNestedObjectsWithHtMeta: (currentLocusPart: any, parent?: any, currentKey?: string | number) => void;

package/dist/types/locus-info/index.d.ts

@@ -1,45 +1,15 @@
 import EventsScope from '../common/events/events-scope';
-export type LocusDTO = {
-    controls?: any;
-    fullState?: {
-        active: boolean;
-        count: number;
-        lastActive: string;
-        locked: boolean;
-        sessionId: string;
-        seessionIds: string[];
-        startTime: number;
-        state: string;
-        type: string;
+import { LOCUSEVENT } from '../constants';
+import HashTreeParser, { DataSet, HashTreeMessage, HashTreeObject } from '../hashTree/hashTreeParser';
+import { LocusDTO } from './types';
+export type LocusLLMEvent = {
+    data: {
+        eventType: typeof LOCUSEVENT.HASH_TREE_DATA_UPDATED;
+        stateElementsMessage: HashTreeMessage;
     };
-    host?: {
-        id: string;
-        incomingCallProtocols: any[];
-        isExternal: boolean;
-        name: string;
-        orgId: string;
-    };
-    info?: any;
-    links?: any;
-    mediaShares?: any[];
-    meetings?: any[];
-    participants: any[];
-    replaces?: any[];
-    self?: any;
-    sequence?: {
-        dirtyParticipants: number;
-        entries: number[];
-        rangeEnd: number;
-        rangeStart: number;
-        sequenceHash: number;
-        sessionToken: string;
-        since: string;
-        totalParticipants: number;
-    };
-    syncUrl?: string;
-    url?: string;
 };
 export type LocusApiResponseBody = {
+    dataSets?: DataSet[];
     locus: LocusDTO;
 };
 /**
@@ -80,6 +50,9 @@ export default class LocusInfo extends EventsScope {
     resources: any;
     mainSessionLocusCache: any;
     self: any;
+    hashTreeParser?: HashTreeParser;
+    hashTreeObjectId2ParticipantId: Map<number, string>;
+    classicVsHashTreeMismatchMetricCounter: number;
     /**
      * Constructor
      * @param {function} updateMeeting callback to update the meeting object from an object
@@ -90,6 +63,7 @@ export default class LocusInfo extends EventsScope {
     constructor(updateMeeting: any, webex: any, meetingId: any);
     /**
      * Does a Locus sync. It tries to get the latest delta DTO or if it can't, it falls back to getting the full Locus DTO.
+     * WARNING: This function must not be used for hash tree based Locus meetings.
      *
      * @param {Meeting} meeting
      * @param {boolean} isLocusUrlChanged
@@ -121,11 +95,28 @@ export default class LocusInfo extends EventsScope {
      */
     init(locus?: any): void;
     /**
-     * @param {Object} locus
+     * Creates the HashTreeParser instance.
+     * @param {Object} initial locus data
+     * @returns {void}
+     */
+    private createHashTreeParser;
+    /**
+     * @param {Object} data - data to initialize locus info with. It may be from a join or GET /loci response or from a Mercury event that triggers a creation of meeting object
      * @returns {undefined}
      * @memberof LocusInfo
      */
-    initialSetup(locus: object): void;
+    initialSetup(data: {
+        trigger: 'join-response';
+        locus: LocusDTO;
+        dataSets?: DataSet[];
+    } | {
+        trigger: 'locus-message';
+        locus?: LocusDTO;
+        hashTreeMessage?: HashTreeMessage;
+    } | {
+        trigger: 'get-loci-response';
+        locus?: LocusDTO;
+    }): Promise<void>;
     /**
      * Handles HTTP response from Locus API call.
      * @param {Meeting} meeting meeting object
@@ -133,6 +124,39 @@ export default class LocusInfo extends EventsScope {
      * @returns {void}
      */
     handleLocusAPIResponse(meeting: any, responseBody: LocusApiResponseBody): void;
+    /**
+     *
+     * @param {HashTreeObject} object data set object
+     * @param {any} locus
+     * @returns {void}
+     */
+    updateLocusFromHashTreeObject(object: HashTreeObject, locus: LocusDTO): LocusDTO;
+    /**
+     * Sends a metric when we receive something from Locus that uses hash trees while we
+     * expect classic deltas or the other way around.
+     * @param {Meeting} meeting
+     * @param {string} message
+     * @returns {void}
+     */
+    sendClassicVsHashTreeMismatchMetric(meeting: any, message: string): void;
+    /**
+     * Handles a hash tree message received from Locus.
+     *
+     * @param {Meeting} meeting - The meeting object
+     * @param {eventType} eventType - The event type
+     * @param {HashTreeMessage} message incoming hash tree message
+     * @returns {void}
+     */
+    private handleHashTreeMessage;
+    /**
+     * Callback registered with HashTreeParser to receive locus info updates.
+     * Updates our locus info based on the data parsed by the hash tree parser.
+     *
+     * @param {LocusInfoUpdateType} updateType - The type of update received.
+     * @param {Object} [data] - Additional data for the update, if applicable.
+     * @returns {void}
+     */
+    private updateFromHashTree;
     /**
      * @param {Meeting} meeting
      * @param {Object} data
@@ -148,14 +172,39 @@ export default class LocusInfo extends EventsScope {
      * @memberof LocusInfo
      */
     emitScoped(scope?: any, eventName?: string, args?: any): boolean;
+    /**
+     * Function for handling full locus when it's using hash trees (so not the "classic" one).
+     *
+     * @param {object} locus locus object
+     * @param {string} eventType locus event
+     * @param {DataSet[]} dataSets
+     * @returns {void}
+     */
+    private onFullLocusWithHashTrees;
+    /**
+     * Function for handling full locus when it's the "classic" one (not hash trees)
+     *
+     * @param {object} locus locus object
+     * @param {string} eventType locus event
+     * @returns {void}
+     */
+    private onFullLocusClassic;
     /**
      * updates the locus with full locus object
      * @param {object} locus locus object
-     * @param {string} eventType particulat locus event
+     * @param {string} eventType locus event
+     * @param {DataSet[]} dataSets
      * @returns {object} null
      * @memberof LocusInfo
      */
-    onFullLocus(locus: any, eventType?: string): void;
+    onFullLocus(locus: any, eventType?: string, dataSets?: Array<DataSet>): void;
+    /**
+     * Common part of handling full locus, used by both classic and hash tree based locus handling
+     * @param {object} locus locus object
+     * @param {string} eventType locus event
+     * @returns {void}
+     */
+    private onFullLocusCommon;
     /**
      * @param {String} eventType
      * @returns {undefined}

package/dist/types/locus-info/types.d.ts

@@ -0,0 +1,46 @@
+import { HtMeta } from '../hashTree/types';
+export type LocusFullState = {
+    active: boolean;
+    count: number;
+    lastActive: string;
+    locked: boolean;
+    sessionId: string;
+    seessionIds: string[];
+    startTime: number;
+    state: string;
+    type: string;
+};
+export type LocusDTO = {
+    controls?: any;
+    fullState?: LocusFullState;
+    host?: {
+        id: string;
+        incomingCallProtocols: any[];
+        isExternal: boolean;
+        name: string;
+        orgId: string;
+    };
+    htMeta?: HtMeta;
+    info?: any;
+    jsSdkMeta?: {
+        removedParticipantIds: string[];
+    };
+    links?: any;
+    mediaShares?: any[];
+    meetings?: any[];
+    participants: any[];
+    replaces?: any[];
+    self?: any;
+    sequence?: {
+        dirtyParticipants: number;
+        entries: number[];
+        rangeEnd: number;
+        rangeStart: number;
+        sequenceHash: number;
+        sessionToken: string;
+        since: string;
+        totalParticipants: number;
+    };
+    syncUrl?: string;
+    url?: string;
+};

package/dist/types/meeting/index.d.ts

@@ -23,6 +23,8 @@ import { LocusMediaRequest } from './locusMediaRequest';
 import { BrbState } from './brbState';
 import { SetStageOptions } from './request.type';
 import { Invitee } from './type';
+import { DataSet } from '../hashTree/hashTreeParser';
+import { LocusDTO } from '../locus-info/types';
 export type CaptionData = {
     id: string;
     isFinal: boolean;
@@ -1034,25 +1036,30 @@ export default class Meeting extends StatelessWebexPlugin {
      */
     setSipUri(sipUri: string): void;
     /**
-     * Set the locus info the class instance
-     * @param {Object} locus
-     * @param {Array} locus.mediaConnections
-     * @param {String} locus.locusUrl
-     * @param {String} locus.locusId
-     * @param {String} locus.mediaId
-     * @param {Object} locus.host
+     * Set the locus info the class instance. Should be called with the parsed locus
+     * we got in the join response.
+     *
+     * @param {Object} data
+     * @param {Array} data.mediaConnections
+     * @param {String} data.locusUrl
+     * @param {String} data.locusId
+     * @param {String} data.mediaId
+     * @param {Object} data.host
      * @todo change name to genertic parser
      * @returns {undefined}
      * @private
      * @memberof Meeting
      */
-    setLocus(locus: {
+    setLocus(data: {
+        locus: LocusDTO;
         mediaConnections: Array<any>;
         locusUrl: string;
         locusId: string;
         mediaId: string;
         host: object;
-    } | any): void;
+        selfId: string;
+        dataSets: DataSet[];
+    }): void;
     /**
      * Upload logs for the current meeting
      * @param {object} options file name and function name
@@ -1269,6 +1276,12 @@ export default class Meeting extends StatelessWebexPlugin {
     startTranscription(options?: {
         spokenLanguage?: string;
     }): Promise<void>;
+    /** Handles Locus LLM events
+     *
+     * @param {LocusLLMEvent} event - The Locus LLM event to process
+     * @returns {void}
+     */
+    private processLocusLLMEvent;
     /**
      * Callback called when a relay event is received from meeting LLM Connection
      * @param {RelayEvent} e Event object coming from LLM Connection

package/dist/types/meetings/index.d.ts

@@ -5,10 +5,17 @@ import { WebexPlugin } from '@webex/webex-core';
 import { DeviceRegistrationOptions } from '@webex/internal-plugin-device';
 import * as mediaHelpersModule from '@webex/media-helpers';
 import 'webrtc-adapter';
-import { DESTINATION_TYPE } from '../constants';
+import { LOCUSEVENT, DESTINATION_TYPE } from '../constants';
 import { CallStateForMetrics } from '../meeting';
 import Reachability from '../reachability';
 import { INoiseReductionEffect, IVirtualBackgroundEffect, MeetingRegistrationStatus } from './meetings.types';
+import { HashTreeMessage } from '../hashTree/hashTreeParser';
+export type LocusEvent = {
+    eventType: LOCUSEVENT;
+    locusUrl?: string;
+    locus?: any;
+    stateElementsMessage?: HashTreeMessage;
+};
 /**
  * Meetings Ready Event
  * Emitted when the meetings instance on webex is ready
@@ -129,7 +136,7 @@ export default class Meetings extends WebexPlugin {
      * @private
      * @memberof Meetings
      */
-    getCorrespondingMeetingByLocus(data: any): any;
+    getCorrespondingMeetingByLocus(data: LocusEvent): any;
     /**
      * handle locus events and takes meeting actions with them as they come in
      * @param {Object} data a locus event

package/dist/types/metrics/constants.d.ts

@@ -84,5 +84,7 @@ declare const BEHAVIORAL_METRICS: {
     VERIFY_REGISTRATION_ID_ERROR: string;
     JOIN_FORBIDDEN_ERROR: string;
     MEDIA_ISSUE_DETECTED: string;
+    LOCUS_CLASSIC_VS_HASH_TREE_MISMATCH: string;
+    LOCUS_HASH_TREE_UNSUPPORTED_OPERATION: string;
 };
 export { BEHAVIORAL_METRICS as default };