@newrelic/browser-agent 1.289.0 → 1.290.0

package/dist/cjs/loaders/api/register.js

@@ -0,0 +1,182 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.buildRegisterApi = buildRegisterApi;
+exports.setupRegisterAPI = setupRegisterAPI;
+var _handle = require("../../common/event-emitter/handle");
+var _console = require("../../common/util/console");
+var _target = require("../../common/util/target");
+var _features = require("../features/features");
+var _now = require("../../common/timing/now");
+var _constants = require("../../features/metrics/constants");
+var _sharedHandlers = require("./sharedHandlers");
+var _constants2 = require("./constants");
+var _log = require("./log");
+var _addPageAction = require("./addPageAction");
+var _noticeError = require("./noticeError");
+/**
+ * Copyright 2020-2025 New Relic, Inc. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @typedef {import('./register-api-types').RegisterAPI} RegisterAPI
+ */
+
+/**
+ * @experimental
+ * IMPORTANT: This feature is being developed for use internally and is not in a public-facing production-ready state.
+ * It is not recommended for use in production environments and will not receive support for issues.
+ */
+function setupRegisterAPI(agent) {
+  (0, _sharedHandlers.setupAPI)(_constants2.REGISTER, function (target) {
+    return buildRegisterApi(agent, target);
+  }, agent);
+}
+
+/**
+ * Builds the api object that will be returned from the register api method.
+ * Also conducts certain side-effects, such as harvesting a PageView event when triggered and gathering metadata for the registered entity.
+ * @param {Object} agentRef the reference to the base agent instance
+ * @param {Object} handlers the shared handlers to be used by both the base agent's API and the external target's API
+ * @param {Object} target the target information to be used by the external target's API to send data to the correct location
+ * @returns {RegisterAPI} the api object to be returned from the register api method
+ */
+function buildRegisterApi(agentRef, target) {
+  const attrs = {};
+  (0, _console.warn)(54, 'newrelic.register');
+
+  /** @type {Function|undefined} a function that is set and reports when APIs are triggered -- warns the customer of the invalid state  */
+  let invalidApiResponse;
+
+  /**
+       * A promise that indicates when all needed connections for the registered child to be ready to report data
+       * 1. The main agent to be ready (made a RUM call and got its entity guid)
+       * 2. The child to be registered with the main agent (made its own RUM call and got its entity guid)
+       * @type {Promise<RegisterAPI>}
+       */
+  let _connected;
+  if (!agentRef.init.api.allow_registered_children) invalidApiResponse = () => (0, _console.warn)(55);
+  if (!target || !(0, _target.isValidTarget)(target)) invalidApiResponse = () => (0, _console.warn)(48, target);
+
+  /** @type {RegisterAPI} */
+  const api = {
+    addPageAction: (name, attributes = {}) => {
+      report(_addPageAction.addPageAction, [name, {
+        ...attrs,
+        ...attributes
+      }, agentRef], target);
+    },
+    log: (message, options = {}) => {
+      report(_log.log, [message, {
+        ...options,
+        customAttributes: {
+          ...attrs,
+          ...(options.customAttributes || {})
+        }
+      }, agentRef], target);
+    },
+    noticeError: (error, attributes = {}) => {
+      report(_noticeError.noticeError, [error, {
+        ...attrs,
+        ...attributes
+      }, agentRef], target);
+    },
+    setApplicationVersion: value => {
+      attrs['application.version'] = value;
+    },
+    setCustomAttribute: (key, value) => {
+      attrs[key] = value;
+    },
+    setUserId: value => {
+      attrs['enduser.id'] = value;
+    },
+    /** metadata */
+    metadata: {
+      customAttributes: attrs,
+      target,
+      /** set in a getter so that later access of the Promise is not polluted before customer is allowed to set a catch block */
+      get connected() {
+        return _connected || Promise.reject(new Error('Failed to connect'));
+      }
+    }
+  };
+  if (invalidApiResponse) {
+    invalidApiResponse();
+  } else {
+    _connected = new Promise((resolve, reject) => {
+      try {
+        const entityManager = agentRef.runtime?.entityManager;
+        /** check if main agent already has main agent entity guid */
+        let mainAgentReady = !!entityManager?.get().entityGuid;
+        /** check if registered target already has entity guid */
+        let registeredEntityGuid = entityManager?.getEntityGuidFor(target.licenseKey, target.applicationID);
+        let registrationReady = !!registeredEntityGuid;
+
+        /** check if we can just resolve immediately without making another connect call */
+        if (mainAgentReady && registrationReady) {
+          target.entityGuid = registeredEntityGuid;
+          resolve(api);
+        } else {
+          /** we need to make a new connection call since we dont already have a registered entity for this call */
+
+          /** if the connect callback doesnt resolve in 15 seconds... reject */
+          const timeout = setTimeout(() => reject(new Error('Failed to connect - Timeout')), 15000);
+
+          // tell the main agent to send a rum call for this target
+          // when the rum call resolves, it will emit an "entity-added" event, see below
+          agentRef.ee.emit('api-send-rum', [attrs, target]);
+
+          // wait for entity events to emit to see when main agent and/or API registration is ready
+          agentRef.ee.on('entity-added', entityEventHandler);
+          function entityEventHandler(entity) {
+            if ((0, _target.isContainerAgentTarget)(entity, agentRef)) mainAgentReady ||= true;else {
+              if (target.licenseKey === entity.licenseKey && target.applicationID === entity.applicationID) {
+                registrationReady = true;
+                target.entityGuid = entity.entityGuid;
+              }
+            }
+            if (mainAgentReady && registrationReady) {
+              clearTimeout(timeout);
+              // unsubscribe from the event emitter
+              agentRef.ee.removeEventListener('entity-added', entityEventHandler);
+              resolve(api);
+            }
+          }
+        }
+      } catch (err) {
+        reject(err);
+      }
+    });
+  }
+
+  /**
+     * The reporter method that will be used to report the data to the container agent's API method. If invalid, will log a warning and not execute.
+     * If the api.duplicate_registered_data configuration value is set to true, the data will be reported to BOTH the container and the external target
+     * @param {*} methodToCall the container agent's API method to call
+     * @param {*} args the arguments to supply to the container agent's API method
+     * @param {string} targetEntityGuid the target entity guid, which looks up the target to report the data to from the entity manager. If undefined, will report to the container agent's target.
+     * @returns
+     */
+  const report = async (methodToCall, args, target) => {
+    if (invalidApiResponse) return invalidApiResponse();
+    /** set the timestamp before the async part of waiting for the rum response for better accuracy */
+    const timestamp = (0, _now.now)();
+    (0, _handle.handle)(_constants.SUPPORTABILITY_METRIC_CHANNEL, ["API/register/".concat(methodToCall.name, "/called")], undefined, _features.FEATURE_NAMES.metrics, agentRef.ee);
+    try {
+      await _connected;
+      // target should be decorated with entityGuid by the rum resp at this point
+      const shouldDuplicate = agentRef.init.api.duplicate_registered_data;
+      if (shouldDuplicate === true || Array.isArray(shouldDuplicate) && shouldDuplicate.includes(target.entityGuid)) {
+        // also report to container by providing undefined target
+        methodToCall(...args, undefined, timestamp);
+      }
+      methodToCall(...args, target.entityGuid, timestamp); // always report to target
+    } catch (err) {
+      (0, _console.warn)(50, err);
+    }
+  };
+  return api;
+}

