@webex/internal-plugin-metrics 3.11.0 → 3.12.0-auth-prejoin-fetch.1

package/src/new-metrics.ts

@@ -9,6 +9,8 @@ import CallDiagnosticMetrics from './call-diagnostic/call-diagnostic-metrics';
 import BehavioralMetrics from './behavioral-metrics';
 import OperationalMetrics from './operational-metrics';
 import BusinessMetrics from './business-metrics';
+import PreLoginMetrics from './prelogin-metrics';
+import PreLoginMetricsBatcher from './prelogin-metrics-batcher';
 import {
   RecursivePartial,
   MetricEventProduct,
@@ -17,17 +19,20 @@ import {
   ClientEvent,
   FeatureEvent,
   EventPayload,
-  OperationalEvent,
   MediaQualityEvent,
   InternalEvent,
   SubmitClientEventOptions,
   Table,
   DelayedClientEvent,
   DelayedClientFeatureEvent,
+  PrivacyAndSecurityPermission,
 } from './metrics.types';
 import CallDiagnosticLatencies from './call-diagnostic/call-diagnostic-metrics-latencies';
 import {setMetricTimings} from './call-diagnostic/call-diagnostic-metrics.util';
 import {generateCommonErrorMetadata} from './utils';
+import {isAutomatedUser as detectAutomatedUser} from './automated-user';
+import PrivacyAndSecurityPermissionEnricher from './privacy-and-security-permission-enricher';
+import {startUnhandledExceptionTelemetry} from './unhandled-exception-telemetry';
 
 /**
  * Metrics plugin to centralize all types of metrics.
@@ -45,6 +50,7 @@ class Metrics extends WebexPlugin {
   behavioralMetrics: BehavioralMetrics;
   operationalMetrics: OperationalMetrics;
   businessMetrics: BusinessMetrics;
+  preLoginMetrics: PreLoginMetrics;
   isReady = false;
 
   /**
@@ -64,6 +70,8 @@ class Metrics extends WebexPlugin {
 
   delayedClientFeatureEventsOverrides: Partial<DelayedClientFeatureEvent['options']> = {};
 
+  private privacyAndSecurityPermissionEnricher: PrivacyAndSecurityPermissionEnricher;
+
   /**
    * Constructor
    * @param args
@@ -74,8 +82,19 @@ class Metrics extends WebexPlugin {
   constructor(...args) {
     super(...args);
 
+    this.privacyAndSecurityPermissionEnricher = new PrivacyAndSecurityPermissionEnricher(
+      (error) => {
+        // @ts-ignore
+        this.webex.logger.error(
+          'NewMetrics: @submitClientEvent. Privacy and security permission enrichment failed.',
+          error
+        );
+      }
+    );
     // @ts-ignore
     this.callDiagnosticLatencies = new CallDiagnosticLatencies({}, {parent: this.webex});
+    // @ts-ignore
+    this.callDiagnosticMetrics = new CallDiagnosticMetrics({}, {parent: this.webex});
     this.onReady();
   }
 
@@ -85,13 +104,20 @@ class Metrics extends WebexPlugin {
   private onReady() {
     // @ts-ignore
     this.webex.once('ready', () => {
-      // @ts-ignore
-      this.callDiagnosticMetrics = new CallDiagnosticMetrics({}, {parent: this.webex});
+      this.preLoginMetrics = new PreLoginMetrics(
+        // @ts-ignore
+        new PreLoginMetricsBatcher({}, {parent: this.webex}),
+        {},
+        // @ts-ignore
+        {parent: this.webex}
+      );
       this.isReady = true;
       this.setDelaySubmitClientEvents({
         shouldDelay: this.delaySubmitClientEvents,
         overrides: this.delayedClientEventsOverrides,
       });
+      // @ts-ignore
+      startUnhandledExceptionTelemetry(this.webex);
     });
   }
 
@@ -172,6 +198,13 @@ class Metrics extends WebexPlugin {
     return this.businessMetrics?.isReadyToSubmitEvents() ?? false;
   }
 
+  /**
+   * @returns whether the current user agent belongs to an automated user
+   */
+  isAutomatedUser() {
+    return detectAutomatedUser();
+  }
+
   /**
    * Behavioral event
    * @param args
@@ -251,6 +284,38 @@ class Metrics extends WebexPlugin {
     return this.businessMetrics.submitBusinessEvent({name, payload, table, metadata});
   }
 
+  /**
+   * Call Analyzer: Pre-Login Event
+   * @param args
+   */
+  submitPreLoginEvent({
+    name,
+    preLoginId,
+    payload,
+    metadata,
+  }: {
+    name: string;
+    preLoginId: string;
+    payload: EventPayload;
+    metadata?: EventPayload;
+  }): Promise<void> {
+    if (!this.isReady) {
+      // @ts-ignore
+      this.webex.logger.log(
+        `NewMetrics: @submitPreLoginEvent. Attempted to submit before webex.ready: ${name}`
+      );
+
+      return Promise.resolve();
+    }
+
+    return this.preLoginMetrics.submitPreLoginEvent({
+      name,
+      preLoginId,
+      payload,
+      metadata,
+    });
+  }
+
   /**
    * Call Analyzer: Media Quality Event
    * @param args
@@ -283,7 +348,7 @@ class Metrics extends WebexPlugin {
     payload?: RecursivePartial<FeatureEvent['payload']>;
     options: any;
   }) {
-    if (!this.callDiagnosticLatencies || !this.callDiagnosticMetrics) {
+    if (!this.isReady) {
       // @ts-ignore
       this.webex.logger.log(
         `NewMetrics: @submitFeatureEvent. Attempted to submit before webex.ready. Event name: ${name}`
@@ -318,7 +383,7 @@ class Metrics extends WebexPlugin {
     payload?: RecursivePartial<ClientEvent['payload']>;
     options?: SubmitClientEventOptions;
   }): Promise<any> {
-    if (!this.callDiagnosticLatencies || !this.callDiagnosticMetrics) {
+    if (!this.isReady) {
       // @ts-ignore
       this.webex.logger.log(
         `NewMetrics: @submitClientEvent. Attempted to submit before webex.ready. Event name: ${name}`
@@ -331,14 +396,41 @@ class Metrics extends WebexPlugin {
       options: {meetingId: options?.meetingId},
     });
 
-    return this.callDiagnosticMetrics.submitClientEvent({
+    const enrichedPayload = this.privacyAndSecurityPermissionEnricher.enrich({
       name,
       payload,
+      scope: this.getPermissionScope(options),
+    });
+
+    return this.callDiagnosticMetrics.submitClientEvent({
+      name,
+      payload: enrichedPayload,
       options,
       delaySubmitEvent: this.delaySubmitClientEvents,
     });
   }
 
+  /**
+   * Stores the latest browser permission state supplied by the client.
+   * @param permission latest normalized permission snapshot
+   */
+  public setPrivacyAndSecurityPermission(permission: PrivacyAndSecurityPermission): void {
+    this.privacyAndSecurityPermissionEnricher.setPermission(permission);
+  }
+
+  /**
+   * Resolves event options to the call identity used by Call Diagnostic where possible.
+   * @param options client event options
+   * @returns the permission history scope
+   */
+  private getPermissionScope(options?: SubmitClientEventOptions): string {
+    const meeting = options?.meetingId
+      ? (this as any).webex.meetings?.getBasicMeetingInformation?.(options.meetingId)
+      : undefined;
+
+    return options?.correlationId ?? meeting?.correlationId ?? 'default';
+  }
+
   /**
    * Issue request to alias a user's pre-login ID with their CI UUID
    * @param {string} preLoginId

package/src/prelogin-metrics.ts

@@ -0,0 +1,94 @@
+import GenericMetrics from './generic-metrics';
+import {BusinessEvent, EventPayload} from './metrics.types';
+import PreLoginMetricsBatcher from './prelogin-metrics-batcher';
+
+/**
+ * @description Util class to handle PreLogin Metrics
+ * @export
+ * @class PreLoginMetrics
+ */
+export default class PreLoginMetrics extends GenericMetrics {
+  private preLoginMetricsBatcher: typeof PreLoginMetricsBatcher;
+
+  /**
+   * Constructor
+   * @param {PreLoginMetricsBatcher} preLoginMetricsBatcher - Pre-login metrics batcher
+   * @param {any} attrs - Attributes
+   * @param {any} options - Options
+   * @constructor
+   */
+  constructor(
+    preLoginMetricsBatcher: typeof PreLoginMetricsBatcher,
+    attrs: any = {},
+    options: {parent?: any} = {}
+  ) {
+    super(attrs, options);
+    this.preLoginMetricsBatcher = preLoginMetricsBatcher;
+  }
+
+  /**
+   * Submit a business metric to our metrics endpoint.
+   * Routes to the correct table with the correct schema payload by table.
+   * @see https://confluence-eng-gpk2.cisco.com/conf/display/WAP/Business+metrics++-%3E+ROMA
+   * @param {Object} options - The options object
+   * @param {string} options.name - Name of the metric
+   * @param {string} options.preLoginId - ID to identify pre-login user
+   * @param {EventPayload} options.payload - User payload of the metric
+   * @param {EventPayload} [options.metadata] - Optional metadata to include outside of eventPayload.value
+   * @returns {Promise<void>} Promise that resolves when the metric is submitted
+   */
+  public submitPreLoginEvent({
+    name,
+    preLoginId,
+    payload,
+    metadata,
+  }: {
+    name: string;
+    preLoginId: string;
+    payload: EventPayload;
+    metadata?: EventPayload;
+  }): Promise<void> {
+    if (!metadata) {
+      metadata = {};
+    }
+    if (!metadata.appType) {
+      metadata.appType = 'Web Client';
+    }
+
+    const finalEvent = this.buildEvent(name, preLoginId, payload, metadata);
+
+    this.preLoginMetricsBatcher.savePreLoginId(preLoginId);
+
+    return this.preLoginMetricsBatcher.request(finalEvent);
+  }
+
+  /**
+   * Builds a formatted event object for metrics submission.
+   * @param {string} metricName - Metric name
+   * @param {string} preLoginId - Pre-login user identifier
+   * @param {EventPayload} payload - Metric payload data
+   * @param {EventPayload} metadata - Additional metadata to include in the event
+   * @returns {object} Formatted metrics event object with type, eventPayload, and timestamp
+   */
+  private buildEvent(
+    metricName: string,
+    preLoginId: string,
+    payload: EventPayload,
+    metadata: EventPayload
+  ): BusinessEvent {
+    return {
+      type: ['business'],
+      eventPayload: {
+        metricName,
+        browserDetails: this.getBrowserDetails(),
+        context: this.getContext(),
+        timestamp: new Date().getTime(),
+        value: {
+          preLoginId,
+          ...metadata,
+          ...payload,
+        },
+      },
+    };
+  }
+}

package/src/privacy-and-security-permission-enricher/constants.ts

@@ -0,0 +1,33 @@
+import type {ClientEvent} from '../metrics.types';
+import type {PermissionEnrichmentPolicy} from './types';
+
+export const CAMERA_AND_MICROPHONE_PERMISSION_EVENTS = new Set<ClientEvent['name']>([
+  'client.call.initiated',
+  'client.media.capabilities',
+  'client.ice.end',
+  'client.locus.join.request',
+  'client.locus.join.response',
+  'client.media-engine.ready',
+]);
+
+export const MEDIA_TX_PERMISSION_EVENTS = new Set<ClientEvent['name']>([
+  'client.media.tx.start',
+  'client.media.tx.stop',
+]);
+
+export const CONTENT_SHARE_PERMISSION_EVENTS = new Set<ClientEvent['name']>([
+  'client.share.initiated',
+  'client.share.floor-grant.request',
+  'client.share.floor-granted.local',
+]);
+
+export const FINAL_PERMISSION_EVENTS = new Set<ClientEvent['name']>([
+  'client.call.leave',
+  'client.call.remote-ended',
+  'client.call.aborted',
+]);
+
+export const NO_PERMISSION_ENRICHMENT: PermissionEnrichmentPolicy = {
+  resources: [],
+  terminal: false,
+};

package/src/privacy-and-security-permission-enricher/index.ts

@@ -0,0 +1,142 @@
+import type {ClientEventPayload, PrivacyAndSecurityPermission} from '../metrics.types';
+import {
+  CAMERA_AND_MICROPHONE_PERMISSION_EVENTS,
+  CONTENT_SHARE_PERMISSION_EVENTS,
+  FINAL_PERMISSION_EVENTS,
+  MEDIA_TX_PERMISSION_EVENTS,
+  NO_PERMISSION_ENRICHMENT,
+} from './constants';
+import type {
+  PermissionEnrichmentContext,
+  PermissionEnrichmentPolicy,
+  PermissionEnrichmentRule,
+} from './types';
+import {
+  getChangedPermission,
+  projectPrivacyAndSecurityPermission,
+  resolveContentShareResources,
+  resolveMediaResources,
+} from './utils';
+
+export const PERMISSION_ENRICHMENT_RULES = [
+  {
+    events: CAMERA_AND_MICROPHONE_PERMISSION_EVENTS,
+    resolve: () => ({resources: ['camera', 'microphone'], terminal: false}),
+  },
+  {
+    events: MEDIA_TX_PERMISSION_EVENTS,
+    resolve: (payload) => ({resources: resolveMediaResources(payload), terminal: false}),
+  },
+  {
+    events: CONTENT_SHARE_PERMISSION_EVENTS,
+    resolve: (payload) => ({
+      resources: resolveContentShareResources(payload),
+      terminal: false,
+    }),
+  },
+  {
+    events: FINAL_PERMISSION_EVENTS,
+    resolve: () => ({resources: ['camera', 'microphone', 'contentShare'], terminal: true}),
+  },
+] satisfies readonly PermissionEnrichmentRule[];
+
+const resolvePermissionEnrichmentPolicy = (
+  name: PermissionEnrichmentContext['name'],
+  payload?: ClientEventPayload
+): PermissionEnrichmentPolicy =>
+  PERMISSION_ENRICHMENT_RULES.find(({events}) => events.has(name))?.resolve(payload) ??
+  NO_PERMISSION_ENRICHMENT;
+
+/**
+ * Enriches eligible client events with relevant browser permission changes.
+ */
+export default class PrivacyAndSecurityPermissionEnricher {
+  private permission?: PrivacyAndSecurityPermission;
+
+  private lastReported = new Map<string, PrivacyAndSecurityPermission>();
+
+  private readonly onEnrichmentError: (error: unknown) => void;
+
+  /**
+   * Creates a permission enricher.
+   * @param {Function} onEnrichmentError permission enrichment error handler
+   */
+  constructor(onEnrichmentError: (error: unknown) => void) {
+    this.onEnrichmentError = onEnrichmentError;
+  }
+
+  /**
+   * Stores the latest normalized browser permission state.
+   * @param {PrivacyAndSecurityPermission} permission permission snapshot
+   * @returns {void}
+   */
+  public setPermission(permission: PrivacyAndSecurityPermission): void {
+    this.permission = projectPrivacyAndSecurityPermission(permission, [
+      'camera',
+      'microphone',
+      'contentShare',
+    ]);
+  }
+
+  /**
+   * Returns the original payload or a copy enriched with relevant permission changes.
+   * @param {PermissionEnrichmentContext} context event context and permission history scope
+   * @returns {ClientEventPayload | undefined}
+   */
+  public enrich({
+    name,
+    payload,
+    scope,
+  }: PermissionEnrichmentContext): ClientEventPayload | undefined {
+    const policy = resolvePermissionEnrichmentPolicy(name, payload);
+
+    try {
+      if (payload?.privacyAndSecurityPermission !== undefined) {
+        // An explicitly supplied permission payload is authoritative for this event.
+        if (!policy.terminal) {
+          this.lastReported.set(scope, {
+            ...this.lastReported.get(scope),
+            ...(payload.privacyAndSecurityPermission as PrivacyAndSecurityPermission),
+          });
+        }
+
+        return payload;
+      }
+
+      if (policy.resources.length === 0) {
+        return payload;
+      }
+
+      const projectedPermission = this.permission
+        ? projectPrivacyAndSecurityPermission(this.permission, policy.resources)
+        : undefined;
+
+      if (!projectedPermission) {
+        return payload;
+      }
+
+      if (policy.terminal) {
+        return {...payload, privacyAndSecurityPermission: projectedPermission};
+      }
+
+      const lastReported = this.lastReported.get(scope) ?? {};
+      const changedPermission = getChangedPermission(projectedPermission, lastReported);
+
+      if (!changedPermission) {
+        return payload;
+      }
+
+      this.lastReported.set(scope, {...lastReported, ...changedPermission});
+
+      return {...payload, privacyAndSecurityPermission: changedPermission};
+    } catch (error) {
+      this.onEnrichmentError(error);
+
+      return payload;
+    } finally {
+      if (policy.terminal) {
+        this.lastReported.delete(scope);
+      }
+    }
+  }
+}

package/src/privacy-and-security-permission-enricher/types.ts

@@ -0,0 +1,21 @@
+import type {
+  ClientEvent,
+  ClientEventPayload,
+  PrivacyAndSecurityPermissionResource,
+} from '../metrics.types';
+
+export type PermissionEnrichmentPolicy = {
+  resources: readonly PrivacyAndSecurityPermissionResource[];
+  terminal: boolean;
+};
+
+export type PermissionEnrichmentRule = {
+  events: ReadonlySet<ClientEvent['name']>;
+  resolve: (payload?: ClientEventPayload) => PermissionEnrichmentPolicy;
+};
+
+export type PermissionEnrichmentContext = {
+  name: ClientEvent['name'];
+  payload?: ClientEventPayload;
+  scope: string;
+};

package/src/privacy-and-security-permission-enricher/utils.ts

@@ -0,0 +1,82 @@
+import {isEqual} from 'lodash';
+
+import type {
+  ClientEventPayload,
+  PrivacyAndSecurityPermission,
+  PrivacyAndSecurityPermissionResource,
+} from '../metrics.types';
+
+export const resolveMediaResources = (
+  payload?: ClientEventPayload
+): PrivacyAndSecurityPermissionResource[] => {
+  switch (payload?.mediaType) {
+    case 'audio':
+      return ['microphone'];
+    case 'video':
+      return ['camera'];
+    case 'share':
+      return ['contentShare'];
+    default:
+      return [];
+  }
+};
+
+export const resolveContentShareResources = (
+  payload?: ClientEventPayload
+): PrivacyAndSecurityPermissionResource[] => {
+  if (payload?.mediaType !== 'share') {
+    return [];
+  }
+
+  return ['contentShare'];
+};
+
+const copyPermissionState = (
+  source: PrivacyAndSecurityPermission,
+  target: PrivacyAndSecurityPermission,
+  resource: PrivacyAndSecurityPermissionResource
+): void => {
+  switch (resource) {
+    case 'camera':
+      if (source.camera) {
+        target.camera = {...source.camera};
+      }
+      break;
+    case 'microphone':
+      if (source.microphone) {
+        target.microphone = {...source.microphone};
+      }
+      break;
+    case 'contentShare':
+      if (source.contentShare) {
+        target.contentShare = {...source.contentShare};
+      }
+      break;
+    default:
+      break;
+  }
+};
+
+export const projectPrivacyAndSecurityPermission = (
+  permission: PrivacyAndSecurityPermission,
+  resources: readonly PrivacyAndSecurityPermissionResource[]
+): PrivacyAndSecurityPermission | undefined => {
+  const projectedPermission: PrivacyAndSecurityPermission = {};
+
+  resources.forEach((resource) => {
+    copyPermissionState(permission, projectedPermission, resource);
+  });
+
+  return Object.keys(projectedPermission).length > 0 ? projectedPermission : undefined;
+};
+
+export const getChangedPermission = (
+  current: PrivacyAndSecurityPermission,
+  previous: PrivacyAndSecurityPermission
+): PrivacyAndSecurityPermission | undefined => {
+  const changedResources = (Object.keys(current) as PrivacyAndSecurityPermissionResource[]).filter(
+    (resource) => !isEqual(current[resource], previous[resource])
+  );
+
+  return projectPrivacyAndSecurityPermission(current, changedResources);
+};