@equinor/fusion-framework-module-analytics 3.1.0 → 3.1.1

package/docs/testing.md

@@ -1,87 +0,0 @@
-# Testing
-
-Use `MockAnalyticsAdapter` from `@equinor/fusion-framework-module-analytics/mock` to assert on tracked analytics events without exporting them to a real backend. Register it like any other adapter via `setAdapter`, then query or await recorded events from your test:
-
-```ts
-import { enableAnalytics } from '@equinor/fusion-framework-module-analytics';
-import { MockAnalyticsAdapter } from '@equinor/fusion-framework-module-analytics/mock';
-
-const recorder = new MockAnalyticsAdapter();
-
-enableAnalytics(configurator, (builder) => {
-  builder.setAdapter('mock', async () => recorder);
-});
-
-// ... exercise the app under test, then assert:
-const event = await recorder.waitForAnalytic('button-click');
-expect(event.attributes?.section).toBe('header');
-
-// or synchronously inspect everything recorded so far:
-expect(recorder.getAnalytics('page-view')).toHaveLength(1);
-```
-
-`MockAnalyticsAdapter` is a genuine `IAnalyticsAdapter` implementation — it works the same way through the real `enableAnalytics` configuration pipeline as `ConsoleAnalyticsAdapter` or `FusionAnalyticsAdapter`, so registering it alongside other adapters doesn't change their behavior.
-
-## `getAnalytics(matcher?)`
-
-Returns recorded events synchronously, filtered by an event name, an array of names, or a predicate. Omit the matcher to get every recorded event.
-
-```ts
-recorder.getAnalytics(); // every recorded event
-recorder.getAnalytics('button-click'); // by name
-recorder.getAnalytics(['button-click', 'page-view']); // any of these names
-recorder.getAnalytics((event) => event.attributes?.section === 'header'); // predicate
-```
-
-## `waitForAnalytic(matcher, options?)`
-
-Resolves with the first matching event — immediately if one was already recorded, or waiting for a future one. Supports an optional `timeout` (ms) and `signal` (`AbortSignal`) so a test can't hang indefinitely, and rejects if the adapter is disposed before a match occurs.
-
-```ts
-// Rejects after 1000ms if the event never fires
-const event = await recorder.waitForAnalytic('button-click', { timeout: 1000 });
-
-// Rejects as soon as the signal aborts
-const controller = new AbortController();
-const pending = recorder.waitForAnalytic('button-click', { signal: controller.signal });
-controller.abort();
-
-await expect(pending).rejects.toThrow();
-```
-
-## Using a bespoke `ModulesConfigurator`
-
-`MockAnalyticsAdapter` works the same way with a manually composed set of modules — no app or portal host required:
-
-```ts
-import { ModulesConfigurator } from '@equinor/fusion-framework-module';
-import { enableAnalytics } from '@equinor/fusion-framework-module-analytics';
-import { MockAnalyticsAdapter } from '@equinor/fusion-framework-module-analytics/mock';
-import type { IAnalyticsProvider } from '@equinor/fusion-framework-module-analytics';
-
-const recorder = new MockAnalyticsAdapter();
-const configurator = new ModulesConfigurator([]);
-
-enableAnalytics(configurator, (builder) => {
-  builder.setAdapter('mock', async () => recorder);
-});
-
-// enableAnalytics only registers the module at runtime, so `initialize()` isn't
-// statically typed with an `analytics` property — cast to the real provider type.
-const instances = await configurator.initialize();
-const { analytics } = instances as unknown as { analytics: IAnalyticsProvider };
-analytics.trackAnalytic({ name: 'button-click', value: 'save' });
-
-expect(recorder.getAnalytics('button-click')).toHaveLength(1);
-```
-
-## Disposal
-
-`MockAnalyticsAdapter` completes its internal event stream on `[Symbol.dispose]()`, rejecting any pending `waitForAnalytic` calls instead of leaving them hanging:
-
-```ts
-const pending = recorder.waitForAnalytic('button-click');
-recorder[Symbol.dispose]();
-
-await expect(pending).rejects.toThrow('disposed before a matching event was recorded');
-```

package/docs/tracking-events.md

@@ -1,16 +0,0 @@
-# Tracking Events Manually
-
-The provider exposes methods for ad-hoc event tracking outside of collectors:
-
-```typescript
-// Single event
-provider.trackAnalytic({
-  name: 'button-click',
-  value: 'save',
-  attributes: { section: 'toolbar' },
-});
-
-// Observable stream
-const subscription = provider.trackAnalytic$(myEvent$);
-// later: subscription.unsubscribe();
-```

