@equinor/fusion-framework-module-analytics 1.0.2 → 2.0.0

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # @equinor/fusion-framework-module-analytics
 
+## 2.0.0
+
+### Major Changes
+
+- abffa53: Major version bump for Fusion Framework React 19 release.
+
+  All packages are bumped to the next major version as part of the React 19 upgrade. This release drops support for React versions below 18 and includes breaking changes across the framework.
+
+  **Breaking changes:**
+  - Peer dependencies now require React 18 or 19 (`^18.0.0 || ^19.0.0`)
+  - React Router upgraded from v6 to v7
+  - Navigation module refactored with new history API
+  - `renderComponent` and `renderApp` now use `createRoot` API
+
+  **Migration:**
+  - Update your React version to 18.0.0 or higher before upgrading
+  - Replace `NavigationProvider.createRouter()` with `@equinor/fusion-framework-react-router`
+  - See individual package changelogs for package-specific migration steps
+
+### Patch Changes
+
+- Updated dependencies [abffa53]
+- Updated dependencies [abffa53]
+- Updated dependencies [abffa53]
+- Updated dependencies [abffa53]
+- Updated dependencies [abffa53]
+- Updated dependencies [abffa53]
+  - @equinor/fusion-framework-module@6.0.0
+  - @equinor/fusion-framework-module-app@8.0.0
+  - @equinor/fusion-framework-module-context@8.0.0
+  - @equinor/fusion-framework-module-event@6.0.0
+  - @equinor/fusion-framework-module-http@8.0.0
+  - @equinor/fusion-observable@9.0.0
+
 ## 1.0.2
 
 ### Patch Changes

package/README.md

@@ -1,202 +1,219 @@
-# Analytics Module
+# @equinor/fusion-framework-module-analytics
 
-The Fusion Framework Analytics Module provides an unified way to track analytics.
-It offers a consistent API for logging analytics data while supporting multiple
-adapters and collectors.
+Fusion Framework module for collecting and exporting application analytics using
+OpenTelemetry standards.
 
-When a collector emits a event, it will be sent to all adapters.
+## Overview
 
-## Configuration
+The analytics module provides a pluggable **adapter/collector** architecture:
 
-To configure the analytics module, you need to provide a function that specifies
-the adapters and collectors you want to use. The configuration can be done in
-your portal entry file or wherever you initialize the Fusion Framework.
+- **Collectors** observe application state (context changes, app selection,
+  app loads) and emit structured `AnalyticsEvent` objects.
+- **Adapters** receive those events and forward them to a backend — the browser
+  console for debugging, or an OTLP-compatible endpoint for production.
+
+When a collector emits an event it is delivered to **every** registered adapter.
+
+### Entry points
+
+| Import path | Contents |
+|---|---|
+| `@equinor/fusion-framework-module-analytics` | Module definition, `enableAnalytics`, core types |
+| `@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` |
+
+## Quick Start
+
+Call `enableAnalytics` inside your application or portal configuration callback
+to register adapters and collectors:
 
 ```typescript
 import { enableAnalytics } from '@equinor/fusion-framework-module-analytics';
+import { ConsoleAnalyticsAdapter } from '@equinor/fusion-framework-module-analytics/adapters';
+import { ContextSelectedCollector } from '@equinor/fusion-framework-module-analytics/collectors';
 
-const configure = (configurator: IModulesConfigurator<any, any>) => {
+const configure = (configurator) => {
   enableAnalytics(configurator, (builder) => {
-    // configure the analytics module
-
-    builder.setAdapter('console', async () => {
-      return new ConsoleAnalyticsAdapter();
-    });
+    // Register an adapter — receives every event
+    builder.setAdapter('console', async () => new ConsoleAnalyticsAdapter());
 
+    // Register a collector — emits events on context change
     builder.setCollector('context-selected', async (args) => {
       const contextProvider = await args.requireInstance('context');
       const appProvider = await args.requireInstance('app');
       return new ContextSelectedCollector(contextProvider, appProvider);
     });
   });
-}
+};
 ```
 
-## Initialization
+> **Note:** The analytics module initialises automatically when used inside the
+> Fusion Framework module system. Manual initialisation is only required when
+> accessing the provider directly.
 
