@elliemae/ssf-host 2.24.0 → 2.25.0

package/dist/cjs/guest.js

@@ -74,9 +74,9 @@ class Guest {
    */
   #remoting;
   /**
-   * analytics object
+   * performance tracker for timing measurements
    */
-  #analyticsObj;
+  #perfTracker;
   /**
    * Create object representing guest application
    * @param {GuestOption} option - options for creating a guest application
@@ -91,7 +91,7 @@ class Guest {
       searchParams = {},
       openMode = import_types.OpenMode.Embed,
       remoting,
-      analyticsObj
+      perfTracker
     } = option;
     this.id = guestId;
     this.title = title;
@@ -102,7 +102,7 @@ class Guest {
     this.window = window;
     this.openMode = openMode;
     this.capabilities = {};
-    this.#analyticsObj = analyticsObj;
+    this.#perfTracker = perfTracker;
     this.#remoting = remoting;
   }
   /**
@@ -188,16 +188,17 @@ class Guest {
    * invokes event callback on the guest application
    * @param {EventObject} event - event object
    * @param {number} timeout - timeout in milliseconds
+   * @returns {Promise} resolves when the guest handles the event
    */
   dispatchEvent = (event, timeout) => {
-    this.#analyticsObj.startTiming(
-      `ScriptingObject.Event.${event.object.objectId}.${event.eventName}`,
-      {
+    let timingToken;
+    if (this.#perfTracker.enabled) {
+      const name = `ScriptingObject.Event.${event.object.objectId}.${event.eventName}`;
+      timingToken = this.#perfTracker.start(name, {
         appId: this.id,
         appUrl: this.url
-      }
-    ).catch(() => {
-    });
+      });
+    }
     return this.#remoting.invoke({
       targetWin: this.window,
       targetOrigin: this.origin,
@@ -205,14 +206,12 @@ class Guest {
       messageBody: event,
       responseTimeoutMs: timeout
     }).finally(() => {
-      this.#analyticsObj.endTiming(
-        `ScriptingObject.Event.${event.object.objectId}.${event.eventName}`,
-        {
+      if (timingToken) {
+        this.#perfTracker.end(timingToken, {
           appId: this.id,
           appUrl: this.url
-        }
-      ).catch(() => {
-      });
+        });
+      }
     });
   };
   /**

package/dist/cjs/host.js

@@ -27,6 +27,7 @@ var import_microfe_common = require("@elliemae/microfe-common");
 var import_types = require("./types.js");
 var import_guest = require("./guest.js");
 var import_utils = require("./utils.js");
+var import_performanceTracker = require("./performanceTracker.js");
 const SANDBOX_DEFAULT = [
   import_types.IFrameSandboxValues.AllowScripts,
   import_types.IFrameSandboxValues.AllowPopups,
@@ -98,16 +99,13 @@ class SSFHost {
    */
   #guestMetadata = /* @__PURE__ */ new Map();
   /**
-   * Tracks the last time a timing measurement was recorded for each metric name.
-   * Used to skip redundant startTiming/endTiming cross-window calls for
-   * the same API or event within the dedup window.
+   * Performance tracker for host-side timing (with dedup).
    */
-  #timingLastRecorded = /* @__PURE__ */ new Map();
+  #perfTracker;
   /**
-   * Minimum interval (ms) between timing measurements for the same metric name.
+   * Performance tracker shared by all guests (no dedup).
    */
