@equinor/fusion-framework-module-analytics 3.0.1 → 3.0.3

package/dist/types/AnalyticsConfigurator.d.ts

@@ -22,6 +22,9 @@ import type { AnalyticsEvent } from './types.js';
  */
 export declare class AnalyticsConfigurator extends BaseConfigBuilder<AnalyticsConfig> implements IAnalyticsConfigurator {
     #private;
+    /**
+     * Registers the async resolvers for `collectors` and `adapters` config keys.
+     */
     constructor();
     /**
      * Registers an analytics collector factory.

package/dist/types/AnalyticsProvider.d.ts

@@ -23,6 +23,9 @@ import { type ObservableInput, Subscription } from 'rxjs';
  */
 export declare class AnalyticsProvider extends BaseModuleProvider<AnalyticsConfig> implements IAnalyticsProvider {
     #private;
+    /**
+     * @param config - Resolved analytics module configuration, including collectors and adapters.
+     */
     constructor(config: AnalyticsConfig);
     /**
      * Initialises all adapters and collectors, then wires collector output into

package/dist/types/adapters/ConsoleAnalyticsAdapter.d.ts

@@ -17,7 +17,13 @@ import type { AnalyticsEvent } from '../types.js';
  * ```
  */
 export declare class ConsoleAnalyticsAdapter<T extends AnalyticsEvent = AnalyticsEvent> implements IAnalyticsAdapter {
-    /** Logs the event to the console. */
+    /**
+     * Logs the event to the console.
+     *
+     * @param event - The analytics event to log.
+     * @returns Resolves once the event has been logged.
+     */
     registerAnalytic(event: T): Promise<void> | void;
+    /** No teardown is required for this adapter. */
     [Symbol.dispose](): void;
 }

package/dist/types/adapters/FusionAnalyticsAdapter.d.ts

@@ -41,7 +41,12 @@ export declare class FusionAnalyticsAdapter<T extends AnalyticsEvent = Analytics
         portalId: string;
         logExporter: OTLPExporterBase<ReadableLogRecord[]>;
     });
-    /** Maps an analytics event to an OTLP `LogRecord` and emits it via the logger. */
+    /**
+     * Maps an analytics event to an OTLP `LogRecord` and emits it via the logger.
+     *
+     * @param event - The analytics event to map and emit.
+     * @returns Resolves once the event has been emitted to the logger.
+     */
     registerAnalytic(event: T): Promise<void> | void;
     /** Shuts down the log exporter and logger provider, flushing remaining records. */
     [Symbol.dispose](): void;

package/dist/types/collectors/AppLoadedCollector.d.ts

@@ -1,6 +1,6 @@
-import { BaseCollector } from './BaseCollector.js';
-import { type AppItemType } from './utils/extractAppMetadata.js';
-import { type ContextItemType } from './utils/extractContextMetadata.js';
+import { BaseCollector } from './create-schema.js';
+import { type AppItemType } from './utils/app-schema.js';
+import { type ContextItemType } from './utils/context-schema.js';
 import type { IAnalyticsCollector } from './AnalyticsCollector.interface.js';
 import type { AppModuleProvider } from '@equinor/fusion-framework-module-app';
 import type { IEventModuleProvider } from '@equinor/fusion-framework-module-event';