-The analytics module supports asynchronous initialization of adapters and
-collectors. The provider exposes an `initialize()` method that should be called
-to set up all configured adapters and collectors:
+## Adapters
 
-```typescript
-// Get the analytics provider from modules
-const provider = modules.analytics;
+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.
 
-// Initialize adapters and collectors (required before use)
-await provider.initialize();
+### ConsoleAnalyticsAdapter
 
-// Check if provider is initialized
-if (provider.initialized) {
-  // Provider is ready for use
-}
-```
+Logs every analytics event to the browser console. Useful for development and
+debugging. No configuration required.
 
-> [!NOTE]
-> The analytics module will automatically initialize when used within the
-> Fusion Framework module system. Manual initialization is only required when
-> accessing the provider directly.
+```typescript
+builder.setAdapter('console', async () => new ConsoleAnalyticsAdapter());
+```
 
-## Adapters
+### FusionAnalyticsAdapter
 
-Adapters are responsible for processing and sending telemetry data to their
-respective destinations. All adapters support asynchronous initialization and
-will automatically be initialized when the analytics provider initializes.
+Forwards analytics events to an OpenTelemetry-compatible log endpoint via a
+bundled `LoggerProvider`.
 
-### Using `setAdapter`
+Configuration options:
 
-The `AnalyticsConfigurator` provides a method for adding adapters: `setAdapter`
-for pre-instantiated adapters.
+| Option | Type | Description |
+|---|---|---|
+| `portalId` | `string` | Portal identifier included in every log record |
+| `logExporter` | `OTLPExporterBase` | OTLP log exporter for transport |
 
-#### Simple `setAdapter` Example
+#### Using `OTLPLogExporter` (direct HTTP)
 
 ```typescript
-import { enableAnalytics } from '@equinor/fusion-framework-module-analytics';
-import { ConsoleAnalyticsAdapter } from '@equinor/fusion-framework-module-analytics/adapters';
+import { OTLPLogExporter } from '@equinor/fusion-framework-module-analytics/logExporters';
+import { FusionAnalyticsAdapter } from '@equinor/fusion-framework-module-analytics/adapters';
 
-const configure = (configurator: IModulesConfigurator<any, any>) => {
-  enableAnalytics(configurator, (builder) => {
-    builder.setAdapter('console', async () => {
-      return new ConsoleAnalyticsAdapter();
-    });
+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 });
+});
 ```
 
-### Console Adapter
-
-The `ConsoleAnalyticsAdapter` provides a simple way to log analytics data to the
-console, useful for development and debugging.
+#### Using `FusionOTLPLogExporter` (service discovery HTTP client)
 
-#### Installation
-
-The Console Adapter is included with the analytics module and doesn't require
-additional installation.
+```typescript
+import { FusionOTLPLogExporter } from '@equinor/fusion-framework-module-analytics/logExporters';
+import { FusionAnalyticsAdapter } from '@equinor/fusion-framework-module-analytics/adapters';
 
-#### Configuration
+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');
+});
+```
 
-The Console Adapter does not require any configuration.
+### Creating a Custom Adapter
 
-### Fusion Analytics Adapter
+Implement `IAnalyticsAdapter` and register it with `setAdapter`:
 
-The `FusionAnalyticsAdapter` provides a way to log analytics data to a service
-using the OpenTelemetry Logs pattern.
+```typescript
+import type { IAnalyticsAdapter } from '@equinor/fusion-framework-module-analytics/adapters';
+import type { AnalyticsEvent } from '@equinor/fusion-framework-module-analytics';
 
-#### Installation
+class MyRemoteAdapter implements IAnalyticsAdapter {
+  registerAnalytic(event: AnalyticsEvent): void {
+    navigator.sendBeacon('/analytics', JSON.stringify(event));
+  }
 
-The Fusion Analytics Adapter is included with the analytics module and doesn't
-require additional installation.
+  [Symbol.dispose](): void {
+    // cleanup if needed
+  }
+}
 
-#### Configuration
+builder.setAdapter('remote', async () => new MyRemoteAdapter());
+```
 
-The Fusion Analytics Adapter support the following configuration options:
+## Collectors
 
-- `portalId`: The portal Id to be included in log records.
+Collectors implement `IAnalyticsCollector` (or extend `BaseCollector`) and emit
+`AnalyticsEvent` objects that are forwarded to all adapters. All collectors
+support async initialisation.
 
