@equinor/fusion-framework 7.3.20 → 7.4.0

package/dist/types/FrameworkConfigurator.d.ts

@@ -2,7 +2,8 @@ import { type AnyModule, ModulesConfigurator } from '@equinor/fusion-framework-m
 import { configureHttpClient, configureHttp, type HttpClientOptions } from '@equinor/fusion-framework-module-http';
 import type { HttpClientMsal } from '@equinor/fusion-framework-module-http/client';
 import { type AuthConfigFn } from '@equinor/fusion-framework-module-msal';
-import type { FusionModules } from './types';
+import { enableTelemetry } from '@equinor/fusion-framework-module-telemetry';
+import type { FusionModules } from './types.js';
 import type { AuthClientConfig } from '@equinor/fusion-framework-module-msal/v2';
 /**
  * Module configurator for Framework modules
@@ -10,12 +11,162 @@ import type { AuthClientConfig } from '@equinor/fusion-framework-module-msal/v2'
  * @template TRef - usually undefined, optional references
  */
 export declare class FrameworkConfigurator<TModules extends Array<AnyModule> = [], TRef = any> extends ModulesConfigurator<FusionModules<TModules>, TRef> {
+    /**
+     * Creates a new FrameworkConfigurator instance with default telemetry configuration.
+     *
+     * Initializes the framework with core modules (event, auth, http, service discovery,
+     * services, context, and telemetry) and sets up default telemetry that includes
+     * framework version metadata and 'framework' scope for all telemetry events.
+     *
+     * @example
+     * ```typescript
+     * const configurator = new FrameworkConfigurator();
+     * // Now ready to configure additional modules
+     * ```
+     */
     constructor();
+    /**
+     * Configures the global HTTP module settings such as base URLs, default headers,
+     * request/response interceptors, and timeout settings.
+     *
+     * This affects all HTTP requests made through the framework's HTTP module.
+     * Use this for application-wide HTTP configuration.
+     *
+     * @param args - HTTP module configuration arguments (same as configureHttp function)
+     *
+     * @example
+     * ```typescript
+     * configurator.configureHttp({
+     *   baseUri: 'https://api.example.com',
+     *   defaultHeaders: { 'X-App-Version': '1.0.0' }
+     * });
+     * ```
+     */
     configureHttp(...args: Parameters<typeof configureHttp>): void;
+    /**
+     * Configures a named HTTP client instance with specific settings.
+     *
+     * Unlike configureHttp which sets global HTTP settings, this creates a named client
+     * that can have its own base URL, headers, interceptors, and other HTTP-specific
+     * configuration. Useful for connecting to different APIs or services with different requirements.
+     *
+     * @param args - HTTP client configuration arguments: [name, clientOptions]
+     *               where name is a string identifier and clientOptions contains HTTP settings
+     *
+     * @example
+     * ```typescript
+     * // Configure a client for external API
+     * configurator.configureHttpClient('external-api', {
+     *   baseUri: 'https://external-api.com',
+     *   defaultHeaders: { 'Authorization': 'Bearer token' }
+     * });
+     *
+     * // Configure a client for internal services
+     * configurator.configureHttpClient('internal', {
+     *   baseUri: 'https://internal.company.com',
+     *   timeout: 10000
+     * });
+     * ```
+     */
     configureHttpClient(...args: Parameters<typeof configureHttpClient>): void;
+    /**
+     * Configures Microsoft Authentication Library (MSAL) authentication for the framework.
+     *
+     * This sets up OAuth 2.0 / OpenID Connect authentication using Azure AD or other
+     * MSAL-compatible identity providers. The authentication module will handle token
+     * acquisition, refresh, and user session management.
+     *
+     * @param cb_or_config - Authentication configuration. Can be either:
+     *                      - A callback function that receives an auth builder for advanced configuration
+     *                      - A client configuration object with MSAL settings
+     * @param requiresAuth - Whether the application requires authentication to function.
+     *                      When true (default), unauthenticated users cannot access the app.
+     *                      When false, authentication is optional but available when needed.
+     *
+     * @example
+     * ```typescript
+     * // Simple configuration with client config object
+     * configurator.configureMsal({
+     *   clientId: 'your-client-id',
+     *   authority: 'https://login.microsoftonline.com/your-tenant-id'
+     * });
+     *
+     * // Advanced configuration with callback
+     * configurator.configureMsal((builder) => {
+     *   builder.setClientConfig({
+     *     clientId: 'your-client-id',
+     *     authority: 'https://login.microsoftonline.com/your-tenant-id'
+     *   });
+     *   builder.setScopes(['User.Read', 'api://your-api/scope']);
+     *   builder.setRequiresAuth(true);
+     * });
+     *
+     * // Optional authentication
+     * configurator.configureMsal(config, false);
+     * ```
+     */
     configureMsal(cb_or_config: AuthConfigFn | AuthClientConfig, requiresAuth?: boolean): void;
+    /**
+     * Configures the service discovery module to automatically find and connect to services.
+     *
+     * Service discovery allows the framework to dynamically locate microservices and APIs
+     * at runtime rather than hardcoding their URLs. This is essential in distributed systems
+     * where services may be deployed across multiple environments or scaled dynamically.
+     *
+     * @param args - Configuration object for service discovery
+     * @param args.client - HTTP client configuration used to communicate with the
+     *                     service discovery registry. Typically includes base URL,
+     *                     authentication, and timeout settings.
+     *
+     * @example
+     * ```typescript
+     * configurator.configureServiceDiscovery({
+     *   client: {
+     *     baseUri: 'https://service-registry.company.com',
+     *     defaultHeaders: { 'Authorization': 'Bearer token' },
+     *     timeout: 5000
+     *   }
+     * });
+     * ```
+     */
     configureServiceDiscovery(args: {
         client: HttpClientOptions<HttpClientMsal>;
     }): void;
+    /**
+     * Configures application telemetry and observability settings.
+     *
+     * Telemetry enables tracking of application usage, performance metrics, errors,
+     * and custom events. This helps with monitoring, debugging, and understanding
+     * how your application is being used. The framework comes with default telemetry
+     * that includes framework version and scope information.
+     *
+     * @param cb - Configuration callback function that receives a telemetry builder.
+     *             Use this to customize telemetry settings like event scopes, metadata,
+     *             sampling rates, and custom instrumentation.
+     *
+     * @example
+     * ```typescript
+     * configurator.configureTelemetry((builder) => {
+     *   // Add custom metadata to all telemetry events
+     *   builder.setMetadata({
+     *     application: 'my-app',
+     *     environment: 'production',
+     *     version: '1.2.3'
+     *   });
+     *
+     *   // Set custom scopes for filtering events
+     *   builder.setDefaultScope(['app', 'performance']);
+     *
+     *   // Configure sampling (only send 10% of events)
+     *   builder.setSamplingRate(0.1);
+     *
+     *   // Add custom instrumentation
+     *   builder.addInstrumentation('custom-operation', (context) => {
+     *     // Track custom metrics
+     *   });
+     * });
+     * ```
+     */
+    configureTelemetry(cb: Parameters<typeof enableTelemetry>[1]): void;
 }
 export default FrameworkConfigurator;