package/dist/cjs/loaders/api/setApplicationVersion.js

@@ -0,0 +1,28 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.setupSetApplicationVersionAPI = setupSetApplicationVersionAPI;
+var _console = require("../../common/util/console");
+var _constants = require("./constants");
+var _sharedHandlers = require("./sharedHandlers");
+/**
+ * Copyright 2020-2025 New Relic, Inc. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+function setupSetApplicationVersionAPI(agent) {
+  /**
+   * Attach the 'applcation.version' attribute onto agent payloads. This may be used in NR queries to group all browser events by a specific customer-defined release.
+   * @param {string|null} value - Application version -- if null, will "unset" the value
+   * @returns @see apiCall
+   */
+  (0, _sharedHandlers.setupAPI)(_constants.SET_APPLICATION_VERSION, function (value) {
+    if (!(typeof value === 'string' || value === null)) {
+      (0, _console.warn)(42, typeof value);
+      return;
+    }
+    return (0, _sharedHandlers.appendJsAttribute)(agent, 'application.version', value, _constants.SET_APPLICATION_VERSION, false);
+  }, agent);
+}

package/dist/cjs/loaders/api/setCustomAttribute.js

@@ -0,0 +1,27 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.setupSetCustomAttributeAPI = setupSetCustomAttributeAPI;
+var _console = require("../../common/util/console");
+var _constants = require("./constants");
+var _sharedHandlers = require("./sharedHandlers");
+/**
+ * Copyright 2020-2025 New Relic, Inc. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+function setupSetCustomAttributeAPI(agent) {
+  (0, _sharedHandlers.setupAPI)(_constants.SET_CUSTOM_ATTRIBUTE, function (name, value, persistAttribute = false) {
+    if (typeof name !== 'string') {
+      (0, _console.warn)(39, typeof name);
+      return;
+    }
+    if (!(['string', 'number', 'boolean'].includes(typeof value) || value === null)) {
+      (0, _console.warn)(40, typeof value);
+      return;
+    }
+    return (0, _sharedHandlers.appendJsAttribute)(agent, name, value, _constants.SET_CUSTOM_ATTRIBUTE, persistAttribute);
+  }, agent);
+}

package/dist/cjs/loaders/api/setErrorHandler.js

@@ -0,0 +1,18 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.setupSetErrorHandlerAPI = setupSetErrorHandlerAPI;
+var _constants = require("./constants");
+var _sharedHandlers = require("./sharedHandlers");
+/**
+ * Copyright 2020-2025 New Relic, Inc. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+function setupSetErrorHandlerAPI(agent) {
+  (0, _sharedHandlers.setupAPI)(_constants.SET_ERROR_HANDLER, function (callback) {
+    agent.runtime.onerror = callback;
+  }, agent);
+}

package/dist/cjs/loaders/api/setPageViewName.js

@@ -0,0 +1,23 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.setupSetPageViewNameAPI = setupSetPageViewNameAPI;
+var _handle = require("../../common/event-emitter/handle");
+var _now = require("../../common/timing/now");
+var _constants = require("./constants");
+var _sharedHandlers = require("./sharedHandlers");
+/**
+ * Copyright 2020-2025 New Relic, Inc. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+function setupSetPageViewNameAPI(agent) {
+  (0, _sharedHandlers.setupAPI)(_constants.SET_PAGE_VIEW_NAME, function (name, host) {
+    if (typeof name !== 'string') return;
+    if (name.charAt(0) !== '/') name = '/' + name;
+    agent.runtime.customTransaction = (host || 'http://custom.transaction') + name;
+    (0, _handle.handle)(_constants.prefix + _constants.SET_PAGE_VIEW_NAME, [(0, _now.now)()], undefined, undefined, agent.ee);
+  }, agent);
+}

package/dist/cjs/loaders/api/setUserId.js

@@ -0,0 +1,28 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.setupSetUserIdAPI = setupSetUserIdAPI;
+var _console = require("../../common/util/console");
+var _constants = require("./constants");
+var _sharedHandlers = require("./sharedHandlers");
+/**
+ * Copyright 2020-2025 New Relic, Inc. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+function setupSetUserIdAPI(agent) {
+  /**
+    * Attach the 'enduser.id' attribute onto agent payloads. This may be used in NR queries to group all browser events by specific users.
+    * @param {string} value - unique user identifier; a null user id suggests none should exist
+    * @returns @see apiCall
+    */
+  (0, _sharedHandlers.setupAPI)(_constants.SET_USER_ID, function (value) {
+    if (!(typeof value === 'string' || value === null)) {
+      (0, _console.warn)(41, typeof value);
+      return;
+    }
+    return (0, _sharedHandlers.appendJsAttribute)(agent, 'enduser.id', value, _constants.SET_USER_ID, true);
+  }, agent);
+}

