@equinor/fusion-framework-module-analytics 3.1.0-next.1 → 3.1.1

package/src/collectors/utils/app-key-schema.ts

@@ -1,17 +0,0 @@
-import { z } from 'zod';
-
-/**
- * Zod schema for an object containing an optional `appKey` string.
- *
- * @remarks
- * Used by {@link AppSelectedCollector} to validate the event body.
- */
-export const appKeySchema = z
-  .object({
-    appKey: z.string().optional(),
-  })
-  .optional()
-  .nullable();
-
-/** Inferred type from {@link appKeySchema}. */
-export type AppKeyType = z.infer<typeof appKeySchema>;

package/src/collectors/utils/app-schema.ts

@@ -1,22 +0,0 @@
-import { z } from 'zod';
-
-/**
- * Zod schema for a Fusion application metadata object.
- *
- * @remarks
- * Validates core app fields (appKey, displayName, type) and optional build
- * and category information. Used by {@link AppLoadedCollector}.
- */
-export const appSchema = z
-  .object({
-    appKey: z.string(),
-    displayName: z.string(),
-    type: z.string(),
-    categoryName: z.string().optional(),
-    buildVersion: z.string().optional(),
-    buildTag: z.string().optional().nullable(),
-  })
-  .optional();
-
-/** Inferred type from {@link appSchema}. */
-export type AppItemType = z.infer<typeof appSchema>;

package/src/collectors/utils/context-schema.ts

@@ -1,22 +0,0 @@
-import { z } from 'zod';
-
-/**
- * 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 const contextSchema = z
-  .object({
-    id: z.string(),
-    type: z.string(),
-    title: z.string().optional(),
-    externalId: z.string().optional(),
-    source: z.string().optional(),
-  })
-  .optional()
-  .nullable();
-
-/** Inferred type from {@link contextSchema}. */
-export type ContextItemType = z.infer<typeof contextSchema>;

package/src/collectors/utils/extract-app-key-metadata.ts

@@ -1,15 +0,0 @@
-import type { CurrentApp } from '@equinor/fusion-framework-module-app';
-import type { z } from 'zod';
-import type { appKeySchema } from './app-key-schema.js';
-
-/**
- * Extracts app-key metadata from a `CurrentApp` instance.
- *
- * @param app - The current app object.
- * @returns An object containing the optional `appKey`.
- */
-export const extractAppKeyMetadata = (app: CurrentApp): z.input<typeof appKeySchema> => {
-  return {
-    appKey: app?.appKey,
-  };
-};

package/src/collectors/utils/extract-app-metadata.ts

@@ -1,20 +0,0 @@
-import type { AppManifest } from '@equinor/fusion-framework-module-app';
-import type { z } from 'zod';
-import type { appSchema } from './app-schema.js';
-
-/**
- * Extracts detailed app metadata from an `AppManifest` for analytics events.
- *
- * @param app - The application manifest.
- * @returns An object with appKey, displayName, type, and optional build/category info.
- */
-export const extractAppMetadata = (app: AppManifest): z.input<typeof appSchema> => {
-  return {
-    appKey: app.appKey,
-    displayName: app.displayName,
-    type: app.type,
-    categoryName: app.category?.name,
-    buildVersion: app.build?.version,
-    buildTag: app.build?.tag,
-  };
-};

package/src/collectors/utils/extract-context-metadata.ts