package/dist/types/__tests__/FrameworkConfigurator.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/index.d.ts

@@ -1,5 +1,5 @@
 import type { FrameworkEvent, FrameworkEventInit } from '@equinor/fusion-framework-module-event';
-import type { Fusion } from './types';
+import type { Fusion } from './types.js';
 declare module '@equinor/fusion-framework-module-event' {
     interface FrameworkEventMap {
         onFrameworkLoaded: FrameworkEvent<FrameworkEventInit<Fusion>>;

package/dist/types/init.d.ts

@@ -1,6 +1,6 @@
 import type { AnyModule } from '@equinor/fusion-framework-module';
-import type { FrameworkConfigurator } from './FrameworkConfigurator';
-import type { Fusion } from './types';
+import type { FrameworkConfigurator } from './FrameworkConfigurator.js';
+import type { Fusion } from './types.js';
 /**
  *
  * @template TModules addition modules

package/dist/types/types.d.ts

@@ -6,6 +6,7 @@ import type { HttpModule } from '@equinor/fusion-framework-module-http';
 import type { MsalModule } from '@equinor/fusion-framework-module-msal';
 import type { ServiceDiscoveryModule } from '@equinor/fusion-framework-module-service-discovery';
 import type { ServicesModule } from '@equinor/fusion-framework-module-services';
+import type { TelemetryModule } from '@equinor/fusion-framework-module-telemetry';
 /**
  * interface of the modules provided by Fusion Framework
  */
@@ -15,7 +16,8 @@ export type FusionModules<TModules extends Array<AnyModule> | unknown = unknown>
     HttpModule,
     MsalModule,
     ServicesModule,
-    ServiceDiscoveryModule
+    ServiceDiscoveryModule,
+    TelemetryModule
 ]>;
 /**
  * Blueprint of instance of framework modules

package/dist/types/version.d.ts

@@ -1 +1 @@
-export declare const version = "7.3.20";
+export declare const version = "7.4.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/fusion-framework",
-  "version": "7.3.20",
+  "version": "7.4.0",
   "description": "",
   "main": "dist/esm/index.js",
   "types": "dist/types/index.d.ts",
@@ -32,18 +32,21 @@
   },
   "dependencies": {
     "rxjs": "^7.8.1",
-    "@equinor/fusion-framework-module-context": "^7.0.0",
-    "@equinor/fusion-framework-module": "^5.0.2",
-    "@equinor/fusion-framework-module-msal": "^5.0.1",
+    "@equinor/fusion-framework-module": "^5.0.3",
+    "@equinor/fusion-framework-module-context": "^7.0.1",
     "@equinor/fusion-framework-module-event": "^4.3.7",
-    "@equinor/fusion-framework-module-http": "^7.0.1",
-    "@equinor/fusion-framework-module-service-discovery": "^9.0.1",
-    "@equinor/fusion-framework-module-services": "^7.1.2"
+    "@equinor/fusion-framework-module-http": "^7.0.2",
+    "@equinor/fusion-framework-module-msal": "^5.0.1",
+    "@equinor/fusion-framework-module-service-discovery": "^9.0.2",
+    "@equinor/fusion-framework-module-services": "^7.1.2",
+    "@equinor/fusion-framework-module-telemetry": "^4.2.0"
   },
   "devDependencies": {
-    "typescript": "^5.8.2"
+    "typescript": "^5.8.2",
+    "vitest": "^3.2.4"
   },
   "scripts": {
-    "build": "tsc -b"
+    "build": "tsc -b",
+    "test": "vitest --run"
   }
 }

package/src/FrameworkConfigurator.ts

@@ -1,7 +1,7 @@
 import {
   type AnyModule,
-  ModuleConsoleLogger,
   ModulesConfigurator,
+  type ModuleEvent,
 } from '@equinor/fusion-framework-module';
 
 import event from '@equinor/fusion-framework-module-event';
@@ -19,9 +19,13 @@ import context from '@equinor/fusion-framework-module-context';
 
 import disco from '@equinor/fusion-framework-module-service-discovery';
 import services from '@equinor/fusion-framework-module-services';
+import telemetry, { enableTelemetry } from '@equinor/fusion-framework-module-telemetry';
 
-import type { FusionModules } from './types';
+import type { FusionModules } from './types.js';
 import type { AuthClientConfig } from '@equinor/fusion-framework-module-msal/v2';
+import { version } from './version.js';
+import { map } from 'rxjs/operators';
+import type { Observable } from 'rxjs';
 
 /**
  * Module configurator for Framework modules
@@ -33,19 +37,124 @@ export class FrameworkConfigurator<
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   TRef = any,
 > extends ModulesConfigurator<FusionModules<TModules>, TRef> {
+  /**
+   * Creates a new FrameworkConfigurator instance with default telemetry configuration.
+   *
+   * Initializes the framework with core modules (event, auth, http, service discovery,
+   * services, context, and telemetry) and sets up default telemetry that includes
+   * framework version metadata and 'framework' scope for all telemetry events.
+   *
+   * @example
+   * ```typescript
+   * const configurator = new FrameworkConfigurator();
+   * // Now ready to configure additional modules
+   * ```
+   */
   constructor() {
-    super([event, auth, http, disco, services, context]);
-    this.logger = new ModuleConsoleLogger('FrameworkConfigurator');
+    super([event, auth, http, disco, services, context, telemetry]);
+
+    // default configuration
+    enableTelemetry(this, {
+      configure: (builder) => {
+        builder.setMetadata({
+          fusion: {
+            type: 'framework-telemetry',
+            framework: {
+              version,
+            },
+          },
+        });
+        builder.setDefaultScope(['framework']);
+      },
+    });
   }
 
+  /**
+   * Configures the global HTTP module settings such as base URLs, default headers,
+   * request/response interceptors, and timeout settings.
+   *
+   * This affects all HTTP requests made through the framework's HTTP module.
+   * Use this for application-wide HTTP configuration.
+   *
+   * @param args - HTTP module configuration arguments (same as configureHttp function)
+   *
+   * @example
+   * ```typescript
+   * configurator.configureHttp({
+   *   baseUri: 'https://api.example.com',
+   *   defaultHeaders: { 'X-App-Version': '1.0.0' }
+   * });
+   * ```
+   */
   public configureHttp(...args: Parameters<typeof configureHttp>) {
     this.addConfig(configureHttp(...args));
   }
 
+  /**
+   * Configures a named HTTP client instance with specific settings.
+   *
+   * Unlike configureHttp which sets global HTTP settings, this creates a named client
+   * that can have its own base URL, headers, interceptors, and other HTTP-specific
+   * configuration. Useful for connecting to different APIs or services with different requirements.
+   *
+   * @param args - HTTP client configuration arguments: [name, clientOptions]
+   *               where name is a string identifier and clientOptions contains HTTP settings
+   *
+   * @example
+   * ```typescript
+   * // Configure a client for external API
+   * configurator.configureHttpClient('external-api', {
+   *   baseUri: 'https://external-api.com',
+   *   defaultHeaders: { 'Authorization': 'Bearer token' }
+   * });
+   *
+   * // Configure a client for internal services
+   * configurator.configureHttpClient('internal', {
+   *   baseUri: 'https://internal.company.com',
+   *   timeout: 10000
+   * });
+   * ```
+   */
   public configureHttpClient(...args: Parameters<typeof configureHttpClient>) {
     this.addConfig(configureHttpClient(...args));
   }
 
+  /**
+   * Configures Microsoft Authentication Library (MSAL) authentication for the framework.
+   *
+   * This sets up OAuth 2.0 / OpenID Connect authentication using Azure AD or other
+   * MSAL-compatible identity providers. The authentication module will handle token
+   * acquisition, refresh, and user session management.
+   *
+   * @param cb_or_config - Authentication configuration. Can be either:
+   *                      - A callback function that receives an auth builder for advanced configuration
+   *                      - A client configuration object with MSAL settings
+   * @param requiresAuth - Whether the application requires authentication to function.
+   *                      When true (default), unauthenticated users cannot access the app.
+   *                      When false, authentication is optional but available when needed.
+   *
+   * @example
+   * ```typescript
+   * // Simple configuration with client config object
+   * configurator.configureMsal({
+   *   clientId: 'your-client-id',
+   *   authority: 'https://login.microsoftonline.com/your-tenant-id'
+   * });
+   *
+   * // Advanced configuration with callback
+   * configurator.configureMsal((builder) => {
+   *   builder.setClientConfig({
+   *     clientId: 'your-client-id',
+   *     authority: 'https://login.microsoftonline.com/your-tenant-id'
+   *   });
+   *   builder.setScopes(['User.Read', 'api://your-api/scope']);
+   *   builder.setRequiresAuth(true);
+   * });
+   *
+   * // Optional authentication
+   * configurator.configureMsal(config, false);
+   * ```
+   */
   public configureMsal(cb_or_config: AuthConfigFn | AuthClientConfig, requiresAuth = true) {
     this.addConfig({
       module: auth,
@@ -63,9 +172,71 @@ export class FrameworkConfigurator<
     });
   }
 
+  /**
+   * Configures the service discovery module to automatically find and connect to services.
+   *
+   * Service discovery allows the framework to dynamically locate microservices and APIs
+   * at runtime rather than hardcoding their URLs. This is essential in distributed systems
+   * where services may be deployed across multiple environments or scaled dynamically.
+   *
+   * @param args - Configuration object for service discovery
+   * @param args.client - HTTP client configuration used to communicate with the
+   *                     service discovery registry. Typically includes base URL,
+   *                     authentication, and timeout settings.
+   *
+   * @example
+   * ```typescript
+   * configurator.configureServiceDiscovery({
+   *   client: {
+   *     baseUri: 'https://service-registry.company.com',
+   *     defaultHeaders: { 'Authorization': 'Bearer token' },
+   *     timeout: 5000
+   *   }
+   * });
+   * ```
+   */
   public configureServiceDiscovery(args: { client: HttpClientOptions<HttpClientMsal> }) {
     this.configureHttpClient('service_discovery', args.client);
   }
+
+  /**
+   * Configures application telemetry and observability settings.
+   *
+   * Telemetry enables tracking of application usage, performance metrics, errors,
+   * and custom events. This helps with monitoring, debugging, and understanding
+   * how your application is being used. The framework comes with default telemetry
+   * that includes framework version and scope information.
+   *
+   * @param cb - Configuration callback function that receives a telemetry builder.
+   *             Use this to customize telemetry settings like event scopes, metadata,
+   *             sampling rates, and custom instrumentation.
+   *
+   * @example
+   * ```typescript
+   * configurator.configureTelemetry((builder) => {
+   *   // Add custom metadata to all telemetry events
+   *   builder.setMetadata({
+   *     application: 'my-app',
+   *     environment: 'production',
+   *     version: '1.2.3'
+   *   });
+   *
+   *   // Set custom scopes for filtering events
+   *   builder.setDefaultScope(['app', 'performance']);
+   *
+   *   // Configure sampling (only send 10% of events)
+   *   builder.setSamplingRate(0.1);
+   *
+   *   // Add custom instrumentation
+   *   builder.addInstrumentation('custom-operation', (context) => {
+   *     // Track custom metrics
+   *   });
+   * });
+   * ```
+   */
+  public configureTelemetry(cb: Parameters<typeof enableTelemetry>[1]): void {
+    enableTelemetry(this, cb);
+  }
 }
 
 export default FrameworkConfigurator;