-  #timingDedupWindowMs;
-  static DEFAULT_TIMING_DEDUP_WINDOW_MS = 1e4;
+  #guestPerfTracker;
   /**
    * Create a new host
    * @param hostId unique identifier for the host
@@ -119,7 +117,20 @@ class SSFHost {
     if (!option?.analyticsObj) throw new Error("Analytics object is required");
     this.#logger = option.logger;
     this.#analyticsObj = option.analyticsObj;
-    this.#timingDedupWindowMs = option?.timingDedupWindowMs ?? SSFHost.DEFAULT_TIMING_DEDUP_WINDOW_MS;
+    const perfOpts = {
+      analyticsObj: option.analyticsObj,
+      enabled: option?.measurePerformance,
+      samplingRatio: option?.performanceSamplingRatio,
+      onError: (msg) => this.#logger.debug(msg)
+    };
+    this.#perfTracker = new import_performanceTracker.PerformanceTracker({
+      ...perfOpts,
+      dedupWindowMs: option?.performanceDedupWindowMs
+    });
+    this.#guestPerfTracker = new import_performanceTracker.PerformanceTracker({
+      ...perfOpts,
+      dedupWindowMs: 0
+    });
     this.#correlationId = (0, import_uuid.v4)();
     this.#remoting = new import_microfe_common.Remoting(this.#logger, this.#correlationId);
     if (option?.readyStateCallback && typeof option?.readyStateCallback !== "function")
@@ -143,34 +154,6 @@ class SSFHost {
       );
     });
   };
-  #startTiming = (name, options) => {
-    this.#analyticsObj.startTiming(name, options).catch((e) => {
-      this.#logger.debug(
-        `Analytics startTiming failed: ${e.message}`
-      );
-    });
-  };
-  #endTiming = (start, options) => {
-    this.#analyticsObj.endTiming(start, options).catch((e) => {
-      this.#logger.debug(`Analytics endTiming failed: ${e.message}`);
-    });
-  };
-  /**
-   * Returns true if a timing measurement should be recorded for the given
-   * metric name. Skips the measurement when one was already recorded for the
-   * same name within the configured dedup window ({@link HostOption.timingDedupWindowMs}).
-   * Always returns true when dedup is disabled (window = 0).
-   * @param name
-   */
-  #shouldTrackTiming = (name) => {
-    if (this.#timingDedupWindowMs <= 0) return true;
-    const now = performance.now();
-    const last = this.#timingLastRecorded.get(name);
-    if (last !== void 0 && now - last < this.#timingDedupWindowMs)
-      return false;
-    this.#timingLastRecorded.set(name, now);
-    return true;
-  };
   #closeAllPopupGuests = () => {
     const popupIds = Array.from(this.#guests.values()).filter((guest) => guest.openMode === import_types.OpenMode.Popup).map((guest) => guest.id);
     popupIds.forEach((id) => this.unloadGuest(id));
@@ -293,7 +276,7 @@ class SSFHost {
     if (!guest.ready) {
       guest.ready = true;
       const guestInfo = guest.getInfo();
-      this.#endTiming("SSF.Guest.Load", {
+      this.#perfTracker.end("SSF.Guest.Load", {
         appId: guestInfo.guestId,
         appUrl: guestInfo.guestUrl
       });
@@ -566,10 +549,10 @@ class SSFHost {
       return false;
     }
     const guestInfo = guest.getInfo();
-    const timingName = `ScriptingObject.API.${objectId}.${body.functionName}`;
-    const trackTiming = this.#shouldTrackTiming(timingName);
-    if (trackTiming) {
-      this.#startTiming(timingName, {
+    let timingToken;
+    if (this.#perfTracker.enabled) {
+      const name = `ScriptingObject.API.${objectId}.${body.functionName}`;
+      timingToken = this.#perfTracker.start(name, {
         appId: guestInfo.guestId,
         appUrl: guestInfo.guestUrl
       });
@@ -609,8 +592,8 @@ class SSFHost {
         ...guestInfo
       });
     }).finally(() => {
-      if (trackTiming) {
-        this.#endTiming(timingName, {
+      if (timingToken) {
+        this.#perfTracker.end(timingToken, {
           appId: guestInfo.guestId,
           appUrl: guestInfo.guestUrl
         });
@@ -685,7 +668,7 @@ class SSFHost {
     const guest = new import_guest.Guest({
       ...param,
       remoting: this.#remoting,
-      analyticsObj: this.#analyticsObj
+      perfTracker: this.#guestPerfTracker
     });
     guest.init();
     this.#guests.set(param.guestId, guest);
@@ -1058,18 +1041,16 @@ class SSFHost {
       };
     }
     const guestPromises = [];
-    const eventTimingName = `ScriptingObject.Event.${scriptingObject.id}.${name}`;
-    let timingMetricStarted = false;
+    let eventTimingToken;
     const dispatchToGuest = (guest) => {
       const guestInfo = guest.getInfo();
       if (timeout && guest?.capabilities?.eventFeedback) {
         guestPromises.push(guest.dispatchEvent(eventObj, timeout));
-        if (!timingMetricStarted && this.#shouldTrackTiming(eventTimingName)) {
-          this.#startTiming(eventTimingName, {
-            appId: this.hostId,
-            appUrl: window.location.href
-          });
-          timingMetricStarted = true;
+        if (!eventTimingToken && this.#perfTracker.enabled) {
+          eventTimingToken = this.#perfTracker.start(
+            `ScriptingObject.Event.${scriptingObject.id}.${name}`,
+            { appId: this.hostId, appUrl: window.location.href }
+          );
         }
         this.#logger.debug({
           message: "Event dispatched and awaiting feedback",
@@ -1107,11 +1088,12 @@ class SSFHost {
       });
       throw ex;
     }).finally(() => {
-      if (timingMetricStarted)
-        this.#endTiming(eventTimingName, {
+      if (eventTimingToken) {
+        this.#perfTracker.end(eventTimingToken, {
           appId: this.hostId,
           appUrl: window.location.href
         });
+      }
     });
   };
   /**
@@ -1155,7 +1137,7 @@ class SSFHost {
     const { openMode = import_types.OpenMode.Embed, popupWindowFeatures = {} } = options;
     const srcUrl = this.#getGuestUrl(url, searchParams);
     let guest = null;
-    this.#startTiming("SSF.Guest.Load", {
+    this.#perfTracker.start("SSF.Guest.Load", {
       appId: instanceId,
       appUrl: srcUrl
     });

package/dist/cjs/performanceTracker.js

@@ -0,0 +1,111 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var performanceTracker_exports = {};
+__export(performanceTracker_exports, {
+  PerformanceTracker: () => PerformanceTracker
+});
+module.exports = __toCommonJS(performanceTracker_exports);
+class PerformanceTracker {
+  #analyticsObj;
+  #enabled;
+  #samplingRatio;
+  #samplingConfigured = /* @__PURE__ */ new Set();
+  #dedupWindowMs;
+  #lastRecorded = /* @__PURE__ */ new Map();
+  #onError;
+  static DEFAULT_SAMPLING_RATIO = 0.05;
+  static DEFAULT_DEDUP_WINDOW_MS = 1e4;
+  static #LOW_FREQUENCY = /* @__PURE__ */ new Set(["SSF.Guest.Load"]);
+  constructor(options) {
+    this.#analyticsObj = options.analyticsObj;
+    this.#enabled = options.enabled ?? false;
+    this.#samplingRatio = options.samplingRatio ?? PerformanceTracker.DEFAULT_SAMPLING_RATIO;
+    this.#dedupWindowMs = options.dedupWindowMs ?? PerformanceTracker.DEFAULT_DEDUP_WINDOW_MS;
+    this.#onError = options.onError;
+  }
+  /**
+   * Whether performance tracking is active. Callers can use this to
+   * skip expensive work (e.g. building timing name strings) when
+   * tracking is disabled.
+   * @returns {boolean} true when performance tracking is enabled
+   */
+  get enabled() {
+    return this.#enabled;
+  }
+  /**
+   * Begin a timing measurement. Returns the timing name as a token when
+   * timing was started, or `undefined` when timing is disabled, deduped,
+   * or skipped. Pass the returned token to {@link end}.
+   * Never throws — failures are reported via the `onError` callback.
+   * @param {string} name - timing event name
+   * @param {TimingOptions} options - context passed to the analytics object
+   * @returns {string | undefined} the timing token, or undefined if skipped
+   */
+  start(name, options) {
+    if (!this.#enabled) return void 0;
+    try {
+      const lowFreq = PerformanceTracker.#LOW_FREQUENCY.has(name);
+      if (!lowFreq && !this.#shouldTrack(name)) return void 0;
+      if (!lowFreq && !this.#samplingConfigured.has(name)) {
+        this.#analyticsObj.setTimingEventSamplingRatio({
+          [name]: this.#samplingRatio
+        });
+        this.#samplingConfigured.add(name);
+      }
+      this.#analyticsObj.startTiming(name, options).catch((e) => {
+        this.#reportError(`startTiming failed: ${e.message}`);
+      });
+      return name;
+    } catch (e) {
+      this.#reportError(`startTiming failed: ${e.message}`);
+      return void 0;
+    }
+  }
+  /**
+   * End a timing measurement previously started via {@link start}.
+   * No-op when token is `undefined` (timing was not started).
+   * Never throws — failures are reported via the `onError` callback.
+   * @param {string | undefined} token - token returned by {@link start}
+   * @param {TimingOptions} options - context passed to the analytics object
+   */
+  end(token, options) {
+    if (!token) return;
+    try {
+      this.#analyticsObj.endTiming(token, options).catch((e) => {
+        this.#reportError(`endTiming failed: ${e.message}`);
+      });
+    } catch (e) {
+      this.#reportError(`endTiming failed: ${e.message}`);
+    }
+  }
+  #reportError(message) {
+    try {
+      this.#onError?.(message);
+    } catch {
+    }
+  }
+  #shouldTrack(name) {
+    if (this.#dedupWindowMs <= 0) return true;
+    const now = performance.now();
+    const last = this.#lastRecorded.get(name);
+    if (last !== void 0 && now - last < this.#dedupWindowMs) return false;
+    this.#lastRecorded.set(name, now);
+    return true;
+  }
+}

