@newrelic/browser-agent 1.252.0 → 1.253.0

package/dist/cjs/features/soft_navigations/aggregate/ajax-node.js

@@ -0,0 +1,50 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.AjaxNode = void 0;
+var _belSerializer = require("../../../common/serialize/bel-serializer");
+var _constants = require("../constants");
+var _belNode = require("./bel-node");
+class AjaxNode extends _belNode.BelNode {
+  constructor(agentIdentifier, ajaxEvent) {
+    super(agentIdentifier);
+    this.belType = _constants.NODE_TYPE.AJAX;
+    this.method = ajaxEvent.method;
+    this.status = ajaxEvent.status;
+    this.domain = ajaxEvent.domain;
+    this.path = ajaxEvent.path;
+    this.txSize = ajaxEvent.requestSize;
+    this.rxSize = ajaxEvent.responseSize;
+    this.requestedWith = ajaxEvent.type === 'fetch' ? 1 : ''; // 'xhr' and 'beacon' types get the empty string
+    this.spanId = ajaxEvent.spanId;
+    this.traceId = ajaxEvent.traceId;
+    this.spanTimestamp = ajaxEvent.spanTimestamp;
+    this.gql = ajaxEvent.gql;
+    this.start = ajaxEvent.startTime;
+    this.end = ajaxEvent.endTime;
+  }
+  serialize(parentStartTimestamp) {
+    const addString = (0, _belSerializer.getAddStringContext)(this.agentIdentifier);
+    const nodeList = [];
+
+    // IMPORTANT: The order in which addString is called matters and correlates to the order in which string shows up in the harvest payload. Do not re-order the following code.
+    const fields = [(0, _belSerializer.numeric)(this.belType), 0,
+    // this will be overwritten below with number of attached nodes
+    (0, _belSerializer.numeric)(this.start - parentStartTimestamp),
+    // start relative to parent start (if part of first node in payload) or first parent start
+    (0, _belSerializer.numeric)(this.end - this.start),
+    // end is relative to start
+    (0, _belSerializer.numeric)(this.callbackEnd), (0, _belSerializer.numeric)(this.callbackDuration), addString(this.method), (0, _belSerializer.numeric)(this.status), addString(this.domain), addString(this.path), (0, _belSerializer.numeric)(this.txSize), (0, _belSerializer.numeric)(this.rxSize), this.requestedWith, addString(this.nodeId), (0, _belSerializer.nullable)(this.spanId, addString, true) + (0, _belSerializer.nullable)(this.traceId, addString, true) + (0, _belSerializer.nullable)(this.spanTimestamp, _belSerializer.numeric)];
+    let allAttachedNodes = [];
+    if (typeof this.gql === 'object') allAttachedNodes = (0, _belSerializer.addCustomAttributes)(this.gql, addString);
+    this.children.forEach(node => allAttachedNodes.push(node.serialize())); // no children is expected under ajax nodes at this time
+
+    fields[1] = (0, _belSerializer.numeric)(allAttachedNodes.length);
+    nodeList.push(fields);
+    if (allAttachedNodes.length) nodeList.push(allAttachedNodes.join(';'));
+    return nodeList.join(';');
+  }
+}
+exports.AjaxNode = AjaxNode;

package/dist/cjs/features/soft_navigations/aggregate/bel-node.js

@@ -0,0 +1,29 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.BelNode = void 0;
+var _now = require("../../../common/timing/now");
+let nodesSeen = 0;
+class BelNode {
+  belType;
+  /** List of other BelNode derivatives. Each children should be of a subclass that implements its own 'serialize' function. */
+  children = [];
+  start = (0, _now.now)();
+  end;
+  callbackEnd = 0;
+  callbackDuration = 0;
+  nodeId = ++nodesSeen;
+  constructor(agentIdentifier) {
+    if (!agentIdentifier) throw new Error('Interaction is missing core attributes');
+    this.agentIdentifier = agentIdentifier;
+  }
+  addChild(child) {
+    this.children.push(child);
+  }
+
+  /** Virtual fn for stringifying an instance. */
+  serialize() {}
+}
+exports.BelNode = BelNode;

package/dist/cjs/features/soft_navigations/aggregate/index.js

