@equinor/fusion-framework-module-analytics 3.0.6 → 3.0.8-next.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @equinor/fusion-framework-module-analytics
 
+## 3.0.8-next.0
+
+### Patch Changes
+
+- c8008e3: Internal: rebase `next` onto `main`, syncing in already-published stable releases so they carry a `next` pre-release tag.
+- Updated dependencies [c8008e3]
+  - @equinor/fusion-framework-module-app@8.0.6-next.0
+  - @equinor/fusion-framework-module-context@9.0.0-next.0
+
+## 3.0.7
+
+### Patch Changes
+
+- Updated dependencies [4a00a7a]
+  - @equinor/fusion-framework-module-app@8.0.5
+
 ## 3.0.6
 
 ### Patch Changes

package/README.md

@@ -3,6 +3,15 @@
 Fusion Framework module for collecting and exporting application analytics using
 OpenTelemetry standards.
 
+## Who should use this
+
+- **Application and portal developers** who want to track user interactions
+  (clicks, context changes, app usage) without wiring up telemetry by hand.
+- **Module authors** who want their module's lifecycle events picked up by
+  analytics automatically via a collector.
+- **Test authors** who need to assert which analytics events an app or
+  collector produced.
+
 ## Overview
 
 The analytics module provides a pluggable **adapter/collector** architecture:
@@ -22,6 +31,16 @@ When a collector emits an event it is delivered to **every** registered adapter.
 | `@equinor/fusion-framework-module-analytics/adapters` | `ConsoleAnalyticsAdapter`, `FusionAnalyticsAdapter`, `IAnalyticsAdapter` |
 | `@equinor/fusion-framework-module-analytics/collectors` | `ContextSelectedCollector`, `AppSelectedCollector`, `AppLoadedCollector`, `IAnalyticsCollector` |
 | `@equinor/fusion-framework-module-analytics/logExporters` | `OTLPLogExporter`, `FusionOTLPLogExporter` |
+| `@equinor/fusion-framework-module-analytics/mock` | `MockAnalyticsAdapter` — record tracked events for test assertions |
+
+## Documentation
+
+| Topic | Description |
+|---|---|
+| [Adapters](docs/adapters.md) | `ConsoleAnalyticsAdapter`, `FusionAnalyticsAdapter`, and creating a custom `IAnalyticsAdapter` |
+| [Collectors](docs/collectors.md) | Built-in collectors (context/app selection, app loaded) and creating a custom `IAnalyticsCollector` |
+| [Tracking Events Manually](docs/tracking-events.md) | `provider.trackAnalytic` / `trackAnalytic$` for ad-hoc event tracking |
+| [Testing](docs/testing.md) | `MockAnalyticsAdapter`, recording and awaiting tracked events, and using a bespoke `ModulesConfigurator` in tests |
 
 ## Quick Start
 
