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

package/src/module.ts

@@ -5,16 +5,16 @@ import { AnalyticsConfigurator } from './AnalyticsConfigurator.js';
 import { AnalyticsProvider } from './AnalyticsProvider.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',
@@ -27,15 +27,15 @@ export type AnalyticsModule = Module<
  * 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 const module = {
   name: 'analytics',

package/src/types.ts

@@ -1,29 +1,60 @@
+/**
+ * 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/src/version.ts

@@ -1,2 +1,2 @@
 // Generated by genversion.
-export const version = '1.0.2';
+export const version = '2.0.0';