package/src/AnalyticsConfigurator.interface.ts

@@ -1,77 +0,0 @@
-import type { ConfigBuilderCallback } from '@equinor/fusion-framework-module';
-import type { IAnalyticsCollector } from './collectors/AnalyticsCollector.interface.js';
-import type { IAnalyticsAdapter } from './adapters/AnalyticsAdapter.interface.js';
-import type { AnalyticsEvent } from './types.js';
-
-/**
- * Resolved analytics configuration containing the instantiated collectors and adapters.
- *
- * @remarks
- * This type is the output of the configuration stage. The module’s `initialize`
- * function receives the resolved `AnalyticsConfig` and passes it to
- * {@link AnalyticsProvider}.
- */
-export type AnalyticsConfig = {
-  /** Record of analytics collectors keyed by a unique identifier. */
-  collectors: Record<string, IAnalyticsCollector>;
-  /** Record of analytics adapters keyed by a unique identifier. */
-  adapters: Record<string, IAnalyticsAdapter>;
-};
-
-/**
- * Configuration-time interface for registering analytics adapters and collectors.
- *
- * @remarks
- * Obtain an instance of this interface inside the callback passed to
- * {@link enableAnalytics}. Use {@link IAnalyticsConfigurator.setAdapter | setAdapter}
- * and {@link IAnalyticsConfigurator.setCollector | setCollector} to register
- * components. Both methods support method chaining.
- *
- * @example
- * ```ts
- * enableAnalytics(configurator, (builder) => {
- *   builder
- *     .setAdapter('console', async () => new ConsoleAnalyticsAdapter())
- *     .setCollector('context-selected', async (args) => {
- *       const ctx = await args.requireInstance('context');
- *       const app = await args.requireInstance('app');
- *       return new ContextSelectedCollector(ctx, app);
- *     });
- * });
- * ```
- */
-export interface IAnalyticsConfigurator {
-  /**
-   * Registers an analytics collector factory identified by a unique key.
-   *
-   * The factory callback receives module-resolution arguments so it can
-   * resolve dependencies (e.g. context or app providers) before returning
-   * the collector instance.
-   *
-   * @template T - The concrete analytics event type the collector emits.
-   * @param identifier - Unique key for this collector.
-   * @param callBack - Async factory that returns the collector instance.
-   * @returns The configurator instance for method chaining.
-   */
-  setCollector<T extends AnalyticsEvent>(
-    identifier: string,
-    callBack: ConfigBuilderCallback<IAnalyticsCollector<T>>,
-  ): this;
-
-  /**
-   * Registers an analytics adapter factory identified by a unique key.
-   *
-   * The factory callback receives module-resolution arguments so it can
-   * resolve dependencies (e.g. service-discovery HTTP clients) before
-   * returning the adapter instance.
-   *
-   * @template T - The concrete analytics event type the adapter handles.
-   * @param identifier - Unique key for this adapter.
-   * @param callback - Async factory that returns the adapter instance.
-   * @returns The configurator instance for method chaining.
-   */
-  setAdapter<T extends AnalyticsEvent>(
-    identifier: string,
-    callback: ConfigBuilderCallback<IAnalyticsAdapter<T>>,
-  ): this;
-}

package/src/AnalyticsConfigurator.ts

