@equinor/fusion-framework-module-analytics 0.1.1

package/src/collectors/utils/extractContextMetadata.ts

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+import type { ContextItem } from '@equinor/fusion-framework-module-context';
+
+// Schema representing an object with data points of a Fusion context.
+// Used to parse an object with context data.
+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();
+
+export type ContextItemType = z.infer<typeof contextSchema>;
+
+export const extractContextMetadata = (context: ContextItem): z.input<typeof contextSchema> => {
+  return {
+    id: context.id,
+    externalId: context.externalId,
+    title: context.title,
+    type: context.type.id,
+    source: context.source,
+  };
+};

package/src/enable-analytics.ts

@@ -0,0 +1,27 @@
+import type { IModulesConfigurator } from '@equinor/fusion-framework-module';
+
+import { module } from './module.js';
+import type { IAnalyticsConfigurator } from './AnalyticsConfigurator.interface.js';
+
+type AnalyticsBuilderCallback = (builder: IAnalyticsConfigurator) => void | Promise<void>;
+
+/**
+ * Enables analytics for agiven 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.
+ */
+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) => {
+      if (callback) {
+        await Promise.resolve(callback(builder));
+      }
+    },
+  });
+};

package/src/index.ts

@@ -0,0 +1,11 @@
+export { module as analyticsModule, AnalyticsModule } from './module.js';
+
+export { AnalyticsEvent } 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

@@ -0,0 +1,41 @@
+import type { LogRecordExporter, ReadableLogRecord } from '@opentelemetry/sdk-logs';
+
+import { JsonLogsSerializer } from '@opentelemetry/otlp-transformer';
+
+import {
+  createOtlpNetworkExportDelegate,
+  OTLPExporterBase,
+  type OtlpSharedConfiguration,
+} from '@opentelemetry/otlp-exporter-base';
+
+import type { IHttpClient } from '@equinor/fusion-framework-module-http';
+import { HttpClientExporterTransport } from './HttpClientExporterTransport.js';
+
+// The shared default configuration needed for the OTLPNetworkExportDelegate
+function getSharedConfigurationDefaults(): OtlpSharedConfiguration {
+  return {
+    timeoutMillis: 10000,
+    concurrencyLimit: 30,
+    compression: 'none',
+  };
+}
+
+/**
+ * A log exporter extending OTLPExporterBase but substitute the normal transport
+ * with a HttpClientExporterTransport. This will use the provided httpClient to
+ * emit the event.
+ */
+export class FusionOTLPLogExporter
+  extends OTLPExporterBase<ReadableLogRecord[]>
+  implements LogRecordExporter
+{
+  constructor(httpClient: IHttpClient) {
+    super(
+      createOtlpNetworkExportDelegate(
+        getSharedConfigurationDefaults(),
+        JsonLogsSerializer,
+        new HttpClientExporterTransport(httpClient),
+      ),
+    );
+  }
+}

package/src/logExporters/fusionOTLPLogExporter/HttpClientExporterTransport.ts

@@ -0,0 +1,89 @@
+import type { IExporterTransport, ExportResponse } from '@opentelemetry/otlp-exporter-base';
+
+import type { IHttpClient } from '@equinor/fusion-framework-module-http';
+
+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);
+}
+
+// Parse the `Retry-After` header and return when the service will allow a retry.
+function parseRetryAfterToMills(retryAfter?: string | undefined | null): number | undefined {
+  if (retryAfter == null) {
+    return undefined;
+  }
+
+  const seconds = Number.parseInt(retryAfter, 10);
+  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();
+
+  if (delay >= 0) {
+    return delay;
+  }
+  return 0;
+}
+
+/**
+ * A Exporter Transport to POST events to provided path using the provided httpClient
+ */
+export class HttpClientExporterTransport implements IExporterTransport {
+  constructor(
+    private httpClient: IHttpClient,
+    private path: string = '/v1/logs',
+  ) {}
+
+  // Will send data with the httpClient.
+  // If the service responds with a non 2** statusCode, we check if it is
+  // retryable.
+  // The timeoutMillis determines when to abort if the service has not yet
+  // responded.
+  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,
+      });
+
+      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;
+      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);
+    }
+  }
+  shutdown(): void {
+    // intentionally left empty, nothing to do.
+  }
+}

package/src/logExporters/index.ts

@@ -0,0 +1,2 @@
+export { FusionOTLPLogExporter } from './fusionOTLPLogExporter/FusionOTLPLogExporter.js';
+export { OTLPLogExporter } from '@opentelemetry/exporter-logs-otlp-http';

package/src/module.ts

@@ -0,0 +1,59 @@
+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';
+
+/**
+ * Representes the Analytics module within the framework.
+ *
+ * @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`).
+ *
+ * @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.
+ */
+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 a analytics provider.
+ *
+ * @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.
+ */
+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;
+  }
+}

package/src/types.ts

@@ -0,0 +1,29 @@
+export type AnyValueScalar = string | number | boolean;
+export type AnyValueArray = Array<AnyValue>;
+
+/**
+ * AnyValueMap is a map from string to AnyValue (attribute value or a nested map)
+ */
+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
+ */
+
+export type AnyValue = AnyValueScalar | Uint8Array | AnyValueArray | AnyValueMap | null | undefined;
+
+export type AnalyticsEvent<
+  TValue extends AnyValue = AnyValue,
+  TAttr extends AnyValueMap = AnyValueMap,
+> = {
+  name: string;
+  value: TValue;
+  attributes?: TAttr;
+};

package/src/version.ts

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

package/tsconfig.json

@@ -0,0 +1,29 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "dist/esm",
+    "rootDir": "src",
+    "declarationDir": "./dist/types"
+  },
+  "references": [
+    {
+      "path": "../module"
+    },
+    {
+      "path": "../event"
+    },
+    {
+      "path": "../app"
+    },
+    {
+      "path": "../context"
+    },
+    {
+      "path": "../http"
+    }
+  ],
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "lib"]
+}