-- `logExporter`: The exporter to use. We bundle `OTLPLogExporter` and `FusionOTLPLogExporter` - see below.
+### ContextSelectedCollector
 
-##### Example configuration
+Emits an event when the active Fusion context changes. Includes the new context,
+the previous context, and the current app key in attributes.
 
 ```typescript
-// OTLPLogExporter
-import { OTLPLogExporter } from '@equinor/fusion-framework-module-analytics/logExporters';
-
-builder.setAdapter('fusion-log', async () => {
-  const logExporter = new OTLPLogExporter({
-    url: 'URL_TO_POST_TO',
-    headers: {
-      'Content-Type': 'application/json',
-    },
-  });
-
-  return new FusionAnalyticsAdapter({
-    portalId: 'PORTAL_ID',
-    logExporter,
-  });
+builder.setCollector('context-selected', async (args) => {
+  const ctx = await args.requireInstance('context');
+  const app = await args.requireInstance('app');
+  return new ContextSelectedCollector(ctx, app);
 });
+```
 
-// FusionOTLPLogExporter with httpClient
-import { FusionOTLPLogExporter } from '@equinor/fusion-framework-module-analytics/logExporters';
+### AppSelectedCollector
 
-builder.setAdapter('fusion', async (args) => {
-  if (args.hasModule('serviceDiscovery')) {
-    const serviceDiscovery = await args.requireInstance<ServiceDiscoveryProvider>(
-      'serviceDiscovery'
-    );
-    const httpClient = await serviceDiscovery.createClient('SERVICE_DISCOVERY_NAME');
+Emits an event when the active application changes. Includes the new and
+previous app key metadata.
 
-    const logExporter = new FusionOTLPLogExporter(httpClient);
-
-    return new FusionAnalyticsAdapter({
-      portalId: 'PORTAL_ID',
-      logExporter,
-    });
-  }
-  console.error('Could not instanziate monitor http client from service-discovery');
+```typescript
+builder.setCollector('app-selected', async (args) => {
+  const app = await args.requireInstance('app');
+  return new AppSelectedCollector(app);
 });
 ```
 
-### Creating Custom Adapters
+### AppLoadedCollector
 
-You can create custom analytics adapters by implementing the `IAnalyticsAdapter`
-interface and add it in configuration.
+Emits an event when an application's modules finish loading. Includes app
+manifest metadata and the current context (if available).
 
-## Collectors
+```typescript
+builder.setCollector('app-loaded', async (args) => {
+  const event = await args.requireInstance('event');
+  const app = await args.requireInstance('app');
+  return new AppLoadedCollector(event, app);
+});
+```
 
-Collectors are responsible for sending events that adapters can pick up. All
-collectors support asynchronous initialization and will automatically be
-initialized when the analytics provider initializes.
+### Creating a Custom Collector
 
-### Using `setCollector`
+Extend `BaseCollector` with a Zod schema for validation:
 
-The `AnalyticsConfigurator` provides a method for adding collectors:
-`setCollector` for pre-instantiated collectors.
+```typescript
+import { BaseCollector, createSchema } from '@equinor/fusion-framework-module-analytics/collectors';
+import { z } from 'zod';
+import { of } from 'rxjs';
 
-### Simple `setCollector` Example
+const schema = createSchema(z.string(), z.object({ page: z.string() }));
 
-```typescript
-import { enableAnalytics } from '@equinor/fusion-framework-module-analytics';
-import { ContextSelectedCollector } from '@equinor/fusion-framework-module-analytics/collectors';
+class PageViewCollector extends BaseCollector<string, { page: string }> {
+  constructor() {
+    super('page-view', schema);
+  }
 
-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);
-    });
-  });
+  _initialize() {
+    return of({ value: window.location.pathname, attributes: { page: document.title } });
+  }
 }
 ```
 
-### Context Selected Collector
+## Tracking Events Manually
 
-The `ContextSelectedCollector` listens for selection in the context module and emits
-the new and optional previous context.
+The provider exposes methods for ad-hoc event tracking outside of collectors:
 
-#### Installation
+```typescript
+// Single event
+provider.trackAnalytic({
+  name: 'button-click',
+  value: 'save',
+  attributes: { section: 'toolbar' },
+});
 