package/src/__tests__/FrameworkConfigurator.test.ts

@@ -0,0 +1,35 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { firstValueFrom, take } from 'rxjs';
+import { FrameworkConfigurator } from '../FrameworkConfigurator.js';
+import type { AnyModule } from '@equinor/fusion-framework-module';
+import { SemanticVersion } from '@equinor/fusion-framework-module';
+
+describe('FrameworkConfigurator', () => {
+  let configurator: FrameworkConfigurator;
+
+  // Create a mock module for testing
+  const createMockModule = (name: string, version = '1.0.0'): AnyModule => ({
+    name,
+    version: new SemanticVersion(version),
+    initialize: () => ({ mockInstance: true }),
+  });
+
+  beforeEach(() => {
+    configurator = new FrameworkConfigurator();
+  });
+
+  describe('Event Name Prefixing', () => {
+    it('should prefix event names with "FrameworkConfigurator::"', async () => {
+      // Trigger event by adding a config
+      configurator.addConfig({
+        module: createMockModule('test', '1.0.0'),
+        configure: () => {},
+      });
+
+      // Wait for the first event to be emitted
+      const event = await firstValueFrom(configurator.event$.pipe(take(1)));
+
+      expect(event.name).toMatch(/^FrameworkConfigurator::/);
+    });
+  });
+});