@@ -1,19 +0,0 @@
-import type { ContextItem } from '@equinor/fusion-framework-module-context';
-import type { z } from 'zod';
-import type { contextSchema } from './context-schema.js';
-
-/**
- * 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 const extractContextMetadata = (context: ContextItem): z.input<typeof contextSchema> => {
-  return {
-    id: context.id,
-    externalId: context.externalId ?? undefined,
-    title: context.title ?? undefined,
-    type: context.type.id,
-    source: context.source ?? undefined,
-  };
-};

package/src/enable-analytics.ts

@@ -1,44 +0,0 @@
-import type { IModulesConfigurator } from '@equinor/fusion-framework-module';
-
-import { module } from './module.js';
-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 the analytics module on a Fusion Framework module configurator.
- *
- * 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 const enableAnalytics = (
-  // biome-ignore lint/suspicious/noExplicitAny: must be any to support all module types
-  configurator: IModulesConfigurator<any, any>,
-  callback?: AnalyticsBuilderCallback,
-): void => {
-  configurator.addConfig({
-    module,
-    configure: async (builder) => {
-      // Only invoke the callback when one was supplied by the caller
-      if (callback) {
-        await Promise.resolve(callback(builder));
-      }
-    },
-  });
-};

package/src/index.ts

@@ -1,30 +0,0 @@
-/**
- * `@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';
-export { IAnalyticsProvider } from './AnalyticsProvider.interface.js';
-
-export { AnalyticsConfig, IAnalyticsConfigurator } from './AnalyticsConfigurator.interface.js';
-export { AnalyticsConfigurator } from './AnalyticsConfigurator.js';
-
-export { enableAnalytics } from './enable-analytics.js';

package/src/logExporters/fusionOTLPLogExporter/FusionOTLPLogExporter.ts

@@ -1,71 +0,0 @@
-import type { LogRecordExporter, ReadableLogRecord } from '@opentelemetry/sdk-logs';
-
-import { JsonLogsSerializer, LogsExporterMetricsHelper } from '@opentelemetry/otlp-transformer';
-
-import {
-  createOtlpNetworkExportDelegate,
-  ExporterMetrics,
-  OTLPExporterBase,
-  type OtlpSharedConfiguration,
-} from '@opentelemetry/otlp-exporter-base';
-
-import type { IHttpClient } from '@equinor/fusion-framework-module-http';
-import { HttpClientExporterTransport } from './HttpClientExporterTransport.js';
-
-/**
- * Returns shared default OTLP exporter configuration values.
- *
- * @returns Default timeout, concurrency limit, and compression settings.
- */
-function getSharedConfigurationDefaults(): OtlpSharedConfiguration {
-  return {
-    timeoutMillis: 10000,
-    concurrencyLimit: 30,
-    compression: 'none',
-  };
-}
-
-/**
- * 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 class FusionOTLPLogExporter
-  extends OTLPExporterBase<ReadableLogRecord[]>
-  implements LogRecordExporter
-{
-  /**
-   * @param httpClient - A Fusion `IHttpClient` used for outbound HTTP transport.
-   */
-  constructor(httpClient: IHttpClient) {
-    super(
-      createOtlpNetworkExportDelegate(
-        getSharedConfigurationDefaults(),
-        JsonLogsSerializer,
-        new ExporterMetrics({
-          componentType: 'fusion_otlp_http_log_exporter',
-          metricsHelper: LogsExporterMetricsHelper,
-          url: undefined,
-          meterProvider: undefined,
-          responseAttributesFromError: () => ({}),
-        }),
-        new HttpClientExporterTransport(httpClient),
-      ),
-    );
-  }
-}

package/src/logExporters/fusionOTLPLogExporter/HttpClientExporterTransport.ts

@@ -1,123 +0,0 @@
-import type { IExporterTransport, ExportResponse } from '@opentelemetry/otlp-exporter-base';
-
-import type { IHttpClient } from '@equinor/fusion-framework-module-http';
-
-/**
- * Checks whether a failed HTTP status code is eligible for automatic retry.
- *
- * @param statusCode - HTTP response status code.
- * @returns `true` for 429, 502, 503, and 504.
- */
-function isExportRetryable(statusCode: number): boolean {
-  // Status codes of when we should consider retrying.
-  // 429 Too Many Requests
-  // 502 Bad Gateway
-  // 503 Service Unavailable
-  // 504 Gateway Timeout
-  const retryCodes = [429, 502, 503, 504];
-  return retryCodes.includes(statusCode);
-}
-
-/**
- * Parses an HTTP `Retry-After` header value into milliseconds.
- *
- * @param retryAfter - Raw header value (integer seconds or HTTP-date).
- * @returns Delay in milliseconds, `-1` for non-positive integers, or `undefined` if absent.
- */
-function parseRetryAfterToMills(retryAfter?: string | undefined | null): number | undefined {
-  // No header present — nothing to compute
-  if (retryAfter == null) {
-    return undefined;
-  }
-
-  const seconds = Number.parseInt(retryAfter, 10);
-  // Retry-After given as a plain integer number of seconds
-  if (Number.isInteger(seconds)) {
-    return seconds > 0 ? seconds * 1000 : -1;
-  }
-  // https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After#directives
-  const delay = new Date(retryAfter).getTime() - Date.now();
-
-  // Only report a positive delay; a past date means retry is already due
-  if (delay >= 0) {
-    return delay;
-  }
-  return 0;
-}
-
-/**
- * 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 class HttpClientExporterTransport implements IExporterTransport {
-  /**
-   * @param httpClient - Fusion HTTP client for outgoing requests.
-   * @param path - URL path appended to the client’s base URL (default `'/v1/logs'`).
-   */
-  constructor(
-    private httpClient: IHttpClient,
-    private path: string = '/v1/logs',
-  ) {}
-
-  /**
-   * 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.
-   */
-  async send(data: Uint8Array, timeoutMillis: number): Promise<ExportResponse> {
-    const abortController = new AbortController();
-    const timeout = setTimeout(() => abortController.abort(), timeoutMillis);
-
-    try {
-      const response = await this.httpClient.fetch(this.path, {
-        method: 'POST',
-        body: new Blob([data.slice().buffer], { type: 'application/json' }),
-        signal: abortController.signal,
-      });
-
-      // A 2xx response means the export succeeded outright
-      if (response.ok) {
-        return { status: 'success' };
-      } else if (isExportRetryable(response.status)) {
-        const retryAfter = response.headers.get('Retry-After');
-        const retryInMillis = parseRetryAfterToMills(retryAfter);
-        return { status: 'retryable', retryInMillis };
-      }
-      return {
-        status: 'failure',
-        error: new Error('Fetch request failed with non-retryable status'),
-      };
-    } catch (error) {
-      const err = error as Error;
-      // Distinguish a timeout (AbortController fired) from other fetch failures
-      if (err?.name === 'AbortError') {
-        return {
-          status: 'failure',
-          error: new Error('Fetch request timed out', { cause: err }),
-        };
-      }
-      return {
-        status: 'failure',
-        error: new Error('Fetch request errored', { cause: err }),
-      };
-    } finally {
-      clearTimeout(timeout);
-    }
-  }
-  /** No-op; the HTTP client does not hold persistent connections. */
-  shutdown(): void {
-    // intentionally left empty, nothing to do.
-  }
-}

