@equinor/fusion-framework-module-analytics 0.1.1

package/src/AnalyticsConfigurator.ts

@@ -0,0 +1,116 @@
+import {
+  BaseConfigBuilder,
+  type ConfigBuilderCallbackArgs,
+  type ConfigBuilderCallback,
+} from '@equinor/fusion-framework-module';
+import type { IAnalyticsConfigurator, AnalyticsConfig } from './AnalyticsConfigurator.interface.js';
+import type { IAnalyticsCollector } from './collectors/AnalyticsCollector.interface.js';
+import type { IAnalyticsAdapter } from './adapters/AnalyticsAdapter.interface.js';
+import type { AnalyticsEvent } from './types.js';
+import { from, type ObservableInput } from 'rxjs';
+
+import { map, scan, filter, defaultIfEmpty, shareReplay, mergeMap } from 'rxjs/operators';
+
+/**
+ * Configures analytics settings for the module.
+ *
+ * The `AnalyticsConfigurator` class extends `BaseConfigBuilder` to provide a fluent API for
+ * setting up analytics adapters and collectors.
+ *
+ * @remarks
+ * - Adapters are managed internally and can be set using `setAdapter`.
+ * - Collectors are managed internally and can be set using `setCollector`.
+ * - All setter methods return `this` for method chaining.
+ *
+ * @see BaseConfigBuilder
+ * @see IAnalyticsConfigurator
+ */
+export class AnalyticsConfigurator
+  extends BaseConfigBuilder<AnalyticsConfig>
+  implements IAnalyticsConfigurator
+{
+  #collectorCallbacks: Record<string, ConfigBuilderCallback<IAnalyticsCollector>> = {};
+  #adapterCallbacks: Record<string, ConfigBuilderCallback<IAnalyticsAdapter>> = {};
+
+  constructor() {
+    super();
+
+    // Configure async collectors resolution using mergeMap to handle Promise/Observable collector factories
+    this._set(
+      'collectors',
+      (args: ConfigBuilderCallbackArgs): ObservableInput<Record<string, IAnalyticsCollector>> => {
+        return from(Object.entries(this.#collectorCallbacks)).pipe(
+          mergeMap(([identifier, collectorFn]) =>
+            from(collectorFn(args)).pipe(
+              filter((collector): collector is IAnalyticsCollector => !!collector),
+              map((collector) => [identifier, collector] as const),
+            ),
+          ),
+          scan(
+            (acc, [identifier, collector]) => {
+              acc[identifier] = collector;
+              return acc;
+            },
+            {} as Record<string, IAnalyticsCollector>,
+          ),
+          defaultIfEmpty({}),
+          shareReplay({ bufferSize: 1, refCount: true }),
+        );
+      },
+    );
+
+    // Configure async adapters resolution using mergeMap to handle Promise/Observable adapter factories
+    this._set(
+      'adapters',
+      (args: ConfigBuilderCallbackArgs): ObservableInput<Record<string, IAnalyticsAdapter>> => {
+        return from(Object.entries(this.#adapterCallbacks)).pipe(
+          mergeMap(([identifier, adapterFn]) =>
+            from(adapterFn(args)).pipe(
+              filter((adapter): adapter is IAnalyticsAdapter => !!adapter),
+              map((adapter) => [identifier, adapter] as const),
+            ),
+          ),
+          scan(
+            (acc, [identifier, adapter]) => {
+              acc[identifier] = adapter;
+              return acc;
+            },
+            {} as Record<string, IAnalyticsAdapter>,
+          ),
+          defaultIfEmpty({}),
+          shareReplay({ bufferSize: 1, refCount: true }),
+        );
+      },
+    );
+  }
+
+  /**
+   * Registers a analytics collector with the configurator.
+   *
+   * @param identifier - The name of the collector
+   * @param callback - A callback function that returns an analytics collector instance
+   * @returns The current instance for method chaining
+   */
+  setCollector<T extends AnalyticsEvent>(
+    identifier: string,
+    callback: ConfigBuilderCallback<IAnalyticsCollector<T>>,
+  ): this {
+    this.#collectorCallbacks[identifier] = callback;
+    return this;
+  }
+
+  /**
+   * Registers a analytics adapter with the configurator.
+   *
+   * @param identifier - The name of the adapter
+   * @param callback - A callback function that returns an analytics adapter instance
+   * @returns The current instance for method chaining
+   */
+  setAdapter<T extends AnalyticsEvent>(
+    identifier: string,
+    callback: ConfigBuilderCallback<IAnalyticsAdapter<T>>,
+  ): this {
+    this.#adapterCallbacks[identifier] = callback;
+    return this;
+  }
+}

package/src/AnalyticsProvider.interface.ts

@@ -0,0 +1,22 @@
+import type { ObservableInput, Subscription } from 'rxjs';
+import type { AnalyticsEvent } from './types.js';
+
+/**
+ * Interface for analytics providers used to track analytics events.
+ */
+export interface IAnalyticsProvider {
+  /**
+   * Tracks a analytics event.
+   *
+   * @param event - The analytic event to track.
+   */
+  trackAnalytic(event: AnalyticsEvent): void;
+
+  /**
+   * Uses a analytics stream and returns both Disposable and Subscription for cleanup.
+   *
+   * @param analytic$ - Observable input stream of analytic events.
+   * @returns Object containing both Disposable and Subscription for proper cleanup.
+   */
+  trackAnalytic$(analytic$: ObservableInput<AnalyticsEvent>): Disposable & Subscription;
+}

package/src/AnalyticsProvider.ts

@@ -0,0 +1,118 @@
+import { BaseModuleProvider } from '@equinor/fusion-framework-module/provider';
+
+import { version } from './version.js';
+
+import type { AnalyticsConfig } from './AnalyticsConfigurator.interface.js';
+import type { IAnalyticsProvider } from './AnalyticsProvider.interface.js';
+import type { AnalyticsEvent } from './types.js';
+import { from, type ObservableInput, Subject, Subscription } from 'rxjs';
+import type { IAnalyticsCollector } from './collectors/AnalyticsCollector.interface.js';
+import type { IAnalyticsAdapter } from './adapters/AnalyticsAdapter.interface.js';
+
+class DisposableSubscription extends Subscription {
+  constructor(subscription: Subscription) {
+    super(subscription.unsubscribe);
+  }
+
+  [Symbol.dispose] = () => {
+    this.unsubscribe();
+  };
+}
+
+/**
+ * Provides analytics tracking, adapters integration and collectors for application instrumentation.
+ *
+ * The `AnalyticsProvider` class is responsible for collecting, processing and relaying analytics
+ * data to the adapters. The events are collected with collectors.
+ *
+ * @typeParam AnalyticsConfig - The configuration type for analytics.
+ * @implements IAnalyticsProvider
+ * @extends BaseModuleProvider<AnalyticsConfig>
+ */
+export class AnalyticsProvider
+  extends BaseModuleProvider<AnalyticsConfig>
+  implements IAnalyticsProvider
+{
+  #analytics: Subject<AnalyticsEvent>;
+  #collectors: Record<string, IAnalyticsCollector>;
+  #adapters: Record<string, IAnalyticsAdapter>;
+
+  constructor(config: AnalyticsConfig) {
+    super({ version, config });
+
+    this.#analytics = new Subject();
+    this.#collectors = config.collectors;
+    this.#adapters = config.adapters;
+  }
+
+  /**
+   * Initializes the analytics provider with adapters and collectors.
+   *
+   * This method sets up the provider for operation by:
+   * 1. Storing the provided adapters
+   * 2. Initializing all adapters
+   * 3. Storing the provided collectors
+   * 4. Initializing all collectors
+   * 5. Setting up subscription for analytics processing
+   *
+   * @returns A promise that resolves when initialization is complete
+   */
+  async initialize(): Promise<void> {
+    const initializedCollectors = Object.values(this.#collectors).map((collector) =>
+      Promise.resolve(collector.initialize?.()),
+    );
+    const initializedAdapters = Object.values(this.#adapters).map((adapters) =>
+      Promise.resolve(adapters.initialize?.()),
+    );
+
+    await Promise.allSettled(initializedCollectors);
+    await Promise.allSettled(initializedAdapters);
+
+    for (const collector of Object.values(this.#collectors)) {
+      const subscription = collector.subscribe({
+        next: (event) => {
+          this.#analytics.next(event);
+        },
+      });
+
+      this._addTeardown(subscription);
+    }
+
+    const adapterSubscription = this.#analytics.subscribe({
+      next: (event) => {
+        for (const adapter of Object.values(this.#adapters)) {
+          adapter.registerAnalytic(event);
+        }
+      },
+    });
+    this._addTeardown(adapterSubscription);
+  }
+
+  /**
+   * Tracks an analytics event
+   *
+   * @param event - The analytics event to track
+   */
+  trackAnalytic(event: AnalyticsEvent): void {
+    // @TODO: Validate AnalyticsEvent includes name, value and attributes
+    this.#analytics.next(event);
+  }
+
+  /**
+   * Uses a analytics stream and returns both Disposable and Subscription for cleanup.
+   *
+   * @param analytic$ - Observable input stream of analytic events.
+   * @returns Object containing both Disposable and Subscription for proper cleanup.
+   */
+  trackAnalytic$(analytic$: ObservableInput<AnalyticsEvent>): Disposable & Subscription {
+    const subscription = from(analytic$)
+      // @TODO: Validate AnalyticsEvent includes name, value and attributes
+      .subscribe({
+        next: (event) => {
+          this.#analytics.next(event);
+        },
+      });
+
+    return new DisposableSubscription(subscription);
+  }
+}

package/src/adapters/AnalyticsAdapter.interface.ts

@@ -0,0 +1,23 @@
+import type { AnalyticsEvent } from '../types.js';
+
+/**
+ * Interface representing an analytics adapter responsible for handling analytics events.
+ *
+ * @template T - The type of analytics event handled by the adapter. Defaults to `AnalyticsEvent`.
+ */
+export interface IAnalyticsAdapter<T extends AnalyticsEvent = AnalyticsEvent> extends Disposable {
+  /**
+   * Initializes the analytics adapter for setup and configuration.
+   *
+   * @returns Promise that resolves when initialization is complete, or void for synchronous initialization.
+   */
+  initialize?(): Promise<void> | void;
+
+  /**
+   * Exports analytics event to the configured backend.
+   *
+   * @param events - Array of analytics events to export.
+   * @returns Promise that resolves when export is complete.
+   */
+  registerAnalytic(event: T): Promise<void> | void;
+}

package/src/adapters/ConsoleAnalyticsAdapter.ts

@@ -0,0 +1,17 @@
+import type { IAnalyticsAdapter } from './AnalyticsAdapter.interface.js';
+import type { AnalyticsEvent } from '../types.js';
+
+/**
+ * An analytics adapter printing the events to the console.
+ */
+export class ConsoleAnalyticsAdapter<T extends AnalyticsEvent = AnalyticsEvent>
+  implements IAnalyticsAdapter
+{
+  registerAnalytic(event: T): Promise<void> | void {
+    console.log('Analytics::Adapter::Console', event);
+  }
+
+  [Symbol.dispose]() {
+    // no-op
+  }
+}

package/src/adapters/FusionAnalyticsAdapter.ts

@@ -0,0 +1,61 @@
+import type { IAnalyticsAdapter } from './AnalyticsAdapter.interface.js';
+import type { AnalyticsEvent } from '../types.js';
+
+import {
+  LoggerProvider,
+  SimpleLogRecordProcessor,
+  type ReadableLogRecord,
+} from '@opentelemetry/sdk-logs';
+import type { OTLPExporterBase } from '@opentelemetry/otlp-exporter-base';
+import {
+  SeverityNumber,
+  type LogAttributes,
+  type Logger,
+  type LogRecord,
+} from '@opentelemetry/api-logs';
+import { resourceFromAttributes } from '@opentelemetry/resources';
+import { version } from '../version.js';
+import { v7 as uuid } from 'uuid';
+
+/**
+ * An analytics adapter for sending events to the log exporter for handling.
+ *
+ * The exporter is a Open Telemetry exporter.
+ * @see OTLPExporterBase
+ */
+export class FusionAnalyticsAdapter<T extends AnalyticsEvent = AnalyticsEvent>
+  implements IAnalyticsAdapter
+{
+  #logExporter: OTLPExporterBase<ReadableLogRecord[]>;
+  #loggerProvider: LoggerProvider;
+  #logger: Logger;
+
+  constructor(args: { portalId: string; logExporter: OTLPExporterBase<ReadableLogRecord[]> }) {
+    this.#logExporter = args.logExporter;
+
+    this.#loggerProvider = new LoggerProvider({
+      processors: [new SimpleLogRecordProcessor(this.#logExporter)],
+      resource: resourceFromAttributes({
+        'module.version': version,
+        'session.id': uuid(),
+        'portal.id': args.portalId,
+      }),
+    });
+    this.#logger = this.#loggerProvider.getLogger('fusion');
+  }
+
+  registerAnalytic(event: T): Promise<void> | void {
+    const logRecord: Partial<LogRecord> = {
+      eventName: event.name,
+      attributes: event.attributes as LogAttributes,
+      body: event.value,
+      severityNumber: SeverityNumber.INFO,
+    };
+    this.#logger.emit(logRecord);
+  }
+
+  [Symbol.dispose]() {
+    this.#logExporter.shutdown();
+    this.#loggerProvider.shutdown();
+  }
+}

package/src/adapters/index.ts

@@ -0,0 +1,3 @@
+export { IAnalyticsAdapter } from './AnalyticsAdapter.interface.js';
+export { ConsoleAnalyticsAdapter } from './ConsoleAnalyticsAdapter.js';
+export { FusionAnalyticsAdapter } from './FusionAnalyticsAdapter.js';

package/src/collectors/AnalyticsCollector.interface.ts

@@ -0,0 +1,18 @@
+import type { Subscribable } from 'rxjs';
+import type { AnalyticsEvent } from '../types.js';
+
+/**
+ * Interface representing an analytics collector responsible for sending analytics events.
+ *
+ * @template T - The type of analytics event handled by the adapter. Defaults to `AnalyticsEvent`.
+ */
+export interface IAnalyticsCollector<T extends AnalyticsEvent = AnalyticsEvent>
+  extends Subscribable<T> {
+  /**
+   * Initializes the analytics collector for setup and configuration.
+   * This method is optional - if not implemented, the collector should be directly subscribable.
+   *
+   * @returns Promise that resolves when initialization is complete, or void for synchronous initialization.
+   */
+  initialize?(): Promise<void> | void;
+}

package/src/collectors/AppLoadedCollector.ts

@@ -0,0 +1,74 @@
+import { BaseCollector, createSchema } from './BaseCollector.js';
+import { type AppItemType, appSchema, extractAppMetadata } from './utils/extractAppMetadata.js';
+import {
+  type ContextItemType,
+  contextSchema,
+  extractContextMetadata,
+} from './utils/extractContextMetadata.js';
+import type { IAnalyticsCollector } from './AnalyticsCollector.interface.js';
+
+import type {
+  AppModulesInstance,
+  AppManifest,
+  AppModuleProvider,
+} from '@equinor/fusion-framework-module-app';
+import type { IEventModuleProvider } from '@equinor/fusion-framework-module-event';
+
+import { type ObservableInput, Subject } from 'rxjs';
+import { z } from 'zod';
+import type { ContextModule } from '@equinor/fusion-framework-module-context';
+
+const EVENT_NAME = 'onAppModulesLoaded';
+
+/**
+ * The schema of the data to be sent.
+ */
+const eventSchema = createSchema(appSchema, z.object({ context: contextSchema }));
+
+/**
+ * Collector to listen for app loaded and add values and attributes for
+ * further processing by adapters.
+ */
+export class AppLoadedCollector
+  extends BaseCollector<AppItemType, { context?: ContextItemType }>
+  implements IAnalyticsCollector
+{
+  #eventProvider: IEventModuleProvider;
+  #appProvider: AppModuleProvider;
+
+  constructor(eventProvider: IEventModuleProvider, appProvider: AppModuleProvider) {
+    super('app-loaded', eventSchema);
+    this.#eventProvider = eventProvider;
+    this.#appProvider = appProvider;
+  }
+
+  _initialize(): ObservableInput<{
+    value: AppItemType;
+    attributes: { context?: ContextItemType };
+  }> {
+    const subject = new Subject<{
+      value: AppItemType;
+      attributes: { context?: ContextItemType };
+    }>();
+    this.#eventProvider.addEventListener(EVENT_NAME, (event) => {
+      // Fallback to appProvider for manifest if app is not updated with latest
+      // payload for onAppModulesLoaded (missing manifest).
+      const manifest =
+        (event.detail.manifest as AppManifest) ?? this.#appProvider.current?.manifest;
+      const modules = event.detail.modules as AppModulesInstance<[ContextModule]>;
+
+      const data = {
+        value: manifest && extractAppMetadata(manifest),
+        attributes: {
+          context:
+            modules.context?.currentContext &&
+            extractContextMetadata(modules.context.currentContext),
+        },
+      };
+
+      subject.next(data);
+    });
+
+    return subject;
+  }
+}

