@newrelic/browser-agent 1.234.0 → 1.235.0

package/dist/types/features/utils/aggregate-base.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"aggregate-base.d.ts","sourceRoot":"","sources":["../../../../src/features/utils/aggregate-base.js"],"names":[],"mappings":"AAMA;IACE,4BAGC;IAED,gDAUC;IAED;;;OAGG;IACH,2BAqBC;CACF;4BAjD2B,gBAAgB"}
+{"version":3,"file":"aggregate-base.d.ts","sourceRoot":"","sources":["../../../../src/features/utils/aggregate-base.js"],"names":[],"mappings":"AAMA;IACE,4BAGC;IAED;;;;OAIG;IACH,yBAHW,MAAM,EAAE,kBAWlB;IAED;;;OAGG;IACH,2BAqBC;CACF;4BApD2B,gBAAgB"}

package/dist/types/features/utils/handler-cache.d.ts

@@ -3,20 +3,21 @@
  */
 export class HandlerCache {
     /**
-       * Wrap callback functions with this method to defer their execution until a decision has been reached
-       * @param {Function} handler
-       * @returns {void}
-       */
+     * Wrap callback functions with this method to defer their execution until a decision has been reached
+     * @param {Function} handler
+     * @returns {void}
+     */
     settle(handler: Function): void;
     /**
-       * Make a decision about what to do with the cache of callbacks.
-       * --- if true: tell the handlerCache that its ok to immediately execute the callbacks that are triggered by the ee from this moment on
-       * and execute all the storage callbacks saved up in the handlerCache ---
-       * --- if false: tell the handlerCache not to execute any of the storage callbacks
-       * and wipe out all the storage callbacks saved up in the handlerCache
-       * @param {boolean} decision
-       */
+     * Make a decision about what to do with the cache of callbacks.
+     * --- if true: tell the handlerCache that its ok to immediately execute the callbacks that are triggered by the ee from this moment on
+     * and execute all the storage callbacks saved up in the handlerCache ---
+     * --- if false: tell the handlerCache not to execute any of the storage callbacks
+     * and wipe out all the storage callbacks saved up in the handlerCache
+     * @param {boolean} decision
+     */
     decide(decision: boolean): void;
+    permanentlyDecide(decision: any): void;
     #private;
 }
 //# sourceMappingURL=handler-cache.d.ts.map

package/dist/types/features/utils/handler-cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handler-cache.d.ts","sourceRoot":"","sources":["../../../../src/features/utils/handler-cache.js"],"names":[],"mappings":"AAAA;;GAEG;AACH;IA6BE;;;;SAIK;IACL,2BAFe,IAAI,CAMlB;IAED;;;;;;;SAOK;IACL,iBAFa,OAAO,QAOnB;;CACF"}
+{"version":3,"file":"handler-cache.d.ts","sourceRoot":"","sources":["../../../../src/features/utils/handler-cache.js"],"names":[],"mappings":"AAAA;;GAEG;AACH;IA6BE;;;;OAIG;IACH,2BAFa,IAAI,CAMhB;IAED;;;;;;;OAOG;IACH,iBAFW,OAAO,QAOjB;IAED,uCAIC;;CACF"}

package/dist/types/features/utils/instrument-base.d.ts