@@ -0,0 +1,263 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.Aggregate = void 0;
+var _config = require("../../../common/config/config");
+var _handle = require("../../../common/event-emitter/handle");
+var _registerHandler = require("../../../common/event-emitter/register-handler");
+var _harvestScheduler = require("../../../common/harvest/harvest-scheduler");
+var _invoke = require("../../../common/util/invoke");
+var _timeToFirstByte = require("../../../common/vitals/time-to-first-byte");
+var _features = require("../../../loaders/features/features");
+var _constants = require("../../metrics/constants");
+var _aggregateBase = require("../../utils/aggregate-base");
+var _constants2 = require("../constants");
+var _ajaxNode = require("./ajax-node");
+var _initialPageLoadInteraction = require("./initial-page-load-interaction");
+var _interaction = require("./interaction");
+class Aggregate extends _aggregateBase.AggregateBase {
+  static featureName = _constants2.FEATURE_NAME;
+  constructor(agentIdentifier, aggregator, _ref) {
+    let {
+      domObserver
+    } = _ref;
+    super(agentIdentifier, aggregator, _constants2.FEATURE_NAME);
+    const harvestTimeSeconds = (0, _config.getConfigurationValue)(agentIdentifier, 'soft_navigations.harvestTimeSeconds') || 10;
+    this.interactionsToHarvest = [];
+    this.interactionsAwaitingRetry = [];
+    this.domObserver = domObserver;
+    this.scheduler = new _harvestScheduler.HarvestScheduler('events', {
+      onFinished: this.onHarvestFinished.bind(this),
+      retryDelay: harvestTimeSeconds,
+      onUnload: () => this.interactionInProgress?.done() // return any held ajax or jserr events so they can be sent with EoL harvest
+    }, {
+      agentIdentifier,
+      ee: this.ee
+    });
+    this.scheduler.harvest.on('events', this.onHarvestStarted.bind(this));
+    this.initialPageLoadInteraction = new _initialPageLoadInteraction.InitialPageLoadInteraction(agentIdentifier);
+    _timeToFirstByte.timeToFirstByte.subscribe(_ref2 => {
+      let {
+        entries
+      } = _ref2;
+      const loadEventTime = entries[0].loadEventEnd;
+      this.initialPageLoadInteraction.forceSave = true;
+      this.initialPageLoadInteraction.done(loadEventTime);
+      this.interactionsToHarvest.push(this.initialPageLoadInteraction);
+      this.initialPageLoadInteraction = null;
+      // Report metric on the initial page load time
+      (0, _handle.handle)(_constants.SUPPORTABILITY_METRIC_CHANNEL, ['SoftNav/Interaction/InitialPageLoad/Duration/Ms', Math.round(loadEventTime)], undefined, _features.FEATURE_NAMES.metrics, this.ee);
+    });
+    this.latestRouteSetByApi = null;
+    this.interactionInProgress = null; // aside from the "page load" interaction, there can only ever be 1 ongoing at a time
+
+    this.blocked = false;
+    this.waitForFlags(['spa']).then(_ref3 => {
+      let [spaOn] = _ref3;
+      if (spaOn) this.scheduler.startTimer(harvestTimeSeconds, 0);else this.blocked = true; // if rum response determines that customer lacks entitlements for spa endpoint, this feature shouldn't harvest
+    });
+
+    // By default, a complete UI driven interaction requires event -> URL change -> DOM mod in that exact order.
+    (0, _registerHandler.registerHandler)('newUIEvent', event => this.startUIInteraction(event.type, event.timeStamp, event.target), this.featureName, this.ee);
+    (0, _registerHandler.registerHandler)('newURL', (timestamp, url) => this.interactionInProgress?.updateHistory(timestamp, url), this.featureName, this.ee);
+    (0, _registerHandler.registerHandler)('newDom', timestamp => {
+      this.interactionInProgress?.updateDom(timestamp);
+      if (this.interactionInProgress?.seenHistoryAndDomChange()) this.interactionInProgress.done();
+    }, this.featureName, this.ee);
+    this.#registerApiHandlers();
+    (0, _registerHandler.registerHandler)('ajax', this.#handleAjaxEvent.bind(this), this.featureName, this.ee);
+    (0, _registerHandler.registerHandler)('jserror', this.#handleJserror.bind(this), this.featureName, this.ee);
+    this.drain();
+  }
+  onHarvestStarted(options) {
+    if (this.interactionsToHarvest.length === 0 || this.blocked) return;
+
+    // The payload depacker takes the first ixn of a payload (if there are multiple ixns) and positively offset the subsequent ixns timestamps by that amount.
+    // In order to accurately portray the real start & end times of the 2nd & onward ixns, we hence need to negatively offset their start timestamps with that of the 1st ixn.
+    let firstIxnStartTime = 0; // the very 1st ixn does not require any offsetting
+    const serializedIxnList = [];
+    for (const interaction of this.interactionsToHarvest) {
+      serializedIxnList.push(interaction.serialize(firstIxnStartTime));
+      if (!firstIxnStartTime) firstIxnStartTime = Math.floor(interaction.start);
+    }
+    const payload = "bel.7;".concat(serializedIxnList.join(';'));
+    if (options.retry) this.interactionsAwaitingRetry.push(...this.interactionsToHarvest);
+    this.interactionsToHarvest = [];
+    return {
+      body: {
+        e: payload
+      }
+    };
+  }
+  onHarvestFinished(result) {
+    if (result.sent && result.retry && this.interactionsAwaitingRetry.length > 0) {
+      this.interactionsToHarvest = [...this.interactionsAwaitingRetry, ...this.interactionsToHarvest];
+      this.interactionsAwaitingRetry = [];
+    }
+  }
+  startUIInteraction(eventName, startedAt, sourceElem) {
+    // this is throttled by instrumentation so that it isn't excessively called
+    if (this.interactionInProgress?.createdByApi) return; // api-started interactions cannot be disrupted aka cancelled by UI events (and the vice versa applies as well)
+    if (this.interactionInProgress?.done() === false) return;
+    this.interactionInProgress = new _interaction.Interaction(this.agentIdentifier, eventName, startedAt, this.latestRouteSetByApi);
+    if (eventName === 'click') {
+      const sourceElemText = getActionText(sourceElem);
+      if (sourceElemText) this.interactionInProgress.customAttributes.actionText = sourceElemText;
+    }
+    this.interactionInProgress.cancellationTimer = setTimeout(() => {
+      this.interactionInProgress.done();
+      // Report metric on frequency of cancellation due to timeout for UI ixn
+      (0, _handle.handle)(_constants.SUPPORTABILITY_METRIC_CHANNEL, ['SoftNav/Interaction/TimeOut'], undefined, _features.FEATURE_NAMES.metrics, this.ee);
+    }, 30000); // UI ixn are disregarded after 30 seconds if it's not completed by then
+    this.setClosureHandlers();
+  }
+  setClosureHandlers() {
+    this.interactionInProgress.on('finished', () => {
+      const ref = this.interactionInProgress;
+      this.interactionsToHarvest.push(this.interactionInProgress);
+      this.interactionInProgress = null;
+      this.domObserver.disconnect(); // can stop observing whenever our interaction logic completes a cycle
+
+      // Report metric on the ixn duration
+      (0, _handle.handle)(_constants.SUPPORTABILITY_METRIC_CHANNEL, ["SoftNav/Interaction/".concat(ref.newURL !== ref.oldURL ? 'RouteChange' : 'Custom', "/Duration/Ms"), Math.round(ref.end - ref.start)], undefined, _features.FEATURE_NAMES.metrics, this.ee);
+    });
+    this.interactionInProgress.on('cancelled', () => {
+      this.interactionInProgress = null;
+      this.domObserver.disconnect();
+    });
+  }
+
+  /**
+   * Find the active interaction (current or past) for a given timestamp. Note that historic lookups mostly only go as far back as the last harvest for this feature.
+   * Also, the caller should check the status of the interaction returned if found via {@link Interaction.status}, if that's pertinent.
+   * TIP: Cancelled (status) interactions are NOT returned!
+   * IMPORTANT: Finished interactions are in queue for next harvest! It's highly recommended that consumer logic be synchronous for safe reference.
+   * @param {DOMHighResTimeStamp} timestamp
+   * @returns An {@link Interaction} or undefined, if no active interaction was found.
+   */
+  getInteractionFor(timestamp) {
+    /* In the sole case wherein there can be two "interactions" overlapping (initialPageLoad + regular route-change),
+      the regular interaction should get precedence in being assigned the "active" interaction in regards to our one-at-a-time model.
+    */
+    if (this.interactionInProgress?.isActiveDuring(timestamp)) return this.interactionInProgress;
+    let saveIxn;
+    for (let idx = this.interactionsToHarvest.length - 1; idx >= 0; idx--) {
+      // reverse search for the latest completed interaction for efficiency
+      const finishedInteraction = this.interactionsToHarvest[idx];
+      if (finishedInteraction.isActiveDuring(timestamp)) {
+        if (finishedInteraction.trigger !== 'initialPageLoad') return finishedInteraction;
+        // It's possible that a complete interaction occurs before page is fully loaded, so we need to consider if a route-change ixn may have overlapped this iPL
+        else saveIxn = finishedInteraction;
+      }
+    }
+    if (saveIxn) return saveIxn; // if an iPL was determined to be active and no route-change was found active for the same time, then iPL is deemed the one
+    if (this.initialPageLoadInteraction?.isActiveDuring(timestamp)) return this.initialPageLoadInteraction; // lowest precedence and also only if it's still in-progress
+    // Time must be when no interaction is happening, so return undefined.
+  }
+
+  /**
+   * Handles or redirect ajax event based on the interaction, if any, that it's tied to.
+   * @param {Object} event see Ajax feature's storeXhr function for object definition
+   */
+  #handleAjaxEvent(event) {
+    const associatedInteraction = this.getInteractionFor(event.startTime);
+    if (!associatedInteraction) {
+      // no interaction was happening when this ajax started, so give it back to Ajax feature for processing
+      (0, _handle.handle)('returnAjax', [event], undefined, _features.FEATURE_NAMES.ajax, this.ee);
+    } else {
+      if (associatedInteraction.status === _constants2.INTERACTION_STATUS.FIN) processAjax(this.agentIdentifier, event, associatedInteraction); // tack ajax onto the ixn object awaiting harvest
+      else {
+        // same thing as above, just at a later time -- if the interaction in progress is cancelled, just send the event back to ajax feat unmodified
+        associatedInteraction.on('finished', () => processAjax(this.agentIdentifier, event, associatedInteraction));
+        associatedInteraction.on('cancelled', () => (0, _handle.handle)('returnAjax', [event], undefined, _features.FEATURE_NAMES.ajax, this.ee));
+      }
+    }
+    function processAjax(agentId, event, parentInteraction) {
+      const newNode = new _ajaxNode.AjaxNode(agentId, event);
+      parentInteraction.addChild(newNode);
+    }
+  }
+
+  /**
+   * Decorate the passed-in params obj with properties relating to any associated interaction at the time of the timestamp.
+   * @param {Object} params reference to the local var instance in Jserrors feature's storeError
+   * @param {DOMHighResTimeStamp} timestamp time the jserror occurred
+   */
+  #handleJserror(params, timestamp) {
+    const associatedInteraction = this.getInteractionFor(timestamp);
+    if (!associatedInteraction) return; // do not need to decorate this jserror params
+
+    // Whether the interaction is in-progress or already finished, the id will let jserror buffer it under its index, until it gets the next step instruction.
+    params.browserInteractionId = associatedInteraction.id;
+    if (associatedInteraction.status === _constants2.INTERACTION_STATUS.FIN) {
+      // This information cannot be relayed back via handle() that flushes buffered errs because this is being called by a jserror's handle() per se and before the err is buffered.
+      params._softNavFinished = true; // instead, signal that this err can be processed right away without needing to be buffered aka wait for an in-progress ixn
+      params._softNavAttributes = associatedInteraction.customAttributes;
+    } else {
+      // These callbacks may be added multiple times for an ixn, but just a single run will deal with all jserrors associated with the interaction.
+      // As such, be cautious not to use the params object since that's tied to one specific jserror and won't affect the rest of them.
+      associatedInteraction.on('finished', (0, _invoke.single)(() => (0, _handle.handle)('softNavFlush', [associatedInteraction.id, true, associatedInteraction.customAttributes], undefined, _features.FEATURE_NAMES.jserrors, this.ee)));
+      associatedInteraction.on('cancelled', (0, _invoke.single)(() => (0, _handle.handle)('softNavFlush', [associatedInteraction.id, false, undefined], undefined, _features.FEATURE_NAMES.jserrors, this.ee))); // don't take custom attrs from cancelled ixns
+    }
+  }
+  #registerApiHandlers() {
+    const INTERACTION_API = 'api-ixn-';
+    const thisClass = this;
+    (0, _registerHandler.registerHandler)(INTERACTION_API + 'get', function (time) {
+      let {
+        waitForEnd
+      } = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+      // In here, 'this' refers to the EventContext specific to per InteractionHandle instance spawned by each .interaction() api call.
+      // Each api call aka IH instance would therefore retain a reference to either the in-progress interaction *at the time of the call* OR a new api-started interaction.
+      this.associatedInteraction = thisClass.getInteractionFor(time);
+      if (!this.associatedInteraction) {
+        // This new api-driven interaction will be the target of any subsequent .interaction() call, until it is closed by EITHER .end() OR the regular seenHistoryAndDomChange process.
+        this.associatedInteraction = thisClass.interactionInProgress = new _interaction.Interaction(thisClass.agentIdentifier, _constants2.API_TRIGGER_NAME, time, thisClass.latestRouteSetByApi);
+        thisClass.setClosureHandlers();
+      }
+      if (waitForEnd === true) this.associatedInteraction.keepOpenUntilEndApi = true;
+    }, thisClass.featureName, thisClass.ee);
+    (0, _registerHandler.registerHandler)(INTERACTION_API + 'end', function (timeNow) {
+      this.associatedInteraction.done(timeNow);
+    }, thisClass.featureName, thisClass.ee);
+    (0, _registerHandler.registerHandler)(INTERACTION_API + 'save', function () {
+      this.associatedInteraction.forceSave = true;
+    }, thisClass.featureName, thisClass.ee);
+    (0, _registerHandler.registerHandler)(INTERACTION_API + 'ignore', function () {
+      this.associatedInteraction.forceIgnore = true;
+    }, thisClass.featureName, thisClass.ee);
+    (0, _registerHandler.registerHandler)(INTERACTION_API + 'getContext', function (time, callback) {
+      if (typeof callback !== 'function') return;
+      setTimeout(() => callback(this.associatedInteraction.customDataByApi), 0);
+    }, thisClass.featureName, thisClass.ee);
+    (0, _registerHandler.registerHandler)(INTERACTION_API + 'onEnd', function (time, callback) {
+      if (typeof callback !== 'function') return;
+      this.associatedInteraction.onDone.push(callback);
+    }, thisClass.featureName, thisClass.ee);
+    (0, _registerHandler.registerHandler)(INTERACTION_API + 'actionText', function (time, newActionText) {
+      if (newActionText) this.associatedInteraction.customAttributes.actionText = newActionText;
+    }, thisClass.featureName, thisClass.ee);
+    (0, _registerHandler.registerHandler)(INTERACTION_API + 'setName', function (time, name, trigger) {
+      if (name) this.associatedInteraction.customName = name;
+      if (trigger) this.associatedInteraction.trigger = trigger;
+    }, thisClass.featureName, thisClass.ee);
+    (0, _registerHandler.registerHandler)(INTERACTION_API + 'setAttribute', function (time, key, value) {
+      this.associatedInteraction.customAttributes[key] = value;
+    }, thisClass.featureName, thisClass.ee);
+    (0, _registerHandler.registerHandler)(INTERACTION_API + 'routeName', function (time, newRouteName) {
+      // notice that this fn tampers with the ixn IP, not with the linked ixn
+      thisClass.latestRouteSetByApi = newRouteName;
+      if (thisClass.interactionInProgress) thisClass.interactionInProgress.newRoute = newRouteName;
+    }, thisClass.featureName, thisClass.ee);
+  }
+}
+exports.Aggregate = Aggregate;
+function getActionText(elem) {
+  const tagName = elem.tagName.toLowerCase();
+  const elementsOfInterest = ['a', 'button', 'input'];
+  if (elementsOfInterest.includes(tagName)) {
+    return elem.title || elem.value || elem.innerText;
+  }
+}