package/src/logExporters/index.ts

@@ -1,10 +0,0 @@
-/**
- * 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/src/mock/MockAnalyticsAdapter.ts

@@ -1,178 +0,0 @@
-import { Subject, filter, type Subscription } from 'rxjs';
-
-import type { IAnalyticsAdapter } from '../adapters/AnalyticsAdapter.interface.js';
-import type { AnalyticsEvent } from '../types.js';
-
-/**
- * Selects which recorded events {@link MockAnalyticsAdapter.waitForAnalytic} or
- * {@link MockAnalyticsAdapter.getAnalytics} act on.
- *
- * - `string` — matches `event.name` exactly.
- * - `string[]` — matches if `event.name` is any of the given entries.
- * - `(event) => boolean` — arbitrary predicate over the full event.
- */
-export type AnalyticsEventMatcher<T extends AnalyticsEvent = AnalyticsEvent> =
-  | string
-  | string[]
-  | ((event: T) => boolean);
-
-/** Options accepted by {@link MockAnalyticsAdapter.waitForAnalytic}. */
-export interface WaitForAnalyticOptions {
-  /**
-   * Maximum time in milliseconds to wait for a matching event.
-   * When elapsed the returned promise rejects.
-   */
-  timeout?: number;
-  /**
-   * AbortSignal that can cancel the wait early.
-   * When aborted the returned promise rejects with the signal's reason.
-   */
-  signal?: AbortSignal;
-}
-
-/**
- * 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<T extends AnalyticsEvent = AnalyticsEvent>
-  implements IAnalyticsAdapter<T>
-{
-  #events: T[] = [];
-  #events$ = new Subject<T>();
-
-  /**
-   * 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: T): void {
-    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?: AnalyticsEventMatcher<T>): T[] {
-    // 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: AnalyticsEventMatcher<T>, options?: WaitForAnalyticOptions): Promise<T> {
-    // 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<T>((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: ReturnType<typeof setTimeout> | undefined;
-      // Declared before subscribing so `complete` can reach it even when the
-      // adapter is already disposed and fires synchronously during `subscribe`.
-      let sub: Subscription | undefined;
-
-      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: T, matcher: AnalyticsEventMatcher<T>): boolean {
-    // 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();
-  }
-}

package/src/mock/index.ts

@@ -1,29 +0,0 @@
-/**
- * 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,
-  type AnalyticsEventMatcher,
-  type WaitForAnalyticOptions,
-} from './MockAnalyticsAdapter.js';

package/src/module.ts

@@ -1,59 +0,0 @@
-import type { Module } from '@equinor/fusion-framework-module';
-import type { IAnalyticsConfigurator } from './AnalyticsConfigurator.interface.js';
-import type { IAnalyticsProvider } from './AnalyticsProvider.interface.js';
-import { AnalyticsConfigurator } from './AnalyticsConfigurator.js';
-import { AnalyticsProvider } from './AnalyticsProvider.js';
-
-/**
- * Represents the Analytics module type within the Fusion Framework module system.
- *
- * @remarks
- * 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.
- *
- * @see {@link IAnalyticsProvider} for the runtime provider interface.
- * @see {@link IAnalyticsConfigurator} for configuration-time setup.
- */
-export type AnalyticsModule = Module<
-  'analytics',
-  IAnalyticsProvider,
-  IAnalyticsConfigurator,
-  [AnalyticsModule]
->;
-
-/**
- * Analytics module definition for the Fusion Framework.
- *
- * @remarks
- * 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.
- *
- * - `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',
-  configure: () => new AnalyticsConfigurator(),
-  initialize: async (args): Promise<IAnalyticsProvider> => {
-    const config = await (args.config as AnalyticsConfigurator).createConfigAsync(args);
-
-    const provider = new AnalyticsProvider(config);
-    await provider.initialize();
-
-    return provider;
-  },
-} satisfies AnalyticsModule;
-
-export default module;
-
-declare module '@equinor/fusion-framework-module' {
-  interface Modules {
-    analytics: AnalyticsModule;
-  }
-}