@symbo.ls/sdk 3.1.2 → 3.2.6

package/dist/cjs/services/TrackingService.js

@@ -0,0 +1,661 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var TrackingService_exports = {};
+__export(TrackingService_exports, {
+  TrackingService: () => TrackingService
+});
+module.exports = __toCommonJS(TrackingService_exports);
+var import_BaseService = require("./BaseService.js");
+var import_environment = __toESM(require("../config/environment.js"), 1);
+const DEFAULT_MAX_QUEUE_SIZE = 100;
+const isBrowserEnvironment = () => typeof window !== "undefined";
+const DEFAULT_TRACKING_OPTIONS = {
+  // Enabled by default unless explicitly disabled via SDK options or runtime config
+  enabled: true,
+  sessionTracking: true,
+  enableTracing: true,
+  maxQueueSize: DEFAULT_MAX_QUEUE_SIZE,
+  transports: null,
+  instrumentations: null,
+  instrumentationsFactory: null,
+  webInstrumentationOptions: null,
+  globalAttributes: {},
+  transport: null,
+  user: null
+};
+const sanitizeAttributes = (value) => {
+  if (!value || typeof value !== "object") {
+    return {};
+  }
+  try {
+    return JSON.parse(JSON.stringify(value));
+  } catch (error) {
+    console.warn("[TrackingService] Failed to sanitize attributes:", error);
+    return { ...value };
+  }
+};
+class TrackingService extends import_BaseService.BaseService {
+  constructor({ context, options } = {}) {
+    super({ context, options });
+    this._faroClient = null;
+    this._queue = [];
+    this._initialized = false;
+    this._enabled = DEFAULT_TRACKING_OPTIONS.enabled;
+    this._runtimeConfig = {};
+    this._setupPromise = null;
+    this._trackingOptions = {
+      ...DEFAULT_TRACKING_OPTIONS,
+      ...(options == null ? void 0 : options.tracking) || {}
+    };
+    this._globalAttributes = sanitizeAttributes(
+      this._trackingOptions.globalAttributes || {}
+    );
+    this._trackingOptions.globalAttributes = { ...this._globalAttributes };
+  }
+  async init({ context = {}, options = {} } = {}) {
+    var _a;
+    this.updateContext(context);
+    this._trackingOptions = {
+      ...DEFAULT_TRACKING_OPTIONS,
+      ...this._trackingOptions,
+      ...((_a = this._options) == null ? void 0 : _a.tracking) || {},
+      ...options.tracking || {}
+    };
+    this._globalAttributes = sanitizeAttributes(
+      this._trackingOptions.globalAttributes || {}
+    );
+    this._enabled = this._trackingOptions.enabled !== false;
+    if (!this._enabled) {
+      this._setReady();
+      return this;
+    }
+    if (!isBrowserEnvironment()) {
+      this._enabled = false;
+      this._setReady();
+      return this;
+    }
+    this._runtimeConfig = this._buildRuntimeConfig();
+    this._trackingOptions.transports = this._runtimeConfig.transports;
+    const hasCustomTransports = Array.isArray(this._runtimeConfig.transports) && this._runtimeConfig.transports.length > 0;
+    if (!this._runtimeConfig.url && !hasCustomTransports) {
+      console.warn("[TrackingService] Grafana Faro URL missing. Tracking will stay disabled.");
+      this._enabled = false;
+      this._setReady();
+      return this;
+    }
+    if (this._initialized) {
+      this._setReady();
+      return this;
+    }
+    if (!this._setupPromise) {
+      this._setupPromise = this._loadFaroClient(this._runtimeConfig);
+    }
+    await this._setupPromise;
+    return this;
+  }
+  updateContext(context) {
+    super.updateContext(context);
+    const trackingContext = context == null ? void 0 : context.tracking;
+    if (trackingContext) {
+      if (Object.hasOwn(trackingContext, "user")) {
+        this.setUser(trackingContext.user, { queue: false });
+      }
+      if (Object.hasOwn(trackingContext, "globalAttributes")) {
+        this.setGlobalAttributes(trackingContext.globalAttributes);
+      }
+    }
+  }
+  configureTracking(trackingOptions = {}) {
+    if (!trackingOptions || typeof trackingOptions !== "object") {
+      return this;
+    }
+    this._trackingOptions = {
+      ...this._trackingOptions,
+      ...trackingOptions
+    };
+    if (Object.hasOwn(trackingOptions, "globalAttributes")) {
+      this.setGlobalAttributes(trackingOptions.globalAttributes);
+    }
+    if (Object.hasOwn(trackingOptions, "user")) {
+      this.setUser(trackingOptions.user);
+      this._trackingOptions.user = trackingOptions.user;
+    }
+    return this;
+  }
+  configure(trackingOptions = {}) {
+    return this.configureTracking(trackingOptions);
+  }
+  trackEvent(name, attributes, options = {}) {
+    if (!name) {
+      throw new Error("Event name is required for trackEvent");
+    }
+    const mergedAttributes = this._mergeAttributes(attributes);
+    const eventOptions = options && typeof options === "object" ? options : {};
+    const { domain, queue, ...restOptions } = eventOptions;
+    const eventDomain = Object.hasOwn(eventOptions, "domain") ? domain : null;
+    const invokeTracking = (client) => {
+      const api = client == null ? void 0 : client.api;
+      if (!(api == null ? void 0 : api.pushEvent)) {
+        console.warn("[TrackingService] Faro pushEvent API not available");
+        return;
+      }
+      api.pushEvent(name, mergedAttributes, eventDomain, restOptions);
+    };
+    if (Object.hasOwn(eventOptions, "queue")) {
+      this._withClient(invokeTracking, { queue: Boolean(queue) });
+    } else {
+      this._withClient(invokeTracking);
+    }
+  }
+  trackError(error, options = {}) {
+    if (!error) {
+      return;
+    }
+    const err = error instanceof Error ? error : new Error(
+      typeof error === "string" ? error : "Unknown error captured by TrackingService"
+    );
+    const isContextOnly = options && typeof options === "object" && options !== null && !("context" in options || "type" in options || "stackFrames" in options || "skipDedupe" in options || "spanContext" in options || "timestampOverwriteMs" in options || "originalError" in options);
+    const normalizedOptions = isContextOnly ? { context: options } : options || {};
+    const mergedContext = this._mergeAttributes(normalizedOptions.context);
+    const apiOptions = {
+      ...normalizedOptions,
+      ...Object.keys(mergedContext).length > 0 ? { context: mergedContext } : {}
+    };
+    const queueConfigured = Object.hasOwn(apiOptions, "queue");
+    const { queue, ...errorOptions } = apiOptions;
+    const invokeTracking = (client) => {
+      const api = client == null ? void 0 : client.api;
+      if (!(api == null ? void 0 : api.pushError)) {
+        console.warn("[TrackingService] Faro pushError API not available");
+        return;
+      }
+      api.pushError(err, errorOptions);
+    };
+    if (queueConfigured) {
+      this._withClient(invokeTracking, { queue: Boolean(queue) });
+    } else {
+      this._withClient(invokeTracking);
+    }
+  }
+  captureException(error, options = {}) {
+    this.trackError(error, options);
+  }
+  logMessage(message, level = "info", context = null) {
+    if (!message) {
+      return;
+    }
+    const payload = Array.isArray(message) ? message : [message];
+    const logContext = this._mergeAttributes(context);
+    const severity = level || "info";
+    const options = {
+      level: severity,
+      ...Object.keys(logContext).length > 0 ? { context: logContext } : {}
+    };
+    this._withClient((client) => {
+      const api = client == null ? void 0 : client.api;
+      if (!(api == null ? void 0 : api.pushLog)) {
+        console.warn("[TrackingService] Faro pushLog API not available");
+        return;
+      }
+      api.pushLog(payload, options);
+    });
+  }
+  logDebug(message, context) {
+    this.logMessage(message, "debug", context);
+  }
+  logInfo(message, context) {
+    this.logMessage(message, "info", context);
+  }
+  logWarning(message, context) {
+    this.logMessage(message, "warn", context);
+  }
+  logWarn(message, context) {
+    this.logWarning(message, context);
+  }
+  logErrorMessage(message, context) {
+    this.logMessage(message, "error", context);
+  }
+  logError(message, context) {
+    this.logErrorMessage(message, context);
+  }
+  addBreadcrumb(message, attributes) {
+    if (!message) {
+      return;
+    }
+    const breadcrumbAttributes = {
+      category: "custom",
+      ...sanitizeAttributes(attributes || {}),
+      message
+    };
+    this.trackEvent("breadcrumb", breadcrumbAttributes);
+  }
+  trackMeasurement(type, values, options = {}) {
+    if (!type) {
+      throw new Error("Measurement type is required for trackMeasurement");
+    }
+    if (values == null) {
+      throw new Error("Measurement values are required for trackMeasurement");
+    }
+    const measurementValues = typeof values === "object" && !Array.isArray(values) ? sanitizeAttributes(values) : { value: Number(values) };
+    if (typeof measurementValues.value === "number" && Number.isNaN(measurementValues.value)) {
+      throw new Error("Measurement value must be a valid number");
+    }
+    const measurementOptions = options && typeof options === "object" ? options : {};
+    const {
+      attributes: measurementAttributesOption,
+      context: measurementContextOption,
+      queue,
+      ...transportOptions
+    } = measurementOptions;
+    const hasGlobalAttributes = Object.keys(this._globalAttributes).length > 0;
+    const attributePayload = measurementAttributesOption ? this._mergeAttributes(measurementAttributesOption) : hasGlobalAttributes ? { ...this._globalAttributes } : {};
+    const payload = {
+      type,
+      values: measurementValues,
+      ...attributePayload && Object.keys(attributePayload).length > 0 ? { attributes: attributePayload } : {}
+    };
+    const context = measurementContextOption ? this._mergeAttributes(measurementContextOption) : hasGlobalAttributes ? { ...this._globalAttributes } : {};
+    const apiOptions = {
+      ...transportOptions,
+      ...Object.keys(context).length > 0 ? { context } : {}
+    };
+    const invokeTracking = (client) => {
+      const api = client == null ? void 0 : client.api;
+      if (!(api == null ? void 0 : api.pushMeasurement)) {
+        console.warn("[TrackingService] Faro pushMeasurement API not available");
+        return;
+      }
+      api.pushMeasurement(payload, apiOptions);
+    };
+    if (Object.hasOwn(measurementOptions, "queue")) {
+      this._withClient(invokeTracking, { queue: Boolean(queue) });
+    } else {
+      this._withClient(invokeTracking);
+    }
+  }
+  trackView(name, attributes) {
+    if (!name) {
+      throw new Error("View name is required for trackView");
+    }
+    const viewAttributes = sanitizeAttributes(attributes || {});
+    const merged = this._mergeAttributes(viewAttributes);
+    this._withClient((client) => {
+      const api = client == null ? void 0 : client.api;
+      if (!(api == null ? void 0 : api.setView)) {
+        console.warn("[TrackingService] Faro setView API not available");
+        return;
+      }
+      api.setView({
+        name,
+        ...merged
+      });
+    });
+  }
+  setUser(user, options = {}) {
+    if (user == null) {
+      this.clearUser();
+      return;
+    }
+    if (typeof user !== "object") {
+      throw new Error("User must be an object");
+    }
+    const userData = sanitizeAttributes(user);
+    const queueConfigured = options && typeof options === "object" && Object.hasOwn(options, "queue");
+    const invokeTracking = (client) => {
+      const api = client == null ? void 0 : client.api;
+      if (!(api == null ? void 0 : api.setUser)) {
+        console.warn("[TrackingService] Faro setUser API not available");
+        return;
+      }
+      api.setUser(userData);
+    };
+    if (queueConfigured) {
+      this._withClient(invokeTracking, { queue: Boolean(options.queue) });
+    } else {
+      this._withClient(invokeTracking);
+    }
+  }
+  clearUser() {
+    this._withClient((client) => {
+      const api = client == null ? void 0 : client.api;
+      if (api == null ? void 0 : api.setUser) {
+        api.setUser(null);
+      } else {
+        console.warn("[TrackingService] Faro setUser API not available");
+      }
+    });
+  }
+  setSession(session, options = {}) {
+    if (session == null) {
+      this.clearSession();
+      return;
+    }
+    if (typeof session !== "object") {
+      throw new Error("Session must be an object");
+    }
+    const sessionData = sanitizeAttributes(session);
+    const queueConfigured = Object.hasOwn(options, "queue");
+    const { queue, ...sessionOptions } = options;
+    const invokeTracking = (client) => {
+      const api = client == null ? void 0 : client.api;
+      if (!(api == null ? void 0 : api.setSession)) {
+        console.warn("[TrackingService] Faro setSession API not available");
+        return;
+      }
+      api.setSession(sessionData, sessionOptions);
+    };
+    if (queueConfigured) {
+      this._withClient(invokeTracking, { queue: Boolean(queue) });
+    } else {
+      this._withClient(invokeTracking);
+    }
+  }
+  clearSession() {
+    this._withClient((client) => {
+      const api = client == null ? void 0 : client.api;
+      if (api == null ? void 0 : api.setSession) {
+        api.setSession(null);
+      } else {
+        console.warn("[TrackingService] Faro setSession API not available");
+      }
+    });
+  }
+  setGlobalAttributes(attributes) {
+    if (attributes == null) {
+      this._globalAttributes = {};
+      this._trackingOptions.globalAttributes = {};
+      return;
+    }
+    if (typeof attributes !== "object") {
+      throw new Error("Global attributes must be an object");
+    }
+    const sanitized = sanitizeAttributes(attributes);
+    this._globalAttributes = sanitized;
+    this._trackingOptions.globalAttributes = sanitized;
+  }
+  setGlobalAttribute(key, value) {
+    if (!key) {
+      throw new Error("Global attribute key is required");
+    }
+    const sanitized = sanitizeAttributes({ [key]: value });
+    this._globalAttributes = {
+      ...this._globalAttributes,
+      ...sanitized
+    };
+    this._trackingOptions.globalAttributes = { ...this._globalAttributes };
+  }
+  removeGlobalAttribute(key) {
+    if (!key) {
+      throw new Error("Global attribute key is required to remove it");
+    }
+    if (Object.hasOwn(this._globalAttributes, key)) {
+      const rest = { ...this._globalAttributes };
+      delete rest[key];
+      this._globalAttributes = rest;
+      this._trackingOptions.globalAttributes = rest;
+    }
+  }
+  _mergeAttributes(attributes) {
+    const hasInput = attributes && typeof attributes === "object";
+    const sanitized = hasInput ? sanitizeAttributes(attributes) : {};
+    if (!this._globalAttributes || Object.keys(this._globalAttributes).length === 0) {
+      return sanitized;
+    }
+    return {
+      ...this._globalAttributes,
+      ...sanitized
+    };
+  }
+  flushQueue() {
+    if (!this._queue.length) {
+      return;
+    }
+    const queue = [...this._queue];
+    this._queue.length = 0;
+    if (!this._faroClient) {
+      return;
+    }
+    queue.forEach((callback) => {
+      try {
+        callback(this._faroClient);
+      } catch (error) {
+        console.error("[TrackingService] Failed to flush queued tracking call", error);
+      }
+    });
+  }
+  getClient() {
+    return this._faroClient;
+  }
+  isEnabled() {
+    return this._enabled && Boolean(this._faroClient);
+  }
+  isInitialized() {
+    return this._initialized;
+  }
+  destroy() {
+    var _a;
+    this._queue.length = 0;
+    if ((_a = this._faroClient) == null ? void 0 : _a.destroy) {
+      try {
+        this._faroClient.destroy();
+      } catch (error) {
+        console.warn("[TrackingService] Failed to destroy Faro client cleanly", error);
+      }
+    }
+    if (isBrowserEnvironment() && window.symbols && window.symbols.faro === this._faroClient) {
+      delete window.symbols.faro;
+    }
+    this._faroClient = null;
+    this._initialized = false;
+    this._setupPromise = null;
+    this._setReady(false);
+    this._enabled = this._trackingOptions.enabled !== false;
+  }
+  _buildRuntimeConfig() {
+    var _a, _b;
+    const contextConfig = ((_a = this._context) == null ? void 0 : _a.tracking) || {};
+    const merged = {
+      ...DEFAULT_TRACKING_OPTIONS,
+      ...this._trackingOptions,
+      ...contextConfig
+    };
+    const transportList = [];
+    if (Array.isArray(merged.transports)) {
+      transportList.push(...merged.transports.filter(Boolean));
+    } else if (merged.transport) {
+      transportList.push(merged.transport);
+    }
+    const configuredUrl = merged.url || contextConfig.url || this._trackingOptions.url;
+    let url = configuredUrl;
+    if (!url && transportList.length === 0) {
+      url = import_environment.default.grafanaUrl;
+    }
+    const appName = merged.appName || contextConfig.appName || this._trackingOptions.appName || import_environment.default.grafanaAppName || "Symbols Platform";
+    const appVersion = merged.appVersion || contextConfig.appVersion || this._trackingOptions.appVersion || ((_b = this._context) == null ? void 0 : _b.appVersion);
+    const environmentName = merged.environment || contextConfig.environment || this._trackingOptions.environment || this._resolveEnvironmentName();
+    const contextGlobalAttributes = sanitizeAttributes(contextConfig.globalAttributes || {});
+    const globalAttributes = sanitizeAttributes({
+      ...this._globalAttributes,
+      ...contextGlobalAttributes
+    });
+    const runtimeConfig = {
+      url,
+      appName,
+      appVersion,
+      environment: environmentName,
+      globalAttributes,
+      sessionTracking: merged.sessionTracking !== false,
+      enableTracing: merged.enableTracing !== false,
+      user: merged.user,
+      maxQueueSize: typeof merged.maxQueueSize === "number" && merged.maxQueueSize > 0 ? merged.maxQueueSize : DEFAULT_MAX_QUEUE_SIZE
+    };
+    if (typeof merged.isolate === "boolean") {
+      runtimeConfig.isolate = merged.isolate;
+    }
+    if (Array.isArray(merged.instrumentations)) {
+      runtimeConfig.instrumentations = merged.instrumentations;
+    }
+    if (typeof merged.instrumentationsFactory === "function") {
+      runtimeConfig.instrumentationsFactory = merged.instrumentationsFactory;
+    }
+    if (merged.webInstrumentationOptions != null) {
+      runtimeConfig.webInstrumentationOptions = merged.webInstrumentationOptions;
+    }
+    if (transportList.length > 0) {
+      runtimeConfig.transports = transportList;
+    }
+    return runtimeConfig;
+  }
+  _resolveEnvironmentName() {
+    if (import_environment.default.isProduction) {
+      return "production";
+    }
+    if (import_environment.default.isStaging) {
+      return "staging";
+    }
+    if (import_environment.default.isTesting) {
+      return "testing";
+    }
+    if (import_environment.default.isDevelopment) {
+      return "development";
+    }
+    return process.env.SYMBOLS_APP_ENV || process.env.NODE_ENV || "development";
+  }
+  async _loadFaroClient(runtimeConfig) {
+    try {
+      const tracingImport = runtimeConfig.enableTracing === false ? Promise.resolve(null) : import("@grafana/faro-web-tracing").catch((error) => {
+        console.warn("[TrackingService] Tracing instrumentation failed to load:", error);
+        return null;
+      });
+      const [{ initializeFaro, getWebInstrumentations }, tracingModule] = await Promise.all([
+        import("@grafana/faro-web-sdk"),
+        tracingImport
+      ]);
+      const TracingInstrumentation = tracingModule == null ? void 0 : tracingModule.TracingInstrumentation;
+      const instrumentations = await this._resolveInstrumentations({
+        runtimeConfig,
+        getWebInstrumentations,
+        TracingInstrumentation
+      });
+      const initializeOptions = {
+        app: {
+          name: runtimeConfig.appName,
+          version: runtimeConfig.appVersion,
+          environment: runtimeConfig.environment
+        },
+        instrumentations,
+        globalAttributes: sanitizeAttributes(runtimeConfig.globalAttributes)
+      };
+      if (runtimeConfig.url) {
+        initializeOptions.url = runtimeConfig.url;
+      }
+      if (Array.isArray(runtimeConfig.transports) && runtimeConfig.transports.length > 0) {
+        initializeOptions.transports = runtimeConfig.transports;
+      }
+      if (runtimeConfig.sessionTracking === false) {
+        initializeOptions.sessionTracking = false;
+      }
+      if (runtimeConfig.isolate === true) {
+        initializeOptions.isolate = true;
+      }
+      this._faroClient = initializeFaro(initializeOptions);
+      if (runtimeConfig.user) {
+        this.setUser(runtimeConfig.user, { queue: false });
+      }
+      if (isBrowserEnvironment()) {
+        window.symbols ||= {};
+        window.symbols.faro = this._faroClient;
+      }
+      this._initialized = true;
+      this._setReady();
+      this.flushQueue();
+    } catch (error) {
+      this._enabled = false;
+      this._setError(error);
+      this._ready = true;
+      console.error("[TrackingService] Failed to initialize Grafana Faro client:", error);
+    } finally {
+      this._setupPromise = null;
+    }
+  }
+  async _resolveInstrumentations({
+    runtimeConfig,
+    getWebInstrumentations,
+    TracingInstrumentation
+  }) {
+    if (Array.isArray(runtimeConfig.instrumentations)) {
+      return runtimeConfig.instrumentations;
+    }
+    if (typeof runtimeConfig.instrumentationsFactory === "function") {
+      try {
+        const instrumentations = await runtimeConfig.instrumentationsFactory({
+          runtimeConfig,
+          getWebInstrumentations,
+          TracingInstrumentation
+        });
+        if (Array.isArray(instrumentations)) {
+          return instrumentations;
+        }
+      } catch (error) {
+        console.warn("[TrackingService] Custom instrumentation factory failed:", error);
+      }
+    }
+    const instrumentationOptions = runtimeConfig.webInstrumentationOptions == null ? {} : runtimeConfig.webInstrumentationOptions;
+    const defaultInstrumentations = getWebInstrumentations(instrumentationOptions);
+    if (runtimeConfig.enableTracing !== false && TracingInstrumentation) {
+      try {
+        defaultInstrumentations.push(new TracingInstrumentation());
+      } catch (error) {
+        console.warn("[TrackingService] Failed to instantiate tracing instrumentation:", error);
+      }
+    }
+    return defaultInstrumentations;
+  }
+  _withClient(callback, options = {}) {
+    if (!this._enabled) {
+      return null;
+    }
+    if (this._faroClient) {
+      try {
+        return callback(this._faroClient);
+      } catch (error) {
+        console.error("[TrackingService] Tracking callback failed:", error);
+        return null;
+      }
+    }
+    if (options.queue === false) {
+      return null;
+    }
+    const queueLimit = this._runtimeConfig.maxQueueSize ?? this._trackingOptions.maxQueueSize ?? DEFAULT_MAX_QUEUE_SIZE;
+    if (this._queue.length >= queueLimit) {
+      this._queue.shift();
+    }
+    this._queue.push(callback);
+    return null;
+  }
+}