@@ -13,10 +13,19 @@ export class InstrumentBase extends FeatureBase {
      *     immediately. Primarily useful for fine-grained control in tests.
      */
     constructor(agentIdentifier: string, aggregator: Aggregator, featureName: string, auto?: boolean | undefined);
-    hasAggregator: boolean;
     auto: boolean;
     /** @type {Function | undefined} This should be set by any derived Instrument class if it has things to do when feature fails or is killed. */
     abortHandler: Function | undefined;
+    /**
+     * @type {Class} Holds the reference to the feature's aggregate module counterpart, if and after it has been initialized. This may not be assigned until after page loads!
+     * The only purpose of this for now is to expose it to the NREUM interface, as the feature's instrument instance is already exposed.
+    */
+    featAggregate: Class;
+    /**
+     * @type {Promise} Assigned immediately after @see importAggregator runs. Serves as a signal for when the inner async fn finishes execution. Useful for features to await
+     * one another if there are inter-features dependencies.
+    */
+    onAggregateImported: Promise<any>;
     /**
      * Lazy-load the latter part of the feature: its aggregator. This method is called by the first part of the feature
      * (the instrumentation) when instrumentation is complete.
@@ -24,6 +33,13 @@ export class InstrumentBase extends FeatureBase {
      * @returns void
      */
     importAggregator(argsObjFromInstrument?: Object | undefined): void;
+    /**
+   * Make a determination if an aggregate class should even be imported
+   * @param {string} featureName
+   * @param {SessionEntity} session
+   * @returns
+   */
+    shouldImportAgg(featureName: string, session: SessionEntity): boolean;
 }
 import { FeatureBase } from './feature-base';
 //# sourceMappingURL=instrument-base.d.ts.map

package/dist/types/features/utils/instrument-base.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"instrument-base.d.ts","sourceRoot":"","sources":["../../../../src/features/utils/instrument-base.js"],"names":[],"mappings":"AAcA;;;GAGG;AACH;IACE;;;;;;;;OAQG;IACH,6BAPW,MAAM,uCAEN,MAAM,8BAchB;IAPC,uBAA0B;IAC1B,cAAgB;IAEhB,8IAA8I;IAC9I,cADW,WAAW,SAAS,CACd;IAKnB;;;;;OAKG;IACH,mEAyCC;CACF;4BAhF2B,gBAAgB"}
+{"version":3,"file":"instrument-base.d.ts","sourceRoot":"","sources":["../../../../src/features/utils/instrument-base.js"],"names":[],"mappings":"AAcA;;;GAGG;AACH;IACE;;;;;;;;OAQG;IACH,6BAPW,MAAM,uCAEN,MAAM,8BAuBhB;IAhBC,cAAgB;IAEhB,8IAA8I;IAC9I,cADW,WAAW,SAAS,CACd;IACjB;;;MAGE;IACF,qBAAkB;IAClB;;;MAGE;IACF,kCAAwB;IAK1B;;;;;OAKG;IACH,mEA4CC;IAED;;;;;KAKC;IACD,6BAJS,MAAM,mCAed;CACF;4BA/G2B,gBAAgB"}

package/dist/types/loaders/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../../src/loaders/agent.js"],"names":[],"mappings":"AAeA;;;GAGG;AACH;IACE,oDAeC;IAdC,wBAAsC;IACtC,6BAAiF;IACjF,aAAkB;IAElB,0BAAsD;IAYxD;;;;;MAOC;IAED,2BAgCC;CACF;2BAvE0B,gCAAgC"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../../src/loaders/agent.js"],"names":[],"mappings":"AAeA;;;GAGG;AACH;IACE,oDAcC;IAbC,wBAAsC;IACtC,6BAAiF;IACjF,aAAkB;IAElB,0BAAsD;IAWxD;;;;;MAOC;IAED,2BAgCC;CACF;2BAtE0B,gCAAgC"}

