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

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

@@ -0,0 +1,129 @@
+import { ObjectType } from './types';
+export type LeafDataItem = {
+    type: ObjectType;
+    id: number;
+    version: number;
+};
+/**
+ * HashTree is a data structure that organizes items into leaves based on their IDs,
+ */
+declare class HashTree {
+    leaves: Array<Record<string, Record<number, LeafDataItem>>>;
+    leafHashes: Array<string>;
+    readonly numLeaves: number;
+    /**
+     * Constructs a new HashTree.
+     * @param {LeafDataItem[]} leafData Initial data to populate the tree.
+     * @param {number} numLeaves The number of leaf nodes in the tree. Must be 0 or a power of 2.
+     * @throws {Error} If numLeaves is not 0 or a power of 2.
+     */
+    constructor(leafData: LeafDataItem[], numLeaves: number);
+    /**
+     * Internal logic for adding or updating an item, without computing the leaf hash.
+     * @param {LeafDataItem} item The item to add or update.
+     * @returns {{put: boolean, index: (number|null)}} Object indicating if put and the leaf index.
+     * @private
+     */
+    private _putItemInternal;
+    /**
+     * Adds or updates a single item in the hash tree.
+     * @param {LeafDataItem} item The item to add or update.
+     * @returns {boolean} True if the item was added or updated, false otherwise (e.g., older version or tree has 0 leaves).
+     */
+    putItem(item: LeafDataItem): boolean;
+    /**
+     * Adds or updates multiple items in the hash tree.
+     * @param {LeafDataItem[]} items The array of items to add or update.
+     * @returns {boolean[]} An array of booleans indicating success for each item.
+     */
+    putItems(items: LeafDataItem[]): boolean[];
+    /**
+     * Internal logic for removing an item, without computing the leaf hash.
+     * @param {LeafDataItem} item The item to remove.
+     * @returns {{removed: boolean, index: (number|null)}} Object indicating if removed and the leaf index.
+     * @private
+     */
+    private _removeItemInternal;
+    /**
+     * Removes a single item from the hash tree.
+     * The removal is based on matching type, id, and the provided item's version
+     * being greater than or equal to the existing item's version.
+     * @param {LeafDataItem} item The item to remove.
+     * @returns {boolean} True if the item was removed, false otherwise.
+     */
+    removeItem(item: LeafDataItem): boolean;
+    /**
+     * Removes multiple items from the hash tree.
+     * @param {LeafDataItem[]} items The array of items to remove.
+     * @returns {boolean[]} An array of booleans indicating success for each item.
+     */
+    removeItems(items: LeafDataItem[]): boolean[];
+    /**
+     * Updates multiple items in the hash tree.
+     * This method can handle both updating and removing items based on the `operation` flag.
+     *
+     * @param {object[]} itemUpdates An array of objects containing `operation` flag and the `item` to update.
+     * @returns {boolean[]} An array of booleans indicating success for each operation.
+     */
+    updateItems(itemUpdates: {
+        operation: 'update' | 'remove';
+        item: LeafDataItem;
+    }[]): boolean[];
+    /**
+     * Computes the hash for a specific leaf.
+     * The hash is based on the sorted items within the leaf.
+     * @param {number} index The index of the leaf to compute the hash for.
+     * @returns {void}
+     */
+    computeLeafHash(index: number): void;
+    /**
+     * Computes all internal and leaf node hashes of the tree.
+     * Internal node hashes are computed bottom-up from the leaf hashes.
+     * @returns {string[]} An array of hash strings, with internal node hashes first, followed by leaf hashes.
+     * Returns `[EMPTY_HASH]` if the tree has 0 leaves.
+     */
+    computeTreeHashes(): string[];
+    /**
+     * Returns all hashes in the tree (internal nodes then leaf nodes).
+     * @returns {string[]} An array of hash strings.
+     */
+    getHashes(): string[];
+    /**
+     * Computes and returns the hash value of the root node.
+     * @returns {string} The root hash of the entire tree. Returns `EMPTY_HASH` if the tree has 0 leaves.
+     */
+    getRootHash(): string;
+    /**
+     * Gets the number of leaves in the tree.
+     * @returns {number} The number of leaves.
+     */
+    getLeafCount(): number;
+    /**
+     * Calculates the total number of items stored in the tree.
+     * @returns {number} The total number of items.
+     */
+    getTotalItemCount(): number;
+    /**
+     * Retrieves all data items from a specific leaf.
+     * @param {number} leafIndex The index of the leaf.
+     * @returns {LeafDataItem[]} An array of LeafDataItem in the specified leaf, sorted by ID,
+     * or an empty array if the index is invalid or leaf is empty.
+     */
+    getLeafData(leafIndex: number): LeafDataItem[];
+    /**
+     * Resizes the HashTree to have a new number of leaf nodes, redistributing all existing items.
+     * @param {number} newNumLeaves The new number of leaf nodes (must be 0 or a power of 2).
+     * @returns {boolean} true if the tree was resized, false if the size didn't change.
+     * @throws {Error} if newNumLeaves is not 0 or a power of 2.
+     */
+    resize(newNumLeaves: number): boolean;
+    /**
+     * Compares the tree's leaf hashes with an external set of hashes and returns the indices of differing leaf nodes.
+     * The externalHashes array is expected to contain all node hashes (internal followed by leaves),
+     * similar to the output of getHashes().
+     * @param {string[]} externalHashes An array of hash strings (internal node hashes then leaf hashes).
+     * @returns {number[]} An array of indices of the leaf nodes that have different hashes.
+     */
+    diffHashes(externalHashes: string[]): number[];
+}
+export default HashTree;

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;
+};