feat: add user activity tracking for embedded apps

Author: mrednic-1A

packages/@ama-mfe/messages/src/messages/user-activity/base.ts

@@ -0,0 +1,14 @@
+/** The user activity message type used for communication between shell and iframes */
+export const USER_ACTIVITY_MESSAGE_TYPE = 'user_activity';
+
+/**
+ * Types of user activity events that can be tracked
+ */
+export type UserActivityEventType =
+  | 'click'
+  | 'keydown'
+  | 'scroll'
+  | 'touchstart'
+  | 'focus'
+  | 'visibilitychange'
+  | 'iframeinteraction';

packages/@ama-mfe/messages/src/messages/user-activity/index.ts

@@ -0,0 +1,8 @@
+import type {
+  UserActivityMessageV1_0,
+} from './user-activity-versions';
+
+/** The versions of user activity messages */
+export type UserActivityMessage = UserActivityMessageV1_0;
+export * from './user-activity-versions';
+export { USER_ACTIVITY_MESSAGE_TYPE, type UserActivityEventType } from './base';

packages/@ama-mfe/messages/src/messages/user-activity/user-activity-versions.ts

@@ -0,0 +1,22 @@
+import type {
+  VersionedMessage,
+} from '@amadeus-it-group/microfrontends';
+import type {
+  USER_ACTIVITY_MESSAGE_TYPE,
+  UserActivityEventType,
+} from './base';
+
+/**
+ * User activity message version 1.0
+ * Sent from embedded modules to the shell to indicate user interaction
+ */
+export interface UserActivityMessageV1_0 extends VersionedMessage {
+  /** @inheritdoc */
+  type: typeof USER_ACTIVITY_MESSAGE_TYPE;
+  /** @inheritdoc */
+  version: '1.0';
+  /** The type of activity event that occurred */
+  eventType: UserActivityEventType;
+  /** Timestamp when the activity occurred */
+  timestamp: number;
+}

packages/@ama-mfe/messages/src/public_api.ts

@@ -2,3 +2,4 @@ export * from './messages/history/index';
 export * from './messages/navigation/index';
 export * from './messages/resize/index';
 export * from './messages/theme/index';
+export * from './messages/user-activity/index';

packages/@ama-mfe/ng-utils/src/messages/index.ts

@@ -1,3 +1,4 @@
 export * from './available-sender';
 export * from './error-sender';
 export * from './error/index';
+export * from './user-activity';

packages/@ama-mfe/ng-utils/src/messages/user-activity.spec.ts

@@ -0,0 +1,87 @@
+import {
+  USER_ACTIVITY_MESSAGE_TYPE,
+  type UserActivityMessageV1_0,
+} from '@ama-mfe/messages';
+import {
+  isUserActivityMessage,
+} from './user-activity';
+
+describe('isUserActivityMessage', () => {
+  it('should return true for valid UserActivityMessageV1_0', () => {
+    const message: UserActivityMessageV1_0 = {
+      type: USER_ACTIVITY_MESSAGE_TYPE,
+      version: '1.0',
+      eventType: 'click',
+      timestamp: Date.now()
+    };
+
+    expect(isUserActivityMessage(message)).toBe(true);
+  });
+
+  it('should return true for all valid event types', () => {
+    const eventTypes = ['click', 'keydown', 'scroll', 'touchstart', 'focus', 'visibilitychange', 'iframeinteraction'] as const;
+
+    eventTypes.forEach((eventType) => {
+      const message: UserActivityMessageV1_0 = {
+        type: USER_ACTIVITY_MESSAGE_TYPE,
+        version: '1.0',
+        eventType,
+        timestamp: Date.now()
+      };
+
+      expect(isUserActivityMessage(message)).toBe(true);
+    });
+  });
+
+  it('should return false for null', () => {
+    expect(isUserActivityMessage(null)).toBe(false);
+  });
+
+  it('should return false for undefined', () => {
+    expect(isUserActivityMessage(undefined)).toBe(false);
+  });
+
+  it('should return false for non-object values', () => {
+    expect(isUserActivityMessage('string')).toBe(false);
+    expect(isUserActivityMessage(123)).toBe(false);
+    expect(isUserActivityMessage(true)).toBe(false);
+  });
+
+  it('should return false for object without type property', () => {
+    const message = {
+      version: '1.0',
+      eventType: 'click',
+      timestamp: Date.now()
+    };
+
+    expect(isUserActivityMessage(message)).toBe(false);
+  });
+
+  it('should return false for object with wrong type', () => {
+    const message = {
+      type: 'wrong_type',
+      version: '1.0',
+      eventType: 'click',
+      timestamp: Date.now()
+    };
+
+    expect(isUserActivityMessage(message)).toBe(false);
+  });
+
+  it('should return false for empty object', () => {
+    expect(isUserActivityMessage({})).toBe(false);
+  });
+
+  it('should return false for array', () => {
+    expect(isUserActivityMessage([])).toBe(false);
+  });
+
+  it('should return true even if other properties are missing (only checks type)', () => {
+    // The type guard only checks for the type property
+    const message = {
+      type: USER_ACTIVITY_MESSAGE_TYPE
+    };
+
+    expect(isUserActivityMessage(message)).toBe(true);
+  });
+});