package/dist/types/loaders/features/featureDependencies.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"featureDependencies.d.ts","sourceRoot":"","sources":["../../../../src/loaders/features/featureDependencies.js"],"names":[],"mappings":"AAEA,kEAWC"}
+{"version":3,"file":"featureDependencies.d.ts","sourceRoot":"","sources":["../../../../src/loaders/features/featureDependencies.js"],"names":[],"mappings":"AAEA,kEAaC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@newrelic/browser-agent",
-  "version": "1.234.0",
+  "version": "1.235.0",
   "private": false,
   "author": "New Relic Browser Agent Team <browser-agent@newrelic.com>",
   "description": "Tests for the New Relic JavaScript agent",
@@ -89,9 +89,8 @@
   "scripts": {
     "wdio": "node --max-old-space-size=8192 tools/wdio/bin/cli.js",
     "start": "npm-run-all --parallel cdn:watch test-server",
-    "test": "jest",
-    "test:watch": "jest --watch",
-    "test:coverage": "jest --coverage",
+    "test:unit": "jest",
+    "test:component": "jest --config jest.component-config.js",
     "build:all": "npm run cdn:build:local && npm run build:npm && npm run tools:test-builds",
     "build:npm": "npm run npm:build:esm && npm run npm:build:cjs && npm run npm:build:types && npm run npm:pack",
     "build:browser-tests": "npm --prefix ./tools/test-builds/browser-tests run build",
@@ -196,10 +195,13 @@
     "gzip-size": "^7.0.0",
     "html-webpack-plugin": "^5.5.0",
     "husky": "^8.0.0",
-    "jest": "^28.1.1",
-    "jest-environment-jsdom": "28.1.1",
+    "istanbul-lib-coverage": "^3.2.0",
+    "istanbul-lib-instrument": "^5.2.1",
+    "istanbul-lib-report": "^3.0.0",
+    "istanbul-reports": "^3.1.5",
+    "jest": "^29.5.0",
+    "jest-environment-jsdom": "29.5.0",
     "jest-extended": "^3.2.4",
-    "jquery": "1.11.3",
     "jung": "^2.1.0",
     "just-debounce": "^1.0.0",
     "mime-types": "^2.1.11",

package/src/common/constants/shared-channel.js

@@ -0,0 +1,13 @@
+/**
+ * @file Keeps an object alive that is passed to all feature aggregate modules.
+ * The purpose is to have a way for communication and signals to relay across features at runtime.
+ * This object can hold any arbitrary values and should be treated as on-the-fly dynamic.
+ */
+
+let onReplayReady
+const sessionReplayInitialized = new Promise(resolve => onReplayReady = resolve)
+
+export const sharedChannel = Object.freeze({
+  onReplayReady,
+  sessionReplayInitialized
+})

package/src/common/harvest/harvest-scheduler.js

@@ -8,6 +8,7 @@ import { SharedContext } from '../context/shared-context'
 import { Harvest, getSubmitMethod } from './harvest'
 import { subscribeToEOL } from '../unload/eol'
 import { getConfigurationValue } from '../config/config'
+import { SESSION_EVENTS } from '../session/session-entity'
 
 /**
  * Periodically invokes harvest calls and handles retries
@@ -37,10 +38,16 @@ export class HarvestScheduler extends SharedContext {
     // unload if EOL mechanism fires
     subscribeToEOL(this.unload.bind(this), getConfigurationValue(this.sharedContext.agentIdentifier, 'allow_bfcache')) // TO DO: remove feature flag after rls stable
 
-    // unload if session resets
-    this.sharedContext?.ee.on('session-reset', this.unload.bind(this))
+    /* Flush all buffered data if session resets and give up retries. This should be synchronous to ensure that the correct `session` value is sent.
+      Since session-reset generates a new session ID and the ID is grabbed at send-time, any delays or retries would cause the payload to be sent under
+      the wrong session ID. */
+    this.sharedContext?.ee.on(SESSION_EVENTS.RESET, () => this.runHarvest({ forceNoRetry: true }))
   }
 
+  /**
+   * This function is only meant for the last outgoing harvest cycle of a page. It trickles down to using sendBeacon, which should not be used
+   * to send payloads while the page is still active, due to limitations on how much data can be buffered in the API at any one time.
+   */
   unload () {
     if (this.aborted) return
     // If opts.onUnload is defined, these are special actions to execute before attempting to send the final payload.
@@ -118,7 +125,7 @@ export class HarvestScheduler extends SharedContext {
         payload,
         opts,
         submitMethod,
-        cbFinished: onHarvestFinished,
+        cbFinished: cbRanAfterSend,
         customUrl: this.opts.customUrl,
         raw: this.opts.raw
       })
@@ -129,9 +136,13 @@ export class HarvestScheduler extends SharedContext {
     }
     return
 
-    function onHarvestFinished (result) {
-      if (result.blocked) scheduler.onHarvestBlocked(opts, result)
-      else scheduler.onHarvestFinished(opts, result)
+    /**
+     * This is executed immediately after harvest sends the data via XHR, or if there's nothing to send. Note that this excludes on unloading / sendBeacon.
+     * @param {Object} result
+     */
+    function cbRanAfterSend (result) {
+      if (opts?.forceNoRetry) result.retry = false // discard unsent data rather than re-queuing for next harvest attempt
+      scheduler.onHarvestFinished(opts, result)
     }
   }
 

package/src/common/session/{session-entity.test.js → session-entity.component-test.js}

@@ -1,12 +1,39 @@
-import { LocalMemory } from '../storage/local-memory'
-import { LocalStorage } from '../storage/local-storage'
-
 import { PREFIX } from './constants'
 import { SessionEntity } from './session-entity'
 
 const agentIdentifier = 'test_agent_identifier'
 const key = 'test_key'
 const value = 'test_value'
+class LocalMemory {
+  constructor (initialState = {}) {
+    this.state = initialState
+  }
+
+  get (key) {
+    try {
+      return this.state[key]
+    } catch (err) {
+      return ''
+    }
+  }
+
+  set (key, value) {
+    try {
+      if (value === undefined || value === null) return this.remove(key)
+      this.state[key] = value
+    } catch (err) {
+      return
+    }
+  }
+
+  remove (key) {
+    try {
+      delete this.state[key]
+    } catch (err) {
+      return
+    }
+  }
+}
 
 jest.mock('../timer/timer')
 jest.mock('../timer/interaction-timer')
@@ -23,9 +50,11 @@ jest.mock('../util/global-scope', () => ({
   }
 }))
 
