@webex/internal-plugin-llm 3.11.0 → 3.12.0

package/package.json

@@ -13,7 +13,7 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@webex/internal-plugin-mercury": "3.11.0"
+    "@webex/internal-plugin-mercury": "3.12.0"
   },
   "browserify": {
     "transform": [
@@ -27,10 +27,10 @@
     "@webex/eslint-config-legacy": "0.0.0",
     "@webex/jest-config-legacy": "0.0.0",
     "@webex/legacy-tools": "0.0.0",
-    "@webex/test-helper-chai": "3.11.0",
-    "@webex/test-helper-mocha": "3.11.0",
-    "@webex/test-helper-mock-webex": "3.11.0",
-    "@webex/test-helper-test-users": "3.11.0",
+    "@webex/test-helper-chai": "3.12.0",
+    "@webex/test-helper-mocha": "3.12.0",
+    "@webex/test-helper-mock-webex": "3.12.0",
+    "@webex/test-helper-test-users": "3.12.0",
     "eslint": "^8.24.0",
     "prettier": "^2.7.1",
     "sinon": "^9.2.4"
@@ -44,5 +44,5 @@
     "test:style": "eslint ./src/**/*.*",
     "test:unit": "webex-legacy-tools test --unit --runner jest"
   },
-  "version": "3.11.0"
+  "version": "3.12.0"
 }

package/src/constants.ts

@@ -1,2 +1,14 @@
 // eslint-disable-next-line import/prefer-default-export
 export const LLM = 'llm';
+
+export const LLM_DEFAULT_SESSION = 'llm-default-session';
+
+export const DATA_CHANNEL_WITH_JWT_TOKEN = 'data-channel-with-jwt-token';
+
+export const SUBSCRIPTION_AWARE_SUBCHANNELS_PARAM = 'subscriptionAwareSubchannels';
+
+export const DATA_CHNANEL_TYPE = {
+  TRANSCRIPTION: 'transcription',
+};
+
+export const AWARE_DATA_CHANNEL = [DATA_CHNANEL_TYPE.TRANSCRIPTION];

package/src/index.ts

@@ -1,8 +1,10 @@
 import * as WebexCore from '@webex/webex-core';
 import LLMChannel, {config} from './llm';
+import {DataChannelTokenType} from './llm.types';
 
 WebexCore.registerInternalPlugin('llm', LLMChannel, {
   config,
 });
 
+export {DataChannelTokenType};
 export {default} from './llm';

package/src/llm.ts

@@ -2,9 +2,15 @@
 
 import Mercury from '@webex/internal-plugin-mercury';
 
-import {LLM} from './constants';
 // eslint-disable-next-line no-unused-vars