packages/@ama-mfe/ng-utils/src/messages/user-activity.ts

@@ -0,0 +1,20 @@
+import {
+  USER_ACTIVITY_MESSAGE_TYPE,
+  type UserActivityMessage,
+} from '@ama-mfe/messages';
+import type {
+  VersionedMessage,
+} from '@amadeus-it-group/microfrontends';
+
+/**
+ * Type guard to check if a message is a user activity message
+ * @param message The message to check
+ */
+export function isUserActivityMessage(message: unknown): message is UserActivityMessage {
+  return (
+    typeof message === 'object'
+    && message !== null
+    && 'type' in message
+    && (message as VersionedMessage).type === USER_ACTIVITY_MESSAGE_TYPE
+  );
+}

packages/@ama-mfe/ng-utils/src/public_api.ts

@@ -6,4 +6,5 @@ export * from './messages/index';
 export * from './navigation/index';
 export * from './resize/index';
 export * from './theme/index';
+export * from './user-activity/index';
 export * from './utils';

packages/@ama-mfe/ng-utils/src/user-activity/activity-consumer.service.spec.ts

@@ -0,0 +1,186 @@
+import {
+  USER_ACTIVITY_MESSAGE_TYPE,
+  type UserActivityMessageV1_0,
+} from '@ama-mfe/messages';
+import type {
+  RoutedMessage,
+} from '@amadeus-it-group/microfrontends';
+import {
+  TestBed,
+} from '@angular/core/testing';
+import {
+  ActivityConsumerService,
+} from './activity-consumer.service';
+import {
+  ConsumerManagerService,
+} from '@ama-mfe/ng-utils';
+
+describe('ActivityConsumerService', () => {
+  let service: ActivityConsumerService;
+  let consumerManagerServiceMock: jest.Mocked<ConsumerManagerService>;
+
+  beforeEach(() => {
+    consumerManagerServiceMock = {
+      register: jest.fn(),
+      unregister: jest.fn()
+    } as unknown as jest.Mocked<ConsumerManagerService>;
+
+    TestBed.configureTestingModule({
+      providers: [
+        ActivityConsumerService,
+        { provide: ConsumerManagerService, useValue: consumerManagerServiceMock }
+      ]
+    });
+
+    service = TestBed.inject(ActivityConsumerService);
+  });
+
+  afterEach(() => {
+    jest.resetAllMocks();
+  });
+
+  describe('initialization', () => {
+    it('should be created', () => {
+      expect(service).toBeDefined();
+      expect(service instanceof ActivityConsumerService).toBe(true);
+    });
+
+    it('should have the correct message type', () => {
+      expect(service.type).toBe(USER_ACTIVITY_MESSAGE_TYPE);
+    });
+
+    it('should have supported version 1.0', () => {
+      expect(service.supportedVersions['1.0']).toBeDefined();
+      expect(typeof service.supportedVersions['1.0']).toBe('function');
+    });
+
+    it('should have undefined latestReceivedActivity initially', () => {
+      expect(service.latestReceivedActivity()).toBeUndefined();
+    });
+  });
+
+  describe('start', () => {
+    it('should register with consumer manager service', () => {
+      service.start();
+
+      expect(consumerManagerServiceMock.register).toHaveBeenCalledWith(service);
+      expect(consumerManagerServiceMock.register).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('stop', () => {
+    it('should unregister from consumer manager service', () => {
+      service.stop();
+
+      expect(consumerManagerServiceMock.unregister).toHaveBeenCalledWith(service);
+      expect(consumerManagerServiceMock.unregister).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('supportedVersions["1.0"]', () => {
+    it('should update latestReceivedActivity signal with message data', () => {
+      const mockMessage: RoutedMessage<UserActivityMessageV1_0> = {
+        from: 'test-channel-id',
+        to: ['consumer'],
+        payload: {
+          type: USER_ACTIVITY_MESSAGE_TYPE,
+          version: '1.0',
+          eventType: 'click',
+          timestamp: 1_234_567_890
+        }
+      };
+
+      service.supportedVersions['1.0'](mockMessage);
+
+      const activity = service.latestReceivedActivity();
+      expect(activity).toBeDefined();
+      expect(activity?.channelId).toBe('test-channel-id');
+      expect(activity?.eventType).toBe('click');
+      expect(activity?.timestamp).toBe(1_234_567_890);
+    });
+
+    it('should use "unknown" as channelId when from is undefined', () => {
+      const mockMessage: RoutedMessage<UserActivityMessageV1_0> = {
+        from: undefined,
+        to: ['consumer'],
+        payload: {
+          type: USER_ACTIVITY_MESSAGE_TYPE,
+          version: '1.0',
+          eventType: 'keydown',
+          timestamp: 9_876_543_210
+        }
+      };
+
+      service.supportedVersions['1.0'](mockMessage);
+
+      const activity = service.latestReceivedActivity();
+      expect(activity?.channelId).toBe('unknown');
+    });
+
+    it('should update latestReceivedActivity on subsequent messages', () => {
+      const firstMessage: RoutedMessage<UserActivityMessageV1_0> = {
+        from: 'channel-1',
+        to: ['consumer'],
+        payload: {
+          type: USER_ACTIVITY_MESSAGE_TYPE,
+          version: '1.0',
+          eventType: 'click',
+          timestamp: 1000
+        }
+      };
+
+      const secondMessage: RoutedMessage<UserActivityMessageV1_0> = {
+        from: 'channel-2',
+        to: ['consumer'],
+        payload: {
+          type: USER_ACTIVITY_MESSAGE_TYPE,
+          version: '1.0',
+          eventType: 'scroll',
+          timestamp: 2000
+        }
+      };
+
+      service.supportedVersions['1.0'](firstMessage);
+      expect(service.latestReceivedActivity()?.channelId).toBe('channel-1');
+      expect(service.latestReceivedActivity()?.eventType).toBe('click');
+
+      service.supportedVersions['1.0'](secondMessage);
+      expect(service.latestReceivedActivity()?.channelId).toBe('channel-2');
+      expect(service.latestReceivedActivity()?.eventType).toBe('scroll');
+      expect(service.latestReceivedActivity()?.timestamp).toBe(2000);
+    });
+
+    it('should handle all event types', () => {
+      const eventTypes = ['click', 'keydown', 'scroll', 'touchstart', 'focus', 'visibilitychange'] as const;
+
+      eventTypes.forEach((eventType) => {
+        const mockMessage: RoutedMessage<UserActivityMessageV1_0> = {
+          from: 'test-channel',
+          to: ['consumer'],
+          payload: {
+            type: USER_ACTIVITY_MESSAGE_TYPE,
+            version: '1.0',
+            eventType,
+            timestamp: Date.now()
+          }
+        };
+
+        service.supportedVersions['1.0'](mockMessage);
+        expect(service.latestReceivedActivity()?.eventType).toBe(eventType);
+      });
+    });
+  });
+
+  describe('latestReceivedActivity signal', () => {
+    it('should be read-only', () => {
+      // The signal should be a readonly signal (no set method exposed)
+      expect(service.latestReceivedActivity).toBeDefined();
+      expect(typeof service.latestReceivedActivity).toBe('function');
+      // Verify it's not a WritableSignal by checking it doesn't have set/update methods
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access -- testing signal type
+      expect((service.latestReceivedActivity as any).set).toBeUndefined();
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access -- testing signal type
+      expect((service.latestReceivedActivity as any).update).toBeUndefined();
+    });
+  });
+});