@newrelic/browser-agent 1.232.1 → 1.233.1

package/src/common/harvest/harvest.js

@@ -8,7 +8,7 @@ import { obj as encodeObj, param as encodeParam } from '../url/encode'
 import { stringify } from '../util/stringify'
 import { submitData } from '../util/submit-data'
 import { getLocation } from '../url/location'
-import { getInfo, getConfigurationValue, getRuntime, getConfiguration } from '../config/config'
+import { getInfo, getConfigurationValue, getRuntime } from '../config/config'
 import { cleanURL } from '../url/clean-url'
 import { now } from '../timing/now'
 import { eventListenerOpts } from '../event-listener/event-listener-opts'
@@ -18,6 +18,23 @@ import { SharedContext } from '../context/shared-context'
 import { VERSION } from '../constants/env'
 import { isBrowserScope, isWorkerScope } from '../util/global-scope'
 
+/**
+ * @typedef {object} NetworkSendSpec
+ * @param {string} endpoint The endpoint to use (jserrors, events, resources etc.)
+ * @param {object} payload Object representing payload.
+ * @param {object} payload.qs Map of values that should be sent as part of the request query string.
+ * @param {string} payload.body String that should be sent as the body of the request.
+ * @param {string} payload.body.e Special case of body used for browser interactions.
+ * @param {object} opts Additional options for sending data
+ * @param {boolean} opts.needResponse Specify whether the caller expects a response data.
+ * @param {boolean} opts.unload Specify whether the call is a final harvest during page unload.
+ * @param {boolean} opts.sendEmptyBody Specify whether the call should be made even if the body is empty. Useful for rum calls.
+ * @param {function} submitMethod The submit method to use {@link ../util/submit-data}
+ * @param {string} customUrl Override the beacon url the data is sent to; must include protocol if defined
+ * @param {boolean} gzip Enabled gzip compression on the body of the request before it is sent
+ * @param {boolean} includeBaseParams Enables the use of base query parameters in the beacon url {@see Harvest.baseQueryString}
+ */
+
 const haveSendBeacon = !!navigator.sendBeacon // only the web window obj has sendBeacon at this time, so 'false' for other envs
 
 export class Harvest extends SharedContext {
@@ -34,55 +51,48 @@ export class Harvest extends SharedContext {
   /**
    * Initiate a harvest from multiple sources. An event that corresponds to the endpoint
    * name is emitted, which gives any listeners the opportunity to provide payload data.
-   *
-   * @param {string} endpoint - The endpoint of the harvest (jserrors, events, resources etc.)
-   *
-   * @param {object} opts
-   * @param {bool} opts.needResponse - Specify whether the caller expects a response data.
-   * @param {bool} opts.unload - Specify whether the call is a final harvest during page unload.
+   * @param {NetworkSendSpec} spec Specification for sending data
    */
-  sendX (endpoint, opts, cbFinished) {
+  sendX (spec) {
+    const { endpoint, opts } = spec
     var submitMethod = getSubmitMethod(endpoint, opts)
     if (!submitMethod) return false
     var options = {
       retry: submitMethod.method === submitData.xhr
     }
-    return this.obfuscator.shouldObfuscate() ? this.obfuscateAndSend(endpoint, this.createPayload(endpoint, options), opts, submitMethod, cbFinished) : this._send(endpoint, this.createPayload(endpoint, options), opts, submitMethod, cbFinished)
+    const payload = this.createPayload(endpoint, options)
+    var caller = this.obfuscator.shouldObfuscate() ? this.obfuscateAndSend.bind(this) : this._send.bind(this)
+    return caller({ ...spec, payload, submitMethod })
   }
 
   /**
- * Initiate a harvest call.
- *
- * @param {string} endpoint - The endpoint of the harvest (jserrors, events, resources etc.)
- * @param {object} nr - The loader singleton.
- *
- * @param {object} singlePayload - Object representing payload.
- * @param {object} singlePayload.qs - Map of values that should be sent as part of the request query string.
- * @param {string} singlePayload.body - String that should be sent as the body of the request.
- * @param {string} singlePayload.body.e - Special case of body used for browser interactions.
- *
- * @param {object} opts
- * @param {bool} opts.needResponse - Specify whether the caller expects a response data.
- * @param {bool} opts.unload - Specify whether the call is a final harvest during page unload.
- */
-  send (endpoint, singlePayload, opts, submitMethod, cbFinished) {
+   * Initiate a harvest call.
+   * @param {NetworkSendSpec} spec Specification for sending data
+   */
+  send (spec) {
+    const { payload = {} } = spec
     var makeBody = createAccumulator()
     var makeQueryString = createAccumulator()
-    if (singlePayload.body) mapOwn(singlePayload.body, makeBody)
-    if (singlePayload.qs) mapOwn(singlePayload.qs, makeQueryString)
+    if (payload.body) mapOwn(payload.body, makeBody)
+    if (payload.qs) mapOwn(payload.qs, makeQueryString)
 
-    var payload = { body: makeBody(), qs: makeQueryString() }
-    var caller = this.obfuscator.shouldObfuscate() ? (...args) => this.obfuscateAndSend(...args) : (...args) => this._send(...args)
+    var newPayload = { body: makeBody(), qs: makeQueryString() }
+    var caller = this.obfuscator.shouldObfuscate() ? this.obfuscateAndSend.bind(this) : this._send.bind(this)
 
-    return caller(endpoint, payload, opts, submitMethod, cbFinished)
+    return caller({ ...spec, payload: newPayload })
   }
 
-  obfuscateAndSend (endpoint, payload, opts, submitMethod, cbFinished) {
+  /**
+   * Apply obfuscation rules to the payload and then initial the harvest network call.
+   * @param {NetworkSendSpec} spec Specification for sending data
+   */
+  obfuscateAndSend (spec) {
+    const { payload = {} } = spec
     applyFnToProps(payload, (...args) => this.obfuscator.obfuscateString(...args), 'string', ['e'])
-    return this._send(endpoint, payload, opts, submitMethod, cbFinished)
+    return this._send({ ...spec, payload })
   }
 
-  _send (endpoint, payload, opts, submitMethod, cbFinished) {
+  _send ({ endpoint, payload = {}, opts = {}, submitMethod, cbFinished, customUrl, raw, includeBaseParams = true }) {
     var info = getInfo(this.sharedContext.agentIdentifier)
     if (!info.errorBeacon) return false
 
@@ -95,11 +105,13 @@ export class Harvest extends SharedContext {
       return false
     }
 
-    if (!opts) opts = {}
-
-    var url = this.getScheme() + '://' + info.errorBeacon + '/' + endpoint + '/1/' + info.licenseKey + this.baseQueryString()
-    if (payload.qs) url += encodeObj(payload.qs, agentRuntime.maxBytes)
+    let url = ''
+    if (customUrl) url = customUrl
+    else if (raw) url = `${this.getScheme()}://${info.errorBeacon}/${endpoint}`
+    else url = `${this.getScheme()}://${info.errorBeacon}/${endpoint}/1/${info.licenseKey}`
 
+    var baseParams = !raw && includeBaseParams ? this.baseQueryString() : ''
+    var payloadParams = payload.qs ? encodeObj(payload.qs, agentRuntime.maxBytes) : ''
     if (!submitMethod) {
       submitMethod = getSubmitMethod(endpoint, opts)
     }
@@ -107,29 +119,39 @@ export class Harvest extends SharedContext {
     var useBody = submitMethod.useBody
 
     var body
-    var fullUrl = url
-    if (useBody && endpoint === 'events') {
-      body = payload.body.e
-    } else if (useBody) {
-      body = stringify(payload.body)
-    } else {
-      fullUrl = url + encodeObj(payload.body, agentRuntime.maxBytes)
-    }
+    var fullUrl = `${url}?${baseParams}${payloadParams}`
+
+    const gzip = payload?.qs?.content_encoding === 'gzip'
+
+    if (!gzip) {
+      if (useBody && endpoint === 'events') {
+        body = payload.body.e
+      } else if (useBody) {
+        body = stringify(payload.body)
+      } else {
+        fullUrl = fullUrl + encodeObj(payload.body, agentRuntime.maxBytes)
+      }
+    } else body = payload.body
 
     // Get bytes harvested per endpoint as a supportability metric. See metrics aggregator (on unload).
     agentRuntime.bytesSent[endpoint] = (agentRuntime.bytesSent[endpoint] || 0) + body?.length || 0
     // Get query bytes harvested per endpoint as a supportability metric. See metrics aggregator (on unload).
     agentRuntime.queryBytesSent[endpoint] = (agentRuntime.queryBytesSent[endpoint] || 0) + fullUrl.split('?').slice(-1)[0]?.length || 0
 
+    const headers = []
+
+    headers.push({ key: 'content-type', value: 'text/plain' })
+
     /* Since workers don't support sendBeacon right now, or Image(), they can only use XHR method.
         Because they still do permit synch XHR, the idea is that at final harvest time (worker is closing),
         we just make a BLOCKING request--trivial impact--with the remaining data as a temp fill-in for sendBeacon. */
-    var result = method(fullUrl, body, opts.unload && isWorkerScope)
+
+    var result = method({ url: fullUrl, body, sync: opts.unload && isWorkerScope, headers })
 
     if (cbFinished && method === submitData.xhr) {
       var xhr = result
       xhr.addEventListener('load', function () {
-        var result = { sent: true }
+        var result = { sent: true, status: this.status }
         if (this.status === 429) {
           result.retry = true
           result.delay = this.tooManyRequestsDelay
@@ -147,7 +169,7 @@ export class Harvest extends SharedContext {
     // if beacon request failed, retry with an alternative method -- will not happen for workers
     if (!result && method === submitData.beacon) {
       method = submitData.img
-      result = method(url + encodeObj(payload.body, agentRuntime.maxBytes))
+      result = method({ url: fullUrl + encodeObj(payload.body, agentRuntime.maxBytes) })
     }
 
     return result
@@ -162,14 +184,14 @@ export class Harvest extends SharedContext {
     var ref = this.obfuscator.shouldObfuscate() ? this.obfuscator.obfuscateString(location) : location
 
     return ([
-      '?a=' + info.applicationID,
+      'a=' + info.applicationID,
       encodeParam('sa', (info.sa ? '' + info.sa : '')),
       encodeParam('v', VERSION),
       transactionNameParam(info),
       encodeParam('ct', runtime.customTransaction),
       '&rst=' + now(),
       '&ck=0', // ck param DEPRECATED - still expected by backend
-      '&s=' + (runtime.session?.value || '0'), // the 0 id encaps all untrackable and default traffic
+      '&s=' + (runtime.session?.state.value || '0'), // the 0 id encaps all untrackable and default traffic
       encodeParam('ref', ref),
       encodeParam('ptid', (runtime.ptid ? '' + runtime.ptid : ''))
     ].join(''))
@@ -241,7 +263,7 @@ function createAccumulator () {
   var accumulator = {}
   var hasData = false
   return function (key, val) {
-    if (val && val.length) {
+    if (val !== null && val !== undefined && val.length) {
       accumulator[key] = val
       hasData = true
     }

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

@@ -8,21 +8,29 @@ 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 { Configurable } from '../config/state/configurable'
+import { getModeledObject } from '../config/state/configurable'
 import { handle } from '../event-emitter/handle'
 import { SUPPORTABILITY_METRIC_CHANNEL } from '../../features/metrics/constants'
 import { FEATURE_NAMES } from '../../loaders/features/features'
 
+// 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 = {
   value: '',
   inactiveAt: 0,
   expiresAt: 0,
   updatedAt: Date.now(),
-  sessionReplayActive: false,
+  sessionReplay: 0,
   sessionTraceActive: false,
   custom: {}
 }
 
+export const SESSION_EVENTS = {
+  PAUSE: 'session-pause',
+  RESET: 'session-reset',
+  RESUME: 'session-resume'
+}
+
 export class SessionEntity {
   /**
    * Create a self-managing Session Entity. This entity is scoped to the agent identifier which triggered it, allowing for multiple simultaneous session objects to exist.
@@ -39,14 +47,15 @@ export class SessionEntity {
     if (!isBrowserScope) this.storage = new LocalMemory()
     else this.storage = storageAPI
 
+    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
-    this.value = value
+    this.state.value = value
 
     this.expiresMs = expiresMs
     this.inactiveMs = inactiveMs
@@ -66,7 +75,7 @@ export class SessionEntity {
     // the set-up of the timer used to expire the session "naturally" at a certain time
     // this gets ignored if the value is falsy, allowing for session entities that do not expire
     if (expiresMs) {
-      this.expiresAt = initialRead?.expiresAt || this.getFutureTimestamp(expiresMs)
+      this.state.expiresAt = initialRead?.expiresAt || this.getFutureTimestamp(expiresMs)
       this.expiresTimer = new Timer({
         // When the inactive timer ends, collect a SM and reset the session
         onEnd: () => {
@@ -74,16 +83,16 @@ export class SessionEntity {
           this.collectSM('duration', this)
           this.reset()
         }
-      }, this.expiresAt - Date.now())
+      }, this.state.expiresAt - Date.now())
     } else {
-      this.expiresAt = Infinity
+      this.state.expiresAt = Infinity
     }
 
     // the set-up of the timer used to expire the session due to "inactivity" at a certain time
     // this gets ignored if the value is falsy, allowing for session entities that do not expire
     // this gets "refreshed" when "activity" is observed
     if (inactiveMs) {
-      this.inactiveAt = initialRead?.inactiveAt || this.getFutureTimestamp(inactiveMs)
+      this.state.inactiveAt = initialRead?.inactiveAt || this.getFutureTimestamp(inactiveMs)
       this.inactiveTimer = new InteractionTimer({
         // When the inactive timer ends, collect a SM and reset the session
         onEnd: () => {
@@ -93,21 +102,25 @@ export class SessionEntity {
         },
         // When the inactive timer refreshes, it will update the storage values with an update timestamp
         onRefresh: this.refresh.bind(this),
+        onResume: () => { this.ee.emit(SESSION_EVENTS.RESUME) },
         // When the inactive timer pauses, update the storage values with an update timestamp
-        onPause: () => this.write(new Configurable(this.read(), model)),
+        onPause: () => {
+          if (this.initialized) this.ee.emit(SESSION_EVENTS.PAUSE)
+          this.write(getModeledObject(this.state, model))
+        },
         ee: this.ee,
         refreshEvents: ['click', 'keydown', 'scroll']
-      }, this.inactiveAt - Date.now())
+      }, this.state.inactiveAt - Date.now())
     } else {
-      this.inactiveAt = Infinity
+      this.state.inactiveAt = Infinity
     }
 
     // The fact that the session is "new" or pre-existing is used in some places in the agent.  Session Replay and Trace
     // can use this info to inform whether to trust a new sampling decision vs continue a previous tracking effort.
-    this.isNew = !Object.keys(initialRead).length
+    if (this.isNew === undefined) this.isNew = !Object.keys(initialRead).length
     // if its a "new" session, we write to storage API with the default values.  These values may change over the lifespan of the agent run.
-    // we can use configurable here to help us know and manage what values are being used. -- see "model" above
-    if (this.isNew) this.write(new Configurable(this, model), true)
+    // we can use a modeled object here to help us know and manage what values are being used. -- see "model" above
+    if (this.isNew) this.write(getModeledObject(this.state, model), true)
     else this.sync(initialRead)
 
     this.initialized = true
@@ -119,7 +132,7 @@ export class SessionEntity {
   }
 
   sync (data) {
-    Object.assign(this, data)
+    Object.assign(this.state, data)
   }
 
   /**
@@ -167,7 +180,8 @@ export class SessionEntity {
       if (!data || typeof data !== 'object') return
       // everytime we update, we can update a timestamp for sanity
       data.updatedAt = Date.now()
-      this.sync(data)
+      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))
       return data
@@ -184,13 +198,11 @@ export class SessionEntity {
     // * stop recording (stn and sr)...
     // * delete the session and start over
     try {
-      if (this.initialized) this.ee.emit('session-reset')
-
+      if (this.initialized) this.ee.emit(SESSION_EVENTS.RESET)
       this.storage.remove(this.lookupKey)
       this.inactiveTimer?.abort?.()
       this.expiresTimer?.clear?.()
-      delete this.custom
-      delete this.value
+      delete this.isNew
 
       this.setup({
         agentIdentifier: this.agentIdentifier,
@@ -211,8 +223,7 @@ export class SessionEntity {
   refresh () {
     // read here & invalidate
     const existingData = this.read()
-    this.inactiveAt = this.getFutureTimestamp(this.inactiveMs)
-    this.write({ ...existingData, inactiveAt: this.inactiveAt })
+    this.write({ ...existingData, inactiveAt: this.getFutureTimestamp(this.inactiveMs) })
   }
 
   /**
@@ -228,7 +239,7 @@ export class SessionEntity {
    * @returns {boolean}
    */
   isInvalid (data) {
-    const requiredKeys = ['value', 'expiresAt', 'inactiveAt']
+    const requiredKeys = Object.keys(model)
     return !requiredKeys.every(x => Object.keys(data).includes(x))
   }
 

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

@@ -41,27 +41,30 @@ describe('constructor', () => {
     expect(session).toMatchObject({
       agentIdentifier: expect.any(String),
       key: expect.any(String),
-      value: expect.any(String),
       expiresMs: expect.any(Number),
-      expiresAt: expect.any(Number),
       expiresTimer: expect.any(Object),
       inactiveMs: expect.any(Number),
-      inactiveAt: expect.any(Number),
       inactiveTimer: expect.any(Object),
       isNew: expect.any(Boolean),
-      sessionReplayActive: expect.any(Boolean),
-      sessionTraceActive: expect.any(Boolean),
-      storage: expect.any(Object)
+      storage: expect.any(Object),
+      state: expect.objectContaining({
+        value: expect.any(String),
+        expiresAt: expect.any(Number),
+        inactiveAt: expect.any(Number),
+        sessionReplay: expect.any(Number),
+        sessionTraceActive: expect.any(Boolean)
+      })
     })
   })
 
   test('can use sane defaults', () => {
     const session = new SessionEntity({ agentIdentifier, key })
-    expect(session).toEqual(expect.objectContaining({
+    expect(session.state).toEqual(expect.objectContaining({
       value: expect.any(String),
       expiresAt: expect.any(Number),
       inactiveAt: expect.any(Number),
-      sessionReplayActive: expect.any(Boolean),
+      updatedAt: expect.any(Number),
+      sessionReplay: expect.any(Number),
       sessionTraceActive: expect.any(Boolean)
     }))
   })
@@ -76,47 +79,47 @@ describe('constructor', () => {
     const now = Date.now()
     jest.setSystemTime(now)
     const session = new SessionEntity({ agentIdentifier, key, expiresMs: 100 })
-    expect(session.expiresAt).toEqual(now + 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 } })
+    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 })
-    expect(session.expiresAt).toEqual(now + 5000)
+    expect(session.state.expiresAt).toEqual(now + 5000)
   })
 
   test('expiresAt never expires if 0', () => {
     const session = new SessionEntity({ agentIdentifier, key, expiresMs: 0 })
-    expect(session.expiresAt).toEqual(Infinity)
+    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 })
-    expect(session.inactiveAt).toEqual(now + 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 } })
+    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 })
-    expect(session.inactiveAt).toEqual(now + 5000)
+    expect(session.state.inactiveAt).toEqual(now + 5000)
   })
 
   test('inactiveAt never expires if 0', () => {
     const session = new SessionEntity({ agentIdentifier, key, inactiveMs: 0 })
-    expect(session.inactiveAt).toEqual(Infinity)
+    expect(session.state.inactiveAt).toEqual(Infinity)
   })
 
   test('should handle isNew', () => {
     const newSession = new SessionEntity({ agentIdentifier, key, expiresMs: 10 })
     expect(newSession.isNew).toBeTruthy()
 
-    const storageAPI = new LocalMemory({ [`${PREFIX}_${key}`]: { value, expiresAt: Infinity, inactiveAt: Infinity } })
+    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 })
     expect(existingSession.isNew).toBeFalsy()
   })
@@ -125,11 +128,12 @@ describe('constructor', () => {
     // missing required fields
     const storageAPI = new LocalMemory({ [`${PREFIX}_${key}`]: { invalid_fields: true } })
     const session = new SessionEntity({ agentIdentifier, key, storageAPI })
-    expect(session).toEqual(expect.objectContaining({
+    expect(session.state).toEqual(expect.objectContaining({
       value: expect.any(String),
       expiresAt: expect.any(Number),
       inactiveAt: expect.any(Number),
-      sessionReplayActive: expect.any(Boolean),
+      updatedAt: expect.any(Number),
+      sessionReplay: expect.any(Number),
       sessionTraceActive: expect.any(Boolean)
     }))
   })
@@ -139,11 +143,12 @@ describe('constructor', () => {
     jest.setSystemTime(now)
     const storageAPI = new LocalMemory({ [`${PREFIX}_${key}`]: { value, expiresAt: now - 100, inactiveAt: Infinity } })
     const session = new SessionEntity({ agentIdentifier, key, storageAPI })
-    expect(session).toEqual(expect.objectContaining({
+    expect(session.state).toEqual(expect.objectContaining({
       value: expect.any(String),
       expiresAt: expect.any(Number),
       inactiveAt: expect.any(Number),
-      sessionReplayActive: expect.any(Boolean),
+      updatedAt: expect.any(Number),
+      sessionReplay: expect.any(Number),
       sessionTraceActive: expect.any(Boolean)
     }))
   })
@@ -153,11 +158,12 @@ describe('constructor', () => {
     jest.setSystemTime(now)
     const storageAPI = new LocalMemory({ [`${PREFIX}_${key}`]: { value, inactiveAt: now - 100, expiresAt: Infinity } })
     const session = new SessionEntity({ agentIdentifier, key, storageAPI })
-    expect(session).toEqual(expect.objectContaining({
+    expect(session.state).toEqual(expect.objectContaining({
       value: expect.any(String),
       expiresAt: expect.any(Number),
       inactiveAt: expect.any(Number),
-      sessionReplayActive: expect.any(Boolean),
+      updatedAt: expect.any(Number),
+      sessionReplay: expect.any(Number),
       sessionTraceActive: expect.any(Boolean)
     }))
   })
@@ -169,10 +175,10 @@ describe('reset()', () => {
     jest.setSystemTime(now)
     const session = new SessionEntity({ agentIdentifier, key, expiresMs: 10 })
     const sessionVal = session.value
-    expect(session.value).toBeTruthy()
+    expect(session.state.value).toBeTruthy()
     session.reset()
-    expect(session.value).toBeTruthy()
-    expect(session.value).not.toEqual(sessionVal)
+    expect(session.state.value).toBeTruthy()
+    expect(session.state.value).not.toEqual(sessionVal)
   })
 
   test('custom data should be wiped on reset', () => {
@@ -180,12 +186,12 @@ describe('reset()', () => {
     jest.setSystemTime(now)
     const session = new SessionEntity({ agentIdentifier, key, expiresMs: 10 })
     session.syncCustomAttribute('test', 123)
-    expect(session.custom.test).toEqual(123)
+    expect(session.state.custom.test).toEqual(123)
     expect(session.read().custom.test).toEqual(123)
 
     // simulate a timer expiring
     session.reset()
-    expect(session.custom?.test).toEqual(undefined)
+    expect(session.state.custom?.test).toEqual(undefined)
     expect(session.read()?.custom?.test).toEqual(undefined)
   })
 })
@@ -199,13 +205,13 @@ describe('read()', () => {
       value: expect.any(String),
       expiresAt: expect.any(Number),
       inactiveAt: expect.any(Number),
-      sessionReplayActive: expect.any(Boolean),
+      sessionReplay: expect.any(Number),
       sessionTraceActive: expect.any(Boolean)
     }))
   })
 
   test('"pre-existing" sessions get data from read()', () => {
-    const storageAPI = new LocalMemory({ [`${PREFIX}_${key}`]: { value, expiresAt: Infinity, inactiveAt: Infinity } })
+    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 })
     expect(session.isNew).toBeFalsy()
     expect(session.read()).toEqual(expect.objectContaining({
@@ -219,20 +225,20 @@ describe('read()', () => {
 describe('write()', () => {
   test('write() sets data to top-level wrapper', () => {
     const session = new SessionEntity({ agentIdentifier, key })
-    expect(session.value).not.toEqual(value)
-    expect(session.expiresAt).not.toEqual(Infinity)
-    expect(session.inactiveAt).not.toEqual(Infinity)
-    session.write({ value, expiresAt: Infinity, inactiveAt: Infinity })
-    expect(session.value).toEqual(value)
-    expect(session.expiresAt).toEqual(Infinity)
-    expect(session.inactiveAt).toEqual(Infinity)
+    expect(session.state.value).not.toEqual(value)
+    expect(session.state.expiresAt).not.toEqual(Infinity)
+    expect(session.state.inactiveAt).not.toEqual(Infinity)
+    session.write({ ...session.state, value, expiresAt: Infinity, inactiveAt: Infinity })
+    expect(session.state.value).toEqual(value)
+    expect(session.state.expiresAt).toEqual(Infinity)
+    expect(session.state.inactiveAt).toEqual(Infinity)
   })
 
   test('write() sets data that read() can access', () => {
     const now = Date.now()
     jest.setSystemTime(now)
     const session = new SessionEntity({ agentIdentifier, key })
-    session.write({ value, expiresAt: now + 100, inactiveAt: now + 100 })
+    session.write({ ...session.state, value, expiresAt: now + 100, inactiveAt: now + 100 })
     const read = session.read()
     expect(read.value).toEqual(value)
     expect(read.expiresAt).toEqual(now + 100)
@@ -259,30 +265,30 @@ describe('refresh()', () => {
     const now = Date.now()
     jest.setSystemTime(now)
     const session = new SessionEntity({ agentIdentifier, key, inactiveMs: 100 })
-    expect(session.inactiveAt).toEqual(now + 100)
+    expect(session.state.inactiveAt).toEqual(now + 100)
     jest.setSystemTime(now + 1000)
     session.refresh()
-    expect(session.inactiveAt).toEqual(now + 100 + 1000)
+    expect(session.state.inactiveAt).toEqual(now + 100 + 1000)
   })
 
   test('refresh resets the entity if expiresTimer is invalid', () => {
     const now = Date.now()
     jest.setSystemTime(now)
     const session = new SessionEntity({ agentIdentifier, key, value })
-    expect(session.value).toEqual(value)
-    session.write({ ...session.read(), expiresAt: now - 1 })
+    expect(session.state.value).toEqual(value)
+    session.write({ ...session.state, expiresAt: now - 1 })
     session.refresh()
-    expect(session.value).not.toEqual(value)
+    expect(session.state.value).not.toEqual(value)
   })
 
   test('refresh resets the entity if inactiveTimer is invalid', () => {
     const now = Date.now()
     jest.setSystemTime(now)
     const session = new SessionEntity({ agentIdentifier, key, value })
-    expect(session.value).toEqual(value)
-    session.write({ ...session.read(), inactiveAt: now - 1 })
+    expect(session.state.value).toEqual(value)
+    session.write({ ...session.state, inactiveAt: now - 1 })
     session.refresh()
-    expect(session.value).not.toEqual(value)
+    expect(session.state.value).not.toEqual(value)
   })
 })
 
@@ -292,20 +298,20 @@ describe('syncCustomAttribute()', () => {
 
     // if custom has never been set, and a "delete" action is triggered, do nothing
     session.syncCustomAttribute('test', null)
-    expect(session?.custom?.test).toEqual(undefined)
+    expect(session?.state?.custom?.test).toEqual(undefined)
 
     session.syncCustomAttribute('test', 1)
-    expect(session?.custom?.test).toEqual(1)
+    expect(session?.state?.custom?.test).toEqual(1)
 
     session.syncCustomAttribute('test', 'string')
-    expect(session?.custom?.test).toEqual('string')
+    expect(session?.state?.custom?.test).toEqual('string')
 
     session.syncCustomAttribute('test', false)
-    expect(session?.custom?.test).toEqual(false)
+    expect(session?.state?.custom?.test).toEqual(false)
 
     // null specifically deletes the object completely
     session.syncCustomAttribute('test', null)
-    expect(session?.custom?.test).toEqual(undefined)
+    expect(session?.state?.custom?.test).toEqual(undefined)
   })
 
   test('Only runs in browser scope', () => {