package/dist/esm/guest.js

@@ -51,9 +51,9 @@ class Guest {
    */
   #remoting;
   /**
-   * analytics object
+   * performance tracker for timing measurements
    */
-  #analyticsObj;
+  #perfTracker;
   /**
    * Create object representing guest application
    * @param {GuestOption} option - options for creating a guest application
@@ -68,7 +68,7 @@ class Guest {
       searchParams = {},
       openMode = OpenMode.Embed,
       remoting,
-      analyticsObj
+      perfTracker
     } = option;
     this.id = guestId;
     this.title = title;
@@ -79,7 +79,7 @@ class Guest {
     this.window = window;
     this.openMode = openMode;
     this.capabilities = {};
-    this.#analyticsObj = analyticsObj;
+    this.#perfTracker = perfTracker;
     this.#remoting = remoting;
   }
   /**
@@ -165,16 +165,17 @@ class Guest {
    * invokes event callback on the guest application
    * @param {EventObject} event - event object
    * @param {number} timeout - timeout in milliseconds
+   * @returns {Promise} resolves when the guest handles the event
    */
   dispatchEvent = (event, timeout) => {
-    this.#analyticsObj.startTiming(
-      `ScriptingObject.Event.${event.object.objectId}.${event.eventName}`,
-      {
+    let timingToken;
+    if (this.#perfTracker.enabled) {
+      const name = `ScriptingObject.Event.${event.object.objectId}.${event.eventName}`;
+      timingToken = this.#perfTracker.start(name, {
         appId: this.id,
         appUrl: this.url
-      }
-    ).catch(() => {
-    });
+      });
+    }
     return this.#remoting.invoke({
       targetWin: this.window,
       targetOrigin: this.origin,