package/src/collectors/AppSelectedCollector.ts

@@ -0,0 +1,53 @@
+import { map, type ObservableInput, pairwise } from 'rxjs';
+import type { IAnalyticsCollector } from './AnalyticsCollector.interface.js';
+import { BaseCollector, createSchema } from './BaseCollector.js';
+import {
+  type AppKeyType,
+  appKeySchema,
+  extractAppKeyMetadata,
+} from './utils/extractAppMetadata.js';
+
+import type { AppModuleProvider } from '@equinor/fusion-framework-module-app';
+
+import { z } from 'zod';
+
+/**
+ * The schema of the data to be sent.
+ */
+const eventSchema = createSchema(appKeySchema, z.object({ previous: appKeySchema }));
+
+/**
+ * Collector to listen for app selection and add values and attributes for
+ * further processing by adapters.
+ */
+export class AppSelectedCollector
+  extends BaseCollector<AppKeyType, { previous?: AppKeyType }>
+  implements IAnalyticsCollector
+{
+  #appProvider: AppModuleProvider;
+
+  constructor(appProvider: AppModuleProvider) {
+    super('app-selected', eventSchema);
+    this.#appProvider = appProvider;
+  }
+
+  _initialize(): ObservableInput<{
+    value: AppKeyType;
+    attributes: { previous?: AppKeyType };
+  }> {
+    const appSelected$ = this.#appProvider.current$.pipe(pairwise());
+
+    const data$ = appSelected$.pipe(
+      map(([prev, next]) => {
+        return {
+          value: extractAppKeyMetadata(next),
+          attributes: {
+            previous: prev && extractAppKeyMetadata(prev),
+          },
+        };
+      }),
+    );
+
+    return data$;
+  }
+}