@@ -52,217 +71,6 @@ const configure = (configurator) => {
 > Fusion Framework module system. Manual initialisation is only required when
 > accessing the provider directly.
 
-## Adapters
-
-Adapters implement `IAnalyticsAdapter` and are responsible for processing and
-sending analytics data to their destinations. All adapters support async
-initialisation and will be initialised automatically when the provider starts.
-
-### ConsoleAnalyticsAdapter
-
-Logs every analytics event to the browser console. Useful for development and
-debugging. No configuration required.
-
-```typescript
-builder.setAdapter('console', async () => new ConsoleAnalyticsAdapter());
-```
-
-### FusionAnalyticsAdapter
-
-Forwards analytics events to an OpenTelemetry-compatible log endpoint via a
-bundled `LoggerProvider`.
-
-Configuration options:
-
-| Option | Type | Description |
-|---|---|---|
-| `portalId` | `string` | Portal identifier included in every log record |
-| `logExporter` | `OTLPExporterBase` | OTLP log exporter for transport |
-
-#### Using `OTLPLogExporter` (direct HTTP)
-
-```typescript
-import { OTLPLogExporter } from '@equinor/fusion-framework-module-analytics/logExporters';
-import { FusionAnalyticsAdapter } from '@equinor/fusion-framework-module-analytics/adapters';
-
-builder.setAdapter('fusion-log', async () => {
-  const logExporter = new OTLPLogExporter({
-    url: 'https://example.com/v1/logs',
-    headers: { 'Content-Type': 'application/json' },
-  });
-  return new FusionAnalyticsAdapter({ portalId: 'my-portal', logExporter });
-});
-```
-
-#### Using `FusionOTLPLogExporter` (service discovery HTTP client)
-
-```typescript
-import { FusionOTLPLogExporter } from '@equinor/fusion-framework-module-analytics/logExporters';
-import { FusionAnalyticsAdapter } from '@equinor/fusion-framework-module-analytics/adapters';
-
-builder.setAdapter('fusion', async (args) => {
-  if (args.hasModule('serviceDiscovery')) {
-    const sd = await args.requireInstance('serviceDiscovery');
-    const httpClient = await sd.createClient('analytics');
-    const logExporter = new FusionOTLPLogExporter(httpClient);
-    return new FusionAnalyticsAdapter({ portalId: 'my-portal', logExporter });
-  }
-  console.error('Service discovery unavailable — analytics adapter not created');
-});
-```
-
-### Creating a Custom Adapter
-
-Implement `IAnalyticsAdapter` and register it with `setAdapter`:
-
-```typescript
-import type { IAnalyticsAdapter } from '@equinor/fusion-framework-module-analytics/adapters';
-import type { AnalyticsEvent } from '@equinor/fusion-framework-module-analytics';
-
-class MyRemoteAdapter implements IAnalyticsAdapter {
-  registerAnalytic(event: AnalyticsEvent): void {
-    navigator.sendBeacon('/analytics', JSON.stringify(event));
-  }
-
-  [Symbol.dispose](): void {
-    // cleanup if needed
-  }
-}
-
-builder.setAdapter('remote', async () => new MyRemoteAdapter());
-```
-
-## Collectors
-
-Collectors implement `IAnalyticsCollector` (or extend `BaseCollector`) and emit
-`AnalyticsEvent` objects that are forwarded to all adapters. All collectors
-support async initialisation.
-
-### ContextSelectedCollector
-
-Emits an event when the active Fusion context changes. Includes the new context,
-the previous context, and the current app key in attributes.
-
-```typescript
-builder.setCollector('context-selected', async (args) => {
-  const ctx = await args.requireInstance('context');
-  const app = await args.requireInstance('app');
-  return new ContextSelectedCollector(ctx, app);
-});
-```
-
-### AppSelectedCollector
-
-Emits an event when the active application changes. Includes the new and
-previous app key metadata.
-
-```typescript
-builder.setCollector('app-selected', async (args) => {
-  const app = await args.requireInstance('app');
-  return new AppSelectedCollector(app);
-});
-```
-
-### AppLoadedCollector
-
-Emits an event when an application's modules finish loading. Includes app
-manifest metadata and the current context (if available).
-
-```typescript
-builder.setCollector('app-loaded', async (args) => {
-  const event = await args.requireInstance('event');
-  const app = await args.requireInstance('app');
-  return new AppLoadedCollector(event, app);
-});
-```
-
-### Creating a Custom Collector
-
-Extend `BaseCollector` with a Zod schema for validation:
-
-```typescript
-import { BaseCollector, createSchema } from '@equinor/fusion-framework-module-analytics/collectors';
-import { z } from 'zod';
-import { of } from 'rxjs';
-
-const schema = createSchema(z.string(), z.object({ page: z.string() }));
-
-class PageViewCollector extends BaseCollector<string, { page: string }> {
-  constructor() {
-    super('page-view', schema);
-  }
-
-  _initialize() {
-    return of({ value: window.location.pathname, attributes: { page: document.title } });
-  }
-}
-```
-
-## 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();
-```
-
-#### Configuration
-
-The Context Selected Collector needs the context provider.
-
-##### Example configuration
-
-```typescript
-import { enableAnalytics } from '@equinor/fusion-framework-module-analytics';
-import { ContextSelectedCollector } from '@equinor/fusion-framework-module-analytics/collectors';
-
-const configure = (configurator: IModulesConfigurator<any, any>) => {
-  enableAnalytics(configurator, (builder) => {
-    builder.setCollector('context-selected', async (args) => {
-      const contextProvider = await args.requireInstance('context');
-      const appProvider = await args.requireInstance('app');
-      return new ContextSelectedCollector(contextProvider, appProvider);
-    });
-  });
-}
-```
-
-### Creating Custom Collectors
-
-You can create custom analytics collector by extending the `BaseCollector` class,
-or implement the `IAnalyticsCollector` interface and add it in configuration.
-
-#### Example Custom Collector
-
-```typescript
-import { type AnalyticsEvent, enableAnalytics } from '@equinor/fusion-framework-module-analytics';
-
-const configure = (configurator: IModulesConfigurator<any, any>) => {
-  enableAnalytics(configurator, (builder) => {
-    builder.setCollector('click-test', async () => {
-      const subject = new Subject<AnalyticsEvent>();
-      window.addEventListener('click', (e) => {
-        subject.next({
-          name: 'window-clicker',
-          value: 42,
-        });
-      });
-
-      return {
-        subscribe: (subscriber) => {
-          return subject.subscribe(subscriber);
-        },
-      };
-    });
-  });
-}
-```
+See [Adapters](docs/adapters.md), [Collectors](docs/collectors.md), and
+[Tracking Events Manually](docs/tracking-events.md) for the full adapter/collector
+reference and how to build your own.

package/dist/esm/__tests__/MockAnalyticsAdapter.test.js

@@ -0,0 +1,91 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { MockAnalyticsAdapter } from '../mock/MockAnalyticsAdapter.js';
+const createEvent = (name, overrides = {}) => ({
+    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);
+    });
+});
+//# sourceMappingURL=MockAnalyticsAdapter.test.js.map

package/dist/esm/__tests__/MockAnalyticsAdapter.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MockAnalyticsAdapter.test.js","sourceRoot":"","sources":["../../../src/__tests__/MockAnalyticsAdapter.test.ts"],"names":[],"mappings":"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"}

package/dist/esm/__tests__/mock/analytics-mock-adapter.test.js

@@ -0,0 +1,60 @@
+import { describe, expect, it, vi } from 'vitest';
+import { ModulesConfigurator } from '@equinor/fusion-framework-module';
+import { Subject } from 'rxjs';
+import { enableAnalytics } from '../../enable-analytics.js';
+import { ConsoleAnalyticsAdapter } from '../../adapters/ConsoleAnalyticsAdapter.js';
+import { MockAnalyticsAdapter } from '../../mock/MockAnalyticsAdapter.js';
+/**
+ * Initializes the analytics module through the real module system, with a
+ * `MockAnalyticsAdapter` registered alongside whatever the test configures.
+ *
+ * @remarks
+ * Deliberately avoids hand-building an `AnalyticsProvider`. Testing the
+ * adapter's own logic in isolation (see `MockAnalyticsAdapter.test.ts`) can't
+ * prove it actually receives events through the real configure -> initialize
+ * -> collector/adapter dispatch pipeline every other adapter goes through.
+ *
+ * @param configure - Optional callback to register additional adapters/collectors.
+ * @returns The real `IAnalyticsProvider` instance and the recording adapter.
+ */
+const initializeWith = async (configure) => {
+    const recorder = new MockAnalyticsAdapter();
+    const configurator = new ModulesConfigurator([]);
+    enableAnalytics(configurator, (builder) => {
+        builder.setAdapter('mock', async () => recorder);
+        configure?.(builder);
+    });
+    const instances = await configurator.initialize();
+    const provider = instances.analytics;
+    return { provider, recorder };
+};
+describe('MockAnalyticsAdapter (through the real analytics module)', () => {
+    it('observes events pushed via provider.trackAnalytic', async () => {
+        const { provider, recorder } = await initializeWith();
+        provider.trackAnalytic({ name: 'button-click', value: 'save' });
+        expect(recorder.getAnalytics('button-click')).toHaveLength(1);
+    });
+    it('observes events emitted by a real registered collector', async () => {
+        const clicks$ = new Subject();
+        const { recorder } = await initializeWith((builder) => {
+            builder.setCollector('clicks', async () => clicks$);
+        });
+        clicks$.next({ name: 'window-click', value: 42 });
+        const event = await recorder.waitForAnalytic('window-click');
+        expect(event.value).toBe(42);
+    });
+    it('does not interfere with other adapters registered alongside it', async () => {
+        const logSpy = vi.spyOn(console, 'log').mockImplementation(() => undefined);
+        const { provider, recorder } = await initializeWith((builder) => {
+            builder.setAdapter('console', async () => new ConsoleAnalyticsAdapter());
+        });
+        provider.trackAnalytic({ name: 'page-view', value: null });
+        expect(recorder.getAnalytics('page-view')).toHaveLength(1);
+        expect(logSpy).toHaveBeenCalledWith('Analytics::Adapter::Console', {
+            name: 'page-view',
+            value: null,
+        });
+        logSpy.mockRestore();
+    });
+});
+//# sourceMappingURL=analytics-mock-adapter.test.js.map

package/dist/esm/__tests__/mock/analytics-mock-adapter.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics-mock-adapter.test.js","sourceRoot":"","sources":["../../../../src/__tests__/mock/analytics-mock-adapter.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAClD,OAAO,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AACvE,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAE/B,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,uBAAuB,EAAE,MAAM,2CAA2C,CAAC;AACpF,OAAO,EAAE,oBAAoB,EAAE,MAAM,oCAAoC,CAAC;AAK1E;;;;;;;;;;;;GAYG;AACH,MAAM,cAAc,GAAG,KAAK,EAC1B,SAAqD,EACsB,EAAE;IAC7E,MAAM,QAAQ,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC5C,MAAM,YAAY,GAAG,IAAI,mBAAmB,CAAC,EAAE,CAAC,CAAC;IAEjD,eAAe,CAAC,YAAY,EAAE,CAAC,OAAO,EAAE,EAAE;QACxC,OAAO,CAAC,UAAU,CAAC,MAAM,EAAE,KAAK,IAAI,EAAE,CAAC,QAAQ,CAAC,CAAC;QACjD,SAAS,EAAE,CAAC,OAAO,CAAC,CAAC;IACvB,CAAC,CAAC,CAAC;IAEH,MAAM,SAAS,GAAG,MAAM,YAAY,CAAC,UAAU,EAAE,CAAC;IAClD,MAAM,QAAQ,GAAI,SAA0D,CAAC,SAAS,CAAC;IAEvF,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC;AAChC,CAAC,CAAC;AAEF,QAAQ,CAAC,0DAA0D,EAAE,GAAG,EAAE;IACxE,EAAE,CAAC,mDAAmD,EAAE,KAAK,IAAI,EAAE;QACjE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,MAAM,cAAc,EAAE,CAAC;QAEtD,QAAQ,CAAC,aAAa,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC;QAEhE,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAC,cAAc,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IAChE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,wDAAwD,EAAE,KAAK,IAAI,EAAE;QACtE,MAAM,OAAO,GAAG,IAAI,OAAO,EAAkB,CAAC;QAC9C,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,cAAc,CAAC,CAAC,OAAO,EAAE,EAAE;YACpD,OAAO,CAAC,YAAY,CAAC,QAAQ,EAAE,KAAK,IAAI,EAAE,CAAC,OAAO,CAAC,CAAC;QACtD,CAAC,CAAC,CAAC;QAEH,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC;QAElD,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,eAAe,CAAC,cAAc,CAAC,CAAC;QAC7D,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC/B,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,gEAAgE,EAAE,KAAK,IAAI,EAAE;QAC9E,MAAM,MAAM,GAAG,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,kBAAkB,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAC5E,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,MAAM,cAAc,CAAC,CAAC,OAAO,EAAE,EAAE;YAC9D,OAAO,CAAC,UAAU,CAAC,SAAS,EAAE,KAAK,IAAI,EAAE,CAAC,IAAI,uBAAuB,EAAE,CAAC,CAAC;QAC3E,CAAC,CAAC,CAAC;QAEH,QAAQ,CAAC,aAAa,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAE3D,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;QAC3D,MAAM,CAAC,MAAM,CAAC,CAAC,oBAAoB,CAAC,6BAA6B,EAAE;YACjE,IAAI,EAAE,WAAW;YACjB,KAAK,EAAE,IAAI;SACZ,CAAC,CAAC;QAEH,MAAM,CAAC,WAAW,EAAE,CAAC;IACvB,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/esm/mock/MockAnalyticsAdapter.js

@@ -0,0 +1,134 @@
+import { Subject, filter } from 'rxjs';
+/**
+ * An {@link IAnalyticsAdapter} that records every tracked event in-memory instead
+ * of exporting it to a backend, for asserting on analytics in tests.
+ *
+ * @remarks
+ * Register it like any other adapter via {@link IAnalyticsConfigurator.setAdapter};
+ * it does not interfere with other adapters registered alongside it.
+ *
+ * @template T - Analytics event type, defaults to {@link AnalyticsEvent}.
+ *
+ * @example
+ * ```ts
+ * import { MockAnalyticsAdapter } from '@equinor/fusion-framework-module-analytics/mock';
+ *
+ * const recorder = new MockAnalyticsAdapter();
+ * enableAnalytics(configurator, (builder) => {
+ *   builder.setAdapter('mock', async () => recorder);
+ * });
+ *
+ * // ...later, in a test
+ * const event = await recorder.waitForAnalytic('button-click');
+ * expect(event.attributes?.section).toBe('header');
+ * ```
+ */
+export class MockAnalyticsAdapter {
+    #events = [];
+    #events$ = new Subject();
+    /**
+     * Records the event so it is visible to {@link getAnalytics} and any pending
+     * {@link waitForAnalytic} calls.
+     *
+     * @param event - The analytics event to record.
+     */
+    registerAnalytic(event) {
+        this.#events.push(event);
+        this.#events$.next(event);
+    }
+    /**
+     * Returns recorded events matching `matcher`, in dispatch order.
+     *
+     * @param matcher - Event name, array of names, or a predicate. Omit to get every recorded event.
+     * @returns Matching recorded events.
+     */
+    getAnalytics(matcher) {
+        // No matcher: return every event recorded so far.
+        if (matcher === undefined)
+            return [...this.#events];
+        // Narrow down to events accepted by the matcher.
+        return this.#events.filter((event) => this.#matches(event, matcher));
+    }
+    /**
+     * Waits for the next event matching `matcher`, resolving immediately if a
+     * matching event was already recorded.
+     *
+     * @param matcher - Event name, array of names, or a predicate.
+     * @param options - Optional timeout (ms) or AbortSignal.
+     * @returns A promise that resolves with the first matching event.
+     */
+    waitForAnalytic(matcher, options) {
+        // Already recorded: resolve immediately rather than only watching future events.
+        const recorded = this.#events.find((event) => this.#matches(event, matcher));
+        // Already recorded: resolve immediately rather than only watching future events.
+        if (recorded)
+            return Promise.resolve(recorded);
+        return new Promise((resolve, reject) => {
+            const { timeout: ms, signal } = options ?? {};
+            // Fail fast without subscribing when the caller already aborted.
+            if (signal?.aborted) {
+                reject(signal.reason ?? new DOMException('Aborted', 'AbortError'));
+                return;
+            }
+            let timer;
+            // Declared before subscribing so `complete` can reach it even when the
+            // adapter is already disposed and fires synchronously during `subscribe`.
+            let sub;
+            const cleanup = () => {
+                clearTimeout(timer);
+                sub?.unsubscribe();
+            };
+            // Only forward events accepted by the matcher to the subscriber below.
+            sub = this.#events$.pipe(filter((event) => this.#matches(event, matcher))).subscribe({
+                next: (event) => {
+                    cleanup();
+                    resolve(event);
+                },
+                // A throwing predicate matcher surfaces here instead of hanging the promise forever.
+                error: (err) => {
+                    cleanup();
+                    reject(err);
+                },
+                complete: () => {
+                    cleanup();
+                    reject(new Error('MockAnalyticsAdapter disposed before a matching event was recorded'));
+                },
+            });
+            // Only arm a timeout when the caller opted in.
+            if (ms !== undefined) {
+                timer = setTimeout(() => {
+                    cleanup();
+                    reject(new Error(`waitForAnalytic timed out after ${ms}ms`));
+                }, ms);
+            }
+            // Only wire abort handling when the caller passed a signal.
+            if (signal) {
+                signal.addEventListener('abort', () => {
+                    cleanup();
+                    reject(signal.reason ?? new DOMException('Aborted', 'AbortError'));
+                }, { once: true });
+            }
+        });
+    }
+    /**
+     * Tests whether `event` satisfies `matcher`.
+     *
+     * @param event - Event to test.
+     * @param matcher - Event name, array of names, or a predicate.
+     * @returns Whether `event` matches.
+     */
+    #matches(event, matcher) {
+        // String matcher: compare event name directly.
+        if (typeof matcher === 'string')
+            return event.name === matcher;
+        // Array matcher: match against any of the given names.
+        if (Array.isArray(matcher))
+            return matcher.includes(event.name);
+        return matcher(event);
+    }
+    /** Completes the internal event stream, rejecting any pending `waitForAnalytic` calls. */
+    [Symbol.dispose]() {
+        this.#events$.complete();
+    }
+}
+//# sourceMappingURL=MockAnalyticsAdapter.js.map

package/dist/esm/mock/MockAnalyticsAdapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MockAnalyticsAdapter.js","sourceRoot":"","sources":["../../../src/mock/MockAnalyticsAdapter.ts"],"names":[],"mappings":"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"}

package/dist/esm/mock/index.js

@@ -0,0 +1,26 @@
+/**
+ * Mock analytics adapter for tests: records tracked events in-memory instead
+ * of exporting them to a backend.
+ *
+ * @remarks
+ * Register it like any other {@link IAnalyticsAdapter} via
+ * {@link IAnalyticsConfigurator.setAdapter} — it observes tracked events
+ * alongside real adapters without affecting their delivery.
+ *
+ * @example
+ * ```ts
+ * import { MockAnalyticsAdapter } from '@equinor/fusion-framework-module-analytics/mock';
+ *
+ * const recorder = new MockAnalyticsAdapter();
+ * enableAnalytics(configurator, (builder) => {
+ *   builder.setAdapter('mock', async () => recorder);
+ * });
+ *
+ * const event = await recorder.waitForAnalytic('button-click');
+ * expect(event.attributes?.section).toBe('header');
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { MockAnalyticsAdapter, } from './MockAnalyticsAdapter.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/mock/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/mock/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,EACL,oBAAoB,GAGrB,MAAM,2BAA2B,CAAC"}

package/dist/esm/version.js

@@ -1,3 +1,3 @@
 // Generated by genversion.
-export const version = '3.0.6';
+export const version = '3.0.8-next.0';
 //# sourceMappingURL=version.js.map

package/dist/esm/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":"AAAA,2BAA2B;AAC3B,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC"}
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":"AAAA,2BAA2B;AAC3B,MAAM,CAAC,MAAM,OAAO,GAAG,cAAc,CAAC"}