+let storage
 beforeEach(() => {
   jest.restoreAllMocks()
   mockBrowserScope.mockReturnValue(true)
+  storage = new LocalMemory()
 })
 
 describe('constructor', () => {
@@ -36,7 +65,7 @@ describe('constructor', () => {
   })
 
   test('top-level properties are set and exposed', () => {
-    const session = new SessionEntity({ agentIdentifier, key })
+    const session = new SessionEntity({ agentIdentifier, key, storage })
     expect(session).toMatchObject({
       agentIdentifier: expect.any(String),
       key: expect.any(String),
@@ -51,119 +80,113 @@ describe('constructor', () => {
         expiresAt: expect.any(Number),
         inactiveAt: expect.any(Number),
         sessionReplay: expect.any(Number),
-        sessionTraceActive: expect.any(Boolean)
+        sessionTraceMode: expect.any(Number)
       })
     })
   })
 
   test('can use sane defaults', () => {
-    const session = new SessionEntity({ agentIdentifier, key })
+    const session = new SessionEntity({ agentIdentifier, key, storage })
     expect(session.state).toEqual(expect.objectContaining({
       value: expect.any(String),
       expiresAt: expect.any(Number),
       inactiveAt: expect.any(Number),
       updatedAt: expect.any(Number),
       sessionReplay: expect.any(Number),
-      sessionTraceActive: expect.any(Boolean)
+      sessionTraceMode: expect.any(Number)
     }))
   })
 
-  test('Workers are forced to use local memory', () => {
-    mockBrowserScope.mockReturnValueOnce(false)
-    const session = new SessionEntity({ agentIdentifier, key, storageAPI: new LocalStorage() })
-    expect(session.storage instanceof LocalMemory).toEqual(true)
-  })
-
   test('expiresAt is the correct future timestamp - new session', () => {
     const now = Date.now()
     jest.setSystemTime(now)
-    const session = new SessionEntity({ agentIdentifier, key, expiresMs: 100 })
+    const session = new SessionEntity({ agentIdentifier, key, storage, expiresMs: 100 })
     expect(session.state.expiresAt).toEqual(now + 100)
   })
 
   test('expiresAt is the correct future timestamp - existing session', () => {
     const now = Date.now()
     jest.setSystemTime(now)
-    const existingData = new LocalMemory({ [`${PREFIX}_${key}`]: { value, expiresAt: now + 5000, inactiveAt: Infinity, updatedAt: now, sessionReplay: 0, sessionTraceActive: false, custom: {} } })
-    const session = new SessionEntity({ agentIdentifier, key, expiresMs: 100, storageAPI: existingData })
+    const existingData = new LocalMemory({ [`${PREFIX}_${key}`]: { value, expiresAt: now + 5000, inactiveAt: Infinity, updatedAt: now, sessionReplay: 0, sessionTraceMode: 0, custom: {} } })
+    const session = new SessionEntity({ agentIdentifier, key, expiresMs: 100, storage: existingData })
     expect(session.state.expiresAt).toEqual(now + 5000)
   })
 
   test('expiresAt never expires if 0', () => {
-    const session = new SessionEntity({ agentIdentifier, key, expiresMs: 0 })
+    const session = new SessionEntity({ agentIdentifier, key, storage, expiresMs: 0 })
     expect(session.state.expiresAt).toEqual(Infinity)
   })
 
   test('inactiveAt is the correct future timestamp - new session', () => {
     const now = Date.now()
     jest.setSystemTime(now)
-    const session = new SessionEntity({ agentIdentifier, key, inactiveMs: 100 })
+    const session = new SessionEntity({ agentIdentifier, key, storage, inactiveMs: 100 })
     expect(session.state.inactiveAt).toEqual(now + 100)
   })
 
   test('inactiveAt is the correct future timestamp - existing session', () => {
     const now = Date.now()
     jest.setSystemTime(now)
-    const existingData = new LocalMemory({ [`${PREFIX}_${key}`]: { value, inactiveAt: now + 5000, expiresAt: Infinity, updatedAt: now, sessionReplay: 0, sessionTraceActive: false, custom: {} } })
-    const session = new SessionEntity({ agentIdentifier, key, inactiveMs: 100, storageAPI: existingData })
+    const existingData = new LocalMemory({ [`${PREFIX}_${key}`]: { value, inactiveAt: now + 5000, expiresAt: Infinity, updatedAt: now, sessionReplay: 0, sessionTraceMode: 0, custom: {} } })
+    const session = new SessionEntity({ agentIdentifier, key, inactiveMs: 100, storage: existingData })
     expect(session.state.inactiveAt).toEqual(now + 5000)
   })
 
   test('inactiveAt never expires if 0', () => {
-    const session = new SessionEntity({ agentIdentifier, key, inactiveMs: 0 })
+    const session = new SessionEntity({ agentIdentifier, key, storage, inactiveMs: 0 })
     expect(session.state.inactiveAt).toEqual(Infinity)
   })
 
   test('should handle isNew', () => {
-    const newSession = new SessionEntity({ agentIdentifier, key, expiresMs: 10 })
+    const newSession = new SessionEntity({ agentIdentifier, key, storage, expiresMs: 10 })
     expect(newSession.isNew).toBeTruthy()
 
-    const storageAPI = new LocalMemory({ [`${PREFIX}_${key}`]: { value, expiresAt: Infinity, inactiveAt: Infinity, updatedAt: Date.now(), sessionReplay: 0, sessionTraceActive: false, custom: {} } })
-    const existingSession = new SessionEntity({ agentIdentifier, key, expiresMs: 10, storageAPI })
+    const newStorage = new LocalMemory({ [`${PREFIX}_${key}`]: { value, expiresAt: Infinity, inactiveAt: Infinity, updatedAt: Date.now(), sessionReplay: 0, sessionTraceMode: 0, custom: {} } })
+    const existingSession = new SessionEntity({ agentIdentifier, key, expiresMs: 10, storage: newStorage })
     expect(existingSession.isNew).toBeFalsy()
   })
 
   test('invalid stored values sets new defaults', () => {
     // missing required fields
-    const storageAPI = new LocalMemory({ [`${PREFIX}_${key}`]: { invalid_fields: true } })
-    const session = new SessionEntity({ agentIdentifier, key, storageAPI })
+    const storage = new LocalMemory({ [`${PREFIX}_${key}`]: { invalid_fields: true } })
+    const session = new SessionEntity({ agentIdentifier, key, storage })
     expect(session.state).toEqual(expect.objectContaining({
       value: expect.any(String),
       expiresAt: expect.any(Number),
       inactiveAt: expect.any(Number),
       updatedAt: expect.any(Number),
       sessionReplay: expect.any(Number),
-      sessionTraceActive: expect.any(Boolean)
+      sessionTraceMode: expect.any(Number)
     }))
   })
 
   test('expired expiresAt value in storage sets new defaults', () => {
     const now = Date.now()
     jest.setSystemTime(now)
-    const storageAPI = new LocalMemory({ [`${PREFIX}_${key}`]: { value, expiresAt: now - 100, inactiveAt: Infinity } })
-    const session = new SessionEntity({ agentIdentifier, key, storageAPI })
+    const storage = new LocalMemory({ [`${PREFIX}_${key}`]: { value, expiresAt: now - 100, inactiveAt: Infinity } })
+    const session = new SessionEntity({ agentIdentifier, key, storage })
     expect(session.state).toEqual(expect.objectContaining({
       value: expect.any(String),
       expiresAt: expect.any(Number),
       inactiveAt: expect.any(Number),
       updatedAt: expect.any(Number),
       sessionReplay: expect.any(Number),
-      sessionTraceActive: expect.any(Boolean)
+      sessionTraceMode: expect.any(Number)
     }))
   })
 
   test('expired inactiveAt value in storage sets new defaults', () => {
     const now = Date.now()
     jest.setSystemTime(now)
-    const storageAPI = new LocalMemory({ [`${PREFIX}_${key}`]: { value, inactiveAt: now - 100, expiresAt: Infinity } })
-    const session = new SessionEntity({ agentIdentifier, key, storageAPI })
+    const storage = new LocalMemory({ [`${PREFIX}_${key}`]: { value, inactiveAt: now - 100, expiresAt: Infinity } })
+    const session = new SessionEntity({ agentIdentifier, key, storage })
     expect(session.state).toEqual(expect.objectContaining({
       value: expect.any(String),
       expiresAt: expect.any(Number),
       inactiveAt: expect.any(Number),
       updatedAt: expect.any(Number),
       sessionReplay: expect.any(Number),
-      sessionTraceActive: expect.any(Boolean)
+      sessionTraceMode: expect.any(Number)
     }))
   })
 })