-import {ILLMChannel} from './llm.types';
+import {
+  LLM,
+  DATA_CHANNEL_WITH_JWT_TOKEN,
+  AWARE_DATA_CHANNEL,
+  SUBSCRIPTION_AWARE_SUBCHANNELS_PARAM,
+  LLM_DEFAULT_SESSION,
+} from './constants';
+import {ILLMChannel, DataChannelTokenType} from './llm.types';
 
 export const config = {
   llm: {
@@ -42,90 +48,289 @@ export const config = {
  */
 export default class LLMChannel extends (Mercury as any) implements ILLMChannel {
   namespace = LLM;
-
+  defaultSessionId = LLM_DEFAULT_SESSION;
   /**
-   * If the LLM plugin has been registered and listening
-   * @instance
-   * @type {Boolean}
-   * @public
+   * Map to store connection-specific data for multiple LLM connections
+   * @private
+   * @type {Map<string, {webSocketUrl?: string; binding?: string; locusUrl?: string; datachannelUrl?: string}>}
    */
+  private connections: Map<
+    string,
+    {
+      webSocketUrl?: string;
+      binding?: string;
+      locusUrl?: string;
+      datachannelUrl?: string;
+      datachannelToken?: string;
+    }
+  > = new Map();
 
-  private webSocketUrl?: string;
-
-  private binding?: string;
-
-  private locusUrl?: string;
+  private datachannelTokens: Record<DataChannelTokenType, string> = {
+    [DataChannelTokenType.Default]: undefined,
+    [DataChannelTokenType.PracticeSession]: undefined,
+  };
 
-  private datachannelUrl?: string;
+  private refreshHandler?: () => Promise<{
+    body: {datachannelToken: string; datachannelTokenType: DataChannelTokenType};
+  }>;
 
   /**
    * Register to the websocket
    * @param {string} llmSocketUrl
+   * @param {string} datachannelToken
+   * @param {string} sessionId - Connection identifier
    * @returns {Promise<void>}
    */
-  private register = (llmSocketUrl: string): Promise<void> =>
-    this.request({
+  private register = async (
+    llmSocketUrl: string,
+    datachannelToken?: string,
+    sessionId: string = LLM_DEFAULT_SESSION
+  ): Promise<void> => {
+    const isDataChannelTokenEnabled = await this.isDataChannelTokenEnabled();
+
+    return this.request({
       method: 'POST',
       url: llmSocketUrl,
       body: {deviceUrl: this.webex.internal.device.url},
+      headers:
+        isDataChannelTokenEnabled && datachannelToken
+          ? {'Data-Channel-Auth-Token': datachannelToken}
+          : {},
     })
       .then((res: {body: {webSocketUrl: string; binding: string}}) => {
-        this.webSocketUrl = res.body.webSocketUrl;
-        this.binding = res.body.binding;
+        // Get or create connection data
+        const sessionData = this.connections.get(sessionId) || {};
+        sessionData.webSocketUrl = res.body.webSocketUrl;
+        sessionData.binding = res.body.binding;
+        this.connections.set(sessionId, sessionData);
       })
       .catch((error: any) => {
-        this.logger.error(`Error connecting to websocket: ${error}`);
+        this.logger.error(`Error connecting to websocket for ${sessionId}: ${error}`);
         throw error;
       });
+  };
 
   /**
    * Register and connect to the websocket
    * @param {string} locusUrl
    * @param {string} datachannelUrl
+   * @param {string} datachannelToken
+   * @param {string} sessionId - Connection identifier
    * @returns {Promise<void>}
    */
-  public registerAndConnect = (locusUrl: string, datachannelUrl: string): Promise<void> =>
-    this.register(datachannelUrl).then(() => {
+  public registerAndConnect = (
+    locusUrl: string,
+    datachannelUrl: string,
+    datachannelToken?: string,
+    sessionId: string = LLM_DEFAULT_SESSION
+  ): Promise<void> =>
+    this.register(datachannelUrl, datachannelToken, sessionId).then(async () => {
       if (!locusUrl || !datachannelUrl) return undefined;
-      this.locusUrl = locusUrl;
-      this.datachannelUrl = datachannelUrl;
-      this.connect(this.webSocketUrl);
+
+      // Get or create connection data
+      const sessionData = this.connections.get(sessionId) || {};
+      sessionData.locusUrl = locusUrl;
+      sessionData.datachannelUrl = datachannelUrl;
+      sessionData.datachannelToken = datachannelToken;
+      this.connections.set(sessionId, sessionData);
+
+      const isDataChannelTokenEnabled = await this.isDataChannelTokenEnabled();
+
+      const connectUrl = isDataChannelTokenEnabled
+        ? LLMChannel.buildUrlWithAwareSubchannels(sessionData.webSocketUrl, AWARE_DATA_CHANNEL)
+        : sessionData.webSocketUrl;
+
+      return this.connect(connectUrl, sessionId);
     });
 
   /**
    * Tells if LLM socket is connected
+   * @param {string} sessionId - Connection identifier
    * @returns {boolean} connected
    */
-  public isConnected = (): boolean => this.connected;
+  public isConnected = (sessionId = LLM_DEFAULT_SESSION): boolean => {
+    const socket = this.getSocket(sessionId);
+
+    return socket ? socket.connected : false;
+  };
 
   /**
    * Tells if LLM socket is binding
+   * @param {string} sessionId - Connection identifier
    * @returns {string} binding
    */
-  public getBinding = (): string => this.binding;
+  public getBinding = (sessionId = LLM_DEFAULT_SESSION): string => {
+    const sessionData = this.connections.get(sessionId);
+
+    return sessionData?.binding;
+  };
 
   /**
    * Get Locus URL for the connection
+   * @param {string} sessionId - Connection identifier
    * @returns {string} locus Url
    */
-  public getLocusUrl = (): string => this.locusUrl;
+  public getLocusUrl = (sessionId = LLM_DEFAULT_SESSION): string => {
+    const sessionData = this.connections.get(sessionId);
+
+    return sessionData?.locusUrl;
+  };
 
   /**
    * Get data channel URL for the connection
+   * @param {string} sessionId - Connection identifier
    * @returns {string} data channel Url
    */
-  public getDatachannelUrl = (): string => this.datachannelUrl;
+  public getDatachannelUrl = (sessionId = LLM_DEFAULT_SESSION): string => {
+    const sessionData = this.connections.get(sessionId);
+
+    return sessionData?.datachannelUrl;
+  };
+
+  /**
+   * Get data channel token for the connection
+   * @param {DataChannelTokenType} dataChannelTokenType
+   * @returns {string} data channel token
+   */
+  public getDatachannelToken = (
+    dataChannelTokenType: DataChannelTokenType = DataChannelTokenType.Default
+  ): string => {
+    return this.datachannelTokens[dataChannelTokenType];
+  };
+
+  /**
+   * Set data channel token for the connection
+   * @param {string} datachannelToken - data channel token
+   * @param {DataChannelTokenType} dataChannelTokenType
+   * @returns {void}
+   */
+  public setDatachannelToken = (
+    datachannelToken: string,
+    dataChannelTokenType: DataChannelTokenType = DataChannelTokenType.Default
+  ): void => {
+    this.datachannelTokens[dataChannelTokenType] = datachannelToken;
+  };
+
+  /**
+   * Resets all data‑channel tokens to their initial undefined values.
+   * Used when leaving or disconnecting from a meeting.
+   * @returns {void}
+   */
+  private resetDatachannelTokens() {
+    this.datachannelTokens = {
+      [DataChannelTokenType.Default]: undefined,
+      [DataChannelTokenType.PracticeSession]: undefined,
+    };
+  }
+
+  /**
+   * Set the handler used to refresh the DataChannel token
+   *
+   * @param {function} handler - Function that returns a refreshed token
+   * @returns {void}
+   */
+  public setRefreshHandler(
+    handler: () => Promise<{
+      body: {datachannelToken: string; datachannelTokenType: DataChannelTokenType};
+    }>
+  ) {
+    this.refreshHandler = handler;
+  }
+
+  /**
+   * Refresh the data channel token using the injected handler.
+   * Logs a descriptive error if the handler is missing or fails.
+   *
+   * @returns {Promise<string>} The refreshed token.
+   */
+  public async refreshDataChannelToken() {
+    if (!this.refreshHandler) {
+      this.logger.warn(
+        'llm#refreshDataChannelToken --> LLM refreshHandler is not set, skipping token refresh'
+      );
+
+      return null;
+    }
+
+    try {
+      const res = await this.refreshHandler();
+
+      return res;
+    } catch (error: any) {
+      this.logger.warn(
+        `llm#refreshDataChannelToken --> DataChannel token refresh failed (likely locus changed or participant left): ${
+          error?.message || error
+        }`
+      );
+
+      return null;
+    }
+  }
 
   /**
    * Disconnects websocket connection
    * @param {{code: number, reason: string}} options - The disconnect option object with code and reason
+   * @param {string} sessionId - Connection identifier
+   * @returns {Promise<void>}
+   */
+  public disconnectLLM = (
+    options: {code: number; reason: string},
+    sessionId: string = LLM_DEFAULT_SESSION
+  ): Promise<void> =>
+    this.disconnect(options, sessionId).then(() => {
+      // Clean up sessions data
+      this.connections.delete(sessionId);
+      this.datachannelTokens[sessionId] = undefined;
+    });
+
+  /**
+   * Disconnects all LLM websocket connections
+   * @param {{code: number, reason: string}} options - The disconnect option object with code and reason
    * @returns {Promise<void>}
    */
-  public disconnectLLM = (options: object): Promise<void> =>
-    this.disconnect(options).then(() => {
-      this.locusUrl = undefined;
-      this.datachannelUrl = undefined;
-      this.binding = undefined;
-      this.webSocketUrl = undefined;
+  public disconnectAllLLM = (options?: {code: number; reason: string}): Promise<void> =>
+    this.disconnectAll(options).then(() => {
+      // Clean up all connection data
+      this.connections.clear();
+      this.resetDatachannelTokens();
     });
+
+  /**
+   * Get all active LLM connections
+   * @returns {Map} Map of sessionId to session data
+   */
+  public getAllConnections = (): Map<
+    string,
+    {
+      webSocketUrl?: string;
+      binding?: string;
+      locusUrl?: string;
+      datachannelUrl?: string;
+      datachannelToken?: string;
+    }
+  > => new Map(this.connections);
+
+  /**
+   * Returns true if  data channel token is enabled, false otherwise
+   * @returns {Promise<boolean>} resolves with true if data channel token  is enabled
+   */
+  public isDataChannelTokenEnabled(): Promise<boolean> {
+    // @ts-ignore
+    return this.webex.internal.feature.getFeature('developer', DATA_CHANNEL_WITH_JWT_TOKEN);
+  }
+
+  /**
+   * Builds a WebSocket URL with the `subscriptionAwareSubchannels` query parameter.
+   *
+   * @param {string} baseUrl - The original WebSocket URL.
+   * @param {string[]} subchannels - List of subchannels to declare as subscription-aware.
+   * @returns {string} The final URL with updated query parameters.
+   */
+
+  public static buildUrlWithAwareSubchannels = (baseUrl: string, subchannels: string[]) => {
+    const urlObj = new URL(baseUrl);
+    urlObj.searchParams.set(SUBSCRIPTION_AWARE_SUBCHANNELS_PARAM, subchannels.join(','));
+
+    return urlObj.toString();
+  };
 }

package/src/llm.types.ts

@@ -1,9 +1,32 @@
 interface ILLMChannel {
-  registerAndConnect: (locusUrl: string, datachannelUrl: string) => Promise<void>;
-  isConnected: () => boolean;
-  getBinding: () => string;
-  getLocusUrl: () => string;
-  disconnectLLM: (options: {code: number; reason: string}) => Promise<void>;
+  registerAndConnect: (
+    locusUrl: string,
+    datachannelUrl: string,
+    datachannelToken?: string,
+    sessionId?: string
+  ) => Promise<void>;
+  isConnected: (sessionId?: string) => boolean;
+  getBinding: (sessionId?: string) => string;
+  getLocusUrl: (sessionId?: string) => string;
+  getDatachannelUrl: (sessionId?: string) => string;
+  disconnectLLM: (options: {code: number; reason: string}, sessionId?: string) => Promise<void>;
+  disconnectAllLLM: (options?: {code: number; reason: string}) => Promise<void>;
+  getAllConnections: () => Map<
+    string,
+    {
+      webSocketUrl?: string;
+      binding?: string;
+      locusUrl?: string;
+      datachannelUrl?: string;
+      datachannelToken?: string;
+    }
+  >;
 }
+
+export enum DataChannelTokenType {
+  Default = 'llm-default-session',
+  PracticeSession = 'llm-practice-session',
+}
+
 // eslint-disable-next-line import/prefer-default-export
 export type {ILLMChannel};