-The Context Selected Collector is included with the analytics module and doesn't
-require additional installation.
+// Observable stream
+const subscription = provider.trackAnalytic$(myEvent$);
+// later: subscription.unsubscribe();
+```
 
 #### Configuration
 

package/dist/esm/AnalyticsConfigurator.js

@@ -2,18 +2,21 @@ import { BaseConfigBuilder, } from '@equinor/fusion-framework-module';
 import { from } 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.
+ * Default {@link IAnalyticsConfigurator} implementation for registering 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.
+ * 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 BaseConfigBuilder
- * @see IAnalyticsConfigurator
+ * @see {@link IAnalyticsConfigurator}
+ * @see {@link BaseConfigBuilder}
  */
 export class AnalyticsConfigurator extends BaseConfigBuilder {
     #collectorCallbacks = {};
@@ -36,22 +39,24 @@ export class AnalyticsConfigurator extends BaseConfigBuilder {
         });
     }
     /**
-     * Registers a analytics collector with the configurator.
+     * Registers an analytics collector factory.
      *
-     * @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
+     * @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(identifier, callback) {
         this.#collectorCallbacks[identifier] = callback;
         return this;
     }
     /**
-     * Registers a analytics adapter with the configurator.
+     * Registers an analytics adapter factory.
      *
-     * @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
+     * @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(identifier, callback) {
         this.#adapterCallbacks[identifier] = callback;

package/dist/esm/AnalyticsConfigurator.js.map

@@ -1 +1 @@
-{"version":3,"file":"AnalyticsConfigurator.js","sourceRoot":"","sources":["../../src/AnalyticsConfigurator.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,GAGlB,MAAM,kCAAkC,CAAC;AAK1C,OAAO,EAAE,IAAI,EAAwB,MAAM,MAAM,CAAC;AAElD,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,cAAc,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1F;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,qBACX,SAAQ,iBAAkC;IAG1C,mBAAmB,GAA+D,EAAE,CAAC;IACrF,iBAAiB,GAA6D,EAAE,CAAC;IAEjF;QACE,KAAK,EAAE,CAAC;QAER,wGAAwG;QACxG,IAAI,CAAC,IAAI,CACP,YAAY,EACZ,CAAC,IAA+B,EAAwD,EAAE;YACxF,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC,CAAC,IAAI,CACxD,QAAQ,CAAC,CAAC,CAAC,UAAU,EAAE,WAAW,CAAC,EAAE,EAAE,CACrC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAC1B,MAAM,CAAC,CAAC,SAAS,EAAoC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,EACpE,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,UAAU,EAAE,SAAS,CAAU,CAAC,CACrD,CACF,EACD,IAAI,CACF,CAAC,GAAG,EAAE,CAAC,UAAU,EAAE,SAAS,CAAC,EAAE,EAAE;gBAC/B,GAAG,CAAC,UAAU,CAAC,GAAG,SAAS,CAAC;gBAC5B,OAAO,GAAG,CAAC;YACb,CAAC,EACD,EAAyC,CAC1C,EACD,cAAc,CAAC,EAAE,CAAC,EAClB,WAAW,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAC/C,CAAC;QACJ,CAAC,CACF,CAAC;QAEF,oGAAoG;QACpG,IAAI,CAAC,IAAI,CACP,UAAU,EACV,CAAC,IAA+B,EAAsD,EAAE;YACtF,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC,CAAC,IAAI,CACtD,QAAQ,CAAC,CAAC,CAAC,UAAU,EAAE,SAAS,CAAC,EAAE,EAAE,CACnC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CACxB,MAAM,CAAC,CAAC,OAAO,EAAgC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,EAC5D,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,UAAU,EAAE,OAAO,CAAU,CAAC,CACjD,CACF,EACD,IAAI,CACF,CAAC,GAAG,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC,EAAE,EAAE;gBAC7B,GAAG,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC;gBAC1B,OAAO,GAAG,CAAC;YACb,CAAC,EACD,EAAuC,CACxC,EACD,cAAc,CAAC,EAAE,CAAC,EAClB,WAAW,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAC/C,CAAC;QACJ,CAAC,CACF,CAAC;IACJ,CAAC;IAED;;;;;;OAMG;IACH,YAAY,CACV,UAAkB,EAClB,QAAuD;QAEvD,IAAI,CAAC,mBAAmB,CAAC,UAAU,CAAC,GAAG,QAAQ,CAAC;QAChD,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;OAMG;IACH,UAAU,CACR,UAAkB,EAClB,QAAqD;QAErD,IAAI,CAAC,iBAAiB,CAAC,UAAU,CAAC,GAAG,QAAQ,CAAC;QAC9C,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}
+{"version":3,"file":"AnalyticsConfigurator.js","sourceRoot":"","sources":["../../src/AnalyticsConfigurator.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,GAGlB,MAAM,kCAAkC,CAAC;AAK1C,OAAO,EAAE,IAAI,EAAwB,MAAM,MAAM,CAAC;AAElD,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,cAAc,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1F;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,qBACX,SAAQ,iBAAkC;IAG1C,mBAAmB,GAA+D,EAAE,CAAC;IACrF,iBAAiB,GAA6D,EAAE,CAAC;IAEjF;QACE,KAAK,EAAE,CAAC;QAER,wGAAwG;QACxG,IAAI,CAAC,IAAI,CACP,YAAY,EACZ,CAAC,IAA+B,EAAwD,EAAE;YACxF,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC,CAAC,IAAI,CACxD,QAAQ,CAAC,CAAC,CAAC,UAAU,EAAE,WAAW,CAAC,EAAE,EAAE,CACrC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAC1B,MAAM,CAAC,CAAC,SAAS,EAAoC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,EACpE,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,UAAU,EAAE,SAAS,CAAU,CAAC,CACrD,CACF,EACD,IAAI,CACF,CAAC,GAAG,EAAE,CAAC,UAAU,EAAE,SAAS,CAAC,EAAE,EAAE;gBAC/B,GAAG,CAAC,UAAU,CAAC,GAAG,SAAS,CAAC;gBAC5B,OAAO,GAAG,CAAC;YACb,CAAC,EACD,EAAyC,CAC1C,EACD,cAAc,CAAC,EAAE,CAAC,EAClB,WAAW,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAC/C,CAAC;QACJ,CAAC,CACF,CAAC;QAEF,oGAAoG;QACpG,IAAI,CAAC,IAAI,CACP,UAAU,EACV,CAAC,IAA+B,EAAsD,EAAE;YACtF,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC,CAAC,IAAI,CACtD,QAAQ,CAAC,CAAC,CAAC,UAAU,EAAE,SAAS,CAAC,EAAE,EAAE,CACnC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CACxB,MAAM,CAAC,CAAC,OAAO,EAAgC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,EAC5D,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,UAAU,EAAE,OAAO,CAAU,CAAC,CACjD,CACF,EACD,IAAI,CACF,CAAC,GAAG,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC,EAAE,EAAE;gBAC7B,GAAG,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC;gBAC1B,OAAO,GAAG,CAAC;YACb,CAAC,EACD,EAAuC,CACxC,EACD,cAAc,CAAC,EAAE,CAAC,EAClB,WAAW,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAC/C,CAAC;QACJ,CAAC,CACF,CAAC;IACJ,CAAC;IAED;;;;;;;OAOG;IACH,YAAY,CACV,UAAkB,EAClB,QAAuD;QAEvD,IAAI,CAAC,mBAAmB,CAAC,UAAU,CAAC,GAAG,QAAQ,CAAC;QAChD,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;;OAOG;IACH,UAAU,CACR,UAAkB,EAClB,QAAqD;QAErD,IAAI,CAAC,iBAAiB,CAAC,UAAU,CAAC,GAAG,QAAQ,CAAC;QAC9C,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}

package/dist/esm/AnalyticsProvider.js

@@ -1,6 +1,13 @@
 import { BaseModuleProvider } from '@equinor/fusion-framework-module/provider';
 import { version } from './version.js';
 import { from, Subject, Subscription } from 'rxjs';
+/**
+ * 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 {
     constructor(subscription) {
         super(subscription.unsubscribe);
@@ -10,14 +17,22 @@ class DisposableSubscription extends Subscription {
     };
 }
 /**
- * Provides analytics tracking, adapters integration and collectors for application instrumentation.
+ * Runtime analytics provider that collects events from collectors and dispatches
+ * them to adapters.
  *
- * The `AnalyticsProvider` class is responsible for collecting, processing and relaying analytics
- * data to the adapters. The events are collected with collectors.
+ * @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$}.
  *
- * @typeParam AnalyticsConfig - The configuration type for analytics.
- * @implements IAnalyticsProvider
  * @extends BaseModuleProvider<AnalyticsConfig>
+ * @implements IAnalyticsProvider
  */
 export class AnalyticsProvider extends BaseModuleProvider {
     #analytics;
@@ -30,16 +45,21 @@ export class AnalyticsProvider extends BaseModuleProvider {
         this.#adapters = config.adapters;
     }
     /**
-     * Initializes the analytics provider with adapters and collectors.
+     * 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.
      *
-     * 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
+     * All subscriptions are registered as teardowns on the base provider.
      *
-     * @returns A promise that resolves when initialization is complete
+     * @returns A promise that resolves when all adapters and collectors are initialised.
      */
     async initialize() {
         const initializedCollectors = Object.values(this.#collectors).map((collector) => Promise.resolve(collector.initialize?.()));
@@ -64,19 +84,20 @@ export class AnalyticsProvider extends BaseModuleProvider {
         this._addTeardown(adapterSubscription);
     }
     /**
-     * Tracks an analytics event
+     * Pushes a single analytics event to all registered adapters.
      *
-     * @param event - The analytics event to track
+     * @param event - The analytics event to track.
      */
     trackAnalytic(event) {
         // @TODO: Validate AnalyticsEvent includes name, value and attributes
         this.#analytics.next(event);
     }
     /**
-     * Uses a analytics stream and returns both Disposable and Subscription for cleanup.
+     * Subscribes to an observable stream of analytics events and forwards each
+     * emission to all registered adapters.
      *
-     * @param analytic$ - Observable input stream of analytic events.
-     * @returns Object containing both Disposable and Subscription for proper cleanup.
+     * @param analytic$ - Observable input stream of analytics events.
+     * @returns A {@link DisposableSubscription} supporting both `unsubscribe()` and `Symbol.dispose`.
      */
     trackAnalytic$(analytic$) {
         const subscription = from(analytic$)

package/dist/esm/AnalyticsProvider.js.map

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

package/dist/esm/adapters/ConsoleAnalyticsAdapter.js

@@ -1,7 +1,21 @@
 /**
- * An analytics adapter printing the events to the console.
+ * Analytics adapter that logs every event to the browser console.
+ *
+ * @remarks
+ * Useful during development and debugging. Each event is logged with the
+ * prefix `Analytics::Adapter::Console`.
+ *
+ * @template T - Analytics event type, defaults to {@link AnalyticsEvent}.
+ *
+ * @example
+ * ```ts
+ * import { ConsoleAnalyticsAdapter } from '@equinor/fusion-framework-module-analytics/adapters';
+ *
+ * builder.setAdapter('console', async () => new ConsoleAnalyticsAdapter());
+ * ```
  */
 export class ConsoleAnalyticsAdapter {
+    /** Logs the event to the console. */
     registerAnalytic(event) {
         console.log('Analytics::Adapter::Console', event);
     }

package/dist/esm/adapters/ConsoleAnalyticsAdapter.js.map

@@ -1 +1 @@
-{"version":3,"file":"ConsoleAnalyticsAdapter.js","sourceRoot":"","sources":["../../../src/adapters/ConsoleAnalyticsAdapter.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,MAAM,OAAO,uBAAuB;IAGlC,gBAAgB,CAAC,KAAQ;QACvB,OAAO,CAAC,GAAG,CAAC,6BAA6B,EAAE,KAAK,CAAC,CAAC;IACpD,CAAC;IAED,CAAC,MAAM,CAAC,OAAO,CAAC;QACd,QAAQ;IACV,CAAC;CACF"}
+{"version":3,"file":"ConsoleAnalyticsAdapter.js","sourceRoot":"","sources":["../../../src/adapters/ConsoleAnalyticsAdapter.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,uBAAuB;IAGlC,qCAAqC;IACrC,gBAAgB,CAAC,KAAQ;QACvB,OAAO,CAAC,GAAG,CAAC,6BAA6B,EAAE,KAAK,CAAC,CAAC;IACpD,CAAC;IAED,CAAC,MAAM,CAAC,OAAO,CAAC;QACd,QAAQ;IACV,CAAC;CACF"}