package/src/index.ts

@@ -1,5 +1,5 @@
 import type { FrameworkEvent, FrameworkEventInit } from '@equinor/fusion-framework-module-event';
-import type { Fusion } from './types';
+import type { Fusion } from './types.js';
 
 declare module '@equinor/fusion-framework-module-event' {
   interface FrameworkEventMap {

package/src/init.ts

@@ -1,7 +1,7 @@
 import type { AnyModule } from '@equinor/fusion-framework-module';
 
-import type { FrameworkConfigurator } from './FrameworkConfigurator';
-import type { Fusion, FusionModules } from './types';
+import type { FrameworkConfigurator } from './FrameworkConfigurator.js';
+import type { Fusion, FusionModules } from './types.js';
 
 /**
  *

package/src/types.ts

@@ -7,13 +7,22 @@ import type { HttpModule } from '@equinor/fusion-framework-module-http';
 import type { MsalModule } from '@equinor/fusion-framework-module-msal';
 import type { ServiceDiscoveryModule } from '@equinor/fusion-framework-module-service-discovery';
 import type { ServicesModule } from '@equinor/fusion-framework-module-services';
+import type { TelemetryModule } from '@equinor/fusion-framework-module-telemetry';
 
 /**
  * interface of the modules provided by Fusion Framework
  */
 export type FusionModules<TModules extends Array<AnyModule> | unknown = unknown> = CombinedModules<
   TModules,
-  [ContextModule, EventModule, HttpModule, MsalModule, ServicesModule, ServiceDiscoveryModule]
+  [
+    ContextModule,
+    EventModule,
+    HttpModule,
+    MsalModule,
+    ServicesModule,
+    ServiceDiscoveryModule,
+    TelemetryModule,
+  ]
 >;
 
 /**

package/src/version.ts

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

package/tsconfig.json

@@ -12,6 +12,9 @@
     {
       "path": "../modules/event"
     },
+    {
+      "path": "../modules/telemetry"
+    },
     {
       "path": "../modules/http"
     },

package/vitest.config.ts

@@ -0,0 +1,10 @@
+import { defineProject } from 'vitest/config';
+
+import { name, version } from './package.json';
+
+export default defineProject({
+  test: {
+    include: ['src/__tests__/**'],
+    name: `${name}@${version}`,
+  },
+});