package/dist/cjs/loaders/api/sharedHandlers.js

@@ -0,0 +1,76 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.appendJsAttribute = appendJsAttribute;
+exports.setupAPI = setupAPI;
+var _globalEvent = require("../../common/dispatch/global-event");
+var _handle = require("../../common/event-emitter/handle");
+var _now = require("../../common/timing/now");
+var _console = require("../../common/util/console");
+var _featureFlags = require("../../common/util/feature-flags");
+var _constants = require("../../features/metrics/constants");
+var _agentBase = require("../agent-base");
+var _features = require("../features/features");
+var _constants2 = require("./constants");
+/**
+ * Copyright 2020-2025 New Relic, Inc. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * setupAPI is a utility function that assigns API methods to an object while emitting supportability metrics and global events.
+ * @param {string} name The API method name to be set up.
+ * @param {Function} fn The function to be executed when the API method is called.
+ * @param {Object} agent The agent instance.  Will be used if no object is provided to assign the api method to.
+ * @param {Object} [obj] The object to which the API method will be assigned.
+ * @returns {*} The output of the function being called.
+ */
+function setupAPI(name, fn, agent, obj) {
+  /* use object if provided, otherwise use agent as base for api method assignment */
+  const api = obj || agent;
+  // We only set the global API event if the API is not already overridden from the default
+  if (!api || !!api[name] && api[name] !== _agentBase.AgentBase.prototype[name]) return;
+  api[name] = function () {
+    (0, _handle.handle)(_constants.SUPPORTABILITY_METRIC_CHANNEL, ['API/' + name + '/called'], undefined, _features.FEATURE_NAMES.metrics, agent.ee);
+    (0, _globalEvent.dispatchGlobalEvent)({
+      agentIdentifier: agent.agentIdentifier,
+      drained: !!_featureFlags.activatedFeatures?.[agent.agentIdentifier],
+      type: 'data',
+      name: 'api',
+      feature: _constants2.prefix + name,
+      data: {}
+    });
+    try {
+      return fn.apply(this, arguments);
+    } catch (err) {
+      (0, _console.warn)(23, err);
+    }
+  };
+}
+
+/**
+   * Attach the key-value attribute onto agent payloads. All browser events in NR will be affected.
+   * @param {Agent} agent the agent instance reference
+   * @param {string} key
+   * @param {string|number|boolean|null} value - null indicates the key should be removed or erased
+   * @param {string} apiName
+   * @param {boolean} addToBrowserStorage - whether this attribute should be stored in browser storage API and retrieved by the next agent context or initialization
+   * @returns @see apiCall
+   */
+function appendJsAttribute(agent, key, value, apiName, addToBrowserStorage) {
+  const currentInfo = agent.info;
+  if (value === null) {
+    delete currentInfo.jsAttributes[key];
+  } else {
+    agent.info = {
+      ...agent.info,
+      jsAttributes: {
+        ...currentInfo.jsAttributes,
+        [key]: value
+      }
+    };
+  }
+  if (addToBrowserStorage || value === null) (0, _handle.handle)(_constants2.prefix + apiName, [(0, _now.now)(), key, value], undefined, 'session', agent.ee);
+}