package/dist/cjs/features/soft_navigations/aggregate/initial-page-load-interaction.js

@@ -0,0 +1,62 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.InitialPageLoadInteraction = void 0;
+var _navTiming = require("../../../common/timing/nav-timing");
+var _interaction = require("./interaction");
+var _belSerializer = require("../../../common/serialize/bel-serializer");
+var _firstPaint = require("../../../common/vitals/first-paint");
+var _firstContentfulPaint = require("../../../common/vitals/first-contentful-paint");
+var _config = require("../../../common/config/config");
+class InitialPageLoadInteraction extends _interaction.Interaction {
+  constructor(agentIdentifier) {
+    super(agentIdentifier, 'initialPageLoad', 0, null);
+    const agentInfo = (0, _config.getInfo)(agentIdentifier);
+    this.queueTime = agentInfo.queueTime;
+    this.appTime = agentInfo.applicationTime;
+  }
+  get firstPaint() {
+    return _firstPaint.firstPaint.current.value;
+  }
+  get firstContentfulPaint() {
+    return _firstContentfulPaint.firstContentfulPaint.current.value;
+  }
+
+  /**
+   * Build the navTiming node. This assumes the navTimingValues array in nav-timing.js has already been filled with values via the PageViewEvent feature having
+   * executed the addPT function first and foremost.
+   */
+  get navTiming() {
+    if (!_navTiming.navTimingValues.length) return;
+    /*
+    1. we initialize the seperator to ',' (seperates the nodeType id from the first value)
+    2. we initialize the navTiming node to 'b' (the nodeType id)
+    3. if the value is present, we add the seperator followed by the value;
+       otherwise:
+        - we add null seperator ('!') to the navTimingNode
+        - we set the seperator to an empty string since we already wrote it above
+      the reason for writing the null seperator instead of setting the seperator
+      is to ensure we still write it if the null is the last navTiming value.
+    */
+    let seperator = ',';
+    let navTimingNode = 'b';
+    let prev = 0;
+
+    // Get all navTiming values except offset aka timeOrigin since we just consider that (this.start) 0.
+    // These are the latter 20 of the 21 timings appended by addPT:
+    _navTiming.navTimingValues.slice(1, 21).forEach(v => {
+      if (v !== undefined) {
+        navTimingNode += seperator + (0, _belSerializer.numeric)(v - prev);
+        seperator = ',';
+        prev = v;
+      } else {
+        navTimingNode += seperator + '!';
+        seperator = '';
+      }
+    });
+    return navTimingNode;
+  }
+}
+exports.InitialPageLoadInteraction = InitialPageLoadInteraction;

