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

package/dist/types/collectors/utils/extractContextMetadata.d.ts

@@ -1,5 +1,12 @@
 import { z } from 'zod';
 import type { ContextItem } from '@equinor/fusion-framework-module-context';
+/**
+ * Zod schema for a Fusion context metadata object.
+ *
+ * @remarks
+ * Validates core context fields (id, type) and optional title, externalId,
+ * and source. Used by {@link ContextSelectedCollector} and {@link AppLoadedCollector}.
+ */
 export declare const contextSchema: z.ZodNullable<z.ZodOptional<z.ZodObject<{
     id: z.ZodString;
     type: z.ZodString;
@@ -7,5 +14,12 @@ export declare const contextSchema: z.ZodNullable<z.ZodOptional<z.ZodObject<{
     externalId: z.ZodOptional<z.ZodString>;
     source: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>>>;
+/** Inferred type from {@link contextSchema}. */
 export type ContextItemType = z.infer<typeof contextSchema>;
+/**
+ * Extracts context metadata from a `ContextItem` for analytics events.
+ *
+ * @param context - The Fusion context item.
+ * @returns An object with id, type, and optional title, externalId, and source.
+ */
 export declare const extractContextMetadata: (context: ContextItem) => z.input<typeof contextSchema>;

package/dist/types/enable-analytics.d.ts

@@ -1,11 +1,27 @@
 import type { IModulesConfigurator } from '@equinor/fusion-framework-module';
 import type { IAnalyticsConfigurator } from './AnalyticsConfigurator.interface.js';
+/** Callback invoked with the {@link IAnalyticsConfigurator} to register adapters and collectors. */
 type AnalyticsBuilderCallback = (builder: IAnalyticsConfigurator) => void | Promise<void>;
 /**
- * Enables analytics for agiven module configurator.
+ * Enables the analytics module on a Fusion Framework module configurator.
  *
- * @param configurator - The module configurator instance to which analytics should be attached.
- * @param callback - An optional callback to further configure the analytics builder. Can be synchronous or asynchronous.
+ * Call this helper during application or portal configuration to register
+ * adapters and collectors for analytics tracking.
+ *
+ * @param configurator - The module configurator instance to attach analytics to.
+ * @param callback - Optional callback to register adapters and collectors on the analytics builder.
+ *
+ * @example
+ * ```ts
+ * import { enableAnalytics } from '@equinor/fusion-framework-module-analytics';
+ * import { ConsoleAnalyticsAdapter } from '@equinor/fusion-framework-module-analytics/adapters';
+ *
+ * const configure = (configurator) => {
+ *   enableAnalytics(configurator, (builder) => {
+ *     builder.setAdapter('console', async () => new ConsoleAnalyticsAdapter());
+ *   });
+ * };
+ * ```
  */
 export declare const enableAnalytics: (configurator: IModulesConfigurator<any, any>, callback?: AnalyticsBuilderCallback) => void;
 export {};

package/dist/types/index.d.ts

@@ -1,3 +1,21 @@
+/**
+ * `@equinor/fusion-framework-module-analytics` — Fusion Framework module for
+ * collecting and exporting application analytics using OpenTelemetry standards.
+ *
+ * @remarks
+ * This package provides a pluggable adapter/collector architecture:
+ *
+ * - **Adapters** receive analytics events and forward them to a backend
+ *   (e.g. console, OTLP endpoint).
+ * - **Collectors** observe application state (context changes, app loads) and
+ *   emit structured {@link AnalyticsEvent} instances.
+ *
+ * Import adapters from `'@equinor/fusion-framework-module-analytics/adapters'`,
+ * collectors from `'@equinor/fusion-framework-module-analytics/collectors'`,
+ * and log exporters from `'@equinor/fusion-framework-module-analytics/logExporters'`.
+ *
+ * @packageDocumentation
+ */
 export { module as analyticsModule, AnalyticsModule } from './module.js';
 export { AnalyticsEvent, AnyValue, AnyValueMap } from './types.js';
 export { AnalyticsProvider } from './AnalyticsProvider.js';

package/dist/types/logExporters/fusionOTLPLogExporter/FusionOTLPLogExporter.d.ts

@@ -2,10 +2,28 @@ import type { LogRecordExporter, ReadableLogRecord } from '@opentelemetry/sdk-lo
 import { OTLPExporterBase } from '@opentelemetry/otlp-exporter-base';
 import type { IHttpClient } from '@equinor/fusion-framework-module-http';
 /**
- * A log exporter extending OTLPExporterBase but substitute the normal transport
- * with a HttpClientExporterTransport. This will use the provided httpClient to
- * emit the event.
+ * OTLP log exporter that uses a Fusion `IHttpClient` as its HTTP transport.
+ *
+ * @remarks
+ * Extends `OTLPExporterBase` and substitutes the default `fetch`-based transport
+ * with {@link HttpClientExporterTransport}, routing log record payloads
+ * through the Fusion HTTP module’s configured client (which may include
+ * authentication headers, interceptors, and service‑discovery routing).
+ *
+ * Typically used with {@link FusionAnalyticsAdapter} when the portal provides
+ * an HTTP client via service discovery.
+ *
+ * @example
+ * ```ts
+ * import { FusionOTLPLogExporter } from '@equinor/fusion-framework-module-analytics/logExporters';
+ *
+ * const httpClient = await serviceDiscovery.createClient('analytics');
+ * const exporter = new FusionOTLPLogExporter(httpClient);
+ * ```
  */
 export declare class FusionOTLPLogExporter extends OTLPExporterBase<ReadableLogRecord[]> implements LogRecordExporter {
+    /**
+     * @param httpClient - A Fusion `IHttpClient` used for outbound HTTP transport.
+     */
     constructor(httpClient: IHttpClient);
 }

package/dist/types/logExporters/fusionOTLPLogExporter/HttpClientExporterTransport.d.ts

@@ -1,12 +1,35 @@
 import type { IExporterTransport, ExportResponse } from '@opentelemetry/otlp-exporter-base';
 import type { IHttpClient } from '@equinor/fusion-framework-module-http';
 /**
- * A Exporter Transport to POST events to provided path using the provided httpClient
+ * OpenTelemetry exporter transport that posts serialised log records using a
+ * Fusion `IHttpClient`.
+ *
+ * @remarks
+ * Implements `IExporterTransport` from `@opentelemetry/otlp-exporter-base`.
+ * The transport honours the exporter’s timeout via `AbortController` and
+ * inspects response status codes to report retryable failures (429, 502–504).
+ *
+ * @example
+ * ```ts
+ * const transport = new HttpClientExporterTransport(httpClient, '/v1/logs');
+ * ```
  */
 export declare class HttpClientExporterTransport implements IExporterTransport {
     private httpClient;
     private path;
+    /**
+     * @param httpClient - Fusion HTTP client for outgoing requests.
+     * @param path - URL path appended to the client’s base URL (default `'/v1/logs'`).
+     */
     constructor(httpClient: IHttpClient, path?: string);
+    /**
+     * Sends serialised log record data to the configured endpoint.
+     *
+     * @param data - Serialised OTLP payload as a `Uint8Array`.
+     * @param timeoutMillis - Maximum time in milliseconds before the request is aborted.
+     * @returns An `ExportResponse` indicating success, retryable failure, or permanent failure.
+     */
     send(data: Uint8Array, timeoutMillis: number): Promise<ExportResponse>;
+    /** No-op; the HTTP client does not hold persistent connections. */
     shutdown(): void;
 }

package/dist/types/logExporters/index.d.ts

@@ -1,2 +1,10 @@
+/**
+ * Re-exports for OTLP log exporters used by analytics adapters.
+ *
+ * @remarks
+ * Import from `'@equinor/fusion-framework-module-analytics/logExporters'`.
+ *
+ * @packageDocumentation
+ */
 export { FusionOTLPLogExporter } from './fusionOTLPLogExporter/FusionOTLPLogExporter.js';
 export { OTLPLogExporter } from '@opentelemetry/exporter-logs-otlp-http';

package/dist/types/module.d.ts

@@ -3,16 +3,16 @@ import type { IAnalyticsConfigurator } from './AnalyticsConfigurator.interface.j
 import type { IAnalyticsProvider } from './AnalyticsProvider.interface.js';
 import { AnalyticsConfigurator } from './AnalyticsConfigurator.js';
 /**
- * Representes the Analytics module within the framework.
+ * Represents the Analytics module type within the Fusion Framework module system.
  *
  * @remarks
- * This type defines a module names `analytics` that integrates with the framwork's module system.
- * It specifies the provider and configurator interfaces for analytics functionality, and declares
- * its dependencies on itself (`AnalyticsModule`).
+ * This type defines a module named `analytics` that integrates with the framework's
+ * module system. It specifies the provider and configurator interfaces for analytics
+ * functionality, and declares a self-dependency so that child modules can inherit
+ * analytics from a parent scope.
  *
- * @typeParam IAnalyticsProvider - The interface for the analytics provider implementation.
- * @typeParam IAnalyticsConfigurator - The interface for configuring analytics behavior.
- * @typeParam AnalyticsModule - Self-reference to allow for recursive or hierarchical module composition.
+ * @see {@link IAnalyticsProvider} for the runtime provider interface.
+ * @see {@link IAnalyticsConfigurator} for configuration-time setup.
  */
 export type AnalyticsModule = Module<'analytics', IAnalyticsProvider, IAnalyticsConfigurator, [
     AnalyticsModule
@@ -21,15 +21,15 @@ export type AnalyticsModule = Module<'analytics', IAnalyticsProvider, IAnalytics
  * Analytics module definition for the Fusion Framework.
  *
  * @remarks
- * This module provides analytics capabilities by configuring and initializing a analytics provider.
+ * This module provides analytics capabilities by configuring and initializing an
+ * {@link AnalyticsProvider}. Register it with {@link enableAnalytics} or add it
+ * directly to a module configurator.
  *
- * @type {AnalyticsModule}
- *
- * @property {string} name - The name of the module ('analytics').
- * @property {() => AnalyticsConfigurator} configure - Factory function to create a new AnalyticsConfigurator instance.
- * @property {(args) => Promise<IAnalyticsProvider>} initialize - Asynchronous initializer that creates and returns a AnalyticsProvider.
- *   - @param args - Initialization arguments, including configuration and module dependencies.
- *   - @returns A promise that resolves to an instance of IAnalyticsProvider.
+ * - `name` — `'analytics'`
+ * - `configure()` — creates a new {@link AnalyticsConfigurator} instance.
+ * - `initialize(args)` — resolves the configuration, creates an
+ *   {@link AnalyticsProvider}, calls {@link AnalyticsProvider.initialize},
+ *   and returns the ready-to-use provider.
  */
 export declare const module: {
     name: "analytics";

package/dist/types/types.d.ts

@@ -1,22 +1,53 @@
+/**
+ * Scalar analytics attribute value: a string, number, or boolean.
+ *
+ * @remarks
+ * Mirrors the OpenTelemetry `AnyValue` scalar subset used in log record
+ * attributes and event bodies.
+ */
 export type AnyValueScalar = string | number | boolean;
+/** Array of {@link AnyValue} entries, allowing nested attribute structures. */
 export type AnyValueArray = Array<AnyValue>;
 /**
- * AnyValueMap is a map from string to AnyValue (attribute value or a nested map)
+ * A key–value map where each value is an {@link AnyValue}.
+ *
+ * Used as the attribute bag on {@link AnalyticsEvent} instances and for
+ * nested attribute structures.
  */
 export interface AnyValueMap {
     [attributeKey: string]: AnyValue;
 }
 /**
- * AnyValue can be one of the following:
- * - a scalar value
- * - a byte array
- * - array of any value
- * - map from string to any value
- * - empty value
+ * A flexible value type compatible with OpenTelemetry log record bodies and attributes.
+ *
+ * Can be one of the following:
+ * - a scalar value (`string | number | boolean`)
+ * - a byte array (`Uint8Array`)
+ * - an array of any value ({@link AnyValueArray})
+ * - a map from string to any value ({@link AnyValueMap})
+ * - `null` or `undefined`
  */
 export type AnyValue = AnyValueScalar | Uint8Array | AnyValueArray | AnyValueMap | null | undefined;
+/**
+ * Represents a single analytics event emitted by a collector and consumed by adapters.
+ *
+ * @template TValue - The event body type, defaults to {@link AnyValue}.
+ * @template TAttr - The attributes map type, defaults to {@link AnyValueMap}.
+ *
+ * @example
+ * ```ts
+ * const event: AnalyticsEvent = {
+ *   name: 'button-click',
+ *   value: 'submit',
+ *   attributes: { section: 'header', count: 1 },
+ * };
+ * ```
+ */
 export type AnalyticsEvent<TValue extends AnyValue = AnyValue, TAttr extends AnyValueMap = AnyValueMap> = {
+    /** Descriptive event name used to categorise the analytic, e.g. `'context-selected'`. */
     name: string;
+    /** The primary payload of the event. */
     value: TValue;
+    /** Optional metadata attached to the event for filtering and grouping. */
     attributes?: TAttr;
 };

package/dist/types/version.d.ts

@@ -1 +1 @@
-export declare const version = "1.0.2";
+export declare const version = "2.0.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/fusion-framework-module-analytics",
-  "version": "1.0.2",
+  "version": "2.0.0",
   "description": "Fusion module for collecting and exporting application analytics using OpenTelemetry standards",
   "main": "dist/esm/index.js",
   "type": "module",
@@ -48,20 +48,20 @@
     "deepmerge": "^4.3.1",
     "rxjs": "^7.8.1",
     "uuid": "^13.0.0",
-    "zod": "^4.1.11",
-    "@equinor/fusion-framework-module": "5.0.6",
-    "@equinor/fusion-framework-module-app": "7.4.1",
-    "@equinor/fusion-framework-module-context": "7.0.3",
-    "@equinor/fusion-framework-module-http": "7.0.8",
-    "@equinor/fusion-framework-module-event": "5.0.1"
+    "zod": "^4.3.6",
+    "@equinor/fusion-framework-module": "6.0.0",
+    "@equinor/fusion-framework-module-app": "8.0.0",
+    "@equinor/fusion-framework-module-event": "6.0.0",
+    "@equinor/fusion-framework-module-context": "8.0.0",
+    "@equinor/fusion-framework-module-http": "8.0.0"
   },
   "devDependencies": {
-    "typescript": "^5.8.2",
-    "vitest": "^3.2.4",
-    "@equinor/fusion-observable": "^8.5.8"
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0",
+    "@equinor/fusion-observable": "^9.0.0"
   },
   "peerDependencies": {
-    "@equinor/fusion-observable": "8.5.8"
+    "@equinor/fusion-observable": "9.0.0"
   },
   "scripts": {
     "build": "tsc -b",

package/src/AnalyticsConfigurator.interface.ts

@@ -4,29 +4,53 @@ import type { IAnalyticsAdapter } from './adapters/AnalyticsAdapter.interface.js
 import type { AnalyticsEvent } from './types.js';
 
 /**
- * Configuration options for setting up analytics within the framework.
+ * Resolved analytics configuration containing the instantiated collectors and adapters.
  *
- * @property collectors - Record of analytics collectors keyed by identifier to be used for reporting analytics data.
- * @property adapters - Record of analytics adapters keyed by identifier to be used to handle events.
+ * @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>;
 };
 
 /**
- * Interface for configuring analytics within the module.
+ * Configuration-time interface for registering analytics adapters and collectors.
  *
- * Provides methods to set 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.
  *
- * @interface IAnalyticsConfigurator
+ * @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 {
   /**
-   * Sets a analytics collector with the given identifier and configuration callback.
+   * Registers an analytics collector factory identified by a unique key.
    *
-   * @param identifier - The unique identifier for the collector.
-   * @param callBack - Configuration callback that returns the collector instance.
+   * 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>(
@@ -35,10 +59,15 @@ export interface IAnalyticsConfigurator {
   ): this;
 
   /**
-   * Sets a analytics adapter with the given identifier and configuration callback.
+   * 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.
    *
-   * @param identifier - The unique identifier for the adapter.
-   * @param callBack - Configuration callback that returns 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>(

package/src/AnalyticsConfigurator.ts

@@ -12,18 +12,21 @@ 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.
+ * 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<AnalyticsConfig>
@@ -85,11 +88,12 @@ export class AnalyticsConfigurator
   }
 
   /**
-   * 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<T extends AnalyticsEvent>(
     identifier: string,
@@ -100,11 +104,12 @@ export class AnalyticsConfigurator
   }
 
   /**
-   * 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<T extends AnalyticsEvent>(
     identifier: string,

package/src/AnalyticsProvider.interface.ts

@@ -2,21 +2,43 @@ import type { ObservableInput, Subscription } from 'rxjs';
 import type { AnalyticsEvent } from './types.js';
 
 /**
- * Interface for analytics providers used to track analytics events.
+ * 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 {
   /**
-   * Tracks a analytics event.
+   * Pushes a single analytics event to all registered adapters.
    *
-   * @param event - The analytic event to track.
+   * @param event - The analytics event to track.
+   *
+   * @example
+   * ```ts
+   * provider.trackAnalytic({
+   *   name: 'button-click',
+   *   value: 'save',
+   *   attributes: { page: 'settings' },
+   * });
+   * ```
    */
   trackAnalytic(event: AnalyticsEvent): void;
 
   /**
-   * 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 analytics events.
+   * @returns A combined `Disposable & Subscription` handle for cleanup.
    *
-   * @param analytic$ - Observable input stream of analytic events.
-   * @returns Object containing both Disposable and Subscription for proper cleanup.
+   * @example
+   * ```ts
+   * const sub = provider.trackAnalytic$(myEvent$);
+   * // later
+   * sub.unsubscribe();
+   * ```
    */
   trackAnalytic$(analytic$: ObservableInput<AnalyticsEvent>): Disposable & Subscription;
 }

package/src/AnalyticsProvider.ts

@@ -9,6 +9,13 @@ 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 {
   constructor(subscription: Subscription) {
     super(subscription.unsubscribe);
@@ -20,14 +27,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<AnalyticsConfig>
@@ -46,16 +61,21 @@ export class AnalyticsProvider
   }
 
   /**
-   * 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(): Promise<void> {
     const initializedCollectors = Object.values(this.#collectors).map((collector) =>
@@ -89,9 +109,9 @@ export class AnalyticsProvider
   }
 
   /**
-   * 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: AnalyticsEvent): void {
     // @TODO: Validate AnalyticsEvent includes name, value and attributes
@@ -99,10 +119,11 @@ export class AnalyticsProvider
   }
 
   /**
-   * 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$: ObservableInput<AnalyticsEvent>): Disposable & Subscription {
     const subscription = from(analytic$)

package/src/adapters/AnalyticsAdapter.interface.ts

@@ -1,9 +1,22 @@
 import type { AnalyticsEvent } from '../types.js';
 
 /**
- * Interface representing an analytics adapter responsible for handling analytics events.
+ * Contract for an analytics adapter that receives events and exports them to a backend.
  *
- * @template T - The type of analytics event handled by the adapter. Defaults to `AnalyticsEvent`.
+ * @remarks
+ * Implement this interface to create a custom adapter. Register it via
+ * {@link IAnalyticsConfigurator.setAdapter}. The adapter must also implement
+ * `Disposable` for resource cleanup.
+ *
+ * @template T - The analytics event type handled by the adapter, defaults to {@link AnalyticsEvent}.
+ *
+ * @example
+ * ```ts
+ * class MyAdapter implements IAnalyticsAdapter {
+ *   registerAnalytic(event) { fetch('/analytics', { method: 'POST', body: JSON.stringify(event) }); }
+ *   [Symbol.dispose]() { /* cleanup *\/ }
+ * }
+ * ```
  */
 export interface IAnalyticsAdapter<T extends AnalyticsEvent = AnalyticsEvent> extends Disposable {
   /**