@webex/internal-plugin-metrics 3.12.0-llmrefactor.1 → 3.12.0-llmrefactor.2

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

package/test/unit/spec/new-metrics.ts

@@ -9,19 +9,23 @@ import MockWebex from '@webex/test-helper-mock-webex';
 import sinon from 'sinon';
 
 describe('internal-plugin-metrics', () => {
-
-  const mockWebex = () => new MockWebex({
-    children: {
-      newMetrics: NewMetrics,
-    },
-    meetings: {
-    },
-    request: sinon.stub().resolves({}),
-    logger: {
-      log: sinon.stub(),
-      error: sinon.stub(),
-    }
-  });
+  const mockWebex = () =>
+    new MockWebex({
+      children: {
+        newMetrics: NewMetrics,
+      },
+      meetings: {
+        getBasicMeetingInformation: sinon.stub().callsFake((meetingId) => ({
+          id: meetingId,
+          correlationId: `correlation-${meetingId}`,
+        })),
+      },
+      request: sinon.stub().resolves({}),
+      logger: {
+        log: sinon.stub(),
+        error: sinon.stub(),
+      },
+    });
 
   describe('check submitClientEvent, submitFeatureEvent when webex is not ready', () => {
     let webex;
@@ -50,12 +54,14 @@ describe('internal-plugin-metrics', () => {
         payload: {
           meetingSummaryInfo: {
             featureName: 'syncSystemMuteStatus',
-            featureActions: [{
-              actionName: 'syncMeetingMicUnmuteStatusToSystem',
-              actionId: '14200',
-              isInitialValue: false,
-              clickCount: '1'
-            }]
+            featureActions: [
+              {
+                actionName: 'syncMeetingMicUnmuteStatusToSystem',
+                actionId: '14200',
+                isInitialValue: false,
+                clickCount: '1',
+              },
+            ],
           },
         },
       });
@@ -68,7 +74,6 @@ describe('internal-plugin-metrics', () => {
 
   describe('new-metrics contstructor', () => {
     it('checks callDiagnosticLatencies is defined before ready emit', () => {
-
       const webex = mockWebex();
 
       assert.instanceOf(webex.internal.newMetrics.callDiagnosticLatencies, CallDiagnosticLatencies);
@@ -124,7 +129,7 @@ describe('internal-plugin-metrics', () => {
 
     afterEach(() => {
       sinon.restore();
-    })
+    });
 
     it('lazy metrics backend initialization when checking if backend ready', () => {
       assert.isUndefined(webex.internal.newMetrics.behavioralMetrics);
@@ -135,10 +140,10 @@ describe('internal-plugin-metrics', () => {
       webex.internal.newMetrics.isReadyToSubmitOperationalEvents();
       assert.isDefined(webex.internal.newMetrics.operationalMetrics);
 
-      assert.isUndefined(webex.internal.newMetrics.businessMetrics)
+      assert.isUndefined(webex.internal.newMetrics.businessMetrics);
       webex.internal.newMetrics.isReadyToSubmitBusinessEvents();
       assert.isDefined(webex.internal.newMetrics.businessMetrics);
-    })
+    });
 
     it('returns the automated user classification', () => {
       assert.strictEqual(
@@ -148,7 +153,7 @@ describe('internal-plugin-metrics', () => {
     });
 
     it('passes the table through to the business metrics', () => {
-      assert.isUndefined(webex.internal.newMetrics.businessMetrics)
+      assert.isUndefined(webex.internal.newMetrics.businessMetrics);
       webex.internal.newMetrics.isReadyToSubmitBusinessEvents();
       assert.isDefined(webex.internal.newMetrics.businessMetrics);
       webex.internal.newMetrics.businessMetrics.submitBusinessEvent = sinon.stub();
@@ -156,14 +161,14 @@ describe('internal-plugin-metrics', () => {
         name: 'foobar',
         payload: {},
         table: 'test',
-        metadata: { foo: 'bar' },
+        metadata: {foo: 'bar'},
       });
 
       assert.calledWith(webex.internal.newMetrics.businessMetrics.submitBusinessEvent, {
         name: 'foobar',
         payload: {},
         table: 'test',
-        metadata: { foo: 'bar' },
+        metadata: {foo: 'bar'},
       });
     });
 
@@ -187,6 +192,87 @@ describe('internal-plugin-metrics', () => {
       });
     });
 
+    describe('privacy and security permission enrichment', () => {
+      const permission = {
+        camera: {status: 'GRANTED' as const},
+        microphone: {status: 'DENIED' as const, reason: 'DENIED_BY_USER' as const},
+        contentShare: {status: 'REQUESTING' as const},
+      };
+
+      it('enriches an eligible client event through the public metrics API', () => {
+        webex.internal.newMetrics.setPrivacyAndSecurityPermission(permission);
+        webex.internal.newMetrics.submitClientEvent({name: 'client.call.initiated'});
+
+        const submittedPayload =
+          webex.internal.newMetrics.callDiagnosticMetrics.submitClientEvent.firstCall.args[0]
+            .payload;
+
+        assert.deepEqual(submittedPayload.privacyAndSecurityPermission, {
+          camera: permission.camera,
+          microphone: permission.microphone,
+        });
+      });
+
+      it('uses the meeting correlation id to preserve history across identifier transitions', () => {
+        webex.meetings.getBasicMeetingInformation
+          .withArgs('meeting-1')
+          .returns({id: 'meeting-1', correlationId: 'correlation-1'});
+        webex.internal.newMetrics.setPrivacyAndSecurityPermission(permission);
+
+        webex.internal.newMetrics.submitClientEvent({
+          name: 'client.call.initiated',
+          options: {correlationId: 'correlation-1'},
+        });
+        webex.internal.newMetrics.submitClientEvent({
+          name: 'client.ice.end',
+          payload: {},
+          options: {meetingId: 'meeting-1'},
+        });
+
+        const submissions = webex.internal.newMetrics.callDiagnosticMetrics.submitClientEvent.args;
+
+        assert.property(submissions[0][0].payload, 'privacyAndSecurityPermission');
+        assert.notProperty(submissions[1][0].payload, 'privacyAndSecurityPermission');
+      });
+
+      it('uses the default scope when no correlation id can be resolved', () => {
+        webex.internal.newMetrics.setPrivacyAndSecurityPermission(permission);
+
+        webex.internal.newMetrics.submitClientEvent({
+          name: 'client.call.initiated',
+          options: {sessionCorrelationId: 'session-1'},
+        });
+        webex.internal.newMetrics.submitClientEvent({
+          name: 'client.ice.end',
+          payload: {},
+          options: {sessionCorrelationId: 'session-2'},
+        });
+
+        const submissions = webex.internal.newMetrics.callDiagnosticMetrics.submitClientEvent.args;
+
+        assert.property(submissions[0][0].payload, 'privacyAndSecurityPermission');
+        assert.notProperty(submissions[1][0].payload, 'privacyAndSecurityPermission');
+      });
+
+      it('captures the permission snapshot before a delayed event is queued', () => {
+        webex.internal.newMetrics.setPrivacyAndSecurityPermission(permission);
+        webex.internal.newMetrics.setDelaySubmitClientEvents({shouldDelay: true});
+        webex.internal.newMetrics.submitClientEvent({name: 'client.call.initiated'});
+        webex.internal.newMetrics.setPrivacyAndSecurityPermission({
+          camera: {status: 'DENIED' as const},
+        });
+
+        const submission =
+          webex.internal.newMetrics.callDiagnosticMetrics.submitClientEvent.firstCall.args[0];
+
+        assert.isTrue(submission.delaySubmitEvent);
+        assert.deepEqual(submission.payload.privacyAndSecurityPermission, {
+          camera: permission.camera,
+          microphone: permission.microphone,
+        });
+      });
+    });
+
     it('submits feature Event successfully', () => {
       webex.internal.newMetrics.submitFeatureEvent({
         name: 'client.feature.meeting.summary',
@@ -196,12 +282,14 @@ describe('internal-plugin-metrics', () => {
         payload: {
           meetingSummaryInfo: {
             featureName: 'syncSystemMuteStatus',
-            featureActions: [{
-              actionName: 'syncMeetingMicUnmuteStatusToSystem',
-              actionId: '14200',
-              isInitialValue: false,
-              clickCount: '1'
-            }]
+            featureActions: [
+              {
+                actionName: 'syncMeetingMicUnmuteStatusToSystem',
+                actionId: '14200',
+                isInitialValue: false,
+                clickCount: '1',
+              },
+            ],
           },
         },
       });
@@ -215,12 +303,14 @@ describe('internal-plugin-metrics', () => {
         payload: {
           meetingSummaryInfo: {
             featureName: 'syncSystemMuteStatus',
-            featureActions: [{
-              actionName: 'syncMeetingMicUnmuteStatusToSystem',
-              actionId: '14200',
-              isInitialValue: false,
-              clickCount: '1'
-            }]
+            featureActions: [
+              {
+                actionName: 'syncMeetingMicUnmuteStatusToSystem',
+                actionId: '14200',
+                isInitialValue: false,
+                clickCount: '1',
+              },
+            ],
           },
         },
         options: {meetingId: '123'},
@@ -281,9 +371,9 @@ describe('internal-plugin-metrics', () => {
           method: 'POST',
           api: 'metrics',
           resource: 'clientmetrics',
-          headers: { 'x-prelogin-userid': 'my-id' },
+          headers: {'x-prelogin-userid': 'my-id'},
           body: {},
-          qs: { alias: true },
+          qs: {alias: true},
         });
         assert.calledWith(
           webex.logger.log,
@@ -292,8 +382,8 @@ describe('internal-plugin-metrics', () => {
       });
 
       it('handles failed request correctly', async () => {
-        webex.request.rejects(new Error("test error"));
-        sinon.stub(Utils, 'generateCommonErrorMetadata').returns('formattedError')
+        webex.request.rejects(new Error('test error'));
+        sinon.stub(Utils, 'generateCommonErrorMetadata').returns('formattedError');
         try {
           await webex.internal.newMetrics.clientMetricsAliasUser({event: 'test'}, 'my-id');
         } catch (err) {
@@ -375,19 +465,26 @@ describe('internal-plugin-metrics', () => {
         sinon.assert.match(webex.internal.newMetrics.delaySubmitClientEvents, true);
         sinon.assert.match(webex.internal.newMetrics.delayedClientEventsOverrides, {});
 
-        webex.internal.newMetrics.setDelaySubmitClientEvents({shouldDelay: false, overrides: {foo: 'bar'}});
+        webex.internal.newMetrics.setDelaySubmitClientEvents({
+          shouldDelay: false,
+          overrides: {foo: 'bar'},
+        });
 
-        assert.calledOnce(webex.internal.newMetrics.callDiagnosticMetrics.submitDelayedClientEvents);
-        assert.calledWith(webex.internal.newMetrics.callDiagnosticMetrics.submitDelayedClientEvents, {foo: 'bar'});
+        assert.calledOnce(
+          webex.internal.newMetrics.callDiagnosticMetrics.submitDelayedClientEvents
+        );
+        assert.calledWith(
+          webex.internal.newMetrics.callDiagnosticMetrics.submitDelayedClientEvents,
+          {foo: 'bar'}
+        );
 
         sinon.assert.match(webex.internal.newMetrics.delaySubmitClientEvents, false);
         sinon.assert.match(webex.internal.newMetrics.delayedClientEventsOverrides, {foo: 'bar'});
       });
 
       it('should not fail when called before webex is ready', () => {
-
         // Create mock
-        webex = mockWebex()
+        webex = mockWebex();
 
         webex.internal.newMetrics.callDiagnosticLatencies.saveTimestamp = sinon.stub();
         webex.internal.newMetrics.callDiagnosticLatencies.clearTimestamps = sinon.stub();
@@ -402,7 +499,6 @@ describe('internal-plugin-metrics', () => {
         webex.internal.newMetrics.setDelaySubmitClientEvents({shouldDelay: false});
         // Webex is ready
         webex.emit('ready');
-
       });
     });
   });