package/dist/cjs/features/soft_navigations/aggregate/interaction.js

@@ -0,0 +1,146 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.Interaction = void 0;
+var _config = require("../../../common/config/config");
+var _runtime = require("../../../common/constants/runtime");
+var _uniqueId = require("../../../common/ids/unique-id");
+var _belSerializer = require("../../../common/serialize/bel-serializer");
+var _cleanUrl = require("../../../common/url/clean-url");
+var _constants = require("../constants");
+var _belNode = require("./bel-node");
+/**
+ * link https://github.com/newrelic/nr-querypack/blob/main/schemas/bel/7.qpschema
+ **/
+class Interaction extends _belNode.BelNode {
+  id = (0, _uniqueId.generateUuid)(); // unique id that is serialized and used to link interactions with errors
+  initialPageURL = _runtime.initialLocation;
+  oldURL = '' + _runtime.globalScope?.location;
+  newURL = '' + _runtime.globalScope?.location;
+  customName;
+  customAttributes = {};
+  customDataByApi = {};
+  queueTime; // only used by initialPageLoad interactions
+  appTime; // only used by initialPageLoad interactions
+  newRoute;
+  /** Internal state of this interaction: in-progress, finished, or cancelled. */
+  status = _constants.INTERACTION_STATUS.IP;
+  domTimestamp = 0;
+  historyTimestamp = 0;
+  createdByApi = false;
+  keepOpenUntilEndApi = false;
+  onDone = [];
+  cancellationTimer;
+  constructor(agentIdentifier, uiEvent, uiEventTimestamp, currentRouteKnown) {
+    super(agentIdentifier);
+    this.belType = _constants.NODE_TYPE.INTERACTION;
+    this.trigger = uiEvent;
+    this.start = uiEventTimestamp;
+    this.oldRoute = currentRouteKnown;
+    this.eventSubscription = new Map([['finished', []], ['cancelled', []]]);
+    this.forceSave = this.forceIgnore = false;
+    if (this.trigger === _constants.API_TRIGGER_NAME) this.createdByApi = true;
+  }
+  updateDom(timestamp) {
+    this.domTimestamp = timestamp || performance.now(); // default timestamp should be precise for accurate isActiveDuring calculations
+  }
+  updateHistory(timestamp, newUrl) {
+    this.newURL = newUrl || '' + _runtime.globalScope?.location;
+    this.historyTimestamp = timestamp || performance.now();
+  }
+  seenHistoryAndDomChange() {
+    return this.historyTimestamp > 0 && this.domTimestamp > this.historyTimestamp; // URL must change before DOM does
+  }
+  on(event, cb) {
+    if (!this.eventSubscription.has(event)) throw new Error('Cannot subscribe to non pre-defined events.');
+    if (typeof cb !== 'function') throw new Error('Must supply function as callback.');
+    this.eventSubscription.get(event).push(cb);
+  }
+  done(customEndTime) {
+    // User could've mark this interaction--regardless UI or api started--as "don't close until .end() is called on it". Only .end provides a timestamp; the default flows do not.
+    if (this.keepOpenUntilEndApi && customEndTime === undefined) return false;
+    this.onDone.forEach(apiProvidedCb => apiProvidedCb(this.customDataByApi)); // this interaction's .save or .ignore can still be set by these user provided callbacks for example
+
+    if (this.forceIgnore) this.#cancel(); // .ignore() always has precedence over save actions
+    else if (this.seenHistoryAndDomChange()) this.#finish(customEndTime); // then this should've already finished while it was the interactionInProgress, with a natural end time
+    else if (this.forceSave) this.#finish(customEndTime || performance.now()); // a manually saved ixn (did not fulfill conditions) must have a specified end time, if one wasn't provided
+    else this.#cancel();
+    return true;
+  }
+  #finish() {
+    let customEndTime = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : 0;
+    if (this.status !== _constants.INTERACTION_STATUS.IP) return; // disallow this call if the ixn is already done aka not in-progress
+    clearTimeout(this.cancellationTimer);
+    this.end = Math.max(this.domTimestamp, this.historyTimestamp, customEndTime);
+    this.customAttributes = {
+      ...(0, _config.getInfo)(this.agentIdentifier).jsAttributes,
+      ...this.customAttributes
+    }; // attrs specific to this interaction should have precedence over the general custom attrs
+    this.status = _constants.INTERACTION_STATUS.FIN;
+
+    // Run all the callbacks awaiting this interaction to finish.
+    const callbacks = this.eventSubscription.get('finished');
+    callbacks.forEach(fn => fn());
+  }
+  #cancel() {
+    if (this.status !== _constants.INTERACTION_STATUS.IP) return; // disallow this call if the ixn is already done aka not in-progress
+    clearTimeout(this.cancellationTimer);
+    this.status = _constants.INTERACTION_STATUS.CAN;
+
+    // Run all the callbacks listening to this interaction's potential cancellation.
+    const callbacks = this.eventSubscription.get('cancelled');
+    callbacks.forEach(fn => fn());
+  }
+
+  /**
+   * Given a timestamp, determine if it falls within this interaction's span, i.e. if this was the active interaction during that time.
+   * For in-progress interactions, this only compares the time with the start of span. Cancelled interactions are not considered active at all.
+   * @param {DOMHighResTimeStamp} timestamp
+   * @returns True or false boolean.
+   */
+  isActiveDuring(timestamp) {
+    if (this.status === _constants.INTERACTION_STATUS.IP) return this.start <= timestamp;
+    return this.status === _constants.INTERACTION_STATUS.FIN && this.start <= timestamp && this.end >= timestamp;
+  }
+
+  // Following are virtual properties overridden by a subclass:
+  get firstPaint() {}
+  get firstContentfulPaint() {}
+  get navTiming() {}
+  serialize(firstStartTimeOfPayload) {
+    const addString = (0, _belSerializer.getAddStringContext)(this.agentIdentifier);
+    const nodeList = [];
+    let ixnType;
+    if (this.trigger === 'initialPageLoad') ixnType = _constants.INTERACTION_TYPE.INITIAL_PAGE_LOAD;else if (this.newURL !== this.oldURL) ixnType = _constants.INTERACTION_TYPE.ROUTE_CHANGE;else ixnType = _constants.INTERACTION_TYPE.UNSPECIFIED;
+
+    // IMPORTANT: The order in which addString is called matters and correlates to the order in which string shows up in the harvest payload. Do not re-order the following code.
+    const fields = [(0, _belSerializer.numeric)(this.belType), 0,
+    // this will be overwritten below with number of attached nodes
+    (0, _belSerializer.numeric)(Math.floor(this.start - firstStartTimeOfPayload)),
+    // relative to first node
+    (0, _belSerializer.numeric)(Math.floor(this.end - this.start)),
+    // end -- relative to start
+    (0, _belSerializer.numeric)(this.callbackEnd),
+    // cbEnd -- relative to start; not used by BrowserInteraction events
+    (0, _belSerializer.numeric)(this.callbackDuration),
+    // not relative
+    addString(this.trigger), addString((0, _cleanUrl.cleanURL)(this.initialPageURL, true)), addString((0, _cleanUrl.cleanURL)(this.oldURL, true)), addString((0, _cleanUrl.cleanURL)(this.newURL, true)), addString(this.customName), ixnType, (0, _belSerializer.nullable)(this.queueTime, _belSerializer.numeric, true) + (0, _belSerializer.nullable)(this.appTime, _belSerializer.numeric, true) + (0, _belSerializer.nullable)(this.oldRoute, addString, true) + (0, _belSerializer.nullable)(this.newRoute, addString, true) + addString(this.id), addString(this.nodeId), (0, _belSerializer.nullable)(this.firstPaint, _belSerializer.numeric, true) + (0, _belSerializer.nullable)(this.firstContentfulPaint, _belSerializer.numeric)];
+    const allAttachedNodes = (0, _belSerializer.addCustomAttributes)(this.customAttributes || {}, addString); // start with all custom attributes
+    if ((0, _config.getInfo)(this.agentIdentifier).atts) allAttachedNodes.push('a,' + addString((0, _config.getInfo)(this.agentIdentifier).atts)); // add apm provided attributes
+    /* Querypack encoder+decoder quirkiness:
+       - If first ixn node of payload is being processed, we use this node's start to offset. (firstStartTime should be 0--or undefined.)
+       - Else for subsequent ixn nodes, we use the first ixn node's start to offset. */
+    this.children.forEach(node => allAttachedNodes.push(node.serialize(firstStartTimeOfPayload || this.start))); // recursively add the serialized string of every child of this (ixn) bel node
+
+    fields[1] = (0, _belSerializer.numeric)(allAttachedNodes.length);
+    nodeList.push(fields);
+    if (allAttachedNodes.length) nodeList.push(allAttachedNodes.join(';'));
+    if (this.navTiming) nodeList.push(this.navTiming);else nodeList.push('');
+    // nodeList = [<fields array>, <serialized string of all attributes and children>, <serialized nav timing info> || '']
+
+    return nodeList.join(';');
+  }
+}
+exports.Interaction = Interaction;