@@ -182,14 +183,12 @@ class Guest {
       messageBody: event,
       responseTimeoutMs: timeout
     }).finally(() => {
-      this.#analyticsObj.endTiming(
-        `ScriptingObject.Event.${event.object.objectId}.${event.eventName}`,
-        {
+      if (timingToken) {
+        this.#perfTracker.end(timingToken, {
           appId: this.id,
           appUrl: this.url
-        }
-      ).catch(() => {
-      });
+        });
+      }
     });
   };
   /**

package/dist/esm/host.js

@@ -14,6 +14,7 @@ import {
 } from "./types.js";
 import { Guest } from "./guest.js";
 import { flatten, isFunction, isTrustedDomain } from "./utils.js";
+import { PerformanceTracker } from "./performanceTracker.js";
 const SANDBOX_DEFAULT = [
   IFrameSandboxValues.AllowScripts,
   IFrameSandboxValues.AllowPopups,
@@ -85,16 +86,13 @@ class SSFHost {
    */
   #guestMetadata = /* @__PURE__ */ new Map();
   /**
-   * Tracks the last time a timing measurement was recorded for each metric name.
-   * Used to skip redundant startTiming/endTiming cross-window calls for
-   * the same API or event within the dedup window.
+   * Performance tracker for host-side timing (with dedup).
    */