@@ -1,128 +0,0 @@
-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';
-
-/**
- * Default {@link IAnalyticsConfigurator} implementation for registering analytics adapters and collectors.
- *
- * @remarks
- * Extends `BaseConfigBuilder` to resolve adapter and collector factories
- * asynchronously at module-initialisation time using RxJS `mergeMap`. Each
- * registered factory is invoked with the module’s `ConfigBuilderCallbackArgs`
- * so it can resolve dependencies from the framework before returning its
- * adapter or collector instance.
- *
- * Use {@link AnalyticsConfigurator.setAdapter | setAdapter} and
- * {@link AnalyticsConfigurator.setCollector | setCollector} to register
- * components. Both methods return `this` for fluent chaining.
- *
- * @see {@link IAnalyticsConfigurator}
- * @see {@link BaseConfigBuilder}
- */
-export class AnalyticsConfigurator
-  extends BaseConfigBuilder<AnalyticsConfig>
-  implements IAnalyticsConfigurator
-{
-  #collectorCallbacks: Record<string, ConfigBuilderCallback<IAnalyticsCollector>> = {};
-  #adapterCallbacks: Record<string, ConfigBuilderCallback<IAnalyticsAdapter>> = {};
-
-  /**
-   * Registers the async resolvers for `collectors` and `adapters` config keys.
-   */
-  constructor() {
-    super();
-
-    // Configure async collectors resolution using mergeMap to handle Promise/Observable collector factories
-    this._set(
-      'collectors',
-      (args: ConfigBuilderCallbackArgs): ObservableInput<Record<string, IAnalyticsCollector>> => {
-        // Resolve each collector factory and drop any that resolve to a falsy value
-        return from(Object.entries(this.#collectorCallbacks)).pipe(
-          mergeMap(([identifier, collectorFn]) =>
-            // Resolve the collector's own Promise/Observable factory result
-            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>> => {
-        // Resolve each adapter factory and drop any that resolve to a falsy value
-        return from(Object.entries(this.#adapterCallbacks)).pipe(
-          mergeMap(([identifier, adapterFn]) =>
-            // Resolve the adapter's own Promise/Observable factory result
-            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 an analytics collector factory.
-   *
-   * @template T - The concrete analytics event type the collector emits.
-   * @param identifier - Unique key for the collector.
-   * @param callback - Factory that receives module-resolution args and returns a collector.
-   * @returns `this` for method chaining.
-   */
-  setCollector<T extends AnalyticsEvent>(
-    identifier: string,
-    callback: ConfigBuilderCallback<IAnalyticsCollector<T>>,
-  ): this {
-    this.#collectorCallbacks[identifier] = callback;
-    return this;
-  }
-
-  /**
-   * Registers an analytics adapter factory.
-   *
-   * @template T - The concrete analytics event type the adapter handles.
-   * @param identifier - Unique key for the adapter.
-   * @param callback - Factory that receives module-resolution args and returns an adapter.
-   * @returns `this` 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

@@ -1,44 +0,0 @@
-import type { ObservableInput, Subscription } from 'rxjs';
-import type { AnalyticsEvent } from './types.js';
-
-/**
- * Public interface for the analytics provider exposed by the `analytics` module.
- *
- * @remarks
- * Use `trackAnalytic` to push a single event or `trackAnalytic$` to forward
- * an observable stream of events. Both methods route events to all registered
- * adapters.
- */
-export interface IAnalyticsProvider {
-  /**
-   * Pushes a single analytics event to all registered adapters.
-   *
-   * @param event - The analytics event to track.
-   *
-   * @example
-   * ```ts
-   * provider.trackAnalytic({
-   *   name: 'button-click',
-   *   value: 'save',
-   *   attributes: { page: 'settings' },
-   * });
-   * ```
-   */
-  trackAnalytic(event: AnalyticsEvent): void;
-
-  /**
-   * Subscribes to an observable stream of analytics events and forwards each
-   * emission to all registered adapters.
-   *
-   * @param analytic$ - Observable input stream of analytics events.
-   * @returns A combined `Disposable & Subscription` handle for cleanup.
-   *
-   * @example
-   * ```ts
-   * const sub = provider.trackAnalytic$(myEvent$);
-   * // later
-   * sub.unsubscribe();
-   * ```
-   */
-  trackAnalytic$(analytic$: ObservableInput<AnalyticsEvent>): Disposable & Subscription;
-}

package/src/AnalyticsProvider.ts

@@ -1,150 +0,0 @@
-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';
-
-/**
- * An RxJS `Subscription` that also implements the TC39 `Disposable` protocol.
- *
- * @remarks
- * Returned by {@link AnalyticsProvider.trackAnalytic$} so callers can clean up
- * with either `subscription.unsubscribe()` or `using` / `Symbol.dispose`.
- */
-class DisposableSubscription extends Subscription {
-  /**
-   * @param subscription - The underlying subscription to wrap with `Symbol.dispose` support.
-   */
-  constructor(subscription: Subscription) {
-    super(subscription.unsubscribe);
-  }
-
-  /** TC39 `Disposable` protocol support, delegating to `unsubscribe()`. */
-  [Symbol.dispose] = () => {
-    this.unsubscribe();
-  };
-}
-
-/**
- * Runtime analytics provider that collects events from collectors and dispatches
- * them to adapters.
- *
- * @remarks
- * Created by the analytics module during initialisation. The provider:
- *
- * 1. Initialises all registered adapters and collectors.
- * 2. Subscribes to every collector and merges their events into a shared stream.
- * 3. Forwards each emitted event to every registered adapter via
- *    {@link IAnalyticsAdapter.registerAnalytic}.
- *
- * Consumers can also push ad-hoc events with {@link AnalyticsProvider.trackAnalytic}
- * or subscribe an observable stream with {@link AnalyticsProvider.trackAnalytic$}.
- *
- * @extends BaseModuleProvider<AnalyticsConfig>
- * @implements IAnalyticsProvider
- */
-export class AnalyticsProvider
-  extends BaseModuleProvider<AnalyticsConfig>
-  implements IAnalyticsProvider
-{
-  #analytics: Subject<AnalyticsEvent>;
-  #collectors: Record<string, IAnalyticsCollector>;
-  #adapters: Record<string, IAnalyticsAdapter>;
-
-  /**
-   * @param config - Resolved analytics module configuration, including collectors and adapters.
-   */
-  constructor(config: AnalyticsConfig) {
-    super({ version, config });
-
-    this.#analytics = new Subject();
-    this.#collectors = config.collectors;
-    this.#adapters = config.adapters;
-  }
-
-  /**
-   * Initialises all adapters and collectors, then wires collector output into
-   * the adapter pipeline.
-   *
-   * @remarks
-   * Initialisation is idempotent within the module lifecycle — the module calls
-   * this once during `module.initialize`. Steps:
-   *
-   * 1. Initialise all collectors (via `Promise.allSettled`).
-   * 2. Initialise all adapters (via `Promise.allSettled`).
-   * 3. Subscribe to each collector and forward events into the shared subject.
-   * 4. Subscribe to the shared subject and dispatch to every adapter.
-   *
-   * All subscriptions are registered as teardowns on the base provider.
-   *
-   * @returns A promise that resolves when all adapters and collectors are initialised.
-   */
-  async initialize(): Promise<void> {
-    // Kick off initialization for every collector, tolerating individual failures
-    const initializedCollectors = Object.values(this.#collectors).map((collector) =>
-      Promise.resolve(collector.initialize?.()),
-    );
-    // Kick off initialization for every adapter, tolerating individual failures
-    const initializedAdapters = Object.values(this.#adapters).map((adapters) =>
-      Promise.resolve(adapters.initialize?.()),
-    );
-
-    await Promise.allSettled(initializedCollectors);
-    await Promise.allSettled(initializedAdapters);
-
-    // Forward every collector's emissions into the shared analytics subject
-    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) => {
-        // Dispatch every emitted event to all registered adapters
-        for (const adapter of Object.values(this.#adapters)) {
-          adapter.registerAnalytic(event);
-        }
-      },
-    });
-    this._addTeardown(adapterSubscription);
-  }
-
-  /**
-   * Pushes a single analytics event to all registered adapters.
-   *
-   * @param event - The analytics event to track.
-   */
-  trackAnalytic(event: AnalyticsEvent): void {
-    // TODO(#5098): Validate AnalyticsEvent includes name, value and attributes
-    this.#analytics.next(event);
-  }
-
-  /**
-   * Subscribes to an observable stream of analytics events and forwards each
-   * emission to all registered adapters.
-   *
-   * @param analytic$ - Observable input stream of analytics events.
-   * @returns A {@link DisposableSubscription} supporting both `unsubscribe()` and `Symbol.dispose`.
-   */
-  trackAnalytic$(analytic$: ObservableInput<AnalyticsEvent>): Disposable & Subscription {
-    const subscription = from(analytic$)
-      // TODO(#5098): Validate AnalyticsEvent includes name, value and attributes
-      .subscribe({
-        next: (event) => {
-          this.#analytics.next(event);
-        },
-      });
-
-    return new DisposableSubscription(subscription);
-  }
-}

package/src/__tests__/MockAnalyticsAdapter.test.ts

@@ -1,127 +0,0 @@
-import { describe, it, expect, vi, afterEach } from 'vitest';
-
-import { MockAnalyticsAdapter } from '../mock/MockAnalyticsAdapter.js';
-import type { AnalyticsEvent } from '../types.js';
-
-const createEvent = (name: string, overrides: Partial<AnalyticsEvent> = {}): AnalyticsEvent => ({
-  name,
-  value: null,
-  ...overrides,
-});
-
-describe('MockAnalyticsAdapter', () => {
-  afterEach(() => {
-    vi.useRealTimers();
-  });
-
-  it('records events via registerAnalytic and returns them from getAnalytics', () => {
-    const adapter = new MockAnalyticsAdapter();
-
-    adapter.registerAnalytic(createEvent('button-click'));
-    adapter.registerAnalytic(createEvent('page-view'));
-
-    expect(adapter.getAnalytics().map((e) => e.name)).toEqual(['button-click', 'page-view']);
-  });
-
-  it('filters getAnalytics by a single name, an array, and a predicate', () => {
-    const adapter = new MockAnalyticsAdapter();
-    adapter.registerAnalytic(createEvent('button-click', { attributes: { section: 'header' } }));
-    adapter.registerAnalytic(createEvent('page-view'));
-
-    expect(adapter.getAnalytics('button-click')).toHaveLength(1);
-    expect(adapter.getAnalytics(['button-click', 'page-view'])).toHaveLength(2);
-    expect(adapter.getAnalytics((e) => e.attributes?.section === 'header')).toHaveLength(1);
-  });
-
-  it('resolves waitForAnalytic immediately when a matching event is already recorded', async () => {
-    const adapter = new MockAnalyticsAdapter();
-    adapter.registerAnalytic(createEvent('button-click'));
-
-    const event = await adapter.waitForAnalytic('button-click');
-
-    expect(event.name).toBe('button-click');
-  });
-
-  it('resolves waitForAnalytic when a matching event is recorded later', async () => {
-    const adapter = new MockAnalyticsAdapter();
-
-    const promise = adapter.waitForAnalytic('button-click');
-    adapter.registerAnalytic(createEvent('page-view'));
-    adapter.registerAnalytic(createEvent('button-click'));
-    const event = await promise;
-
-    expect(event.name).toBe('button-click');
-  });
-
-  it('resolves waitForAnalytic via predicate matcher', async () => {
-    const adapter = new MockAnalyticsAdapter();
-
-    const promise = adapter.waitForAnalytic((e) => e.attributes?.id === 42);
-    adapter.registerAnalytic(createEvent('button-click', { attributes: { id: 1 } }));
-    adapter.registerAnalytic(createEvent('button-click', { attributes: { id: 42 } }));
-    const event = await promise;
-
-    expect(event.attributes?.id).toBe(42);
-  });
-
-  it('rejects when the timeout elapses before a matching event is recorded', async () => {
-    vi.useFakeTimers();
-    const adapter = new MockAnalyticsAdapter();
-
-    const promise = adapter.waitForAnalytic('button-click', { timeout: 500 });
-    vi.advanceTimersByTime(501);
-
-    await expect(promise).rejects.toThrow('waitForAnalytic timed out after 500ms');
-  });
-
-  it('rejects when the AbortSignal fires before a matching event', async () => {
-    const adapter = new MockAnalyticsAdapter();
-    const controller = new AbortController();
-
-    const promise = adapter.waitForAnalytic('button-click', { signal: controller.signal });
-    controller.abort();
-
-    await expect(promise).rejects.toThrow();
-  });
-
-  it('rejects immediately when passed an already-aborted signal', async () => {
-    const adapter = new MockAnalyticsAdapter();
-    const controller = new AbortController();
-    controller.abort();
-
-    await expect(
-      adapter.waitForAnalytic('button-click', { signal: controller.signal }),
-    ).rejects.toThrow();
-  });
-
-  it('rejects pending waitForAnalytic calls when the adapter is disposed', async () => {
-    const adapter = new MockAnalyticsAdapter();
-
-    const promise = adapter.waitForAnalytic('button-click');
-    adapter[Symbol.dispose]();
-
-    await expect(promise).rejects.toThrow('disposed before a matching event was recorded');
-  });
-
-  it('rejects instead of hanging when a predicate matcher throws on a future event', async () => {
-    const adapter = new MockAnalyticsAdapter();
-    const boom = new Error('predicate boom');
-
-    const promise = adapter.waitForAnalytic(() => {
-      throw boom;
-    });
-    adapter.registerAnalytic(createEvent('button-click'));
-
-    await expect(promise).rejects.toThrow(boom);
-  });
-
-  it('does not interfere with events recorded by another adapter instance', () => {
-    const adapterA = new MockAnalyticsAdapter();
-    const adapterB = new MockAnalyticsAdapter();
-
-    adapterA.registerAnalytic(createEvent('button-click'));
-
-    expect(adapterA.getAnalytics()).toHaveLength(1);
-    expect(adapterB.getAnalytics()).toHaveLength(0);
-  });
-});