package/dist/cjs/features/soft_navigations/constants.js

@@ -0,0 +1,31 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.NODE_TYPE = exports.INTERACTION_TYPE = exports.INTERACTION_TRIGGERS = exports.INTERACTION_STATUS = exports.FEATURE_NAME = exports.API_TRIGGER_NAME = void 0;
+var _features = require("../../loaders/features/features");
+const INTERACTION_TRIGGERS = exports.INTERACTION_TRIGGERS = ['click',
+// e.g. user clicks link or the page back/forward buttons
+'keydown',
+// e.g. user presses left and right arrow key to switch between displayed photo gallery
+'submit' // e.g. user clicks submit butotn or presses enter while editing a form field
+];
+const API_TRIGGER_NAME = exports.API_TRIGGER_NAME = 'api';
+const FEATURE_NAME = exports.FEATURE_NAME = _features.FEATURE_NAMES.softNav;
+const INTERACTION_TYPE = exports.INTERACTION_TYPE = {
+  INITIAL_PAGE_LOAD: '',
+  ROUTE_CHANGE: 1,
+  UNSPECIFIED: 2
+};
+const NODE_TYPE = exports.NODE_TYPE = {
+  INTERACTION: 1,
+  AJAX: 2,
+  CUSTOM_END: 3,
+  CUSTOM_TRACER: 4
+};
+const INTERACTION_STATUS = exports.INTERACTION_STATUS = {
+  IP: 'in progress',
+  FIN: 'finished',
+  CAN: 'cancelled'
+};

package/dist/cjs/features/soft_navigations/index.js

@@ -0,0 +1,12 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "SoftNav", {
+  enumerable: true,
+  get: function () {
+    return _index.Instrument;
+  }
+});
+var _index = require("./instrument/index");