package/src/collectors/BaseCollector.ts

@@ -0,0 +1,65 @@
+import type { AnyValue, AnyValueMap, AnalyticsEvent } from '../types.js';
+import type { IAnalyticsCollector } from './AnalyticsCollector.interface.js';
+
+import { from, map, type ObservableInput, Subject, type Observer, type Unsubscribable } from 'rxjs';
+import { z } from 'zod';
+
+/**
+ * Function to create zod schema to be used when collecting
+ */
+export const createSchema = <TValue = AnyValue, TAttr = AnyValueMap>(
+  value: z.ZodSchema<TValue>,
+  attributes: z.ZodSchema<TAttr>,
+) => {
+  return z.object({
+    name: z.string(),
+    value: value,
+    attributes: attributes.optional(),
+  });
+};
+
+export type CollectorSchema<TValue = AnyValue, TAttr = AnyValueMap> = ReturnType<
+  typeof createSchema<TValue, TAttr>
+>;
+
+/**
+ * A base collector to help with parsing the events with provided schema before
+ * emitting.
+ */
+export abstract class BaseCollector<
+  TValue extends AnyValue,
+  TAttr extends AnyValueMap = AnyValueMap,
+> implements IAnalyticsCollector<AnalyticsEvent<TValue, TAttr>>
+{
+  #schema: CollectorSchema<TValue, TAttr>;
+  #name: string;
+  #subject: Subject<z.infer<CollectorSchema<TValue, TAttr>>> = new Subject<
+    z.infer<CollectorSchema<TValue, TAttr>>
+  >();
+
+  constructor(name: string, schema: CollectorSchema<TValue, TAttr>) {
+    this.#name = name;
+    this.#schema = schema;
+  }
+
+  abstract _initialize(): ObservableInput<{ value: TValue; attributes: TAttr }>;
+
+  initialize(): Promise<void> | void {
+    from(this._initialize())
+      .pipe(
+        map(({ value, attributes }) => {
+          return {
+            name: this.#name,
+            value: value,
+            attributes: attributes,
+          };
+        }),
+        map((x) => this.#schema.parse(x)),
+      )
+      .subscribe(this.#subject);
+  }
+
+  subscribe(observer: Partial<Observer<z.infer<CollectorSchema<TValue, TAttr>>>>): Unsubscribable {
+    return this.#subject.subscribe(observer);
+  }
+}

package/src/collectors/ContextSelectedCollector.ts

@@ -0,0 +1,56 @@
+import { distinctUntilChanged, map, type ObservableInput, pairwise } from 'rxjs';
+import type { IAnalyticsCollector } from './AnalyticsCollector.interface.js';
+import type { IContextProvider } from '@equinor/fusion-framework-module-context';
+import { z } from 'zod';
+import { BaseCollector, createSchema } from './BaseCollector.js';
+import {
+  type ContextItemType,
+  contextSchema,
+  extractContextMetadata,
+} from './utils/extractContextMetadata.js';
+
+/**
+ * The schema of the data to be sent.
+ */
+const eventSchema = createSchema(contextSchema, z.object({ previous: contextSchema }));
+
+/**
+ * Collector to listen for context changes and add values and attributes for
+ * further processing by adapters.
+ */
+export class ContextSelectedCollector
+  extends BaseCollector<ContextItemType, { previous?: ContextItemType }>
+  implements IAnalyticsCollector
+{
+  #contextProvider: IContextProvider;
+
+  constructor(contextProvider: IContextProvider) {
+    super('context-selected', eventSchema);
+    this.#contextProvider = contextProvider;
+  }
+
+  _initialize(): ObservableInput<{
+    value: ContextItemType;
+    attributes: { previous?: ContextItemType };
+  }> {
+    const contextSelected$ = this.#contextProvider.currentContext$.pipe(
+      // Only emit when an actual change has happened.
+      distinctUntilChanged((prev, curr) => prev?.id === curr?.id),
+      // Provide both the old and the new value.
+      pairwise(),
+    );
+
+    const data$ = contextSelected$.pipe(
+      map(([prev, next]) => {
+        return {
+          value: next && extractContextMetadata(next),
+          attributes: {
+            previous: prev && extractContextMetadata(prev),
+          },
+        };
+      }),
+    );
+
+    return data$;
+  }
+}

package/src/collectors/index.ts

@@ -0,0 +1,4 @@
+export { IAnalyticsCollector } from './AnalyticsCollector.interface.js';
+export { ContextSelectedCollector } from './ContextSelectedCollector.js';
+export { AppSelectedCollector } from './AppSelectedCollector.js';
+export { AppLoadedCollector } from './AppLoadedCollector.js';

package/src/collectors/utils/extractAppMetadata.ts

@@ -0,0 +1,45 @@
+import { z } from 'zod';
+import type { AppManifest, CurrentApp } from '@equinor/fusion-framework-module-app';
+
+// Schema representing an object with key appKey and a string value.
+// Used to parse an object containing appKey.
+export const appKeySchema = z
+  .object({
+    appKey: z.string().optional(),
+  })
+  .optional()
+  .nullable();
+
+// Schema representing an object with data points of an app.
+// Used to parse an object with app data.
+export const appSchema = z
+  .object({
+    appKey: z.string(),
+    displayName: z.string(),
+    type: z.string(),
+    categoryName: z.string().optional(),
+    buildVersion: z.string().optional(),
+    buildTag: z.string().optional().nullable(),
+  })
+  .optional();
+
+export type AppKeyType = z.infer<typeof appKeySchema>;
+
+export type AppItemType = z.infer<typeof appSchema>;
+
+export const extractAppKeyMetadata = (app: CurrentApp): z.input<typeof appKeySchema> => {
+  return {
+    appKey: app?.appKey,
+  };
+};
+
+export const extractAppMetadata = (app: AppManifest): z.input<typeof appSchema> => {
+  return {
+    appKey: app.appKey,
+    displayName: app.displayName,
+    type: app.type,
+    categoryName: app.category?.name,
+    buildVersion: app.build?.version,
+    buildTag: app.build?.tag,
+  };
+};