package/dist/cjs/loaders/api/start.js

@@ -0,0 +1,18 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.setupStartAPI = setupStartAPI;
+var _constants = require("./constants");
+var _sharedHandlers = require("./sharedHandlers");
+/**
+ * Copyright 2020-2025 New Relic, Inc. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+function setupStartAPI(agent) {
+  (0, _sharedHandlers.setupAPI)(_constants.START, function () {
+    agent.ee.emit('manual-start-all');
+  }, agent);
+}

package/dist/cjs/loaders/api/topLevelCallers.js

@@ -0,0 +1,29 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.setTopLevelCallers = setTopLevelCallers;
+var _nreum = require("../../common/window/nreum");
+var _apiBase = require("../api-base");
+/**
+ * Copyright 2020-2025 New Relic, Inc. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+function setTopLevelCallers(agentRef) {
+  const nr = (0, _nreum.gosCDN)();
+  Object.getOwnPropertyNames(_apiBase.ApiBase.prototype).forEach(fnName => {
+    const origFn = _apiBase.ApiBase.prototype[fnName];
+    if (typeof origFn !== 'function' || origFn === 'constructor') return;
+    /** if the method already exists on the top and we are allowed to -- we can call it multiple times */
+    let origNrFn = nr[fnName];
+    if (!agentRef[fnName] || agentRef.exposed === false || agentRef.runtime?.loaderType === 'micro-agent') return; // dont set the top level callers if we are not allowed to
+
+    nr[fnName] = (...args) => {
+      const thisAgentFnResult = agentRef[fnName](...args);
+      if (!origNrFn) return thisAgentFnResult;
+      return origNrFn(...args); // if origFn is defined, we want to return the value from that call (ie the first agent that was set)
+    };
+  });
+}

package/dist/cjs/loaders/api/wrapLogger.js

@@ -0,0 +1,26 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.setupWrapLoggerAPI = setupWrapLoggerAPI;
+var _wrapLogger = require("../../common/wrap/wrap-logger");
+var _constants = require("../../features/logging/constants");
+var _constants2 = require("./constants");
+var _sharedHandlers = require("./sharedHandlers");
+/**
+ * Copyright 2020-2025 New Relic, Inc. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+function setupWrapLoggerAPI(agent) {
+  (0, _sharedHandlers.setupAPI)(_constants2.WRAP_LOGGER, (parent, functionName, {
+    customAttributes = {},
+    level = _constants.LOG_LEVELS.INFO
+  } = {}) => {
+    (0, _wrapLogger.wrapLogger)(agent.ee, parent, functionName, {
+      customAttributes,
+      level
+    });
+  }, agent);
+}