@@ -172,7 +195,7 @@ describe('reset()', () => {
   test('should create new default values when resetting', () => {
     const now = Date.now()
     jest.setSystemTime(now)
-    const session = new SessionEntity({ agentIdentifier, key, expiresMs: 10 })
+    const session = new SessionEntity({ agentIdentifier, key, storage, expiresMs: 10 })
     const sessionVal = session.value
     expect(session.state.value).toBeTruthy()
     session.reset()
@@ -183,7 +206,7 @@ describe('reset()', () => {
   test('custom data should be wiped on reset', () => {
     const now = Date.now()
     jest.setSystemTime(now)
-    const session = new SessionEntity({ agentIdentifier, key, expiresMs: 10 })
+    const session = new SessionEntity({ agentIdentifier, key, storage, expiresMs: 10 })
     session.syncCustomAttribute('test', 123)
     expect(session.state.custom.test).toEqual(123)
     expect(session.read().custom.test).toEqual(123)
@@ -197,7 +220,7 @@ describe('reset()', () => {
 
 describe('read()', () => {
   test('"new" sessions get data from read()', () => {
-    const newSession = new SessionEntity({ agentIdentifier, key, expiresMs: 10 })
+    const newSession = new SessionEntity({ agentIdentifier, key, storage, expiresMs: 10 })
     expect(newSession.isNew).toBeTruthy()
 
     expect(newSession.read()).toEqual(expect.objectContaining({
@@ -205,13 +228,13 @@ describe('read()', () => {
       expiresAt: expect.any(Number),
       inactiveAt: expect.any(Number),
       sessionReplay: expect.any(Number),
-      sessionTraceActive: expect.any(Boolean)
+      sessionTraceMode: expect.any(Number)
     }))
   })
 
   test('"pre-existing" sessions get data from read()', () => {
-    const storageAPI = new LocalMemory({ [`${PREFIX}_${key}`]: { value, expiresAt: Infinity, inactiveAt: Infinity, updatedAt: Date.now(), sessionReplay: 0, sessionTraceActive: false, custom: {} } })
-    const session = new SessionEntity({ agentIdentifier, key, storageAPI })
+    const storage = new LocalMemory({ [`${PREFIX}_${key}`]: { value, expiresAt: Infinity, inactiveAt: Infinity, updatedAt: Date.now(), sessionReplay: 0, sessionTraceMode: 0, custom: {} } })
+    const session = new SessionEntity({ agentIdentifier, key, storage })
     expect(session.isNew).toBeFalsy()
     expect(session.read()).toEqual(expect.objectContaining({
       value,
@@ -223,7 +246,7 @@ describe('read()', () => {
 
 describe('write()', () => {
   test('write() sets data to top-level wrapper', () => {
-    const session = new SessionEntity({ agentIdentifier, key })
+    const session = new SessionEntity({ agentIdentifier, key, storage })
     expect(session.state.value).not.toEqual(value)
     expect(session.state.expiresAt).not.toEqual(Infinity)
     expect(session.state.inactiveAt).not.toEqual(Infinity)
@@ -236,7 +259,7 @@ describe('write()', () => {
   test('write() sets data that read() can access', () => {
     const now = Date.now()
     jest.setSystemTime(now)
-    const session = new SessionEntity({ agentIdentifier, key })
+    const session = new SessionEntity({ agentIdentifier, key, storage })
     session.write({ ...session.state, value, expiresAt: now + 100, inactiveAt: now + 100 })
     const read = session.read()
     expect(read.value).toEqual(value)
@@ -245,7 +268,7 @@ describe('write()', () => {
   })
 
   test('write() does not run with invalid data', () => {
-    const session = new SessionEntity({ agentIdentifier, key })
+    const session = new SessionEntity({ agentIdentifier, key, storage })
     let out = session.write()
     expect(out).toEqual(undefined)
     out = session.write('string')
@@ -263,7 +286,7 @@ describe('refresh()', () => {
   test('refresh sets inactiveAt to future time', () => {
     const now = Date.now()
     jest.setSystemTime(now)
-    const session = new SessionEntity({ agentIdentifier, key, inactiveMs: 100 })
+    const session = new SessionEntity({ agentIdentifier, key, storage, inactiveMs: 100 })
     expect(session.state.inactiveAt).toEqual(now + 100)
     jest.setSystemTime(now + 1000)
     session.refresh()
@@ -273,7 +296,7 @@ describe('refresh()', () => {
   test('refresh resets the entity if expiresTimer is invalid', () => {
     const now = Date.now()
     jest.setSystemTime(now)
-    const session = new SessionEntity({ agentIdentifier, key, value })
+    const session = new SessionEntity({ agentIdentifier, key, storage, value })
     expect(session.state.value).toEqual(value)
     session.write({ ...session.state, expiresAt: now - 1 })
     session.refresh()
@@ -283,7 +306,7 @@ describe('refresh()', () => {
   test('refresh resets the entity if inactiveTimer is invalid', () => {
     const now = Date.now()
     jest.setSystemTime(now)
-    const session = new SessionEntity({ agentIdentifier, key, value })
+    const session = new SessionEntity({ agentIdentifier, key, storage, value })
     expect(session.state.value).toEqual(value)
     session.write({ ...session.state, inactiveAt: now - 1 })
     session.refresh()
@@ -293,7 +316,7 @@ describe('refresh()', () => {
 
 describe('syncCustomAttribute()', () => {
   test('Custom data can be managed by session entity', () => {
-    const session = new SessionEntity({ agentIdentifier, key })
+    const session = new SessionEntity({ agentIdentifier, key, storage })
 
     // if custom has never been set, and a "delete" action is triggered, do nothing
     session.syncCustomAttribute('test', null)
@@ -315,7 +338,7 @@ describe('syncCustomAttribute()', () => {
 
   test('Only runs in browser scope', () => {
     mockBrowserScope.mockReturnValue(false)
-    const session = new SessionEntity({ agentIdentifier, key })
+    const session = new SessionEntity({ agentIdentifier, key, storage })
     session.syncCustomAttribute('test', 1)
     expect(session.read().custom?.test).toEqual(undefined)
   })

package/src/common/session/session-entity.js

@@ -5,7 +5,6 @@ import { ee } from '../event-emitter/contextual-ee'
 import { Timer } from '../timer/timer'
 import { isBrowserScope } from '../util/global-scope'
 import { DEFAULT_EXPIRES_MS, DEFAULT_INACTIVE_MS, PREFIX } from './constants'
-import { LocalMemory } from '../storage/local-memory'
 import { InteractionTimer } from '../timer/interaction-timer'
 import { wrapEvents } from '../wrap'
 import { getModeledObject } from '../config/state/configurable'
@@ -13,6 +12,11 @@ import { handle } from '../event-emitter/handle'
 import { SUPPORTABILITY_METRIC_CHANNEL } from '../../features/metrics/constants'
 import { FEATURE_NAMES } from '../../loaders/features/features'
 
+export const MODE = {
+  OFF: 0,
+  FULL: 1,
+  ERROR: 2
+}
 // this is what can be stored in local storage (not enforced but probably should be)
 // these values should sync between local storage and the parent class props
 const model = {
@@ -20,11 +24,10 @@ const model = {
   inactiveAt: 0,
   expiresAt: 0,
   updatedAt: Date.now(),
-  sessionReplay: 0,
-  sessionTraceActive: false,
+  sessionReplay: MODE.OFF,
+  sessionTraceMode: MODE.OFF,
   custom: {}
 }
-
 export const SESSION_EVENTS = {
   PAUSE: 'session-pause',
   RESET: 'session-reset',
@@ -42,16 +45,16 @@ export class SessionEntity {
     this.setup(opts)
   }
 
-  setup ({ agentIdentifier, key, value = generateRandomHexString(16), expiresMs = DEFAULT_EXPIRES_MS, inactiveMs = DEFAULT_INACTIVE_MS, storageAPI = new LocalMemory() }) {
-    if (!agentIdentifier || !key) throw new Error('Missing Required Fields')
-    if (!isBrowserScope) this.storage = new LocalMemory()
-    else this.storage = storageAPI
-
+  setup ({ agentIdentifier, key, storage, value = generateRandomHexString(16), expiresMs = DEFAULT_EXPIRES_MS, inactiveMs = DEFAULT_INACTIVE_MS }) {
+    if (!agentIdentifier || !key || !storage) {
+      throw new Error(`Missing required field(s):${!agentIdentifier ? ' agentID' : ''}${!key ? ' key' : ''}${!storage ? ' storage' : ''}`)
+    }
+    this.agentIdentifier = agentIdentifier
+    this.storage = storage
     this.state = {}
 
     this.sync(model)
 
-    this.agentIdentifier = agentIdentifier
     // key is intended to act as the k=v pair
     this.key = key
     // value is intended to act as the primary value of the k=v pair
@@ -183,7 +186,7 @@ export class SessionEntity {
       this.sync(data) // update the parent class "state" properties with the local storage values
       //
       // TODO - compression would need happen here if we decide to do it
-      this.storage.set(this.lookupKey, stringify(data))
+      this.storage.set(this.lookupKey, stringify(this.state))
       return data
     } catch (e) {
       // storage is inaccessible
@@ -207,7 +210,7 @@ export class SessionEntity {
       this.setup({
         agentIdentifier: this.agentIdentifier,
         key: this.key,
-        storageAPI: this.storage,
+        storage: this.storage,
         expiresMs: this.expiresMs,
         inactiveMs: this.inactiveMs
       })

package/src/common/timer/interaction-timer.js

@@ -44,8 +44,8 @@ export class InteractionTimer extends Timer {
         if (state === 'hidden') this.pause()
         // vis change --> visible is treated like a new interaction with the page
         else {
-          this.onResume()
           this.refresh()
+          this.onResume() // emit resume event after state updated
         }
       }, false, false, this.abortController?.signal)
     }