@@ -32,6 +32,12 @@ export declare class AppLoadedCollector extends BaseCollector<AppItemType, {
      * @param appProvider - Fusion app module provider for fallback manifest data.
      */
     constructor(eventProvider: IEventModuleProvider, appProvider: AppModuleProvider);
+    /**
+     * Builds an observable that emits an analytics event whenever the app-loaded
+     * event fires, falling back to `appProvider` for manifest data when needed.
+     *
+     * @returns An observable input emitting the app-loaded event's value and attributes.
+     */
     _initialize(): ObservableInput<{
         value: AppItemType;
         attributes: {

package/dist/types/collectors/AppSelectedCollector.d.ts

@@ -1,7 +1,7 @@
 import { type ObservableInput } from 'rxjs';
 import type { IAnalyticsCollector } from './AnalyticsCollector.interface.js';
-import { BaseCollector } from './BaseCollector.js';
-import { type AppKeyType } from './utils/extractAppMetadata.js';
+import { BaseCollector } from './create-schema.js';
+import { type AppKeyType } from './utils/app-key-schema.js';
 import type { AppModuleProvider } from '@equinor/fusion-framework-module-app';
 /**
  * Collector that emits an analytics event whenever the active Fusion application changes.
@@ -26,6 +26,12 @@ export declare class AppSelectedCollector extends BaseCollector<AppKeyType, {
      * @param appProvider - Fusion app module provider to observe.
      */
     constructor(appProvider: AppModuleProvider);
+    /**
+     * Builds an observable that emits an analytics event each time the selected
+     * app changes, including the previous app's key metadata.
+     *
+     * @returns An observable input emitting the newly selected app's value and attributes.
+     */
     _initialize(): ObservableInput<{
         value: AppKeyType;
         attributes: {

package/dist/types/collectors/ContextSelectedCollector.d.ts

@@ -2,8 +2,8 @@ import { type ObservableInput } from 'rxjs';
 import type { IAnalyticsCollector } from './AnalyticsCollector.interface.js';
 import type { IContextProvider } from '@equinor/fusion-framework-module-context';
 import type { AppModuleProvider } from '@equinor/fusion-framework-module-app';
-import { BaseCollector } from './BaseCollector.js';
-import { type ContextItemType } from './utils/extractContextMetadata.js';
+import { BaseCollector } from './create-schema.js';
+import { type ContextItemType } from './utils/context-schema.js';
 /**
  * Collector that emits an analytics event whenever the active Fusion context changes.
  *
@@ -31,6 +31,12 @@ export declare class ContextSelectedCollector extends BaseCollector<ContextItemT
      * @param appProvider - Fusion app module provider for the current app key.
      */
     constructor(contextProvider: IContextProvider, appProvider: AppModuleProvider);
+    /**
+     * Builds an observable that emits an analytics event each time the selected
+     * context changes, including the previous context and current app key.
+     *
+     * @returns An observable input emitting the newly selected context's value and attributes.
+     */
     _initialize(): ObservableInput<{
         value: ContextItemType;
         attributes: {

package/dist/types/collectors/{BaseCollector.d.ts → create-schema.d.ts}

@@ -70,6 +70,8 @@ export declare abstract class BaseCollector<TValue extends AnyValue, TAttr exten
      * Subscribes to the source returned by {@link BaseCollector._initialize},
      * validates each emission with the Zod schema, and publishes through the
      * internal subject.
+     *
+     * @returns Resolves once the source has been subscribed to.
      */
     initialize(): Promise<void> | void;
     /**

package/dist/types/collectors/utils/app-key-schema.d.ts

@@ -0,0 +1,12 @@
+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 declare const appKeySchema: z.ZodNullable<z.ZodOptional<z.ZodObject<{
+    appKey: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>>;
+/** Inferred type from {@link appKeySchema}. */
+export type AppKeyType = z.infer<typeof appKeySchema>;

package/dist/types/collectors/utils/app-schema.d.ts

@@ -0,0 +1,18 @@
+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 declare const appSchema: z.ZodOptional<z.ZodObject<{
+    appKey: z.ZodString;
+    displayName: z.ZodString;
+    type: z.ZodString;
+    categoryName: z.ZodOptional<z.ZodString>;
+    buildVersion: z.ZodOptional<z.ZodString>;
+    buildTag: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+}, z.core.$strip>>;
+/** Inferred type from {@link appSchema}. */
+export type AppItemType = z.infer<typeof appSchema>;

package/dist/types/collectors/utils/{extractContextMetadata.d.ts → context-schema.d.ts}

@@ -1,5 +1,4 @@
 import { z } from 'zod';
-import type { ContextItem } from '@equinor/fusion-framework-module-context';
 /**
  * Zod schema for a Fusion context metadata object.
  *
@@ -16,10 +15,3 @@ export declare const contextSchema: z.ZodNullable<z.ZodOptional<z.ZodObject<{
 }, 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/collectors/utils/extract-app-key-metadata.d.ts

@@ -0,0 +1,10 @@
+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 declare const extractAppKeyMetadata: (app: CurrentApp) => z.input<typeof appKeySchema>;

package/dist/types/collectors/utils/extract-app-metadata.d.ts

@@ -0,0 +1,10 @@
+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 declare const extractAppMetadata: (app: AppManifest) => z.input<typeof appSchema>;

package/dist/types/collectors/utils/extract-context-metadata.d.ts

@@ -0,0 +1,10 @@
+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 declare const extractContextMetadata: (context: ContextItem) => z.input<typeof contextSchema>;

package/dist/types/version.d.ts

@@ -1 +1 @@
-export declare const version = "3.0.1";
+export declare const version = "3.0.3";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/fusion-framework-module-analytics",
-  "version": "3.0.1",
+  "version": "3.0.3",
   "description": "Fusion module for collecting and exporting application analytics using OpenTelemetry standards",
   "main": "dist/esm/index.js",
   "type": "module",
@@ -39,29 +39,29 @@
     "directory": "packages/modules/analytics"
   },
   "dependencies": {
-    "@opentelemetry/api-logs": "^0.220.0",
-    "@opentelemetry/exporter-logs-otlp-http": "^0.220.0",
-    "@opentelemetry/otlp-exporter-base": "^0.220.0",
-    "@opentelemetry/otlp-transformer": "^0.220.0",
+    "@opentelemetry/api-logs": "^0.221.0",
+    "@opentelemetry/exporter-logs-otlp-http": "^0.221.0",
+    "@opentelemetry/otlp-exporter-base": "^0.221.0",
+    "@opentelemetry/otlp-transformer": "^0.221.0",
     "@opentelemetry/resources": "^2.2.0",
-    "@opentelemetry/sdk-logs": "^0.220.0",
+    "@opentelemetry/sdk-logs": "^0.221.0",
     "deepmerge": "^4.3.1",
     "rxjs": "^7.8.1",
     "uuid": "^14.0.0",
     "zod": "^4.4.3",
-    "@equinor/fusion-framework-module": "6.1.0",
-    "@equinor/fusion-framework-module-app": "8.0.2",
-    "@equinor/fusion-framework-module-context": "8.0.0",
-    "@equinor/fusion-framework-module-event": "6.0.0",
-    "@equinor/fusion-framework-module-http": "8.0.3"
+    "@equinor/fusion-framework-module-context": "8.0.1",
+    "@equinor/fusion-framework-module-app": "8.0.3",
+    "@equinor/fusion-framework-module": "6.1.1",
+    "@equinor/fusion-framework-module-event": "6.0.1",
+    "@equinor/fusion-framework-module-http": "8.0.4"
   },
   "devDependencies": {
-    "typescript": "^6.0.3",
+    "typescript": "^7.0.2",
     "vitest": "^4.1.0",
-    "@equinor/fusion-observable": "^9.1.0"
+    "@equinor/fusion-observable": "^9.1.1"
   },
   "peerDependencies": {
-    "@equinor/fusion-observable": "9.1.0"
+    "@equinor/fusion-observable": "9.1.1"
   },
   "scripts": {
     "build": "tsc -b",

package/src/AnalyticsConfigurator.ts

@@ -35,6 +35,9 @@ export class AnalyticsConfigurator
   #collectorCallbacks: Record<string, ConfigBuilderCallback<IAnalyticsCollector>> = {};
   #adapterCallbacks: Record<string, ConfigBuilderCallback<IAnalyticsAdapter>> = {};
 
+  /**
+   * Registers the async resolvers for `collectors` and `adapters` config keys.
+   */
   constructor() {
     super();
 
@@ -42,8 +45,10 @@ export class AnalyticsConfigurator
     this._set(
       'collectors',
       (args: ConfigBuilderCallbackArgs): ObservableInput<Record<string, IAnalyticsCollector>> => {
+        // Resolve each collector factory and drop any that resolve to a falsy value
         return from(Object.entries(this.#collectorCallbacks)).pipe(
           mergeMap(([identifier, collectorFn]) =>
+            // Resolve the collector's own Promise/Observable factory result
             from(collectorFn(args)).pipe(
               filter((collector): collector is IAnalyticsCollector => !!collector),
               map((collector) => [identifier, collector] as const),
@@ -66,8 +71,10 @@ export class AnalyticsConfigurator
     this._set(
       'adapters',
       (args: ConfigBuilderCallbackArgs): ObservableInput<Record<string, IAnalyticsAdapter>> => {
+        // Resolve each adapter factory and drop any that resolve to a falsy value
         return from(Object.entries(this.#adapterCallbacks)).pipe(
           mergeMap(([identifier, adapterFn]) =>
+            // Resolve the adapter's own Promise/Observable factory result
             from(adapterFn(args)).pipe(
               filter((adapter): adapter is IAnalyticsAdapter => !!adapter),
               map((adapter) => [identifier, adapter] as const),

package/src/AnalyticsProvider.ts

@@ -17,6 +17,9 @@ import type { IAnalyticsAdapter } from './adapters/AnalyticsAdapter.interface.js
  * with either `subscription.unsubscribe()` or `using` / `Symbol.dispose`.
  */
 class DisposableSubscription extends Subscription {
+  /**
+   * @param subscription - The underlying subscription to wrap with `Symbol.dispose` support.
+   */
   constructor(subscription: Subscription) {
     super(subscription.unsubscribe);
   }
@@ -52,6 +55,9 @@ export class AnalyticsProvider
   #collectors: Record<string, IAnalyticsCollector>;
   #adapters: Record<string, IAnalyticsAdapter>;
 
+  /**
+   * @param config - Resolved analytics module configuration, including collectors and adapters.
+   */
   constructor(config: AnalyticsConfig) {
     super({ version, config });
 
@@ -78,9 +84,11 @@ export class AnalyticsProvider
    * @returns A promise that resolves when all adapters and collectors are initialised.
    */
   async initialize(): Promise<void> {
+    // Kick off initialization for every collector, tolerating individual failures
     const initializedCollectors = Object.values(this.#collectors).map((collector) =>
       Promise.resolve(collector.initialize?.()),
     );
+    // Kick off initialization for every adapter, tolerating individual failures
     const initializedAdapters = Object.values(this.#adapters).map((adapters) =>
       Promise.resolve(adapters.initialize?.()),
     );
@@ -88,6 +96,7 @@ export class AnalyticsProvider
     await Promise.allSettled(initializedCollectors);
     await Promise.allSettled(initializedAdapters);
 
+    // Forward every collector's emissions into the shared analytics subject
     for (const collector of Object.values(this.#collectors)) {
       const subscription = collector.subscribe({
         next: (event) => {
@@ -100,6 +109,7 @@ export class AnalyticsProvider
 
     const adapterSubscription = this.#analytics.subscribe({
       next: (event) => {
+        // Dispatch every emitted event to all registered adapters
         for (const adapter of Object.values(this.#adapters)) {
           adapter.registerAnalytic(event);
         }
@@ -114,7 +124,7 @@ export class AnalyticsProvider
    * @param event - The analytics event to track.
    */
   trackAnalytic(event: AnalyticsEvent): void {
-    // @TODO: Validate AnalyticsEvent includes name, value and attributes
+    // TODO(#5098): Validate AnalyticsEvent includes name, value and attributes
     this.#analytics.next(event);
   }
 
@@ -127,7 +137,7 @@ export class AnalyticsProvider
    */
   trackAnalytic$(analytic$: ObservableInput<AnalyticsEvent>): Disposable & Subscription {
     const subscription = from(analytic$)
-      // @TODO: Validate AnalyticsEvent includes name, value and attributes
+      // TODO(#5098): Validate AnalyticsEvent includes name, value and attributes
       .subscribe({
         next: (event) => {
           this.#analytics.next(event);

package/src/adapters/ConsoleAnalyticsAdapter.ts

@@ -20,11 +20,17 @@ import type { AnalyticsEvent } from '../types.js';
 export class ConsoleAnalyticsAdapter<T extends AnalyticsEvent = AnalyticsEvent>
   implements IAnalyticsAdapter
 {
-  /** Logs the event to the console. */
+  /**
+   * Logs the event to the console.
+   *
+   * @param event - The analytics event to log.
+   * @returns Resolves once the event has been logged.
+   */
   registerAnalytic(event: T): Promise<void> | void {
     console.log('Analytics::Adapter::Console', event);
   }
 
+  /** No teardown is required for this adapter. */
   [Symbol.dispose]() {
     // no-op
   }

package/src/adapters/FusionAnalyticsAdapter.ts

@@ -71,7 +71,12 @@ export class FusionAnalyticsAdapter<T extends AnalyticsEvent = AnalyticsEvent>
     this.#logger = this.#loggerProvider.getLogger('fusion');
   }
 
-  /** Maps an analytics event to an OTLP `LogRecord` and emits it via the logger. */
+  /**
+   * Maps an analytics event to an OTLP `LogRecord` and emits it via the logger.
+   *
+   * @param event - The analytics event to map and emit.
+   * @returns Resolves once the event has been emitted to the logger.
+   */
   registerAnalytic(event: T): Promise<void> | void {
     const logRecord: Partial<LogRecord> = {
       eventName: event.name,

package/src/collectors/AppLoadedCollector.ts

@@ -1,10 +1,8 @@
-import { BaseCollector, createSchema } from './BaseCollector.js';
-import { type AppItemType, appSchema, extractAppMetadata } from './utils/extractAppMetadata.js';
-import {
-  type ContextItemType,
-  contextSchema,
-  extractContextMetadata,
-} from './utils/extractContextMetadata.js';
+import { BaseCollector, createSchema } from './create-schema.js';
+import { type AppItemType, appSchema } from './utils/app-schema.js';
+import { extractAppMetadata } from './utils/extract-app-metadata.js';
+import { type ContextItemType, contextSchema } from './utils/context-schema.js';
+import { extractContextMetadata } from './utils/extract-context-metadata.js';
 import type { IAnalyticsCollector } from './AnalyticsCollector.interface.js';
 
 import type {
@@ -58,6 +56,12 @@ export class AppLoadedCollector
     this.#appProvider = appProvider;
   }
 
+  /**
+   * Builds an observable that emits an analytics event whenever the app-loaded
+   * event fires, falling back to `appProvider` for manifest data when needed.
+   *
+   * @returns An observable input emitting the app-loaded event's value and attributes.
+   */
   _initialize(): ObservableInput<{
     value: AppItemType;
     attributes: { context?: ContextItemType };

package/src/collectors/AppSelectedCollector.ts

@@ -1,11 +1,8 @@
 import { map, type ObservableInput, pairwise } from 'rxjs';
 import type { IAnalyticsCollector } from './AnalyticsCollector.interface.js';
-import { BaseCollector, createSchema } from './BaseCollector.js';
-import {
-  type AppKeyType,
-  appKeySchema,
-  extractAppKeyMetadata,
-} from './utils/extractAppMetadata.js';
+import { BaseCollector, createSchema } from './create-schema.js';
+import { type AppKeyType, appKeySchema } from './utils/app-key-schema.js';
+import { extractAppKeyMetadata } from './utils/extract-app-key-metadata.js';
 
 import type { AppModuleProvider } from '@equinor/fusion-framework-module-app';
 
@@ -43,12 +40,20 @@ export class AppSelectedCollector
     this.#appProvider = appProvider;
   }
 
+  /**
+   * Builds an observable that emits an analytics event each time the selected
+   * app changes, including the previous app's key metadata.
+   *
+   * @returns An observable input emitting the newly selected app's value and attributes.
+   */
   _initialize(): ObservableInput<{
     value: AppKeyType;
     attributes: { previous?: AppKeyType };
   }> {
+    // Pair each app-selection emission with the previously selected app
     const appSelected$ = this.#appProvider.current$.pipe(pairwise());
 
+    // Map the [previous, next] pair into the analytics event shape
     const data$ = appSelected$.pipe(
       map(([prev, next]) => {
         return {

package/src/collectors/ContextSelectedCollector.ts

@@ -3,12 +3,9 @@ import type { IAnalyticsCollector } from './AnalyticsCollector.interface.js';
 import type { IContextProvider } from '@equinor/fusion-framework-module-context';
 import type { AppModuleProvider } from '@equinor/fusion-framework-module-app';
 import { z } from 'zod';
-import { BaseCollector, createSchema } from './BaseCollector.js';
-import {
-  type ContextItemType,
-  contextSchema,
-  extractContextMetadata,
-} from './utils/extractContextMetadata.js';
+import { BaseCollector, createSchema } from './create-schema.js';
+import { type ContextItemType, contextSchema } from './utils/context-schema.js';
+import { extractContextMetadata } from './utils/extract-context-metadata.js';
 
 /** Zod schema for the `context-selected` event (value + attributes). */
 const eventSchema = createSchema(
@@ -50,10 +47,17 @@ export class ContextSelectedCollector
     this.#appProvider = appProvider;
   }
 
+  /**
+   * Builds an observable that emits an analytics event each time the selected
+   * context changes, including the previous context and current app key.
+   *
+   * @returns An observable input emitting the newly selected context's value and attributes.
+   */
   _initialize(): ObservableInput<{
     value: ContextItemType;
     attributes: { previous?: ContextItemType; appKey?: string };
   }> {
+    // Track context changes, pairing each new context with the previously selected one
     const contextSelected$ = this.#contextProvider.currentContext$.pipe(
       // Only emit when an actual change has happened.
       distinctUntilChanged((prev, curr) => prev?.id === curr?.id),
@@ -61,6 +65,7 @@ export class ContextSelectedCollector
       pairwise(),
     );
 
+    // Map the [previous, next] pair into the analytics event shape
     const data$ = contextSelected$.pipe(
       map(([prev, next]) => {
         return {

package/src/collectors/{BaseCollector.ts → create-schema.ts}

@@ -92,8 +92,11 @@ export abstract class BaseCollector<
    * Subscribes to the source returned by {@link BaseCollector._initialize},
    * validates each emission with the Zod schema, and publishes through the
    * internal subject.
+   *
+   * @returns Resolves once the source has been subscribed to.
    */
   initialize(): Promise<void> | void {
+    // Shape each emission into the named/validated event before publishing
     from(this._initialize())
       .pipe(
         map(({ value, attributes }) => {

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

@@ -0,0 +1,17 @@
+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

@@ -0,0 +1,22 @@
+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/{extractContextMetadata.ts → context-schema.ts}

@@ -1,5 +1,4 @@
 import { z } from 'zod';
-import type { ContextItem } from '@equinor/fusion-framework-module-context';
 
 /**
  * Zod schema for a Fusion context metadata object.
@@ -21,19 +20,3 @@ export const contextSchema = z
 
 /** 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 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/collectors/utils/extract-app-key-metadata.ts

@@ -0,0 +1,15 @@
+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

@@ -0,0 +1,20 @@
+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,
+  };
+};