-  #timingLastRecorded = /* @__PURE__ */ new Map();
+  #perfTracker;
   /**
-   * Minimum interval (ms) between timing measurements for the same metric name.
+   * Performance tracker shared by all guests (no dedup).
    */
-  #timingDedupWindowMs;
-  static DEFAULT_TIMING_DEDUP_WINDOW_MS = 1e4;
+  #guestPerfTracker;
   /**
    * Create a new host
    * @param hostId unique identifier for the host
@@ -106,7 +104,20 @@ class SSFHost {
     if (!option?.analyticsObj) throw new Error("Analytics object is required");
     this.#logger = option.logger;
     this.#analyticsObj = option.analyticsObj;
-    this.#timingDedupWindowMs = option?.timingDedupWindowMs ?? SSFHost.DEFAULT_TIMING_DEDUP_WINDOW_MS;
+    const perfOpts = {
+      analyticsObj: option.analyticsObj,
+      enabled: option?.measurePerformance,
+      samplingRatio: option?.performanceSamplingRatio,
+      onError: (msg) => this.#logger.debug(msg)
+    };
+    this.#perfTracker = new PerformanceTracker({
+      ...perfOpts,
+      dedupWindowMs: option?.performanceDedupWindowMs
+    });
+    this.#guestPerfTracker = new PerformanceTracker({
+      ...perfOpts,
+      dedupWindowMs: 0
+    });
     this.#correlationId = uuidv4();
     this.#remoting = new Remoting(this.#logger, this.#correlationId);
     if (option?.readyStateCallback && typeof option?.readyStateCallback !== "function")
@@ -130,34 +141,6 @@ class SSFHost {
       );
     });
   };
-  #startTiming = (name, options) => {
-    this.#analyticsObj.startTiming(name, options).catch((e) => {
-      this.#logger.debug(
-        `Analytics startTiming failed: ${e.message}`
-      );
-    });
-  };
-  #endTiming = (start, options) => {
-    this.#analyticsObj.endTiming(start, options).catch((e) => {
-      this.#logger.debug(`Analytics endTiming failed: ${e.message}`);
-    });
-  };
-  /**
-   * Returns true if a timing measurement should be recorded for the given
-   * metric name. Skips the measurement when one was already recorded for the
-   * same name within the configured dedup window ({@link HostOption.timingDedupWindowMs}).
-   * Always returns true when dedup is disabled (window = 0).
-   * @param name
-   */
-  #shouldTrackTiming = (name) => {
-    if (this.#timingDedupWindowMs <= 0) return true;
-    const now = performance.now();
-    const last = this.#timingLastRecorded.get(name);
-    if (last !== void 0 && now - last < this.#timingDedupWindowMs)
-      return false;
-    this.#timingLastRecorded.set(name, now);
-    return true;
-  };
   #closeAllPopupGuests = () => {
     const popupIds = Array.from(this.#guests.values()).filter((guest) => guest.openMode === OpenMode.Popup).map((guest) => guest.id);
     popupIds.forEach((id) => this.unloadGuest(id));
@@ -280,7 +263,7 @@ class SSFHost {
     if (!guest.ready) {
       guest.ready = true;
       const guestInfo = guest.getInfo();
-      this.#endTiming("SSF.Guest.Load", {
+      this.#perfTracker.end("SSF.Guest.Load", {
         appId: guestInfo.guestId,
         appUrl: guestInfo.guestUrl
       });
@@ -553,10 +536,10 @@ class SSFHost {
       return false;
     }
     const guestInfo = guest.getInfo();
-    const timingName = `ScriptingObject.API.${objectId}.${body.functionName}`;
-    const trackTiming = this.#shouldTrackTiming(timingName);
-    if (trackTiming) {
-      this.#startTiming(timingName, {
+    let timingToken;
+    if (this.#perfTracker.enabled) {
+      const name = `ScriptingObject.API.${objectId}.${body.functionName}`;
+      timingToken = this.#perfTracker.start(name, {
         appId: guestInfo.guestId,
         appUrl: guestInfo.guestUrl
       });
@@ -596,8 +579,8 @@ class SSFHost {
         ...guestInfo
       });
     }).finally(() => {
-      if (trackTiming) {
-        this.#endTiming(timingName, {
+      if (timingToken) {
+        this.#perfTracker.end(timingToken, {
           appId: guestInfo.guestId,
           appUrl: guestInfo.guestUrl
         });
@@ -672,7 +655,7 @@ class SSFHost {
     const guest = new Guest({
       ...param,
       remoting: this.#remoting,
-      analyticsObj: this.#analyticsObj
+      perfTracker: this.#guestPerfTracker
     });
     guest.init();
     this.#guests.set(param.guestId, guest);
@@ -1045,18 +1028,16 @@ class SSFHost {
       };
     }
     const guestPromises = [];
-    const eventTimingName = `ScriptingObject.Event.${scriptingObject.id}.${name}`;
-    let timingMetricStarted = false;
+    let eventTimingToken;
     const dispatchToGuest = (guest) => {
       const guestInfo = guest.getInfo();
       if (timeout && guest?.capabilities?.eventFeedback) {
         guestPromises.push(guest.dispatchEvent(eventObj, timeout));
-        if (!timingMetricStarted && this.#shouldTrackTiming(eventTimingName)) {
-          this.#startTiming(eventTimingName, {
-            appId: this.hostId,
-            appUrl: window.location.href
-          });
-          timingMetricStarted = true;
+        if (!eventTimingToken && this.#perfTracker.enabled) {
+          eventTimingToken = this.#perfTracker.start(
+            `ScriptingObject.Event.${scriptingObject.id}.${name}`,
+            { appId: this.hostId, appUrl: window.location.href }
+          );
         }
         this.#logger.debug({
           message: "Event dispatched and awaiting feedback",
@@ -1094,11 +1075,12 @@ class SSFHost {
       });
       throw ex;
     }).finally(() => {
-      if (timingMetricStarted)
-        this.#endTiming(eventTimingName, {
+      if (eventTimingToken) {
+        this.#perfTracker.end(eventTimingToken, {
           appId: this.hostId,
           appUrl: window.location.href
         });
+      }
     });
   };
   /**
@@ -1142,7 +1124,7 @@ class SSFHost {
     const { openMode = OpenMode.Embed, popupWindowFeatures = {} } = options;
     const srcUrl = this.#getGuestUrl(url, searchParams);
     let guest = null;
-    this.#startTiming("SSF.Guest.Load", {
+    this.#perfTracker.start("SSF.Guest.Load", {
       appId: instanceId,
       appUrl: srcUrl
     });